Dokumentasyon ng developer ng Lingara

Isinalin mula sa Ingles ang pahinang ito. Kung magkaiba ang dalawa, ang pahinang Ingles ang tama. Basahin ang pahinang Ingles

Binubuo ang isang koneksyon ng mga hakbang, at puwedeng magdala ng script ang alinmang hakbang. Ang script ng isang hakbang ay ang katawan ng isang function. Tumatanggap ito ng dalawang value: lingara, ang API sa pahinang ito, at input, ang sariling mga field ng hakbang kasama ang client nito at ang mga hakbang na nakakabit bago ito. Nakadepende ang uri ng input sa klase ng hakbang, kaya binabasa ng script ng isang webhook na hakbang ang mga field ng webhook na hakbang. Eksaktong isang object ang ibinabalik ng script, na binuo ng isa sa mga helper sa ibaba.

Hindi kailanman nakakakita ng secret ang isang script. Kapag kailangan ng isang hakbang ang client nito, nakakakuha ito ng handle, gaya ng input.client, at itinatala ng helper ang handle na iyon. Pinupunan ng Lingara ang totoong mga value kapag inilapat mo ang koneksyon.

Ang hindi dapat gawin ng isang script

Tumatakbo ang script sa sarili mong browser, sa isang worker na walang network at walang storage. Sakop ito ng mga limitasyong ito:

Natatapos ito sa loob ng 1 segundo.
Ang string na ibinabalik nito ay hanggang 2048 character lang ang haba.
Ang listahang ibinabalik nito ay may hanggang 64 na item lang.
Ang buong resulta nito ay hanggang 16 KiB lang.

Ang script na lumalampas sa limitasyon, nagta-throw, o nagbabalik ng anumang iba bukod sa resulta ng isang helper ay nagpapapalya sa hakbang nito, at ipinapakita ng “Suriin ito” kung aling hakbang at bakit.

Ang pangako sa bersyon

Lahat ng nasa pahinang ito ay lingara.v1. Sa loob ng v1, lumalaki lang ang API: puwedeng lumabas ang bagong helper, bagong opsyonal na option, o bagong klase ng hakbang, pero walang anumang magagamit mo ngayon ang aalisin, papalitan ng pangalan, o paliliitin. Ang pagbabagong makakasira sa isang script ay isang bagong bersyon sa tabi nito, at mananatili ang v1 kung ano ito.

Ang mga deklarasyon

Ang bawat deklarasyon sa ibaba ay binuo mula sa parehong file na pinagbabatayan ng pag-complete ng script editor.

`NodeHandle`

Ang id ng ibang hakbang, gaya ng "n1". Pinapangalanan ng isang nakadependeng hakbang ang client nito ayon sa handle.

export type NodeHandle = string;

`Scope`

Isang pahintulot na puwedeng hawakan ng isang API client. Ang server ang nagpapasya kung alin ang puwedeng gamitin ng account mo.

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

`AppSlot`

Isang lugar sa Lingara app kung saan puwedeng lumabas ang card ng isang app.

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

`ContextSlice`

Isang bahagi ng context ng mag-aaral na puwedeng hilinging matanggap ng isang app.

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

`ClientOptions`

Mga option para sa lingara.client.

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

name (string) — Ang pangalan ng client, gaya ng ipinapakita ng Mga tool ng developer.
scopes (readonly Scope[]) — Ang mga pahintulot na hinihingi ng client.
redirectUris? (readonly string[]) — Kung saan puwedeng ibalik ng authorization-code flow ang isang mag-aaral. Alisin para sa server-to-server na client.

`WebhookOptions`

Mga option para sa lingara.webhook.

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

client (NodeHandle) — Ang client na hakbang na kinabibilangan ng webhook na ito: input.client.
url (string) — Ang HTTPS address na pinaghahatiran ng Lingara ng mga event.
events (readonly string[]) — Ang mga uri ng event na ihahatid, gaya ng "lesson_plan.ready".

`ManifestOptions`

Mga option para sa lingara.manifest, sa camelCase; isinusulat ng helper ang wire form ng 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>>) — Ang pangalan ng app: isang string, o isang string bawat locale code.
description (string | Readonly<Record<string, string>>) — Isang pangungusap tungkol sa app: isang string, o isang string bawat locale code.
renderUrl (string) — Ang HTTPS address na hinihingan ng Lingara ng card ng app.
slots (readonly AppSlot[]) — Kung saan puwedeng lumabas ang card ng app.
context? (readonly ContextSlice[]) — Ang mga bahagi ng context na natatanggap ng app. Wala bilang default.
scopes? (readonly Scope[]) — Ang mga pahintulot na hinihingi ng app sa mag-aaral. Wala bilang default.
tutorNote? (boolean) — Kung puwedeng mag-iwan ang app ng tala para sa tutor. false bilang default.
defaultLocale? (string) — Ang locale kung saan naka-store ang pangalan o paglalarawang payak na string. "en" bilang default.

`AppOptions`

Mga option para sa lingara.app.

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

