@firtoz/socka 4.0.0 → 5.0.0

package/docs/auth.md

@@ -2,18 +2,27 @@
 
 Socka does not ship a built-in auth layer: you decide **who** may open a WebSocket and **what** each RPC may do. Typical patterns:
 
-## Read credentials on upgrade
+## Reject before upgrade (HTTP 401 / 403)
 
-- **`@firtoz/socka/server`** — by default **`createData`** receives **`SockaStrictWebSocketInit`**; read **`init.request`** (cookies via **`Cookie`**, **`Authorization`**, URL query, path segments).
+When identity is attested on a **web worker** and forwarded to the DO (headers, shared secret, signed query), reject **before** `101 Switching Protocols`:
+
+- **`BaseWebSocketDO.beforeWebSocket(ctx)`** — override on your DO (inherited by **`SockaWebSocketDO`**). Return **`401` / `403`** to stop the upgrade; return **`void`** to proceed. Runs before **`WebSocketPair`** is created.
+- **Hono middleware** on a chained **`app = this.getBaseApp().use(…)`** — same HTTP semantics for routes you mount before **`/websocket`**.
+
+This is preferable to **`override fetch()`** on the whole DO when you only need to gate the WebSocket path.
+
+## Read credentials after upgrade (`createData`)
+
+- **`@firtoz/socka/server`** — **`createData`** receives **`SockaStrictWebSocketInit`**; read **`init.request`** (cookies, **`Authorization`**, query, path).
 - **`SockaDoSession`** with **`createData: (ctx) => …`** — use Hono **`ctx.req`**, **`ctx.get("…")`**, or **`ctx.req.raw.headers`**.
 
