@lessly/sdk-app 48.0.4 → 49.0.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { G as GeneratedClient } from './client.gen-BsjxuDLy.cjs';
+import { G as GeneratedClient } from './client.gen-CLRsCNvG.cjs';
 
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 type ParamIn = 'path' | 'query' | 'body';
@@ -12,9 +12,61 @@ interface Binding {
     readOnly: boolean;
     params?: ParamSpec[];
 }
+/**
+ * The streaming counterpart of `Binding`: the upgrade route of a ws-bound tool. No method (an
+ * upgrade is always a GET) and no `readOnly` (a socket is neither a read nor a write — the tool's
+ * own description defines its framing).
+ */
+interface WsBinding {
+    path: string;
+    params?: ParamSpec[];
+}
 type ActionBindings = Record<string, Binding>;
 type ResourceBindings = Record<string, ActionBindings>;
 type BindingsMap = Record<string, ResourceBindings>;
+type WsActionBindings = Record<string, WsBinding>;
+type WsResourceBindings = Record<string, WsActionBindings>;
+type WsBindingsMap = Record<string, WsResourceBindings>;
+/** Close information, as delivered to every `onClose` subscriber. */
+interface StreamCloseInfo {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+/** Frame payload, exactly as the socket delivered it — never parsed by the SDK. */
+type StreamData = string | ArrayBufferLike | ArrayBufferView | Blob;
+/**
+ * The handle returned by `connectStream`. Deliberately small: no reconnection, no backoff, no
+ * heartbeat and no framing. A dropped connection surfaces once, through `onClose` with the close
+ * code; deciding whether and how to reconnect is the App's business, not the SDK's.
+ */
+interface LesslyStream {
+    /** Queued until the socket is OPEN, then flushed in order. Ignored once the stream is closed. */
+    send(data: StreamData): void;
+    close(code?: number, reason?: string): void;
+    /** Delivers `MessageEvent.data` as-is. Returns an unsubscribe function. */
+    onMessage(cb: (data: StreamData) => void): () => void;
+    /** Returns an unsubscribe function. */
+    onClose(cb: (info: StreamCloseInfo) => void): () => void;
+    /** The underlying socket's readyState (0 CONNECTING, 1 OPEN, 2 CLOSING, 3 CLOSED). */
+    readonly readyState: number;
+}
+/**
+ * What a generated `<tool>Connect` factory needs from the client: the ability to open a stream
+ * for a binding. `createLesslyApp`'s client implements it (see `LesslyClientBase`).
+ */
+interface LesslyStreamOpener {
+    openStream(binding: WsBinding, input?: Record<string, unknown>): LesslyStream;
+}
+/** The shape of `globalThis.WebSocket` this SDK relies on — injectable, like `fetch`. */
+type WebSocketCtor = new (url: string) => WebSocketLike;
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: StreamData): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, cb: (ev: never) => void): void;
+    removeEventListener(type: string, cb: (ev: never) => void): void;
+}
 interface LesslyAppOptions {
     /**
      * Absolute origin ("https://api.lessly.dev") or a path relative to the page
@@ -25,13 +77,30 @@ interface LesslyAppOptions {
     productId: string;
     getCsrfToken?: () => string | null | undefined;
     fetch?: typeof fetch;
+    /** Injectable WebSocket constructor for `connectStream`; defaults to `globalThis.WebSocket`. */
+    WebSocket?: WebSocketCtor;
 }
 
