Lingara-ontwikkelaarsdocumentatie

Deze pagina is vertaald uit het Engels. Als de twee verschillen, is de Engelse pagina juist. Lees de Engelse pagina

Een koppeling bestaat uit stappen, en elke stap kan een script hebben. Het script van een stap is de body van een functie. Het ontvangt twee waarden: lingara, de API op deze pagina, en input, de eigen velden van de stap samen met zijn client en de stappen die ervoor zijn gekoppeld. Het type van input hangt af van het soort stap, dus het script van een webhookstap leest de velden van een webhookstap. Het script geeft precies één object terug, gebouwd door een van de helpers hieronder.

Een script ziet nooit een geheim. Waar een stap zijn client nodig heeft, krijgt hij een handle, zoals input.client, en de helper legt die handle vast. Lingara vult de echte waarden in wanneer je de koppeling toepast.

Wat een script niet mag doen

Een script draait in je eigen browser, in een worker zonder netwerk en zonder opslag. Het moet binnen deze limieten blijven:

Het is binnen 1 seconde klaar.
Een string die het teruggeeft, is hooguit 2048 tekens lang.
Een lijst die het teruggeeft, heeft hooguit 64 items.
Het hele resultaat is hooguit 16 KiB.

Een script dat een limiet overschrijdt, een fout gooit of iets anders teruggeeft dan het resultaat van één helper, laat zijn stap mislukken, en “Controleren” toont welke stap en waarom.

De versiebelofte

Alles op deze pagina is lingara.v1. Binnen v1 groeit de API alleen: er kan een nieuwe helper, een nieuwe optionele optie of een nieuw soort stap bijkomen, maar niets wat je vandaag kunt gebruiken wordt verwijderd, hernoemd of beperkt. Een wijziging die een script zou breken, wordt een nieuwe versie naast deze, en v1 blijft zoals hij is.

De declaraties

Elke declaratie hieronder wordt gegenereerd uit hetzelfde bestand waartegen de scripteditor aanvult.

`NodeHandle`

De id van een andere stap, zoals "n1". Een afhankelijke stap noemt zijn client bij zijn handle.

export type NodeHandle = string;

`Scope`

Een recht dat een API-client kan hebben. De server beoordeelt welke je account mag gebruiken.

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

`AppSlot`

Een plek in de Lingara-app waar de kaart van een app kan verschijnen.

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

`ContextSlice`

Een deel van de context van de leerder dat een app kan vragen te ontvangen.

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

`ClientOptions`

Opties voor lingara.client.

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

name (string) — De naam van de client, zoals Ontwikkelaarstools die toont.
scopes (readonly Scope[]) — De rechten die de client vraagt.
redirectUris? (readonly string[]) — Waarheen de authorization-code-flow een leerder mag terugsturen. Laat weg voor een server-naar-serverclient.

`WebhookOptions`

Opties voor lingara.webhook.

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

client (NodeHandle) — De clientstap waar deze webhook bij hoort: input.client.
url (string) — Het HTTPS-adres waar Lingara events naartoe stuurt.
events (readonly string[]) — De eventtypen die worden afgeleverd, zoals "lesson_plan.ready".

`ManifestOptions`

Opties voor lingara.manifest, in camelCase; de helper schrijft de wire-vorm van het manifest.

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>>) — De naam van de app: één string, of één string per localecode.
description (string | Readonly<Record<string, string>>) — Eén zin over de app: één string, of één string per localecode.
renderUrl (string) — Het HTTPS-adres waar Lingara de kaart van de app opvraagt.
slots (readonly AppSlot[]) — Waar de kaart van de app mag verschijnen.
context? (readonly ContextSlice[]) — De contextdelen die de app ontvangt. Standaard geen.
scopes? (readonly Scope[]) — De rechten die de app de leerder vraagt. Standaard geen.
tutorNote? (boolean) — Of de app een notitie voor de tutor mag achterlaten. Standaard false.
defaultLocale? (string) — De locale waaronder een naam of beschrijving als gewone string wordt opgeslagen. Standaard "en".

`AppOptions`

Opties voor lingara.app.

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

client (NodeHandle) — De clientstap waar deze app bij hoort: input.client.
manifest (Manifest) — Het manifest van de app, gebouwd met lingara.manifest.

`ClientSpec`

