Belgeyên pêşdebiran ên Lingara

Ev rûpel ji Îngilîzî hatiye wergerandin. Heke her du ji hev cuda bin, rûpela Îngilîzî rast e. Rûpela Îngilîzî bixwîne

Girêdanek ji gavan pêk tê, û her gav dikare skrîptekê hilgire. Skrîpta gavekê laşê fonksiyonekê ye. Ew du nirxan werdigire: lingara, API-ya li ser vê rûpelê, û input, qadên gavê bi xwe ligel klientê wê û gavên ku berî wê pê ve hatine girêdan. Cureyê input bi cureyê gavê ve girêdayî ye, ji ber vê yekê skrîpta gaveke webhook qadên gaveke webhook dixwîne. Skrîpt tam yek tiştî vedigerîne, ku bi yek ji alîkarên li jêr hatiye avakirin.

Skrîptek qet nepeniyekê nabîne. Li cihê ku gavek hewceyî klientê xwe ye, ew destikekê distîne, wek input.client, û alîkar wî destikî tomar dike. Dema ku tu girêdanê disepînî, Lingara nirxên rastîn tijî dike.

Tiştê ku skrîptek divê neke

Skrîptek di geroka te bi xwe de, di workerekê de ku ne tor û ne depo heye, dimeşe. Ew bi van sînoran ve girêdayî ye:

Di nav 1 saniyeyê de diqede.
Rêzeka ku vedigerîne herî zêde 2048 tîp dirêj e.
Lîsteya ku vedigerîne herî zêde 64 hêman hene.
Tevahiya encama wê herî zêde 16 KiB e.

Skrîpteke ku sînorekê dişkîne, xeletiyekê davêje, an tiştekî ji bilî encama yek alîkarê vedigerîne, gava xwe têk dibe, û “Kontrol bike” nîşan dide ka kîjan gav û çima.

Soza guhertoyê

Her tiştê li ser vê rûpelê lingara.v1 e. Di nav v1 de API tenê mezin dibe: alîkarekî nû, vebijarkeke nû ya ne-mecbûrî an cureyekî nû yê gavê dikare xuya bibe, lê tiştek ji yên ku tu îro dikarî bikar bînî nayê rakirin, navê wî nayê guhertin an teng nabe. Guhertineke ku dê skrîptekê bişkîne guhertoyeke nû ye li kêleka vê, û v1 wek xwe dimîne.

Danezan

Her danezana li jêr ji heman pelê tê çêkirin ku edîtora skrîptê li gorî wê temam dike.

`NodeHandle`

Nasnameya gaveke din, wek "n1". Gaveke girêdayî klientê xwe bi destikê bi nav dike.

export type NodeHandle = string;

`Scope`

Destûrek ku klientekî API dikare hebe. Server biryar dide ka hesabê te dikare kîjanan bikar bîne.

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

`AppSlot`

Cihek di sepana Lingara de ku karta sepanekê dikare lê xuya bibe.

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

`ContextSlice`

Beşek ji çarçoveya xwendekar ku sepanek dikare bixwaze wergire.

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

`ClientOptions`

Vebijark ji bo lingara.client.

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

name (string) — Navê klient, wek ku Amûrên pêşdebiran nîşan didin.
scopes (readonly Scope[]) — Destûrên ku klient dixwaze.
redirectUris? (readonly string[]) — Cihên ku herikîna koda destûrdanê dikare xwendekarekî vegerîne wan. Ji bo klientekî server-bo-server wê nenivîse.

`WebhookOptions`

Vebijark ji bo lingara.webhook.

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

client (NodeHandle) — Gava klient a ku ev webhook aîdî wê ye: input.client.
url (string) — Navnîşana HTTPS ya ku Lingara bûyeran digihîne wê.
events (readonly string[]) — Cureyên bûyeran ên ku divê werin gihandin, wek "lesson_plan.ready".

`ManifestOptions`

Vebijark ji bo lingara.manifest, bi camelCase; alîkar şiklê veguhastinê yê manifestê dinivîse.

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>>) — Navê sepanê: rêzekek, an rêzekek ji bo her koda herêmî.
description (string | Readonly<Record<string, string>>) — Hevokek li ser sepanê: rêzekek, an rêzekek ji bo her koda herêmî.
renderUrl (string) — Navnîşana HTTPS ya ku Lingara karta sepanê jê dixwaze.
slots (readonly AppSlot[]) — Cihên ku karta sepanê dikare lê xuya bibe.
context? (readonly ContextSlice[]) — Beşên çarçoveyê yên ku sepan werdigire. Bi xwerû tune.
scopes? (readonly Scope[]) — Destûrên ku sepan ji xwendekar dixwaze. Bi xwerû tune.
tutorNote? (boolean) — Gelo sepan dikare notekê ji mamoste re bihêle. Bi xwerû false.
defaultLocale? (string) — Herêma ku nav an danasîneke bi rêzeka sade di bin wê de tê tomarkirin. Bi xwerû "en".

`AppOptions`

Vebijark ji bo lingara.app.

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

