Lingara-Entwicklerdokumentation

Diese Seite ist aus dem Englischen übersetzt. Wenn die beiden voneinander abweichen, ist die englische Seite maßgeblich. Englische Seite lesen

Eine Verbindung besteht aus Schritten, und jeder Schritt kann ein Skript tragen. Das Skript eines Schritts ist der Rumpf einer Funktion. Es erhält zwei Werte: lingara, die API auf dieser Seite, und input, die eigenen Felder des Schritts zusammen mit seinem Client und den Schritten, die vor ihm verknüpft sind. Der Typ von input hängt von der Art des Schritts ab, sodass das Skript eines Webhook-Schritts die Felder eines Webhook-Schritts liest. Das Skript gibt genau ein Objekt zurück, das von einer der Hilfsfunktionen unten erstellt wird.

Ein Skript sieht nie ein Secret. Wo ein Schritt seinen Client braucht, bekommt er ein Handle, etwa input.client, und die Hilfsfunktion hält dieses Handle fest. Lingara setzt die echten Werte ein, wenn Sie die Verbindung übernehmen.

Was ein Skript nicht tun darf

Ein Skript läuft in Ihrem eigenen Browser, in einem Worker ohne Netzwerk und ohne Speicher. Es unterliegt diesen Grenzen:

Es ist innerhalb von 1 Sekunde fertig.
Eine Zeichenkette, die es zurückgibt, ist höchstens 2048 Zeichen lang.
Eine Liste, die es zurückgibt, hat höchstens 64 Einträge.
Sein gesamtes Ergebnis ist höchstens 16 KiB groß.

Ein Skript, das eine Grenze überschreitet, eine Ausnahme wirft oder etwas anderes als das Ergebnis einer Hilfsfunktion zurückgibt, lässt seinen Schritt fehlschlagen, und „Prüfen“ zeigt, welcher Schritt und warum.

Das Versionsversprechen

Alles auf dieser Seite ist lingara.v1. Innerhalb von v1 wächst die API nur: Eine neue Hilfsfunktion, eine neue optionale Option oder eine neue Schrittart kann hinzukommen, aber nichts, was Sie heute verwenden können, wird entfernt, umbenannt oder eingeschränkt. Eine Änderung, die ein Skript brechen würde, wird eine neue Version neben dieser, und v1 bleibt, wie es ist.

Die Deklarationen

Jede Deklaration unten wird aus derselben Datei erzeugt, gegen die der Skripteditor vervollständigt.

`NodeHandle`

Die ID eines anderen Schritts, etwa "n1". Ein abhängiger Schritt benennt seinen Client per Handle.

export type NodeHandle = string;

`Scope`

Eine Berechtigung, die ein API-Client haben kann. Der Server entscheidet, welche Ihr Konto verwenden darf.

export type Scope = 'vocab:generate' | 'lesson_plans:read' | 'lesson_plans:write' | 'tutor:converse' | 'usage:read' | 'events:read' | 'events:write' | 'embed:mint' | 'embed:play';

`AppSlot`

Ein Platz in der Lingara-App, an dem die Karte einer App erscheinen kann.

export type AppSlot = 'plans.empty_detail' | 'home.side';

`ContextSlice`

Ein Teil des Kontexts des Lernenden, den eine App anfordern kann.

export type ContextSlice = 'languages' | 'plan_summary' | 'review_due' | 'tutor_topic';

`ClientOptions`

Optionen für lingara.client.

export interface ClientOptions {
    name: string;
    scopes: readonly Scope[];
    redirectUris?: readonly string[];
}

name (string) — Der Name des Clients, wie die Entwicklertools ihn anzeigen.
scopes (readonly Scope[]) — Die Berechtigungen, die der Client anfordert.
redirectUris? (readonly string[]) — Wohin der Autorisierungscode-Ablauf einen Lernenden zurückschicken darf. Bei einem Server-zu-Server-Client weglassen.

`WebhookOptions`

Optionen für lingara.webhook.

export interface WebhookOptions {
    client: NodeHandle;
    url: string;
    events: readonly string[];
}

client (NodeHandle) — Der Client-Schritt, zu dem dieser Webhook gehört: input.client.
url (string) — Die HTTPS-Adresse, an die Lingara Ereignisse zustellt.
events (readonly string[]) — Die zuzustellenden Ereignistypen, etwa "lesson_plan.ready".

`ManifestOptions`

Optionen für lingara.manifest, in camelCase; die Hilfsfunktion schreibt die Übertragungsform des Manifests.

