Lingara geliştirici belgeleri

Bu sayfa İngilizceden çevrilmiştir. İkisi arasında fark varsa İngilizce sayfa doğrudur. İngilizce sayfayı oku

Bir bağlantı adımlardan oluşur ve her adım bir betik taşıyabilir. Bir adımın betiği bir fonksiyonun gövdesidir. İki değer alır: lingara, bu sayfadaki API, ve input, adımın kendi alanları ile birlikte istemcisi ve kendisinden önce bağlanan adımlar. input türü adımın çeşidine bağlıdır; bu yüzden bir webhook adımının betiği bir webhook adımının alanlarını okur. Betik, aşağıdaki yardımcılardan biriyle oluşturulmuş tam olarak bir nesne döndürür.

Bir betik hiçbir zaman bir gizli anahtar görmez. Bir adımın istemcisine ihtiyaç duyduğu yerde, input.client gibi bir tanıtıcı alır ve yardımcı bu tanıtıcıyı kaydeder. Gerçek değerleri, bağlantıyı uyguladığınızda Lingara doldurur.

Bir betiğin yapmaması gerekenler

Bir betik kendi tarayıcınızda, ağı ve depolaması olmayan bir worker içinde çalışır. Şu sınırlara tabidir:

• 1 saniye içinde biter.
• Döndürdüğü bir dize en fazla 2048 karakter uzunluğundadır.
• Döndürdüğü bir listede en fazla 64 öğe bulunur.
• Sonucunun tamamı en fazla 16 KiB’tır.

Bir sınırı aşan, hata fırlatan ya da tek bir yardımcının sonucundan başka bir şey döndüren betik, adımını başarısız kılar ve “Kontrol et” hangi adım olduğunu ve nedenini gösterir.

Sürüm sözü

Bu sayfadaki her şey lingara.v1 kapsamındadır. v1 içinde API yalnızca büyür: yeni bir yardımcı, yeni bir isteğe bağlı seçenek ya da yeni bir adım çeşidi eklenebilir, ancak bugün kullanabildiğiniz hiçbir şey kaldırılmaz, yeniden adlandırılmaz veya daraltılmaz. Bir betiği bozacak bir değişiklik, bunun yanında yeni bir sürüm olur ve v1 olduğu gibi kalır.

Bildirimler

Aşağıdaki her bildirim, betik düzenleyicisinin tamamlamada kullandığı aynı dosyadan üretilir.

NodeHandle

Başka bir adımın kimliği, örneğin "n1". Bağımlı bir adım, istemcisini tanıtıcıyla adlandırır.

export type NodeHandle = string;

Scope

Bir API istemcisinin sahip olabileceği bir izin. Hesabınızın hangilerini kullanabileceğine sunucu karar verir.

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 uygulamasında bir uygulamanın kartının görünebileceği bir yer.

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

ContextSlice

Öğrencinin bağlamının, bir uygulamanın almak isteyebileceği bir parçası.

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

ClientOptions

lingara.client için seçenekler.

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

• name (string) — İstemcinin adı, Geliştirici araçlarının gösterdiği biçimde.
• scopes (readonly Scope[]) — İstemcinin istediği izinler.
• redirectUris? (readonly string[]) — Yetkilendirme kodu akışının bir öğrenciyi geri gönderebileceği yerler. Sunucudan sunucuya bir istemci için boş bırakın.

WebhookOptions

lingara.webhook için seçenekler.

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

• client (NodeHandle) — Bu webhook’un ait olduğu istemci adımı: input.client.
• url (string) — Lingara’nın olayları teslim ettiği HTTPS adresi.
• events (readonly string[]) — Teslim edilecek olay türleri, örneğin "lesson_plan.ready".

ManifestOptions

lingara.manifest için camelCase seçenekler; yardımcı, manifestonun aktarım biçimini yazar.

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>>) — Uygulamanın adı: tek bir dize ya da yerel ayar kodu başına bir dize.
• description (string | Readonly<Record<string, string>>) — Uygulama hakkında bir cümle: tek bir dize ya da yerel ayar kodu başına bir dize.
• renderUrl (string) — Lingara’nın uygulamanın kartını istediği HTTPS adresi.
• slots (readonly AppSlot[]) — Uygulamanın kartının görünebileceği yerler.
• context? (readonly ContextSlice[]) — Uygulamanın aldığı bağlam parçaları. Varsayılan olarak hiçbiri.
• scopes? (readonly Scope[]) — Uygulamanın öğrenciden istediği izinler. Varsayılan olarak hiçbiri.
• tutorNote? (boolean) — Uygulamanın öğretmene not bırakıp bırakamayacağı. Varsayılan false.
• defaultLocale? (string) — Düz dize olarak verilen bir adın veya açıklamanın altında saklandığı yerel ayar. Varsayılan "en".

AppOptions

lingara.app için seçenekler.

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

