402mob-merchant-sdk 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 An open-source, dependency-free TypeScript client for resolving agent resources and enrolling or operating a 402Mob merchant from a Node.js server or agent runtime.
 
-It wraps the existing HTTP merchant API. It does not custody keys, sign for wallets, submit transactions, or make x402 purchases.
+It wraps the existing HTTP merchant API, including seller-side Work Ticket inbox, claim, quote, and result methods. It does not custody keys, sign for wallets, submit transactions, or make x402 purchases.
 
 The SDK is intended for server-side and agent-runtime use. `evidence.contact` does not enable cross-origin browser requests, and merchant API keys are long-lived secrets. For a browser UI, keep the key on your backend and proxy calls through it; the browser may sign the exact challenge message with its wallet and send only the signature to that backend.
 
@@ -26,7 +26,7 @@ Install from npm:
 npm install 402mob-merchant-sdk
 ```
 
-This guide documents SDK version **0.2.0**, which adds public agent resource resolution. See the [npm package page](https://www.npmjs.com/package/402mob-merchant-sdk) or browse the [source repository](https://github.com/gggggggg424242/402mob-merchant-sdk).
+This source prepares SDK version **0.3.0**, adding seller Work Ticket methods and public buyer status reads. The published npm version remains **0.2.0** until 0.3.0 is separately released. See the [npm package page](https://www.npmjs.com/package/402mob-merchant-sdk) or browse the [source repository](https://github.com/gggggggg424242/402mob-merchant-sdk).
 
 Requires Node.js 18 or newer. The SDK uses the built-in Fetch API and has no runtime dependencies.
 
@@ -94,6 +94,27 @@ if (page.items[0]) {
 
 `resolveResources` searches provider names, resource titles, and descriptions. It returns only active prepared resources from providers that opted into directory visibility. `getProviderResources(merchantId)` reads a known provider's public profile and resources even when it is not discoverable. `resolveLatestResource(merchantId, offerId)` follows an older offer ID to the current version in its series. These calls return descriptors and checkout paths; they do not execute work, purchase an artifact, sign a payment, or endorse the provider. Use an x402-capable buyer or the documented checkout flow to purchase.
 
+## Seller Work Tickets
+
+Merchant agents with the `merchant:work` scope can inspect their private inbox, claim a buyer-addressed task, submit a fixed quote, and deliver a result after the buyer's x402 payment is confirmed. The SDK methods are `listWorkTickets`, `claimWorkTicket`, `quoteWorkTicket`, `getWorkTicket`, and `submitWorkTicketResult`.
+
+```ts
+const seller = new MerchantClient({ apiKey: process.env.MERCHANT_API_KEY });
+const { tickets } = await seller.listWorkTickets({ states: ["open"], limit: 20 });
+const ticket = tickets[0];
+if (ticket) {
+  await seller.claimWorkTicket(ticket.id, 600);
+  await seller.quoteWorkTicket(ticket.id, {
+    priceUSDC: "0.05",
+    deliverable: "JSON transfer summary",
+    contentType: "application/json",
+    expiresInSeconds: 600,
+  });
+}
+```
+
+The buyer must separately sign the exact quote and pay through x402 before `submitWorkTicketResult` succeeds. The seller SDK does not make or sign buyer payments. Read the [Work Ticket protocol guide](https://evidence.contact/work-tickets.md) for the complete buyer/seller sequence and recovery rules.
+
 ## Enrollment with a wallet transaction tool
 
 For runtimes that can submit Base USDC actions but cannot sign arbitrary messages, pass a callback that submits the exact zero-USDC action from the challenge. Wait for the response's advertised confirmation depth before returning the transaction hash.
@@ -178,3 +199,16 @@ Adds `setDiscoverable(discoverable)`, which calls the authenticated `PUT /v1/age
 ## Version 0.1.2
 
 The source now rejects unreadable or incomplete successful API responses with `MerchantApiError` code `invalid_response`. Challenge fields and zero-USDC instructions are checked before invoking the wallet callback; enrollment and rotation responses must contain a merchant ID and a nonempty API key. An invalid completion response can mean the server already completed the operation: recover access through credential rotation if its one-time key was lost. This validation is included in published 0.1.2. Integrations using 0.1.1 should validate required fields explicitly. Preserve the original challenge and submitted transaction hash when completion is interrupted; rerunning `enrollWithTransaction` creates a fresh challenge and invokes the wallet callback again. A completion error is not permission to submit another proof transaction automatically.
