@mitumba/sdk 1.30.1 → 1.32.0

package/dist/index.js

@@ -1,5 +1,55 @@
 'use strict';
 
+// src/types/messages-v2.ts
+var MESSAGING_ERROR_CODES = [
+  "invalid_input",
+  "unauthorized",
+  "session_expired",
+  "forbidden",
+  "conversation_not_found",
+  "thread_not_found",
+  "message_not_found",
+  "timeline_item_not_found",
+  "context_mismatch",
+  "idempotency_conflict",
+  "cursor_invalid",
+  "cursor_expired",
+  "attachment_not_ready",
+  "blocked",
+  "legacy_context_required",
+  "client_upgrade_required",
+  "rate_limited",
+  "temporarily_unavailable",
+  "internal_error",
+  "invalid_response",
+  "network_error"
+];
+var MESSAGING_ERROR_CODE_SET = new Set(MESSAGING_ERROR_CODES);
+function isMessagingAPIError(value, code) {
+  if (!(value instanceof Error) || value.name !== "APIError") {
+    return false;
+  }
+  const candidate = value;
+  if (typeof candidate.code !== "string" || typeof candidate.status !== "number" || !MESSAGING_ERROR_CODE_SET.has(candidate.code)) {
+    return false;
+  }
+  return code === void 0 || candidate.code === code;
+}
+var RealtimeProtocolError = class extends Error {
+  /** Construct a stable protocol failure without echoing an untrusted frame. */
+  constructor() {
+    super("Messaging realtime protocol is invalid.");
+    this.name = "RealtimeProtocolError";
+  }
+};
+var RealtimeUnavailableError = class extends Error {
+  /** Construct a stable runtime-unavailable failure. */
+  constructor() {
+    super("Messaging realtime is unavailable in this runtime.");
+    this.name = "RealtimeUnavailableError";
+  }
+};
+
 // src/token-store.ts
 var MemoryTokenStore = class {
   accessToken = null;
@@ -101,6 +151,37 @@ function isExpiringSoon(token, thresholdSeconds) {
     return false;
   }
 }
