@poolse/sdk 1.1.0 → 2.0.1

package/CHANGELOG.md

@@ -4,6 +4,49 @@ 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).
 
+## [2.0.0] — 2026-06-03
+
+Lockstep release with `@poolse/react@2.0.0` and `@poolse/react-ui@2.0.0`.
+Single load-bearing change: the SDK no longer surfaces poolse-internal
+user uuids in identity-shaped APIs — everything is keyed by the
+tenant's own `external_id` instead.
+
+### Breaking
+
+- **`PoolseConfig.userResolver` signature changes.** Was
+  `(userId: string) => UserProfile | null`; now
+  `(externalId: string) => UserProfile | null`. Your resolver receives
+  YOUR user id (the same string you pass when minting JWTs and as
+  `member_external_ids`), so no `poolse_user_id` column is needed.
+- **`Message.sender_external_id`** added (string | null, required on
+  every wire payload that carries a sender).
+- **`Membership.external_id`** added (string, required).
+- **`QuotedMessagePreview.sender_external_id`** added.
+- **`TypingEvent.external_id`** added — `useTyping` returns
+  `Set<externalId>` instead of `Set<userId>`.
+- **`UsersResource.{peek, get, subscribe, invalidate}`** all keyed by
+  `externalId` (was `userId`). Same semantics; same caching.
+
+### Migration
+
+See `MIGRATING.md` at the repo root. For most apps it's a rename of
+the resolver argument plus deleting the `poolse_user_id` column if
+you stored one.
+
+### Backend coupling
+
+Pairs with the `poolse-server` change that:
+
+- lazy-provisions unknown `external_id`s referenced in
+  `POST /v1/conversations` (`member_external_ids`) and
+  `POST /v1/conversations/:id/members` (`external_ids`), abuse-capped
+  at 50/hour per JWT,
+- emits `sender_external_id` / `external_id` on every user-shaped
+  wire payload (REST, webhook, realtime).
+
+Self-hosted `@poolse/sdk@2.0.0` against an older backend will get
+`sender_external_id: null` everywhere — degraded display, but no crash.
+
 ## [1.1.0] — 2026-06-02
 
 Lockstep release with `@poolse/react@1.1.0` and `@poolse/react-ui@1.1.0`.

package/README.md

@@ -4,6 +4,8 @@ Headless TypeScript SDK for [poolse](https://poolse.dev) — REST + WebSocket cl
 
 If you're using React, you'll usually 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). Both sit on top of this package; you can drop down to it whenever you outgrow them.
 
