402mob-merchant-sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.4.0
+
+- Worker profiles: `setWorkerProfile`, `getMyWorkerProfile`, public `getWorkerProfile` and `searchWorkers`, with exported input/response types. No prepared artifact is required. Worker discovery uses its own explicit visibility setting.
+- Public buyer requests: signed publication, reads, merchant prepared-offer proposals and buyer-signed selection returning an independently payable checkout path.
+- `listWorkTickets({order:"latest"})`; oldest remains the default.
+- Validate worker limits, full replacement bodies, Unicode text and the 64 KiB JSON request bound before sending. Check saved content, merchant routing, capability/format correlation, visibility and pagination before returning successful responses.
+- Validate buyer-request challenge fields and checkout terms against the selected proposal, budget, Base USDC and payout. Invalid successful responses raise `MerchantApiError` with code `invalid_response`; a write may already have completed.
+- Include worker discovery and request-to-checkout examples. Examples import packaged `dist` output and are type-checked during tests.
+
+The SDK does not create buyer Work Ticket grants or submit x402 payments. Use the HTTP/MCP ticket protocol with your own signer and spending authority. Worker discovery requires a server release advertising `workerDiscovery` in `/v1/capabilities`. Offline HTTP/MCP/SDK lifecycle tests do not establish live Base Work Ticket or public-request checkout settlement.
+
+## 0.3.1
+
+- Require standard 65-byte EIP-191 enrollment/rotation signatures; retain prepared-resource discovery and seller Work Ticket methods.

package/README.md

@@ -1,9 +1,23 @@
 # 402Mob Merchant SDK
 
+**Version 0.4.0** adds worker profiles and discovery, public buyer requests and newest-first Work Ticket reads. Upgrade from 0.3.1 to use these additions. Check the target server's `/v1/capabilities` first; new worker routes require `workerDiscovery`. See [CHANGELOG.md](./CHANGELOG.md).
+
 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, 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.
 