+
+
+## Work Ticket reads and recovery (0.3.0 source)
+
+Buyer agents can call `client.getWorkTicketStatus(ticketId)` without an API key to read state, quote terms, payment references, and result hashes. This public response excludes the buyer wallet, private input, and signed buyer receipt. It does not fetch result bytes or authorize payment.
+
+Seller agents use `getWorkTicket(ticketId)` or `listWorkTickets({ states: ["paid"], limit: 20 })` with a `merchant:work` key. Inbox, detail, and claim responses include private `input`; it becomes `null` after retention ends. Quote and result-submission responses return `WorkTicketSummary`, which has no `input` field. Fetch the authenticated detail if the worker needs that input again.
+
+The supported states are `open`, `claimed`, `quoted`, `accepted`, `paying`, `paid`, `delivered`, `accepted_by_buyer`, `disputed`, and `expired`. Cancellation is not implemented. An explicit `states` filter must contain 1–10 supported states; omit it to use the server default. Work Ticket IDs must be UUIDs.
+
+SDK requests reject HTTP redirects and never retry automatically. An interrupted mutation may have completed. Read the ticket before repeating a claim or quote; quote and claim creation are not idempotent. Repeating identical result content is supported while retained. For payment recovery through HTTP or MCP, reuse the original checkout key and authorization, including after delivery or a buyer receipt. The SDK does not submit payments.
+
+These methods are prepared in the 0.3.0 source release; publishing the package is a separate step.

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type EvmSignature = `0x${string}`;
 export type TransactionHash = `0x${string}`;
 export type ProofMethod = "approve_zero" | "transfer_zero";
 export type ArtifactContentType = "application/json" | "text/plain; charset=utf-8";
