Documentation développeur de Lingara

Cette page est traduite de l'anglais. En cas de différence, la page anglaise fait foi. Lire la page en anglais

Une connexion se compose d’étapes, et chaque étape peut porter un script. Le script d’une étape est le corps d’une fonction. Il reçoit deux valeurs : lingara, l’API décrite sur cette page, et input, les champs propres à l’étape ainsi que son client et les étapes reliées avant elle. Le type de input dépend du type de l’étape, si bien que le script d’une étape webhook lit les champs d’une étape webhook. Le script renvoie exactement un objet, construit par l’une des fonctions d’aide ci-dessous.

Un script ne voit jamais de secret. Lorsqu’une étape a besoin de son client, elle reçoit une référence, comme input.client, et la fonction d’aide enregistre cette référence. Lingara remplit les vraies valeurs quand vous appliquez la connexion.

Ce qu’un script ne doit pas faire

Un script s’exécute dans votre propre navigateur, dans un worker sans réseau ni stockage. Il est soumis à ces limites :

Il se termine en 1 seconde au plus.
Une chaîne qu’il renvoie fait au plus 2048 caractères.
Une liste qu’il renvoie contient au plus 64 éléments.
Son résultat complet fait au plus 16 KiB.

Un script qui dépasse une limite, lève une exception ou renvoie autre chose que le résultat d’une fonction d’aide fait échouer son étape, et « Vérifier » indique quelle étape et pourquoi.

La promesse de version

Tout ce qui figure sur cette page relève de lingara.v1. Au sein de v1, l’API ne fait que grandir : une nouvelle fonction d’aide, une nouvelle option facultative ou un nouveau type d’étape peuvent apparaître, mais rien de ce que vous pouvez utiliser aujourd’hui n’est supprimé, renommé ou restreint. Un changement qui casserait un script devient une nouvelle version à côté de celle-ci, et v1 reste tel quel.

Les déclarations

Chaque déclaration ci-dessous est générée à partir du même fichier que celui sur lequel s’appuie la complétion de l’éditeur de scripts.

`NodeHandle`

L’identifiant d’une autre étape, comme "n1". Une étape dépendante désigne son client par sa référence.

export type NodeHandle = string;

`Scope`

Une autorisation qu’un client d’API peut détenir. Le serveur juge lesquelles votre compte peut utiliser.

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

`AppSlot`

Un emplacement de l’application Lingara où la carte d’une application peut apparaître.

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

`ContextSlice`

Une partie du contexte de l’apprenant qu’une application peut demander à recevoir.

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

`ClientOptions`

Options pour lingara.client.

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

name (string) — Le nom du client, tel que l’affichent les Outils de développement.
scopes (readonly Scope[]) — Les autorisations que demande le client.
redirectUris? (readonly string[]) — Où le flux par code d’autorisation peut renvoyer un apprenant. À omettre pour un client de serveur à serveur.

`WebhookOptions`

Options pour lingara.webhook.

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

client (NodeHandle) — L’étape client à laquelle appartient ce webhook : input.client.
url (string) — L’adresse HTTPS à laquelle Lingara livre les événements.
events (readonly string[]) — Les types d’événements à livrer, comme "lesson_plan.ready".

`ManifestOptions`

Options pour lingara.manifest, en camelCase ; la fonction d’aide écrit la forme de transmission du manifeste.

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>>) — Le nom de l’application : une chaîne, ou une chaîne par code de langue.
description (string | Readonly<Record<string, string>>) — Une phrase sur l’application : une chaîne, ou une chaîne par code de langue.
renderUrl (string) — L’adresse HTTPS à laquelle Lingara demande la carte de l’application.
slots (readonly AppSlot[]) — Où la carte de l’application peut apparaître.
context? (readonly ContextSlice[]) — Les tranches de contexte que reçoit l’application. Par défaut, aucune.
scopes? (readonly Scope[]) — Les autorisations que l’application demande à l’apprenant. Par défaut, aucune.
tutorNote? (boolean) — Si l’application peut laisser une note au tuteur. Par défaut false.
defaultLocale? (string) — La langue sous laquelle un nom ou une description en simple chaîne est stocké. Par défaut "en".

`AppOptions`

Options pour lingara.app.

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

