@poolse/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `@poolse/sdk` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[semver](https://semver.org).
+
+## [0.1.0] — 2026-06-01
+
+First publishable release.
+
+### Added
+
+- `Poolse` client class with REST resources: `me`, `conversations`
+  (list/create/get/update + members), `messages` (send/list/mark-read +
+  edit/delete/replies/reactions on per-id handle), `attachments`
+  (presigned upload + download + delete).
+- `RestClient` low-level wrapper:
+  - Bearer JWT via `config.getToken` (async or sync; nullable for
+    deliberate unauthenticated calls).
+  - Auto-generated `Idempotency-Key` for non-GET requests
+    (`crypto.randomUUID()` by default; overrideable).
+  - Exponential backoff with full jitter for transient failures.
+  - `Retry-After` header honoured on 429.
+  - Network errors retried (except `AbortError`).
+  - 401 → `AuthError`, 429 → `RateLimitedError`, other 4xx/5xx → `ApiError`,
+    network failures → `NetworkError`. All `instanceof`-checkable.
+- Initial scaffold: TypeScript, dual ESM+CJS build via tsup, vitest,
+  eslint, prettier, Node 22 Docker dev environment.
+
+## [0.0.1] — scaffolding only
+
+Placeholder release. The real `Poolse` client class (REST + Channels +
+offline queue) lands in subsequent SDK tasks under Phase 1F.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Poolse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# `@poolse/sdk`
+
+The headless TypeScript SDK for **[poolse](https://poolse.dev)** — realtime chat infrastructure.
+
+REST + WebSocket + presence + typing + reactions + threads + attachments, all in one runtime-agnostic package. Works in browsers, Node, Deno, Bun, and React Native. No UI.
+
+> Most React apps will want **[`@poolse/react`](https://www.npmjs.com/package/@poolse/react)** (hooks) or **[`@poolse/react-ui`](https://www.npmjs.com/package/@poolse/react-ui)** (prebuilt chat surface) instead. This package is the foundation underneath both.
+
+## Install
+
+```bash
+npm install @poolse/sdk
+```
+
+## Quick start
+
+```ts
+import { Poolse } from '@poolse/sdk';
+
+const chat = new Poolse({
+  apiUrl: 'https://chat.example.com',
+  // Your backend mints a JWT for the signed-in End User and returns it.
+  // The SDK caches + refreshes via this callback — never embed an API key
+  // in the browser.
+  getToken: async () => {
+    const res = await fetch('/api/chat-token', { method: 'POST' });
+    const { token } = await res.json();
+    return token;
+  },
+});
+
+// REST
+const me = await chat.me.show();
+const { data: conversations } = await chat.conversations.list();
+
+// Send + receive in real time
+const conv = chat.conversations.one('<conversation-id>');
+const sent = await conv.messages.send({ body: 'Hello' });
+
+const off = chat.realtime
+  .conversation('<conversation-id>')
+  .onMessage((msg) => console.log('new message', msg));
+
+// Later
+off();
+chat.destroy();
+```
+
+## What it covers
+
+- **REST resources**: `me`, `conversations` (incl. members), `messages` (send / edit / delete / replies / reactions / mark-read), `attachments` (presigned upload + download + delete).
+- **Realtime channels**: `message:new`, `message:updated`, `message:deleted`, `typing:start/stop`, `reaction:added/removed`, presence state + diff, per-user `mention:new` + `conversation:created`.
+- **Token caching** — `getToken` is called once per JWT lifetime, not per request. Auto-invalidates on 401 and re-issues.
+- **Idempotency** — every non-GET request carries an auto-generated `Idempotency-Key`, so retries (network or 5xx) never insert duplicates.
+- **Backoff** — exponential with full jitter, honors `Retry-After` on 429, never retries `AbortError`.
+- **Typed errors** — `AuthError` / `ApiError` / `NetworkError` / `RateLimitedError`, all `instanceof`-checkable.
+
+## Architecture pattern
+
+```
+┌──────────────┐   API key      ┌──────────────┐    JWT     ┌──────────────┐
+│ Your backend │ ─────────────▶ │ poolse REST  │ ◀───────── │ Your browser │
+│              │ ◀───  user_id  │              │            │  (uses SDK)  │
+│  /api/chat-  │                │              │            │              │
+│   token      │ ───────────────────────────────────────▶   │              │
+└──────────────┘     JWT to browser via your own fetch       └──────────────┘
+```
+
+The poolse API key NEVER touches the browser. Your backend exchanges it for short-lived End User JWTs (`POST /v1/users/:id/tokens`); the SDK uses those JWTs for everything else.
+
+## Documentation
+
+- Full SDK + integration docs — <https://poolse.dev/docs>
+- Source — <https://github.com/poolse-hq/js-sdk>
+- Issues — <https://github.com/poolse-hq/js-sdk/issues>
+
+## License
+
+MIT