402mob-merchant-sdk 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # 402Mob Merchant SDK
 
-An open-source, dependency-free TypeScript client for enrolling and operating a 402Mob merchant from a Node.js server or agent runtime.
+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.
 
@@ -26,7 +26,7 @@ Install from npm:
 npm install 402mob-merchant-sdk
 ```
 
-Prepared package version: **0.1.2**. Publish this version before installing it from npm. 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 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).
 
 Requires Node.js 18 or newer. The SDK uses the built-in Fetch API and has no runtime dependencies.
 
@@ -56,11 +56,44 @@ const offer = await merchant.createOffer({
   result: { summary: "Prepared by the seller agent" },
 });
 
+// Make active offers searchable in the public merchant directory.
+await merchant.setDiscoverable(true);
+
 console.log({ offerId: offer.id, checkout: offer.checkout });
 ```
 
 `wallet.signMessage` above is an adapter-specific example. The SDK never receives a private key and never logs the returned signature or API key.
 
+## Resolve agent resources
+
+Buyer agents can search opted-in providers without an API key, inspect a provider by known merchant ID, and resolve a saved offer ID to its current published version.
+
+```ts
+import { MerchantClient } from "402mob-merchant-sdk";
+
+const buyer = new MerchantClient();
+const page = await buyer.resolveResources({ query: "payment summary", limit: 20 });
+
+for (const { merchant, offer } of page.items) {
+  console.log({
+    provider: merchant.name,
+    title: offer.title,
+    priceUSDC: offer.amountUSDC,
+    checkout: offer.checkout,
+  });
+}
+
+if (page.items[0]) {
+  const current = await buyer.resolveLatestResource(
+    page.items[0].merchant.id,
+    page.items[0].offer.id,
+  );
+  console.log(current.offer.version, current.offer.title);
+}
+```
+
+`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.
+
 ## 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.
@@ -88,6 +121,9 @@ This action moves no USDC and grants no allowance, but it costs Base ETH for gas
 
 ### Public methods
 
+- `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.
 - `createEnrollmentChallenge({ wallet, name })`
 - `completeEnrollmentWithSignature({ wallet, name, challengeId, signature })`
 - `completeEnrollmentWithTransaction({ wallet, name, challengeId, method, transactionHash })`
@@ -102,10 +138,11 @@ This action moves no USDC and grants no allowance, but it costs Base ETH for gas
 - `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)`
 
-Create offer prices as decimal strings (for example `"0.02"`) to avoid floating-point rounding. 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.
+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.
 
 ## Safety and behavior
 
@@ -126,10 +163,18 @@ npm test
 
 The SDK tests use mocked HTTP responses and do not contact `evidence.contact` or submit wallet transactions.
 
-See [`examples/enroll-and-publish.ts`](./examples/enroll-and-publish.ts) for an adapter-based integration that enrolls a wallet and creates its first offer.
+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.
 
 MIT licensed. See [LICENSE](./LICENSE).
 
+## Version 0.2.0
+
+Adds public buyer-agent methods `resolveResources`, `getProviderResources`, and `resolveLatestResource`, plus typed resource response interfaces. The calls need no merchant key and do not make purchases. Existing seller enrollment and management methods remain available.
+
+## Version 0.1.3
+
+Adds `setDiscoverable(discoverable)`, which calls the authenticated `PUT /v1/agent/merchant/discovery` endpoint. The service controls visibility; enrollment still defaults to hidden. Directory search exposes active offer descriptions and prices to public callers.
+
 ## 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. The npm registry still serves 0.1.1 until 0.1.2 is published. 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.
+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.

package/dist/index.d.ts

