@poolse/sdk 1.1.0 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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
@@ -73,7 +75,7 @@ chat.destroy(); // closes WebSocket, leaves every joined channel
 | `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. |
+| `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

@@ -815,55 +815,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 +871,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 +884,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 +1172,7 @@ var Poolse = class {
 };
 
 // src/version.ts
-var version = "1.1.0";
+var version = "2.0.0";
 
 exports.ApiError = ApiError;
 exports.AttachmentHandle = AttachmentHandle;