export interface ManifestOptions {
    name: string | Readonly<Record<string, string>>;
    description: string | Readonly<Record<string, string>>;
    renderUrl: string;
    slots: readonly AppSlot[];
    context?: readonly ContextSlice[];
    scopes?: readonly Scope[];
    tutorNote?: boolean;
    defaultLocale?: string;
}

name (string | Readonly<Record<string, string>>) — Der Name der App: eine Zeichenkette oder eine Zeichenkette pro Sprachcode.
description (string | Readonly<Record<string, string>>) — Ein Satz über die App: eine Zeichenkette oder eine Zeichenkette pro Sprachcode.
renderUrl (string) — Die HTTPS-Adresse, bei der Lingara die Karte der App anfragt.
slots (readonly AppSlot[]) — Wo die Karte der App erscheinen darf.
context? (readonly ContextSlice[]) — Die Kontextausschnitte, die die App erhält. Standardmäßig keine.
scopes? (readonly Scope[]) — Die Berechtigungen, die die App beim Lernenden anfragt. Standardmäßig keine.
tutorNote? (boolean) — Ob die App dem Tutor eine Notiz hinterlassen darf. Standardmäßig false.
defaultLocale? (string) — Die Sprache, unter der ein Name oder eine Beschreibung als einfache Zeichenkette gespeichert wird. Standardmäßig "en".

`AppOptions`

Optionen für lingara.app.

export interface AppOptions {
    client: NodeHandle;
    manifest: Manifest;
}

client (NodeHandle) — Der Client-Schritt, zu dem diese App gehört: input.client.
manifest (Manifest) — Das Manifest der App, erstellt mit lingara.manifest.

`ClientSpec`

Was ein Client-Schritt erstellt: einen API-Client.

export interface ClientSpec {
    readonly kind: 'client';
    readonly name: string;
    readonly scopes: readonly Scope[];
    readonly redirectUris?: readonly string[];
}

kind ('client') — Immer "client".
name (string) — Der Name des Clients.
scopes (readonly Scope[]) — Die Berechtigungen, die der Client anfordert.
redirectUris? (readonly string[]) — Die Weiterleitungs-URIs des Clients, falls er welche hat.

`SecretSpec`

Was ein Secret-Schritt erstellt: ein neues Secret für seinen Client.

export interface SecretSpec {
    readonly kind: 'secret';
    readonly client: NodeHandle;
}

kind ('secret') — Immer "secret".
client (NodeHandle) — Der Client-Schritt, zu dem das Secret gehört.

`WebhookSpec`

Was ein Webhook-Schritt erstellt: einen Webhook-Endpunkt.

export interface WebhookSpec {
    readonly kind: 'webhook';
    readonly client: NodeHandle;
    readonly url: string;
    readonly events: readonly string[];
}

kind ('webhook') — Immer "webhook".
client (NodeHandle) — Der Client-Schritt, zu dem der Webhook gehört.
url (string) — Die Adresse, an die Ereignisse zugestellt werden.
events (readonly string[]) — Die zugestellten Ereignistypen.

`AppSpec`

Was ein App-Schritt erstellt: eine App, die eine Karte in Lingara rendert.

export interface AppSpec {
    readonly kind: 'app';
    readonly client: NodeHandle;
    readonly manifest: Manifest;
}

kind ('app') — Immer "app".
client (NodeHandle) — Der Client-Schritt, zu dem die App gehört.
manifest (Manifest) — Das Manifest der App.

`Manifest`

Ein App-Manifest in seiner Übertragungsform, wie der Server es speichert.

export interface Manifest {
    readonly manifest_version: 1;
    readonly default_locale: string;
    readonly name: Readonly<Record<string, string>>;
    readonly description: Readonly<Record<string, string>>;
    readonly render_url: string;
    readonly slots: readonly AppSlot[];
    readonly context: readonly ContextSlice[];
    readonly scopes: readonly Scope[];
    readonly tutor_note: boolean;
}

manifest_version (1) — Immer 1.
default_locale (string) — Die Sprache, die angezeigt wird, wenn es für die Sprache des Lernenden keinen Eintrag gibt.
name (Readonly<Record<string, string>>) — Der Name der App, pro Sprachcode.
description (Readonly<Record<string, string>>) — Ein Satz über die App, pro Sprachcode.
render_url (string) — Die HTTPS-Adresse, bei der Lingara die Karte der App anfragt.
slots (readonly AppSlot[]) — Wo die Karte der App erscheinen darf.
context (readonly ContextSlice[]) — Die Kontextausschnitte, die die App erhält.
scopes (readonly Scope[]) — Die Berechtigungen, die die App beim Lernenden anfragt.
tutor_note (boolean) — Ob die App dem Tutor eine Notiz hinterlassen darf.

