@lessly/sdk-app 48.0.4 → 49.0.1

package/dist/index.d.cts

@@ -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

@@ -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.js

@@ -124,6 +124,65 @@ async function executeRequest(opts, binding, input) {
   return parsed;
 }
 
+// src/runtime/connectStream.ts
+function toWsUrl(url) {
+  if (url.startsWith("https:")) return `wss:${url.slice("https:".length)}`;
+  if (url.startsWith("http:")) return `ws:${url.slice("http:".length)}`;
+  return url;
+}
+function connectStream(opts, binding, input) {
+  const restLike = { method: "GET", path: binding.path, ...binding.params ? { params: binding.params } : {} };
+  const { path, query, body } = resolveRequest(restLike, input);
+  const url = toWsUrl(buildUrl(opts.baseUrl, path, { ...query, ...body ?? {} }));
+  const Ctor = opts.WebSocket ?? globalThis.WebSocket;
+  if (!Ctor) {
+    throw new Error(
+      `@lessly/sdk-app: WebSocket is unavailable in this environment, so the stream to "${binding.path}" cannot be opened. Streaming requires a browser; pass options.WebSocket to supply an implementation.`
+    );
+  }
+  const socket = new Ctor(url);
+  const messageSubs = /* @__PURE__ */ new Set();
+  const closeSubs = /* @__PURE__ */ new Set();
+  let pending = [];
+  socket.addEventListener("open", () => {
+    const queued = pending ?? [];
+    pending = null;
+    for (const frame of queued) socket.send(frame);
+  });
+  socket.addEventListener("message", (ev) => {
+    for (const cb of [...messageSubs]) cb(ev.data);
+  });
+  socket.addEventListener("close", (ev) => {
+    pending = null;
+    const info = { code: ev.code ?? 1006, reason: ev.reason ?? "", wasClean: ev.wasClean ?? false };
+    for (const cb of [...closeSubs]) cb(info);
+  });
+  return {
+    send(data) {
+      if (pending !== null) {
+        pending.push(data);
+        return;
+      }
+      if (socket.readyState === 1) socket.send(data);
+    },
+    close(code, reason) {
+      pending = null;
+      socket.close(code, reason);
+    },
+    onMessage(cb) {
+      messageSubs.add(cb);
+      return () => messageSubs.delete(cb);
+    },
+    onClose(cb) {
+      closeSubs.add(cb);
+      return () => closeSubs.delete(cb);
+    },
+    get readyState() {
+      return socket.readyState;
+    }
+  };
+}
+
 // src/runtime/name.ts
 var ROOT_RESOURCE = "$root";
 function splitToolName(name) {
@@ -8179,6 +8238,13 @@ function createLesslyApp(opts) {
   const map = bindings;
   const nsCache = {};
   const base = {
+    // The whole streaming surface of the client. Streams are NOT reachable through the request
+    // proxy: a socket is not a promise-returning call, and hanging one off `sdk.<ns>.<res>.<act>`
+    // would make two very different lifetimes look identical at the call site. The generated
+    // `<tool>Connect` factories carry the binding and call this.
+    openStream(binding, input) {
+      return connectStream(opts, binding, input);
+    },
     call(toolName, input) {
       let split;
       try {
@@ -8203,6 +8269,6 @@ function createLesslyApp(opts) {
   });
 }
 
-export { LesslyApiError, createLesslyApp };
+export { LesslyApiError, connectStream, createLesslyApp };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map