@oxpulse/chat-sdk 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# @oxpulse/chat-sdk
+
+TypeScript client for the OxPulse encrypted chat message log API.
+
+## Install
+
+> Publishing to npm is deferred to W8 (embed widget wave). Until then use a
+> local path dependency or build from source.
+
+```bash
+# After W8 publish:
+npm install @oxpulse/chat-sdk
+```
+
+## Usage
+
+```ts
+import { SDKChatClient } from '@oxpulse/chat-sdk';
+
+// JWT obtained from POST /api/sdk/tokens (server-side mint).
+const client = new SDKChatClient({
+  baseUrl: 'https://chat.example.com',
+  jwt: 'raw-jwt-here', // do NOT include "Bearer " prefix
+});
+
+// Send a sealed (E2EE) message.
+const { seq, msgId } = await client.send('room-123', {
+  senderUid: 'user-1',
+  sealed: ciphertextArrayBuffer,
+});
+
+// List historical messages.
+const rows = await client.list('room-123', { afterSeq: 0, limit: 100 });
+
+// Subscribe to live messages via SSE.
+// Auth uses a short-lived ticket (RFC 6750 compliant — no JWT in URL).
+const teardown = client.subscribe('room-123', {
+  onMessage: (row) => {
+    // row.sealed — ciphertext as ArrayBuffer; pass to your E2EE decrypt function.
+    console.log('new message seq=%d', row.seq);
+  },
+  onError: (err) => console.error('SSE error', err),
+});
+
+// Stop subscribing.
+teardown();
+```
+
+## Error model
+
+All failures throw `SDKChatError` with a typed `code` field:
+
+| Code | When |
+|------|------|
+| `unauthorized` | 401 — invalid or expired JWT / ticket |
+| `forbidden` | 403 — missing scope |
+| `not_found` | 404 |
+| `rate_limited` | 429 |
+| `invalid_args` | 400–4xx (other than above) |
+| `server_error` | 5xx |
+| `network` | fetch/network-level failure |
+
+## License
+
+AGPL-3.0-or-later. See root [LICENSE](../../LICENSE).
+
+## Compression (optional)
+
+By default all outgoing `POST /api/sdk/messages` requests use plain JSON
+(`compression: 'none'`). Enable zstd compression to reduce payload size:
+
+```ts
+import { SDKChatClient } from '@oxpulse/chat-sdk';
+
+const client = new SDKChatClient({
+  baseUrl: 'https://chat.example.com',
+  jwt: 'jwt...',
+  compression: 'auto',       // zstd dictless (0xC6) when payload ≥ 256 B
+});
+
+// Or use a shared dictionary for better compression on RU/FA/EN content:
+const client2 = new SDKChatClient({
+  baseUrl: 'https://chat.example.com',
+  jwt: 'jwt...',
+  compression: 'dict',
+  dictBaseUrl: '/dicts',     // served at /dicts/zstd-dict-ru-v1.zstd etc.
+  dictHint: 'zstd-dict-ru-v1',
+});
+```
+
+See `@oxpulse/wire-codec` README for codec internals, dict management, and
+the server-side frame format.
+
+## CSP Compatibility
+
+`@oxpulse/chat-sdk` is **strict-CSP-safe by design** — zero `eval()`, zero
+`new Function()`. Tested against:
+
+```
+script-src 'self' 'wasm-unsafe-eval' 'nonce-...' 'strict-dynamic'
+```
+
+(no `'unsafe-eval'`, no `'unsafe-inline'`).
+
+The SDK does NOT use zod internally — types are exported but runtime
+validation is left to the integrator. This means no zod `Function()` probe
+in the SDK bundle itself.
+
+### If you bundle the SDK with eval-using libraries
+
+If your own bundle pulls in libraries that call `Function()`, you'll hit CSP
+violations unrelated to the SDK. Common culprits and mitigations:
+
+- **zod v4 (default mode):** calls `new Function(...)` at schema-build time
+  to JIT-compile validators. Set:
+  ```ts
+  // app boot script — BEFORE any module-level z.object() executes:
+  globalThis.__zod_globalConfig = { jitless: true };
+  ```
+  Putting `zod.config({ jitless: true })` inside an instance file is too
+  late — module-level `z.object()` already ran during import.
+
+- **cbor-x (default import):** JIT-compiles decoders via `new Function`.
+  Import from the no-eval subpath instead:
+  ```ts
+  import { Encoder, decode } from 'cbor-x/index-no-eval';
+  ```
+  `@oxpulse/wire-codec` (a transitive dep of this SDK) already uses
+  `cbor-x/index-no-eval` internally — you only need this fix if you import
+  `cbor-x` directly in your application code.
+
+### Verifying your bundle
+
+Scan your built output before shipping:
+
+```bash
+grep -E 'new Function|eval\(' dist/**/*.js
+```
+
+A build-time test that asserts the SDK bundle stays clean lives at
+`packages/chat-sdk/src/__tests__/csp-cleanliness.test.ts`. Run it after
+`npm run build` to catch regressions introduced by dependency updates.

package/dist/client.d.ts

