وثائق Lingara للمطوّرين

هذه الصفحة مترجمة من الإنجليزية. إذا اختلفت النسختان، فالصفحة الإنجليزية هي الصحيحة. اقرأ الصفحة الإنجليزية

يتكوّن الاتصال من خطوات، ويمكن لأي خطوة أن تحمل نصًا برمجيًا. النص البرمجي للخطوة هو جسم دالة. ويتلقّى قيمتين: lingara، وهي الواجهة الموصوفة في هذه الصفحة، وinput، وهي حقول الخطوة نفسها مع عميلها والخطوات المربوطة قبلها. يعتمد نوع input على نوع الخطوة، فالنص البرمجي لخطوة webhook يقرأ حقول خطوة webhook. ويُرجع النص البرمجي كائنًا واحدًا بالضبط، تبنيه إحدى الدوال المساعدة أدناه.

لا يرى النص البرمجي سرًّا أبدًا. حيث تحتاج الخطوة إلى عميلها، تحصل على مُعرِّف، مثل input.client، وتسجّل الدالة المساعدة ذلك المُعرِّف. تملأ Lingara القيم الحقيقية عندما تطبّق الاتصال.

ما يجب ألا يفعله النص البرمجي

يعمل النص البرمجي في متصفحك أنت، داخل عامل بلا شبكة وبلا تخزين. ويخضع لهذه الحدود:

• ينتهي خلال 1 ثانية.
• السلسلة النصية التي يُرجعها لا يتجاوز طولها 2048 حرفًا.
• القائمة التي يُرجعها لا تتجاوز 64 عنصرًا.
• نتيجته كاملةً لا تتجاوز 16 KiB.

النص البرمجي الذي يتجاوز حدًّا، أو يرمي استثناءً، أو يُرجع شيئًا غير نتيجة دالة مساعدة واحدة، يُفشل خطوته، ويعرض «تحقّق منه» أي خطوة ولماذا.

وعد الإصدار

كل ما في هذه الصفحة هو lingara.v1. داخل v1 لا تفعل الواجهة إلا أن تنمو: قد تظهر دالة مساعدة جديدة، أو خيار اختياري جديد، أو نوع خطوة جديد، لكن لا شيء مما يمكنك استخدامه اليوم يُزال أو يُعاد تسميته أو يُضيَّق. التغيير الذي قد يكسر نصًا برمجيًا يكون إصدارًا جديدًا بجانب هذا الإصدار، ويبقى 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;