Lingara 開發者文件

這頁係對英文翻譯過來个。若係兩片無共樣，以英文頁為準。看英文頁

一隻連接係步驟組成个，任何步驟都做得帶一隻腳本。步驟个腳本係一隻函式个主體。佢會收到兩隻值：lingara，就係這頁講个 API；還有 input，就係該隻步驟自家个欄位，連佢个用戶端摎在佢以前連接个步驟。input 个型別看步驟个種類來決定，所以 Webhook 步驟个腳本讀个係 Webhook 步驟个欄位。腳本淨轉一隻物件，用下背其中一隻輔助函式建立。

腳本永遠看毋到密鑰。步驟需要佢个用戶端个時節，佢會拿到一隻控制代碼，像 input.client，輔助函式會將這隻控制代碼記起來。你套用連接个時節，Lingara 會填入真正个值。

腳本毋做得做个事情

腳本在你自家个瀏覽器肚項行，在一隻無網路、無儲存空間个 worker 肚項。佢愛守下背个限制：

佢愛在 1 秒肚項做完。
佢轉來个字串最多 2048 隻字元。
佢轉來个清單最多 64 項。
佢歸隻結果最多 16 KiB。

超過限制、擲出例外，抑係轉來个毋係輔助函式結果个腳本，會分佢个步驟失敗，「檢查看啊」會顯示係哪一隻步驟摎原因。

版本个承諾

這頁个一切都屬於 lingara.v1。在 v1 肚項，API 淨會擴充：可能會出現新个輔助函式、新个做得揀个選項，抑係新个步驟種類，毋過你今晡日做得用个東西都毋會分人拿忒、改名抑係縮細。會將腳本打爛个改變會成做摎這隻版本並排个新版本，v1 會維持原樣。

宣告

下背每隻宣告都係從腳本編輯器自動完成所根據个同一隻檔案產生个。

`NodeHandle`

另外一隻步驟个 id，像 "n1"。靠別隻步驟个步驟會用控制代碼指定佢个用戶端。

export type NodeHandle = string;

`Scope`

API 用戶端做得有个一項權限。由伺服器判斷你个帳戶做得用哪兜。

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

`AppSlot`

Lingara App 肚項做得顯示 App 卡片个位所。

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

`ContextSlice`

App 做得要求收到个學習者情境个一部分。

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

`ClientOptions`

lingara.client 个選項。

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

name (string) — 用戶端个名稱，摎開發者工具顯示个共樣。
scopes (readonly Scope[]) — 用戶端要求个權限。
redirectUris? (readonly string[]) — 授權碼流程做得將學習者送轉去个位所。伺服器對伺服器个用戶端做得毋使填。

`WebhookOptions`

lingara.webhook 个選項。

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

client (NodeHandle) — 這隻 Webhook 所屬个用戶端步驟：input.client。
url (string) — Lingara 將事件送去个 HTTPS 地址。
events (readonly string[]) — 愛送个事件類型，像 "lesson_plan.ready"。

`ManifestOptions`

lingara.manifest 个選項，用 camelCase；輔助函式會寫出清單个傳輸格式。

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>>) — App 个名稱：一隻字串，抑係每隻語言代碼一隻字串。
description (string | Readonly<Record<string, string>>) — 關於 App 个一句話：一隻字串，抑係每隻語言代碼一隻字串。
renderUrl (string) — Lingara 討 App 卡片个 HTTPS 地址。
slots (readonly AppSlot[]) — App 卡片做得出現个位所。
context? (readonly ContextSlice[]) — App 收到个情境片段。預設係無。
scopes? (readonly Scope[]) — App 向學習者要求个權限。預設係無。
tutorNote? (boolean) — App 做得留一隻備註分導師無。預設係 false。
defaultLocale? (string) — 單純字串个名稱抑係描述儲存所用个語言代碼。預設係 "en"。

`AppOptions`

lingara.app 个選項。

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

client (NodeHandle) — 這隻 App 所屬个用戶端步驟：input.client。
manifest (Manifest) — App 个清單，用 lingara.manifest 建立。

`ClientSpec`

用戶端步驟建立个東西：一隻 API 用戶端。

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

