402mob-merchant-sdk 0.1.0 → 0.1.2

package/README.md

@@ -6,6 +6,18 @@ It wraps the existing HTTP merchant API. It does not custody keys, sign for wall
 
 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.
+
+
+## Enrollment readiness
+
+The runtime must provide a caller that can read the challenge response, one wallet proof method, and secure storage for the returned merchant API key. The SDK supplies HTTP calls; your callbacks supply signing or transaction submission. It does not install MCP tools or unlock a failed wallet tool. Check these capabilities before starting the five-minute challenge.
+
+If a message signer is locked, stop retries. `enrollWithTransaction` can use a separate wallet transaction adapter that supports zero-USDC approval/transfer, with authorized Base ETH gas spending. A generic send/swap tool may reject zero amounts; verify support first. The SDK never submits this transaction itself. For MCP 406 errors, missing response bodies, expired challenges, and lost keys, see the [enrollment troubleshooting guide](https://evidence.contact/merchant-api.md#enrollment-troubleshooting).
+
+
 ## Install
 
 Install from npm:
@@ -14,7 +26,7 @@ Install from npm:
 npm install 402mob-merchant-sdk
 ```
 
-The source is available at [github.com/gggggggg424242/402mob-merchant-sdk](https://github.com/gggggggg424242/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).
 
 Requires Node.js 18 or newer. The SDK uses the built-in Fetch API and has no runtime dependencies.
 
@@ -117,3 +129,7 @@ The SDK tests use mocked HTTP responses and do not contact `evidence.contact` or
 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).
+
+## 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.

package/dist/index.js

@@ -129,15 +129,38 @@ export class MerchantClient {
             payload = await response.json();
         }
         catch {
+            if (response.ok)
+                throw new MerchantApiError(response.status, "invalid_response", "402Mob returned an unreadable response. The request may have completed; do not assume it failed.");
             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}.`);
         }
+        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 === "/v1/merchants/enrollment-challenges" || path === "/v1/merchants/credential-challenges") {
+            const proof = payload.transactionProof;
+            if (!nonempty(payload.challengeId) || !nonempty(payload.message) || !nonempty(payload.expiresAt) ||
+                !Number.isFinite(Date.parse(payload.expiresAt)) || !isRecord(proof) ||
+                proof.network !== "eip155:8453" || !address(proof.asset) || !address(proof.proofAddress) ||
+                !isRecord(proof.approve) || !isRecord(proof.send) ||
+                typeof proof.approve.spender !== "string" || proof.approve.spender.toLowerCase() !== proof.proofAddress.toLowerCase() ||
+                typeof proof.send.recipient !== "string" || proof.send.recipient.toLowerCase() !== proof.proofAddress.toLowerCase() ||
+                proof.approve.amountAtomic !== "0" || proof.send.amountAtomic !== "0" ||
+                typeof proof.requiredConfirmations !== "string" || !/^[1-9][0-9]*$/.test(proof.requiredConfirmations))
+                throw invalidResponse();
+        }
+        if (["/v1/merchants/enrollments", "/v1/merchants/enrollments/transaction", "/v1/merchants/credentials/rotate", "/v1/merchants/credentials/rotate-transaction"].includes(path)) {
+            if (!isRecord(payload.merchant) || !nonempty(payload.merchant.id) || !nonempty(payload.apiKey))
+                throw invalidResponse();
+        }
         return payload;
     }
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(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); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "402mob-merchant-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Server-side TypeScript client for enrolling and operating 402Mob merchants.",
   "license": "MIT",
   "repository": {