Documentação para programadores do Lingara

Esta página é uma tradução do inglês. Se as duas diferirem, a página em inglês é a correta. Ler a página em inglês

Uma ligação é composta por passos, e qualquer passo pode ter um script. O script de um passo é o corpo de uma função. Recebe dois valores: lingara, a API desta página, e input, os campos do próprio passo juntamente com o seu cliente e os passos ligados antes dele. O tipo de input depende do tipo de passo, por isso o script de um passo de webhook lê os campos de um passo de webhook. O script devolve exatamente um objeto, criado por uma das funções auxiliares abaixo.

Um script nunca vê um segredo. Quando um passo precisa do seu cliente, recebe uma referência, como input.client, e a função auxiliar regista essa referência. O Lingara preenche os valores reais quando aplica a ligação.

O que um script não pode fazer

Um script é executado no seu próprio navegador, num worker sem rede e sem armazenamento. Está sujeito a estes limites:

Termina em 1 segundo, no máximo.
Uma cadeia que devolve tem, no máximo, 2048 caracteres.
Uma lista que devolve tem, no máximo, 64 itens.
O seu resultado completo tem, no máximo, 16 KiB.

Um script que ultrapasse um limite, lance uma exceção ou devolva algo diferente do resultado de uma função auxiliar faz falhar o seu passo, e «Verificar» mostra qual o passo e porquê.

A promessa de versão

Tudo nesta página é lingara.v1. Dentro de v1, a API só cresce: pode surgir uma nova função auxiliar, uma nova opção opcional ou um novo tipo de passo, mas nada do que pode usar hoje é removido, renomeado ou restringido. Uma alteração que quebraria um script passa a ser uma nova versão ao lado desta, e v1 fica como está.

As declarações

Cada declaração abaixo é gerada a partir do mesmo ficheiro que o editor de scripts usa para o preenchimento automático.

`NodeHandle`

O id de outro passo, como "n1". Um passo dependente indica o seu cliente por referência.

export type NodeHandle = string;

`Scope`

Uma permissão que um cliente da API pode ter. O servidor decide quais a sua conta pode usar.

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

`AppSlot`

Um lugar na app Lingara onde o cartão de uma app pode aparecer.

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

`ContextSlice`

Uma parte do contexto do aprendente que uma app pode pedir para receber.

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

`ClientOptions`

Opções para lingara.client.

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

name (string) — O nome do cliente, tal como as Ferramentas de programador o mostram.
scopes (readonly Scope[]) — As permissões que o cliente pede.
redirectUris? (readonly string[]) — Para onde o fluxo de código de autorização pode reencaminhar um aprendente. Omita-o num cliente de servidor para servidor.

`WebhookOptions`

Opções para lingara.webhook.

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

client (NodeHandle) — O passo de cliente a que este webhook pertence: input.client.
url (string) — O endereço HTTPS para onde o Lingara entrega os eventos.
events (readonly string[]) — Os tipos de evento a entregar, como "lesson_plan.ready".

`ManifestOptions`

Opções para lingara.manifest, em camelCase; a função auxiliar escreve a forma de transmissão do manifesto.

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>>) — O nome da app: uma cadeia, ou uma cadeia por código de idioma.
description (string | Readonly<Record<string, string>>) — Uma frase sobre a app: uma cadeia, ou uma cadeia por código de idioma.
renderUrl (string) — O endereço HTTPS a que o Lingara pede o cartão da app.
slots (readonly AppSlot[]) — Onde o cartão da app pode aparecer.
context? (readonly ContextSlice[]) — As partes do contexto que a app recebe. Por omissão, nenhuma.
scopes? (readonly Scope[]) — As permissões que a app pede ao aprendente. Por omissão, nenhuma.
tutorNote? (boolean) — Se a app pode deixar uma nota para o tutor. Por omissão, false.
defaultLocale? (string) — O idioma em que fica guardado um nome ou uma descrição em cadeia simples. Por omissão, "en".

`AppOptions`

Opções para lingara.app.

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

client (NodeHandle) — O passo de cliente a que esta app pertence: input.client.
manifest (Manifest) — O manifesto da app, criado com lingara.manifest.

