@poolse/sdk 0.1.0 → 0.2.0-alpha.3

package/dist/index.d.cts

@@ -1,14 +1,23 @@
 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, e.g. `https://chat.example.com`.
-     * MUST NOT include the `/v1` path — the SDK adds that itself.
+     * 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;
+    apiUrl?: string;
     /**
      * Async hook the SDK calls every time it needs an `Authorization:
      * Bearer <jwt>` header. Most apps refresh the JWT from their own
@@ -146,6 +155,13 @@ interface Conversation {
     last_message_at: IsoDateTime | null;
     /** Monotonic per-conversation sequence counter (last message's `sequence`). */
     last_sequence: number;
+    /**
+     * Number of messages the caller hasn't read yet
+     * (`last_sequence - sequence_of(my_last_read_message_id)`).
+     * Populated only by `chat.conversations.list()` — undefined when the
+     * conversation is fetched via other paths.
+     */
+    unread_count?: number;
     inserted_at: IsoDateTime;
     updated_at: IsoDateTime;
 }
@@ -213,6 +229,13 @@ interface Message {
     thread_root_id: Uuid | null;
     mentions: Uuid[];
     reactions: Record<string, Uuid[]>;
+    /**
+     * Attachments linked to this message. Server populates on send +
+     * realtime broadcast; absent on partial responses (e.g. when the
+     * client posted with attachment_ids but the server has yet to
+     * resolve them).
+     */
+    attachments?: Attachment[];
     edited_at: IsoDateTime | null;
     deleted_at: IsoDateTime | null;
     sequence: number;
@@ -223,10 +246,31 @@ interface MessageList {
     data: Message[];
 }
 interface MessageCreateRequest {
-    body: string;
+    /**
+     * Plain-text body. Optional only when `attachment_ids` is non-empty
+     * — a message with attachments AND no body is valid (just the
+     * attachment renders). At least one of `body` or `attachment_ids`
+     * must be present.
+     */
+    body?: string | null;
     type?: MessageType;
     reply_to_id?: Uuid;
     mentions?: Uuid[];
+    /**
+     * Attach previously-uploaded attachments to this message. Each id
+     * must come from `chat.attachments.upload(...)` or the lower-level
+     * `requestUpload(...)` flow and must belong to the same tenant.
+     * The server links them in the same transaction as the insert, so
+     * the broadcast and REST response both carry the resolved
+     * `Attachment` rows in `message.attachments`.
+     */
+    attachment_ids?: Uuid[];
+    /**
+     * Client-supplied UUID for retry-safe sends. The SDK fills this in
+     * automatically when not provided so the optimistic temp row and
+     * the canonical server row share a single id (used for id-based
+     * dedup in `useMessages`).
+     */
     id?: Uuid;
 }
 interface MessageUpdateRequest {
@@ -304,6 +348,18 @@ interface ReactionEvent {
     emoji: string;
     user_id: Uuid;
 }
+/**
+ * `member:read` — a conversation member advanced their read cursor.
+ * Server broadcasts on `conversation:<id>` so the sender's
+ * read-receipt glyph (check vs check-double) updates in real time
+ * without needing to refetch the member list.
+ */
+interface MemberReadEvent {
+    user_id: Uuid;
+    conversation_id: Uuid;
+    last_read_message_id: Uuid;
+    last_read_at: string;
+}
 /** Per-user mention push on the `user:<id>` channel. */
 interface MentionEvent {
     message_id: Uuid;
@@ -421,6 +477,11 @@ declare class ConversationChannel {
     onTypingStop(fn: (evt: TypingEvent) => void): Unsubscribe;
     onReactionAdded(fn: (evt: ReactionEvent) => void): Unsubscribe;
     onReactionRemoved(fn: (evt: ReactionEvent) => void): Unsubscribe;
+    /**
+     * A conversation member advanced their read cursor. Used to flip the
+     * sender's read-receipt glyph from "sent" to "read" in real time.
+     */
+    onMemberRead(fn: (evt: MemberReadEvent) => void): Unsubscribe;
     onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe;
     onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe;
     /** Send a typing ping to the server. Debounced server-side. */
@@ -772,4 +833,4 @@ declare class AuthError extends ApiError {
 
 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 };
+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, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type TypingEvent, type Unsubscribe, UserChannel, type Uuid, version };

package/dist/index.d.ts

@@ -1,14 +1,23 @@
 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, e.g. `https://chat.example.com`.
-     * MUST NOT include the `/v1` path — the SDK adds that itself.
+     * 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;
+    apiUrl?: string;
     /**
      * Async hook the SDK calls every time it needs an `Authorization:
      * Bearer <jwt>` header. Most apps refresh the JWT from their own
@@ -146,6 +155,13 @@ interface Conversation {
     last_message_at: IsoDateTime | null;
     /** Monotonic per-conversation sequence counter (last message's `sequence`). */
     last_sequence: number;
+    /**
+     * Number of messages the caller hasn't read yet
+     * (`last_sequence - sequence_of(my_last_read_message_id)`).
+     * Populated only by `chat.conversations.list()` — undefined when the
+     * conversation is fetched via other paths.
+     */
+    unread_count?: number;
     inserted_at: IsoDateTime;
     updated_at: IsoDateTime;
 }
@@ -213,6 +229,13 @@ interface Message {
     thread_root_id: Uuid | null;
     mentions: Uuid[];
     reactions: Record<string, Uuid[]>;
+    /**
+     * Attachments linked to this message. Server populates on send +
+     * realtime broadcast; absent on partial responses (e.g. when the
+     * client posted with attachment_ids but the server has yet to
+     * resolve them).
+     */
+    attachments?: Attachment[];
     edited_at: IsoDateTime | null;
     deleted_at: IsoDateTime | null;
     sequence: number;
@@ -223,10 +246,31 @@ interface MessageList {
     data: Message[];
 }
 interface MessageCreateRequest {
-    body: string;
+    /**
+     * Plain-text body. Optional only when `attachment_ids` is non-empty
+     * — a message with attachments AND no body is valid (just the
+     * attachment renders). At least one of `body` or `attachment_ids`
+     * must be present.
+     */
+    body?: string | null;
     type?: MessageType;
     reply_to_id?: Uuid;
     mentions?: Uuid[];
+    /**
+     * Attach previously-uploaded attachments to this message. Each id
+     * must come from `chat.attachments.upload(...)` or the lower-level
+     * `requestUpload(...)` flow and must belong to the same tenant.
+     * The server links them in the same transaction as the insert, so
+     * the broadcast and REST response both carry the resolved
+     * `Attachment` rows in `message.attachments`.
+     */
+    attachment_ids?: Uuid[];
+    /**
+     * Client-supplied UUID for retry-safe sends. The SDK fills this in
+     * automatically when not provided so the optimistic temp row and
+     * the canonical server row share a single id (used for id-based
+     * dedup in `useMessages`).
+     */
     id?: Uuid;
 }
 interface MessageUpdateRequest {
@@ -304,6 +348,18 @@ interface ReactionEvent {
     emoji: string;
     user_id: Uuid;
 }
+/**
+ * `member:read` — a conversation member advanced their read cursor.
+ * Server broadcasts on `conversation:<id>` so the sender's
+ * read-receipt glyph (check vs check-double) updates in real time
+ * without needing to refetch the member list.
+ */
+interface MemberReadEvent {
+    user_id: Uuid;
+    conversation_id: Uuid;
+    last_read_message_id: Uuid;
+    last_read_at: string;
+}
 /** Per-user mention push on the `user:<id>` channel. */
 interface MentionEvent {
     message_id: Uuid;
@@ -421,6 +477,11 @@ declare class ConversationChannel {
     onTypingStop(fn: (evt: TypingEvent) => void): Unsubscribe;
     onReactionAdded(fn: (evt: ReactionEvent) => void): Unsubscribe;
     onReactionRemoved(fn: (evt: ReactionEvent) => void): Unsubscribe;
+    /**
+     * A conversation member advanced their read cursor. Used to flip the
+     * sender's read-receipt glyph from "sent" to "read" in real time.
+     */
+    onMemberRead(fn: (evt: MemberReadEvent) => void): Unsubscribe;
     onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe;
     onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe;
     /** Send a typing ping to the server. Debounced server-side. */
@@ -772,4 +833,4 @@ declare class AuthError extends ApiError {
 
 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 };
+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, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type TypingEvent, type Unsubscribe, UserChannel, type Uuid, version };

package/dist/index.js

@@ -1,13 +1,11 @@
 import { Socket } from 'phoenix';
 
 // src/config.ts
+var POOLSE_API_URL = "https://api.poolse.dev";
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_BASE_BACKOFF_MS = 250;
 var DEFAULT_MAX_BACKOFF_MS = 3e4;
 function resolveConfig(config) {
-  if (!config.apiUrl) {
-    throw new Error("Poolse: `apiUrl` is required.");
-  }
   if (typeof config.getToken !== "function") {
     throw new Error("Poolse: `getToken` is required and must be a function.");
   }
@@ -19,7 +17,7 @@ function resolveConfig(config) {
   }
   const fetchFn = rawFetch.bind(globalThis);
   return {
-    apiUrl: trimTrailingSlash(config.apiUrl),
+    apiUrl: trimTrailingSlash(config.apiUrl ?? POOLSE_API_URL),
     getToken: config.getToken,
     fetch: fetchFn,
     maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
@@ -259,6 +257,13 @@ var ConversationChannel = class {
   onReactionRemoved(fn) {
     return this.subscribe("reaction:removed", fn);
   }
+  /**
+   * A conversation member advanced their read cursor. Used to flip the
+   * sender's read-receipt glyph from "sent" to "read" in real time.
+   */
+  onMemberRead(fn) {
+    return this.subscribe("member:read", fn);
+  }
   onPresenceState(fn) {
     return this.subscribe("presence_state", fn);
   }
@@ -741,6 +746,9 @@ var RestClient = class {
         if (opts.signal) init.signal = opts.signal;
         response = await this.config.fetch(url, init);
       } catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+          throw err;
+        }
         if (attempt < maxRetries && isRetryableNetworkError(err)) {
           await sleep(this.backoffDelay(attempt));
           attempt += 1;
@@ -980,6 +988,6 @@ var Poolse = class {
 // src/version.ts
 var version = "0.0.1";
 
-export { ApiError, AttachmentHandle, AttachmentsResource, AuthError, ConversationChannel, ConversationHandle, ConversationMessages, ConversationsResource, MeResource, MessageHandle, MessagesResource, NetworkError, Poolse, PoolseError, PoolseRealtime, RateLimitedError, UserChannel, version };
+export { ApiError, AttachmentHandle, AttachmentsResource, AuthError, ConversationChannel, ConversationHandle, ConversationMessages, ConversationsResource, MeResource, MessageHandle, MessagesResource, NetworkError, POOLSE_API_URL, Poolse, PoolseError, PoolseRealtime, RateLimitedError, UserChannel, version };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map