@poolse/sdk 0.2.0-alpha.7 → 1.0.0-rc.0

package/dist/index.d.cts

@@ -1,120 +1,5 @@
 import { Channel } from 'phoenix';
 
-/**
- * Hosted poolse API URL. Used as the default for `PoolseConfig.apiUrl`
- * when you don't pass one — appropriate for the vast majority of
- * integrations that target the official poolse cloud. Self-hosted /
- * staging deployments override via the `apiUrl` field.
- */
-declare const POOLSE_API_URL = "https://api.poolse.dev";
-/**
- * SDK configuration passed to `new Poolse(config)`.
- */
-interface PoolseConfig {
-    /**
-     * Base URL of the poolse REST API. Defaults to the hosted endpoint
-     * at `https://api.poolse.dev`. Override only for self-hosted /
-     * staging deployments. MUST NOT include the `/v1` path — the SDK
-     * adds that itself.
-     */
-    apiUrl?: string;
-    /**
-     * Async hook the SDK calls every time it needs an `Authorization:
-     * Bearer <jwt>` header. Most apps refresh the JWT from their own
-     * backend here — the SDK never talks to poolse's `POST
-     * /v1/users/:user_id/tokens` itself (that endpoint is API-key-authed
-     * and lives on the Customer's BACKEND, not the End User's device).
-     *
-     * Return `null` to deliberately make an unauthenticated request — the
-     * server will reject it, but the SDK won't error inside `getToken`.
-     */
-    getToken: () => Promise<string | null> | string | null;
-    /**
-     * Optional fetch override. Browsers and Node 22+ both ship a global
-     * `fetch`, but tests can inject a mock here; bundlers in restricted
-     * environments can supply a polyfill.
-     */
-    fetch?: typeof globalThis.fetch;
-    /**
-     * Retry budget for transient failures (network + 5xx + 429). Defaults
-     * to 3 attempts after the initial request. Set to 0 to disable.
-     */
-    maxRetries?: number;
-    /**
-     * Base for the exponential backoff, in milliseconds. Each retry waits
-     * `min(maxBackoffMs, baseBackoffMs * 2^attempt)` plus jitter, OR honours
-     * the `Retry-After` header if present. Default 250 ms.
-     */
-    baseBackoffMs?: number;
-    /** Hard cap on a single retry delay. Default 30_000 ms. */
-    maxBackoffMs?: number;
-    /**
-     * Override the idempotency-key generator. Defaults to
-     * `crypto.randomUUID()`. Most apps don't need to override this — the
-     * generator is exposed mainly for deterministic tests.
-     */
-    generateIdempotencyKey?: () => string;
-    /**
-     * Override the WebSocket URL. Defaults to `apiUrl` with `http(s)://`
-     * swapped to `ws(s)://`, suitable when the realtime gateway shares
-     * its origin with the REST API. Set explicitly for split-host
-     * deployments (`https://api.example.com` REST + `wss://realtime.example.com` WS).
-     */
-    wsUrl?: string;
-    /**
-     * Path the WebSocket is mounted on. Defaults to `/socket` — matches
-     * `CaasRealtimeWeb.UserSocket`'s mount point.
-     */
-    socketPath?: string;
-    /**
-     * Called when the underlying socket encounters a non-fatal error
-     * (Phoenix retries internally). Useful for surfacing reconnect
-     * banners in the UI without coupling to socket internals.
-     */
-    onSocketError?: (err: Error) => void;
-}
-/** Internal resolved config — all the defaults filled in. */
-interface ResolvedConfig {
-    apiUrl: string;
-    getToken: PoolseConfig['getToken'];
-    fetch: typeof globalThis.fetch;
-    maxRetries: number;
-    baseBackoffMs: number;
-    maxBackoffMs: number;
-    generateIdempotencyKey: () => string;
-    wsUrl: string | undefined;
-    socketPath: string;
-    onSocketError: ((err: Error) => void) | undefined;
-}
-
-type Fetcher = PoolseConfig['getToken'];
-interface GetTokenOptions {
-    /** Bypass the cache and force a fresh call to the consumer's `getToken`. */
-    forceRefresh?: boolean;
-}
-declare class TokenCache {
-    private readonly fetcher;
-    private token;
-    private expMs;
-    private inFlight;
-    constructor(fetcher: Fetcher);
-    /**
-     * Synchronously return the cached token without triggering a fetch.
-     * Returns `null` if the cache is empty OR if the cached token is
-     * within the refresh window (treating near-expiry tokens as stale
-     * keeps the realtime layer from handshaking with an about-to-expire
-     * JWT when a refresh is already due).
-     *
-     * Exists for callers like Phoenix.js's `params` callback that the
-     * library invokes synchronously and does NOT await — see
-     * `phoenix/priv/static/phoenix.mjs::endPointURL()`.
-     */
-    peekToken(): string | null;
-    getToken(opts?: GetTokenOptions): Promise<string | null>;
-    invalidate(): void;
-    private fetchAndStore;
-}
-
 type Uuid = string;
 type IsoDateTime = string;
 interface Me {
@@ -262,6 +147,30 @@ interface Message {
     inserted_at: IsoDateTime;
     updated_at: IsoDateTime;
 }
+/**
+ * Customer-supplied user metadata — the SDK doesn't know your users'
+ * names or where their avatars live. Customers wire a
+ * `PoolseConfig.userResolver` that maps a poolse `Uuid` to whatever
+ * their app already stores: a display name, an avatar URL.
+ *
+ * The SDK caches resolved profiles in-memory (deduplicating
+ * concurrent lookups) so a 50-message render only fires one
+ * resolver call per unique sender.
+ */
+interface PoolseUserProfile {
+    /**
+     * The name shown in sender labels, mention dropdowns, member
+     * lists, and read-receipt tooltips. Customers usually pass their
+     * app's `display_name` / `username` / `full_name`.
+     */
+    displayName: string;
+    /**
+     * Square avatar URL (any size — the UI scales). Null = render the
+     * fallback `<Avatar>` with initials. Optional so customers that
+     * don't track avatars can omit the field.
+     */
+    avatarUrl?: string | null;
+}
 /**
  * Compact preview of a quoted message, embedded on the quoting
  * message when `Message.quoted_message_id` is set. Just enough for
@@ -368,6 +277,150 @@ interface ErrorEnvelope {
     };
 }
 
+/**
+ * Hosted poolse API URL. Used as the default for `PoolseConfig.apiUrl`
+ * when you don't pass one — appropriate for the vast majority of
+ * integrations that target the official poolse cloud. Self-hosted /
+ * staging deployments override via the `apiUrl` field.
+ */
+declare const POOLSE_API_URL = "https://api.poolse.dev";
+
+/**
+ * SDK configuration passed to `new Poolse(config)`.
+ */
+interface PoolseConfig {
+    /**
+     * Base URL of the poolse REST API. Defaults to the hosted endpoint
+     * at `https://api.poolse.dev`. Override only for self-hosted /
+     * staging deployments. MUST NOT include the `/v1` path — the SDK
+     * adds that itself.
+     */
+    apiUrl?: string;
+    /**
+     * Async hook the SDK calls every time it needs an `Authorization:
+     * Bearer <jwt>` header. Most apps refresh the JWT from their own
+     * backend here — the SDK never talks to poolse's `POST
+     * /v1/users/:user_id/tokens` itself (that endpoint is API-key-authed
+     * and lives on the Customer's BACKEND, not the End User's device).
+     *
+     * Return `null` to deliberately make an unauthenticated request — the
+     * server will reject it, but the SDK won't error inside `getToken`.
+     */
+    getToken: () => Promise<string | null> | string | null;
+    /**
+     * Optional fetch override. Browsers and Node 22+ both ship a global
+     * `fetch`, but tests can inject a mock here; bundlers in restricted
+     * environments can supply a polyfill.
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Retry budget for transient failures (network + 5xx + 429). Defaults
+     * to 3 attempts after the initial request. Set to 0 to disable.
+     */
+    maxRetries?: number;
+    /**
+     * Base for the exponential backoff, in milliseconds. Each retry waits
+     * `min(maxBackoffMs, baseBackoffMs * 2^attempt)` plus jitter, OR honours
+     * the `Retry-After` header if present. Default 250 ms.
+     */
+    baseBackoffMs?: number;
+    /** Hard cap on a single retry delay. Default 30_000 ms. */
+    maxBackoffMs?: number;
+    /**
+     * Override the idempotency-key generator. Defaults to
+     * `crypto.randomUUID()`. Most apps don't need to override this — the
+     * generator is exposed mainly for deterministic tests.
+     */
+    generateIdempotencyKey?: () => string;
+    /**
+     * Override the WebSocket URL. Defaults to `apiUrl` with `http(s)://`
+     * swapped to `ws(s)://`, suitable when the realtime gateway shares
+     * its origin with the REST API. Set explicitly for split-host
+     * deployments (`https://api.example.com` REST + `wss://realtime.example.com` WS).
+     */
+    wsUrl?: string;
+    /**
+     * Path the WebSocket is mounted on. Defaults to `/socket` — matches
+     * `CaasRealtimeWeb.UserSocket`'s mount point.
+     */
+    socketPath?: string;
+    /**
+     * Called when the underlying socket encounters a non-fatal error
+     * (Phoenix retries internally). Useful for surfacing reconnect
+     * banners in the UI without coupling to socket internals.
+     */
+    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.
+     *
+     * 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:
+     *
+     *   userResolver: async (userId) => {
+     *     const u = await fetch(`/api/users/by-poolse-id/${userId}`)
+     *       .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):
+     *
+     *   userResolver: (userId) => directory[userId] ?? null
+     *
+     * Return `null` when the user can't be found — components fall
+     * back to a userId-derived label and an initials avatar.
+     */
+    userResolver?: (userId: string) => Promise<PoolseUserProfile | null> | PoolseUserProfile | null;
+}
+/** Internal resolved config — all the defaults filled in. */
+interface ResolvedConfig {
+    apiUrl: string;
+    getToken: PoolseConfig['getToken'];
+    fetch: typeof globalThis.fetch;
+    maxRetries: number;
+    baseBackoffMs: number;
+    maxBackoffMs: number;
+    generateIdempotencyKey: () => string;
+    wsUrl: string | undefined;
+    socketPath: string;
+    onSocketError: ((err: Error) => void) | undefined;
+    userResolver: PoolseConfig['userResolver'];
+}
+
+type Fetcher = PoolseConfig['getToken'];
+interface GetTokenOptions {
+    /** Bypass the cache and force a fresh call to the consumer's `getToken`. */
+    forceRefresh?: boolean;
+}
+declare class TokenCache {
+    private readonly fetcher;
+    private token;
+    private expMs;
+    private inFlight;
+    constructor(fetcher: Fetcher);
+    /**
+     * Synchronously return the cached token without triggering a fetch.
+     * Returns `null` if the cache is empty OR if the cached token is
+     * within the refresh window (treating near-expiry tokens as stale
+     * keeps the realtime layer from handshaking with an about-to-expire
+     * JWT when a refresh is already due).
+     *
+     * Exists for callers like Phoenix.js's `params` callback that the
+     * library invokes synchronously and does NOT await — see
+     * `phoenix/priv/static/phoenix.mjs::endPointURL()`.
+     */
+    peekToken(): string | null;
+    getToken(opts?: GetTokenOptions): Promise<string | null>;
+    invalidate(): void;
+    private fetchAndStore;
+}
+
 /** `message:new` / `message:updated` push payloads. */
 type MessageNewEvent = Message;
 type MessageUpdatedEvent = Message;
@@ -612,6 +665,23 @@ interface AttachmentUploadInput {
 /** Options accepted by every attachment method. */
 interface AttachmentOptions {
     signal?: AbortSignal;
+    /**
+     * Progress callback for `upload()`. Called periodically during the
+     * PUT phase (NOT during the presigned-URL request — that's a small
+     * JSON round-trip). When set, the SDK switches to XHR for the PUT
+     * since the standard `fetch` doesn't expose upload progress events.
+     *
+     * Customers using a custom `config.fetch` (e.g. node-fetch polyfill)
+     * lose progress reporting and the callback never fires — XHR is
+     * a browser-only API.
+     */
+    onProgress?: (event: AttachmentProgressEvent) => void;
+}
+interface AttachmentProgressEvent {
+    /** Bytes uploaded so far. */
+    loaded: number;
+    /** Total bytes — equals `input.byteSize` (passed back for convenience). */
+    total: number;
 }
 /** Top-level `/v1/attachments` collection. */
 declare class AttachmentsResource {
@@ -794,6 +864,43 @@ declare class MeResource {
     show(signal?: AbortSignal): Promise<Me>;
 }
 
+type Listener = () => void;
+declare class UsersResource {
+    private readonly config;
+    private readonly cache;
+    private readonly pending;
+    private readonly listeners;
+    constructor(config: ResolvedConfig);
+    /**
+     * Get the cached value if present. Returns `undefined` to mean
+     * "not in cache yet" (different from `null`, which means "resolver
+     * ran and the user wasn't found").
+     */
+    peek(userId: string): PoolseUserProfile | null | undefined;
+    /**
+     * Resolve a user, hitting the customer's `userResolver` on cache
+     * miss. Concurrent calls for the same id share one Promise.
+     */
+    get(userId: string): Promise<PoolseUserProfile | null>;
+    /**
+     * Subscribe to changes for a single user 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;
+    /** Drop a single cached entry — next `get` re-fetches via the resolver. */
+    invalidate(userId: 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
+     * customer just renamed every user in bulk).
+     */
+    invalidateAll(): void;
+    private notify;
+}
+
 declare class Poolse {
     /** `/v1/me` — current End User. */
     readonly me: MeResource;
@@ -803,6 +910,17 @@ declare class Poolse {
     readonly messages: MessagesResource;
     /** `/v1/attachments/*` — presigned-URL uploads/downloads. */
     readonly attachments: AttachmentsResource;
+    /**
+     * Customer-supplied user metadata, cached + dedup'd.
+     * `chat.users.get(userId)` returns `{ displayName, avatarUrl }`
+     * via the optional `config.userResolver`. UI components
+     * (`MessageBubble`, `MemberList`, `TypingIndicator`) pick this up
+     * automatically via the `useUser` hook in `@poolse/react`.
+     *
+     * If no resolver is configured, `get` always returns `null` and
+     * UI falls back to the userId slice + initials avatar.
+     */
+    readonly users: UsersResource;
     /**
      * Low-level REST client. Exposed for advanced use cases (custom endpoints,
      * raw retry/headers control). Most callers should use the resources above.
@@ -871,6 +989,6 @@ declare class AuthError extends ApiError {
     constructor(envelope: ErrorEnvelope['error']);
 }
 
-declare const version = "0.0.1";
+declare const version = "1.0.0-rc.0";
 
-export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, 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 PresenceSnapshot, type QuotedMessagePreview, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type TypingEvent, type Unsubscribe, UserChannel, 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, version };