@poolse/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,985 @@
+import { Socket } from 'phoenix';
+
+// src/config.ts
+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.");
+  }
+  const rawFetch = config.fetch ?? globalThis.fetch;
+  if (typeof rawFetch !== "function") {
+    throw new Error(
+      "Poolse: no global `fetch` found. Provide one via `config.fetch` (Node <18 or a sandboxed runtime)."
+    );
+  }
+  const fetchFn = rawFetch.bind(globalThis);
+  return {
+    apiUrl: trimTrailingSlash(config.apiUrl),
+    getToken: config.getToken,
+    fetch: fetchFn,
+    maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+    baseBackoffMs: config.baseBackoffMs ?? DEFAULT_BASE_BACKOFF_MS,
+    maxBackoffMs: config.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS,
+    generateIdempotencyKey: config.generateIdempotencyKey ?? defaultIdempotencyKey,
+    wsUrl: config.wsUrl,
+    socketPath: config.socketPath ?? "/socket",
+    onSocketError: config.onSocketError
+  };
+}
+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."
+  );
+}
+
+// src/errors.ts
+var PoolseError = class extends Error {
+  name = "PoolseError";
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NetworkError = class extends PoolseError {
+  name = "NetworkError";
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+  }
+};
+var ApiError = class extends PoolseError {
+  name = "ApiError";
+  status;
+  code;
+  docUrl;
+  details;
+  constructor(status, envelope) {
+    super(`[${status}] ${envelope.code}: ${envelope.message}`);
+    this.status = status;
+    this.code = envelope.code;
+    this.docUrl = envelope.doc_url;
+    this.details = envelope.details;
+  }
+};
+var RateLimitedError = class extends ApiError {
+  name = "RateLimitedError";
+  retryAfterMs;
+  constructor(envelope, retryAfterMs) {
+    super(429, envelope);
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var AuthError = class extends ApiError {
+  name = "AuthError";
+  constructor(envelope) {
+    super(401, envelope);
+  }
+};
+
+// src/realtime/realtime.ts
+var PoolseRealtime = class {
+  config;
+  tokenCache;
+  socketPath;
+  wsUrl;
+  socket = null;
+  conversations = /* @__PURE__ */ new Map();
+  userChannel = null;
+  status = "idle";
+  statusListeners = /* @__PURE__ */ new Set();
+  constructor(config, tokenCache, opts = {}) {
+    this.config = config;
+    this.tokenCache = tokenCache;
+    this.socketPath = opts.socketPath ?? "/socket";
+    this.wsUrl = opts.wsUrl ?? deriveWsUrl(config.apiUrl);
+  }
+  /** Current connection status. */
+  getStatus() {
+    return this.status;
+  }
+  /** Subscribe to connection-status changes. */
+  onStatus(listener) {
+    this.statusListeners.add(listener);
+    return () => this.statusListeners.delete(listener);
+  }
+  /**
+   * 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() {
+    if (this.socket) return;
+    this.setStatus("connecting");
+    const socket = new Socket(`${this.wsUrl}${this.socketPath}`, {
+      params: () => ({ token: this.tokenCache.peekToken() ?? "" })
+      // Phoenix's default reconnect strategy: 10ms, 50ms, 100ms, 150ms,
+      // 200ms, 250ms, 500ms, 1s, 2s, 5s — perfectly reasonable for chat.
+    });
+    socket.onOpen(() => this.setStatus("connected"));
+    socket.onClose(() => {
+      this.setStatus(this.status === "closed" ? "closed" : "reconnecting");
+    });
+    socket.onError((err) => {
+      this.setStatus("reconnecting");
+      this.config.onSocketError?.(new PoolseError(`socket error: ${String(err)}`));
+    });
+    this.socket = socket;
+    void this.tokenCache.getToken().catch((err) => {
+      this.config.onSocketError?.(
+        new PoolseError(`token fetch failed before socket open: ${String(err)}`)
+      );
+    }).finally(() => {
+      socket.connect();
+    });
+  }
+  /** Close the socket and tear down every joined channel. */
+  disconnect() {
+    this.setStatus("closed");
+    this.conversations.forEach((c) => c._destroy());
+    this.conversations.clear();
+    this.userChannel?._destroy();
+    this.userChannel = null;
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+    }
+  }
+  /**
+   * 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) {
+    const existing = this.conversations.get(conversationId);
+    if (existing) return existing;
+    this.connect();
+    if (!this.socket) {
+      throw new PoolseError("socket not initialised \u2014 call connect() first");
+    }
+    const channel = this.socket.channel(`conversation:${conversationId}`, {});
+    const handle = new ConversationChannel(conversationId, channel);
+    this.conversations.set(conversationId, handle);
+    handle._join();
+    return handle;
+  }
+  /**
+   * Subscribe to the current user's `user:<id>` channel. Only the user
+   * matching the JWT can join — poolse's UserChannel enforces this.
+   */
+  user(userId) {
+    if (this.userChannel) return this.userChannel;
+    this.connect();
+    if (!this.socket) {
+      throw new PoolseError("socket not initialised \u2014 call connect() first");
+    }
+    const channel = this.socket.channel(`user:${userId}`, {});
+    const handle = new UserChannel(userId, channel);
+    this.userChannel = handle;
+    handle._join();
+    return handle;
+  }
+  /** Drop a conversation handle and leave the channel. */
+  leave(conversationId) {
+    const handle = this.conversations.get(conversationId);
+    if (!handle) return;
+    handle._destroy();
+    this.conversations.delete(conversationId);
+  }
+  setStatus(status) {
+    if (this.status === status) return;
+    this.status = status;
+    this.statusListeners.forEach((l) => l(status));
+  }
+};
+var ConversationChannel = class {
+  conversationId;
+  channel;
+  // Map from event-name → set of listeners. We bind one Phoenix `.on(...)`
+  // per event name (no matter how many JS listeners) and fan out
+  // ourselves — much cheaper than re-binding on every subscription.
+  listeners = /* @__PURE__ */ new Map();
+  constructor(conversationId, channel) {
+    this.conversationId = conversationId;
+    this.channel = channel;
+  }
+  /** New message pushed to the conversation. */
+  onMessage(fn) {
+    return this.subscribe("message:new", fn);
+  }
+  /** Existing message edited by its sender. */
+  onMessageUpdated(fn) {
+    return this.subscribe("message:updated", fn);
+  }
+  /** Tombstone for a soft-deleted message. */
+  onMessageDeleted(fn) {
+    return this.subscribe("message:deleted", fn);
+  }
+  onTypingStart(fn) {
+    return this.subscribe("typing:start", fn);
+  }
+  onTypingStop(fn) {
+    return this.subscribe("typing:stop", fn);
+  }
+  onReactionAdded(fn) {
+    return this.subscribe("reaction:added", fn);
+  }
+  onReactionRemoved(fn) {
+    return this.subscribe("reaction:removed", fn);
+  }
+  onPresenceState(fn) {
+    return this.subscribe("presence_state", fn);
+  }
+  onPresenceDiff(fn) {
+    return this.subscribe("presence_diff", fn);
+  }
+  /** Send a typing ping to the server. Debounced server-side. */
+  sendTyping() {
+    this.channel.push("typing", {});
+  }
+  /** @internal — called by `PoolseRealtime.conversation/1`. */
+  _join() {
+    this.channel.join();
+  }
+  /** @internal — called when the consumer leaves this conversation. */
+  _destroy() {
+    this.listeners.clear();
+    this.channel.leave();
+  }
+  subscribe(event, fn) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+      this.channel.on(event, (payload) => {
+        const listeners = this.listeners.get(event);
+        if (listeners) listeners.forEach((l) => l(payload));
+      });
+    }
+    set.add(fn);
+    return () => {
+      set.delete(fn);
+    };
+  }
+};
+var UserChannel = class {
+  userId;
+  channel;
+  mentionListeners = /* @__PURE__ */ new Set();
+  conversationCreatedListeners = /* @__PURE__ */ new Set();
+  mentionBound = false;
+  conversationCreatedBound = false;
+  constructor(userId, channel) {
+    this.userId = userId;
+    this.channel = channel;
+  }
+  onMention(fn) {
+    if (!this.mentionBound) {
+      this.mentionBound = true;
+      this.channel.on("mention:new", (payload) => {
+        this.mentionListeners.forEach((l) => l(payload));
+      });
+    }
+    this.mentionListeners.add(fn);
+    return () => {
+      this.mentionListeners.delete(fn);
+    };
+  }
+  /**
+   * 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) {
+    if (!this.conversationCreatedBound) {
+      this.conversationCreatedBound = true;
+      this.channel.on("conversation:created", (payload) => {
+        this.conversationCreatedListeners.forEach((l) => l(payload));
+      });
+    }
+    this.conversationCreatedListeners.add(fn);
+    return () => {
+      this.conversationCreatedListeners.delete(fn);
+    };
+  }
+  /** @internal */
+  _join() {
+    this.channel.join();
+  }
+  /** @internal */
+  _destroy() {
+    this.mentionListeners.clear();
+    this.conversationCreatedListeners.clear();
+    this.channel.leave();
+  }
+};
+function deriveWsUrl(apiUrl) {
+  return apiUrl.replace(/^http/, "ws");
+}
+
+// src/resources/attachments.ts
+var AttachmentsResource = class {
+  /**
+   * 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, fetchFn) {
+    this.client = client;
+    this.fetchFn = fetchFn;
+  }
+  client;
+  fetchFn;
+  /**
+   * 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, opts = {}) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/attachments/upload-url",
+      body: attrs,
+      ...opts.signal ? { signal: opts.signal } : {}
+    });
+  }
+  /**
+   * 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.
+   */
+  async upload(input, opts = {}) {
+    const req = {
+      content_type: input.contentType,
+      byte_size: input.byteSize,
+      ...input.filename !== void 0 ? { original_filename: input.filename } : {}
+    };
+    const { attachment, upload } = await this.requestUpload(req, opts);
+    const putInit = {
+      method: upload.method.toUpperCase(),
+      headers: upload.headers,
+      body: input.body,
+      ...opts.signal ? { signal: opts.signal } : {}
+    };
+    const res = await this.fetchFn(upload.url, putInit);
+    if (!res.ok) {
+      throw new Error(
+        `Poolse: presigned upload PUT failed (${res.status}) for attachment ${attachment.id}`
+      );
+    }
+    return attachment;
+  }
+  /** Returns a handle for further operations on a single attachment. */
+  one(id) {
+    return new AttachmentHandle(this.client, id);
+  }
+};
+var AttachmentHandle = class {
+  constructor(client, id) {
+    this.client = client;
+    this.id = id;
+  }
+  client;
+  id;
+  /**
+   * 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 = {}) {
+    return this.client.request({
+      method: "GET",
+      path: `/v1/attachments/${this.id}/download-url`,
+      ...opts.signal ? { signal: opts.signal } : {}
+    });
+  }
+  /**
+   * Delete the attachment row + best-effort bucket object delete.
+   * Authz: uploader (while still `:pending`) or message-sender / conv
+   * owner-admin (once linked).
+   */
+  delete(opts = {}) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/v1/attachments/${this.id}`,
+      ...opts.signal ? { signal: opts.signal } : {}
+    });
+  }
+};
+
+// src/resources/messages.ts
+var ConversationMessages = class {
+  constructor(client, conversationId) {
+    this.client = client;
+    this.conversationId = conversationId;
+  }
+  client;
+  conversationId;
+  list(opts = {}, signal) {
+    return this.client.request({
+      method: "GET",
+      path: `/v1/conversations/${this.conversationId}/messages`,
+      query: {
+        ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+        ...opts.before !== void 0 ? { before: opts.before } : {}
+      },
+      ...signal ? { signal } : {}
+    });
+  }
+  /**
+   * 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, signal) {
+    const body = attrs.id !== void 0 ? attrs : { ...attrs, id: generateClientMessageId() };
+    return this.client.request({
+      method: "POST",
+      path: `/v1/conversations/${this.conversationId}/messages`,
+      body,
+      ...signal ? { signal } : {}
+    });
+  }
+  markRead(messageId, signal) {
+    return this.client.request({
+      method: "POST",
+      path: `/v1/conversations/${this.conversationId}/read`,
+      body: { message_id: messageId },
+      ...signal ? { signal } : {}
+    });
+  }
+};
+var MessageHandle = class {
+  constructor(client, id) {
+    this.client = client;
+    this.id = id;
+  }
+  client;
+  id;
+  update(attrs, signal) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/v1/messages/${this.id}`,
+      body: attrs,
+      ...signal ? { signal } : {}
+    });
+  }
+  delete(signal) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/v1/messages/${this.id}`,
+      ...signal ? { signal } : {}
+    });
+  }
+  replies(opts = {}, signal) {
+    return this.client.request({
+      method: "GET",
+      path: `/v1/messages/${this.id}/replies`,
+      query: {
+        ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+        ...opts.after !== void 0 ? { after: opts.after } : {}
+      },
+      ...signal ? { signal } : {}
+    });
+  }
+  addReaction(emoji, signal) {
+    const body = { emoji };
+    return this.client.request({
+      method: "POST",
+      path: `/v1/messages/${this.id}/reactions`,
+      body,
+      ...signal ? { signal } : {}
+    });
+  }
+  removeReaction(emoji, signal) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/v1/messages/${this.id}/reactions/${encodeURIComponent(emoji)}`,
+      ...signal ? { signal } : {}
+    });
+  }
+};
+var MessagesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  one(id) {
+    return new MessageHandle(this.client, id);
+  }
+};
+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)."
+  );
+}
+
+// src/resources/conversations.ts
+var ConversationHandle = class {
+  constructor(client, id) {
+    this.client = client;
+    this.id = id;
+    this.messages = new ConversationMessages(this.client, this.id);
+  }
+  client;
+  id;
+  /**
+   * Message ops scoped to this conversation: `list`, `send`, `markRead`.
+   * Lazy: constructed on first access so an idle handle stays cheap.
+   */
+  messages;
+  show(signal) {
+    return this.client.request({
+      method: "GET",
+      path: `/v1/conversations/${this.id}`,
+      ...signal ? { signal } : {}
+    });
+  }
+  update(attrs, signal) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/v1/conversations/${this.id}`,
+      body: attrs,
+      ...signal ? { signal } : {}
+    });
+  }
+  // ── members ────────────────────────────────────────────────────────────
+  listMembers(signal) {
+    return this.client.request({
+      method: "GET",
+      path: `/v1/conversations/${this.id}/members`,
+      ...signal ? { signal } : {}
+    });
+  }
+  /**
+   * 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, opts = {}) {
+    return this.client.request({
+      method: "POST",
+      path: `/v1/conversations/${this.id}/members`,
+      body: {
+        external_ids: externalIds,
+        ...opts.role !== void 0 ? { role: opts.role } : {}
+      },
+      ...opts.signal ? { signal: opts.signal } : {}
+    });
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async addMember(externalId, opts = {}) {
+    const list = await this.addMembers([externalId], opts);
+    const row = list.data[0];
+    if (!row) {
+      throw new Error("Poolse: addMember succeeded but server returned no membership row.");
+    }
+    return row;
+  }
+  removeMember(userId, signal) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/v1/conversations/${this.id}/members/${userId}`,
+      ...signal ? { signal } : {}
+    });
+  }
+};
+var ConversationsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  list(signal) {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/conversations",
+      ...signal ? { signal } : {}
+    });
+  }
+  create(attrs, signal) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/conversations",
+      body: attrs,
+      ...signal ? { signal } : {}
+    });
+  }
+  /** Returns a handle for further operations on a single conversation. */
+  one(id) {
+    return new ConversationHandle(this.client, id);
+  }
+};
+
+// src/resources/me.ts
+var MeResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** GET /v1/me */
+  show(signal) {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/me",
+      ...signal ? { signal } : {}
+    });
+  }
+};
+
+// src/rest-client.ts
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET"]);
+var RestClient = class {
+  config;
+  tokenCache;
+  constructor(config, tokenCache) {
+    this.config = config;
+    this.tokenCache = tokenCache;
+  }
+  async request(opts) {
+    const url = this.buildUrl(opts.path, opts.query);
+    const maxRetries = opts.maxRetries ?? this.config.maxRetries;
+    const idempotencyKey = this.resolveIdempotencyKey(opts);
+    let attempt = 0;
+    let triedAuthRefresh = false;
+    for (; ; ) {
+      const body = opts.body === void 0 ? void 0 : JSON.stringify(opts.body);
+      const headers = await this.buildHeaders(opts.method, idempotencyKey, body !== void 0);
+      let response;
+      try {
+        const init = { method: opts.method, headers };
+        if (body !== void 0) init.body = body;
+        if (opts.signal) init.signal = opts.signal;
+        response = await this.config.fetch(url, init);
+      } catch (err) {
+        if (attempt < maxRetries && isRetryableNetworkError(err)) {
+          await sleep(this.backoffDelay(attempt));
+          attempt += 1;
+          continue;
+        }
+        throw new NetworkError("Network request failed", err);
+      }
+      if (response.status >= 200 && response.status < 300) {
+        return await parseJsonOrNull(response);
+      }
+      if (response.status === 401) {
+        if (!triedAuthRefresh) {
+          this.tokenCache.invalidate();
+          triedAuthRefresh = true;
+          continue;
+        }
+        throw new AuthError(await parseEnvelope(response));
+      }
+      if (response.status === 429) {
+        const envelope = await parseEnvelope(response);
+        const retryAfterMs = retryAfterHeaderMs(response);
+        if (attempt < maxRetries) {
+          await sleep(Math.max(retryAfterMs ?? 0, this.backoffDelay(attempt)));
+          attempt += 1;
+          continue;
+        }
+        throw new RateLimitedError(envelope, retryAfterMs ?? 0);
+      }
+      if (response.status >= 500 && attempt < maxRetries) {
+        await sleep(this.backoffDelay(attempt));
+        attempt += 1;
+        continue;
+      }
+      throw new ApiError(response.status, await parseEnvelope(response));
+    }
+  }
+  // ── helpers ────────────────────────────────────────────────────────────
+  buildUrl(path, query) {
+    const base = `${this.config.apiUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    if (!query) return base;
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0 && v !== null) {
+        params.append(k, String(v));
+      }
+    }
+    const qs = params.toString();
+    return qs ? `${base}?${qs}` : base;
+  }
+  async buildHeaders(method, idempotencyKey, hasBody) {
+    const headers = { Accept: "application/json" };
+    if (hasBody) headers["Content-Type"] = "application/json";
+    const token = await this.config.getToken();
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+    if (!IDEMPOTENT_METHODS.has(method) && idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
+    }
+    return headers;
+  }
+  resolveIdempotencyKey(opts) {
+    if (opts.idempotencyKey === null) return null;
+    if (opts.idempotencyKey) return opts.idempotencyKey;
+    if (IDEMPOTENT_METHODS.has(opts.method)) return null;
+    return this.config.generateIdempotencyKey();
+  }
+  backoffDelay(attempt) {
+    const exp = this.config.baseBackoffMs * 2 ** attempt;
+    const capped = Math.min(this.config.maxBackoffMs, exp);
+    return Math.floor(Math.random() * capped);
+  }
+};
+async function parseEnvelope(response) {
+  try {
+    const json = await response.json();
+    if (json?.error?.code) return json.error;
+  } catch {
+  }
+  return {
+    code: "unknown_error",
+    message: `HTTP ${response.status}`,
+    doc_url: ""
+  };
+}
+async function parseJsonOrNull(response) {
+  if (response.status === 204) return null;
+  const text = await response.text();
+  if (!text) return null;
+  return JSON.parse(text);
+}
+function retryAfterHeaderMs(response) {
+  const raw = response.headers.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number.parseInt(raw, 10);
+  return Number.isFinite(seconds) ? seconds * 1e3 : null;
+}
+function isRetryableNetworkError(err) {
+  if (err instanceof DOMException && err.name === "AbortError") return false;
+  return true;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/token-cache.ts
+var REFRESH_BUFFER_MS = 3e4;
+var FALLBACK_TTL_MS = 6e4;
+var TokenCache = class {
+  constructor(fetcher) {
+    this.fetcher = fetcher;
+  }
+  fetcher;
+  token = null;
+  expMs = null;
+  inFlight = null;
+  /**
+   * 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() {
+    if (this.token === null || this.expMs === null) return this.token;
+    return Date.now() < this.expMs - REFRESH_BUFFER_MS ? this.token : null;
+  }
+  async getToken(opts = {}) {
+    if (opts.forceRefresh) this.invalidate();
+    const now = Date.now();
+    if (this.token && this.expMs !== null && now < this.expMs - REFRESH_BUFFER_MS) {
+      return this.token;
+    }
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.fetchAndStore().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+  invalidate() {
+    this.token = null;
+    this.expMs = null;
+  }
+  async fetchAndStore() {
+    const token = await this.fetcher();
+    if (!token) {
+      this.token = null;
+      this.expMs = null;
+      return null;
+    }
+    const expSec = parseJwtExp(token);
+    if (expSec !== null) {
+      const expMs = expSec * 1e3;
+      this.expMs = expMs <= Date.now() ? Date.now() + FALLBACK_TTL_MS : expMs;
+    } else {
+      this.expMs = Date.now() + FALLBACK_TTL_MS;
+    }
+    this.token = token;
+    return token;
+  }
+};
+function parseJwtExp(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    const json = decodeBase64Url(parts[1]);
+    const payload = JSON.parse(json);
+    return typeof payload.exp === "number" && Number.isFinite(payload.exp) ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+function decodeBase64Url(s) {
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+  if (typeof atob === "function") return atob(padded);
+  const g = globalThis;
+  if (g.Buffer) return g.Buffer.from(padded, "base64").toString("binary");
+  throw new Error("No base64 decoder available");
+}
+
+// src/poolse.ts
+var Poolse = class {
+  /** `/v1/me` — current End User. */
+  me;
+  /** `/v1/conversations` collection + per-conversation handle factory. */
+  conversations;
+  /** `/v1/messages/:id/*` — accessed via `chat.messages.one(id)`. */
+  messages;
+  /** `/v1/attachments/*` — presigned-URL uploads/downloads. */
+  attachments;
+  /**
+   * Low-level REST client. Exposed for advanced use cases (custom endpoints,
+   * raw retry/headers control). Most callers should use the resources above.
+   */
+  rest;
+  /**
+   * 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`.
+   */
+  realtime;
+  resolved;
+  tokenCache;
+  constructor(config) {
+    this.resolved = resolveConfig(config);
+    this.tokenCache = new TokenCache(this.resolved.getToken);
+    const cachedConfig = {
+      ...this.resolved,
+      getToken: () => this.tokenCache.getToken()
+    };
+    this.rest = new RestClient(cachedConfig, this.tokenCache);
+    this.me = new MeResource(this.rest);
+    this.conversations = new ConversationsResource(this.rest);
+    this.messages = new MessagesResource(this.rest);
+    this.attachments = new AttachmentsResource(this.rest, cachedConfig.fetch);
+    this.realtime = new PoolseRealtime(cachedConfig, this.tokenCache, {
+      ...this.resolved.wsUrl !== void 0 ? { wsUrl: this.resolved.wsUrl } : {},
+      socketPath: this.resolved.socketPath
+    });
+  }
+  /**
+   * 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() {
+    this.realtime.disconnect();
+  }
+};
+
+// 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 };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map