+> **⚠️ Upgrading from 1.x?** See [MIGRATING.md](https://github.com/poolse-hq/js-sdk/blob/main/MIGRATING.md). 2.0 is a breaking change: identity APIs are now keyed by your `external_id` instead of poolse uuids — `userResolver`, `useUser`, member operations all flip.
+
 ## Install
 
 ```bash
@@ -61,19 +63,19 @@ chat.destroy(); // closes WebSocket, leaves every joined channel
 
 `new Poolse(config)` — every field but `getToken` has a default.
 
-| Field                    | Type                                                                                  | Default                           | Notes                                                                                                                                              |
-| ------------------------ | ------------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `getToken`               | `() => Promise<string \| null> \| string \| null`                                     | — _required_                      | Called when the SDK needs a JWT. Return `null` to make an unauthenticated request (rare — the server requires a JWT for most routes).              |
-| `apiUrl`                 | `string`                                                                              | `https://api.poolse.dev`          | Base URL **without** `/v1`. Strip the trailing slash if present (the SDK does this too).                                                           |
-| `wsUrl`                  | `string`                                                                              | `apiUrl` with `http(s)` → `ws(s)` | Override for split-host deployments where the WebSocket gateway is on a different origin.                                                          |
-| `socketPath`             | `string`                                                                              | `/socket`                         | Phoenix Channels mount point.                                                                                                                      |
-| `fetch`                  | `typeof fetch`                                                                        | `globalThis.fetch`                | Inject a fetch implementation (tests, restricted environments). Must be bound to `globalThis` if you pass the global one explicitly.               |
-| `maxRetries`             | `number`                                                                              | `3`                               | Retry budget for transient failures, per request.                                                                                                  |
-| `baseBackoffMs`          | `number`                                                                              | `250`                             | Base of the exponential backoff.                                                                                                                   |
-| `maxBackoffMs`           | `number`                                                                              | `30000`                           | Hard ceiling on a single retry delay.                                                                                                              |
-| `generateIdempotencyKey` | `() => string`                                                                        | `crypto.randomUUID()`             | Override the key generator. Defaults throws at construction time if no `crypto.randomUUID` is available.                                           |
-| `onSocketError`          | `(err: Error) => void`                                                                | —                                 | Fired on non-fatal socket errors (Phoenix handles reconnect internally; this is for surface-level banners).                                        |
-| `userResolver`           | `(userId: string) => Promise<PoolseUserProfile \| null> \| PoolseUserProfile \| null` | —                                 | Optional. Resolve a poolse `user_id` to a `{ displayName, avatarUrl }` pair from your app's user data. The UI packages pick this up automatically. |
+| Field                    | Type                                                                                      | Default                           | Notes                                                                                                                                                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `getToken`               | `() => Promise<string \| null> \| string \| null`                                         | — _required_                      | Called when the SDK needs a JWT. Return `null` to make an unauthenticated request (rare — the server requires a JWT for most routes).                                                                              |
+| `apiUrl`                 | `string`                                                                                  | `https://api.poolse.dev`          | Base URL **without** `/v1`. Strip the trailing slash if present (the SDK does this too).                                                                                                                           |
+| `wsUrl`                  | `string`                                                                                  | `apiUrl` with `http(s)` → `ws(s)` | Override for split-host deployments where the WebSocket gateway is on a different origin.                                                                                                                          |
+| `socketPath`             | `string`                                                                                  | `/socket`                         | Phoenix Channels mount point.                                                                                                                                                                                      |
+| `fetch`                  | `typeof fetch`                                                                            | `globalThis.fetch`                | Inject a fetch implementation (tests, restricted environments). Must be bound to `globalThis` if you pass the global one explicitly.                                                                               |
+| `maxRetries`             | `number`                                                                                  | `3`                               | Retry budget for transient failures, per request.                                                                                                                                                                  |
+| `baseBackoffMs`          | `number`                                                                                  | `250`                             | Base of the exponential backoff.                                                                                                                                                                                   |
+| `maxBackoffMs`           | `number`                                                                                  | `30000`                           | Hard ceiling on a single retry delay.                                                                                                                                                                              |
+| `generateIdempotencyKey` | `() => string`                                                                            | `crypto.randomUUID()`             | Override the key generator. Defaults throws at construction time if no `crypto.randomUUID` is available.                                                                                                           |
+| `onSocketError`          | `(err: Error) => void`                                                                    | —                                 | Fired on non-fatal socket errors (Phoenix handles reconnect internally; this is for surface-level banners).                                                                                                        |
+| `userResolver`           | `(externalId: string) => Promise<PoolseUserProfile \| null> \| PoolseUserProfile \| null` | —                                 | Optional. Resolve the tenant's own user identifier (`external_id` — same string you pass when minting JWTs) to `{ displayName, avatarUrl }` from your app's user data. The UI packages pick this up automatically. |
 
 ## REST surface
 

package/dist/index.cjs

@@ -2,6 +2,27 @@
 
 var phoenix = require('phoenix');
 
+// src/uuid.ts
+function safeUuid() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (c?.getRandomValues) {
+    c.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < 16; i++) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = [];
+  for (let i = 0; i < 16; i++) {
+    hex.push(bytes[i].toString(16).padStart(2, "0"));
+  }
+  return hex.slice(0, 4).join("") + "-" + hex.slice(4, 6).join("") + "-" + hex.slice(6, 8).join("") + "-" + hex.slice(8, 10).join("") + "-" + hex.slice(10).join("");
+}
+
 // src/config.ts
 var POOLSE_API_URL = "https://api.poolse.dev";
 var DEFAULT_MAX_RETRIES = 3;
@@ -36,13 +57,7 @@ function trimTrailingSlash(s) {
   return s.endsWith("/") ? s.slice(0, -1) : s;
 }
 function defaultIdempotencyKey() {
-  const c = globalThis.crypto;
-  if (c && typeof c.randomUUID === "function") {
-    return c.randomUUID();
-  }
-  throw new Error(
-    "Poolse: globalThis.crypto.randomUUID() is not available; supply `config.generateIdempotencyKey` instead."
-  );
+  return safeUuid();
 }
 
 // src/errors.ts
@@ -665,13 +680,7 @@ var MessagesResource = class {
   }
 };
 function generateClientMessageId() {
-  const c = globalThis.crypto;
-  if (c && typeof c.randomUUID === "function") {
-    return c.randomUUID();
-  }
-  throw new Error(
-    "Poolse: globalThis.crypto.randomUUID() unavailable \u2014 pass `id` explicitly in MessageCreateRequest (your env lacks a built-in UUID generator)."
-  );
+  return safeUuid();
 }
 
 // src/resources/conversations.ts
