402mob-merchant-sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 402Mob contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# 402Mob Merchant SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An open-source, dependency-free TypeScript client for enrolling and 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.
+
+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?
+
+The SDK is optional. An agent already connected to `https://evidence.contact/mcp` can call `create_merchant_enrollment_challenge`, sign the exact returned message with its wallet tool, then submit it with `complete_merchant_enrollment_signature`. If its wallet cannot sign messages, use the returned zero-USDC action and complete it with `complete_merchant_enrollment_transaction`; this fallback requires Base ETH gas. The MCP caller and wallet signer are separate runtime tools. Either method returns the merchant API key once, so store it in the agent's secret manager. Use the [copy-ready enrollment prompt](https://evidence.contact/merchant-api.md#agent-enrollment-prompt). Choose this SDK when your Node.js app needs to call the merchant HTTP API directly.
+
+## Install
+
+Install from npm:
+
+```sh
+npm install 402mob-merchant-sdk
+```
+
+The current release is **0.1.1**. 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.
+
+## EIP-191 enrollment
+
+Provide a callback backed by the merchant wallet. The SDK requests the challenge and passes the exact returned message to the callback.
+
+```ts
+import { MerchantClient } from "402mob-merchant-sdk";
+
+const publicClient = new MerchantClient();
+const enrollment = await publicClient.enrollWithSignature({
+  wallet: "0xYourBaseWallet",
+  name: "Research Agent",
+  signMessage: (message) => wallet.signMessage({ message }),
+});
+
+// Persist this one-time value with your own secret manager.
+await secretManager.set("402mob/merchant-api-key", enrollment.apiKey);
+
+const merchant = publicClient.withApiKey(enrollment.apiKey);
+const offer = await merchant.createOffer({
+  title: "Base payment summary",
+  description: "A prepared report for the buyer.",
+  priceUSDC: "0.02",
+  contentType: "application/json",
+  result: { summary: "Prepared by the seller agent" },
+});
+
+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.
+
+## 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.
+
+```ts
+const enrollment = await publicClient.enrollWithTransaction({
+  wallet: "0xYourBaseWallet",
+  name: "Research Agent",
+  submitProof: async (challenge) => {
+    const tx = await walletTool.submitUsdcApproval({
+      network: challenge.transactionProof.network,
+      token: challenge.transactionProof.asset,
+      spender: challenge.transactionProof.approve.spender,
+      amount: 0n,
+    });
+    await walletTool.waitForConfirmations(tx.hash, Number(challenge.transactionProof.requiredConfirmations));
+    return { method: "approve_zero", transactionHash: tx.hash };
+  },
+});
+```
+
+This action moves no USDC and grants no allowance, but it costs Base ETH for gas. The `transfer_zero` alternative must be sent directly by the merchant wallet. Both methods must be mined and submitted before the five-minute challenge expires. The callback is responsible for showing the transaction to the wallet owner and waiting for confirmation; the SDK only submits the returned hash to 402Mob.
+
+## API
+
+### Public methods
+
+- `createEnrollmentChallenge({ wallet, name })`
+- `completeEnrollmentWithSignature({ wallet, name, challengeId, signature })`
+- `completeEnrollmentWithTransaction({ wallet, name, challengeId, method, transactionHash })`
+- `enrollWithSignature({ wallet, name, signMessage })`
+- `enrollWithTransaction({ wallet, name, submitProof })`
+- `createCredentialRotationChallenge(wallet)`
+- `rotateCredentialWithSignature(wallet, challengeId, signature)`
+- `rotateCredentialWithTransaction({ wallet, challengeId, method, transactionHash })`
+- `rotateWithSignature({ wallet, signMessage })`
+- `rotateWithTransaction({ wallet, submitProof })`
+- `withApiKey(apiKey)`
+- `getMerchant()`
+- `createOffer(input)`
+- `setOfferActive(offerId, active)`
+- `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.
+
+## Safety and behavior
+
+- The base URL defaults to `https://evidence.contact`; use `baseUrl` to target a compatible service. Remote URLs must use HTTPS. A base URL path prefix is preserved, so a reverse proxy mounted at `https://example.com/402mob` receives requests below `/402mob/v1/...`. Credentials, query strings, and fragments are rejected. Browser frontends cannot call `evidence.contact` directly because its API does not send CORS headers.
+- Wallet signing and transaction submission are injected callbacks. The SDK has no private-key parameter.
+- Enrollment and rotation return a long-lived API key once. Save it in your own secret manager. The SDK holds it only in memory when passed to `withApiKey`.
+- The SDK does not persist credentials or automatically retry requests. If an enrollment completes but its response is lost, the one-time key cannot be recovered; use the wallet-bound credential-rotation flow to issue a replacement. Do not enroll the same wallet again. If a rotation response is lost, use the wallet-bound rotation flow again to issue another replacement.
+- Merchant management creates prepared artifacts. It does not register dynamic callbacks or execute seller code.
+- `MerchantApiError` exposes the HTTP `status` and API `code`; errors never include request headers or wallet secrets.
+
+## Development
+
+```sh
+npm install
+npm run build
+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.
+
+MIT licensed. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+export type EvmAddress = `0x${string}`;
+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 interface EnrollmentChallenge {
+    challengeId: string;
+    message: string;
+    expiresAt: string;
+    signature: string;
+    transactionProof: {
+        network: "eip155:8453";
+        asset: EvmAddress;
+        proofAddress: EvmAddress;
+        approve: {
+            spender: EvmAddress;
+            amountAtomic: "0";
+        };
+        send: {
+            recipient: EvmAddress;
+            amountAtomic: "0";
+        };
+        submit: string;
+        requiredConfirmations: string;
+        note: string;
+    };
+}
+export interface CredentialChallenge extends EnrollmentChallenge {
+}
+export interface MerchantProfile {
+    id: string;
+    agentId: string;
+    name: string;
+    payoutAddress: EvmAddress;
+    createdAt: string;
+}
+export interface MerchantAgent {
+    id: string;
+    name: string;
+    scopes: string[];
+}
+export interface EnrollmentResult {
+    merchant: MerchantProfile;
+    agent: MerchantAgent;
+    /** Returned once. Store it in the integrating application's secret manager. */
+    apiKey: string;
+    warning: string;
+    proof?: {
+        method: ProofMethod;
+        network: "eip155:8453";
+        transactionHash: TransactionHash;
+        blockNumber: string;
+        confirmations: string;
+    };
+}
+export interface CredentialRotationResult {
+    merchant: MerchantProfile;
+    /** Replacement returned once. Store it in the integrating application's secret manager. */
+    apiKey: string;
+    warning: string;
+    proof?: {
+        method: ProofMethod;
+        network: "eip155:8453";
+        transactionHash: TransactionHash;
+        blockNumber: string;
+        confirmations: string;
+    };
+}
+interface MerchantOfferBase {
+    id: string;
+    merchantId: string;
+    seriesId: string;
+    version: string;
+    supersedesOfferId: string | null;
+    title: string;
+    description: string;
+    amountUSDC: string;
+    contentType: ArtifactContentType;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+    latest: string;
+    checkout: string;
+    directTransferChallenge: string;
+}
+export type MerchantOffer = MerchantOfferBase & ({
+    amount: string;
+    amountAtomic?: never;
+} | {
+    amount?: never;
+    amountAtomic: string;
+});
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+interface OfferInputBase {
+    title: string;
+    description: string;
+    priceUSDC: string;
+    version?: string;
+    supersedesOfferId?: string;
+}
+export type CreateOfferInput = OfferInputBase & ({
+    contentType: "application/json";
+    result: JsonValue;
+} | {
+    contentType: "text/plain; charset=utf-8";
+    result: string;
+});
+export interface MerchantWorkspace {
+    merchant: MerchantProfile;
+    offers: MerchantOffer[];
+}
+export interface MerchantSale {
+    id: string;
+    state: string;
+    route: string;
+    amountAtomic: string;
+    asset: EvmAddress;
+    network: "eip155:8453";
+    createdAt: string;
+    expiresAt: string;
+    transaction: TransactionHash | null;
+    resultAvailable: boolean;
+    error: string | null;
+}
+export interface SaleList {
+    sales: MerchantSale[];
+}
+export interface SaleDetails {
+    sale: MerchantSale;
+    responseHash: string | null;
+    deliveryReceipts: unknown[];
+}
+export interface MerchantClientOptions {
+    /** Defaults to https://evidence.contact. */
+    baseUrl?: string;
+    /** Merchant bearer key. The SDK keeps it in memory only. */
+    apiKey?: string;
+    /** Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface CreateEnrollmentInput {
+    wallet: EvmAddress;
+    name: string;
+}
+export interface CompleteSignatureInput extends CreateEnrollmentInput {
+    challengeId: string;
+    signature: EvmSignature;
+}
+export interface CompleteTransactionInput extends CreateEnrollmentInput {
+    challengeId: string;
+    method: ProofMethod;
+    transactionHash: TransactionHash;
+}
+export interface EnrollWithSignatureInput extends CreateEnrollmentInput {
+    /** Sign the exact message returned by the challenge endpoint using EIP-191. */
+    signMessage(message: string): Promise<EvmSignature>;
+}
+export interface EnrollWithTransactionInput extends CreateEnrollmentInput {
+    /** Submit the exact zero-USDC action from the challenge, then wait for its advertised confirmations. */
+    submitProof(challenge: EnrollmentChallenge): Promise<{
+        method: ProofMethod;
+        transactionHash: TransactionHash;
+    }>;
+}
+export interface CredentialRotationSignatureInput {
+    wallet: EvmAddress;
+    signMessage(message: string): Promise<EvmSignature>;
+}
+export interface CredentialRotationTransactionInput {
+    wallet: EvmAddress;
+    submitProof(challenge: CredentialChallenge): Promise<{
+        method: ProofMethod;
+        transactionHash: TransactionHash;
+    }>;
+}
+export declare class MerchantApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/**
+ * Minimal, dependency-free HTTP client for 402Mob merchant enrollment and management.
+ * It never signs messages, submits wallet transactions, persists API keys, or retries requests.
+ */
+export declare class MerchantClient {
+    #private;
+    private readonly baseUrl;
+    private readonly fetcher;
+    constructor(options?: MerchantClientOptions);
+    /** Return a new client with the supplied key; no key is written to disk or logged. */
+    withApiKey(apiKey: string): MerchantClient;
+    createEnrollmentChallenge(input: CreateEnrollmentInput): Promise<EnrollmentChallenge>;
+    completeEnrollmentWithSignature(input: CompleteSignatureInput): Promise<EnrollmentResult>;
+    completeEnrollmentWithTransaction(input: CompleteTransactionInput): Promise<EnrollmentResult>;
+    /** Request a challenge, ask the caller's wallet adapter to sign its exact message, then enroll. */
+    enrollWithSignature(input: EnrollWithSignatureInput): Promise<EnrollmentResult>;
+    /** Request a challenge, delegate its exact zero-value wallet action, then submit the confirmed hash. */
+    enrollWithTransaction(input: EnrollWithTransactionInput): Promise<EnrollmentResult>;
+    createCredentialRotationChallenge(wallet: EvmAddress): Promise<CredentialChallenge>;
+    rotateCredentialWithSignature(wallet: EvmAddress, challengeId: string, signature: EvmSignature): Promise<CredentialRotationResult>;
+    rotateCredentialWithTransaction(input: {
+        wallet: EvmAddress;
+        challengeId: string;
+        method: ProofMethod;
+        transactionHash: TransactionHash;
+    }): Promise<CredentialRotationResult>;
+    rotateWithSignature(input: CredentialRotationSignatureInput): Promise<CredentialRotationResult>;
+    rotateWithTransaction(input: CredentialRotationTransactionInput): Promise<CredentialRotationResult>;
+    getMerchant(): Promise<MerchantWorkspace>;
+    createOffer(input: CreateOfferInput): Promise<MerchantOffer>;
+    setOfferActive(offerId: string, active: boolean): Promise<MerchantOffer>;
+    listSales(limit?: number): Promise<SaleList>;
+    getSale(operationId: string): Promise<SaleDetails>;
+    private request;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,143 @@
+export class MerchantApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "MerchantApiError";
+    }
+}
+/**
+ * Minimal, dependency-free HTTP client for 402Mob merchant enrollment and management.
+ * It never signs messages, submits wallet transactions, persists API keys, or retries requests.
+ */
+export class MerchantClient {
+    baseUrl;
+    #apiKey;
+    fetcher;
+    constructor(options = {}) {
+        const baseUrl = options.baseUrl ?? "https://evidence.contact";
+        const parsed = new URL(baseUrl);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+            throw new TypeError("baseUrl must use HTTP or HTTPS.");
+        }
+        if (parsed.protocol === "http:" && !["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname)) {
+            throw new TypeError("HTTP is allowed only for loopback development URLs; use HTTPS for remote services.");
+        }
+        if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+            throw new TypeError("baseUrl must not contain credentials, a query, or a fragment.");
+        }
+        const pathPrefix = parsed.pathname.replace(/\/+$/, "");
+        this.baseUrl = `${parsed.origin}${pathPrefix}`;
+        this.#apiKey = options.apiKey;
+        this.fetcher = options.fetch ?? globalThis.fetch;
+        if (typeof this.fetcher !== "function") {
+            throw new TypeError("A Fetch API implementation is required.");
+        }
+    }
+    /** Return a new client with the supplied key; no key is written to disk or logged. */
+    withApiKey(apiKey) {
+        return new MerchantClient({ baseUrl: this.baseUrl, apiKey, fetch: this.fetcher });
+    }
+    createEnrollmentChallenge(input) {
+        return this.request("POST", "/v1/merchants/enrollment-challenges", input);
+    }
+    completeEnrollmentWithSignature(input) {
+        return this.request("POST", "/v1/merchants/enrollments", input);
+    }
+    completeEnrollmentWithTransaction(input) {
+        return this.request("POST", "/v1/merchants/enrollments/transaction", input);
+    }
+    /** 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);
+        return this.completeEnrollmentWithSignature({
+            wallet: input.wallet,
+            name: input.name,
+            challengeId: challenge.challengeId,
+            signature,
+        });
+    }
+    /** Request a challenge, delegate its exact zero-value wallet action, then submit the confirmed hash. */
+    async enrollWithTransaction(input) {
+        const challenge = await this.createEnrollmentChallenge({ wallet: input.wallet, name: input.name });
+        const proof = await input.submitProof(challenge);
+        return this.completeEnrollmentWithTransaction({
+            wallet: input.wallet,
+            name: input.name,
+            challengeId: challenge.challengeId,
+            ...proof,
+        });
+    }
+    createCredentialRotationChallenge(wallet) {
+        return this.request("POST", "/v1/merchants/credential-challenges", { wallet });
+    }
+    rotateCredentialWithSignature(wallet, challengeId, signature) {
+        return this.request("POST", "/v1/merchants/credentials/rotate", { wallet, challengeId, 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);
+        return this.rotateCredentialWithSignature(input.wallet, challenge.challengeId, signature);
+    }
+    async rotateWithTransaction(input) {
+        const challenge = await this.createCredentialRotationChallenge(input.wallet);
+        const proof = await input.submitProof(challenge);
+        return this.rotateCredentialWithTransaction({
+            wallet: input.wallet,
+            challengeId: challenge.challengeId,
+            ...proof,
+        });
+    }
+    getMerchant() {
+        return this.request("GET", "/v1/agent/merchant", undefined, true);
+    }
+    createOffer(input) {
+        return this.request("POST", "/v1/agent/merchant/offers", input, true);
+    }
+    setOfferActive(offerId, active) {
+        return this.request("PUT", `/v1/agent/merchant/offers/${encodeURIComponent(offerId)}/status`, { active }, true);
+    }
+    listSales(limit = 50) {
+        const query = new URLSearchParams({ limit: String(limit) });
+        return this.request("GET", `/v1/agent/merchant/sales?${query}`, undefined, true);
+    }
+    getSale(operationId) {
+        return this.request("GET", `/v1/agent/merchant/sales/${encodeURIComponent(operationId)}`, undefined, 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).");
+        }
+        const headers = { Accept: "application/json" };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (authenticated && this.#apiKey)
+            headers.Authorization = `Bearer ${this.#apiKey}`;
+        const response = await this.fetcher(new URL(`${this.baseUrl}${path}`), {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            payload = undefined;
+        }
+        if (!response.ok) {
+            const error = isRecord(payload) ? payload : {};
+            throw new MerchantApiError(response.status, typeof error.error === "string" ? error.error : "http_error", typeof error.message === "string" ? error.message : `402Mob returned HTTP ${response.status}.`);
+        }
+        return payload;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/examples/enroll-and-publish.ts

@@ -0,0 +1,43 @@
+import {
+  MerchantClient,
+  type EvmAddress,
+  type EvmSignature,
+  type MerchantOffer,
+} from "../src/index.js";
+
+export interface MessageSigningWallet {
+  address: EvmAddress;
+  signMessage(message: string): Promise<EvmSignature>;
+}
+
+export interface SecretStore {
+  set(name: string, secret: string): Promise<void>;
+}
+
+/**
+ * Example integration for an agent runtime that provides a wallet signer and secret store.
+ * The wallet and secret-store adapters stay under the integrating project's control.
+ */
+export async function enrollAndPublish(input: {
+  wallet: MessageSigningWallet;
+  secretStore: SecretStore;
+}): Promise<{ offer: MerchantOffer; merchantClient: MerchantClient }> {
+  const publicClient = new MerchantClient();
+  const enrollment = await publicClient.enrollWithSignature({
+    wallet: input.wallet.address,
+    name: "Research Agent",
+    signMessage: (message) => input.wallet.signMessage(message),
+  });
+
+  await input.secretStore.set("402mob/merchant-api-key", enrollment.apiKey);
+  const merchantClient = publicClient.withApiKey(enrollment.apiKey);
+  const offer = await merchantClient.createOffer({
+    title: "Base payment summary",
+    description: "A prepared report for the buyer.",
+    priceUSDC: "0.02",
+    contentType: "application/json",
+    result: { summary: "Prepared by the seller agent" },
+  });
+
+  return { offer, merchantClient };
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "402mob-merchant-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Server-side TypeScript client for enrolling and operating 402Mob merchants.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gggggggg424242/402mob-merchant-sdk.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}