@@ -0,0 +1,98 @@
+/**
+ * SDKChatClient — standalone npm package implementation.
+ *
+ * This is a standalone copy of the HTTP client for use by third-party
+ * integrations that import @oxpulse/chat-sdk directly.  The SvelteKit
+ * front-end uses web/src/lib/api/sdkChat.ts (same semantics, same wire
+ * protocol) — kept separate to avoid pulling in SvelteKit build tooling.
+ *
+ * W4 skeleton: full implementation mirrors web/src/lib/api/sdkChat.ts.
+ * Publishing to npmjs.org is deferred to W8 (embed widget wave).
+ */
+import type { SDKChatClientOptions, SendArgs, ListArgs, MessageRow, SubscribeArgs, Room, Member, CreateRoomArgs, UpdateRoomArgs, PresenceUser } from './types.js';
+export declare class SDKChatClient {
+    #private;
+    constructor(opts: SDKChatClientOptions);
+    /**
+     * Encode a payload to the bytes that would be sent on the wire, without sending.
+     * Mirrors the encoding _encodeBody applies to POST /api/sdk/messages.
+     */
+    encodeEnvelope(payload: unknown): Promise<string | Uint8Array>;
+    /**
+     * Decode bytes received from the server back to the JSON payload.
+     * Server responses are always plain JSON; this also handles wire-codec
+     * compressed frames for completeness (round-trip with encodeEnvelope).
+     *
+     * Note: #compression governs OUTGOING encoding only. A server may send a
+     * compressed frame (0xC6/0xC7) regardless of the client's compression setting.
+     * decodeEnvelope checks the first byte directly and initializes zstd if needed.
+     */
+    decodeEnvelope(bytes: Uint8Array | string): Promise<unknown>;
+    send(roomId: string, args: SendArgs): Promise<{
+        seq: number;
+        msgId: string;
+    }>;
+    list(roomId: string, args?: ListArgs): Promise<MessageRow[]>;
+    subscribe(roomId: string, args: SubscribeArgs): () => void;
+    /**
+     * Broadcast a typing indicator for roomId.
+     * Wire-contract: POST /api/sdk/rooms/:room_id/typing
+     * Body: { ttl_secs? }
+     */
+    sendTyping(roomId: string, ttlSecs?: number): Promise<void>;
+    /**
+     * Send a presence heartbeat for roomId.
+     * Wire-contract: POST /api/sdk/rooms/:room_id/presence
+     * Body: {}
+     */
+    sendPresence(roomId: string): Promise<void>;
+    /**
+     * Fetch presence snapshot for roomId.
+     * Wire-contract: GET /api/sdk/rooms/:room_id/presence
+     * Returns: Array<PresenceUser>
+     */
+    getPresence(roomId: string): Promise<PresenceUser[]>;
+    /**
+     * Mark messages up to seq as read (monotonic — cannot regress).
+     * Wire-contract: POST /api/sdk/rooms/:room_id/read?seq=N
+     */
+    markRead(roomId: string, seq: number): Promise<void>;
+    /**
+     * Create a room. Idempotent per roomId.
+     * Wire-contract: POST /api/sdk/rooms
+     */
+    createRoom(args?: CreateRoomArgs): Promise<Room>;
+    /**
+     * Fetch room metadata + active members.
+     * Wire-contract: GET /api/sdk/rooms/:room_id
+     */
+    getRoom(roomId: string): Promise<Room>;
+    /**
+     * Update room title / metadata. Owner-only.
+     * Wire-contract: PATCH /api/sdk/rooms/:room_id
+     */
+    updateRoom(roomId: string, args: UpdateRoomArgs): Promise<Room>;
+    /**
+     * List active members of a room (fetches room and returns members).
+     */
+    listMembers(roomId: string): Promise<Member[]>;
+    /**
+     * Add a user to a room.
+     * Wire-contract: POST /api/sdk/rooms/:room_id/members
+     * Body: { user_id, role? }
+     */
+    addMember(roomId: string, userId: string, role?: string): Promise<Member>;
+    /**
+     * Remove a user from a room (soft-delete).
+     * Wire-contract: DELETE /api/sdk/rooms/:room_id/members/:user_id
+     */
+    removeMember(roomId: string, userId: string): Promise<void>;
+    /**
+     * Fetch all reply messages in a thread.
+     * Wire-contract: GET /api/sdk/rooms/:room_id/threads/:root_msg_id
+     * Returns: Array<MessageRow> sorted by seq ascending (server-side ORDER BY seq).
+     * Requires scope: chat:read:<room_id>.
+     */
+    getThread(roomId: string, rootMsgId: string): Promise<MessageRow[]>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAWH,OAAO,KAAK,EACV,oBAAoB,EACpB,QAAQ,EACR,QAAQ,EACR,UAAU,EAEV,aAAa,EACb,IAAI,EACJ,MAAM,EACN,cAAc,EACd,cAAc,EACd,YAAY,EACb,MAAM,YAAY,CAAC;AAgEpB,qBAAa,aAAa;;gBAQZ,IAAI,EAAE,oBAAoB;IAoDtC;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC;IAIpE;;;;;;;;OAQG;IACG,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwB5D,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAuC7E,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,QAAa,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAwEtE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,IAAI;IAwI1D;;;;OAIG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BjE;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BjD;;;;OAIG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA+B1D;;;OAGG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB1D;;;OAGG;IACG,UAAU,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2C1D;;;OAGG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB5C;;;OAGG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BrE;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKpD;;;;OAIG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,SAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAoCjF;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBjE;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CA2C1E"}