+## Work inbox order (0.4.0)
+
+`listWorkTickets({order:"latest", limit:50})` reads newest-created tickets first. `order:"oldest"` is the default. HTTP and MCP support this optional order directly. See the [Guild Board guide](https://evidence.contact/guild-board.md).
+
+## Public buyer requests (0.4.0)
+
+The buyer publishes a signed public request, merchants propose owned prepared offers, and a buyer-signed selection returns the exact offer's canonical checkout route. Selection is not payment and does not track a completed purchase. Use SDK 0.4.0 or the HTTP/MCP interfaces for this flow.
+
+Methods: `createBuyerRequestChallenge(input, key)`, `completeBuyerRequest(input, key)`, `listBuyerRequests({query, limit, cursor})`, `getBuyerRequest(id)`, authenticated `proposeBuyerRequestOffer(id, {offerId, note})`, `createBuyerRequestSelectionChallenge(id, {buyer, proposalId})`, and `selectBuyerRequestOffer(id, {challengeId, signature})`. These methods reject incomplete successful responses and checkout handoffs that disagree with the selected proposal, request budget, Base USDC, payout or canonical destination; such errors use `MerchantApiError.code === "invalid_response"`. They never sign or pay as a fallback.
+
+Persist the exact signed publication request and creation key for replay. Sign only after inspecting each returned EIP-191 message. Use a separate payment journal/key for the returned checkout, inspect its actual 402 terms, and authorize spending separately. Request/proposal text is public and untrusted. See the [protocol guide](https://evidence.contact/buyer-requests.md) and [source example](examples/request-to-checkout.ts). Live Base validation of this new sequence is pending; offline integration tests use mocked settlement.
+
 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.
 
 ### Prefer MCP for a connected agent?
@@ -23,10 +37,10 @@ If a message signer is locked, stop retries. `enrollWithTransaction` can use a s
 Install from npm:
 
 ```sh
-npm install 402mob-merchant-sdk
+npm install 402mob-merchant-sdk@0.4.0
 ```
 
-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).
+Version **0.4.0** retains enrollment, resource resolution and seller Work Ticket methods. Enrollment and credential rotation require standard 65-byte EIP-191 signatures; malformed or compact 64-byte signatures are rejected before submission. See the [npm package](https://www.npmjs.com/package/402mob-merchant-sdk) and [source](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 +108,44 @@ 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.
 
+## Worker capabilities and discovery (0.4.0)
+
+An enrolled merchant can offer fresh work without a prepared artifact. Worker visibility is independent of prepared-resource discovery. Only owner calls require `merchant:manage`; search and public known-ID reads send no API key.
+
+```ts
+const merchant = new MerchantClient({ apiKey: process.env.MOB402_API_KEY });
+const saved = await merchant.setWorkerProfile({
+  description: "Scoped repository engineering in our agent runtime.",
+  availability: "accepting",
+  discoverable: true, // Publish only with the merchant owner's approval.
+  capabilities: [{
+    id: "repository-review",
+    title: "Repository review",
+    description: "Find reproducible defects in an agreed revision.",
+    inputDescription: "Repository reference, revision and acceptance criteria; arrange access separately.",
+    resultDescription: "JSON findings, reproduction steps and checks run. Scope and price require a ticket quote.",
+    resultContentTypes: ["application/json"],
+  }],
+});
+const settings = await merchant.getMyWorkerProfile(); // Includes hidden/paused settings.
+
+const buyer = new MerchantClient();
+const page = await buyer.searchWorkers({
+  capability: "repository-review", contentType: "application/json", limit: 20,
+});
+const candidate = page.items[0];
+if (candidate) {
+  const current = await buyer.getWorkerProfile(candidate.merchant.id);
+  console.log(current.merchant.id, current.workerProfile.revision, current.workTicket);
+}
+```
+
+`setWorkerProfile` is a **full replacement**: description, capabilities, availability and discoverable are all required. Do not pass the entire GET response back as input; read-only or unknown fields are rejected. Unchanged normalized content preserves revision/timestamps. Text is trimmed, IDs/formats must be unique, and the whole JSON request must fit within 64 KiB. See the [worker guide](https://evidence.contact/worker-discovery.md) for field limits.
+
+`searchWorkers` returns only opted-in, accepting active merchants. Capability ID and result format must match the same capability. Follow numeric `nextCursor` until null and deduplicate merchant IDs; declarations can change between offset pages. `getWorkerProfile` requires opt-in and can return paused profiles; owner reads include hidden settings. Pausing/unpublishing affects discovery, not existing or independently addressed tickets.
+
+A declaration is not verified expertise or a price. The buyer must independently choose a merchant/capability, sign a Work Ticket grant, review/sign the exact quote and separately authorize payment. This SDK exposes the discovery handoff and seller ticket methods; buyer grant creation, quote acceptance and payment use the documented HTTP/MCP protocol. A server without the new routes can return 404; the SDK preserves that error and never falls back to publishing an artifact or paying.
+
 ## 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`.
@@ -142,6 +194,13 @@ This action moves no USDC and grants no allowance, but it costs Base ETH for gas
 
 ### Public methods
 
+- `searchWorkers({ query?, capability?, contentType?, limit?, cursor? })` — declared accepting workers; no prepared artifact needed.
+- `getWorkerProfile(merchantId)` — public opted-in profile, including paused availability.
+- `createBuyerRequestChallenge(input, idempotencyKey)` — prepare free public demand for the buyer's EIP-191 signature.
+- `completeBuyerRequest(input, idempotencyKey)` — publish/replay the saved signed body using the original key.
+- `listBuyerRequests({ query?, limit?, cursor? })` and `getBuyerRequest(requestId)`.
+- `createBuyerRequestSelectionChallenge(requestId, { buyer, proposalId })` and `selectBuyerRequestOffer(requestId, { challengeId, signature })` — signed selection, returning a checkout handoff without payment.
+- `getWorkTicketStatus(ticketId)` — public progress, not private input or result bytes.
 - `resolveResources({ query?, limit?, cursor? })` — search public, opted-in prepared resources without an API key.
 - `getProviderResources(merchantId)` — read one known provider's public profile and published resources.
 - `resolveLatestResource(merchantId, offerId)` — resolve an older offer ID to the current published version.
@@ -156,12 +215,18 @@ This action moves no USDC and grants no allowance, but it costs Base ETH for gas
 - `rotateWithSignature({ wallet, signMessage })`
 - `rotateWithTransaction({ wallet, submitProof })`
 - `withApiKey(apiKey)`
+
+### Authenticated merchant methods
+
+- `setWorkerProfile(input)` and `getMyWorkerProfile()` — require `merchant:manage`.
+- `proposeBuyerRequestOffer(requestId, { offerId, note })` — an owned active prepared offer; requires `merchant:manage`.
 - `getMerchant()`
 - `createOffer(input)`
 - `setOfferActive(offerId, active)`
 - `setDiscoverable(discoverable)` — opt the merchant into or out of public offer search. Defaults to hidden.
 - `listSales(limit?)`
 - `getSale(operationId)`
+- `listWorkTickets({ states?, limit?, order? })`, `getWorkTicket(ticketId)`, `claimWorkTicket(ticketId, leaseSeconds?)`, `quoteWorkTicket(ticketId, input)` and `submitWorkTicketResult(ticketId, input)` — require `merchant:work`; default inbox order is oldest.
 
 Create offer prices as decimal strings (for example `"0.02"`) to avoid floating-point rounding. Prices must be positive, from `0.000001` through `999999.999999` USDC, with at most six fractional digits. Results are prepared JSON or text artifacts, limited by the service to 48 KiB. An offer's price and content are immutable. To publish an update, submit a higher semantic version and the current `supersedesOfferId`; the new version unpublishes its predecessor.
 
@@ -180,11 +245,14 @@ Create offer prices as decimal strings (for example `"0.02"`) to avoid floating-
 npm install
 npm run build
 npm test
+npm pack --pack-destination /tmp
 ```
 
-The SDK tests use mocked HTTP responses and do not contact `evidence.contact` or submit wallet transactions.
+To test a local build in another project, install the generated file with `npm install /tmp/402mob-merchant-sdk-0.4.0.tgz`. The CLI's published SDK dependency remains 0.3.1 until a separate CLI release.
+
+The SDK tests use mocked HTTP responses and type-check every bundled example. They do not contact `evidence.contact` or submit wallet transactions. Service integration tests in the main repository cover actual local HTTP/enrollment signatures; Work Ticket and public-request live Base validation remain pending.
 
-See [`examples/enroll-and-publish.ts`](./examples/enroll-and-publish.ts) for an adapter-based seller integration and [`examples/resolve-resources.ts`](./examples/resolve-resources.ts) for public buyer-agent discovery. Both examples import the built package output and are included in the npm tarball.
+Examples included in the tarball import the built package output: [enroll and publish](./examples/enroll-and-publish.ts), [resolve prepared resources](./examples/resolve-resources.ts), [worker discovery](./examples/worker-discovery.ts), and [signed request to checkout handoff](./examples/request-to-checkout.ts).
 
 MIT licensed. See [LICENSE](./LICENSE).
 
@@ -201,7 +269,7 @@ Adds `setDiscoverable(discoverable)`, which calls the authenticated `PUT /v1/age
 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)
+## Work Ticket reads and recovery
 
 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.
 
@@ -211,4 +279,4 @@ The supported states are `open`, `claimed`, `quoted`, `accepted`, `paying`, `pai
 
 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.
+These methods are available from version 0.3.0.

package/dist/index.d.ts

@@ -251,6 +251,120 @@ export interface MerchantClientOptions {
     /** Defaults to globalThis.fetch. */
     fetch?: typeof globalThis.fetch;
 }
+export interface WorkerCapability {
+    /** Exact routing hint: 3–64 lowercase letters, digits or hyphens, alphanumeric ends. */
+    id: string;
+    title: string;
+    description: string;
+    inputDescription: string;
+    resultDescription: string;
+    resultContentTypes: ArtifactContentType[];
+}
+/** Full replacement. Discovery flags do not cancel or restrict independently addressed tickets. */
+export interface WorkerProfileInput {
+    description: string;
+    capabilities: WorkerCapability[];
+    availability: "accepting" | "paused";
+    discoverable: boolean;
+}
+export interface WorkerProfile extends WorkerProfileInput {
+    merchantId: string;
+    revision: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface WorkerProfileView {
+    merchant: {
+        id: string;
+        name: string;
+        payoutAddress: EvmAddress;
+    };
+    workerProfile: WorkerProfile;
+    workTicket: {
+        method: "POST";
+        challengePath: "/v1/work-tickets/challenges";
+        merchantId: string;
+        guide: "/work-tickets.md";
+        paymentRequiredToCreate: false;
+        quoteRequired: true;
+    };
+}
+export interface WorkerSearchInput {
+    /** Case-insensitive substring, at most 80 characters after trimming. */
+    query?: string;
+    /** Exact declared capability; the same capability must satisfy contentType. */
+    capability?: string;
+    contentType?: ArtifactContentType;
+    /** 1–50, default 20. */
+    limit?: number;
+    /** Numeric offset, default 0; follow nextCursor and deduplicate merchant IDs. */
+    cursor?: number;
+}
+export interface WorkerDirectoryPage {
+    items: WorkerProfileView[];
+    nextCursor: number | null;
+}
+export interface BuyerRequestInput {
+    buyer: EvmAddress;
+    title: string;
+    description: string;
+    maxPriceUSDC: string;
+    contentType: ArtifactContentType;
+    expiresInSeconds: number;
+}
+export interface BuyerRequestChallenge {
+    challengeId: string;
+    message: string;
+    expiresAt: string;
+    requestExpiresAt: string;
+    policyHash: string;
+}
+export interface PublicBuyerRequest {
+    id: string;
+    title: string;
+    description: string;
+    maxPriceAtomic: string;
+    contentType: ArtifactContentType;
+    state: "open" | "selected" | "expired";
+    createdAt: string;
+    expiresAt: string;
+    selectedProposalId: string | null;
+}
+export interface BuyerRequestProposal {
+    id: string;
+    requestId: string;
+    merchantId: string;
+    offerId: string;
+    note: string;
+    title: string;
+    version: string;
+    amountAtomic: string;
+    contentType: ArtifactContentType;
+    payoutAddress: EvmAddress;
+    termsHash: string;
+    createdAt: string;
+}
+export interface BuyerCheckoutHandoff {
+    merchantId: string;
+    offerId: string;
+    amountAtomic: string;
+    payTo: EvmAddress;
+    network: "eip155:8453";
+    asset: EvmAddress;
+    contentType: ArtifactContentType;
+    method: "POST";
+    path: string;
+    body: Record<string, never>;
+    directTransferChallenge: string;
+    mcpTool: "buy_prepared_artifact";
+    paymentRequired: true;
+    paymentStatus: "not_observed";
+}
+export interface BuyerRequestDetail {
+    request: PublicBuyerRequest;
+    proposals: BuyerRequestProposal[];
+    checkoutHandoff: BuyerCheckoutHandoff | null;
+}
 export interface CreateEnrollmentInput {
     wallet: EvmAddress;
     name: string;
@@ -302,6 +416,14 @@ export declare class MerchantClient {
     constructor(options?: MerchantClientOptions);
     /** Return a new client with the supplied key; no key is written to disk or logged. */
     withApiKey(apiKey: string): MerchantClient;
+    /** Full replacement, with separate worker-discovery opt-in. No artifact or wallet action. */
+    setWorkerProfile(input: WorkerProfileInput): Promise<WorkerProfileView>;
+    /** Requires merchant:manage; includes this merchant's unpublished or paused settings. */
+    getMyWorkerProfile(): Promise<WorkerProfileView>;
+    /** Public known-ID read. Opt-in is required; a paused profile can remain visible. */
+    getWorkerProfile(merchantId: string): Promise<WorkerProfileView>;
+    /** Public opted-in, accepting worker declarations; no key, quote or payment authorization. */
+    searchWorkers(input?: WorkerSearchInput): Promise<WorkerDirectoryPage>;
     createEnrollmentChallenge(input: CreateEnrollmentInput): Promise<EnrollmentChallenge>;
     completeEnrollmentWithSignature(input: CompleteSignatureInput): Promise<EnrollmentResult>;
     completeEnrollmentWithTransaction(input: CompleteTransactionInput): Promise<EnrollmentResult>;
@@ -338,6 +460,7 @@ export declare class MerchantClient {
     listWorkTickets(input?: {
         states?: WorkTicketState[];
         limit?: number;
+        order?: "oldest" | "latest";
     }): Promise<WorkTicketInbox>;
     /** Public progress and recovery metadata; no API key, private input, or result bytes. */
     getWorkTicketStatus(ticketId: string): Promise<{
@@ -362,6 +485,42 @@ export declare class MerchantClient {
         buyerResultChallenge: string;
         retentionDays: number;
     }>;
+    /** Free public demand. Caller persists the key, signs the returned message and completes separately. */
+    createBuyerRequestChallenge(input: BuyerRequestInput, idempotencyKey: string): Promise<BuyerRequestChallenge>;
+    completeBuyerRequest(input: BuyerRequestInput & {
+        challengeId: string;
+        signature: EvmSignature;
+    }, idempotencyKey: string): Promise<BuyerRequestDetail & {
+        replay: boolean;
+    }>;
+    listBuyerRequests(input?: ResolveAgentResourcesInput): Promise<{
+        items: PublicBuyerRequest[];
+        nextCursor: number | null;
+    }>;
+    getBuyerRequest(requestId: string): Promise<BuyerRequestDetail>;
+    proposeBuyerRequestOffer(requestId: string, input: {
+        offerId: string;
+        note: string;
+    }): Promise<{
+        proposal: BuyerRequestProposal;
+        replay: boolean;
+    }>;
+    createBuyerRequestSelectionChallenge(requestId: string, input: {
+        buyer: EvmAddress;
+        proposalId: string;
+    }): Promise<{
+        challengeId: string;
+        message: string;
+        expiresAt: string;
+        proposal: BuyerRequestProposal;
+    }>;
+    /** Return a checkout handoff; this method never authorizes or submits payment. */
+    selectBuyerRequestOffer(requestId: string, input: {
+        challengeId: string;
+        signature: EvmSignature;
+    }): Promise<BuyerRequestDetail & {
+        replay: boolean;
+    }>;
     private request;
 }
 export {};

package/dist/index.js

@@ -1,3 +1,14 @@
+function requireEip191Signature(signature) {
+    if (!/^0x[0-9a-fA-F]{130}$/.test(signature)) {
+        throw new TypeError("signature must be a 65-byte EIP-191 signature encoded as 0x-prefixed hex.");
+    }
+    return signature;
+}
+function buyerRequestKey(key) {
+    if (!/^[A-Za-z0-9_-]{16,128}$/.test(key))
+        throw new TypeError("Persist an idempotency key of 16–128 letters, digits, underscores or hyphens.");
+    return key;
+}
 export class MerchantApiError extends Error {
     status;
     code;
@@ -40,11 +51,46 @@ export class MerchantClient {
     withApiKey(apiKey) {
         return new MerchantClient({ baseUrl: this.baseUrl, apiKey, fetch: this.fetcher });
     }
+    /** Full replacement, with separate worker-discovery opt-in. No artifact or wallet action. */
+    setWorkerProfile(input) {
+        if (!isWorkerProfileInput(input) || !onlyKeys(input, ["description", "capabilities", "availability", "discoverable"]) || !input.capabilities.every(cap => onlyKeys(cap, ["id", "title", "description", "inputDescription", "resultDescription", "resultContentTypes"])))
+            throw new TypeError("Provide the worker profile PUT body: bounded descriptions, unique capability IDs/formats, availability and explicit discoverable. Unknown or read-only fields are not allowed.");
+        const body = normalizedWorkerProfile(input);
+        if (new TextEncoder().encode(JSON.stringify(body)).byteLength > 64 * 1024)
+            throw new TypeError("The whole worker profile JSON request must fit within 64 KiB.");
+        return this.request("PUT", "/v1/agent/merchant/worker-profile", body, true);
+    }
+    /** Requires merchant:manage; includes this merchant's unpublished or paused settings. */
+    getMyWorkerProfile() { return this.request("GET", "/v1/agent/merchant/worker-profile", undefined, true); }
+    /** Public known-ID read. Opt-in is required; a paused profile can remain visible. */
+    getWorkerProfile(merchantId) {
+        if (!uuid(merchantId))
+            throw new TypeError("merchantId must be a UUID.");
+        return this.request("GET", `/v1/merchants/${merchantId}/worker-profile`);
+    }
+    /** Public opted-in, accepting worker declarations; no key, quote or payment authorization. */
+    searchWorkers(input = {}) {
+        if (input.query !== undefined && (typeof input.query !== "string" || input.query.trim().length > 80))
+            throw new TypeError("query must be at most 80 characters.");
+        if (input.capability !== undefined && !validWorkerCapabilityId(input.capability))
+            throw new TypeError("capability must be a lowercase slug of 3–64 characters.");
+        if (input.contentType !== undefined && !artifactType(input.contentType))
+            throw new TypeError("Unsupported worker result format.");
+        const limit = input.limit ?? 20, cursor = input.cursor ?? 0;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50 || !Number.isSafeInteger(cursor) || cursor < 0 || cursor > 100000000)
+            throw new TypeError("Use limit 1–50 and a nonnegative numeric cursor.");
+        const query = new URLSearchParams({ q: input.query?.trim() ?? "", limit: String(limit), cursor: String(cursor) });
+        if (input.capability)
+            query.set("capability", input.capability);
+        if (input.contentType)
+            query.set("contentType", input.contentType);
+        return this.request("GET", "/v1/worker-directory?" + query);
+    }
     createEnrollmentChallenge(input) {
         return this.request("POST", "/v1/merchants/enrollment-challenges", input);
     }
     completeEnrollmentWithSignature(input) {
-        return this.request("POST", "/v1/merchants/enrollments", input);
+        return this.request("POST", "/v1/merchants/enrollments", { ...input, signature: requireEip191Signature(input.signature) });
     }
     completeEnrollmentWithTransaction(input) {
         return this.request("POST", "/v1/merchants/enrollments/transaction", input);
@@ -52,7 +98,7 @@ export class MerchantClient {
     /** Request a challenge, ask the caller's wallet adapter to sign its exact message, then enroll. */
     async enrollWithSignature(input) {
         const challenge = await this.createEnrollmentChallenge({ wallet: input.wallet, name: input.name });
-        const signature = await input.signMessage(challenge.message);
+        const signature = requireEip191Signature(await input.signMessage(challenge.message));
         return this.completeEnrollmentWithSignature({
             wallet: input.wallet,
             name: input.name,
@@ -75,14 +121,14 @@ export class MerchantClient {
         return this.request("POST", "/v1/merchants/credential-challenges", { wallet });
     }
     rotateCredentialWithSignature(wallet, challengeId, signature) {
-        return this.request("POST", "/v1/merchants/credentials/rotate", { wallet, challengeId, signature });
+        return this.request("POST", "/v1/merchants/credentials/rotate", { wallet, challengeId, signature: requireEip191Signature(signature) });
     }
     rotateCredentialWithTransaction(input) {
         return this.request("POST", "/v1/merchants/credentials/rotate-transaction", input);
     }
     async rotateWithSignature(input) {
         const challenge = await this.createCredentialRotationChallenge(input.wallet);
-        const signature = await input.signMessage(challenge.message);
+        const signature = requireEip191Signature(await input.signMessage(challenge.message));
         return this.rotateCredentialWithSignature(input.wallet, challenge.challengeId, signature);
     }
     async rotateWithTransaction(input) {
@@ -165,6 +211,11 @@ export class MerchantClient {
         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.order !== undefined) {
+            if (input.order !== "oldest" && input.order !== "latest")
+                throw new TypeError("order must be oldest or latest.");
+            query.set("order", input.order);
+        }
         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.");
@@ -197,11 +248,37 @@ export class MerchantClient {
     submitWorkTicketResult(ticketId, input) {
         return this.request("POST", `/v1/agent/work-tickets/${checkedWorkTicketId(ticketId)}/results`, input, true);
     }
-    async request(method, path, body, authenticated = false) {
+    /** Free public demand. Caller persists the key, signs the returned message and completes separately. */
+    createBuyerRequestChallenge(input, idempotencyKey) {
+        return this.request("POST", "/v1/buyer-requests/challenges", input, false, { "Idempotency-Key": buyerRequestKey(idempotencyKey) });
+    }
+    completeBuyerRequest(input, idempotencyKey) {
+        return this.request("POST", "/v1/buyer-requests", { ...input, signature: requireEip191Signature(input.signature) }, false, { "Idempotency-Key": buyerRequestKey(idempotencyKey) });
+    }
+    listBuyerRequests(input = {}) {
+        const query = input.query ?? "", limit = input.limit ?? 20, cursor = input.cursor ?? 0;
+        if (typeof query !== "string" || query.trim().length > 80 || !Number.isInteger(limit) || limit < 1 || limit > 50 || !Number.isSafeInteger(cursor) || cursor < 0 || cursor > 100000000)
+            throw new TypeError("Use a query up to 80 characters, limit 1–50 and cursor 0–100000000.");
+        return this.request("GET", "/v1/buyer-requests?" + new URLSearchParams({ q: query.trim(), limit: String(limit), cursor: String(cursor) }));
+    }
+    getBuyerRequest(requestId) {
+        return this.request("GET", `/v1/buyer-requests/${checkedWorkTicketId(requestId)}`);
+    }
+    proposeBuyerRequestOffer(requestId, input) {
+        return this.request("POST", `/v1/agent/buyer-requests/${checkedWorkTicketId(requestId)}/proposals`, input, true);
+    }
+    createBuyerRequestSelectionChallenge(requestId, input) {
+        return this.request("POST", `/v1/buyer-requests/${checkedWorkTicketId(requestId)}/selection-challenges`, input);
+    }
+    /** Return a checkout handoff; this method never authorizes or submits payment. */
+    selectBuyerRequestOffer(requestId, input) {
+        return this.request("POST", `/v1/buyer-requests/${checkedWorkTicketId(requestId)}/selections`, { ...input, signature: requireEip191Signature(input.signature) });
+    }
+    async request(method, path, body, authenticated = false, extraHeaders = {}) {
         if (authenticated && !this.#apiKey) {
             throw new Error("This request requires a merchant API key. Use client.withApiKey(apiKey).");
         }
-        const headers = { Accept: "application/json" };
+        const headers = { Accept: "application/json", ...extraHeaders };
         if (body !== undefined)
             headers["Content-Type"] = "application/json";
         if (authenticated && this.#apiKey)
@@ -228,6 +305,25 @@ export class MerchantClient {
         const invalidResponse = () => new MerchantApiError(response.status, "invalid_response", "402Mob returned an incomplete response. The request may have completed; preserve recovery data. If enrollment or rotation completed without a usable key, use credential rotation.");
         if (!isRecord(payload))
             throw invalidResponse();
+        if (path.startsWith("/v1/worker-directory?")) {
+            if (!Array.isArray(payload.items) || !payload.items.every(item => isWorkerProfileView(item) && item.workerProfile.discoverable && item.workerProfile.availability === "accepting") || !(payload.nextCursor === null || Number.isSafeInteger(payload.nextCursor) && Number(payload.nextCursor) >= 0))
+                throw invalidResponse();
+            const params = new URL(path, "https://schema.invalid").searchParams, capability = params.get("capability"), type = params.get("contentType"), limit = Number(params.get("limit")), cursor = Number(params.get("cursor"));
+            const items = payload.items;
+            if (items.length > limit || new Set(items.map(item => item.merchant.id)).size !== items.length || payload.nextCursor !== null && (items.length !== limit || Number(payload.nextCursor) !== cursor + limit) || !items.every(item => item.workerProfile.capabilities.some(cap => (!capability || cap.id === capability) && (!type || cap.resultContentTypes.includes(type)))))
+                throw invalidResponse();
+        }
+        if (path.endsWith("/worker-profile")) {
+            if (!isWorkerProfileView(payload))
+                throw invalidResponse();
+            const requested = path.match(/^\/v1\/merchants\/([^/]+)\/worker-profile$/)?.[1];
+            if (requested && (payload.merchant.id !== requested || !payload.workerProfile.discoverable))
+                throw invalidResponse();
+            if (method === "PUT" && JSON.stringify(normalizedWorkerProfile(payload.workerProfile)) !== JSON.stringify(body))
+                throw invalidResponse();
+        }
+        if ((path.startsWith("/v1/buyer-requests") || path.startsWith("/v1/agent/buyer-requests/")) && !isBuyerRequestResponse(method, path, payload, body))
+            throw invalidResponse();
         if (path === "/v1/merchants/enrollment-challenges" || path === "/v1/merchants/credential-challenges") {
             const proof = payload.transactionProof;
             if (!nonempty(payload.challengeId) || !nonempty(payload.message) || !nonempty(payload.expiresAt) ||
@@ -252,6 +348,96 @@ function isRecord(value) {
 }
 function nonempty(value) { return typeof value === "string" && value.trim().length > 0; }
 function address(value) { return typeof value === "string" && /^0x[0-9a-fA-F]{40}$/.test(value); }
+const baseUsdc = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+function uuid(value) { return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value); }
+function timestamp(value) { return typeof value === "string" && Number.isFinite(Date.parse(value)); }
+function digest(value) { return typeof value === "string" && /^[0-9a-f]{64}$/.test(value); }
+function atomicAmount(value) { return typeof value === "string" && /^[1-9][0-9]{0,11}$/.test(value); }
+function publicText(value, max) { return typeof value === "string" && value.trim().length > 0 && Array.from(value).length <= max; }
+function artifactType(value) { return value === "application/json" || value === "text/plain; charset=utf-8"; }
+function validWorkerCapabilityId(value) { return typeof value === "string" && /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/.test(value); }
+function onlyKeys(value, keys) { return Object.keys(value).every(key => keys.includes(key)); }
+function boundedWorkerText(value, max) { return typeof value === "string" && value.trim().length > 0 && Array.from(value.trim()).length <= max; }
+function normalizedWorkerProfile(value) {
+    return { description: value.description.trim(), capabilities: value.capabilities.map(cap => ({ id: cap.id, title: cap.title.trim(), description: cap.description.trim(), inputDescription: cap.inputDescription.trim(), resultDescription: cap.resultDescription.trim(), resultContentTypes: [...cap.resultContentTypes] })), availability: value.availability, discoverable: value.discoverable };
+}
+function isWorkerProfileInput(value) {
+    if (!isRecord(value) || !boundedWorkerText(value.description, 1000) || (value.availability !== "accepting" && value.availability !== "paused") || typeof value.discoverable !== "boolean" || !Array.isArray(value.capabilities) || !value.capabilities.length || value.capabilities.length > 10)
+        return false;
+    if (new Set(value.capabilities.map(c => isRecord(c) ? c.id : null)).size !== value.capabilities.length)
+        return false;
+    return value.capabilities.every(c => isRecord(c) && validWorkerCapabilityId(c.id) && boundedWorkerText(c.title, 100) && boundedWorkerText(c.description, 1000) && boundedWorkerText(c.inputDescription, 1000) && boundedWorkerText(c.resultDescription, 1000) && Array.isArray(c.resultContentTypes) && c.resultContentTypes.length >= 1 && c.resultContentTypes.length <= 2 && new Set(c.resultContentTypes).size === c.resultContentTypes.length && c.resultContentTypes.every(artifactType));
+}
+function isWorkerProfileView(value) {
+    if (!isRecord(value) || !isRecord(value.merchant) || !uuid(value.merchant.id) || !publicText(value.merchant.name, 100) || !address(value.merchant.payoutAddress) || !isWorkerProfileInput(value.workerProfile))
+        return false;
+    const profile = value.workerProfile;
+    return profile.merchantId === value.merchant.id && Number.isSafeInteger(profile.revision) && profile.revision > 0 && timestamp(profile.createdAt) && timestamp(profile.updatedAt) && isRecord(value.workTicket) && value.workTicket.method === "POST" && value.workTicket.challengePath === "/v1/work-tickets/challenges" && value.workTicket.merchantId === value.merchant.id && value.workTicket.guide === "/work-tickets.md" && value.workTicket.paymentRequiredToCreate === false && value.workTicket.quoteRequired === true;
+}
+function usdcAtomic(value) {
+    if (typeof value !== "string")
+        return;
+    const parts = /^(0|[1-9][0-9]{0,5})(?:\.([0-9]{1,6}))?$/.exec(value);
+    return parts ? BigInt(parts[1] + (parts[2] ?? "").padEnd(6, "0")).toString() : undefined;
+}
+function isPublicBuyerRequest(value) {
+    if (!isRecord(value))
+        return false;
+    return uuid(value.id) && publicText(value.title, 100) && publicText(value.description, 2000) && atomicAmount(value.maxPriceAtomic) && artifactType(value.contentType) &&
+        ["open", "selected", "expired"].includes(String(value.state)) && timestamp(value.createdAt) && timestamp(value.expiresAt) &&
+        (value.state === "selected" ? uuid(value.selectedProposalId) : value.selectedProposalId === null);
+}
+function isBuyerRequestProposal(value) {
+    if (!isRecord(value))
+        return false;
+    return uuid(value.id) && uuid(value.requestId) && uuid(value.merchantId) && uuid(value.offerId) && publicText(value.note, 300) && publicText(value.title, 100) &&
+        typeof value.version === "string" && /^(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})$/.test(value.version) &&
+        atomicAmount(value.amountAtomic) && artifactType(value.contentType) && address(value.payoutAddress) && digest(value.termsHash) && timestamp(value.createdAt);
+}
+function isBuyerCheckoutHandoff(value, proposal) {
+    if (!isRecord(value))
+        return false;
+    const path = `/v1/merchants/${proposal.merchantId}/offers/${proposal.offerId}/checkout`;
+    return value.merchantId === proposal.merchantId && value.offerId === proposal.offerId && value.amountAtomic === proposal.amountAtomic &&
+        address(value.payTo) && value.payTo.toLowerCase() === proposal.payoutAddress.toLowerCase() && value.contentType === proposal.contentType &&
+        value.network === "eip155:8453" && typeof value.asset === "string" && value.asset.toLowerCase() === baseUsdc && value.method === "POST" && value.path === path &&
+        value.directTransferChallenge === path + "/transfer-challenges" && isRecord(value.body) && Object.keys(value.body).length === 0 &&
+        value.mcpTool === "buy_prepared_artifact" && value.paymentRequired === true && value.paymentStatus === "not_observed";
+}
+function isBuyerRequestDetail(value, expectedId) {
+    if (!isRecord(value) || !isPublicBuyerRequest(value.request) || !Array.isArray(value.proposals) || value.proposals.length > 20 || !value.proposals.every(isBuyerRequestProposal))
+        return false;
+    const request = value.request, proposals = value.proposals;
+    if (expectedId && request.id !== expectedId)
+        return false;
+    if (new Set(proposals.map(p => p.id)).size !== proposals.length || new Set(proposals.map(p => p.merchantId)).size !== proposals.length ||
+        proposals.some(p => p.requestId !== request.id || p.contentType !== request.contentType || BigInt(p.amountAtomic) > BigInt(request.maxPriceAtomic)))
+        return false;
+    if (request.state !== "selected")
+        return value.checkoutHandoff === null;
+    const selected = proposals.find(p => p.id === request.selectedProposalId);
+    return Boolean(selected && isBuyerCheckoutHandoff(value.checkoutHandoff, selected));
+}
+function isBuyerRequestResponse(method, path, value, body) {
+    const args = isRecord(body) ? body : {};
+    const challenge = () => uuid(value.challengeId) && nonempty(value.message) && timestamp(value.expiresAt);
+    const id = path.match(/^\/v1\/(?:agent\/)?buyer-requests\/([^/?]+)/)?.[1];
+    if (path === "/v1/buyer-requests/challenges")
+        return challenge() && timestamp(value.requestExpiresAt) && digest(value.policyHash) && Date.parse(value.expiresAt) <= Date.parse(value.requestExpiresAt);
+    if (path === "/v1/buyer-requests" && method === "POST")
+        return isBuyerRequestDetail(value) && typeof value.replay === "boolean" &&
+            value.request.title === (typeof args.title === "string" ? args.title.trim() : undefined) && value.request.description === (typeof args.description === "string" ? args.description.trim() : undefined) && value.request.contentType === args.contentType && value.request.maxPriceAtomic === usdcAtomic(args.maxPriceUSDC);
+    if (path.startsWith("/v1/buyer-requests?") || (path === "/v1/buyer-requests" && method === "GET"))
+        return Array.isArray(value.items) && value.items.length <= 50 && value.items.every(isPublicBuyerRequest) &&
+            (value.nextCursor === null || (Number.isSafeInteger(value.nextCursor) && value.nextCursor >= 0));
+    if (path.endsWith("/selection-challenges"))
+        return challenge() && isBuyerRequestProposal(value.proposal) && value.proposal.requestId === id && value.proposal.id === args.proposalId;
+    if (path.endsWith("/proposals"))
+        return isBuyerRequestProposal(value.proposal) && value.proposal.requestId === id && value.proposal.offerId === args.offerId && value.proposal.note === (typeof args.note === "string" ? args.note.trim() : undefined) && typeof value.replay === "boolean";
+    if (path.endsWith("/selections"))
+        return isBuyerRequestDetail(value, id) && value.request.state === "selected" && typeof value.replay === "boolean";
+    return method === "GET" && isBuyerRequestDetail(value, id);
+}
 function isAgentResource(value) {
     if (!isRecord(value))
         return false;

package/examples/request-to-checkout.ts

@@ -0,0 +1,25 @@
+// SDK 0.4.0 example. This stops before payment.
+// Buyer and seller run independently; exchange only the public request/proposal IDs.
+import { MerchantClient, type BuyerRequestInput, type EvmSignature } from "../dist/index.js";
+
+export async function publishDemand(client:MerchantClient,input:BuyerRequestInput,key:string,sign:(message:string)=>Promise<EvmSignature>,persist:(value:unknown)=>Promise<void>) {
+  const challenge=await client.createBuyerRequestChallenge(input,key);
+  // The caller must inspect origin, public text, budget, format and expiry first.
+  const completion={...input,challengeId:challenge.challengeId,signature:await sign(challenge.message)};
+  await persist({key,completion}); // Save BEFORE dispatch; replay exactly after interruption.
+  return client.completeBuyerRequest(completion,key);
+}
+
+export async function proposePreparedOffer(merchant:MerchantClient,requestId:string,offerId:string) {
+  return merchant.proposeBuyerRequestOffer(requestId,{offerId,note:"Prepared artifact matching the public request."});
+}
+
+export async function selectForCheckout(buyer:MerchantClient,requestId:string,wallet:`0x${string}`,proposalId:string,sign:(message:string)=>Promise<EvmSignature>,persist:(value:unknown)=>Promise<void>) {
+  const challenge=await buyer.createBuyerRequestSelectionChallenge(requestId,{buyer:wallet,proposalId});
+  // Review the exact offer, price, payout and version before signing.
+  const selection={challengeId:challenge.challengeId,signature:await sign(challenge.message)};
+  await persist({requestId,selection});
+  const selected=await buyer.selectBuyerRequestOffer(requestId,selection);
+  // Separate payment authorization/journal is required to use this handoff.
+  return selected.checkoutHandoff;
+}

package/examples/worker-discovery.ts

@@ -0,0 +1,43 @@
+import {
+  MerchantClient,
+  type WorkerProfileInput,
+  type WorkerProfileView,
+  type ArtifactContentType,
+} from "../dist/index.js";
+
+/** The caller approves capabilities, availability and public visibility before this full replacement. */
+export async function publishWorkerProfile(merchant: MerchantClient, input: WorkerProfileInput) {
+  const saved = await merchant.setWorkerProfile(input);
+  return { saved, current: await merchant.getMyWorkerProfile() };
+}
+
+/** Read-only: inspect declarations, then use the Work Ticket protocol with a separate buyer signer. */
+export async function findWorkers(
+  buyer: MerchantClient,
+  capability: string,
+  contentType: ArtifactContentType = "application/json",
+): Promise<WorkerProfileView[]> {
+  const seen = new Map<string, WorkerProfileView>();
+  let cursor: number | null = 0;
+  // Bounded pass, since concurrent declaration changes can shift offset pages.
+  for (let page = 0; page < 4 && cursor !== null; page++) {
+    const result = await buyer.searchWorkers({ capability, contentType, limit: 50, cursor });
+    for (const worker of result.items) seen.set(worker.merchant.id, worker);
+    cursor = result.nextCursor;
+  }
+  return [...seen.values()];
+}
+
+export const repositoryReview: WorkerProfileInput = {
+  description: "Bounded repository review in our agent runtime.",
+  availability: "accepting",
+  discoverable: false, // Explicit opt-in belongs to the merchant owner.
+  capabilities: [{
+    id: "repository-review",
+    title: "Repository review",
+    description: "Find reproducible defects within an agreed revision and scope.",
+    inputDescription: "Repository reference, revision and acceptance criteria; arrange access separately.",
+    resultDescription: "JSON findings, reproduction steps and checks run. Price and scope require a ticket quote.",
+    resultContentTypes: ["application/json"],
+  }],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "402mob-merchant-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeScript client for resolving agent resources and enrolling and operating 402Mob merchants.",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,7 @@
     "dist",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "main": "./dist/index.js",
@@ -27,7 +28,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test tests/*.test.mjs",
+    "test": "npm run build && npm run typecheck:examples && node --test tests/*.test.mjs",
+    "typecheck:examples": "tsc -p tsconfig.examples.json",
     "prepare": "npm run build"
   },
   "devDependencies": {