402mob-merchant-sdk 0.1.3 → 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
 ```
 
-The current published release is **0.1.2**. The working tree prepares **0.1.3** with a typed directory visibility method; publish it from the SDK package directory when ready. 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.
 
@@ -64,6 +64,36 @@ 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.
@@ -91,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 })`
@@ -109,7 +142,7 @@ This action moves no USDC and grants no allowance, but it costs Base ETH for gas
 - `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
 
@@ -130,11 +163,15 @@ 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.1.3 (unpublished)
+## 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.
 

package/dist/index.d.ts

@@ -113,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;
@@ -183,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 {
@@ -211,6 +259,12 @@ 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;

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,52 @@ 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);
     }
@@ -167,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.3",
-  "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",