@swarm-tips/client 0.2.4 → 0.2.6

package/README.md

@@ -22,3 +22,5 @@ tools. Browser entrypoints do not depend on Node built-ins or a global Buffer.
 
 The `/evm` subpath expects the optional `viem` and `wagmi` peers. Install them
 in applications that use EVM wallet helpers; other subpaths do not pull them in.
+
+Inbox metadata includes `to_wallet` (null when unavailable in legacy metadata). `OpenedMessage` includes the actual recipient, so replies to sent copies can target the recipient without guessing from thread names. Opening and replying never acknowledge messages.

package/SBOM.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@swarm-tips/client-0.2.4",
-  "documentNamespace": "https://swarm.tips/sbom/client/0.2.4",
+  "name": "@swarm-tips/client-0.2.6",
+  "documentNamespace": "https://swarm.tips/sbom/client/0.2.6",
   "creationInfo": {
-    "created": "2026-09-09T05:55:37.047Z",
+    "created": "2026-09-10T13:43:36.045Z",
     "creators": [
       "Tool: sdk/client/scripts/generate-sbom.mjs",
       "Organization: Swarm Tips"
@@ -15,8 +15,8 @@
     {
       "name": "@swarm-tips/client",
       "SPDXID": "SPDXRef-Package",
-      "versionInfo": "0.2.4",
-      "downloadLocation": "https://www.npmjs.com/package/@swarm-tips/client/v/0.2.4",
+      "versionInfo": "0.2.6",
+      "downloadLocation": "https://www.npmjs.com/package/@swarm-tips/client/v/0.2.6",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
       "licenseDeclared": "MIT"

package/dist/inbox/client.d.ts

@@ -46,6 +46,75 @@ export interface InboxMessage {
      *  inbound-only reads (treat as "received"). */
     direction?: "received" | "sent";
 }
+export interface MessageReference {
+    msg_id: string;
+    direction?: "received" | "sent";
+}
+export interface MessageEnvelope {
+    /** Stored recipient; null for legacy metadata without a recipient. */
+    to_wallet: string | null;
+    msg_id: string;
+    direction: "received" | "sent";
+    from_wallet: string;
+    sent_at: string;
+    /** Inbox messages do not expire. */
+    expires_at: null;
+    body_bytes: number;
+    intent: "game_invite" | "task_offer" | "task_clarification" | null;
+    /** Stable mailbox-local grouping label, not a threadId filter. */
+    thread_ref: string;
+    acknowledged: boolean | null;
+    /** Untrusted excerpt; absent unless explicitly requested. */
+    preview?: string;
+    preview_truncated?: boolean;
+}
+export interface InboxListOptions {
+    cursor?: string;
+    limit?: number;
+    threadId?: string;
+    minTrust?: number;
+    status?: "pending" | "all";
+    includeSent?: boolean;
+    preview?: boolean;
+}
+export interface InboxListPage {
+    messages: MessageEnvelope[];
+    count: number;
+    /** Continue even when messages is empty. */
+    next_cursor: string | null;
+    filtered_acknowledged: number;
+    filtered_muted: number;
+    filtered_below_min_trust: number;
+}
+export type OpenedMessage = InboxMessage & Omit<MessageEnvelope, "acknowledged" | "to_wallet"> & {
+    /** Actual recipient of this message, including sent mirror copies. */
+    to_wallet: string;
+};
+export type OpenMessageResult = {
+    msg_id: string;
+    direction: "received" | "sent";
+    status: "opened";
+    message: OpenedMessage;
+} | {
+    msg_id: string;
+    direction: "received" | "sent";
+    status: "unavailable";
+} | {
+    msg_id: string;
+    direction: "received" | "sent";
+    status: "error";
+    error: "storage_error";
+};
+export type AckMessageResult = {
+    msg_id: string;
+    direction: "received";
+    status: "acknowledged" | "unavailable";
+} | {
+    msg_id: string;
+    direction: "received";
+    status: "error";
+    error: "storage_error";
+};
 export interface MessagePage {
     messages: InboxMessage[];
     next_cursor: string | null;
@@ -145,6 +214,16 @@ export declare class InboxClient {
          *  `direction:"sent"`. */
         includeSent?: boolean;
     }): Promise<MessagePage>;
+    /** Metadata first; listing never acknowledges. Old bulk status is independent. */
+    listMessages(opts?: InboxListOptions): Promise<InboxListPage>;
+    /** Load only selected bodies. This never acknowledges or follows message links. */
+    openMessages(messages: MessageReference[]): Promise<{
+        results: OpenMessageResult[];
+    }>;
+    /** Mark only these received IDs handled/dismissed. Per-ID errors can be retried. */
+    ackMessageIds(messageIds: string[]): Promise<{
+        results: AckMessageResult[];
+    }>;
     /** Read one thread (e.g. `task:{task_id}` / `game:{id}`), newest first. Pass
      *  `includeSent` to fold in the connected wallet's own replies (full
      *  two-way conversation). */

package/dist/inbox/client.js

@@ -145,6 +145,32 @@ export class InboxClient {
             next_cursor: page.next_cursor ?? null,
         };
     }
+    /** Metadata first; listing never acknowledges. Old bulk status is independent. */
+    async listMessages(opts = {}) {
+        if (opts.includeSent && opts.status !== "all")
+            throw new InboxApiError(0, "includeSent requires status=all");
+        if (opts.limit !== undefined && (!Number.isInteger(opts.limit) || opts.limit < 1 || opts.limit > 50))
+            throw new InboxApiError(0, "limit must be in 1..50");
+        if (opts.minTrust !== undefined && (!Number.isFinite(opts.minTrust) || opts.minTrust < 0 || opts.minTrust > 1))
+            throw new InboxApiError(0, "minTrust must be in [0,1]");
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries({ cursor: opts.cursor, limit: opts.limit, thread_id: opts.threadId, min_trust: opts.minTrust, status: opts.status, include_sent: opts.includeSent, preview: opts.preview })) {
+            if (value !== undefined)
+                query.set(key, String(value));
+        }
+        const suffix = query.toString();
+        return this.authed(`/internal/inbox/list${suffix ? `?${suffix}` : ""}`, { method: "GET" });
+    }
+    /** Load only selected bodies. This never acknowledges or follows message links. */
+    async openMessages(messages) {
+        validateSelectedIds(messages.map(m => m.msg_id));
+        return this.authed("/internal/inbox/open", { method: "POST", body: JSON.stringify({ messages }) });
+    }
+    /** Mark only these received IDs handled/dismissed. Per-ID errors can be retried. */
+    async ackMessageIds(messageIds) {
+        validateSelectedIds(messageIds);
+        return this.authed("/internal/inbox/ack-ids", { method: "POST", body: JSON.stringify({ message_ids: messageIds }) });
+    }
     /** Read one thread (e.g. `task:{task_id}` / `game:{id}`), newest first. Pass
      *  `includeSent` to fold in the connected wallet's own replies (full
      *  two-way conversation). */
@@ -332,3 +358,9 @@ export class InboxClient {
         }
     }
 }