`ClientSpec`

O que um passo de cliente cria: um cliente da API.

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

kind ('client') — Sempre "client".
name (string) — O nome do cliente.
scopes (readonly Scope[]) — As permissões que o cliente pede.
redirectUris? (readonly string[]) — Os URI de redirecionamento do cliente, quando os tem.

`SecretSpec`

O que um passo de segredo cria: um novo segredo para o seu cliente.

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

kind ('secret') — Sempre "secret".
client (NodeHandle) — O passo de cliente a que o segredo pertence.

`WebhookSpec`

O que um passo de webhook cria: um endpoint de webhook.

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

kind ('webhook') — Sempre "webhook".
client (NodeHandle) — O passo de cliente a que o webhook pertence.
url (string) — O endereço para onde os eventos são entregues.
events (readonly string[]) — Os tipos de evento entregues.

`AppSpec`

O que um passo de app cria: uma app que desenha um cartão dentro do Lingara.

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

kind ('app') — Sempre "app".
client (NodeHandle) — O passo de cliente a que a app pertence.
manifest (Manifest) — O manifesto da app.

`Manifest`

Um manifesto de app na sua forma de transmissão, tal como o servidor o guarda.

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) — O idioma mostrado quando o do aprendente não tem entrada.
name (Readonly<Record<string, string>>) — O nome da app, por código de idioma.
description (Readonly<Record<string, string>>) — Uma frase sobre a app, por código de idioma.
render_url (string) — O endereço HTTPS a que o Lingara pede o cartão da app.
slots (readonly AppSlot[]) — Onde o cartão da app pode aparecer.
context (readonly ContextSlice[]) — As partes do contexto que a app recebe.
scopes (readonly Scope[]) — As permissões que a app pede ao aprendente.
tutor_note (boolean) — Se a app pode deixar uma nota para o tutor.

`Spec`

Qualquer especificação que uma função auxiliar devolve. Um script devolve exatamente uma.

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

`Upstream`

A saída de cada passo diretamente anterior, por referência.

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

`ClientInput`

A entrada de um passo de cliente: os seus campos, que são as opções de lingara.client.

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

name (string) — O nome do cliente.
scopes (readonly Scope[]) — As permissões que o cliente pede.
redirectUris? (readonly string[]) — Os URI de redirecionamento do cliente, quando o passo os tem.
upstream (Upstream) — A saída de cada passo diretamente anterior.

`SecretInput`

A entrada de um passo de segredo. client é o único passo de cliente ligado a este.

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

client (NodeHandle) — O passo de cliente ligado a este.
upstream (Upstream) — A saída de cada passo diretamente anterior.

`WebhookInput`

A entrada de um passo de webhook: os seus campos, mais o cliente ligado.

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

client (NodeHandle) — O passo de cliente ligado a este.
url (string) — O endereço que os campos do passo indicam.
events (readonly string[]) — Os tipos de evento que os campos do passo indicam.
upstream (Upstream) — A saída de cada passo diretamente anterior.

`AppInput`

A entrada de um passo de app: os campos do seu manifesto, mais o cliente ligado.

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

client (NodeHandle) — O passo de cliente ligado a este.
manifest (ManifestOptions) — O manifesto que os campos do passo descrevem.
upstream (Upstream) — A saída de cada passo diretamente anterior.

`InputFor`

A entrada que recebe um script do tipo de passo indicado.

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

`LingaraV1`

As funções auxiliares que um script chama. Cada uma devolve uma especificação congelada, e uma opção com o tipo errado lança um TypeError que a nomeia.

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 — Um cliente da API.
secret(client: NodeHandle): SecretSpec — Um novo segredo para um passo de cliente.
webhook(options: WebhookOptions): WebhookSpec — Um endpoint de webhook num passo de cliente.
app(options: AppOptions): AppSpec — Uma app num passo de cliente.
manifest(options: ManifestOptions): Manifest — Um manifesto na sua forma de transmissão, com as opções que a v1 deixa opcionais já preenchidas.

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`

O script de um passo é o corpo desta função: 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;

Ver também

Autenticação