@layla-network/sdk 0.1.0 → 0.1.1

package/dist/index.d.cts

@@ -1,61 +1,128 @@
 /**
- * LaylaSDK
- * --------
- * A web-side client (runs INSIDE the Layla WebView) that talks to the native
- * Layla app over the React Native WebView bridge, exposed through an API that
- * mirrors the OpenAI JavaScript SDK so existing OpenAI code ports with minimal
- * friction.
+ * protocol.ts
+ * -----------
+ * The native wire contract: every type that must stay in sync with the React
+ * Native host. If the native side changes, this is the file that changes with
+ * it. Nothing here has runtime behaviour — it's pure types plus the one global
+ * declaration for the bridge channel.
  *
- * The native host runs the model and streams tokens back; this SDK turns that
- * event stream into the OpenAI shapes (`ChatCompletion`, `ChatCompletionChunk`)
- * and an async-iterable stream.
- *
- * Wire protocol (must match the React Native host):
- *   Web -> RN : { cmd: 'send_message', data: LaylaChatMessage[] }
- *   RN -> Web : { event: 'on_message',     data: { msg, delta } }   (per token)
- *               { event: 'on_message_end' }                          (end)
- *               { event: 'on_error',       data: { message } }       (error)
- *
- * Quick start:
- *
- *   import { LaylaSDK } from './layla-sdk';
- *   const layla = new LaylaSDK();
- *
- *   // Streaming (async iteration) -- the OpenAI way:
- *   const stream = await layla.chat.completions.create({
- *     messages: [{ role: 'user', content: 'Hello' }],
- *     stream: true,
- *   });
- *   for await (const chunk of stream) {
- *     process_token(chunk.choices[0]?.delta?.content ?? '');
- *   }
- *
- *   // Streaming (event helper) -- maps cleanly onto Layla's delta/snapshot:
- *   const s = layla.chat.completions.stream({
- *     messages: [{ role: 'user', content: 'Hello' }],
- *   });
- *   s.on('content', (delta, snapshot) => render(snapshot));
- *   const final = await s.finalContent();
- *
- *   // Non-streaming -- resolves once when the model is done:
- *   const completion = await layla.chat.completions.create({
- *     messages: [{ role: 'user', content: 'Hello' }],
- *   });
- *   console.log(completion.choices[0].message.content);
+ * Adding a one-shot endpoint touches this file in two spots: a command in
+ * `LaylaApiRequest` and a response in `LaylaApiEvent`.
  */
-type LaylaChatRole = 'system' | 'user' | 'assistant' | 'tool' | 'function';
+declare global {
+    interface Window {
+        /** Injected by the React Native <WebView> when its `onMessage` prop is set. */
+        ReactNativeWebView?: {
+            postMessage: (message: string) => void;
+        };
+    }
+}
+type LaylaChatRole = 'system' | 'user' | 'assistant';
 /** An OpenAI-style chat message. */
 interface LaylaChatMessage {
     role: LaylaChatRole;
     content: string | null;
     name?: string;
 }
