Dokumentasi pengembang Lingara

Halaman ini diterjemahkan dari bahasa Inggris. Jika keduanya berbeda, halaman bahasa Inggris yang benar. Baca halaman bahasa Inggris

Sebuah koneksi terdiri dari langkah-langkah, dan langkah mana pun dapat membawa skrip. Skrip sebuah langkah adalah isi sebuah fungsi. Skrip menerima dua nilai: lingara, API di halaman ini, dan input, kolom-kolom milik langkah itu sendiri beserta kliennya dan langkah-langkah yang tersambung sebelumnya. Tipe input bergantung pada jenis langkah, sehingga skrip langkah webhook membaca kolom-kolom langkah webhook. Skrip mengembalikan tepat satu objek, yang dibuat oleh salah satu fungsi pembantu di bawah.

Skrip tidak pernah melihat rahasia. Ketika sebuah langkah memerlukan kliennya, langkah itu mendapat sebuah handle, seperti input.client, dan fungsi pembantu mencatat handle tersebut. Lingara mengisi nilai sebenarnya saat Anda menerapkan koneksi.

Yang tidak boleh dilakukan skrip

Skrip berjalan di browser Anda sendiri, di dalam worker tanpa jaringan dan tanpa penyimpanan. Skrip terikat pada batas-batas berikut:

Skrip selesai dalam 1 detik.
String yang dikembalikannya paling panjang 2048 karakter.
Daftar yang dikembalikannya berisi paling banyak 64 item.
Seluruh hasilnya paling besar 16 KiB.

Skrip yang melanggar batas, melempar galat, atau mengembalikan sesuatu selain hasil dari satu fungsi pembantu akan menggagalkan langkahnya, dan “Periksa” menunjukkan langkah mana dan alasannya.

Janji versi

Semua yang ada di halaman ini adalah lingara.v1. Di dalam v1, API hanya bertambah: fungsi pembantu baru, opsi opsional baru, atau jenis langkah baru dapat muncul, tetapi tidak ada yang dapat Anda gunakan hari ini yang dihapus, diganti namanya, atau dipersempit. Perubahan yang akan merusak skrip menjadi versi baru di samping versi ini, dan v1 tetap seperti apa adanya.

Deklarasi

Setiap deklarasi di bawah dihasilkan dari berkas yang sama dengan yang digunakan editor skrip untuk pelengkapan otomatis.

`NodeHandle`

Id dari langkah lain, seperti "n1". Langkah yang bergantung menyebut kliennya melalui handle.

export type NodeHandle = string;

`Scope`

Izin yang dapat dimiliki klien API. Server menilai izin mana yang boleh digunakan akun Anda.

export type Scope = 'vocab:generate' | 'lesson_plans:read' | 'lesson_plans:write' | 'tutor:converse' | 'usage:read' | 'events:read' | 'events:write' | 'embed:mint' | 'embed:play';

`AppSlot`

Tempat di aplikasi Lingara tempat kartu sebuah aplikasi dapat muncul.

export type AppSlot = 'plans.empty_detail' | 'home.side';

`ContextSlice`

Bagian dari konteks pelajar yang dapat diminta oleh aplikasi.

export type ContextSlice = 'languages' | 'plan_summary' | 'review_due' | 'tutor_topic';

`ClientOptions`

Opsi untuk lingara.client.

export interface ClientOptions {
    name: string;
    scopes: readonly Scope[];
    redirectUris?: readonly string[];
}

name (string) — Nama klien, sebagaimana ditampilkan di Alat pengembang.
scopes (readonly Scope[]) — Izin yang diminta klien.
redirectUris? (readonly string[]) — Ke mana alur kode otorisasi dapat mengembalikan pelajar. Hilangkan untuk klien server-ke-server.

`WebhookOptions`

Opsi untuk lingara.webhook.

export interface WebhookOptions {
    client: NodeHandle;
    url: string;
    events: readonly string[];
}

client (NodeHandle) — Langkah klien tempat webhook ini berada: input.client.
url (string) — Alamat HTTPS tujuan Lingara mengirimkan peristiwa.
events (readonly string[]) — Jenis peristiwa yang dikirimkan, seperti "lesson_plan.ready".

`ManifestOptions`

Opsi untuk lingara.manifest, dalam camelCase; fungsi pembantu menulis bentuk kawat manifest.

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>>) — Nama aplikasi: satu string, atau satu string per kode lokal.
description (string | Readonly<Record<string, string>>) — Satu kalimat tentang aplikasi: satu string, atau satu string per kode lokal.
renderUrl (string) — Alamat HTTPS tempat Lingara meminta kartu aplikasi.
slots (readonly AppSlot[]) — Tempat kartu aplikasi dapat muncul.
context? (readonly ContextSlice[]) — Bagian konteks yang diterima aplikasi. Bawaannya tidak ada.
scopes? (readonly Scope[]) — Izin yang diminta aplikasi dari pelajar. Bawaannya tidak ada.
tutorNote? (boolean) — Apakah aplikasi boleh meninggalkan catatan untuk tutor. Bawaannya false.
defaultLocale? (string) — Lokal tempat nama atau deskripsi berupa string biasa disimpan. Bawaannya "en".

`AppOptions`

Opsi untuk lingara.app.

export interface AppOptions {
    client: NodeHandle;
    manifest: Manifest;
}

client (NodeHandle) — Langkah klien tempat aplikasi ini berada: input.client.
manifest (Manifest) — Manifest aplikasi, dibuat dengan lingara.manifest.

`ClientSpec`

Yang dibuat oleh langkah klien: sebuah klien API.

export interface ClientSpec {
    readonly kind: 'client';
    readonly name: string;
    readonly scopes: readonly Scope[];
    readonly redirectUris?: readonly string[];
}

