ឯកសារអ្នកអភិវឌ្ឍន៍ Lingara

ទំព័រនេះត្រូវបានបកប្រែពីភាសាអង់គ្លេស។ ប្រសិនបើទាំងពីរខុសគ្នា ទំព័រភាសាអង់គ្លេសគឺត្រឹមត្រូវ។ អានទំព័រភាសាអង់គ្លេស

ការតភ្ជាប់មួយត្រូវបានបង្កើតឡើងពីជំហាន ហើយជំហានណាមួយក៏អាចមានស្គ្រីបបានដែរ។ ស្គ្រីបរបស់ជំហានមួយគឺជាតួនៃអនុគមន៍មួយ។ វាទទួលតម្លៃពីរ៖ lingara ដែលជា API នៅលើទំព័រនេះ និង input ដែលជាវាលផ្ទាល់របស់ជំហាន រួមជាមួយក្លាយអិនត៍របស់វា និងជំហានដែលបានភ្ជាប់នៅមុនវា។ ប្រភេទនៃ input អាស្រ័យលើប្រភេទជំហាន ដូច្នេះស្គ្រីបរបស់ជំហាន Webhook អានវាលរបស់ជំហាន Webhook។ ស្គ្រីបត្រឡប់វត្ថុតែមួយគត់ ដែលបង្កើតដោយអនុគមន៍ជំនួយមួយក្នុងចំណោមអនុគមន៍ខាងក្រោម។

ស្គ្រីបមិនដែលឃើញសម្ងាត់ទេ។ នៅពេលជំហានមួយត្រូវការក្លាយអិនត៍របស់វា វាទទួលបាន handle មួយ ដូចជា input.client ហើយអនុគមន៍ជំនួយកត់ត្រា handle នោះ។ Lingara បំពេញតម្លៃពិតនៅពេលអ្នកអនុវត្តការតភ្ជាប់។

អ្វីដែលស្គ្រីបមិនត្រូវធ្វើ

ស្គ្រីបដំណើរការនៅក្នុងកម្មវិធីរុករកផ្ទាល់ខ្លួនរបស់អ្នក នៅក្នុង worker ដែលគ្មានបណ្ដាញ និងគ្មានកន្លែងផ្ទុក។ វាត្រូវគោរពដែនកំណត់ទាំងនេះ៖

• វាបញ្ចប់ក្នុងរយៈពេល 1 វិនាទី។
• ខ្សែអក្សរដែលវាត្រឡប់មានប្រវែងយ៉ាងច្រើន 2048 តួអក្សរ។
• បញ្ជីដែលវាត្រឡប់មានយ៉ាងច្រើន 64 ធាតុ។
• លទ្ធផលទាំងមូលរបស់វាមានទំហំយ៉ាងច្រើន 16 KiB។

ស្គ្រីបដែលបំពានដែនកំណត់ បោះកំហុស ឬត្រឡប់អ្វីផ្សេងក្រៅពីលទ្ធផលរបស់អនុគមន៍ជំនួយមួយ ធ្វើឲ្យជំហានរបស់វាបរាជ័យ ហើយ «ពិនិត្យវា» បង្ហាញថាជំហានណា និងហេតុអ្វី។

ការសន្យាអំពីកំណែ

អ្វីៗទាំងអស់នៅលើទំព័រនេះគឺ lingara.v1។ នៅក្នុង v1 API មានតែរីកធំឡើងប៉ុណ្ណោះ៖ អនុគមន៍ជំនួយថ្មី ជម្រើសមិនបង្ខំថ្មី ឬប្រភេទជំហានថ្មីអាចលេចឡើង ប៉ុន្តែគ្មានអ្វីដែលអ្នកអាចប្រើថ្ងៃនេះត្រូវបានដកចេញ ប្ដូរឈ្មោះ ឬបង្រួមឡើយ។ ការផ្លាស់ប្ដូរដែលនឹងធ្វើឲ្យស្គ្រីបខូច គឺជាកំណែថ្មីនៅក្បែរកំណែនេះ ហើយ v1 នៅដដែល។

សេចក្ដីប្រកាស

សេចក្ដីប្រកាសនីមួយៗខាងក្រោមត្រូវបានបង្កើតចេញពីឯកសារដដែលដែលកម្មវិធីកែស្គ្រីបប្រើសម្រាប់ការបំពេញស្វ័យប្រវត្តិ។

NodeHandle

លេខសម្គាល់នៃជំហានមួយទៀត ដូចជា "n1"។ ជំហានដែលពឹងផ្អែកដាក់ឈ្មោះក្លាយអិនត៍របស់វាតាម handle។

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 អនុគមន៍ជំនួយសរសេរទម្រង់បញ្ជូន (wire form) របស់ម៉ានីហ្វេស្ត។

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[]) — URI បញ្ជូនបន្តរបស់ក្លាយអិនត៍ ប្រសិនបើវាមាន។

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

spec ណាមួយដែលអនុគមន៍ជំនួយត្រឡប់។ ស្គ្រីបមួយត្រឡប់តែមួយគត់។

export type Spec = ClientSpec | SecretSpec | WebhookSpec | AppSpec;

Upstream

លទ្ធផលរបស់ជំហានខាងលើផ្ទាល់នីមួយៗ តាម handle។

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[]) — URI បញ្ជូនបន្តរបស់ក្លាយអិនត៍ ប្រសិនបើជំហានមាន។
• 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

អនុគមន៍ជំនួយដែលស្គ្រីបហៅ។ អនុគមន៍នីមួយៗត្រឡប់ spec ដែលបានបង្កក ហើយជម្រើសដែលខុសប្រភេទបោះ 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;