@@ -33,6 +33,8 @@ export interface MerchantProfile {
     name: string;
     payoutAddress: EvmAddress;
     createdAt: string;
+    /** Present in authenticated merchant workspace responses; opt-in controls directory search. */
+    discoverable?: boolean;
 }
 export interface MerchantAgent {
     id: string;
@@ -111,6 +113,54 @@ export interface MerchantWorkspace {
     merchant: MerchantProfile;
     offers: MerchantOffer[];
 }
+/** Public provider fields returned while an agent resolves available resources. */
+export interface AgentResourceProvider {
+    id: string;
+    name: string;
+    /** Present in directory results; points to the provider's public profile. */
+    profile?: string;
+    /** Present in direct profile and latest-resource lookups. */
+    payoutAddress?: EvmAddress;
+    createdAt?: string;
+}
+/** A provider-published, fixed-price resource descriptor. */
+export interface AgentResource {
+    id: string;
+    seriesId: string;
+    version: string;
+    title: string;
+    description: string;
+    amountAtomic: string;
+    amountUSDC: string;
+    contentType: ArtifactContentType;
+    latest: string;
+    checkout: string;
+    directTransferChallenge: string;
+    supersedesOfferId?: string | null;
+}
+export interface ResolvedAgentResource {
+    merchant: AgentResourceProvider;
+    offer: AgentResource;
+}
+export interface AgentResourcePage {
+    items: ResolvedAgentResource[];
+    nextCursor: number | null;
+}
+export interface ResolveAgentResourcesInput {
+    /** Searches provider names, resource titles, and descriptions; maximum 80 characters. */
+    query?: string;
+    /** Page size from 1 through 50; defaults to 20. */
+    limit?: number;
+    /** Zero-based result offset; defaults to 0. */
+    cursor?: number;
+}
+export interface AgentProviderCatalog {
+    merchant: AgentResourceProvider & {
+        payoutAddress: EvmAddress;
+        createdAt: string;
+    };
+    offers: AgentResource[];
+}
 export interface MerchantSale {
     id: string;
     state: string;
@@ -181,7 +231,7 @@ export declare class MerchantApiError extends Error {
     constructor(status: number, code: string, message: string);
 }
 /**
- * Minimal, dependency-free HTTP client for 402Mob merchant enrollment and management.
+ * Minimal, dependency-free HTTP client for 402Mob agent resource resolution and merchant management.
  * It never signs messages, submits wallet transactions, persists API keys, or retries requests.
  */
 export declare class MerchantClient {
@@ -209,6 +259,16 @@ export declare class MerchantClient {
     rotateWithSignature(input: CredentialRotationSignatureInput): Promise<CredentialRotationResult>;
     rotateWithTransaction(input: CredentialRotationTransactionInput): Promise<CredentialRotationResult>;
     getMerchant(): Promise<MerchantWorkspace>;
+    /** Search publicly discoverable prepared resources. This read-only call needs no API key. */
+    resolveResources(input?: ResolveAgentResourcesInput): Promise<AgentResourcePage>;
+    /** Read one provider's public profile and published resource descriptors by known ID. */
+    getProviderResources(merchantId: string): Promise<AgentProviderCatalog>;
+    /** Resolve an older resource ID to its currently published version. This call is public. */
+    resolveLatestResource(merchantId: string, offerId: string): Promise<ResolvedAgentResource>;
+    setDiscoverable(discoverable: boolean): Promise<{
+        merchantId: string;
+        discoverable: boolean;
+    }>;
     createOffer(input: CreateOfferInput): Promise<MerchantOffer>;
     setOfferActive(offerId: string, active: boolean): Promise<MerchantOffer>;
     listSales(limit?: number): Promise<SaleList>;

package/dist/index.js

@@ -9,7 +9,7 @@ export class MerchantApiError extends Error {
     }
 }
 /**
- * Minimal, dependency-free HTTP client for 402Mob merchant enrollment and management.
+ * Minimal, dependency-free HTTP client for 402Mob agent resource resolution and merchant management.
  * It never signs messages, submits wallet transactions, persists API keys, or retries requests.
  */
 export class MerchantClient {
@@ -97,6 +97,55 @@ export class MerchantClient {
     getMerchant() {
         return this.request("GET", "/v1/agent/merchant", undefined, true);
     }
+    /** Search publicly discoverable prepared resources. This read-only call needs no API key. */
+    async resolveResources(input = {}) {
+        const query = input.query ?? "";
+        const limit = input.limit ?? 20;
+        const cursor = input.cursor ?? 0;
+        if (typeof query !== "string" || query.trim().length > 80) {
+            throw new TypeError("query must be a string no longer than 80 characters.");
+        }
+        if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+            throw new TypeError("limit must be an integer from 1 through 50.");
+        }
+        if (!Number.isSafeInteger(cursor) || cursor < 0 || cursor > 100_000_000) {
+            throw new TypeError("cursor must be an integer from 0 through 100000000.");
+        }
+        const params = new URLSearchParams({ q: query.trim(), limit: String(limit), cursor: String(cursor) });
+        const payload = await this.request("GET", `/v1/merchant-directory?${params}`);
+        if (!isRecord(payload) || !Array.isArray(payload.items) ||
+            !(payload.nextCursor === null || (Number.isSafeInteger(payload.nextCursor) && payload.nextCursor >= 0)) ||
+            !payload.items.every(isResolvedAgentResource)) {
+            throw invalidPublicResponse();
+        }
+        return payload;
+    }
+    /** Read one provider's public profile and published resource descriptors by known ID. */
+    async getProviderResources(merchantId) {
+        if (!nonempty(merchantId))
+            throw new TypeError("merchantId must be a nonempty string.");
+        const payload = await this.request("GET", `/v1/merchants/${encodeURIComponent(merchantId)}`);
+        if (!isRecord(payload) || !isProviderProfile(payload.merchant) || !Array.isArray(payload.offers) ||
+            !payload.offers.every(isAgentResource)) {
+            throw invalidPublicResponse();
+        }
+        return payload;
+    }
+    /** Resolve an older resource ID to its currently published version. This call is public. */
+    async resolveLatestResource(merchantId, offerId) {
+        if (!nonempty(merchantId) || !nonempty(offerId)) {
+            throw new TypeError("merchantId and offerId must be nonempty strings.");
+        }
+        const path = `/v1/merchants/${encodeURIComponent(merchantId)}/offers/${encodeURIComponent(offerId)}/latest`;
+        const payload = await this.request("GET", path);
+        if (!isRecord(payload) || !isPublicProvider(payload.merchant) || !isAgentResource(payload.offer)) {
+            throw invalidPublicResponse();
+        }
+        return payload;
+    }
+    setDiscoverable(discoverable) {
+        return this.request("PUT", "/v1/agent/merchant/discovery", { discoverable }, true);
+    }
     createOffer(input) {
         return this.request("POST", "/v1/agent/merchant/offers", input, true);
     }
@@ -164,3 +213,32 @@ 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); }
+function isAgentResource(value) {
+    if (!isRecord(value))
+        return false;
+    const amountAtomic = value.amountAtomic;
+    const amountUSDC = value.amountUSDC;
+    return nonempty(value.id) && nonempty(value.seriesId) && nonempty(value.version) &&
+        nonempty(value.title) && typeof value.description === "string" &&
+        typeof amountAtomic === "string" && /^[1-9][0-9]*$/.test(amountAtomic) &&
+        typeof amountUSDC === "string" && /^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$/.test(amountUSDC) &&
+        (value.contentType === "application/json" || value.contentType === "text/plain; charset=utf-8") &&
+        nonempty(value.latest) && nonempty(value.checkout) && nonempty(value.directTransferChallenge) &&
+        (value.supersedesOfferId === undefined || value.supersedesOfferId === null || nonempty(value.supersedesOfferId));
+}
+function isResolvedAgentResource(value) {
+    if (!isRecord(value) || !isRecord(value.merchant))
+        return false;
+    return nonempty(value.merchant.id) && nonempty(value.merchant.name) && nonempty(value.merchant.profile) &&
+        isAgentResource(value.offer);
+}
+function isProviderProfile(value) {
+    return isRecord(value) && nonempty(value.id) && nonempty(value.name) && address(value.payoutAddress) &&
+        nonempty(value.createdAt) && Number.isFinite(Date.parse(value.createdAt));
+}
+function isPublicProvider(value) {
+    return isRecord(value) && nonempty(value.id) && nonempty(value.name) && address(value.payoutAddress);
+}
+function invalidPublicResponse() {
+    return new MerchantApiError(200, "invalid_response", "402Mob returned an incomplete public resource response.");
+}

package/examples/enroll-and-publish.ts

@@ -3,7 +3,7 @@ import {
   type EvmAddress,
   type EvmSignature,
   type MerchantOffer,
-} from "../src/index.js";
+} from "../dist/index.js";
 
 export interface MessageSigningWallet {
   address: EvmAddress;
@@ -21,6 +21,7 @@ export interface SecretStore {
 export async function enrollAndPublish(input: {
   wallet: MessageSigningWallet;
   secretStore: SecretStore;
+  discoverable?: boolean;
 }): Promise<{ offer: MerchantOffer; merchantClient: MerchantClient }> {
   const publicClient = new MerchantClient();
   const enrollment = await publicClient.enrollWithSignature({
@@ -38,6 +39,7 @@ export async function enrollAndPublish(input: {
     contentType: "application/json",
     result: { summary: "Prepared by the seller agent" },
   });
+  if (input.discoverable) await merchantClient.setDiscoverable(true);
 
   return { offer, merchantClient };
 }

package/examples/resolve-resources.ts

@@ -0,0 +1,19 @@
+import { MerchantClient, type ResolveAgentResourcesInput } from "../dist/index.js";
+
+/** Public, read-only discovery for a buyer agent; checkout remains a separate step. */
+export async function resolveAgentResources(input: ResolveAgentResourcesInput = {}) {
+  const buyer = new MerchantClient();
+  const page = await buyer.resolveResources(input);
+
+  return page.items.map(({ merchant, offer }) => ({
+    providerId: merchant.id,
+    providerName: merchant.name,
+    offerId: offer.id,
+    title: offer.title,
+    description: offer.description,
+    amountUSDC: offer.amountUSDC,
+    contentType: offer.contentType,
+    checkout: offer.checkout,
+    latest: offer.latest,
+  }));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "402mob-merchant-sdk",
-  "version": "0.1.2",
-  "description": "Server-side TypeScript client for enrolling and operating 402Mob merchants.",
+  "version": "0.2.0",
+  "description": "TypeScript client for resolving agent resources and enrolling and operating 402Mob merchants.",
   "license": "MIT",
   "repository": {
     "type": "git",