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 應用程式內底會當顯示應用程式卡片的所在。

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

`ContextSlice`

應用程式會當要求收著的學習者情境的一部份。

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

`AppOptions`

lingara.app 的選項。

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

client (NodeHandle) — 這个應用程式所屬的用戶端步驟：input.client。
manifest (Manifest) — 應用程式的資訊清單，用 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`

應用程式步驟建立的物件：一个佇 Lingara 內底畫卡片的應用程式。

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

kind ('app') — 一定是 "app"。
client (NodeHandle) — 應用程式所屬的用戶端步驟。
manifest (Manifest) — 應用程式的資訊清單。

`Manifest`

傳輸格式的應用程式資訊清單，佮伺服器儲存的形式仝款。

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>>) — 應用程式的名稱，照語言代碼分。
description (Readonly<Record<string, string>>) — 關係應用程式的一句話，照語言代碼分。
render_url (string) — Lingara 討應用程式卡片的 HTTPS 地址。
slots (readonly AppSlot[]) — 應用程式卡片會當出現的所在。
context (readonly ContextSlice[]) — 應用程式收著的情境片段。
scopes (readonly Scope[]) — 應用程式向學習者要求的權限。
tutor_note (boolean) — 應用程式敢會當留一个備註予導師。

`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`

應用程式步驟的輸入：伊的資訊清單欄位，閣加上連結的用戶端。

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 — 用戶端步驟頂懸的應用程式。
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;

閣看

身份驗證