د 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;