• client (NodeHandle) — Bu uygulamanın ait olduğu istemci adımı: input.client.
• manifest (Manifest) — lingara.manifest ile oluşturulmuş uygulama manifestosu.

ClientSpec

Bir istemci adımının oluşturduğu şey: bir API istemcisi.

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

• kind ('client') — Her zaman "client".
• name (string) — İstemcinin adı.
• scopes (readonly Scope[]) — İstemcinin istediği izinler.
• redirectUris? (readonly string[]) — Varsa istemcinin yönlendirme URI’leri.

SecretSpec

Bir gizli anahtar adımının oluşturduğu şey: istemcisi için yeni bir gizli anahtar.

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

• kind ('secret') — Her zaman "secret".
• client (NodeHandle) — Gizli anahtarın ait olduğu istemci adımı.

WebhookSpec

Bir webhook adımının oluşturduğu şey: bir webhook uç noktası.

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

• kind ('webhook') — Her zaman "webhook".
• client (NodeHandle) — Webhook’un ait olduğu istemci adımı.
• url (string) — Olayların teslim edildiği adres.
• events (readonly string[]) — Teslim edilen olay türleri.

AppSpec

Bir uygulama adımının oluşturduğu şey: Lingara içinde bir kart çizen bir uygulama.

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

• kind ('app') — Her zaman "app".
• client (NodeHandle) — Uygulamanın ait olduğu istemci adımı.
• manifest (Manifest) — Uygulamanın manifestosu.

Manifest

Sunucunun sakladığı biçimiyle, aktarım biçimindeki bir uygulama manifestosu.

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) — Her zaman 1.
• default_locale (string) — Öğrencinin kendi yerel ayarı için bir giriş olmadığında gösterilen yerel ayar.
• name (Readonly<Record<string, string>>) — Yerel ayar kodu başına uygulamanın adı.
• description (Readonly<Record<string, string>>) — Yerel ayar kodu başına uygulama hakkında bir cümle.
• render_url (string) — Lingara’nın uygulamanın kartını istediği HTTPS adresi.
• slots (readonly AppSlot[]) — Uygulamanın kartının görünebileceği yerler.
• context (readonly ContextSlice[]) — Uygulamanın aldığı bağlam parçaları.
• scopes (readonly Scope[]) — Uygulamanın öğrenciden istediği izinler.
• tutor_note (boolean) — Uygulamanın öğretmene not bırakıp bırakamayacağı.

Spec

Bir yardımcının döndürdüğü herhangi bir tanım. Bir betik tam olarak bir tane döndürür.

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

Upstream

Doğrudan önceki her adımın çıktısı, tanıtıcıya göre.

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

ClientInput

Bir istemci adımının girdisi: alanları, yani lingara.client seçenekleri.

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

• name (string) — İstemcinin adı.
• scopes (readonly Scope[]) — İstemcinin istediği izinler.
• redirectUris? (readonly string[]) — Adımda varsa istemcinin yönlendirme URI’leri.
• upstream (Upstream) — Doğrudan önceki her adımın çıktısı.

SecretInput

Bir gizli anahtar adımının girdisi. client, bu adıma bağlanan tek istemci adımıdır.

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

• client (NodeHandle) — Bu adıma bağlanan istemci adımı.
• upstream (Upstream) — Doğrudan önceki her adımın çıktısı.

WebhookInput

Bir webhook adımının girdisi: alanları ve bağlanan istemci.

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

• client (NodeHandle) — Bu adıma bağlanan istemci adımı.
• url (string) — Adımın alanlarında belirtilen adres.
• events (readonly string[]) — Adımın alanlarında belirtilen olay türleri.
• upstream (Upstream) — Doğrudan önceki her adımın çıktısı.

AppInput

Bir uygulama adımının girdisi: manifesto alanları ve bağlanan istemci.

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

• client (NodeHandle) — Bu adıma bağlanan istemci adımı.
• manifest (ManifestOptions) — Adımın alanlarının tarif ettiği manifesto.
• upstream (Upstream) — Doğrudan önceki her adımın çıktısı.

InputFor

Belirli bir adım çeşidindeki bir betiğin aldığı girdi.

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

LingaraV1

Bir betiğin çağırdığı yardımcılar. Her biri dondurulmuş bir tanım döndürür ve yanlış türde bir seçenek, o seçeneği adlandıran bir TypeError fırlatır.

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') — Her zaman "v1".
• client(options: ClientOptions): ClientSpec — Bir API istemcisi.
• secret(client: NodeHandle): SecretSpec — Bir istemci adımı için yeni bir gizli anahtar.
• webhook(options: WebhookOptions): WebhookSpec — Bir istemci adımında bir webhook uç noktası.
• app(options: AppOptions): AppSpec — Bir istemci adımında bir uygulama.
• manifest(options: ManifestOptions): Manifest — Aktarım biçiminde bir manifesto; v1’in isteğe bağlı bıraktığı seçenekler doldurulmuş olarak.

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

Bir adımın betiği bu fonksiyonun gövdesidir: 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;