بەڵگەنامەکانی گەشەپێدەرانی Lingara

ئەم پەڕەیە لە ئینگلیزییەوە وەرگێڕدراوە. ئەگەر هەردووکیان جیاواز بوون، پەڕە ئینگلیزییەکە ڕاستە. پەڕە ئینگلیزییەکە بخوێنەوە

پەیوەندییەک لە هەنگاوەکان پێکدێت، و هەر هەنگاوێک دەتوانێت سکریپتێکی هەبێت. سکریپتی هەنگاوێک جەستەی فەنکشنێکە. دوو بەها وەردەگرێت: lingara، کە API ـی ئەم پەڕەیەیە، و input، کە خانەکانی خودی هەنگاوەکەیە لەگەڵ کلاینتەکەی و ئەو هەنگاوانەی پێش ئەو پێوەی بەستراون. جۆری input بەندە بە جۆری هەنگاوەکە، بۆیە سکریپتی هەنگاوێکی webhook خانەکانی هەنگاوێکی webhook دەخوێنێتەوە. سکریپتەکە ڕێک یەک شت دەگەڕێنێتەوە، کە یەکێک لە فەنکشنە یاریدەدەرەکانی خوارەوە دروستی کردووە.

سکریپتێک هەرگیز نهێنییەک نابینێت. لەو شوێنەی هەنگاوێک پێویستی بە کلاینتەکەی هەیە، ناسێنەرێک وەردەگرێت، وەک input.client، و فەنکشنە یاریدەدەرەکە ئەو ناسێنەرە تۆمار دەکات. Lingara بەها ڕاستەقینەکان پڕ دەکاتەوە کاتێک پەیوەندییەکە جێبەجێ دەکەیت.

ئەوەی سکریپتێک نابێت بیکات

سکریپتێک لە وێبگەڕەکەی خۆتدا کار دەکات، لە worker ـێکدا کە نە تۆڕی هەیە نە کۆگا. پابەندی ئەم سنوورانەیە:

• لە ماوەی 1 چرکەدا تەواو دەبێت.
• ئەو دەقەی دەیگەڕێنێتەوە زۆرترین درێژییەکەی 2048 پیتە.
• ئەو لیستەی دەیگەڕێنێتەوە زۆرترین 64 بڕگەی هەیە.
• هەموو ئەنجامەکەی زۆرترین 16 KiB ـە.

سکریپتێک کە سنوورێک تێپەڕێنێت، هەڵەیەک فڕێ بدات، یان شتێک جگە لە ئەنجامی یەک فەنکشنی یاریدەدەر بگەڕێنێتەوە، هەنگاوەکەی شکست پێدەهێنێت، و «بیپشکنە» نیشان دەدات کام هەنگاو و بۆچی.

بەڵێنی وەشان

هەموو شتێک لەم پەڕەیەدا lingara.v1 ـە. لەناو v1 دا API ـەکە تەنها گەشە دەکات: لەوانەیە فەنکشنێکی یاریدەدەری نوێ، هەڵبژاردنێکی ئارەزوومەندانەی نوێ یان جۆرێکی نوێی هەنگاو دەربکەوێت، بەڵام هیچ شتێک کە ئەمڕۆ دەتوانیت بەکاری بهێنیت لاناببرێت، ناوی ناگۆڕدرێت یان تەسک ناکرێتەوە. گۆڕانکارییەک کە سکریپتێک تێکبدات وەشانێکی نوێیە لە تەنیشت ئەمەوە، و v1 وەک خۆی دەمێنێتەوە.

ڕاگەیاندنەکان

هەر ڕاگەیاندنێکی خوارەوە لە هەمان ئەو فایلەوە دروستکراوە کە دەستکاریکەری سکریپت تەواوکردنەکانی لەسەر بنەمای ئەو دەکات.

NodeHandle

ناسێنەری هەنگاوێکی تر، وەک "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) — ئەو ناونیشانە HTTPS ـەی Lingara ڕووداوەکانی پێ دەگەیەنێت.
• 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) — ئەو ناونیشانە HTTPS ـەی Lingara داوای کارتی ئەپەکەی لێ دەکات.
• 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[]) — ناونیشانەکانی گەڕاندنەوەی کلاینتەکە، ئەگەر هەیبێت.

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) — ئەو ناونیشانە HTTPS ـەی Lingara داوای کارتی ئەپەکەی لێ دەکات.
• slots (readonly AppSlot[]) — ئەو شوێنەی کارتی ئەپەکە دەتوانێت تێیدا دەربکەوێت.
• context (readonly ContextSlice[]) — ئەو بەشانەی دۆخ کە ئەپەکە وەریان دەگرێت.
• scopes (readonly Scope[]) — ئەو مۆڵەتانەی ئەپەکە لە فێرخوازەکە داوایان دەکات.
• tutor_note (boolean) — ئایا ئەپەکە دەتوانێت تێبینییەک بۆ مامۆستاکە بەجێبهێڵێت.

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[]) — ناونیشانەکانی گەڕاندنەوەی کلاینتەکە، ئەگەر هەنگاوەکە هەیبێت.
• 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

ئەو فەنکشنە یاریدەدەرانەی سکریپتێک بانگیان دەکات. هەر یەکەیان تایبەتمەندییەکی بەستوو دەگەڕێنێتەوە، و هەڵبژاردنێک بە جۆری هەڵە 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;