@4mica/sdk 0.5.0

package/dist/x402.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402Flow = exports.X402SettledPayment = exports.X402SignedPayment = exports.X402PaymentEnvelope = exports.TabResponse = exports.PaymentRequirementsExtra = exports.PaymentRequirements = void 0;
+const models_1 = require("./models");
+const utils_1 = require("./utils");
+const errors_1 = require("./errors");
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+class PaymentRequirements {
+    constructor(scheme, network, maxAmountRequired, payTo, asset, extra, resource, description, mimeType, outputSchema, maxTimeoutSeconds) {
+        this.scheme = scheme;
+        this.network = network;
+        this.maxAmountRequired = maxAmountRequired;
+        this.payTo = payTo;
+        this.asset = asset;
+        this.extra = extra;
+        this.resource = resource;
+        this.description = description;
+        this.mimeType = mimeType;
+        this.outputSchema = outputSchema;
+        this.maxTimeoutSeconds = maxTimeoutSeconds;
+    }
+    static fromRaw(raw) {
+        const pick = (keys, defaultValue) => {
+            for (const key of keys) {
+                const value = raw[key];
+                if (value !== undefined && value !== null)
+                    return value;
+            }
+            return defaultValue;
+        };
+        const amount = pick(['maxAmountRequired', 'max_amount_required']);
+        const payTo = pick(['payTo', 'pay_to']);
+        const asset = pick(['asset', 'assetAddress', 'asset_address']);
+        const scheme = pick(['scheme']);
+        const network = pick(['network']);
+        if (!amount || !payTo || !asset || !scheme || !network) {
+            const missing = [
+                ['scheme', scheme],
+                ['network', network],
+                ['maxAmountRequired', amount],
+                ['payTo', payTo],
+                ['asset', asset],
+            ]
+                .filter(([, value]) => !value)
+                .map(([key]) => key)
+                .join(', ');
+            throw new errors_1.X402Error(`payment requirements missing fields: ${missing}`);
+        }
+        return new PaymentRequirements(String(scheme), String(network), String(amount), String(payTo), String(asset), pick(['extra'], {}) ?? {}, pick(['resource']), pick(['description']), pick(['mimeType', 'mime_type']), pick(['outputSchema', 'output_schema']), pick(['maxTimeoutSeconds', 'max_timeout_seconds']));
+    }
+    toPayload() {
+        const extraPayload = { ...(this.extra ?? {}) };
+        if ('tab_endpoint' in extraPayload && !('tabEndpoint' in extraPayload)) {
+            extraPayload['tabEndpoint'] = extraPayload['tab_endpoint'];
+            delete extraPayload['tab_endpoint'];
+        }
+        const payload = {
+            scheme: this.scheme,
+            network: this.network,
+            maxAmountRequired: this.maxAmountRequired,
+            payTo: this.payTo,
+            asset: this.asset,
+            extra: extraPayload,
+        };
+        if (this.resource !== undefined)
+            payload.resource = this.resource;
+        if (this.description !== undefined)
+            payload.description = this.description;
+        if (this.mimeType !== undefined)
+            payload.mimeType = this.mimeType;
+        if (this.outputSchema !== undefined)
+            payload.outputSchema = this.outputSchema;
+        if (this.maxTimeoutSeconds !== undefined)
+            payload.maxTimeoutSeconds = this.maxTimeoutSeconds;
+        return payload;
+    }
+}
+exports.PaymentRequirements = PaymentRequirements;
+class PaymentRequirementsExtra {
+    constructor(tabEndpoint) {
+        this.tabEndpoint = tabEndpoint;
+    }
+    static fromRaw(raw) {
+        const tabEndpointRaw = (isRecord(raw) ? raw.tabEndpoint : undefined) ??
+            (isRecord(raw) ? raw.tab_endpoint : undefined);
+        const tabEndpoint = typeof tabEndpointRaw === 'string'
+            ? tabEndpointRaw
+            : tabEndpointRaw === null
+                ? null
+                : undefined;
+        return new PaymentRequirementsExtra(tabEndpoint);
+    }
+}
+exports.PaymentRequirementsExtra = PaymentRequirementsExtra;
+class TabResponse {
+    constructor(tabId, userAddress, nextReqId) {
+        this.tabId = tabId;
+        this.userAddress = userAddress;
+        this.nextReqId = nextReqId;
+    }
+}
+exports.TabResponse = TabResponse;
+class X402PaymentEnvelope {
+    constructor(x402Version, scheme, network, payload) {
+        this.x402Version = x402Version;
+        this.scheme = scheme;
+        this.network = network;
+        this.payload = payload;
+    }
+    toPayload() {
+        return {
+            x402Version: this.x402Version,
+            scheme: this.scheme,
+            network: this.network,
+            payload: this.payload,
+        };
+    }
+}
+exports.X402PaymentEnvelope = X402PaymentEnvelope;
+class X402SignedPayment {
+    constructor(header, claims, signature) {
+        this.header = header;
+        this.claims = claims;
+        this.signature = signature;
+    }
+}
+exports.X402SignedPayment = X402SignedPayment;
+class X402SettledPayment {
+    constructor(payment, settlement) {
+        this.payment = payment;
+        this.settlement = settlement;
+    }
+}
+exports.X402SettledPayment = X402SettledPayment;
+class X402Flow {
+    constructor(signer, fetchFn = fetch) {
+        this.signer = signer;
+        this.fetchFn = fetchFn;
+    }
+    static fromClient(client) {
+        return new X402Flow(client.user);
+    }
+    async signPayment(paymentRequirements, userAddress, existingTabId, existingReqId) {
+        X402Flow.validateScheme(paymentRequirements.scheme);
+        let tab;
+        if (existingTabId !== undefined && existingTabId !== null) {
+            tab = new TabResponse(String(existingTabId), userAddress, existingReqId !== undefined && existingReqId !== null ? String(existingReqId) : undefined);
+        }
+        else {
+            tab = await this.requestTab(paymentRequirements, userAddress);
+        }
+        const claims = this.buildClaims(paymentRequirements, tab, userAddress);
+        const signature = await this.signer.signPayment(claims, models_1.SigningScheme.EIP712);
+        const envelope = X402Flow.buildEnvelope(paymentRequirements, claims, signature);
+        const payload = envelope.toPayload();
+        payload.x402Version ?? (payload.x402Version = envelope.x402Version);
+        const header = Buffer.from(JSON.stringify(payload)).toString('base64');
+        return new X402SignedPayment(header, claims, signature);
+    }
+    async settlePayment(payment, paymentRequirements, facilitatorUrl) {
+        const url = `${facilitatorUrl.replace(/\/$/, '')}/settle`;
+        const response = await this.fetchFn(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                x402Version: 1,
+                paymentHeader: payment.header,
+                paymentRequirements: paymentRequirements.toPayload(),
+            }),
+        });
+        const data = await response.text();
+        if (!response.ok) {
+            throw new errors_1.X402Error(`settlement failed with status ${response.status}: ${data}`);
+        }
+        const settlement = data ? JSON.parse(data) : {};
+        return new X402SettledPayment(payment, settlement);
+    }
+    async requestTab(paymentRequirements, userAddress) {
+        const extra = PaymentRequirementsExtra.fromRaw(paymentRequirements.extra);
+        if (!extra.tabEndpoint) {
+            throw new errors_1.X402Error('missing tabEndpoint in paymentRequirements.extra');
+        }
+        const resp = await this.fetchFn(extra.tabEndpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                userAddress,
+                paymentRequirements: paymentRequirements.toPayload(),
+            }),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new errors_1.X402Error(`tab resolution failed: ${resp.status} ${text}`);
+        }
+        const body = await resp.json();
+        return new TabResponse(body.tabId ?? body.tab_id, body.userAddress ?? body.user_address, body.nextReqId ?? body.next_req_id ?? body.reqId ?? body.req_id);
+    }
+    buildClaims(requirements, tab, userAddress) {
+        const tabId = (0, utils_1.parseU256)(tab.tabId);
+        const reqId = tab.nextReqId !== undefined && tab.nextReqId !== null ? (0, utils_1.parseU256)(tab.nextReqId) : 0n;
+        const amount = (0, utils_1.parseU256)(requirements.maxAmountRequired);
+        if (tab.userAddress.toLowerCase() !== userAddress.toLowerCase()) {
+            throw new errors_1.X402Error(`user mismatch in paymentRequirements: found ${tab.userAddress}, expected ${userAddress}`);
+        }
+        const timestamp = Math.floor(Date.now() / 1000);
+        return models_1.PaymentGuaranteeRequestClaims.new(userAddress, (0, utils_1.normalizeAddress)(requirements.payTo), tabId, amount, timestamp, requirements.asset, reqId);
+    }
+    static validateScheme(scheme) {
+        if (!scheme.toLowerCase().includes('4mica')) {
+            throw new errors_1.X402Error(`invalid scheme: ${scheme}`);
+        }
+    }
+    static buildEnvelope(paymentRequirements, claims, signature) {
+        const payload = {
+            claims: {
+                version: 'v1',
+                user_address: claims.userAddress,
+                recipient_address: claims.recipientAddress,
+                tab_id: `0x${claims.tabId.toString(16)}`,
+                req_id: `0x${claims.reqId.toString(16)}`,
+                amount: `0x${claims.amount.toString(16)}`,
+                asset_address: claims.assetAddress,
+                timestamp: claims.timestamp,
+            },
+            signature: signature.signature,
+            scheme: signature.scheme,
+        };
+        return new X402PaymentEnvelope(1, paymentRequirements.scheme, paymentRequirements.network, payload);
+    }
+}
+exports.X402Flow = X402Flow;

package/eslint.config.mjs

@@ -0,0 +1,22 @@
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import pluginReact from "eslint-plugin-react";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    ignores: ["dist/**", "coverage/**", "node_modules/**", "*.cjs"],
+  },
+  {
+    files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
+    plugins: { js },
+    extends: ["js/recommended"],
+    languageOptions: { globals: globals.browser },
+  },
+  tseslint.configs.recommended,
+  pluginReact.configs.flat.recommended,
+  {
+    settings: { react: { version: "detect" } },
+  },
+]);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@4mica/sdk",
+  "version": "0.5.0",
+  "description": "TypeScript SDK for interacting with the 4Mica payment network",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "eslint . --ext .ts",
+    "fmt": "prettier --check \"{src,tests}/**/*.{ts,js,json}\""
+  },
+  "dependencies": {
+    "ethers": "^6.16.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react": "^7.37.5",
+    "globals": "^17.3.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.17"
+  },
+  "license": "MIT"
+}