اسناد انکشاف‌دهندگان Lingara

این صفحه از انگلیسی ترجمه شده است. اگر این دو با هم فرق داشته باشند، صفحهٔ انگلیسی درست است. صفحهٔ انگلیسی را بخوانید

یک اتصال از مرحله‌ها تشکیل می‌شود و هر مرحله می‌تواند یک اسکریپت داشته باشد. اسکریپت یک مرحله بدنهٔ یک تابع است. دو مقدار دریافت می‌کند: lingara، یعنی API همین صفحه، و input، یعنی خانه‌های خود مرحله همراه با کلاینت آن و مرحله‌هایی که پیش از آن وصل شده‌اند. نوع input به نوع مرحله بستگی دارد، پس اسکریپت یک مرحلهٔ وب‌هوک خانه‌های یک مرحلهٔ وب‌هوک را می‌خواند. اسکریپت دقیقاً یک شیء برمی‌گرداند که با یکی از تابع‌های کمکی پایین ساخته شده است.

اسکریپت هرگز یک رمز را نمی‌بیند. جایی که یک مرحله به کلاینت خود نیاز دارد، یک شناسه می‌گیرد، مانند 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) — مرحلهٔ کلاینتی که این وب‌هوک به آن تعلق دارد: 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

آنچه یک مرحلهٔ وب‌هوک می‌سازد: یک نقطهٔ پایانی وب‌هوک.

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

• kind ('webhook') — همیشه "webhook".
• client (NodeHandle) — مرحلهٔ کلاینتی که وب‌هوک به آن تعلق دارد.
• 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

ورودی یک مرحلهٔ وب‌هوک: خانه‌های آن، به اضافهٔ کلاینت وصل‌شده.

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 — یک نقطهٔ پایانی وب‌هوک روی یک مرحلهٔ کلاینت.
• 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;