مستندات توسعه‌دهندگان 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;