client (NodeHandle) — Gava klient a ku ev sepan aîdî wê ye: input.client.
manifest (Manifest) — Manifesta sepanê, ku bi lingara.manifest hatiye avakirin.

`ClientSpec`

Tiştê ku gaveke klient çêdike: klientekî API.

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

kind ('client') — Her tim "client".
name (string) — Navê klient.
scopes (readonly Scope[]) — Destûrên ku klient dixwaze.
redirectUris? (readonly string[]) — URI-yên beralîkirinê yên klient, dema ku hebin.

`SecretSpec`

Tiştê ku gaveke nepeniyê çêdike: nepeniyeke nû ji bo klientê wê.

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

kind ('secret') — Her tim "secret".
client (NodeHandle) — Gava klient a ku nepenî aîdî wê ye.

`WebhookSpec`

Tiştê ku gaveke webhook çêdike: xaleke dawî ya webhook.

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

kind ('webhook') — Her tim "webhook".
client (NodeHandle) — Gava klient a ku webhook aîdî wê ye.
url (string) — Navnîşana ku bûyer digihêjin wê.
events (readonly string[]) — Cureyên bûyeran ên ku têne gihandin.

`AppSpec`

Tiştê ku gaveke sepanê çêdike: sepanek ku kartekê di nav Lingara de xêz dike.

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

kind ('app') — Her tim "app".
client (NodeHandle) — Gava klient a ku sepan aîdî wê ye.
manifest (Manifest) — Manifesta sepanê.

`Manifest`

Manifesta sepanê bi şiklê wê yê veguhastinê, wek ku server wê tomar dike.

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) — Her tim 1.
default_locale (string) — Herêma ku tê nîşandan dema ku ya xwendekar bi xwe tomarek tune be.
name (Readonly<Record<string, string>>) — Navê sepanê, li gorî koda herêmî.
description (Readonly<Record<string, string>>) — Hevokek li ser sepanê, li gorî koda herêmî.
render_url (string) — Navnîşana HTTPS ya ku Lingara karta sepanê jê dixwaze.
slots (readonly AppSlot[]) — Cihên ku karta sepanê dikare lê xuya bibe.
context (readonly ContextSlice[]) — Beşên çarçoveyê yên ku sepan werdigire.
scopes (readonly Scope[]) — Destûrên ku sepan ji xwendekar dixwaze.
tutor_note (boolean) — Gelo sepan dikare notekê ji mamoste re bihêle.

`Spec`

Her spec a ku alîkarek vedigerîne. Skrîptek tam yekê vedigerîne.

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

`Upstream`

Derana her gaveke rasterast a berê, li gorî destikê.

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

`ClientInput`

Têketina gaveke klient: qadên wê, ku vebijarkên lingara.client in.

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

name (string) — Navê klient.
scopes (readonly Scope[]) — Destûrên ku klient dixwaze.
redirectUris? (readonly string[]) — URI-yên beralîkirinê yên klient, dema ku gav hin hebin.
upstream (Upstream) — Derana her gaveke rasterast a berê.

`SecretInput`

Têketina gaveke nepeniyê. client ew yek gava klient e ku bi vê ve hatiye girêdan.

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

client (NodeHandle) — Gava klient a ku bi vê ve hatiye girêdan.
upstream (Upstream) — Derana her gaveke rasterast a berê.

`WebhookInput`

Têketina gaveke webhook: qadên wê, û klientê girêdayî.

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

client (NodeHandle) — Gava klient a ku bi vê ve hatiye girêdan.
url (string) — Navnîşana ku qadên gavê navê wê didin.
events (readonly string[]) — Cureyên bûyeran ên ku qadên gavê navê wan didin.
upstream (Upstream) — Derana her gaveke rasterast a berê.

`AppInput`

Têketina gaveke sepanê: qadên manifesta wê, û klientê girêdayî.

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

client (NodeHandle) — Gava klient a ku bi vê ve hatiye girêdan.
manifest (ManifestOptions) — Manifesta ku qadên gavê didin nasîn.
upstream (Upstream) — Derana her gaveke rasterast a berê.

`InputFor`

Têketina ku skrîpteke ji cureyê gava diyarkirî werdigire.

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

`LingaraV1`

Alîkarên ku skrîptek gazî dike. Her yek spec a cemidî vedigerîne, û vebijarkeke bi cureyê şaş TypeError davêje ku navê wê dide.

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') — Her tim "v1".
client(options: ClientOptions): ClientSpec — Klientekî API.
secret(client: NodeHandle): SecretSpec — Nepeniyeke nû ji bo gaveke klient.
webhook(options: WebhookOptions): WebhookSpec — Xaleke dawî ya webhook li ser gaveke klient.
app(options: AppOptions): AppSpec — Sepanek li ser gaveke klient.
manifest(options: ManifestOptions): Manifest — Manifestek bi şiklê veguhastinê, bi vebijarkên ku v1 vebijarkî dihêle tijîkirî.

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`

Skrîpta gavekê laşê vê fonksiyonê ye: 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;

Herwiha binêre

Rastandin