`Spec`

Jede Spezifikation, die eine Hilfsfunktion zurückgibt. Ein Skript gibt genau eine zurück.

export type Spec = ClientSpec | SecretSpec | WebhookSpec | AppSpec;

`Upstream`

Die Ausgabe jedes direkt vorgelagerten Schritts, nach Handle.

export type Upstream = Readonly<Record<NodeHandle, Spec & {
    readonly handle: NodeHandle;
}>>;

`ClientInput`

Die Eingabe eines Client-Schritts: seine Felder, die die Optionen von lingara.client sind.

export interface ClientInput {
    readonly name: string;
    readonly scopes: readonly Scope[];
    readonly redirectUris?: readonly string[];
    readonly upstream: Upstream;
}

name (string) — Der Name des Clients.
scopes (readonly Scope[]) — Die Berechtigungen, die der Client anfordert.
redirectUris? (readonly string[]) — Die Weiterleitungs-URIs des Clients, falls der Schritt welche hat.
upstream (Upstream) — Die Ausgabe jedes direkt vorgelagerten Schritts.

`SecretInput`

Die Eingabe eines Secret-Schritts. client ist der eine Client-Schritt, der mit diesem verknüpft ist.

export interface SecretInput {
    readonly client: NodeHandle;
    readonly upstream: Upstream;
}

client (NodeHandle) — Der mit diesem verknüpfte Client-Schritt.
upstream (Upstream) — Die Ausgabe jedes direkt vorgelagerten Schritts.

`WebhookInput`

Die Eingabe eines Webhook-Schritts: seine Felder plus der verknüpfte Client.

export interface WebhookInput {
    readonly client: NodeHandle;
    readonly url: string;
    readonly events: readonly string[];
    readonly upstream: Upstream;
}

client (NodeHandle) — Der mit diesem verknüpfte Client-Schritt.
url (string) — Die Adresse, die die Felder des Schritts nennen.
events (readonly string[]) — Die Ereignistypen, die die Felder des Schritts nennen.
upstream (Upstream) — Die Ausgabe jedes direkt vorgelagerten Schritts.

`AppInput`

Die Eingabe eines App-Schritts: seine Manifestfelder plus der verknüpfte Client.

export interface AppInput {
    readonly client: NodeHandle;
    readonly manifest: ManifestOptions;
    readonly upstream: Upstream;
}

client (NodeHandle) — Der mit diesem verknüpfte Client-Schritt.
manifest (ManifestOptions) — Das Manifest, das die Felder des Schritts beschreiben.
upstream (Upstream) — Die Ausgabe jedes direkt vorgelagerten Schritts.

`InputFor`

Die Eingabe, die ein Skript der angegebenen Schrittart erhält.

export type InputFor<K extends Spec['kind']> = K extends 'client' ? ClientInput : K extends 'secret' ? SecretInput : K extends 'webhook' ? WebhookInput : AppInput;

`LingaraV1`

Die Hilfsfunktionen, die ein Skript aufruft. Jede gibt eine eingefrorene Spezifikation zurück, und eine Option mit falschem Typ wirft einen TypeError, der sie benennt.

export interface LingaraV1 {
    readonly version: 'v1';
    client(options: ClientOptions): ClientSpec;
    secret(client: NodeHandle): SecretSpec;
    webhook(options: WebhookOptions): WebhookSpec;
    app(options: AppOptions): AppSpec;
    manifest(options: ManifestOptions): Manifest;
}

version ('v1') — Immer "v1".
client(options: ClientOptions): ClientSpec — Ein API-Client.
secret(client: NodeHandle): SecretSpec — Ein neues Secret für einen Client-Schritt.
webhook(options: WebhookOptions): WebhookSpec — Ein Webhook-Endpunkt an einem Client-Schritt.
app(options: AppOptions): AppSpec — Eine App an einem Client-Schritt.
manifest(options: ManifestOptions): Manifest — Ein Manifest in seiner Übertragungsform, mit den Optionen ausgefüllt, die v1 optional lässt.

return lingara.client({ name: input.name, scopes: input.scopes })

return lingara.secret(input.client)

return lingara.webhook({ client: input.client, url: input.url, events: input.events })

return lingara.app({ client: input.client, manifest: lingara.manifest(input.manifest) })

`NodeScript`

Das Skript eines Schritts ist der Rumpf dieser Funktion: return lingara.webhook({ client: input.client, url: input.url, events: input.events }).

export type NodeScript<K extends Spec['kind']> = (lingara: LingaraV1, input: InputFor<K>) => Spec;

Siehe auch

Authentifizierung