-Reject before returning session data: throw **`SockaError`** with **`{ code, data }`** so the client receives a correlated **`serverError`** frame (see **[Reference — RPC handler errors](./reference.md#rpc-handler-errors)**).
+Throwing **`SockaError`** in **`createData`** runs **after** the upgrade (`101` already sent). The client gets a correlated **`serverError`** frame and the socket closes — **not** a clean HTTP rejection. Use this for “connected but not allowed” or when credentials are only available post-upgrade; use **`beforeWebSocket`** when you need HTTP status codes before opening the socket.
 
 ## Browsers and the WebSocket API
 
 The browser **`WebSocket`** constructor cannot set arbitrary headers on the handshake. Common approaches:
 
-- **Cookie** — `SameSite` cookies sent automatically to your origin; read them in **`createData`** from **`init.request`**.
+- **Cookie** — `SameSite` cookies sent automatically to your origin; read them in **`createData`** or validate on the worker and forward attested identity to the DO **`beforeWebSocket`** check.
 - **Query string** — `wss://app.example.com/ws/room?token=…` (treat tokens as secrets; prefer short-lived tokens and HTTPS/WSS only).
 - **Subprotocol** — rarely needed; socka uses its own wire framing on the same socket.
 
@@ -23,5 +32,6 @@ You can also enforce auth inside **RPC handlers** using **`session.data`** (set
 
 ## See also
 
+- **[Durable Objects](./durable-objects.md)** — chaining HTTP routes on **`app`**.
 - **[Multi-room](./multi-room.md)** — scoping **`sessionMap`** per tenant/room.
-- **[Client](./client.md)** — lifecycle and reconnect; re-auth after reconnect may repeat **`listHistory`** / snapshot RPCs.
+- **[Client](./client.md)** — lifecycle and reconnect; re-auth after reconnect may repeat snapshot RPCs.

package/docs/client.md

@@ -69,6 +69,14 @@ Optional **`pushHandlers`** in the second argument matches **`Partial<InferSocka
 
 **Recommended pattern:** In the route module, set **`const [url, setUrl] = useState<string | null>(null)`**, and in **`useEffect`** (browser-only), build a **`wss://` / `ws://`** URL from **`window.location`** (protocol, host, path to your Worker’s WebSocket route). If **`url === null`**, render a **loading** shell; only render a child component that calls **`useSockaSession(myContract, { url, pushHandlers? }, [url])`** when **`url`** is set. Keep **`url`** in the hook **`deps`** so identity changes re-open the right socket.
 
+**SSR checklist:**
+
+1. **Never** call **`useSockaSession`** with a placeholder URL during SSR — the hook connects in **`useEffect`** and will throw if **`url`** is missing at runtime.
+2. **Parent gates the child** — render **`ClientOnly`** / **`url === null ? <Loading /> : <ChatWithSocket url={url} />`** so the hook runs only in the browser with a real URL.
+3. **Build the URL in `useEffect`** — derive **`wss:`** from **`window.location`**, room id from route params, and optional auth query params there (not during render).
+4. **Pass `[url]` in hook deps** — room or tenant changes should remount the connection.
+5. **`SockaSessionProvider`** follows the same rules — wrap only after **`url`** is known.
+
 **React + Durable Object** end-to-end wiring: **[React + Durable Objects](./react-durable-objects.md)**.
 
 ### `useSocka` — hold a `SockaSession` ref

package/docs/durable-objects.md

@@ -28,7 +28,12 @@ export class MyDO extends SockaWebSocketDO<
   Env
 > {
   protected readonly contract = myContract;
-  app = this.getBaseApp();
+  app = this.getBaseApp().delete("/admin/messages/:messageId", async (c) => {
+    const messageId = c.req.param("messageId");
+    await this.db.delete(messageId);
+    await this.broadcastPushToAll("messageDeleted", { id: messageId });
+    return c.json({ ok: true as const });
+  });
 
   protected buildSockaSessionConfig(
     ctx: Context<{ Bindings: Env }> | undefined,
@@ -47,7 +52,7 @@ export class MyDO extends SockaWebSocketDO<
     };
   }
 
-  // HTTP admin — no WebSocket session on this path
+  // Same logic as the HTTP route above — callable from alarms or internal helpers
   async deleteMessage(id: string) {
     await this.db.delete(…);
     await this.broadcastPushToAll("messageDeleted", { id });
@@ -111,9 +116,18 @@ If you mutate **`session.data`** after connect, call **`await session.update()`*
 
 ## Pushes from HTTP / non-WebSocket handlers
 
-Many DO apps expose **Hono HTTP routes** on **`app`** (admin moderation, internal APIs, alarms) in addition to **`/websocket`**. After mutating storage from those handlers, you often need a contract-typed push to **every** connected client — with **no** originating WebSocket session.
+Many DO apps expose **Hono HTTP routes** on **`app`** (admin moderation, internal APIs, alarms) in addition to **`/websocket`**. Chain routes on **`this.getBaseApp()`** — socka registers **`GET /websocket`**; your handlers share the same **`app`** instance:
 
-Use **`await this.broadcastPushToAll("messageDeleted", { id })`** on your DO subclass. The DO **`contract`** is the single source of truth. See **[Pushes — Pushes from HTTP / non-WebSocket handlers](./pushes.md#pushes-from-http--non-websocket-handlers)**.
+```ts
+app = this.getBaseApp().delete("/admin/messages/:messageId", async (c) => {
+  const id = c.req.param("messageId");
+  await this.db.delete(id);
+  await this.broadcastPushToAll("messageDeleted", { id });
+  return c.json({ ok: true as const });
+});
+```
+
+After mutating storage from those handlers, **`broadcastPushToAll`** fans out to every connected client. The DO **`contract`** is the single source of truth. See **[Pushes — Pushes from HTTP / non-WebSocket handlers](./pushes.md#pushes-from-http--non-websocket-handlers)**.
 
 Without a DO subclass, use **`broadcastContractPushToAll(this.sessions, contract, name, body)`** from **`@firtoz/socka/server`**.
 

package/docs/reference.md

@@ -120,7 +120,7 @@ Anything that implements **Standard Schema v1** works — **Zod**, **Valibot**,
 | Path | Use for |
 |------|---------|
 | `@firtoz/socka` | Same as **`@firtoz/socka/core`** — `defineSocka`, wire helpers, errors, types (prefer explicit **`/core`** in examples) |
-| `@firtoz/socka/core` | `defineSocka`, wire helpers, `SockaError`, `SockaReportError`, `reportSockaError`, types |
+| `@firtoz/socka/core` | `defineSocka`, wire helpers, `SockaError`, `SockaReportError`, `reportSockaError`, types. Export map includes **`require`** / **`default`** for Node tooling (e.g. drizzle-kit) that resolves CJS. Keep **constants-only** modules (no socka import) beside Drizzle schema when possible. |
 | `@firtoz/socka/client` | `SockaSession`, `SockaWebSocketClient` (also re-exports `SockaReportError`, `reportSockaError`) |
 | `@firtoz/socka/test` | `createFakeWebSocket` for unit tests — see **[Testing](./testing.md)** |
 | `@firtoz/socka/react` | `useSocka`, `useSockaSession`, `useSockaPresence`, provider + context |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/socka",
-	"version": "4.0.0",
+	"version": "5.0.0",
 	"type": "module",
 	"description": "Standard Schema–first WebSocket RPC for TypeScript — Bun, Hono, Node ws, Cloudflare Workers, Durable Objects",
 	"main": "./dist/core/index.js",
@@ -9,43 +9,63 @@
 	"exports": {
 		".": {
 			"types": "./dist/core/index.d.ts",
-			"import": "./dist/core/index.js"
+			"import": "./dist/core/index.js",
+			"require": "./dist/core/index.js",
+			"default": "./dist/core/index.js"
 		},
 		"./core": {
 			"types": "./dist/core/index.d.ts",
-			"import": "./dist/core/index.js"
+			"import": "./dist/core/index.js",
+			"require": "./dist/core/index.js",
+			"default": "./dist/core/index.js"
 		},
 		"./client": {
 			"types": "./dist/client/index.d.ts",
-			"import": "./dist/client/index.js"
+			"import": "./dist/client/index.js",
+			"require": "./dist/client/index.js",
+			"default": "./dist/client/index.js"
 		},
 		"./react": {
 			"types": "./dist/react/index.d.ts",
-			"import": "./dist/react/index.js"
+			"import": "./dist/react/index.js",
+			"require": "./dist/react/index.js",
+			"default": "./dist/react/index.js"
 		},
 		"./do": {
 			"types": "./dist/do/index.d.ts",
-			"import": "./dist/do/index.js"
+			"import": "./dist/do/index.js",
+			"require": "./dist/do/index.js",
+			"default": "./dist/do/index.js"
 		},
 		"./server": {
 			"types": "./dist/server/index.d.ts",
-			"import": "./dist/server/index.js"
+			"import": "./dist/server/index.js",
+			"require": "./dist/server/index.js",
+			"default": "./dist/server/index.js"
 		},
 		"./bun": {
 			"types": "./dist/bun/index.d.ts",
-			"import": "./dist/bun/index.js"
+			"import": "./dist/bun/index.js",
+			"require": "./dist/bun/index.js",
+			"default": "./dist/bun/index.js"
 		},
 		"./hono": {
 			"types": "./dist/hono/index.d.ts",
-			"import": "./dist/hono/index.js"
+			"import": "./dist/hono/index.js",
+			"require": "./dist/hono/index.js",
+			"default": "./dist/hono/index.js"
 		},
 		"./hono/cloudflare": {
 			"types": "./dist/hono/cloudflare-workers.d.ts",
-			"import": "./dist/hono/cloudflare-workers.js"
+			"import": "./dist/hono/cloudflare-workers.js",
+			"require": "./dist/hono/cloudflare-workers.js",
+			"default": "./dist/hono/cloudflare-workers.js"
 		},
 		"./test": {
 			"types": "./dist/test/index.d.ts",
-			"import": "./dist/test/index.js"
+			"import": "./dist/test/index.js",
+			"require": "./dist/test/index.js",
+			"default": "./dist/test/index.js"
 		}
 	},
 	"files": [
@@ -96,13 +116,13 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@firtoz/maybe-error": "^1.6.1",
+		"@firtoz/maybe-error": "^1.6.2",
 		"@standard-schema/spec": "^1.1.0",
 		"msgpackr": "^2.0.1"
 	},
 	"peerDependencies": {
 		"@cloudflare/workers-types": "^4.20260503.1",
-		"@firtoz/websocket-do": "^13.0.2",
+		"@firtoz/websocket-do": "^14.0.0",
 		"@hono/node-server": "^1.19.2",
 		"@hono/node-ws": "^1.3.0",
 		"hono": "^4.12.9",