@poolse/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,340 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { PoolseConfig, Poolse, Me, Uuid, Conversation, ConversationCreateRequest, Membership, MemberRole, Message, MessageCreateRequest, RealtimeStatus, Attachment, AttachmentUploadInput } from '@poolse/sdk';
+export { ApiError, Attachment, AttachmentStatus, AttachmentUploadInput, AttachmentUploadRequest, AttachmentUploadResponse, AuthError, Conversation, ConversationCreateRequest, Me, MemberRole, Membership, Message, MessageCreateRequest, MessageType, NetworkError, PoolseConfig, PoolseError, RateLimitedError, RealtimeStatus, Uuid } from '@poolse/sdk';
+import { ReactNode } from 'react';
+
+interface PoolseProviderProps {
+    /**
+     * SDK configuration. The provider builds the `Poolse` instance ONCE
+     * per mount and reads `getToken` (and the other function-typed
+     * options) from a ref on each call, so it's safe to pass a fresh
+     * callback or a fresh object literal on every render.
+     *
+     * Re-mount the provider (give it a new `key`) when you genuinely
+     * want a fresh client — typically after a sign-out, a tenant swap,
+     * or an `apiUrl` change. Mutating `apiUrl` / `wsUrl` / `socketPath`
+     * after mount is a no-op (the values are captured at construction
+     * time); dev mode logs a warning when this happens.
+     */
+    config: PoolseConfig;
+    children: ReactNode;
+}
+/**
+ * Top-level provider. Wrap your tree once with this; every hook in
+ * `@poolse/react` reads from the context.
+ *
+ * ```tsx
+ * <PoolseProvider config={{apiUrl, getToken}}>
+ *   <App />
+ * </PoolseProvider>
+ * ```
+ *
+ * The `Poolse` instance is destroyed on unmount — closes the WebSocket
+ * and drops every joined channel.
+ */
+declare function PoolseProvider({ config, children }: PoolseProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the underlying `Poolse` instance. Most app code should prefer
+ * higher-level hooks (`useMessages`, `useTyping`, etc.) but the raw
+ * client is here for escape-hatch usage (custom REST calls, direct
+ * realtime control).
+ */
+declare function usePoolse(): Poolse;
+
+interface UseMeState {
+    me: Me | null;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * The currently-signed-in End User (`/v1/me`). Fetches once on mount
+ * and never re-fetches automatically — user identity is stable for
+ * the JWT's lifetime.
+ *
+ * Most apps won't need this; the JWT subject is enough. Useful when
+ * the UI needs the display name / external_id without re-asking the
+ * Customer's backend.
+ */
+declare function useMe(): UseMeState;
+
+interface UseConversationState {
+    /** The fetched conversation, or `null` while loading or on error. */
+    conversation: Conversation | null;
+    loading: boolean;
+    error: Error | null;
+    /** Re-run the GET. Use after a `chat.conversations.one(id).update(...)` to refresh state. */
+    refetch: () => Promise<void>;
+}
+/**
+ * Fetch a single conversation by id. Re-fetches when `id` changes
+ * (e.g. routing to a different conversation in the same component).
+ *
+ * Doesn't subscribe to realtime updates yet — the backend doesn't
+ * broadcast `conversation:updated` to user channels. Use `refetch()`
+ * after a mutation if you need fresh state in the same render cycle.
+ *
+ * ```ts
+ * const { conversation, loading } = useConversation(convId);
+ * if (loading) return <Spinner />;
+ * if (!conversation) return <NotFound />;
+ * return <h1>{conversation.name ?? 'Untitled'}</h1>;
+ * ```
+ */
+declare function useConversation(id: Uuid | null): UseConversationState;
+
+interface UseConversationsState {
+    conversations: Conversation[];
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+    create: (attrs: ConversationCreateRequest) => Promise<Conversation>;
+}
+/**
+ * List of conversations the current End User can see.
+ *
+ * On mount: REST-fetches the list and subscribes to the user's
+ * `user:<id>` channel for `conversation:created` events — fired by
+ * the server both when this user creates a conversation AND when
+ * someone else adds them to one. New rows are prepended to local
+ * state with id-based dedup so an optimistic `create()` followed by
+ * the realtime echo doesn't insert twice.
+ *
+ * `refetch()` is still here for explicit re-syncs (e.g. after a
+ * mutation that the SDK doesn't yet observe — name changes,
+ * settings updates). `create()` returns the canonical server row.
+ */
+declare function useConversations(): UseConversationsState;
+
+interface UseMembersState {
+    members: Membership[];
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+    /**
+     * Add one or more users by external_id. The returned memberships
+     * are appended to local state on success.
+     */
+    addMembers: (externalIds: string[], opts?: {
+        role?: MemberRole;
+    }) => Promise<Membership[]>;
+    /**
+     * Remove a member by user_id. Optimistically removes from state;
+     * rolls back on server error.
+     */
+    removeMember: (userId: Uuid) => Promise<void>;
+}
+/**
+ * Live-ish membership list for a conversation. Initial REST fetch on
+ * mount; mutation helpers update local state in place. No realtime
+ * sync yet — the backend doesn't broadcast `member:joined` /
+ * `member:left` events. For now, callers who depend on
+ * cross-client member updates should poll with `refetch()` or
+ * remount the hook.
+ */
+declare function useMembers(conversationId: Uuid): UseMembersState;
+
+interface UseMessagesState {
+    /** Newest-last array. The wire returns newest-first; we reverse so list rendering matches reading order. */
+    messages: Message[];
+    loading: boolean;
+    error: Error | null;
+    hasMore: boolean;
+    /** Load an older page (lower sequence numbers). Idempotent if no older messages exist. */
+    loadMore: () => Promise<void>;
+    /** Optimistically append + POST. Replaces the optimistic row with the server response on success. */
+    send: (attrs: MessageCreateRequest) => Promise<Message>;
+}
+/**
+ * Live message list for `conversationId`. Combines:
+ *
+ *   * Initial REST fetch (newest 50) on mount.
+ *   * WebSocket subscription for `message:new`, `message:updated`,
+ *     `message:deleted` — applied in-place to the cached array.
+ *   * Optimistic-send via `send()` — the message appears immediately
+ *     under the SAME id the server will assign (we pre-generate it
+ *     client-side and pass it through), so the realtime echo and the
+ *     REST response both arrive carrying that id and get deduped by
+ *     `findIndex(m => m.id === msg.id)`. No heuristic match, no race.
+ *
+ * Re-mounting with the same `conversationId` reuses the underlying
+ * channel — no extra socket traffic.
+ */
+declare function useMessages(conversationId: string): UseMessagesState;
+
+/**
+ * Map of emoji → list of user_ids who reacted with it. Matches the
+ * shape of `Message.reactions` so initial seeding from a message you
+ * already have in state is a direct assignment.
+ */
+type ReactionMap = Record<string, Uuid[]>;
+interface UseReactionsState {
+    reactions: ReactionMap;
+    /** Add the caller's reaction (idempotent server-side). */
+    addReaction: (emoji: string) => Promise<void>;
+    /** Remove the caller's reaction. No-op if not present. */
+    removeReaction: (emoji: string) => Promise<void>;
+}
+interface UseReactionsOptions {
+    /**
+     * Required for the in-channel subscription — the realtime layer
+     * routes reaction events through the conversation channel, not a
+     * per-message channel. Pass the conversation id you already know.
+     */
+    conversationId: Uuid;
+    /**
+     * Seed the local reaction map from a message you already have
+     * (e.g. from `useMessages`). Without this the hook starts empty
+     * and only sees deltas from the realtime stream.
+     */
+    initialReactions?: ReactionMap;
+    /**
+     * Current user's id. When provided, optimistic mutate updates the
+     * local map immediately for that user; when omitted, we wait for
+     * the server's `reaction:added` echo to update state.
+     */
+    currentUserId?: Uuid | null;
+}
+/**
+ * Live reaction map for a single message. Subscribes to
+ * `reaction:added` / `reaction:removed` realtime events filtered to
+ * `messageId`, and provides mutation helpers.
+ *
+ * ```ts
+ * const { reactions, addReaction } = useReactions(msg.id, {
+ *   conversationId: msg.conversation_id,
+ *   initialReactions: msg.reactions,
+ *   currentUserId: me?.id,
+ * });
+ * <button onClick={() => addReaction('🎉')}>🎉 {reactions['🎉']?.length ?? 0}</button>
+ * ```
+ */
+declare function useReactions(messageId: Uuid, opts: UseReactionsOptions): UseReactionsState;
+
+interface UseThreadState {
+    /** Replies, oldest-first (the wire returns oldest-first; we don't flip). */
+    replies: Message[];
+    loading: boolean;
+    error: Error | null;
+    /** More older-than-current-page replies available on the server. */
+    hasMore: boolean;
+    /** Load the next page after the current newest reply. Idempotent if no more. */
+    loadMore: () => Promise<void>;
+    /**
+     * Send a reply into this thread. Fills `reply_to_id` with the root
+     * message id automatically; pass `body` (and any other
+     * `MessageCreateRequest` fields) as you would to `useMessages.send`.
+     */
+    sendReply: (attrs: Omit<MessageCreateRequest, 'reply_to_id'>) => Promise<Message>;
+}
+/**
+ * Thread view rooted at `rootMessageId`. Loads replies oldest-first
+ * with cursor pagination (`after: sequence`), subscribes to the
+ * conversation channel's `message:new` event filtered by
+ * `thread_root_id === rootMessageId`, and provides a `sendReply`
+ * that wires `reply_to_id` for you.
+ *
+ * Like `useMessages`, the optimistic send uses the same id the
+ * server will assign (auto-generated by the SDK), so the realtime
+ * echo just upserts in place — no double-render.
+ */
+declare function useThread(conversationId: Uuid, rootMessageId: Uuid): UseThreadState;
+
+interface UseTypingState {
+    /** Set of user_ids currently typing. */
+    typing: Set<Uuid>;
+    /**
+     * Send a typing ping to the server. Debounced inside the SDK — the
+     * server squashes `typing:start` to one push per (user, conversation,
+     * window). Call as often as you want from input handlers.
+     */
+    signalTyping: () => void;
+}
+/**
+ * Tracks who's typing in `conversationId`. Subscribes to the
+ * `typing:start` / `typing:stop` broadcasts; auto-cleans up entries
+ * when stop fires.
+ *
+ * `signalTyping` debounces on the client side to once per 500 ms so a
+ * fast-typing user doesn't flood the channel — poolse does its own
+ * server-side debounce too, so both layers are safe.
+ */
+declare function useTyping(conversationId: string): UseTypingState;
+
+interface UsePresenceState {
+    /** Set of user_ids currently online in this conversation. */
+    online: Set<Uuid>;
+}
+/**
+ * Who's currently joined to `conversationId`'s channel. Backed by
+ * Phoenix.Presence broadcasts (`presence_state` snapshot on join,
+ * `presence_diff` on changes).
+ */
+declare function usePresence(conversationId: string): UsePresenceState;
+
+/**
+ * Connection status of the underlying WebSocket. Useful for showing a
+ * "reconnecting…" banner without coupling to socket internals.
+ *
+ * Returns one of: `'idle' | 'connecting' | 'connected' | 'reconnecting' | 'closed'`.
+ */
+declare function useRealtimeStatus(): RealtimeStatus;
+
+interface UseAttachmentUploadState {
+    /** Last successfully uploaded attachment, or null. */
+    attachment: Attachment | null;
+    uploading: boolean;
+    error: Error | null;
+    /**
+     * Run the upload pipeline (presigned-URL request + PUT). Updates
+     * local state with the resolved attachment on success; sets `error`
+     * and rethrows on failure so callers can surface a toast.
+     */
+    upload: (input: AttachmentUploadInput) => Promise<Attachment>;
+    /** Reset state (clears `attachment`, `error`). */
+    reset: () => void;
+}
+/**
+ * Stateful wrapper around `chat.attachments.upload`. Provides
+ * `uploading` + `error` flags for the common "show a spinner while
+ * the PUT is in flight" UI, plus retention of the last attachment
+ * so the caller can reference its id when sending a message.
+ *
+ * ```tsx
+ * const { upload, uploading, attachment } = useAttachmentUpload();
+ * const onPick = async (file: File) => {
+ *   const att = await upload({
+ *     body: file, contentType: file.type, byteSize: file.size, filename: file.name
+ *   });
+ *   await chat.conversations.one(convId).messages.send({
+ *     body: 'attached',
+ *     custom_data: { attachment_id: att.id },
+ *   });
+ * };
+ * ```
+ */
+declare function useAttachmentUpload(): UseAttachmentUploadState;
+
+interface UseAttachmentUrlState {
+    /** Presigned GET URL, or null while loading / on error. */
+    url: string | null;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Resolve an attachment's presigned download URL. Pass `null` to
+ * skip the fetch — useful in routing-driven views where the id may
+ * not be known yet.
+ *
+ * Doesn't auto-refresh: the server's URL TTL is ~1 hour and most
+ * UI lifetimes are much shorter. If you do need a refresh (long-lived
+ * dashboard, etc.), remount the hook or wrap it in a parent that
+ * re-keys on a timer.
+ *
+ * ```tsx
+ * const { url } = useAttachmentUrl(message.custom_data?.attachment_id ?? null);
+ * return url ? <img src={url} /> : <Spinner />;
+ * ```
+ */
+declare function useAttachmentUrl(attachmentId: Uuid | null): UseAttachmentUrlState;
+
+export { PoolseProvider, type PoolseProviderProps, type ReactionMap, useAttachmentUpload, useAttachmentUrl, useConversation, useConversations, useMe, useMembers, useMessages, usePoolse, usePresence, useReactions, useRealtimeStatus, useThread, useTyping };