kind ('client') — Selalu "client".
name (string) — Nama klien.
scopes (readonly Scope[]) — Izin yang diminta klien.
redirectUris? (readonly string[]) — URI pengalihan klien, jika ada.

`SecretSpec`

Yang dibuat oleh langkah rahasia: rahasia baru untuk kliennya.

export interface SecretSpec {
    readonly kind: 'secret';
    readonly client: NodeHandle;
}

kind ('secret') — Selalu "secret".
client (NodeHandle) — Langkah klien tempat rahasia ini berada.

`WebhookSpec`

Yang dibuat oleh langkah webhook: sebuah titik akhir webhook.

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

kind ('webhook') — Selalu "webhook".
client (NodeHandle) — Langkah klien tempat webhook ini berada.
url (string) — Alamat tujuan pengiriman peristiwa.
events (readonly string[]) — Jenis peristiwa yang dikirimkan.

`AppSpec`

Yang dibuat oleh langkah aplikasi: aplikasi yang menampilkan kartu di dalam Lingara.

export interface AppSpec {
    readonly kind: 'app';
    readonly client: NodeHandle;
    readonly manifest: Manifest;
}

kind ('app') — Selalu "app".
client (NodeHandle) — Langkah klien tempat aplikasi ini berada.
manifest (Manifest) — Manifest aplikasi.

`Manifest`

Manifest aplikasi dalam bentuk kawatnya, sebagaimana disimpan server.

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) — Selalu 1.
default_locale (string) — Lokal yang ditampilkan ketika lokal pelajar sendiri tidak memiliki entri.
name (Readonly<Record<string, string>>) — Nama aplikasi, per kode lokal.
description (Readonly<Record<string, string>>) — Satu kalimat tentang aplikasi, per kode lokal.
render_url (string) — Alamat HTTPS tempat Lingara meminta kartu aplikasi.
slots (readonly AppSlot[]) — Tempat kartu aplikasi dapat muncul.
context (readonly ContextSlice[]) — Bagian konteks yang diterima aplikasi.
scopes (readonly Scope[]) — Izin yang diminta aplikasi dari pelajar.
tutor_note (boolean) — Apakah aplikasi boleh meninggalkan catatan untuk tutor.

`Spec`

Spec apa pun yang dikembalikan fungsi pembantu. Skrip mengembalikan tepat satu.

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

`Upstream`

Keluaran setiap langkah hulu langsung, menurut handle.

export type Upstream = Readonly<Record<NodeHandle, Spec & {
    readonly handle: NodeHandle;
}>>;

`ClientInput`

Masukan langkah klien: kolom-kolomnya, yang merupakan opsi lingara.client.

export interface ClientInput {
    readonly name: string;
    readonly scopes: readonly Scope[];
    readonly redirectUris?: readonly string[];
    readonly upstream: Upstream;
}

name (string) — Nama klien.
scopes (readonly Scope[]) — Izin yang diminta klien.
redirectUris? (readonly string[]) — URI pengalihan klien, jika langkah memilikinya.
upstream (Upstream) — Keluaran setiap langkah hulu langsung.

`SecretInput`

Masukan langkah rahasia. client adalah satu-satunya langkah klien yang tersambung ke langkah ini.

export interface SecretInput {
    readonly client: NodeHandle;
    readonly upstream: Upstream;
}

client (NodeHandle) — Langkah klien yang tersambung ke langkah ini.
upstream (Upstream) — Keluaran setiap langkah hulu langsung.

`WebhookInput`

Masukan langkah webhook: kolom-kolomnya, ditambah klien yang tersambung.

export interface WebhookInput {
    readonly client: NodeHandle;
    readonly url: string;
    readonly events: readonly string[];
    readonly upstream: Upstream;
}

client (NodeHandle) — Langkah klien yang tersambung ke langkah ini.
url (string) — Alamat yang disebutkan kolom-kolom langkah.
events (readonly string[]) — Jenis peristiwa yang disebutkan kolom-kolom langkah.
upstream (Upstream) — Keluaran setiap langkah hulu langsung.

`AppInput`

Masukan langkah aplikasi: kolom-kolom manifest-nya, ditambah klien yang tersambung.

export interface AppInput {
    readonly client: NodeHandle;
    readonly manifest: ManifestOptions;
    readonly upstream: Upstream;
}

client (NodeHandle) — Langkah klien yang tersambung ke langkah ini.
manifest (ManifestOptions) — Manifest yang dijelaskan kolom-kolom langkah.
upstream (Upstream) — Keluaran setiap langkah hulu langsung.

`InputFor`

Masukan yang diterima skrip dari jenis langkah tertentu.

export type InputFor<K extends Spec['kind']> = K extends 'client' ? ClientInput : K extends 'secret' ? SecretInput : K extends 'webhook' ? WebhookInput : AppInput;

`LingaraV1`

Fungsi pembantu yang dipanggil skrip. Masing-masing mengembalikan spec yang dibekukan, dan opsi dengan tipe yang salah akan melempar TypeError yang menyebut namanya.

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') — Selalu "v1".
client(options: ClientOptions): ClientSpec — Sebuah klien API.
secret(client: NodeHandle): SecretSpec — Rahasia baru untuk sebuah langkah klien.
webhook(options: WebhookOptions): WebhookSpec — Titik akhir webhook pada sebuah langkah klien.
app(options: AppOptions): AppSpec — Aplikasi pada sebuah langkah klien.
manifest(options: ManifestOptions): Manifest — Manifest dalam bentuk kawatnya, dengan opsi yang dibiarkan opsional oleh v1 sudah terisi.

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`

Skrip sebuah langkah adalah isi dari fungsi ini: 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;

Lihat juga

Autentikasi