@poolse/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,775 @@
+import { Channel } from 'phoenix';
+
+/**
+ * SDK configuration passed to `new Poolse(config)`.
+ */
+interface PoolseConfig {
+    /**
+     * Base URL of the poolse REST API, e.g. `https://chat.example.com`.
+     * 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 {
+    id: Uuid;
+    tenant_id: Uuid;
+    external_id: string;
+    display_name: string | null;
+    custom_data: Record<string, unknown>;
+    is_blocked: boolean;
+    inserted_at: IsoDateTime;
+    updated_at: IsoDateTime;
+}
+type ConversationType = 'direct' | 'group';
+interface Conversation {
+    id: Uuid;
+    tenant_id: Uuid;
+    type: ConversationType;
+    /** Display name (for group chats); null for unnamed conversations. */
+    name: string | null;
+    /** Public avatar URL; null when none uploaded. */
+    avatar_url: string | null;
+    /** User that created the conversation; null for system-created rows. */
+    created_by_user_id: Uuid | null;
+    /** Hard cap on memberships; null = unlimited (tenant default). */
+    member_limit: number | null;
+    /**
+     * Customer-supplied free-form data — anything you want to attach to
+     * the conversation that doesn't fit the schema (UI flags, tags, etc).
+     * Server treats it as opaque JSON.
+     */
+    custom_data: Record<string, unknown>;
+    /**
+     * Server-defined behavioral knobs (notification rules, retention,
+     * etc). Defaults to `{}` and is updateable.
+     */
+    settings: Record<string, unknown>;
+    /** Most recent message's `inserted_at`; null until first message. */
+    last_message_at: IsoDateTime | null;
+    /** Monotonic per-conversation sequence counter (last message's `sequence`). */
+    last_sequence: number;
+    inserted_at: IsoDateTime;
+    updated_at: IsoDateTime;
+}
+interface ConversationList {
+    data: Conversation[];
+}
+interface ConversationCreateRequest {
+    type: ConversationType;
+    name?: string | null;
+    avatar_url?: string | null;
+    member_limit?: number | null;
+    /**
+     * Customer-side user IDs to add as members on creation — saves a
+     * round-trip vs creating then calling `addMembers`.
+     */
+    member_external_ids?: string[];
+    custom_data?: Record<string, unknown>;
+    settings?: Record<string, unknown>;
+}
+interface ConversationUpdateRequest {
+    name?: string | null;
+    avatar_url?: string | null;
+    member_limit?: number | null;
+    custom_data?: Record<string, unknown>;
+    settings?: Record<string, unknown>;
+}
+type MemberRole = 'owner' | 'admin' | 'member';
+interface Membership {
+    id: Uuid;
+    conversation_id: Uuid;
+    user_id: Uuid;
+    role: MemberRole;
+    last_read_message_id: Uuid | null;
+    last_read_at: IsoDateTime | null;
+    inserted_at: IsoDateTime;
+    updated_at: IsoDateTime;
+}
+interface MembershipList {
+    data: Membership[];
+}
+/**
+ * Server accepts a batch of `external_ids` (the customer's stable user
+ * identifiers — what was passed to `POST /v1/users`). The server
+ * resolves each to its internal user_id and creates a membership row
+ * per external_id, all in one round-trip. Optional `role` defaults to
+ * `"member"` server-side.
+ *
+ * Most callers use the higher-level
+ * `chat.conversations.one(id).addMember(externalId)` /
+ * `addMembers([externalIds])` methods which build this shape for you.
+ */
+interface MembershipCreateRequest {
+    external_ids: string[];
+    role?: MemberRole;
+}
+type MessageType = 'text' | 'system' | 'custom';
+interface Message {
+    id: Uuid;
+    tenant_id: Uuid;
+    conversation_id: Uuid;
+    sender_id: Uuid | null;
+    type: MessageType;
+    body: string | null;
+    reply_to_id: Uuid | null;
+    thread_root_id: Uuid | null;
+    mentions: Uuid[];
+    reactions: Record<string, Uuid[]>;
+    edited_at: IsoDateTime | null;
+    deleted_at: IsoDateTime | null;
+    sequence: number;
+    inserted_at: IsoDateTime;
+    updated_at: IsoDateTime;
+}
+interface MessageList {
+    data: Message[];
+}
+interface MessageCreateRequest {
+    body: string;
+    type?: MessageType;
+    reply_to_id?: Uuid;
+    mentions?: Uuid[];
+    id?: Uuid;
+}
+interface MessageUpdateRequest {
+    body: string;
+}
+interface ReadRequest {
+    message_id: Uuid;
+}
+interface ReactionRequest {
+    emoji: string;
+}
+type AttachmentStatus = 'pending' | 'ready';
+interface Attachment {
+    id: Uuid;
+    tenant_id: Uuid;
+    /** Linked message id; null while the attachment is still `:pending`. */
+    message_id: Uuid | null;
+    /** Uploader; null for system-created attachments. */
+    sender_id: Uuid | null;
+    content_type: string;
+    byte_size: number;
+    /** Server-computed SHA-256 of the uploaded bytes; populated after the PUT completes. */
+    sha256: string | null;
+    original_filename: string | null;
+    status: AttachmentStatus;
+    inserted_at: IsoDateTime;
+    updated_at: IsoDateTime;
+}
+interface AttachmentUploadRequest {
+    content_type: string;
+    byte_size: number;
+    original_filename?: string;
+}
+/** Presigned PUT payload returned by `POST /v1/attachments/upload-url`. */
+interface AttachmentUploadResponse {
+    attachment: Attachment;
+    upload: {
+        url: string;
+        method: 'put';
+        /** Headers the client MUST include on the PUT (signed into the URL). */
+        headers: Record<string, string>;
+    };
+}
+/** Presigned GET payload returned by `GET /v1/attachments/:id/download-url`. */
+interface AttachmentDownloadResponse {
+    url: string;
+    method: 'get';
+}
+interface ErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        doc_url: string;
+        details?: Record<string, unknown>;
+    };
+}
+
+/** `message:new` / `message:updated` push payloads. */
+type MessageNewEvent = Message;
+type MessageUpdatedEvent = Message;
+/** `message:deleted` push payload (just the tombstone, no body). */
+interface MessageDeletedEvent {
+    id: Uuid;
+    conversation_id: Uuid;
+    deleted_at: string | null;
+}
+/** `typing:start` / `typing:stop`. */
+interface TypingEvent {
+    user_id: Uuid;
+}
+/** `reaction:added` / `reaction:removed`. */
+interface ReactionEvent {
+    message_id: Uuid;
+    conversation_id: Uuid;
+    emoji: string;
+    user_id: Uuid;
+}
+/** Per-user mention push on the `user:<id>` channel. */
+interface MentionEvent {
+    message_id: Uuid;
+    conversation_id: Uuid;
+    sender_id: Uuid | null;
+}
+/**
+ * Pushed on `user:<id>` when the user is added to a conversation —
+ * either as creator (via `POST /v1/conversations`) or as additional
+ * member (via `POST /v1/conversations/:id/members`). Payload is the
+ * full conversation row.
+ */
+type ConversationCreatedEvent = Conversation;
+/** Phoenix Presence list shape. */
+type PresenceSnapshot = Record<Uuid, {
+    metas: Array<{
+        phx_ref: string;
+        online_at: number;
+        external_id?: string;
+    }>;
+}>;
+/**
+ * Connection status. Reflects the underlying socket lifecycle plus
+ * channel join state — easier for UIs than tracking both separately.
+ */
+type RealtimeStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
+/** Unsubscribe handle returned by `onX` listener registrations. */
+type Unsubscribe = () => void;
+
+interface RealtimeOptions {
+    /**
+     * WebSocket endpoint path (mounted in caas_realtime). Defaults to
+     * `'/socket'` — matches the path served by `CaasRealtimeWeb.UserSocket`.
+     */
+    socketPath?: string;
+    /**
+     * Override the Phoenix-derived WebSocket URL. Use when the realtime
+     * gateway lives on a different host than the REST API (most common
+     * in prod: `https://api.example.com` for REST, `wss://realtime.example.com`
+     * for WebSocket). When unset, the WS URL is derived from `apiUrl` by
+     * swapping http(s) → ws(s).
+     */
+    wsUrl?: string;
+}
+declare class PoolseRealtime {
+    private readonly config;
+    private readonly tokenCache;
+    private readonly socketPath;
+    private readonly wsUrl;
+    private socket;
+    private readonly conversations;
+    private userChannel;
+    private status;
+    private readonly statusListeners;
+    constructor(config: ResolvedConfig, tokenCache: TokenCache, opts?: RealtimeOptions);
+    /** Current connection status. */
+    getStatus(): RealtimeStatus;
+    /** Subscribe to connection-status changes. */
+    onStatus(listener: (status: RealtimeStatus) => void): Unsubscribe;
+    /**
+     * Open the socket (idempotent). Synchronous construction so callers
+     * can join a channel on the next line; the underlying WebSocket
+     * connects on the next tick once the JWT pre-fetch resolves.
+     *
+     * Phoenix.js invokes the `params` callback SYNCHRONOUSLY on every
+     * (re)connect and does NOT await its return value — see
+     * `phoenix/priv/static/phoenix.mjs::endPointURL`. So `params` has
+     * to read a token that's already in hand. We:
+     *
+     *   1. Construct the Socket immediately (sets `this.socket` so
+     *      concurrent `conversation()` / `user()` callers can attach
+     *      channels — Phoenix buffers joins until the socket opens).
+     *   2. Pre-fetch the JWT through `TokenCache`, which fills its
+     *      internal cache.
+     *   3. Call `socket.connect()` so phoenix.js's first handshake reads
+     *      a primed `peekToken()`.
+     *
+     * On reconnect, Phoenix calls `params()` again; the cache is still
+     * warm (default JWT exp ~1h, refresh window 30s) so `peekToken()`
+     * returns the live token. When the token genuinely expires, our
+     * REST 401 path invalidates the cache; the next reconnect's
+     * `peekToken()` is `null` and the handshake intentionally fails so
+     * the cache can re-fill on the next iteration.
+     */
+    connect(): void;
+    /** Close the socket and tear down every joined channel. */
+    disconnect(): void;
+    /**
+     * Subscribe to a conversation. Returns a typed handle with
+     * `onMessage`, `onTyping`, etc. Reusing the same `id` returns the
+     * same handle — re-subscribing doesn't open a second channel.
+     */
+    conversation(conversationId: string): ConversationChannel;
+    /**
+     * Subscribe to the current user's `user:<id>` channel. Only the user
+     * matching the JWT can join — poolse's UserChannel enforces this.
+     */
+    user(userId: string): UserChannel;
+    /** Drop a conversation handle and leave the channel. */
+    leave(conversationId: string): void;
+    private setStatus;
+}
+declare class ConversationChannel {
+    readonly conversationId: string;
+    private readonly channel;
+    private readonly listeners;
+    constructor(conversationId: string, channel: Channel);
+    /** New message pushed to the conversation. */
+    onMessage(fn: (msg: MessageNewEvent) => void): Unsubscribe;
+    /** Existing message edited by its sender. */
+    onMessageUpdated(fn: (msg: MessageUpdatedEvent) => void): Unsubscribe;
+    /** Tombstone for a soft-deleted message. */
+    onMessageDeleted(fn: (evt: MessageDeletedEvent) => void): Unsubscribe;
+    onTypingStart(fn: (evt: TypingEvent) => void): Unsubscribe;
+    onTypingStop(fn: (evt: TypingEvent) => void): Unsubscribe;
+    onReactionAdded(fn: (evt: ReactionEvent) => void): Unsubscribe;
+    onReactionRemoved(fn: (evt: ReactionEvent) => void): Unsubscribe;
+    onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe;
+    onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe;
+    /** Send a typing ping to the server. Debounced server-side. */
+    sendTyping(): void;
+    /** @internal — called by `PoolseRealtime.conversation/1`. */
+    _join(): void;
+    /** @internal — called when the consumer leaves this conversation. */
+    _destroy(): void;
+    private subscribe;
+}
+declare class UserChannel {
+    readonly userId: string;
+    private readonly channel;
+    private readonly mentionListeners;
+    private readonly conversationCreatedListeners;
+    private mentionBound;
+    private conversationCreatedBound;
+    constructor(userId: string, channel: Channel);
+    onMention(fn: (evt: MentionEvent) => void): Unsubscribe;
+    /**
+     * Subscribe to "you've been added to a conversation" notifications.
+     * Fires once per new membership — either because you created the
+     * conversation, or because someone added you to an existing one.
+     *
+     * Payload is the full {@link Conversation} row so consumers can
+     * prepend it to a local list without a refetch.
+     */
+    onConversationCreated(fn: (conv: ConversationCreatedEvent) => void): Unsubscribe;
+    /** @internal */
+    _join(): void;
+    /** @internal */
+    _destroy(): void;
+}
+
+type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+interface RequestOptions {
+    method: HttpMethod;
+    path: string;
+    /** JSON-serialisable body for non-GETs. Omit for GET/DELETE. */
+    body?: unknown;
+    /** Query string params; values are stringified, nullish entries dropped. */
+    query?: Record<string, string | number | boolean | null | undefined>;
+    /**
+     * Idempotency-Key override. Defaults to a fresh UUID for non-GETs.
+     * Pass `null` to deliberately omit the header (e.g. when the caller's
+     * own retry logic supplies a deterministic one).
+     */
+    idempotencyKey?: string | null;
+    /**
+     * Per-request override for total retry budget. Defaults to
+     * `config.maxRetries`.
+     */
+    maxRetries?: number;
+    /** AbortSignal for caller-driven cancellation. */
+    signal?: AbortSignal;
+}
+declare class RestClient {
+    private readonly config;
+    private readonly tokenCache;
+    constructor(config: ResolvedConfig, tokenCache: TokenCache);
+    request<T>(opts: RequestOptions): Promise<T>;
+    private buildUrl;
+    private buildHeaders;
+    private resolveIdempotencyKey;
+    private backoffDelay;
+}
+
+/** Input accepted by {@link AttachmentsResource.upload}. */
+interface AttachmentUploadInput {
+    /**
+     * The bytes to upload. Browser: pass a `File` or `Blob`. Node /
+     * Workers / Deno: a `Uint8Array`, `ArrayBuffer`, or any
+     * `BodyInit`-compatible value the runtime's `fetch` accepts as a
+     * PUT body.
+     */
+    body: BodyInit;
+    /**
+     * MIME type. MUST match what you pass as `content_type` on the
+     * upload-URL request (the storage backend signs it into the URL —
+     * a mismatch makes the PUT fail with 403).
+     */
+    contentType: string;
+    /** Total bytes — must match the bytes you actually PUT. */
+    byteSize: number;
+    /** Surfaced in download UX so saved files keep a sensible name. */
+    filename?: string;
+}
+/** Options accepted by every attachment method. */
+interface AttachmentOptions {
+    signal?: AbortSignal;
+}
+/** Top-level `/v1/attachments` collection. */
+declare class AttachmentsResource {
+    private readonly client;
+    private readonly fetchFn;
+    /**
+     * The PUT to the presigned URL bypasses the SDK's authenticated
+     * REST client (presigned URLs encode their own auth and MUST NOT
+     * receive an `Authorization` header). It still respects
+     * `config.fetch` if the customer provided one — required for tests
+     * with a mock fetch, and for runtimes where `globalThis.fetch` is
+     * not the right transport.
+     */
+    constructor(client: RestClient, fetchFn: typeof globalThis.fetch);
+    /**
+     * Step 1 of an upload — request a presigned PUT URL. Use this when
+     * you want to drive the PUT yourself (e.g. resumable uploads,
+     * React Native FileSystem). For the common case prefer
+     * {@link upload}, which does both steps for you.
+     */
+    requestUpload(attrs: AttachmentUploadRequest, opts?: AttachmentOptions): Promise<AttachmentUploadResponse>;
+    /**
+     * One-call upload: request a presigned URL, PUT the bytes to it,
+     * return the attachment row. After this resolves the attachment is
+     * ready to be referenced from a message send.
+     *
+     * ```ts
+     * // Browser <input type="file">:
+     * const file = inputEl.files![0]!;
+     * const att = await chat.attachments.upload({
+     *   body: file,
+     *   contentType: file.type,
+     *   byteSize: file.size,
+     *   filename: file.name,
+     * });
+     * await chat.conversations.one(convId).messages.send({
+     *   body: 'Look at this!',
+     *   custom_data: { attachment_id: att.id },
+     * });
+     * ```
+     *
+     * Note: the PUT uses the runtime's bare `fetch` (NOT the SDK's
+     * authenticated REST client) — presigned URLs already encode their
+     * own auth and MUST NOT receive an `Authorization` header.
+     */
+    upload(input: AttachmentUploadInput, opts?: AttachmentOptions): Promise<Attachment>;
+    /** Returns a handle for further operations on a single attachment. */
+    one(id: Uuid): AttachmentHandle;
+}
+/** Wraps an attachment id for download-url + delete. */
+declare class AttachmentHandle {
+    private readonly client;
+    readonly id: Uuid;
+    constructor(client: RestClient, id: Uuid);
+    /**
+     * Request a presigned GET URL (~1h TTL). Conversation-member-gated
+     * server-side. Useful when rendering files in chat: cache the URL
+     * client-side until close to expiry, then re-fetch.
+     */
+    downloadUrl(opts?: AttachmentOptions): Promise<AttachmentDownloadResponse>;
+    /**
+     * Delete the attachment row + best-effort bucket object delete.
+     * Authz: uploader (while still `:pending`) or message-sender / conv
+     * owner-admin (once linked).
+     */
+    delete(opts?: AttachmentOptions): Promise<void>;
+}
+
+/** Per-conversation message collection: send, list, mark-read. */
+declare class ConversationMessages {
+    private readonly client;
+    private readonly conversationId;
+    constructor(client: RestClient, conversationId: Uuid);
+    list(opts?: {
+        limit?: number;
+        before?: number;
+    }, signal?: AbortSignal): Promise<MessageList>;
+    /**
+     * Send a message to this conversation.
+     *
+     * If `attrs.id` is omitted the SDK generates a v4 UUID and uses it
+     * as both the wire-level idempotency key AND the literal message.id
+     * the server stores. Two side-effects that make a real-time UI
+     * trivial:
+     *
+     *   * Resending the same `id` (e.g. a network-retry) returns the
+     *     ORIGINAL message instead of inserting a duplicate.
+     *   * The realtime `message:new` broadcast carries this same id,
+     *     so an optimistic UI can pre-render the row under the final id
+     *     and dedup by id alone — no client/server id swap needed.
+     *
+     * Pass an explicit `attrs.id` only when you generated it yourself
+     * upstream (e.g. you already render an optimistic row in your hook
+     * and want the server to confirm under the same key).
+     */
+    send(attrs: MessageCreateRequest, signal?: AbortSignal): Promise<Message>;
+    markRead(messageId: Uuid, signal?: AbortSignal): Promise<void>;
+}
+/** Per-message operations: edit, delete, react, list replies. */
+declare class MessageHandle {
+    private readonly client;
+    readonly id: Uuid;
+    constructor(client: RestClient, id: Uuid);
+    update(attrs: MessageUpdateRequest, signal?: AbortSignal): Promise<Message>;
+    delete(signal?: AbortSignal): Promise<void>;
+    replies(opts?: {
+        limit?: number;
+        after?: number;
+    }, signal?: AbortSignal): Promise<MessageList>;
+    addReaction(emoji: string, signal?: AbortSignal): Promise<Message>;
+    removeReaction(emoji: string, signal?: AbortSignal): Promise<Message>;
+}
+/** Top-level `/v1/messages` namespace — accessed via `chat.messages(id)`. */
+declare class MessagesResource {
+    private readonly client;
+    constructor(client: RestClient);
+    one(id: Uuid): MessageHandle;
+}
+
+/** Optional knobs accepted by every member-add call. */
+interface AddMemberOptions {
+    /** Membership role — defaults to `"member"` server-side. */
+    role?: MemberRole;
+    /** AbortSignal for caller-driven cancellation. */
+    signal?: AbortSignal;
+}
+/** Wraps a single conversation by id — used as the entry point for sub-resources. */
+declare class ConversationHandle {
+    private readonly client;
+    readonly id: Uuid;
+    /**
+     * Message ops scoped to this conversation: `list`, `send`, `markRead`.
+     * Lazy: constructed on first access so an idle handle stays cheap.
+     */
+    readonly messages: ConversationMessages;
+    constructor(client: RestClient, id: Uuid);
+    show(signal?: AbortSignal): Promise<Conversation>;
+    update(attrs: ConversationUpdateRequest, signal?: AbortSignal): Promise<Conversation>;
+    listMembers(signal?: AbortSignal): Promise<MembershipList>;
+    /**
+     * Add multiple users to this conversation in one round-trip.
+     *
+     * `externalIds` are the stable customer-side identifiers you passed
+     * to `POST /v1/users` when creating each user — the server resolves
+     * them to internal user_ids and creates one membership row per id.
+     *
+     * Requires `:manage_members` on this conversation (owner or admin).
+     *
+     * ```ts
+     * await chat.conversations.one(convId).addMembers(['alice', 'bob']);
+     * ```
+     */
+    addMembers(externalIds: string[], opts?: AddMemberOptions): Promise<MembershipList>;
+    /**
+     * Add a single user. Convenience wrapper around {@link addMembers}
+     * that unwraps the returned list to the single membership row.
+     *
+     * ```ts
+     * const m = await chat.conversations.one(convId).addMember('alice');
+     * ```
+     */
+    addMember(externalId: string, opts?: AddMemberOptions): Promise<Membership>;
+    removeMember(userId: Uuid, signal?: AbortSignal): Promise<void>;
+}
+/** Top-level `/v1/conversations` collection. */
+declare class ConversationsResource {
+    private readonly client;
+    constructor(client: RestClient);
+    list(signal?: AbortSignal): Promise<ConversationList>;
+    create(attrs: ConversationCreateRequest, signal?: AbortSignal): Promise<Conversation>;
+    /** Returns a handle for further operations on a single conversation. */
+    one(id: Uuid): ConversationHandle;
+}
+
+/** `/v1/me` — the End-User identity behind the presented JWT. */
+declare class MeResource {
+    private readonly client;
+    constructor(client: RestClient);
+    /** GET /v1/me */
+    show(signal?: AbortSignal): Promise<Me>;
+}
+
+declare class Poolse {
+    /** `/v1/me` — current End User. */
+    readonly me: MeResource;
+    /** `/v1/conversations` collection + per-conversation handle factory. */
+    readonly conversations: ConversationsResource;
+    /** `/v1/messages/:id/*` — accessed via `chat.messages.one(id)`. */
+    readonly messages: MessagesResource;
+    /** `/v1/attachments/*` — presigned-URL uploads/downloads. */
+    readonly attachments: AttachmentsResource;
+    /**
+     * Low-level REST client. Exposed for advanced use cases (custom endpoints,
+     * raw retry/headers control). Most callers should use the resources above.
+     */
+    readonly rest: RestClient;
+    /**
+     * WebSocket / Phoenix Channels client. Lazily connects on the first
+     * `poolse.realtime.conversation(id)` / `poolse.realtime.user(id)`
+     * call — passing `config.apiUrl` (with `http(s)://` swapped to
+     * `ws(s)://`) for the socket URL by default, overridable via
+     * `config.wsUrl`.
+     */
+    readonly realtime: PoolseRealtime;
+    private readonly resolved;
+    private readonly tokenCache;
+    constructor(config: PoolseConfig);
+    /**
+     * Tear down the SDK: close the WebSocket, drop all channels.
+     * No-op for REST — fetch() doesn't keep persistent state.
+     * Call this when the user signs out or the SDK instance is
+     * being replaced.
+     */
+    destroy(): void;
+}
+
+/** Base for any error originating in the SDK. */
+declare class PoolseError extends Error {
+    readonly name: string;
+    constructor(message: string);
+}
+/** fetch() rejected or the server returned no response at all. */
+declare class NetworkError extends PoolseError {
+    readonly name: string;
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+/**
+ * Server returned a non-2xx status with the canonical error envelope.
+ * `code` is poolse's snake_case error code (e.g. `"invalid_user_token"`).
+ */
+declare class ApiError extends PoolseError {
+    readonly name: string;
+    readonly status: number;
+    readonly code: string;
+    readonly docUrl: string;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(status: number, envelope: ErrorEnvelope['error']);
+}
+/**
+ * 429 specifically. Surfaced as its own subclass so callers can back off
+ * politely without parsing the generic ApiError.
+ */
+declare class RateLimitedError extends ApiError {
+    readonly name: string;
+    readonly retryAfterMs: number;
+    constructor(envelope: ErrorEnvelope['error'], retryAfterMs: number);
+}
+/**
+ * Auth failure (401, including expired/revoked tokens). Callers should
+ * refresh the JWT (via `getToken`) and retry — the SDK does NOT do this
+ * automatically, because the failure could also mean "the user signed
+ * out on another tab" and silent re-auth would hide that.
+ */
+declare class AuthError extends ApiError {
+    readonly name: string;
+    constructor(envelope: ErrorEnvelope['error']);
+}
+
+declare const version = "0.0.1";
+
+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 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, type PoolseConfig, PoolseError, PoolseRealtime, type PresenceSnapshot, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type TypingEvent, type Unsubscribe, UserChannel, type Uuid, version };