@paynodelabs/sdk-js 2.2.3 → 2.3.0

package/README.md

@@ -33,9 +33,36 @@ async function main() {
 main();
 ```
 
+### Market Merchant (Seller)
+
+Starting from **v2.3.0**, PayNode SDK provides a unified merchant gateway for seamless [PayNode Market](https://mk.paynode.dev) integration.
+
+```typescript
+import { PayNodeMerchant } from "@paynodelabs/sdk-js";
+import express from "express";
+
+const app = express();
+const merchant = new PayNodeMerchant({
+  sharedSecret: "YOUR_MARKET_SECRET" // From Market Hub
+});
+
+
+// 1. Unified Middleware (Strict Market Auth + Discovery + Body Unwrap)
+app.post("/my-api", merchant.middleware({
+    manifest: { slug: "my-tool", price_per_call: "0.1" },
+    strict: true // Enforce Market Proxy (Ensures you & Market get fees)
+  }), (req, res) => {
+    // req.body is automatically unwrapped from market data structure.
+    // Payment details available in req.paynode.txHash
+    res.json({ data: "premium_content" });
+  }
+);
+```
+
 ### Key Features (v2.2.1)
+
 - **Zero-Wait Checkout**: API response speed drops from 5 seconds to **under 50ms** by using local signatures instead of waiting for on-chain inclusion.
-- **Double-Spend Protection**: 
+- **Double-Spend Protection**:
   - **L1 (Memory)**: High-speed local replay protection via `IdempotencyStore`.
   - **L2 (RPC)**: Real-time on-chain `authorizationState` verification.
 - **Empty-Wallet Proof**: Integrated `balanceOf` probes to block malicious agents using empty wallets to generate valid signatures.
@@ -44,6 +71,7 @@ main();
 - **Dual Flow**: Automatic switch between V1 (on-chain receipts) and V2 (off-chain signatures).
 
 ## 🗺️ Roadmap
+
 - **TRON Support**: USDT (TRC-20) payment integration.
 - **Solana Support**: SPL USDC/USDT payment integration.
 - **Cross-chain**: Universal settlement via bridges.
@@ -108,10 +136,13 @@ To publish a new version of the SDK:
 
 PayNode uses two distinct versioning schemes:
 
-| Version Type | Description | Current Value |
-| :--- | :--- | :--- |
-| **Protocol Version** | On-chain contracts & core x402 data schema. | `1.4.0` |
-| **SDK/Product Version** | Software package version (npm/SemVer). | `2.2.2` |
+| Version Type            | Description                                 | Current Value |
+| :---------------------- | :------------------------------------------ | :------------ |
+| **Protocol Version**    | On-chain contracts & core x402 data schema. | `1.4.0`       |
+| **SDK/Product Version** | Software package version (npm/SemVer).      | `2.2.3`       |
+
+> [!IMPORTANT]
+> **Production Hardening (v2.2.3+)**: This version includes critical fixes for Base Mainnet transaction stability (Inconsistent Quorum/Code 9) by enforcing `staticNetwork` and optimized provider settings. It is the minimum recommended version for mainnet deployment.
 
 > [!NOTE]
 > Protocol Version changes imply breaking changes in verification or contract interfaces. SDK Version changes may include features, fixes, or performance improvements without altering protocol logic.

package/dist/index.d.ts

@@ -8,4 +8,6 @@ export * from './constants';
 export * from './utils/payload';
 export * from './types/x402';
 export { ethers } from 'ethers';
+export * from './merchant';
+export * from './merchant/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -26,3 +26,5 @@ __exportStar(require("./utils/payload"), exports);
 __exportStar(require("./types/x402"), exports);
 var ethers_1 = require("ethers");
 Object.defineProperty(exports, "ethers", { enumerable: true, get: function () { return ethers_1.ethers; } });
+__exportStar(require("./merchant"), exports);
+__exportStar(require("./merchant/types"), exports);

package/dist/merchant/index.d.ts

@@ -0,0 +1,37 @@
+import { MerchantConfig, MerchantMiddlewareOptions, ApiManifest } from './types';
+import { PayNodeMiddlewareOptions } from '../middleware/x402';
+/**
+ * PayNodeMerchant: The high-level SDK class for Merchant Integration.
+ */
+export declare class PayNodeMerchant {
+    private config;
+    constructor(config: MerchantConfig);
+    /**
+     * Registers or syncs the API manifest with the PayNode Market.
+     * This ensures the market shows the correct price and input schema.
+     */
+    sync(manifest: ApiManifest): Promise<boolean>;
+    /**
+     * Returns a unified middleware that handles:
+     * 1. Market Proxy (Strict Signature Check + Body Unwrap)
+     * 2. Auto-Discovery (Market Sync Probe)
+     * 3. (Optional) Direct X402 payment
+     */
+    middleware(options?: MerchantMiddlewareOptions & Partial<PayNodeMiddlewareOptions>): (req: import("express").Request | any, res: import("express").Response | any, next: import("express").NextFunction) => Promise<any>;
+    /**
+     * Manual verification for Next.js or other non-Express environments.
+     * Extracts headers and verifies signature. Returns the unwrapped body and context.
+     */
+    verify(req: any): Promise<{
+        isValid: boolean;
+        error: string;
+        body?: undefined;
+        paynodeContext?: undefined;
+    } | {
+        isValid: boolean;
+        body: any;
+        paynodeContext: any;
+        error?: undefined;
+    }>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/merchant/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/merchant/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,yBAAyB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAG9D;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,cAAc;IAOlC;;;OAGG;IACG,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BnD;;;;;OAKG;IACH,UAAU,CAAC,OAAO,GAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAM;IAOtF;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,GAAG;;;;;;;;;;;CAiDtB"}

package/dist/merchant/index.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PayNodeMerchant = void 0;
+const middleware_1 = require("./middleware");
+const signature_1 = require("../utils/signature");
+/**
+ * PayNodeMerchant: The high-level SDK class for Merchant Integration.
+ */
+class PayNodeMerchant {
+    config;
+    constructor(config) {
+        this.config = {
+            marketUrl: 'https://mk.paynode.dev',
+            ...config
+        };
+    }
+    /**
+     * Registers or syncs the API manifest with the PayNode Market.
+     * This ensures the market shows the correct price and input schema.
+     */
+    async sync(manifest) {
+        console.log(`[PayNode-SDK] Syncing API manifest for ${manifest.slug} to ${this.config.marketUrl}`);
+        try {
+            const response = await fetch(`${this.config.marketUrl}/api/v1/merchant/apis`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    ...manifest,
+                    gateway_url: manifest.slug
+                })
+            });
+            const result = await response.json();
+            if (response.ok && result.success) {
+                console.log(`[PayNode-SDK] Successfully synced ${manifest.slug}. Status: ${result.api_id}`);
+                return true;
+            }
+            else {
+                console.warn(`[PayNode-SDK] Sync failed for ${manifest.slug}: ${result.error || response.statusText}`);
+                return false;
+            }
+        }
+        catch (err) {
+            console.error(`[PayNode-SDK] Network error during sync for ${manifest.slug}:`, err.message);
+            return false;
+        }
+    }
+    /**
+     * Returns a unified middleware that handles:
+     * 1. Market Proxy (Strict Signature Check + Body Unwrap)
+     * 2. Auto-Discovery (Market Sync Probe)
+     * 3. (Optional) Direct X402 payment
+     */
+    middleware(options = {}) {
+        return (0, middleware_1.createMerchantMiddleware)(this.config, {
+            price: options.manifest?.price_per_call || '0.01',
+            ...options
+        });
+    }
+    /**
+     * Manual verification for Next.js or other non-Express environments.
+     * Extracts headers and verifies signature. Returns the unwrapped body and context.
+     */
+    async verify(req) {
+        const getHeader = (name) => {
+            if (typeof req.getHeader === 'function')
+                return req.getHeader(name);
+            if (typeof req.get === 'function')
+                return req.get(name);
+            if (req.headers?.get && typeof req.headers.get === 'function')
+                return req.headers.get(name);
+            if (req.headers)
+                return req.headers[name.toLowerCase()] || req.headers[name];
+            return null;
+        };
+        const signature = getHeader('X-PayNode-Signature');
+        const timestamp = getHeader('X-PayNode-Timestamp');
+        const requestId = getHeader('X-PayNode-Request-Id') || getHeader('X-402-Order-Id');
+        const isValid = (0, signature_1.verifyMarketSignature)({
+            signature,
+            orderId: requestId,
+            timestamp,
+            sharedSecret: this.config.sharedSecret,
+        });
+        if (!isValid) {
+            return { isValid: false, error: 'Invalid PayNode Market Signature' };
+        }
+        // Handle Body Unwrap if it's a JSON body
+        let body = {};
+        try {
+            if (typeof req.json === 'function') {
+                body = await req.json();
+            }
+            else {
+                body = req.body;
+            }
+        }
+        catch (e) { }
+        let paynodeContext = { orderId: requestId };
+        if (body && body.payload && typeof body.payload === 'object') {
+            paynodeContext = {
+                ...paynodeContext,
+                txHash: getHeader('X-PayNode-Transaction-Hash') || body.tx_hash,
+                amount: getHeader('X-PayNode-Amount') || body.amount,
+                network: getHeader('X-PayNode-Network') || body.network,
+                chainId: getHeader('X-PayNode-Chain-Id') || body.chain_id?.toString(),
+            };
+            body = body.payload;
+        }
+        return { isValid: true, body, paynodeContext };
+    }
+}
+exports.PayNodeMerchant = PayNodeMerchant;

package/dist/merchant/middleware.d.ts

@@ -0,0 +1,12 @@
+import { Request, Response, NextFunction } from 'express';
+import { MerchantConfig, MerchantMiddlewareOptions } from './types';
+import { PayNodeMiddlewareOptions } from '../middleware/x402';
+/**
+ * Unified PayNode Merchant Middleware
+ * Handles:
+ * 1. Market Proxy (Strict HMAC Signature + Body Unwrapping)
+ * 2. Discovery Probes (Auto-respond with API Manifest)
+ * 3. Direct Agent Access (Optional X402 Fallback)
+ */
+export declare const createMerchantMiddleware: (config: MerchantConfig, options: MerchantMiddlewareOptions & PayNodeMiddlewareOptions) => (req: Request | any, res: Response | any, next: NextFunction) => Promise<any>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/merchant/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/merchant/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAEpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,QAAQ,cAAc,EAAE,SAAS,yBAAyB,GAAG,wBAAwB,MAG9G,KAAK,OAAO,GAAG,GAAG,EAAE,KAAK,QAAQ,GAAG,GAAG,EAAE,MAAM,YAAY,iBAiE1E,CAAC"}

package/dist/merchant/middleware.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMerchantMiddleware = void 0;
+const signature_1 = require("../utils/signature");
+/**
+ * Unified PayNode Merchant Middleware
+ * Handles:
+ * 1. Market Proxy (Strict HMAC Signature + Body Unwrapping)
+ * 2. Discovery Probes (Auto-respond with API Manifest)
+ * 3. Direct Agent Access (Optional X402 Fallback)
+ */
+const createMerchantMiddleware = (config, options) => {
+    const { manifest, strict = true } = options;
+    return async (req, res, next) => {
+        // 1. Check for Market Proxy Headers
+        const signature = req.header('X-PayNode-Signature');
+        const timestamp = req.header('X-PayNode-Timestamp');
+        const requestId = req.header('X-PayNode-Request-Id') || req.header('X-402-Order-Id');
+        const isDiscovery = req.header('X-PayNode-Discovery') === 'true';
+        if (signature && requestId && timestamp) {
+            // ✅ Verify Signature from PayNode Market
+            const isValid = (0, signature_1.verifyMarketSignature)({
+                signature,
+                orderId: requestId,
+                timestamp,
+                sharedSecret: config.sharedSecret,
+            });
+            if (!isValid) {
+                console.error(`[PayNode-SDK] Invalid Market Proxy Signature for request ${requestId}`);
+                return res.status(401).json({ error: 'unauthorized', message: 'PayNode Market Signature verification failed.' });
+            }
+            // --- Scene A: Discovery Probe ---
+            if (isDiscovery) {
+                return res.status(200).json({
+                    status: 'DISCOVERED',
+                    version: '2.0.0',
+                    manifest: manifest || {},
+                    last_synced: new Date().toISOString()
+                });
+            }
+            // --- Scene B: Proxy Flow - Body Unwrapping ---
+            // The Market Proxy wraps original body in { payload: { ... } }
+            if (req.body && req.body.payload && typeof req.body.payload === 'object') {
+                const metadata = { ...req.body };
+                delete metadata.payload;
+                // Enrich request context with Proxy details
+                req.paynode = {
+                    orderId: requestId,
+                    txHash: req.header('X-PayNode-Transaction-Hash') || req.body.tx_hash,
+                    amount: req.header('X-PayNode-Amount') || req.body.amount,
+                    network: req.header('X-PayNode-Network') || req.body.network,
+                    chainId: req.header('X-PayNode-Chain-Id') || req.body.chain_id?.toString(),
+                    proxyMetadata: metadata
+                };
+                // Transparently Unwrap Body
+                req.body = req.body.payload;
+            }
+            else {
+                // Direct call via Proxy (unlikely for POST, but possible for some flows)
+                req.paynode = { orderId: requestId };
+            }
+            return next();
+        }
+        // 2. Scene C: Direct Agent Call (Rejected)
+        // PayNodeMerchant component REQUIRES Market Proxy to ensure protocol consistency and fee collection.
+        // Use x402Gate directly for standalone/direct 402 integration.
+        return res.status(403).json({
+            error: 'forbidden',
+            message: 'PayNode Market Auth required. This API must be accessed via PayNode Market Proxy for verification.'
+        });
+    };
+};
+exports.createMerchantMiddleware = createMerchantMiddleware;

package/dist/merchant/types.d.ts

@@ -0,0 +1,27 @@
+export interface MerchantConfig {
+    sharedSecret: string;
+    marketUrl?: string;
+}
+export interface ApiManifest {
+    slug: string;
+    name: string;
+    description: string;
+    price_per_call: string;
+    currency?: string;
+    network?: 'mainnet' | 'testnet';
+    input_schema?: Record<string, any>;
+    sample_response?: Record<string, any>;
+}
+export interface PayNodeRequestContext {
+    orderId: string;
+    txHash?: string;
+    payer?: string;
+    amount?: string;
+    network?: string;
+    chainId?: string;
+}
+export interface MerchantMiddlewareOptions {
+    manifest?: Partial<ApiManifest>;
+    strict?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/merchant/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/merchant/types.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/merchant/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/signature.d.ts

@@ -0,0 +1,11 @@
+export interface SignatureContext {
+    signature: string;
+    orderId: string;
+    timestamp: string;
+    sharedSecret: string;
+}
+/**
+ * Verifies the HMAC-SHA256 signature from PayNode Market Proxy
+ */
+export declare function verifyMarketSignature(context: SignatureContext): boolean;
+//# sourceMappingURL=signature.d.ts.map

package/dist/utils/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/utils/signature.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CA4BxE"}

package/dist/utils/signature.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMarketSignature = verifyMarketSignature;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Verifies the HMAC-SHA256 signature from PayNode Market Proxy
+ */
+function verifyMarketSignature(context) {
+    const { signature, orderId, timestamp, sharedSecret } = context;
+    if (!signature || !orderId || !timestamp || !sharedSecret) {
+        return false;
+    }
+    // Check for timestamp drift (default 5 minutes to prevent replay)
+    const tsDate = new Date(timestamp);
+    const now = new Date();
+    // Accept both ISO string and milliseconds
+    const tsMs = isNaN(tsDate.getTime()) ? parseInt(timestamp) : tsDate.getTime();
+    if (isNaN(tsMs))
+        return false;
+    const drift = Math.abs(now.getTime() - tsMs);
+    if (drift > 5 * 60 * 1000) {
+        console.warn(`[PayNode-SDK] Signature timestamp drift too high: ${drift}ms`);
+        return false;
+    }
+    const expectedSig = crypto_1.default
+        .createHmac('sha256', sharedSecret)
+        .update(`${orderId}${timestamp}`)
+        .digest('hex');
+    return signature === expectedSig;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paynodelabs/sdk-js",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "The official JavaScript/TypeScript SDK for PayNode x402 protocol on Base L2.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",