+function validateSelectedIds(ids) {
+    if (ids.length < 1 || ids.length > 50)
+        throw new InboxApiError(0, "select 1..50 message IDs");
+    if (ids.some(id => !/^\d{20}_[0-9a-fA-F]{8}$/.test(id)))
+        throw new InboxApiError(0, "msg_id must be a server-issued message ID");
+}

package/dist/inbox/index.d.ts

@@ -1,2 +1,2 @@
-export { InboxClient, InboxApiError, type InboxClientOpts, type InboxMessage, type InboxSession, type MessagePage, type NonceSigner, type SendReceipt, type TopicId, type TopicPost, type TopicPage, type PublishReceipt, type ReportReceipt, } from "./client.js";
+export { InboxClient, InboxApiError, type InboxClientOpts, type InboxMessage, type MessageReference, type MessageEnvelope, type InboxListOptions, type InboxListPage, type OpenMessageResult, type OpenedMessage, type AckMessageResult, type InboxSession, type MessagePage, type NonceSigner, type SendReceipt, type TopicId, type TopicPost, type TopicPage, type PublishReceipt, type ReportReceipt, } from "./client.js";
 export { solanaNonceSigner } from "./solana.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarm-tips/client",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Typed browser and Node.js clients for Swarm Tips, Shillbot, and Coordination Game",
   "type": "module",
   "main": "dist/index.js",