-/** Web -> RN command. */
-interface LaylaApiMessage {
+interface LaylaCharacter {
+    id: string;
+    data: TavernCardV2;
+}
+/**
+ * A character card following the Character Card V2 spec (`chara_card_v2`), as
+ * returned by the host's `get_characters` handler. If your app already exports
+ * its own `TavernCardV2`, prefer importing that — they describe the same shape.
+ */
+interface TavernCardV2 {
+    spec: 'chara_card_v2';
+    spec_version: '2.0';
+    data: {
+        name: string;
+        description: string;
+        personality: string;
+        scenario: string;
+        first_mes: string;
+        mes_example: string;
+        creator_notes: string;
+        system_prompt: string;
+        post_history_instructions: string;
+        alternate_greetings: string[];
+        character_book?: TavernCharacterBook;
+        tags: string[];
+        creator: string;
+        character_version: string;
+        extensions: Record<string, unknown>;
+    };
+}
+interface TavernCharacterBook {
+    name?: string;
+    description?: string;
+    scan_depth?: number;
+    token_budget?: number;
+    recursive_scanning?: boolean;
+    extensions: Record<string, unknown>;
+    entries: Array<{
+        keys: string[];
+        content: string;
+        extensions: Record<string, unknown>;
+        enabled: boolean;
+        insertion_order: number;
+        case_sensitive?: boolean;
+        name?: string;
+        priority?: number;
+        id?: number;
+        comment?: string;
+        selective?: boolean;
+        secondary_keys?: string[];
+        constant?: boolean;
+        position?: 'before_char' | 'after_char';
+    }>;
+}
+/** Send a conversation for completion (a streaming request). */
+interface LaylaApiSendMessage {
     cmd: 'send_message';
     data: LaylaChatMessage[];
 }
-/** RN -> Web: a streamed token. `msg` is the full snapshot, `delta` is new. */
+/** Ask the host for the list of available character cards (a one-shot request). */
+interface LaylaApiGetCharacters {
+    cmd: 'get_characters';
+}
+/** Ask the host for a character image identified by <characterId>. */
+interface LaylaApiGetCharacterImage {
+    cmd: 'get_character_image';
+    data: {
+        character_id: string;
+    };
+}
+/**
+ * Stop the in-flight generation.
+ *
+ * Native contract: on receiving this, the host MUST stop the current
+ * generation and then emit a normal `on_message_end` (or `on_error`) for that
+ * request. That terminating event is the acknowledgement the SDK waits for
+ * before starting the next queued request, so it must always be sent — even
+ * when generation was cut short. Tokens already posted before the host
+ * processes the cancel are harmless; the SDK swallows them.
+ */
+interface LaylaApiCancel {
+    cmd: 'cancel';
+}
+/**
+ * Ask the host to generate an image based on the provided prompt. The host should respond with an `on_generate_image_response` event containing the generated image encoded in base64 (including the data URI prefix).
+ */
+interface LaylaApiGenerateImage {
+    cmd: 'generate_image';
+    data: {
+        prompt: string;
+    };
+}
+/**
+ * A request command (anything that opens a job and expects events back).
+ * Add new one-shot commands here. `cancel` is not a request — it's a control
+ * signal for an already-open job — so it lives outside this union.
+ */
+type LaylaApiRequest = LaylaApiSendMessage | LaylaApiGetCharacters | LaylaApiGetCharacterImage | LaylaApiCancel | LaylaApiGenerateImage;
+/** A streamed token. `msg` is the full snapshot, `delta` is new. */
 interface LaylaApiEvent_onMsg {
     event: 'on_message';
     data: {
@@ -63,18 +130,133 @@ interface LaylaApiEvent_onMsg {
         delta: string;
     };
 }
-/** RN -> Web: stream finished. */
+/** Stream finished. */
 interface LaylaApiEvent_onMsgEnd {
     event: 'on_message_end';
 }
-/** RN -> Web: error. */
+/** Error. Terminates whatever request is in flight, of any kind. */
 interface LaylaApiEvent_onError {
     event: 'on_error';
     data: {
         message: string;
     };
 }
-type LaylaApiEvent = LaylaApiEvent_onMsg | LaylaApiEvent_onMsgEnd | LaylaApiEvent_onError;
+/** The character card list for a `get_characters` request. */
+interface LaylaApiEvent_onGetCharactersResponse {
+    event: 'on_get_characters_response';
+    data: LaylaCharacter[];
+}
+/** The character image for a `get_character_image` request, encoded in base64 (includes the data URI prefix) */
+interface LaylaApiEvent_onGetCharacterImageResponse {
+    event: 'on_get_character_image_response';
+    data: {
+        character_id: string;
+        image_data_base64: string | null;
+    } | null;
+}
+/**
+ * The generated image for a `generate_image` request, encoded in base64 (includes the data URI prefix). If `image_data_base64` is null, it indicates that there was an error during image generation.
+ */
+interface LaylaApiEvent_onGenerateImageResponse {
+    event: 'on_generate_image_response';
+    data: {
+        image_data_base64: string | null;
+    } | null;
+}
+interface LaylaApiEvent_onGenerateImageProgress {
+    event: 'on_generate_image_progress';
+    data: {
+        status: string;
+        steps: number;
+        total_steps: number;
+    };
+}
+type LaylaApiEvent = LaylaApiEvent_onMsg | LaylaApiEvent_onMsgEnd | LaylaApiEvent_onError | LaylaApiEvent_onGetCharactersResponse | LaylaApiEvent_onGetCharacterImageResponse | LaylaApiEvent_onGenerateImageResponse | LaylaApiEvent_onGenerateImageProgress;
+
+/**
+ * errors.ts
+ * ---------
+ * The error hierarchy. Everything the SDK throws or rejects with extends
+ * `LaylaError`, so consumers can `catch (e) { if (e instanceof LaylaError) ... }`.
+ */
+declare class LaylaError extends Error {
+    constructor(message: string);
+}
+declare class LaylaAbortError extends LaylaError {
+    constructor(message?: string);
+}
+declare class LaylaBridgeUnavailableError extends LaylaError {
+    constructor();
+}
+
+/**
+ * internal/one-shot.ts
+ * --------------------
+ * The reusable primitive for every request/response endpoint.
+ *
+ * `OneShotRequest` is a Deferred wearing the BridgeSink interface: you give it
+ * the command to send, the name of the event that answers it, and how to pull
+ * the result out of that event. It resolves on the response event and rejects
+ * on error/abort. The `oneShot` helper wires up the AbortSignal and enqueues.
+ * Adding a new endpoint needs neither a new class here nor any bridge change.
+ */
+
+/** Shared options for one-shot requests. */
+interface RequestOptions {
+    /** Abort the request from the consumer side. */
+    signal?: AbortSignal;
+}
+
+/**
+ * internal/bridge.ts
+ * ------------------
+ * The single low-level transport over the WebView message channel.
+ *
+ * Owns one global `message` listener and serialises requests, because the
+ * current protocol has no request id to correlate concurrent jobs. Every job —
+ * chat completions and one-shot requests alike — flows through the same queue
+ * and single active slot, so a one-shot waits behind an in-flight generation
+ * rather than racing it.
+ *
+ * The bridge is intentionally event-agnostic: it routes every parsed event to
+ * the active job's sink and lets the sink say when it's done. The only event it
+ * special-cases is `on_error`, which terminates any job. New request/response
+ * shapes therefore need NO changes here. If you add an `id` field to both
+ * `LaylaApiMessage` and `LaylaApiEvent`, this is the one place that would change
+ * to support true concurrency.
+ */
+
+/**
+ * Everything the bridge needs from a job. A sink consumes the inbound event
+ * stream for the active request and reports when the request is complete.
+ */
+interface BridgeSink {
+    /**
+     * Handle one parsed RN->web event (never `on_error`; the bridge routes that
+     * to `fail`). Return `true` when this event terminates the request, so the
+     * bridge can free the active slot and pump the next job. Return `false` for
+     * events that are not yours or that don't end the request.
+     */
+    accept(event: LaylaApiEvent): boolean;
+    /** Terminate the request with an error (host error, abort, missing bridge). */
+    fail(err: Error): void;
+    isClosed(): boolean;
+    /**
+     * Optional: the message to post to the host if this request is cancelled
+     * while in flight. Streaming generation returns `{ cmd: 'cancel' }`; one-shot
+     * requests return nothing (there's no generation to stop — they just close
+     * locally and the host's eventual response frees the slot).
+     */
+    cancelMessage?(): LaylaApiRequest | null;
+}
+
+/**
+ * resources/chat/types.ts
+ * -----------------------
+ * The OpenAI-shaped output and parameter types for chat completions. These are
+ * the SDK's public surface for chat, not the native wire protocol.
+ */
+
 interface ChatCompletionChunk {
     id: string;
     object: 'chat.completion.chunk';
@@ -121,31 +303,21 @@ interface ChatCompletionCreateParamsNonStreaming extends ChatCompletionCreatePar
 interface ChatCompletionCreateParamsStreaming extends ChatCompletionCreateParamsBase {
     stream: true;
 }
-declare class LaylaError extends Error {
-    constructor(message: string);
-}
-declare class LaylaAbortError extends LaylaError {
-    constructor(message?: string);
-}
-declare class LaylaBridgeUnavailableError extends LaylaError {
-    constructor();
-}
-declare global {
-    interface Window {
-        ReactNativeWebView?: {
-            postMessage: (message: string) => void;
-        };
-    }
-}
-/** Implemented by ChatCompletionStream; the bridge drives it. */
-interface StreamSink {
-    handleDelta(delta: string, snapshot: string): void;
-    handleEnd(): void;
-    handleError(err: Error): void;
-    isClosed(): boolean;
-}
+
+/**
+ * resources/chat/stream.ts
+ * ------------------------
+ * ChatCompletionStream: the user-facing streaming object.
+ *
+ * - Async-iterable of ChatCompletionChunk (the OpenAI `for await` pattern)
+ * - Event emitter: 'content' | 'chunk' | 'end' | 'error'
+ * - Convenience: finalContent(), finalChatCompletion()
+ *
+ * Implements BridgeSink so the bridge can drive it from `on_message*` events.
+ */
+
 type Listener = (...args: any[]) => void;
-declare class ChatCompletionStream implements StreamSink, AsyncIterable<ChatCompletionChunk> {
+declare class ChatCompletionStream implements BridgeSink, AsyncIterable<ChatCompletionChunk> {
     private readonly id;
     private readonly created;
     private readonly model;
@@ -165,12 +337,14 @@ declare class ChatCompletionStream implements StreamSink, AsyncIterable<ChatComp
     on(event: 'error', listener: (err: Error) => void): this;
     off(event: string, listener: Listener): this;
     private emit;
-    handleDelta(delta: string, snapshot: string): void;
-    handleEnd(): void;
-    handleError(err: Error): void;
+    accept(event: LaylaApiEvent): boolean;
+    fail(err: Error): void;
     isClosed(): boolean;
+    cancelMessage(): LaylaApiCancel;
     /** Abort from the consumer side. */
     abort(reason?: unknown): void;
+    private handleDelta;
+    private handleEnd;
     next(): Promise<IteratorResult<ChatCompletionChunk>>;
     /** Breaking out of `for await` aborts the request, like the OpenAI SDK. */
     return(): Promise<IteratorResult<ChatCompletionChunk>>;
@@ -183,6 +357,15 @@ declare class ChatCompletionStream implements StreamSink, AsyncIterable<ChatComp
     private makeChunk;
     private buildCompletion;
 }
+
+/**
+ * resources/chat/index.ts
+ * -----------------------
+ * The chat resource: `layla.chat.completions.create(...)` / `.stream(...)`,
+ * mirroring the OpenAI SDK shape. Re-exports the public chat types and the
+ * stream class for the package barrel.
+ */
+
 declare class Completions {
     create(body: ChatCompletionCreateParamsNonStreaming): Promise<ChatCompletion>;
     create(body: ChatCompletionCreateParamsStreaming): Promise<ChatCompletionStream>;
@@ -196,13 +379,60 @@ declare class Completions {
 declare class Chat {
     readonly completions: Completions;
 }
+
+/**
+ * resources/images.ts
+ * -----------------------
+ * The images resource: `layla.images.generateImage()`.
+ *
+ */
+
+declare class Images {
+    /**
+     * Ask the native host to generate an image. Resolves to a ready-to-use base64 image src string, or null if the character has no image
+     */
+    generateImage(prompt: string, onProgress: (status: string, step: number, total_step: number) => void, options?: RequestOptions): Promise<string | null>;
+}
+
+/**
+ * resources/characters.ts
+ * -----------------------
+ * The characters resource: `layla.characters.list()`.
+ *
+ * This is the template for any one-shot endpoint — a single `oneShot(...)` call
+ * giving the command, the response event name, and how to read the payload.
+ * Copy this file to add a new resource (e.g. `settings.ts` -> `Settings.get`).
+ */
+
+declare class Characters {
+    /**
+     * Ask the native host for the available character cards. Resolves once with
+     * the host's `on_get_characters_response` payload, or rejects on error/abort.
+     */
+    list(options?: RequestOptions): Promise<LaylaCharacter[]>;
+    /**
+     * Ask the native host for a character portrait. Resolves to a ready-to-use
+     * image src string, or null when the character has no image.
+     */
+    getImage(characterId: string, options?: RequestOptions): Promise<string | null>;
+}
+
+/**
+ * client.ts
+ * ---------
+ * The top-level client. Composes the resources into the object users interact
+ * with. Add a new resource by importing it and assigning it a readonly field.
+ */
+
 interface LaylaSDKOptions {
     /** Reserved for future use (e.g. default model). */
     model?: string;
 }
 declare class LaylaSDK {
     readonly chat: Chat;
+    readonly characters: Characters;
+    readonly images: Images;
     constructor(_options?: LaylaSDKOptions);
 }
 
-export { type ChatCompletion, type ChatCompletionChunk, type ChatCompletionCreateParamsBase, type ChatCompletionCreateParamsNonStreaming, type ChatCompletionCreateParamsStreaming, ChatCompletionStream, LaylaSDK as Layla, LaylaAbortError, type LaylaApiEvent, type LaylaApiEvent_onError, type LaylaApiEvent_onMsg, type LaylaApiEvent_onMsgEnd, type LaylaApiMessage, LaylaBridgeUnavailableError, type LaylaChatMessage, type LaylaChatRole, LaylaError, LaylaSDK, type LaylaSDKOptions, LaylaSDK as default };
+export { type ChatCompletion, type ChatCompletionChunk, type ChatCompletionCreateParamsBase, type ChatCompletionCreateParamsNonStreaming, type ChatCompletionCreateParamsStreaming, ChatCompletionStream, Images, LaylaSDK as Layla, LaylaAbortError, type LaylaApiCancel, type LaylaApiEvent, type LaylaApiEvent_onError, type LaylaApiEvent_onGenerateImageResponse, type LaylaApiEvent_onGetCharacterImageResponse, type LaylaApiEvent_onGetCharactersResponse, type LaylaApiEvent_onMsg, type LaylaApiEvent_onMsgEnd, type LaylaApiGenerateImage, type LaylaApiGetCharacterImage, type LaylaApiGetCharacters, type LaylaApiRequest, type LaylaApiSendMessage, LaylaBridgeUnavailableError, type LaylaCharacter, type LaylaChatMessage, type LaylaChatRole, LaylaError, LaylaSDK, type LaylaSDKOptions, type RequestOptions, type TavernCardV2, type TavernCharacterBook, LaylaSDK as default };