Documentazione per sviluppatori di Lingara

Questa pagina è tradotta dall'inglese. Se le due versioni differiscono, fa fede la pagina in inglese. Leggi la pagina in inglese

Una connessione è composta da passaggi, e ogni passaggio può avere uno script. Lo script di un passaggio è il corpo di una funzione. Riceve due valori: lingara, l’API descritta in questa pagina, e input, i campi propri del passaggio insieme al suo client e ai passaggi collegati prima di esso. Il tipo di input dipende dal tipo di passaggio, quindi lo script di un passaggio webhook legge i campi di un passaggio webhook. Lo script restituisce esattamente un oggetto, costruito da una delle funzioni di supporto qui sotto.

Uno script non vede mai un segreto. Quando un passaggio ha bisogno del suo client, riceve un riferimento, come input.client, e la funzione di supporto registra quel riferimento. Lingara inserisce i valori reali quando applichi la connessione.

Cosa uno script non deve fare

Uno script viene eseguito nel tuo browser, in un worker senza rete e senza archiviazione. È soggetto a questi limiti:

Termina entro 1 secondo.
Una stringa che restituisce è lunga al massimo 2048 caratteri.
Un elenco che restituisce ha al massimo 64 elementi.
Il suo risultato complessivo è al massimo di 16 KiB.

Uno script che supera un limite, genera un’eccezione o restituisce qualcosa di diverso dal risultato di una funzione di supporto fa fallire il suo passaggio, e «Controlla» mostra quale passaggio e perché.

La promessa di versione

Tutto ciò che si trova in questa pagina è lingara.v1. All’interno di v1 l’API cresce soltanto: possono comparire una nuova funzione di supporto, una nuova opzione facoltativa o un nuovo tipo di passaggio, ma niente di ciò che puoi usare oggi viene rimosso, rinominato o ristretto. Una modifica che romperebbe uno script diventa una nuova versione accanto a questa, e v1 resta com’è.

Le dichiarazioni

Ogni dichiarazione qui sotto è generata dallo stesso file su cui si basa il completamento dell’editor di script.

`NodeHandle`

L’id di un altro passaggio, come "n1". Un passaggio dipendente indica il suo client tramite riferimento.

export type NodeHandle = string;

`Scope`

Un’autorizzazione che un client API può avere. Il server decide quali può usare il tuo account.

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 punto dell’app Lingara in cui può comparire la scheda di un’app.

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

`ContextSlice`

Una parte del contesto dello studente che un’app può chiedere di ricevere.

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

`ClientOptions`

Opzioni per lingara.client.

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

name (string) — Il nome del client, come lo mostrano gli Strumenti per sviluppatori.
scopes (readonly Scope[]) — Le autorizzazioni che il client richiede.
redirectUris? (readonly string[]) — Dove il flusso con codice di autorizzazione può rimandare uno studente. Omettilo per un client da server a server.

`WebhookOptions`

Opzioni per lingara.webhook.

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

client (NodeHandle) — Il passaggio client a cui appartiene questo webhook: input.client.
url (string) — L’indirizzo HTTPS a cui Lingara consegna gli eventi.
events (readonly string[]) — I tipi di evento da consegnare, come "lesson_plan.ready".

`ManifestOptions`

Opzioni per lingara.manifest, in camelCase; la funzione di supporto scrive la forma di trasmissione del 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>>) — Il nome dell’app: una stringa, oppure una stringa per codice di lingua.
description (string | Readonly<Record<string, string>>) — Una frase sull’app: una stringa, oppure una stringa per codice di lingua.
renderUrl (string) — L’indirizzo HTTPS a cui Lingara chiede la scheda dell’app.
slots (readonly AppSlot[]) — Dove può comparire la scheda dell’app.
context? (readonly ContextSlice[]) — Le parti di contesto che l’app riceve. Per impostazione predefinita, nessuna.
scopes? (readonly Scope[]) — Le autorizzazioni che l’app chiede allo studente. Per impostazione predefinita, nessuna.
tutorNote? (boolean) — Se l’app può lasciare una nota per il tutor. Per impostazione predefinita, false.
defaultLocale? (string) — La lingua con cui viene memorizzato un nome o una descrizione in forma di stringa semplice. Per impostazione predefinita, "en".

`AppOptions`

Opzioni per lingara.app.

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

client (NodeHandle) — Il passaggio client a cui appartiene questa app: input.client.
manifest (Manifest) — Il manifest dell’app, costruito con lingara.manifest.