client (NodeHandle) — L’étape client à laquelle appartient cette application : input.client.
manifest (Manifest) — Le manifeste de l’application, construit avec lingara.manifest.

`ClientSpec`

Ce que crée une étape client : un client d’API.

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

kind ('client') — Toujours "client".
name (string) — Le nom du client.
scopes (readonly Scope[]) — Les autorisations que demande le client.
redirectUris? (readonly string[]) — Les URI de redirection du client, s’il en a.

`SecretSpec`

Ce que crée une étape secret : un nouveau secret pour son client.

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

kind ('secret') — Toujours "secret".
client (NodeHandle) — L’étape client à laquelle appartient le secret.

`WebhookSpec`

Ce que crée une étape webhook : un point de terminaison webhook.

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

kind ('webhook') — Toujours "webhook".
client (NodeHandle) — L’étape client à laquelle appartient le webhook.
url (string) — L’adresse à laquelle les événements sont livrés.
events (readonly string[]) — Les types d’événements livrés.

`AppSpec`

Ce que crée une étape app : une application qui affiche une carte dans Lingara.

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

kind ('app') — Toujours "app".
client (NodeHandle) — L’étape client à laquelle appartient l’application.
manifest (Manifest) — Le manifeste de l’application.

`Manifest`

Un manifeste d’application dans sa forme de transmission, tel que le serveur le stocke.

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) — Toujours 1.
default_locale (string) — La langue affichée quand celle de l’apprenant n’a pas d’entrée.
name (Readonly<Record<string, string>>) — Le nom de l’application, par code de langue.
description (Readonly<Record<string, string>>) — Une phrase sur l’application, par code de langue.
render_url (string) — L’adresse HTTPS à laquelle Lingara demande la carte de l’application.
slots (readonly AppSlot[]) — Où la carte de l’application peut apparaître.
context (readonly ContextSlice[]) — Les tranches de contexte que reçoit l’application.
scopes (readonly Scope[]) — Les autorisations que l’application demande à l’apprenant.
tutor_note (boolean) — Si l’application peut laisser une note au tuteur.

`Spec`

Toute spécification que renvoie une fonction d’aide. Un script en renvoie exactement une.

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

`Upstream`

La sortie de chaque étape directement en amont, par référence.

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

`ClientInput`

L’entrée d’une étape client : ses champs, qui sont les options de lingara.client.

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

name (string) — Le nom du client.
scopes (readonly Scope[]) — Les autorisations que demande le client.
redirectUris? (readonly string[]) — Les URI de redirection du client, si l’étape en a.
upstream (Upstream) — La sortie de chaque étape directement en amont.

`SecretInput`

L’entrée d’une étape secret. client est la seule étape client reliée à celle-ci.

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

client (NodeHandle) — L’étape client reliée à celle-ci.
upstream (Upstream) — La sortie de chaque étape directement en amont.

`WebhookInput`

L’entrée d’une étape webhook : ses champs, plus le client relié.

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

client (NodeHandle) — L’étape client reliée à celle-ci.
url (string) — L’adresse que nomment les champs de l’étape.
events (readonly string[]) — Les types d’événements que nomment les champs de l’étape.
upstream (Upstream) — La sortie de chaque étape directement en amont.

`AppInput`

L’entrée d’une étape app : les champs de son manifeste, plus le client relié.

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

client (NodeHandle) — L’étape client reliée à celle-ci.
manifest (ManifestOptions) — Le manifeste que décrivent les champs de l’étape.
upstream (Upstream) — La sortie de chaque étape directement en amont.

`InputFor`

L’entrée que reçoit un script du type d’étape donné.

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

`LingaraV1`

Les fonctions d’aide qu’appelle un script. Chacune renvoie une spécification figée, et une option du mauvais type lève une TypeError qui la nomme.

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') — Toujours "v1".
client(options: ClientOptions): ClientSpec — Un client d’API.
secret(client: NodeHandle): SecretSpec — Un nouveau secret pour une étape client.
webhook(options: WebhookOptions): WebhookSpec — Un point de terminaison webhook sur une étape client.
app(options: AppOptions): AppSpec — Une application sur une étape client.
manifest(options: ManifestOptions): Manifest — Un manifeste dans sa forme de transmission, avec les options que v1 laisse facultatives remplies.

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`

Le script d’une étape est le corps de cette fonction : 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;

Voir aussi

Authentification