+export type WorkTicketState = "open" | "claimed" | "quoted" | "accepted" | "paying" | "paid" | "delivered" | "accepted_by_buyer" | "disputed" | "expired";
 export interface EnrollmentChallenge {
     challengeId: string;
     message: string;
@@ -182,6 +183,66 @@ export interface SaleDetails {
     responseHash: string | null;
     deliveryReceipts: unknown[];
 }
+export interface WorkTicketSummary {
+    id: string;
+    buyer: EvmAddress;
+    merchantId: string;
+    capability: string;
+    inputHash: string;
+    maxPriceAtomic: string;
+    maxPriceUSDC: string;
+    state: WorkTicketState;
+    createdAt: string;
+    expiresAt: string;
+    claimExpiresAt: string | null;
+    quote: null | {
+        id: string;
+        amount: string;
+        amountAtomic: string;
+        amountUSDC: string;
+        deliverable: string;
+        contentType: ArtifactContentType;
+        termsHash: string;
+        expiresAt: string;
+    };
+    payment: {
+        operationId: string | null;
+        transaction: TransactionHash | null;
+    };
+    result: {
+        sha256: string | null;
+        contentType: ArtifactContentType | null;
+    };
+    buyerReceipt: null | {
+        verdict: "accepted" | "disputed";
+        challengeId: string;
+        message: string;
+        signature: EvmSignature;
+        createdAt: string;
+    };
+}
+/** Authenticated inbox/detail/claim responses include private input, or null after retention. */
+export interface MerchantWorkTicket extends WorkTicketSummary {
+    input: unknown;
+}
+/** Public status excludes the buyer wallet, private input, and signed buyer receipt. */
+export type PublicWorkTicket = Omit<WorkTicketSummary, "buyer" | "buyerReceipt">;
+export interface WorkTicketInbox {
+    tickets: MerchantWorkTicket[];
+}
+export interface MerchantWorkQuoteInput {
+    priceUSDC: string;
+    deliverable: string;
+    contentType: ArtifactContentType;
+    expiresInSeconds: number;
+}
+export type MerchantWorkResultInput = {
+    contentType: "application/json";
+    result: JsonValue;
+} | {
+    contentType: "text/plain; charset=utf-8";
+    result: string;
+};
 export interface MerchantClientOptions {
     /** Defaults to https://evidence.contact. */
     baseUrl?: string;
@@ -273,6 +334,34 @@ export declare class MerchantClient {
     setOfferActive(offerId: string, active: boolean): Promise<MerchantOffer>;
     listSales(limit?: number): Promise<SaleList>;
     getSale(operationId: string): Promise<SaleDetails>;
+    /** Read this merchant's private work inbox; requires the merchant:work scope. */
+    listWorkTickets(input?: {
+        states?: WorkTicketState[];
+        limit?: number;
+    }): Promise<WorkTicketInbox>;
+    /** Public progress and recovery metadata; no API key, private input, or result bytes. */
+    getWorkTicketStatus(ticketId: string): Promise<{
+        ticket: PublicWorkTicket;
+    }>;
+    /** Claim a ticket addressed to this merchant for a bounded lease. */
+    claimWorkTicket(ticketId: string, leaseSeconds?: number): Promise<{
+        ticket: MerchantWorkTicket;
+    }>;
+    /** Submit one fixed quote; the server rejects amounts above the buyer-signed cap. */
+    quoteWorkTicket(ticketId: string, input: MerchantWorkQuoteInput): Promise<{
+        ticket: WorkTicketSummary;
+        acceptanceChallenge: string;
+    }>;
+    /** Read this merchant's own ticket, including input and buyer receipt metadata. */
+    getWorkTicket(ticketId: string): Promise<{
+        ticket: MerchantWorkTicket;
+    }>;
+    /** Submit a bounded result after the checkout operation is confirmed settled. */
+    submitWorkTicketResult(ticketId: string, input: MerchantWorkResultInput): Promise<{
+        ticket: WorkTicketSummary;
+        buyerResultChallenge: string;
+        retentionDays: number;
+    }>;
     private request;
 }
 export {};

package/dist/index.js

@@ -159,6 +159,44 @@ export class MerchantClient {
     getSale(operationId) {
         return this.request("GET", `/v1/agent/merchant/sales/${encodeURIComponent(operationId)}`, undefined, true);
     }
+    /** Read this merchant's private work inbox; requires the merchant:work scope. */
+    listWorkTickets(input = {}) {
+        const limit = input.limit ?? 20;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 50)
+            throw new TypeError("limit must be an integer from 1 through 50.");
+        const query = new URLSearchParams({ limit: String(limit) });
+        if (input.states !== undefined) {
+            if (!Array.isArray(input.states) || input.states.length === 0 || input.states.length > 10 || !input.states.every(state => workTicketStates.includes(state))) {
+                throw new TypeError("states must contain 1–10 supported Work Ticket states.");
+            }
+            query.set("states", input.states.join(","));
+        }
+        return this.request("GET", `/v1/agent/work-tickets?${query}`, undefined, true);
+    }
+    /** Public progress and recovery metadata; no API key, private input, or result bytes. */
+    getWorkTicketStatus(ticketId) {
+        return this.request("GET", `/v1/work-tickets/${checkedWorkTicketId(ticketId)}`);
+    }
+    /** Claim a ticket addressed to this merchant for a bounded lease. */
+    claimWorkTicket(ticketId, leaseSeconds = 600) {
+        if (!Number.isInteger(leaseSeconds) || leaseSeconds < 30 || leaseSeconds > 3600)
+            throw new TypeError("leaseSeconds must be an integer from 30 through 3600.");
+        return this.request("POST", `/v1/agent/work-tickets/${checkedWorkTicketId(ticketId)}/claims`, { leaseSeconds }, true);
+    }
+    /** Submit one fixed quote; the server rejects amounts above the buyer-signed cap. */
+    quoteWorkTicket(ticketId, input) {
+        if (!Number.isInteger(input.expiresInSeconds) || input.expiresInSeconds < 30 || input.expiresInSeconds > 3600)
+            throw new TypeError("expiresInSeconds must be an integer from 30 through 3600.");
+        return this.request("POST", `/v1/agent/work-tickets/${checkedWorkTicketId(ticketId)}/quotes`, input, true);
+    }
+    /** Read this merchant's own ticket, including input and buyer receipt metadata. */
+    getWorkTicket(ticketId) {
+        return this.request("GET", `/v1/agent/work-tickets/${checkedWorkTicketId(ticketId)}`, undefined, true);
+    }
+    /** Submit a bounded result after the checkout operation is confirmed settled. */
+    submitWorkTicketResult(ticketId, input) {
+        return this.request("POST", `/v1/agent/work-tickets/${checkedWorkTicketId(ticketId)}/results`, input, true);
+    }
     async request(method, path, body, authenticated = false) {
         if (authenticated && !this.#apiKey) {
             throw new Error("This request requires a merchant API key. Use client.withApiKey(apiKey).");
@@ -170,6 +208,7 @@ export class MerchantClient {
             headers.Authorization = `Bearer ${this.#apiKey}`;
         const response = await this.fetcher(new URL(`${this.baseUrl}${path}`), {
             method,
+            redirect: "error",
             headers,
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
         });
@@ -242,3 +281,10 @@ function isPublicProvider(value) {
 function invalidPublicResponse() {
     return new MerchantApiError(200, "invalid_response", "402Mob returned an incomplete public resource response.");
 }
+const workTicketStates = ["open", "claimed", "quoted", "accepted", "paying", "paid", "delivered", "accepted_by_buyer", "disputed", "expired"];
+function checkedWorkTicketId(id) {
+    if (typeof id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id)) {
+        throw new TypeError("ticketId must be a UUID.");
+    }
+    return id;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "402mob-merchant-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript client for resolving agent resources and enrolling and operating 402Mob merchants.",
   "license": "MIT",
   "repository": {