kind ('client') — 一定係 "client"。
name (string) — 用戶端个名稱。
scopes (readonly Scope[]) — 用戶端要求个權限。
redirectUris? (readonly string[]) — 用戶端个重新導向 URI（若有个話）。

`SecretSpec`

密鑰步驟建立个東西：為佢个用戶端產生个新密鑰。

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

kind ('secret') — 一定係 "secret"。
client (NodeHandle) — 密鑰所屬个用戶端步驟。

`WebhookSpec`

Webhook 步驟建立个東西：一隻 Webhook 端點。

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

kind ('webhook') — 一定係 "webhook"。
client (NodeHandle) — Webhook 所屬个用戶端步驟。
url (string) — 事件送去个地址。
events (readonly string[]) — 送出个事件類型。

`AppSpec`

App 步驟建立个東西：一隻在 Lingara 肚背畫卡个 App。

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

kind ('app') — 一定係 "app"。
client (NodeHandle) — App 所屬个用戶端步驟。
manifest (Manifest) — App 个清單。

`Manifest`

傳輸格式个 App 清單，摎伺服器儲存个形式共樣。

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) — 一定係 1。
default_locale (string) — 學習者自家个語言無項目个時節顯示个語言。
name (Readonly<Record<string, string>>) — App 个名稱，照語言代碼分。
description (Readonly<Record<string, string>>) — 關於 App 个一句話，照語言代碼分。
render_url (string) — Lingara 討 App 卡片个 HTTPS 地址。
slots (readonly AppSlot[]) — App 卡片做得出現个位所。
context (readonly ContextSlice[]) — App 收到个情境片段。
scopes (readonly Scope[]) — App 向學習者要求个權限。
tutor_note (boolean) — App 做得留一隻備註分導師無。

`Spec`

輔助函式轉來个任何 spec。腳本淨轉一隻。

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

`Upstream`

每隻直接上游步驟个輸出，照控制代碼索引。

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

`ClientInput`

用戶端步驟个輸入：佢个欄位，就係 lingara.client 个選項。

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

name (string) — 用戶端个名稱。
scopes (readonly Scope[]) — 用戶端要求个權限。
redirectUris? (readonly string[]) — 用戶端个重新導向 URI（若步驟有个話）。
upstream (Upstream) — 每隻直接上游步驟个輸出。

`SecretInput`

密鑰步驟个輸入。client 係摎這隻步驟連接个該隻用戶端步驟。

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

client (NodeHandle) — 摎這隻步驟連接个用戶端步驟。
upstream (Upstream) — 每隻直接上游步驟个輸出。

`WebhookInput`

Webhook 步驟个輸入：佢个欄位，再加上連接个用戶端。

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

client (NodeHandle) — 摎這隻步驟連接个用戶端步驟。
url (string) — 步驟个欄位指定个地址。
events (readonly string[]) — 步驟个欄位指定个事件類型。
upstream (Upstream) — 每隻直接上游步驟个輸出。

`AppInput`

App 步驟个輸入：佢个清單欄位，再加上連接个用戶端。

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

client (NodeHandle) — 摎這隻步驟連接个用戶端步驟。
manifest (ManifestOptions) — 步驟个欄位描述个清單。
upstream (Upstream) — 每隻直接上游步驟个輸出。

`InputFor`

指定種類个步驟腳本會收到个輸入。

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

`LingaraV1`

腳本呼叫个輔助函式。每隻都會轉一隻凍結个 spec，型別毋著个選項會擲出一隻講明係哪隻選項个 TypeError。

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') — 一定係 "v1"。
client(options: ClientOptions): ClientSpec — 一隻 API 用戶端。
secret(client: NodeHandle): SecretSpec — 為用戶端步驟產生个新密鑰。
webhook(options: WebhookOptions): WebhookSpec — 用戶端步驟頂高个 Webhook 端點。
app(options: AppOptions): AppSpec — 用戶端步驟頂高个 App。
manifest(options: ManifestOptions): Manifest — 傳輸格式个清單，還將 v1 留做做得揀个選項填好。

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`

步驟个腳本就係這隻函式个主體：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;

另外看

身份驗證