@poolse/sdk 1.1.0 → 2.0.1

package/dist/index.d.cts

@@ -77,7 +77,16 @@ type MemberRole = 'owner' | 'admin' | 'member';
 interface Membership {
     id: Uuid;
     conversation_id: Uuid;
+    /** Internal poolse user id. Most consumer code uses `external_id` instead. */
     user_id: Uuid;
+    /**
+     * The tenant's own user identifier (the same string you pass as
+     * `external_id` when minting JWTs or referencing users in
+     * `member_external_ids`). Every user reference on the wire carries
+     * this so the SDK's `userResolver(externalId)` is a complete API
+     * — no need to maintain a `poolse_user_id` mapping on your side.
+     */
+    external_id: string;
     role: MemberRole;
     last_read_message_id: Uuid | null;
     last_read_at: IsoDateTime | null;
@@ -107,7 +116,15 @@ interface Message {
     id: Uuid;
     tenant_id: Uuid;
     conversation_id: Uuid;
+    /** Internal poolse user id of the sender. Null for system messages. */
     sender_id: Uuid | null;
+    /**
+     * The tenant's own user identifier for the sender — passed straight
+     * to `userResolver(externalId)` to render display name + avatar.
+     * Null for system messages, and null on read paths that didn't
+     * preload the sender (very rare; every client-facing path preloads).
+     */
+    sender_external_id: string | null;
     type: MessageType;
     body: string | null;
     reply_to_id: Uuid | null;
@@ -179,6 +196,8 @@ interface PoolseUserProfile {
 interface QuotedMessagePreview {
     id: Uuid;
     sender_id: Uuid | null;
+    /** Same external-id story as `Message.sender_external_id`. */
+    sender_external_id: string | null;
     /** Truncated to ~200 chars server-side; null when the original was deleted. */
     body: string | null;
     deleted_at: IsoDateTime | null;
@@ -351,32 +370,33 @@ interface PoolseConfig {
      */
     onSocketError?: (err: Error) => void;
     /**
-     * Resolve a poolse `user_id` to the customer's own user metadata
-     * (display name + avatar). Called by `chat.users.get(userId)` and
-     * the `useUser(userId)` React hook whenever a UI component needs
-     * to render a participant.
+     * Resolve the tenant's user identifier (`external_id` — same string
+     * you pass when minting JWTs and referencing users in
+     * `member_external_ids`) to the customer's own user metadata
+     * (display name + avatar). Called by `chat.users.get(externalId)`
+     * and the `useUser(externalId)` React hook whenever a UI component
+     * needs to render a participant.
      *
      * The SDK caches results in-memory and dedupes concurrent calls,
      * so a busy chat with 50 messages from 5 senders fires the
      * resolver 5 times — once per unique sender — not 50.
      *
-     * Customers typically hit their OWN backend here:
+     * Customers hit their OWN backend / store here, keyed by **their own
+     * user id** (no poolse uuid mapping required):
      *
-     *   userResolver: async (userId) => {
-     *     const u = await fetch(`/api/users/by-poolse-id/${userId}`)
-     *       .then((r) => r.json());
+     *   userResolver: async (externalId) => {
+     *     const u = await fetch(`/api/users/${externalId}`).then((r) => r.json());
      *     return { displayName: u.full_name, avatarUrl: u.avatar_url };
      *   }
      *
-     * Sync returns are fine when the customer already has the user
-     * data in memory (e.g., from a directory loaded at app boot):
+     * Sync returns are fine when the data's already in memory:
      *
-     *   userResolver: (userId) => directory[userId] ?? null
+     *   userResolver: (externalId) => directory[externalId] ?? null
      *
-     * Return `null` when the user can't be found — components fall
-     * back to a userId-derived label and an initials avatar.
+     * Return `null` when the user can't be found — components fall back
+     * to the external_id as a label and an initials avatar.
      */
-    userResolver?: (userId: string) => Promise<PoolseUserProfile | null> | PoolseUserProfile | null;
+    userResolver?: (externalId: string) => Promise<PoolseUserProfile | null> | PoolseUserProfile | null;
 }
 /** Internal resolved config — all the defaults filled in. */
 interface ResolvedConfig {
@@ -432,7 +452,10 @@ interface MessageDeletedEvent {
 }
 /** `typing:start` / `typing:stop`. */
 interface TypingEvent {
+    /** Internal poolse user id. Most consumer code uses `external_id` instead. */
     user_id: Uuid;
+    /** The tenant's own id — what your `userResolver` consumes. */
+    external_id: string | null;
 }
 /** `reaction:added` / `reaction:removed`. */
 interface ReactionEvent {
@@ -880,22 +903,22 @@ declare class UsersResource {
      * "not in cache yet" (different from `null`, which means "resolver
      * ran and the user wasn't found").
      */
-    peek(userId: string): PoolseUserProfile | null | undefined;
+    peek(externalId: string): PoolseUserProfile | null | undefined;
     /**
      * 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.
      */
-    get(userId: string): Promise<PoolseUserProfile | null>;
+    get(externalId: string): Promise<PoolseUserProfile | null>;
     /**
-     * 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: string, listener: Listener): () => void;
+    subscribe(externalId: string, listener: Listener): () => void;
     /** Drop a single cached entry — next `get` re-fetches via the resolver. */
-    invalidate(userId: string): void;
+    invalidate(externalId: string): void;
     /**
      * Drop the entire cache. Use after a sign-out, tenant swap, or any
      * other event that invalidates every cached profile (e.g., the
@@ -993,6 +1016,8 @@ declare class AuthError extends ApiError {
     constructor(envelope: ErrorEnvelope['error']);
 }
 
-declare const version = "1.1.0";
+declare const version = "2.0.1";
+
+declare function safeUuid(): string;
 
-export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type Conversation, ConversationChannel, type ConversationCreateRequest, type ConversationCreatedEvent, ConversationHandle, type ConversationList, ConversationMessages, type ConversationType, type ConversationUpdateRequest, ConversationsResource, type ErrorEnvelope, type IsoDateTime, type Me, MeResource, type MemberReadEvent, type MemberRole, type Membership, type MembershipCreateRequest, type MembershipList, type MentionEvent, type Message, type MessageCreateRequest, type MessageDeletedEvent, MessageHandle, type MessageList, type MessageNewEvent, type MessageType, type MessageUpdateRequest, type MessageUpdatedEvent, MessagesResource, NetworkError, POOLSE_API_URL, Poolse, type PoolseConfig, PoolseError, PoolseRealtime, type PoolseUserProfile, type PresenceSnapshot, type QuotedMessagePreview, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type TypingEvent, type Unsubscribe, UserChannel, UsersResource, type Uuid, version };
+export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type Conversation, ConversationChannel, type ConversationCreateRequest, type ConversationCreatedEvent, ConversationHandle, type ConversationList, ConversationMessages, type ConversationType, type ConversationUpdateRequest, ConversationsResource, type ErrorEnvelope, type IsoDateTime, type Me, MeResource, type MemberReadEvent, type MemberRole, type Membership, type MembershipCreateRequest, type MembershipList, type MentionEvent, type Message, type MessageCreateRequest, type MessageDeletedEvent, MessageHandle, type MessageList, type MessageNewEvent, type MessageType, type MessageUpdateRequest, type MessageUpdatedEvent, MessagesResource, NetworkError, POOLSE_API_URL, Poolse, type PoolseConfig, PoolseError, PoolseRealtime, type PoolseUserProfile, type PresenceSnapshot, type QuotedMessagePreview, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type TypingEvent, type Unsubscribe, UserChannel, UsersResource, type Uuid, safeUuid, version };

package/dist/index.d.ts

@@ -77,7 +77,16 @@ type MemberRole = 'owner' | 'admin' | 'member';
 interface Membership {
     id: Uuid;
     conversation_id: Uuid;
+    /** Internal poolse user id. Most consumer code uses `external_id` instead. */
     user_id: Uuid;
+    /**
+     * The tenant's own user identifier (the same string you pass as
+     * `external_id` when minting JWTs or referencing users in
+     * `member_external_ids`). Every user reference on the wire carries
+     * this so the SDK's `userResolver(externalId)` is a complete API
+     * — no need to maintain a `poolse_user_id` mapping on your side.
+     */
+    external_id: string;
     role: MemberRole;
     last_read_message_id: Uuid | null;
     last_read_at: IsoDateTime | null;
@@ -107,7 +116,15 @@ interface Message {
     id: Uuid;
     tenant_id: Uuid;
     conversation_id: Uuid;
+    /** Internal poolse user id of the sender. Null for system messages. */
     sender_id: Uuid | null;
+    /**
+     * The tenant's own user identifier for the sender — passed straight
+     * to `userResolver(externalId)` to render display name + avatar.
+     * Null for system messages, and null on read paths that didn't
+     * preload the sender (very rare; every client-facing path preloads).
+     */
+    sender_external_id: string | null;
     type: MessageType;
     body: string | null;
     reply_to_id: Uuid | null;
@@ -179,6 +196,8 @@ interface PoolseUserProfile {
 interface QuotedMessagePreview {
     id: Uuid;
     sender_id: Uuid | null;
+    /** Same external-id story as `Message.sender_external_id`. */
+    sender_external_id: string | null;
     /** Truncated to ~200 chars server-side; null when the original was deleted. */
     body: string | null;
     deleted_at: IsoDateTime | null;
@@ -351,32 +370,33 @@ interface PoolseConfig {
      */
     onSocketError?: (err: Error) => void;
     /**
-     * Resolve a poolse `user_id` to the customer's own user metadata
-     * (display name + avatar). Called by `chat.users.get(userId)` and
-     * the `useUser(userId)` React hook whenever a UI component needs
-     * to render a participant.
+     * Resolve the tenant's user identifier (`external_id` — same string
+     * you pass when minting JWTs and referencing users in
+     * `member_external_ids`) to the customer's own user metadata
+     * (display name + avatar). Called by `chat.users.get(externalId)`
+     * and the `useUser(externalId)` React hook whenever a UI component
+     * needs to render a participant.
      *
      * The SDK caches results in-memory and dedupes concurrent calls,
      * so a busy chat with 50 messages from 5 senders fires the
      * resolver 5 times — once per unique sender — not 50.
      *
-     * Customers typically hit their OWN backend here:
+     * Customers hit their OWN backend / store here, keyed by **their own
+     * user id** (no poolse uuid mapping required):
      *
-     *   userResolver: async (userId) => {
-     *     const u = await fetch(`/api/users/by-poolse-id/${userId}`)
-     *       .then((r) => r.json());
+     *   userResolver: async (externalId) => {
+     *     const u = await fetch(`/api/users/${externalId}`).then((r) => r.json());
      *     return { displayName: u.full_name, avatarUrl: u.avatar_url };
      *   }
      *
-     * Sync returns are fine when the customer already has the user
-     * data in memory (e.g., from a directory loaded at app boot):
+     * Sync returns are fine when the data's already in memory:
      *
-     *   userResolver: (userId) => directory[userId] ?? null
+     *   userResolver: (externalId) => directory[externalId] ?? null
      *
-     * Return `null` when the user can't be found — components fall
-     * back to a userId-derived label and an initials avatar.
+     * Return `null` when the user can't be found — components fall back
+     * to the external_id as a label and an initials avatar.
      */
-    userResolver?: (userId: string) => Promise<PoolseUserProfile | null> | PoolseUserProfile | null;
+    userResolver?: (externalId: string) => Promise<PoolseUserProfile | null> | PoolseUserProfile | null;
 }
 /** Internal resolved config — all the defaults filled in. */
 interface ResolvedConfig {
@@ -432,7 +452,10 @@ interface MessageDeletedEvent {
 }
 /** `typing:start` / `typing:stop`. */
 interface TypingEvent {
+    /** Internal poolse user id. Most consumer code uses `external_id` instead. */
     user_id: Uuid;
+    /** The tenant's own id — what your `userResolver` consumes. */
+    external_id: string | null;
 }
 /** `reaction:added` / `reaction:removed`. */
 interface ReactionEvent {
@@ -880,22 +903,22 @@ declare class UsersResource {
      * "not in cache yet" (different from `null`, which means "resolver
      * ran and the user wasn't found").
      */
-    peek(userId: string): PoolseUserProfile | null | undefined;
+    peek(externalId: string): PoolseUserProfile | null | undefined;
     /**
      * 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.
      */
-    get(userId: string): Promise<PoolseUserProfile | null>;
+    get(externalId: string): Promise<PoolseUserProfile | null>;
     /**
-     * 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: string, listener: Listener): () => void;
+    subscribe(externalId: string, listener: Listener): () => void;
     /** Drop a single cached entry — next `get` re-fetches via the resolver. */
-    invalidate(userId: string): void;
+    invalidate(externalId: string): void;
     /**
      * Drop the entire cache. Use after a sign-out, tenant swap, or any
      * other event that invalidates every cached profile (e.g., the
@@ -993,6 +1016,8 @@ declare class AuthError extends ApiError {
     constructor(envelope: ErrorEnvelope['error']);
 }
 
-declare const version = "1.1.0";
+declare const version = "2.0.1";
+
+declare function safeUuid(): string;
 
-export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type Conversation, ConversationChannel, type ConversationCreateRequest, type ConversationCreatedEvent, ConversationHandle, type ConversationList, ConversationMessages, type ConversationType, type ConversationUpdateRequest, ConversationsResource, type ErrorEnvelope, type IsoDateTime, type Me, MeResource, type MemberReadEvent, type MemberRole, type Membership, type MembershipCreateRequest, type MembershipList, type MentionEvent, type Message, type MessageCreateRequest, type MessageDeletedEvent, MessageHandle, type MessageList, type MessageNewEvent, type MessageType, type MessageUpdateRequest, type MessageUpdatedEvent, MessagesResource, NetworkError, POOLSE_API_URL, Poolse, type PoolseConfig, PoolseError, PoolseRealtime, type PoolseUserProfile, type PresenceSnapshot, type QuotedMessagePreview, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type TypingEvent, type Unsubscribe, UserChannel, UsersResource, type Uuid, version };
+export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type Conversation, ConversationChannel, type ConversationCreateRequest, type ConversationCreatedEvent, ConversationHandle, type ConversationList, ConversationMessages, type ConversationType, type ConversationUpdateRequest, ConversationsResource, type ErrorEnvelope, type IsoDateTime, type Me, MeResource, type MemberReadEvent, type MemberRole, type Membership, type MembershipCreateRequest, type MembershipList, type MentionEvent, type Message, type MessageCreateRequest, type MessageDeletedEvent, MessageHandle, type MessageList, type MessageNewEvent, type MessageType, type MessageUpdateRequest, type MessageUpdatedEvent, MessagesResource, NetworkError, POOLSE_API_URL, Poolse, type PoolseConfig, PoolseError, PoolseRealtime, type PoolseUserProfile, type PresenceSnapshot, type QuotedMessagePreview, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type TypingEvent, type Unsubscribe, UserChannel, UsersResource, type Uuid, safeUuid, version };

package/dist/index.js

@@ -1,5 +1,26 @@
 import { Socket } from '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;
@@ -34,13 +55,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
@@ -663,13 +678,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
@@ -813,55 +822,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 () => {
@@ -869,10 +878,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
@@ -882,12 +891,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();
   }
@@ -1170,8 +1179,8 @@ var Poolse = class {
 };
 
 // src/version.ts
-var version = "1.1.0";
+var version = "2.0.1";
 
-export { ApiError, AttachmentHandle, AttachmentsResource, AuthError, ConversationChannel, ConversationHandle, ConversationMessages, ConversationsResource, MeResource, MessageHandle, MessagesResource, NetworkError, POOLSE_API_URL, Poolse, PoolseError, PoolseRealtime, RateLimitedError, UserChannel, UsersResource, version };
+export { ApiError, AttachmentHandle, AttachmentsResource, AuthError, ConversationChannel, ConversationHandle, ConversationMessages, ConversationsResource, MeResource, MessageHandle, MessagesResource, NetworkError, POOLSE_API_URL, Poolse, PoolseError, PoolseRealtime, RateLimitedError, UserChannel, UsersResource, safeUuid, version };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map