Lingara डेवलपर दस्तावेज़

यह पेज अंग्रेज़ी से अनुवादित है। अगर दोनों में अंतर हो, तो अंग्रेज़ी पेज सही है। अंग्रेज़ी पेज पढ़ें

एक कनेक्शन चरणों से बनता है, और किसी भी चरण में एक स्क्रिप्ट हो सकती है। किसी चरण की स्क्रिप्ट एक फ़ंक्शन का बॉडी होती है। उसे दो मान मिलते हैं: lingara, इस पेज पर बताया गया API, और input, चरण के अपने फ़ील्ड, साथ में उसका क्लाइंट और उससे पहले जुड़े चरण। input का प्रकार चरण के प्रकार पर निर्भर करता है, इसलिए किसी Webhook चरण की स्क्रिप्ट Webhook चरण के फ़ील्ड पढ़ती है। स्क्रिप्ट ठीक एक ऑब्जेक्ट लौटाती है, जो नीचे दिए गए हेल्परों में से किसी एक से बना होता है।

स्क्रिप्ट कभी कोई सीक्रेट नहीं देखती। जहाँ किसी चरण को अपने क्लाइंट की ज़रूरत होती है, उसे एक हैंडल मिलता है, जैसे input.client, और हेल्पर उस हैंडल को दर्ज करता है। कनेक्शन लागू करते समय Lingara असली मान भरता है।

स्क्रिप्ट को क्या नहीं करना चाहिए

स्क्रिप्ट आपके अपने ब्राउज़र में, बिना नेटवर्क और बिना स्टोरेज वाले एक वर्कर में चलती है। उस पर ये सीमाएँ लागू होती हैं:

• यह 1 सेकंड के भीतर पूरी हो जाती है।
• इसके लौटाए किसी स्ट्रिंग की लंबाई ज़्यादा से ज़्यादा 2048 अक्षर होती है।
• इसकी लौटाई किसी सूची में ज़्यादा से ज़्यादा 64 आइटम होते हैं।
• इसका पूरा नतीजा ज़्यादा से ज़्यादा 16 KiB होता है।

जो स्क्रिप्ट कोई सीमा तोड़ती है, कोई त्रुटि फेंकती है, या किसी एक हेल्पर के नतीजे के अलावा कुछ और लौटाती है, उसका चरण विफल हो जाता है, और “जांचें” दिखाता है कि कौन-सा चरण और क्यों।

संस्करण का वादा

इस पेज पर सब कुछ lingara.v1 है। v1 के भीतर API सिर्फ़ बढ़ता है: कोई नया हेल्पर, कोई नया वैकल्पिक विकल्प या कोई नया चरण प्रकार आ सकता है, लेकिन आज आप जो कुछ भी इस्तेमाल कर सकते हैं, उसे न हटाया जाता है, न उसका नाम बदला जाता है और न उसे सीमित किया जाता है। जो बदलाव किसी स्क्रिप्ट को तोड़ देगा, वह इसके बगल में एक नया संस्करण होगा, और v1 जैसा है वैसा ही रहेगा।

घोषणाएँ

नीचे दी गई हर घोषणा उसी फ़ाइल से बनाई गई है जिसके आधार पर स्क्रिप्ट एडिटर ऑटो-कम्प्लीट करता है।

NodeHandle

किसी दूसरे चरण की id, जैसे "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[]) — क्लाइंट के रीडायरेक्ट 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

कोई भी स्पेक जो कोई हेल्पर लौटाता है। स्क्रिप्ट ठीक एक लौटाती है।

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[]) — क्लाइंट के रीडायरेक्ट 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

वे हेल्पर जिन्हें स्क्रिप्ट कॉल करती है। हर एक एक फ़्रोज़न स्पेक लौटाता है, और गलत प्रकार का विकल्प उसका नाम बताने वाली 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;