`ClientSpec`

Cosa crea un passaggio client: un client API.

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

kind ('client') — Sempre "client".
name (string) — Il nome del client.
scopes (readonly Scope[]) — Le autorizzazioni che il client richiede.
redirectUris? (readonly string[]) — Gli URI di reindirizzamento del client, se ne ha.

`SecretSpec`

Cosa crea un passaggio segreto: un nuovo segreto per il suo client.

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

kind ('secret') — Sempre "secret".
client (NodeHandle) — Il passaggio client a cui appartiene il segreto.

`WebhookSpec`

Cosa crea un passaggio webhook: un endpoint webhook.

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

kind ('webhook') — Sempre "webhook".
client (NodeHandle) — Il passaggio client a cui appartiene il webhook.
url (string) — L’indirizzo a cui vengono consegnati gli eventi.
events (readonly string[]) — I tipi di evento consegnati.

`AppSpec`

Cosa crea un passaggio app: un’app che disegna una scheda dentro Lingara.

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

kind ('app') — Sempre "app".
client (NodeHandle) — Il passaggio client a cui appartiene l’app.
manifest (Manifest) — Il manifest dell’app.

`Manifest`

Un manifest dell’app nella sua forma di trasmissione, così come lo memorizza il server.

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) — Sempre 1.
default_locale (string) — La lingua mostrata quando quella dello studente non ha una voce.
name (Readonly<Record<string, string>>) — Il nome dell’app, per codice di lingua.
description (Readonly<Record<string, string>>) — Una frase sull’app, per codice di lingua.
render_url (string) — L’indirizzo HTTPS a cui Lingara chiede la scheda dell’app.
slots (readonly AppSlot[]) — Dove può comparire la scheda dell’app.
context (readonly ContextSlice[]) — Le parti di contesto che l’app riceve.
scopes (readonly Scope[]) — Le autorizzazioni che l’app chiede allo studente.
tutor_note (boolean) — Se l’app può lasciare una nota per il tutor.

`Spec`

Qualsiasi specifica restituita da una funzione di supporto. Uno script ne restituisce esattamente una.

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

`Upstream`

L’output di ogni passaggio direttamente a monte, per riferimento.

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

`ClientInput`

L’input di un passaggio client: i suoi campi, che sono le opzioni di lingara.client.

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

name (string) — Il nome del client.
scopes (readonly Scope[]) — Le autorizzazioni che il client richiede.
redirectUris? (readonly string[]) — Gli URI di reindirizzamento del client, se il passaggio ne ha.
upstream (Upstream) — L’output di ogni passaggio direttamente a monte.

`SecretInput`

L’input di un passaggio segreto. client è l’unico passaggio client collegato a questo.

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

client (NodeHandle) — Il passaggio client collegato a questo.
upstream (Upstream) — L’output di ogni passaggio direttamente a monte.

`WebhookInput`

L’input di un passaggio webhook: i suoi campi, più il client collegato.

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

client (NodeHandle) — Il passaggio client collegato a questo.
url (string) — L’indirizzo indicato dai campi del passaggio.
events (readonly string[]) — I tipi di evento indicati dai campi del passaggio.
upstream (Upstream) — L’output di ogni passaggio direttamente a monte.

`AppInput`

L’input di un passaggio app: i campi del suo manifest, più il client collegato.

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

client (NodeHandle) — Il passaggio client collegato a questo.
manifest (ManifestOptions) — Il manifest descritto dai campi del passaggio.
upstream (Upstream) — L’output di ogni passaggio direttamente a monte.

`InputFor`

L’input che riceve uno script del tipo di passaggio indicato.

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

`LingaraV1`

Le funzioni di supporto che uno script chiama. Ognuna restituisce una specifica congelata, e un’opzione del tipo sbagliato genera un TypeError che la nomina.

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') — Sempre "v1".
client(options: ClientOptions): ClientSpec — Un client API.
secret(client: NodeHandle): SecretSpec — Un nuovo segreto per un passaggio client.
webhook(options: WebhookOptions): WebhookSpec — Un endpoint webhook su un passaggio client.
app(options: AppOptions): AppSpec — Un’app su un passaggio client.
manifest(options: ManifestOptions): Manifest — Un manifest nella sua forma di trasmissione, con le opzioni che v1 lascia facoltative già compilate.

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`

Lo script di un passaggio è il corpo di questa funzione: 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;

Vedi anche

Autenticazione