client (NodeHandle) — Ang client na hakbang na kinabibilangan ng app na ito: input.client.
manifest (Manifest) — Ang manifest ng app, na binuo gamit ang lingara.manifest.

`ClientSpec`

Ang ginagawa ng isang client na hakbang: isang API client.

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

kind ('client') — Palaging "client".
name (string) — Ang pangalan ng client.
scopes (readonly Scope[]) — Ang mga pahintulot na hinihingi ng client.
redirectUris? (readonly string[]) — Ang mga redirect URI ng client, kung mayroon ito.

`SecretSpec`

Ang ginagawa ng isang secret na hakbang: isang bagong secret para sa client nito.

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

kind ('secret') — Palaging "secret".
client (NodeHandle) — Ang client na hakbang na kinabibilangan ng secret.

`WebhookSpec`

Ang ginagawa ng isang webhook na hakbang: isang endpoint ng webhook.

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

kind ('webhook') — Palaging "webhook".
client (NodeHandle) — Ang client na hakbang na kinabibilangan ng webhook.
url (string) — Ang address na pinaghahatiran ng mga event.
events (readonly string[]) — Ang mga uri ng event na inihahatid.

`AppSpec`

Ang ginagawa ng isang app na hakbang: isang app na nagre-render ng card sa loob ng Lingara.

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

kind ('app') — Palaging "app".
client (NodeHandle) — Ang client na hakbang na kinabibilangan ng app.
manifest (Manifest) — Ang manifest ng app.

`Manifest`

Isang manifest ng app sa wire form nito, gaya ng pag-store dito ng 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) — Palaging 1.
default_locale (string) — Ang locale na ipinapakita kapag walang entry para sa sariling locale ng mag-aaral.
name (Readonly<Record<string, string>>) — Ang pangalan ng app, bawat locale code.
description (Readonly<Record<string, string>>) — Isang pangungusap tungkol sa app, bawat locale code.
render_url (string) — Ang HTTPS address na hinihingan ng Lingara ng card ng app.
slots (readonly AppSlot[]) — Kung saan puwedeng lumabas ang card ng app.
context (readonly ContextSlice[]) — Ang mga bahagi ng context na natatanggap ng app.
scopes (readonly Scope[]) — Ang mga pahintulot na hinihingi ng app sa mag-aaral.
tutor_note (boolean) — Kung puwedeng mag-iwan ang app ng tala para sa tutor.

`Spec`

Anumang spec na ibinabalik ng isang helper. Eksaktong isa ang ibinabalik ng isang script.

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

`Upstream`

Ang output ng bawat direktang upstream na hakbang, ayon sa handle.

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

`ClientInput`

Ang input ng isang client na hakbang: ang mga field nito, na siyang mga option ng lingara.client.

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

name (string) — Ang pangalan ng client.
scopes (readonly Scope[]) — Ang mga pahintulot na hinihingi ng client.
redirectUris? (readonly string[]) — Ang mga redirect URI ng client, kung mayroon ang hakbang.
upstream (Upstream) — Ang output ng bawat direktang upstream na hakbang.

`SecretInput`

Ang input ng isang secret na hakbang. Ang client ay ang iisang client na hakbang na nakakabit dito.

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

client (NodeHandle) — Ang client na hakbang na nakakabit dito.
upstream (Upstream) — Ang output ng bawat direktang upstream na hakbang.

`WebhookInput`

Ang input ng isang webhook na hakbang: ang mga field nito, at ang nakakabit na client.

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

client (NodeHandle) — Ang client na hakbang na nakakabit dito.
url (string) — Ang address na pinapangalanan ng mga field ng hakbang.
events (readonly string[]) — Ang mga uri ng event na pinapangalanan ng mga field ng hakbang.
upstream (Upstream) — Ang output ng bawat direktang upstream na hakbang.

`AppInput`

Ang input ng isang app na hakbang: ang mga field ng manifest nito, at ang nakakabit na client.

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

client (NodeHandle) — Ang client na hakbang na nakakabit dito.
manifest (ManifestOptions) — Ang manifest na inilalarawan ng mga field ng hakbang.
upstream (Upstream) — Ang output ng bawat direktang upstream na hakbang.

`InputFor`

Ang input na natatanggap ng script ng ibinigay na klase ng hakbang.

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

`LingaraV1`

Ang mga helper na tinatawag ng isang script. Nagbabalik ang bawat isa ng naka-freeze na spec, at nagta-throw ng TypeError na pinapangalanan ito ang option na mali ang uri.

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') — Palaging "v1".
client(options: ClientOptions): ClientSpec — Isang API client.
secret(client: NodeHandle): SecretSpec — Isang bagong secret para sa isang client na hakbang.
webhook(options: WebhookOptions): WebhookSpec — Isang endpoint ng webhook sa isang client na hakbang.
app(options: AppOptions): AppSpec — Isang app sa isang client na hakbang.
manifest(options: ManifestOptions): Manifest — Isang manifest sa wire form nito, na napunan na ang mga option na iniiwang opsyonal ng 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`

Ang script ng isang hakbang ay ang katawan ng function na ito: 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;

Tingnan din

Pagpapatunay