+function isErrorRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeAPIErrorResponse(value, fallbackMessage) {
+  if (isErrorRecord(value) && typeof value.error === "string") {
+    return {
+      error: value.error,
+      message: typeof value.message === "string" ? value.message : fallbackMessage,
+      details: value.details
+    };
+  }
+  if (isErrorRecord(value) && isErrorRecord(value.error) && typeof value.error.code === "string") {
+    return {
+      error: value.error.code,
+      message: typeof value.error.message === "string" ? value.error.message : fallbackMessage,
+      details: value.error.details
+    };
+  }
+  return { error: "unknown_error", message: fallbackMessage };
+}
+var InvalidRefreshCredentialsError = class extends Error {
+  constructor() {
+    super("Refresh credentials are invalid.");
+    this.name = "InvalidRefreshCredentialsError";
+  }
+};
+function isTokenResponse(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.access_token === "string" && candidate.access_token.length > 0 && typeof candidate.refresh_token === "string" && candidate.refresh_token.length > 0;
+}
 var APIClient = class {
   config;
   tokenStore;
@@ -136,6 +217,13 @@ var APIClient = class {
   getBaseUrl() {
     return this.config.baseUrl;
   }
+  /** Create an isomorphic WebSocket using the configured or global transport. */
+  createWebSocket(url, protocols) {
+    if (this.config.webSocketFactory) return this.config.webSocketFactory(url, protocols);
+    const Constructor = globalThis.WebSocket;
+    if (typeof Constructor !== "function") throw new RealtimeUnavailableError();
+    return new Constructor(url, protocols);
+  }
   async clearToken() {
     this.config.token = void 0;
     this.config.refreshToken = void 0;
@@ -159,7 +247,7 @@ var APIClient = class {
     if (access) this.config.token = access;
     if (refresh) this.config.refreshToken = refresh;
   }
-  async ensureFreshToken() {
+  async ensureFreshToken(options) {
     if (!this.config.token) {
       const stored = await this.tokenStore.getAccessToken();
       if (stored) this.config.token = stored;
@@ -167,12 +255,12 @@ var APIClient = class {
       if (refresh) this.config.refreshToken = refresh;
     }
     if (this.config.token && isExpiringSoon(this.config.token, 60) && this.config.refreshToken && this.config.refreshToken.length > 0) {
-      await this.handleTokenRefresh();
+      await this.handleTokenRefresh(options?.signal);
     }
   }
   async request(method, path, body, params, options) {
     if (!path.includes("/auth/refresh") && !path.includes("/auth/login") && !path.includes("/auth/register")) {
-      await this.ensureFreshToken();
+      await this.ensureFreshToken(options);
     }
     const url = new URL(path, this.config.baseUrl);
     if (params) {
@@ -236,15 +324,14 @@ var APIClient = class {
       const hasRefreshToken = this.config.refreshToken && this.config.refreshToken.length > 0;
       if (hasRefreshToken) {
         try {
-          await this.handleTokenRefresh();
-          headers.set("Authorization", `Bearer ${this.config.token}`);
-          response = await fetch(url.toString(), { ...init, headers });
-        } catch {
-          if (this.config.onAuthExpired) {
-            this.config.onAuthExpired();
-          }
+          await this.handleTokenRefresh(options?.signal);
+        } catch (error) {
+          if (!(error instanceof InvalidRefreshCredentialsError)) throw error;
+          this.config.onAuthExpired?.();
           throw new APIError(401, { error: "session_expired", message: "Session expired. Please log in again." });
         }
+        headers.set("Authorization", `Bearer ${this.config.token}`);
+        response = await fetch(url.toString(), { ...init, headers });
       } else {
         if (this.config.onAuthExpired) {
           this.config.onAuthExpired();
@@ -253,20 +340,20 @@ var APIClient = class {
       }
     }
     if (!response.ok) {
-      let errorData;
+      let decoded;
       try {
-        errorData = await response.json();
+        decoded = await response.json();
       } catch {
-        errorData = { error: "unknown_error", message: response.statusText };
+        decoded = null;
       }
-      throw new APIError(response.status, errorData);
+      throw new APIError(response.status, normalizeAPIErrorResponse(decoded, response.statusText));
     }
     if (response.status === 204) {
       return void 0;
     }
     return response.json();
   }
-  async handleTokenRefresh() {
+  async handleTokenRefresh(signal) {
     if (this.isRefreshing && this.refreshPromise) {
       return this.refreshPromise;
     }
@@ -277,21 +364,35 @@ var APIClient = class {
         const response = await fetch(url.toString(), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ refresh_token: this.config.refreshToken })
+          body: JSON.stringify({ refresh_token: this.config.refreshToken }),
+          signal
         });
+        if (response.status === 400 || response.status === 401) {
+          await this.clearToken();
+          throw new InvalidRefreshCredentialsError();
+        }
         if (!response.ok) {
-          throw new Error("Refresh failed");
+          let decoded2;
+          try {
+            decoded2 = await response.json();
+          } catch {
+            decoded2 = null;
+          }
+          throw new APIError(response.status, normalizeAPIErrorResponse(decoded2, response.statusText || "Token refresh failed."));
         }
-        const data = await response.json();
-        this.config.token = data.access_token;
-        this.config.refreshToken = data.refresh_token;
-        await this.tokenStore.setTokens(data.access_token, data.refresh_token);
-        if (this.config.onTokenRefresh) {
-          this.config.onTokenRefresh({ token: data.access_token, refreshToken: data.refresh_token });
+        let decoded;
+        try {
+          decoded = await response.json();
+        } catch {
+          throw new APIError(response.status, { error: "refresh_response_invalid", message: "Token refresh returned an invalid response." });
         }
-      } catch (err) {
-        await this.clearToken();
-        throw err;
+        if (!isTokenResponse(decoded)) {
+          throw new APIError(response.status, { error: "refresh_response_invalid", message: "Token refresh returned an invalid response." });
+        }
+        this.config.token = decoded.access_token;
+        this.config.refreshToken = decoded.refresh_token;
+        await this.tokenStore.setTokens(decoded.access_token, decoded.refresh_token);
+        this.config.onTokenRefresh?.({ token: decoded.access_token, refreshToken: decoded.refresh_token });
       } finally {
         this.isRefreshing = false;
         this.refreshPromise = null;
@@ -861,15 +962,447 @@ var VaziModule = class {
   }
 };
 
+// src/realtime/messages-realtime.ts
+var PROTOCOL = "mitumba-messaging-v1";
+var TYPING_THROTTLE_MS = 750;
+var TYPING_CLEAR_MS = 3e3;
+var MAX_DEDUPLICATION_IDS = 2e3;
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isAuthor(value) {
+  if (!isRecord(value)) return false;
+  if (value.side === "buyer") return isRecord(value.buyer) && typeof value.buyer.id === "string";
+  return value.side === "store" && isRecord(value.store) && typeof value.store.id === "string";
+}
+function isThreadMessage(value) {
+  return isRecord(value) && typeof value.id === "string" && typeof value.thread_id === "string" && Number.isSafeInteger(value.sequence) && typeof value.body === "string" && isAuthor(value.author) && Array.isArray(value.attachments) && typeof value.created_at === "string";
+}
+function isThreadCard(value) {
+  return isRecord(value) && typeof value.id === "string" && typeof value.conversation_id === "string" && ["general", "listing", "order"].includes(String(value.kind)) && typeof value.unread_count === "number";
+}
+function isConversation(value) {
+  return isRecord(value) && typeof value.id === "string" && isRecord(value.buyer) && isRecord(value.store) && typeof value.unread_count === "number";
+}
+function isSystemEvent(value) {
+  return isRecord(value) && typeof value.id === "string" && typeof value.thread_id === "string" && Number.isSafeInteger(value.sequence) && value.kind === "thread.linked";
+}
+function isReadCursor(value) {
+  return isRecord(value) && typeof value.thread_id === "string" && typeof value.last_read_item_id === "string" && Number.isSafeInteger(value.last_read_sequence);
+}
+function isUpload(value) {
+  return isRecord(value) && typeof value.id === "string" && typeof value.thread_id === "string" && ["authorized", "uploaded", "pending_scan", "safe", "rejected", "expired", "claimed"].includes(String(value.state));
+}
+function validDurablePayload(type, payload) {
+  if (!isRecord(payload)) return false;
+  if (type === "message.created") return isThreadMessage(payload.message);
+  if (type === "system_event.created") return isSystemEvent(payload.event);
+  if (type === "conversation.updated") return isConversation(payload.conversation);
+  if (type === "thread.created" || type === "thread.updated") return isThreadCard(payload.thread);
+  if (type === "read_cursor.updated") return isReadCursor(payload.cursor);
+  if (type === "attachment.updated") return isUpload(payload.upload);
+  return type === "message.policy_applied" && typeof payload.message_id === "string" && Array.isArray(payload.notices) && payload.notices.every((notice) => typeof notice === "string");
+}
+function parseEvent(value) {
+  if (!isRecord(value) || value.api_version !== 2 || value.protocol_version !== 1 || typeof value.type !== "string") {
+    throw new RealtimeProtocolError();
+  }
+  if (value.type === "ready") {
+    if (typeof value.connection_id !== "string" || value.resume_cursor !== null && typeof value.resume_cursor !== "string") {
+      throw new RealtimeProtocolError();
+    }
+    return { type: "ready", resume_cursor: value.resume_cursor };
+  }
+  if (value.type === "typing.updated") {
+    if (typeof value.thread_id !== "string" || !isAuthor(value.author) || typeof value.is_typing !== "boolean" || typeof value.occurred_at !== "string") {
+      throw new RealtimeProtocolError();
+    }
+    return value;
+  }
+  if (value.type === "resync.required") {
+    if (!["cursor_expired", "gap_detected", "authorization_changed"].includes(String(value.reason)) || typeof value.resume_cursor !== "string") {
+      throw new RealtimeProtocolError();
+    }
+    return value;
+  }
+  const durableTypes = [
+    "message.created",
+    "system_event.created",
+    "conversation.updated",
+    "thread.created",
+    "thread.updated",
+    "read_cursor.updated",
+    "attachment.updated",
+    "message.policy_applied"
+  ];
+  if (!durableTypes.includes(value.type) || typeof value.event_id !== "string" || typeof value.resume_cursor !== "string" || typeof value.occurred_at !== "string" || !validDurablePayload(value.type, value.payload)) {
+    throw new RealtimeProtocolError();
+  }
+  return value;
+}
+function ticketPath(options) {
+  return options.perspective.kind === "buyer" ? "/notify/v2/inboxes/buyer/realtime/tickets" : `/notify/v2/inboxes/stores/${encodeURIComponent(options.perspective.store_id)}/realtime/tickets`;
+}
+function parseTicket(value) {
+  if (!isRecord(value) || value.api_version !== 2 || !isRecord(value.data)) throw new RealtimeProtocolError();
+  const ticket = value.data;
+  if (typeof ticket.ticket !== "string" || typeof ticket.expires_at !== "string" || typeof ticket.websocket_url !== "string" || ticket.websocket_protocol !== PROTOCOL || ticket.protocol_version !== 1 || ticket.resume_cursor !== null && typeof ticket.resume_cursor !== "string") {
+    throw new RealtimeProtocolError();
+  }
+  let url;
+  try {
+    url = new URL(ticket.websocket_url);
+  } catch {
+    throw new RealtimeProtocolError();
+  }
+  if (!["ws:", "wss:"].includes(url.protocol) || url.searchParams.has("token") || !url.searchParams.has("ticket")) {
+    throw new RealtimeProtocolError();
+  }
+  return ticket;
+}
+var ManagedMessagesRealtimeConnection = class {
+  constructor(client, options) {
+    this.client = client;
+    this.options = options;
+    this.currentCursor = options.resumeCursor ?? null;
+  }
+  client;
+  options;
+  currentState = "closed";
+  currentCursor;
+  socket = null;
+  reconnectTimer = null;
+  typingTimers = /* @__PURE__ */ new Map();
+  typingSentAt = /* @__PURE__ */ new Map();
+  eventListeners = /* @__PURE__ */ new Set();
+  stateListeners = /* @__PURE__ */ new Set();
+  subscribedThreads = /* @__PURE__ */ new Set();
+  seenEventIds = /* @__PURE__ */ new Set();
+  lastMessageSequence = /* @__PURE__ */ new Map();
+  explicitClose = false;
+  reconnectAttempt = 0;
+  startPromise = null;
+  resolveStart = null;
+  rejectStart = null;
+  onOpen = () => void 0;
+  onMessage = (event) => {
+    void this.handleMessage(event);
+  };
+  onClose = (event) => {
+    this.handleClose(event);
+  };
+  onError = () => void 0;
+  get state() {
+    return this.currentState;
+  }
+  get resumeCursor() {
+    return this.currentCursor;
+  }
+  onEvent(listener) {
+    this.eventListeners.add(listener);
+    return () => {
+      this.eventListeners.delete(listener);
+    };
+  }
+  onStateChange(listener) {
+    this.stateListeners.add(listener);
+    return () => {
+      this.stateListeners.delete(listener);
+    };
+  }
+  subscribeThread(threadId) {
+    this.subscribedThreads.add(threadId);
+  }
+  unsubscribeThread(threadId) {
+    this.clearTyping(threadId, true);
+    this.subscribedThreads.delete(threadId);
+  }
+  setTyping(threadId, isTyping) {
+    if (!this.subscribedThreads.has(threadId) || this.currentState !== "open" || !this.socket) return;
+    const now = Date.now();
+    const last = this.typingSentAt.get(threadId) ?? 0;
+    if (now - last < TYPING_THROTTLE_MS) return;
+    this.send({ protocol_version: 1, type: "typing.set", thread_id: threadId, is_typing: isTyping });
+    this.typingSentAt.set(threadId, now);
+    const existing = this.typingTimers.get(threadId);
+    if (existing) clearTimeout(existing);
+    if (isTyping) {
+      this.typingTimers.set(threadId, setTimeout(() => {
+        this.typingSentAt.delete(threadId);
+        this.setTyping(threadId, false);
+        this.typingTimers.delete(threadId);
+      }, TYPING_CLEAR_MS));
+    } else {
+      this.typingTimers.delete(threadId);
+    }
+  }
+  async start() {
+    if (this.explicitClose) throw new RealtimeUnavailableError();
+    if (this.currentState === "open") return;
+    if (this.startPromise) return this.startPromise;
+    const pending = new Promise((resolve, reject) => {
+      this.resolveStart = resolve;
+      this.rejectStart = reject;
+    });
+    this.startPromise = pending;
+    await this.open(false).catch((error) => {
+      if (error instanceof RealtimeProtocolError || error instanceof RealtimeUnavailableError || error instanceof APIError && [401, 403, 409].includes(error.status)) {
+        this.fail(error);
+      } else {
+        this.scheduleReconnect();
+      }
+    });
+    return pending;
+  }
+  close() {
+    this.explicitClose = true;
+    this.clearReconnect();
+    this.clearAllTyping();
+    this.detachSocket(true);
+    this.transition("closed");
+    this.resolveStart?.();
+    this.finishStart();
+    this.eventListeners.clear();
+    this.stateListeners.clear();
+  }
+  async open(reconnecting) {
+    this.transition(reconnecting ? "reconnecting" : "connecting");
+    const raw = await this.client.post(ticketPath(this.options), {
+      resume_cursor: this.currentCursor,
+      supported_protocol_versions: [1]
+    }, { signal: this.options.signal });
+    if (this.explicitClose) return;
+    const ticket = parseTicket(raw);
+    const socket = this.client.createWebSocket(ticket.websocket_url, ticket.websocket_protocol);
+    this.socket = socket;
+    socket.addEventListener("open", this.onOpen);
+    socket.addEventListener("message", this.onMessage);
+    socket.addEventListener("close", this.onClose);
+    socket.addEventListener("error", this.onError);
+  }
+  async handleMessage(event) {
+    try {
+      if (typeof event.data !== "string") throw new RealtimeProtocolError();
+      let decoded;
+      try {
+        decoded = JSON.parse(event.data);
+      } catch {
+        throw new RealtimeProtocolError();
+      }
+      const parsed = parseEvent(decoded);
+      if (parsed.type === "ready") {
+        this.currentCursor = parsed.resume_cursor ?? this.currentCursor;
+        this.reconnectAttempt = 0;
+        this.transition("open");
+        this.resolveStart?.();
+        this.finishStart();
+        return;
+      }
+      if ("event_id" in parsed) {
+        if (this.seenEventIds.has(parsed.event_id)) {
+          this.ack(parsed.event_id, parsed.resume_cursor);
+          return;
+        }
+        if (parsed.type === "message.created") {
+          const message = parsed.payload.message;
+          const previous = this.lastMessageSequence.get(message.thread_id) ?? 0;
+          if (message.sequence <= previous) {
+            this.remember(parsed.event_id);
+            this.ack(parsed.event_id, parsed.resume_cursor);
+            return;
+          }
+          this.lastMessageSequence.set(message.thread_id, message.sequence);
+        }
+        if (parsed.thread_id && this.subscribedThreads.size > 0 && !this.subscribedThreads.has(parsed.thread_id)) {
+          this.remember(parsed.event_id);
+          this.ack(parsed.event_id, parsed.resume_cursor);
+          return;
+        }
+      } else if (parsed.type === "typing.updated" && !this.subscribedThreads.has(parsed.thread_id)) {
+        return;
+      }
+      for (const listener of [...this.eventListeners]) await listener(parsed);
+      if ("event_id" in parsed) {
+        this.remember(parsed.event_id);
+        this.currentCursor = parsed.resume_cursor;
+        this.ack(parsed.event_id, parsed.resume_cursor);
+      } else if (parsed.type === "resync.required") {
+        this.currentCursor = parsed.resume_cursor;
+      }
+    } catch (error) {
+      this.fail(error instanceof RealtimeProtocolError ? error : new RealtimeProtocolError());
+      this.socket?.close(4004, "protocol_error");
+    }
+  }
+  handleClose(event) {
+    this.detachSocket(false);
+    this.clearAllTyping();
+    if (this.explicitClose) return;
+    if ([4002, 4003, 4004].includes(event.code)) {
+      this.fail(new RealtimeProtocolError());
+      return;
+    }
+    this.scheduleReconnect();
+  }
+  scheduleReconnect() {
+    if (this.reconnectTimer || this.explicitClose) return;
+    this.transition("reconnecting");
+    const base = Math.max(10, this.options.reconnectBaseDelayMs ?? 500);
+    const maximum = Math.max(base, this.options.reconnectMaxDelayMs ?? 3e4);
+    const cap = Math.min(maximum, base * 2 ** this.reconnectAttempt);
+    const random = this.options.random ?? Math.random;
+    const delay = Math.floor(random() * cap);
+    this.reconnectAttempt += 1;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      void this.open(true).catch((error) => {
+        if (error instanceof APIError && [401, 403].includes(error.status)) this.fail(error);
+        else this.scheduleReconnect();
+      });
+    }, delay);
+  }
+  ack(eventId, cursor) {
+    this.send({ protocol_version: 1, type: "ack", event_id: eventId, resume_cursor: cursor });
+  }
+  send(frame) {
+    if (!this.socket || this.currentState !== "open") return;
+    try {
+      this.socket.send(JSON.stringify(frame));
+    } catch {
+    }
+  }
+  remember(eventId) {
+    this.seenEventIds.add(eventId);
+    if (this.seenEventIds.size <= MAX_DEDUPLICATION_IDS) return;
+    const oldest = this.seenEventIds.values().next().value;
+    if (typeof oldest === "string") this.seenEventIds.delete(oldest);
+  }
+  clearTyping(threadId, sendFalse) {
+    const timer = this.typingTimers.get(threadId);
+    if (timer) clearTimeout(timer);
+    this.typingTimers.delete(threadId);
+    this.typingSentAt.delete(threadId);
+    if (sendFalse && this.subscribedThreads.has(threadId)) {
+      this.send({ protocol_version: 1, type: "typing.set", thread_id: threadId, is_typing: false });
+    }
+  }
+  clearAllTyping() {
+    for (const timer of this.typingTimers.values()) clearTimeout(timer);
+    this.typingTimers.clear();
+    this.typingSentAt.clear();
+  }
+  clearReconnect() {
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+  }
+  detachSocket(close) {
+    const socket = this.socket;
+    if (!socket) return;
+    socket.removeEventListener("open", this.onOpen);
+    socket.removeEventListener("message", this.onMessage);
+    socket.removeEventListener("close", this.onClose);
+    socket.removeEventListener("error", this.onError);
+    if (close) {
+      try {
+        socket.close(1e3, "client_close");
+      } catch {
+      }
+    }
+    this.socket = null;
+  }
+  transition(state) {
+    if (this.currentState === state) return;
+    this.currentState = state;
+    for (const listener of [...this.stateListeners]) listener(state);
+  }
+  fail(error) {
+    this.clearReconnect();
+    this.transition("failed");
+    this.rejectStart?.(error);
+    this.finishStart();
+  }
+  finishStart() {
+    this.resolveStart = null;
+    this.rejectStart = null;
+    this.startPromise = null;
+  }
+};
+
 // src/modules/messages.ts
+function encode(value) {
+  return encodeURIComponent(value);
+}
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function unwrap(value, valid = () => true) {
+  if (!isRecord2(value) || value.api_version !== 2 || !("data" in value) || !valid(value.data)) {
+    throw new APIError(502, { error: "invalid_response", message: "Messaging returned an invalid response." });
+  }
+  return value.data;
+}
+function isPage(value) {
+  return isRecord2(value) && Array.isArray(value.items);
+}
+function isIdentified(value) {
+  return isRecord2(value) && typeof value.id === "string";
+}
+function perspectiveBase(perspective) {
+  return perspective.kind === "buyer" ? "/notify/v2/inboxes/buyer" : `/notify/v2/inboxes/stores/${encode(perspective.store_id)}`;
+}
+function query(params) {
+  const entries = Object.entries(params);
+  return entries.some(([, value]) => value !== void 0) ? Object.fromEntries(entries) : void 0;
+}
+function idempotentOptions(options) {
+  if (!options.idempotencyKey.trim()) throw new TypeError("idempotencyKey is required.");
+  return {
+    signal: options.signal,
+    headers: { ...options.headers, "Idempotency-Key": options.idempotencyKey }
+  };
+}
+function validateLimit(params) {
+  if (params.limit !== void 0 && (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 100)) {
+    throw new RangeError("Messaging limit must be an integer from 1 through 100.");
+  }
+}
+function validateSendInput(input) {
+  if (!input.client_message_id.trim()) throw new TypeError("client_message_id is required.");
+  const length = input.body.trim().length;
+  if (length < 1 || length > 2e3) throw new RangeError("Message body must contain 1 to 2,000 characters after trimming.");
+}
+function validateAttachmentInput(input) {
+  if (!input.file_name.trim() || !input.content_type.trim()) throw new TypeError("Attachment file name and content type are required.");
+  if (!Number.isSafeInteger(input.size_bytes) || input.size_bytes < 1) throw new RangeError("Attachment size must be a positive integer.");
+  if (!/^[a-f0-9]{64}$/u.test(input.sha256)) throw new TypeError("Attachment SHA-256 must be lowercase hexadecimal.");
+}
+function uploadBodySize(body) {
+  if ("size" in body) return body.size;
+  return body.byteLength;
+}
+async function parseDirectResponse(response) {
+  let decoded;
+  try {
+    decoded = await response.json();
+  } catch {
+    throw new APIError(response.status || 502, { error: "invalid_response", message: "Messaging returned an invalid response." });
+  }
+  if (!response.ok) {
+    const error = isRecord2(decoded) && isRecord2(decoded.error) ? decoded.error : decoded;
+    throw new APIError(response.status, {
+      error: isRecord2(error) && typeof error.code === "string" ? error.code : isRecord2(error) && typeof error.error === "string" ? error.error : "unknown_error",
+      message: isRecord2(error) && typeof error.message === "string" ? error.message : response.statusText,
+      details: isRecord2(error) ? error.details : void 0
+    });
+  }
+  return unwrap(decoded);
+}
 var MessagesModule = class {
   constructor(client) {
     this.client = client;
   }
   client;
-  /**
-   * List all conversations for the authenticated user.
-   */
+  /** @deprecated Use listConversations or listStoreConversations. Context fields are non-authoritative server-validated hints. */
   async list(storeId, options) {
     return this.client.get(
       "/notify/messages",
@@ -877,9 +1410,7 @@ var MessagesModule = class {
       options
     );
   }
-  /**
-   * Get the message thread with a specific partner.
-   */
+  /** @deprecated Resolve a v2 thread and call listThreadMessages. */
   async getThread(partnerId, storeId, options) {
     return this.client.get(
       `/notify/messages/${partnerId}`,
@@ -887,37 +1418,206 @@ var MessagesModule = class {
       options
     );
   }
-  /**
-   * Send a message to another user.
-   */
+  /** @deprecated Use sendThreadMessage. Receiver and context fields are hints validated by the server. */
   async send(input, options) {
     return this.client.post("/notify/messages", input, options);
   }
-  /**
-   * Mark all messages from a partner as read.
-   */
+  /** @deprecated Use advanceThreadReadCursor for precise monotonic state. */
   async markRead(partnerId, storeId, options) {
     const path = storeId ? `/notify/messages/${partnerId}/read?store_id=${storeId}` : `/notify/messages/${partnerId}/read`;
     return this.client.post(path, void 0, options);
   }
-  /**
-   * Connect to the typing indicator WebSocket for a conversation.
-   * Token is passed via query param since WebSocket can't set headers.
-   */
+  /** @deprecated Use managed messaging realtime. */
   connectTyping(partnerId) {
     const token = this.client.getToken();
     const wsUrl = this.client.getBaseUrl().replace(/^http/, "ws") + `/notify/messages/${partnerId}/ws?token=${token}`;
     return new WebSocket(wsUrl);
   }
-  /**
-   * Connect to the user-scoped inbox WebSocket.
-   * Emits InboxRealtimeEvent for every inbound message across all conversations.
-   */
+  /** @deprecated Use managed messaging realtime. */
   connectInbox() {
     const token = this.client.getToken();
     const wsUrl = this.client.getBaseUrl().replace(/^http/, "ws") + `/notify/messages/inbox?token=${token}`;
     return new WebSocket(wsUrl);
   }
+  /** Create a legacy inbox socket only after hydrating/refreshing the access token. */
+  async connectInboxFresh(options) {
+    await this.client.ensureFreshToken(options);
+    const token = this.client.getToken() ?? "";
+    const wsUrl = this.client.getBaseUrl().replace(/^http/, "ws") + `/notify/messages/inbox?token=${encode(token)}`;
+    return this.client.createWebSocket(wsUrl, []);
+  }
+  /** Create a report for a message or conversation. */
+  async createReport(input, options) {
+    return this.client.post("/notify/messages/reports", input, options);
+  }
+  /** Create an idempotent bilateral buyer/store relationship block. */
+  async createBlock(input, options) {
+    return this.client.post("/notify/messages/blocks", input, options);
+  }
+  /** Remove a block created by the current perspective. */
+  async removeBlock(blockId, options) {
+    return this.client.delete(`/notify/messages/blocks/${encode(blockId)}`, void 0, options);
+  }
+  /** Discover server messaging capabilities. */
+  async getMessagingCapabilities(options) {
+    const value = await this.client.get("/notify/v2/capabilities", void 0, options);
+    return unwrap(value, isRecord2);
+  }
+  /** List buyer and represented-store inbox perspectives. */
+  async listMessagingInboxes(options) {
+    const value = await this.client.get("/notify/v2/inboxes", void 0, options);
+    return unwrap(value, isRecord2);
+  }
+  /** List personal buyer conversations. */
+  async listConversations(params = {}, options) {
+    validateLimit(params);
+    const value = await this.client.get("/notify/v2/inboxes/buyer/conversations", query(params), options);
+    return unwrap(value, isPage);
+  }
+  /** List conversations for one represented store. */
+  async listStoreConversations(storeId, params = {}, options) {
+    validateLimit(params);
+    const value = await this.client.get(`/notify/v2/inboxes/stores/${encode(storeId)}/conversations`, query(params), options);
+    return unwrap(value, isPage);
+  }
+  /** Get one authorized buyer/store conversation. */
+  async getConversation(perspective, conversationId, options) {
+    const value = await this.client.get(`${perspectiveBase(perspective)}/conversations/${encode(conversationId)}`, void 0, options);
+    const data = unwrap(value, isRecord2);
+    if (!isIdentified(data.conversation)) throw new APIError(502, { error: "invalid_response" });
+    return data.conversation;
+  }
+  /** Resolve a General, Listing, or Order thread idempotently. */
+  async resolveThread(perspective, input, options) {
+    const value = await this.client.post(`${perspectiveBase(perspective)}/threads/resolve`, input, idempotentOptions(options));
+    return unwrap(value, (data) => isRecord2(data) && isIdentified(data.thread) && isIdentified(data.conversation));
+  }
+  /** List contextual thread cards for one conversation. */
+  async listThreads(perspective, conversationId, params = {}, options) {
+    validateLimit(params);
+    const value = await this.client.get(
+      `${perspectiveBase(perspective)}/conversations/${encode(conversationId)}/threads`,
+      query(params),
+      options
+    );
+    return unwrap(value, isPage);
+  }
+  /** Get one contextual thread card and its conversation. */
+  async getConversationThread(perspective, threadId, options) {
+    const value = await this.client.get(`${perspectiveBase(perspective)}/threads/${encode(threadId)}`, void 0, options);
+    return unwrap(value, (data) => isRecord2(data) && isIdentified(data.thread) && isIdentified(data.conversation));
+  }
+  /** Update shared support status for a Listing or Order thread. */
+  async updateThreadStatus(perspective, threadId, status, options) {
+    const value = await this.client.patch(`${perspectiveBase(perspective)}/threads/${encode(threadId)}/status`, { status }, options);
+    const data = unwrap(value, isRecord2);
+    if (!isIdentified(data.thread)) throw new APIError(502, { error: "invalid_response" });
+    return data.thread;
+  }
+  /** Update perspective-private thread preferences. */
+  async updateThreadPreferences(perspective, threadId, preferences, options) {
+    const value = await this.client.patch(`${perspectiveBase(perspective)}/threads/${encode(threadId)}/preferences`, preferences, options);
+    const data = unwrap(value, isRecord2);
+    if (!isIdentified(data.thread)) throw new APIError(502, { error: "invalid_response" });
+    return data.thread;
+  }
+  /** Update perspective-private conversation preferences. */
+  async updateConversationPreferences(perspective, conversationId, preferences, options) {
+    const value = await this.client.patch(`${perspectiveBase(perspective)}/conversations/${encode(conversationId)}/preferences`, preferences, options);
+    const data = unwrap(value, isRecord2);
+    if (!isIdentified(data.conversation)) throw new APIError(502, { error: "invalid_response" });
+    return data.conversation;
+  }
+  /** List the newest, older, or catch-up timeline window for one thread. */
+  async listThreadMessages(perspective, threadId, params = {}, options) {
+    validateLimit(params);
+    const value = await this.client.get(`${perspectiveBase(perspective)}/threads/${encode(threadId)}/messages`, query(params), options);
+    return unwrap(value, isPage);
+  }
+  /** Send one idempotent message without ever replacing the caller-owned ID. */
+  async sendThreadMessage(perspective, threadId, input, options) {
+    validateSendInput(input);
+    const { client_message_id, ...body } = input;
+    const value = await this.client.post(
+      `${perspectiveBase(perspective)}/threads/${encode(threadId)}/messages`,
+      body,
+      { ...options, headers: { ...options?.headers, "Idempotency-Key": client_message_id } }
+    );
+    return unwrap(value, (data) => isRecord2(data) && isIdentified(data.message));
+  }
+  /** Advance the selected perspective read cursor to one visible timeline item. */
+  async advanceThreadReadCursor(perspective, threadId, timelineItemId, options) {
+    const value = await this.client.put(
+      `${perspectiveBase(perspective)}/threads/${encode(threadId)}/read-cursor`,
+      { timeline_item_id: timelineItemId },
+      options
+    );
+    return unwrap(value, (data) => isRecord2(data) && typeof data.last_read_sequence === "number");
+  }
+  /** List read-only exact-participant legacy archives. */
+  async listLegacyMessageArchives(params = {}, options) {
+    validateLimit(params);
+    const value = await this.client.get("/notify/v2/legacy-messages", query(params), options);
+    return unwrap(value, isPage);
+  }
+  /** List messages in one read-only legacy archive. */
+  async listLegacyMessages(legacyThreadId, params = {}, options) {
+    validateLimit(params);
+    const value = await this.client.get(`/notify/v2/legacy-messages/${encode(legacyThreadId)}`, query(params), options);
+    return unwrap(value, isPage);
+  }
+  /** Resolve a temporary partner/order link without guessing between stores. */
+  async resolveLegacyLink(input, options) {
+    const value = await this.client.post("/notify/v2/inboxes/buyer/legacy-links/resolve", input, options);
+    return unwrap(value, (data) => isRecord2(data) && typeof data.result === "string");
+  }
+  /** Authorize a private attachment upload for one thread. */
+  async createThreadAttachmentUpload(perspective, threadId, input, options) {
+    validateAttachmentInput(input);
+    const value = await this.client.post(`${perspectiveBase(perspective)}/threads/${encode(threadId)}/attachment-uploads`, input, options);
+    return unwrap(value, (data) => isRecord2(data) && data.state === "authorized" && typeof data.upload_url === "string");
+  }
+  /** Upload exact bytes through a one-use application ticket. */
+  async uploadThreadAttachment(authorization, body, options) {
+    if (uploadBodySize(body) !== authorization.accepted.size_bytes) {
+      throw new RangeError("Attachment body size does not match its authorization.");
+    }
+    const response = await fetch(authorization.upload_url, {
+      method: "PUT",
+      headers: { ...options?.headers, "Content-Type": authorization.accepted.content_type },
+      body,
+      signal: options?.signal
+    });
+    return parseDirectResponse(response);
+  }
+  /** Get current status for an upload created by the same perspective. */
+  async getThreadAttachmentUpload(perspective, threadId, uploadId, options) {
+    const value = await this.client.get(
+      `${perspectiveBase(perspective)}/threads/${encode(threadId)}/attachment-uploads/${encode(uploadId)}`,
+      void 0,
+      options
+    );
+    return unwrap(value, (data) => isRecord2(data) && typeof data.state === "string");
+  }
+  /** Create a short-lived mediated download for one committed attachment. */
+  async createThreadAttachmentDownload(perspective, threadId, attachmentId, options) {
+    const value = await this.client.post(
+      `${perspectiveBase(perspective)}/threads/${encode(threadId)}/attachments/${encode(attachmentId)}/download`,
+      void 0,
+      options
+    );
+    return unwrap(value, (data) => isRecord2(data) && typeof data.url === "string");
+  }
+  /** Create an inert managed realtime connection. Register listeners before start(). */
+  createMessagesRealtimeConnection(options) {
+    return new ManagedMessagesRealtimeConnection(this.client, options);
+  }
+  /** Create and start a managed realtime connection. */
+  async connectMessagesRealtime(options) {
+    const connection = this.createMessagesRealtimeConnection(options);
+    await connection.start();
+    return connection;
+  }
 };
 
 // src/modules/notifications.ts
@@ -1678,6 +2378,44 @@ var DISPUTE_STATUSES = ["open", "seller_responded", "under_review", "resolved_re
 // src/types/wholesale.ts
 var BALE_ORDER_STATUSES = ["pending_payment", "paid", "confirmed", "in_transit", "delivered", "completed", "cancelled"];
 
+// src/share.ts
+var DEFAULT_SHARE_ORIGIN = "https://go.mitumba.africa";
+var ID_PATTERN = /^[0-9a-f]{32}$/;
+var SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function resolveOrigin(origin) {
+  if (origin === void 0) return DEFAULT_SHARE_ORIGIN;
+  let url;
+  try {
+    url = new URL(origin);
+  } catch {
+    throw new TypeError(`Invalid share origin: ${origin}`);
+  }
+  const local = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+  if (url.protocol !== "https:" && !local || url.username || url.password) {
+    throw new TypeError(`Share origin must be https:// (or http://localhost): ${origin}`);
+  }
+  if (url.pathname !== "/" && url.pathname !== "" || url.search || url.hash) {
+    throw new TypeError(`Share origin must not include a path, query or fragment: ${origin}`);
+  }
+  return url.origin;
+}
+function identifier(kind, value) {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (!ID_PATTERN.test(normalized)) throw new TypeError(`Invalid ${kind} ID: ${String(value)}`);
+  return normalized;
+}
+function listingShareUrl(listingId, options = {}) {
+  return `${resolveOrigin(options.origin)}/l/${encodeURIComponent(identifier("listing", listingId))}`;
+}
+function storeShareUrl(storeSlug, options = {}) {
+  const slug = typeof storeSlug === "string" ? storeSlug.trim().toLowerCase() : "";
+  if (slug.length > 64 || !SLUG_PATTERN.test(slug)) throw new TypeError(`Invalid store slug: ${String(storeSlug)}`);
+  return `${resolveOrigin(options.origin)}/s/${encodeURIComponent(slug)}`;
+}
+function baleShareUrl(baleId, options = {}) {
+  return `${resolveOrigin(options.origin)}/b/${encodeURIComponent(identifier("bale", baleId))}`;
+}
+
 // src/index.ts
 var MitumbaClient = class {
   api;
@@ -1771,6 +2509,7 @@ exports.BALE_ORDER_STATUSES = BALE_ORDER_STATUSES;
 exports.BusinessesModule = BusinessesModule;
 exports.CONDITIONS = CONDITIONS;
 exports.CartModule = CartModule;
+exports.DEFAULT_SHARE_ORIGIN = DEFAULT_SHARE_ORIGIN;
 exports.DESIRED_RESOLUTIONS = DESIRED_RESOLUTIONS;
 exports.DISPUTE_REASONS = DISPUTE_REASONS;
 exports.DISPUTE_STATUSES = DISPUTE_STATUSES;
@@ -1787,6 +2526,8 @@ exports.ORDER_STATUSES = ORDER_STATUSES;
 exports.OrdersModule = OrdersModule;
 exports.PAYMENT_STATUSES = PAYMENT_STATUSES;
 exports.PayModule = PayModule;
+exports.RealtimeProtocolError = RealtimeProtocolError;
+exports.RealtimeUnavailableError = RealtimeUnavailableError;
 exports.ReportsModule = ReportsModule;
 exports.ReviewsModule = ReviewsModule;
 exports.SearchModule = SearchModule;
@@ -1797,6 +2538,10 @@ exports.UploadsModule = UploadsModule;
 exports.VaziModule = VaziModule;
 exports.WholesaleModule = WholesaleModule;
 exports.WishlistsModule = WishlistsModule;
+exports.baleShareUrl = baleShareUrl;
 exports.createTokenStore = createTokenStore;
+exports.isMessagingAPIError = isMessagingAPIError;
+exports.listingShareUrl = listingShareUrl;
+exports.storeShareUrl = storeShareUrl;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map