Wat een clientstap maakt: een API-client.

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

kind ('client') — Altijd "client".
name (string) — De naam van de client.
scopes (readonly Scope[]) — De rechten die de client vraagt.
redirectUris? (readonly string[]) — De redirect-URI’s van de client, als hij die heeft.

`SecretSpec`

Wat een geheimstap maakt: een nieuw geheim voor zijn client.

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

kind ('secret') — Altijd "secret".
client (NodeHandle) — De clientstap waar het geheim bij hoort.

`WebhookSpec`

Wat een webhookstap maakt: een webhook-endpoint.

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

kind ('webhook') — Altijd "webhook".
client (NodeHandle) — De clientstap waar de webhook bij hoort.
url (string) — Het adres waar events naartoe worden gestuurd.
events (readonly string[]) — De eventtypen die worden afgeleverd.

`AppSpec`

Wat een appstap maakt: een app die een kaart in Lingara toont.

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

kind ('app') — Altijd "app".
client (NodeHandle) — De clientstap waar de app bij hoort.
manifest (Manifest) — Het manifest van de app.

`Manifest`

Een app-manifest in zijn wire-vorm, zoals de server het opslaat.

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) — Altijd 1.
default_locale (string) — De locale die wordt getoond wanneer die van de leerder zelf geen vermelding heeft.
name (Readonly<Record<string, string>>) — De naam van de app, per localecode.
description (Readonly<Record<string, string>>) — Eén zin over de app, per localecode.
render_url (string) — Het HTTPS-adres waar Lingara de kaart van de app opvraagt.
slots (readonly AppSlot[]) — Waar de kaart van de app mag verschijnen.
context (readonly ContextSlice[]) — De contextdelen die de app ontvangt.
scopes (readonly Scope[]) — De rechten die de app de leerder vraagt.
tutor_note (boolean) — Of de app een notitie voor de tutor mag achterlaten.

`Spec`

Elke spec die een helper teruggeeft. Een script geeft er precies één terug.

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

`Upstream`

De uitvoer van elke directe voorgaande stap, per handle.

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

`ClientInput`

De invoer van een clientstap: zijn velden, die de opties van lingara.client zijn.

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

name (string) — De naam van de client.
scopes (readonly Scope[]) — De rechten die de client vraagt.
redirectUris? (readonly string[]) — De redirect-URI’s van de client, als de stap die heeft.
upstream (Upstream) — De uitvoer van elke directe voorgaande stap.

`SecretInput`

De invoer van een geheimstap. client is de ene clientstap die aan deze stap is gekoppeld.

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

client (NodeHandle) — De clientstap die aan deze stap is gekoppeld.
upstream (Upstream) — De uitvoer van elke directe voorgaande stap.

`WebhookInput`

De invoer van een webhookstap: zijn velden, plus de gekoppelde client.

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

client (NodeHandle) — De clientstap die aan deze stap is gekoppeld.
url (string) — Het adres dat de velden van de stap noemen.
events (readonly string[]) — De eventtypen die de velden van de stap noemen.
upstream (Upstream) — De uitvoer van elke directe voorgaande stap.

`AppInput`

De invoer van een appstap: zijn manifestvelden, plus de gekoppelde client.

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

client (NodeHandle) — De clientstap die aan deze stap is gekoppeld.
manifest (ManifestOptions) — Het manifest dat de velden van de stap beschrijven.
upstream (Upstream) — De uitvoer van elke directe voorgaande stap.

`InputFor`

De invoer die een script van het gegeven soort stap ontvangt.

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

`LingaraV1`

De helpers die een script aanroept. Elk geeft een bevroren spec terug, en een optie van het verkeerde type gooit een TypeError die haar noemt.

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') — Altijd "v1".
client(options: ClientOptions): ClientSpec — Een API-client.
secret(client: NodeHandle): SecretSpec — Een nieuw geheim voor een clientstap.
webhook(options: WebhookOptions): WebhookSpec — Een webhook-endpoint op een clientstap.
app(options: AppOptions): AppSpec — Een app op een clientstap.
manifest(options: ManifestOptions): Manifest — Een manifest in zijn wire-vorm, met de opties die v1 optioneel laat ingevuld.

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`

Het script van een stap is de body van deze functie: 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;

Zie ook

Authenticatie