@@ -815,55 +824,55 @@ var UsersResource = class {
    * "not in cache yet" (different from `null`, which means "resolver
    * ran and the user wasn't found").
    */
-  peek(userId) {
-    return this.cache.get(userId);
+  peek(externalId) {
+    return this.cache.get(externalId);
   }
   /**
    * Resolve a user, hitting the customer's `userResolver` on cache
-   * miss. Concurrent calls for the same id share one Promise.
+   * miss. Concurrent calls for the same external_id share one Promise.
    */
-  async get(userId) {
-    if (this.cache.has(userId)) {
-      return this.cache.get(userId) ?? null;
+  async get(externalId) {
+    if (this.cache.has(externalId)) {
+      return this.cache.get(externalId) ?? null;
     }
-    const existingPending = this.pending.get(userId);
+    const existingPending = this.pending.get(externalId);
     if (existingPending) return existingPending;
     const resolver = this.config.userResolver;
     if (!resolver) {
-      this.cache.set(userId, null);
-      this.notify(userId);
+      this.cache.set(externalId, null);
+      this.notify(externalId);
       return null;
     }
-    const promise = Promise.resolve().then(() => resolver(userId)).then(
+    const promise = Promise.resolve().then(() => resolver(externalId)).then(
       (profile) => {
-        this.cache.set(userId, profile ?? null);
-        this.pending.delete(userId);
-        this.notify(userId);
+        this.cache.set(externalId, profile ?? null);
+        this.pending.delete(externalId);
+        this.notify(externalId);
         return profile ?? null;
       },
       (err) => {
-        console.error("[poolse] userResolver failed for", userId, err);
-        this.cache.set(userId, null);
-        this.pending.delete(userId);
-        this.notify(userId);
+        console.error("[poolse] userResolver failed for", externalId, err);
+        this.cache.set(externalId, null);
+        this.pending.delete(externalId);
+        this.notify(externalId);
         return null;
       }
     );
-    this.pending.set(userId, promise);
+    this.pending.set(externalId, promise);
     return promise;
   }
   /**
-   * Subscribe to changes for a single user id. The listener fires
+   * Subscribe to changes for a single external_id. The listener fires
    * when the resolver lands (or when the entry is invalidated).
    * Returns an unsubscribe.
    *
    * `useUser` in @poolse/react uses this with `useSyncExternalStore`.
    */
-  subscribe(userId, listener) {
-    let set = this.listeners.get(userId);
+  subscribe(externalId, listener) {
+    let set = this.listeners.get(externalId);
     if (!set) {
       set = /* @__PURE__ */ new Set();
-      this.listeners.set(userId, set);
+      this.listeners.set(externalId, set);
     }
     set.add(listener);
     return () => {
@@ -871,10 +880,10 @@ var UsersResource = class {
     };
   }
   /** Drop a single cached entry — next `get` re-fetches via the resolver. */
-  invalidate(userId) {
-    this.cache.delete(userId);
-    this.pending.delete(userId);
-    this.notify(userId);
+  invalidate(externalId) {
+    this.cache.delete(externalId);
+    this.pending.delete(externalId);
+    this.notify(externalId);
   }
   /**
    * Drop the entire cache. Use after a sign-out, tenant swap, or any
@@ -884,12 +893,12 @@ var UsersResource = class {
   invalidateAll() {
     this.cache.clear();
     this.pending.clear();
-    for (const userId of this.listeners.keys()) {
-      this.notify(userId);
+    for (const externalId of this.listeners.keys()) {
+      this.notify(externalId);
     }
   }
-  notify(userId) {
-    const set = this.listeners.get(userId);
+  notify(externalId) {
+    const set = this.listeners.get(externalId);
     if (!set) return;
     for (const l of set) l();
   }
@@ -1172,7 +1181,7 @@ var Poolse = class {
 };
 
 // src/version.ts
-var version = "1.1.0";
+var version = "2.0.1";
 
 exports.ApiError = ApiError;
 exports.AttachmentHandle = AttachmentHandle;
@@ -1193,6 +1202,7 @@ exports.PoolseRealtime = PoolseRealtime;
 exports.RateLimitedError = RateLimitedError;
 exports.UserChannel = UserChannel;
 exports.UsersResource = UsersResource;
+exports.safeUuid = safeUuid;
 exports.version = version;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map