-interface LesslyClientBase {
+interface LesslyClientBase extends LesslyStreamOpener {
     call(toolName: string, input?: Record<string, unknown>): Promise<unknown>;
 }
 declare function createLesslyApp(opts: LesslyAppOptions): GeneratedClient & LesslyClientBase;
 
+/**
+ * Open the sanctioned streaming connection for a ws-bound tool.
+ *
+ * Session cookies ride the upgrade automatically, so this sends NOTHING extra: no CSRF token (an
+ * upgrade is not an HTTP mutation) and no product header — a browser WebSocket cannot set headers
+ * at all, and the gateway's upgrade path authenticates from the session alone.
+ *
+ * Params are placed exactly as for a GET request: `:token` segments are substituted into the
+ * path, everything else becomes a query parameter. A param declared `in: 'body'` has no meaning
+ * on an upgrade and is treated as a query parameter rather than silently dropped.
+ *
+ * There is no reconnection, backoff or heartbeat logic here on purpose (see `LesslyStream`).
+ */
+declare function connectStream(opts: LesslyAppOptions, binding: WsBinding, input?: Record<string, unknown>): LesslyStream;
+
 declare class LesslyApiError extends Error {
     readonly status: number;
     readonly code: string | null;
@@ -39,4 +108,4 @@ declare class LesslyApiError extends Error {
     constructor(status: number, code: string | null, message: string, body: unknown);
 }
 
-export { type Binding, type BindingsMap, GeneratedClient, type HttpMethod, LesslyApiError, type LesslyAppOptions, type LesslyClientBase, type ParamIn, type ParamSpec, createLesslyApp };
+export { type Binding, type BindingsMap, GeneratedClient, type HttpMethod, LesslyApiError, type LesslyAppOptions, type LesslyClientBase, type LesslyStream, type LesslyStreamOpener, type ParamIn, type ParamSpec, type StreamCloseInfo, type StreamData, type WebSocketCtor, type WebSocketLike, type WsBinding, type WsBindingsMap, connectStream, createLesslyApp };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { G as GeneratedClient } from './client.gen-BsjxuDLy.js';
+import { G as GeneratedClient } from './client.gen-CLRsCNvG.js';
 
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 type ParamIn = 'path' | 'query' | 'body';
@@ -12,9 +12,61 @@ interface Binding {
     readOnly: boolean;
     params?: ParamSpec[];
 }
+/**
+ * The streaming counterpart of `Binding`: the upgrade route of a ws-bound tool. No method (an
+ * upgrade is always a GET) and no `readOnly` (a socket is neither a read nor a write — the tool's
+ * own description defines its framing).
+ */
+interface WsBinding {
+    path: string;
+    params?: ParamSpec[];
+}
 type ActionBindings = Record<string, Binding>;
 type ResourceBindings = Record<string, ActionBindings>;
 type BindingsMap = Record<string, ResourceBindings>;
+type WsActionBindings = Record<string, WsBinding>;
+type WsResourceBindings = Record<string, WsActionBindings>;
+type WsBindingsMap = Record<string, WsResourceBindings>;
+/** Close information, as delivered to every `onClose` subscriber. */
+interface StreamCloseInfo {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+/** Frame payload, exactly as the socket delivered it — never parsed by the SDK. */
+type StreamData = string | ArrayBufferLike | ArrayBufferView | Blob;
+/**
+ * The handle returned by `connectStream`. Deliberately small: no reconnection, no backoff, no
+ * heartbeat and no framing. A dropped connection surfaces once, through `onClose` with the close
+ * code; deciding whether and how to reconnect is the App's business, not the SDK's.
+ */
+interface LesslyStream {
+    /** Queued until the socket is OPEN, then flushed in order. Ignored once the stream is closed. */
+    send(data: StreamData): void;
+    close(code?: number, reason?: string): void;
+    /** Delivers `MessageEvent.data` as-is. Returns an unsubscribe function. */
+    onMessage(cb: (data: StreamData) => void): () => void;
+    /** Returns an unsubscribe function. */
+    onClose(cb: (info: StreamCloseInfo) => void): () => void;
+    /** The underlying socket's readyState (0 CONNECTING, 1 OPEN, 2 CLOSING, 3 CLOSED). */
+    readonly readyState: number;
+}
+/**
+ * What a generated `<tool>Connect` factory needs from the client: the ability to open a stream
+ * for a binding. `createLesslyApp`'s client implements it (see `LesslyClientBase`).
+ */
+interface LesslyStreamOpener {
+    openStream(binding: WsBinding, input?: Record<string, unknown>): LesslyStream;
+}
+/** The shape of `globalThis.WebSocket` this SDK relies on — injectable, like `fetch`. */
+type WebSocketCtor = new (url: string) => WebSocketLike;
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: StreamData): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, cb: (ev: never) => void): void;
+    removeEventListener(type: string, cb: (ev: never) => void): void;
+}
 interface LesslyAppOptions {
     /**
      * Absolute origin ("https://api.lessly.dev") or a path relative to the page
@@ -25,13 +77,30 @@ interface LesslyAppOptions {
     productId: string;
     getCsrfToken?: () => string | null | undefined;
     fetch?: typeof fetch;
+    /** Injectable WebSocket constructor for `connectStream`; defaults to `globalThis.WebSocket`. */
+    WebSocket?: WebSocketCtor;
 }
 
-interface LesslyClientBase {
+interface LesslyClientBase extends LesslyStreamOpener {
     call(toolName: string, input?: Record<string, unknown>): Promise<unknown>;
 }
 declare function createLesslyApp(opts: LesslyAppOptions): GeneratedClient & LesslyClientBase;
 
+/**
+ * Open the sanctioned streaming connection for a ws-bound tool.
+ *
+ * Session cookies ride the upgrade automatically, so this sends NOTHING extra: no CSRF token (an
+ * upgrade is not an HTTP mutation) and no product header — a browser WebSocket cannot set headers
+ * at all, and the gateway's upgrade path authenticates from the session alone.
+ *
+ * Params are placed exactly as for a GET request: `:token` segments are substituted into the
+ * path, everything else becomes a query parameter. A param declared `in: 'body'` has no meaning
+ * on an upgrade and is treated as a query parameter rather than silently dropped.
+ *
+ * There is no reconnection, backoff or heartbeat logic here on purpose (see `LesslyStream`).
+ */
+declare function connectStream(opts: LesslyAppOptions, binding: WsBinding, input?: Record<string, unknown>): LesslyStream;
+
 declare class LesslyApiError extends Error {
     readonly status: number;
     readonly code: string | null;
@@ -39,4 +108,4 @@ declare class LesslyApiError extends Error {
     constructor(status: number, code: string | null, message: string, body: unknown);
 }
 
-export { type Binding, type BindingsMap, GeneratedClient, type HttpMethod, LesslyApiError, type LesslyAppOptions, type LesslyClientBase, type ParamIn, type ParamSpec, createLesslyApp };
+export { type Binding, type BindingsMap, GeneratedClient, type HttpMethod, LesslyApiError, type LesslyAppOptions, type LesslyClientBase, type LesslyStream, type LesslyStreamOpener, type ParamIn, type ParamSpec, type StreamCloseInfo, type StreamData, type WebSocketCtor, type WebSocketLike, type WsBinding, type WsBindingsMap, connectStream, createLesslyApp };