@lessly/sdk-app 48.0.4 → 49.0.1

package/docs/recipes/sdk-usage.md

@@ -134,8 +134,58 @@ tools carry a REST binding. Run `npm i @lessly/sdk-app@latest` to pick up newly
 migrated namespaces. To see exactly what a given version exposes, check its
 subpaths in `package.json` `exports`, or the `manifest.gen.ts` namespace list.
 
+## Streaming (`*Connect` factories)
+
+Some catalog tools are ws-bound: instead of a request/response pair they carry
+a `ws` binding, and the generator emits a `<toolId>Connect` factory for them
+next to the option factories. That factory is the **only** sanctioned way to
+stream from an App (APP-001) — it derives `ws(s)://` from your `baseUrl`, opens
+the socket, and hands back a small handle:
+
+```ts
+import { createLesslyApp } from '@lessly/sdk-app';
+import { playgroundWsEchoConnect } from '@lessly/sdk-app/playground';
+
+const sdk = createLesslyApp({ baseUrl: 'https://api.lessly.dev', productId: 'prod_123' });
+
+const stream = playgroundWsEchoConnect(sdk, { room: 'lobby' });
+const off = stream.onMessage((frame) => console.log(frame));
+stream.onClose(({ code, reason, wasClean }) => console.log('closed', code, reason, wasClean));
+stream.send('hello');       // queued until the socket is OPEN, then flushed in order
+// later
+off();
+stream.close(1000, 'done');
+```
+
+What the handle does and does not do:
+
+- **Session cookies ride the upgrade.** No CSRF token and no product header are
+  sent — a browser `WebSocket` cannot set headers at all, and the gateway
+  authenticates the upgrade from the session.
+- **Frames are raw.** `onMessage` delivers `MessageEvent.data` exactly as it
+  arrived (`string`, `ArrayBuffer` or `Blob`); the SDK never parses it. Framing
+  is protocol-specific and is documented by the tool's own description.
+- **No reconnection.** A dropped connection surfaces once, through `onClose`
+  with the close code (`1006` for an abnormal drop). Whether and how to
+  reconnect is the App's decision — the SDK will not retry behind your back.
+- **Params are placed like a GET.** `:token` segments are filled from the input,
+  everything else becomes a query parameter.
+
+The `*Connect` factory is the App-facing surface, and the only one APP-001
+sanctions. The lower-level pieces it is built on — `sdk.openStream(binding, …)`
+and the `connectStream` runtime — are the SDK's own primitive: they are exported
+so the generated code can use them and so tests can substitute a socket, not so
+that App code can address a route by hand. Call the factory.
+
+Streaming needs a browser: outside one (SSR, node tests) there is no
+`WebSocket`, and the SDK says so by name rather than failing opaquely. Pass
+`options.WebSocket` to supply an implementation in tests.
+
 ## What not to do
 
+- Don't open a `WebSocket` to a platform host, and don't hand-build a
+  `ws(s)://` URL from `baseUrl` (APP-001) — use the generated `*Connect`
+  factory. A tool without a `ws` binding has no sanctioned stream.
 - Don't `fetch` a platform host directly, and don't use any other HTTP client
   for platform data (APP-001) — always go through `sdk` or the generated
   factories.

package/docs/rules.md

@@ -23,6 +23,19 @@ generated `*QueryOptions`/`*MutationOptions` factories built on top of it. An
 App MUST NOT `fetch` a platform host directly, and MUST NOT use any other HTTP
 client to reach platform data.
 
+**Streaming.** The same rule covers WebSockets. Platform streaming MUST go
+through the generated `*Connect` factories (`<toolId>Connect(sdk, params)`,
+imported from the tool's namespace subpath), which are emitted for every
+catalog tool that carries a `ws` binding and are backed by the SDK's
+`connectStream` runtime. An App MUST NOT construct `new WebSocket(...)` against
+a platform host, exactly as it must not `fetch` one — and MUST NOT hand-build a
+`ws(s)://` URL from `baseUrl`. A tool with no `ws` binding has no sanctioned
+stream: there is nothing to open, and reaching for a raw socket is a violation,
+not a workaround.
+
+`new WebSocket(...)` against an App's OWN non-platform host (a third-party
+service the App integrates) is outside this rule.
+
 ### APP-002 (MUST) — Frontend-only
 
 An App MUST NOT ship a backend service, a database, or an MCP endpoint. All

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessly/sdk-app",
-  "version": "48.0.4",
+  "version": "49.0.1",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -101,5 +101,5 @@
       "require": "./dist/waitlist/index.cjs"
     }
   },
-  "sdkContentHash": "sha256:82da00e2c226a8955611954633868a0b341f2c4448c844865f0281540a68671b"
+  "sdkContentHash": "sha256:9954f7b662b31bf1716d5023b5b42f83b84a1258101a622ef7a26a933f974200"
 }

package/src/gen/bindings.gen.ts

@@ -1,5 +1,5 @@
 // AUTOGENERATED by scripts/generate.ts — do not edit.
-import type { BindingsMap } from '../runtime/types';
+import type { BindingsMap, WsBindingsMap } from '../runtime/types';
 
 export const bindings: BindingsMap = {
   "analytics": {
@@ -8011,3 +8011,5 @@ export const bindings: BindingsMap = {
     }
   }
 };
+
+export const wsBindings: WsBindingsMap = {};