@4mica/sdk 1.2.16 → 1.3.1

package/dist/src/x402/index.d.ts

@@ -1,90 +0,0 @@
-import { PaymentGuaranteeRequestClaims, PaymentGuaranteeRequestClaimsV2, PaymentSignature, SigningScheme } from '../models';
-import { PaymentRequirementsV1, TabResponse, X402SignedPayment, X402SettledPayment, PaymentRequirementsV2, X402PaymentRequired, X402ResourceInfo } from './models';
-import type { FetchFn } from '../rpc';
-export * from './models';
-/**
- * Minimal signing interface required by {@link X402Flow}.
- * Implemented by {@link UserClient} from the main SDK client.
- */
-export interface FlowSigner {
-    signPayment(claims: PaymentGuaranteeRequestClaims | PaymentGuaranteeRequestClaimsV2, scheme: SigningScheme): Promise<PaymentSignature>;
-}
-/**
- * Handles the x402 HTTP 402 payment protocol for 4Mica.
- *
- * Orchestrates the full client-side x402 flow: resolving a tab from the recipient's
- * tab endpoint, building and signing payment claims (V1 or V2), and optionally settling
- * the payment against a facilitator service.
- *
- * @example
- * ```ts
- * const flow = X402Flow.fromClient(client);
- * const signed = await flow.signPayment(paymentRequirements, userAddress);
- * // attach signed.header as the X-PAYMENT header on the protected request
- * ```
- */
-export declare class X402Flow {
-    private signer;
-    private fetchFn;
-    /**
-     * @param signer - Payment signer, typically `client.user`.
-     * @param fetchFn - HTTP fetch implementation. Defaults to global `fetch`.
-     */
-    constructor(signer: FlowSigner, fetchFn?: FetchFn);
-    /**
-     * Convenience factory — creates an `X402Flow` from the user sub-client of a `Client`.
-     *
-     * @param client - Any object with a `.user` property implementing {@link FlowSigner}.
-     */
-    static fromClient(client: {
-        user: FlowSigner;
-    }): X402Flow;
-    /**
-     * Sign an x402 V1 payment.
-     *
-     * Resolves a tab from `paymentRequirements.extra.tabEndpoint`, builds V1 claims,
-     * signs them with EIP-712, and returns the base64-encoded payment header together
-     * with the raw payload and signature.
-     *
-     * @param paymentRequirements - V1 payment requirements from the `402 Payment Required` response.
-     * @param userAddress - Address of the paying user.
-     * @returns Signed payment ready to attach as the `X-PAYMENT` request header.
-     * @throws {@link X402Error} if the scheme is not a 4Mica scheme or the tab endpoint fails.
-     */
-    signPayment(paymentRequirements: PaymentRequirementsV1, userAddress: string): Promise<X402SignedPayment>;
-    /**
-     * Sign an x402 V2 payment, optionally including a V2 validation policy.
-     *
-     * If `accepted.extra` contains all required validation policy fields
-     * (`validationRegistryAddress`, `validatorAddress`, `validatorAgentId`,
-     * `minValidationScore`, `validationChainId`, `jobHash`), the claims are built as V2 with
-     * the computed `validationSubjectHash` and `validationRequestHash`. Otherwise
-     * falls back to V1 claims.
-     *
-     * @param paymentRequired - The original `402 Payment Required` response object.
-     * @param accepted - The accepted V2 payment requirements.
-     * @param userAddress - Address of the paying user.
-     * @returns Signed payment ready to attach as the `X-PAYMENT` request header.
-     * @throws {@link X402Error} if the scheme is not a 4Mica scheme or the tab endpoint fails.
-     */
-    signPaymentV2(paymentRequired: X402PaymentRequired, accepted: PaymentRequirementsV2, userAddress: string): Promise<X402SignedPayment>;
-    /**
-     * Submit a signed payment to a facilitator for on-chain settlement.
-     *
-     * Sends a POST request to `{facilitatorUrl}/settle` with the payment header,
-     * decoded payload, and payment requirements. Use this when the protected resource
-     * requires facilitator-confirmed settlement before granting access.
-     *
-     * @param payment - Signed payment returned by {@link signPayment} or {@link signPaymentV2}.
-     * @param paymentRequirements - V1 payment requirements included in the settlement request.
-     * @param facilitatorUrl - Base URL of the facilitator service.
-     * @returns The original payment plus the raw settlement response from the facilitator.
-     * @throws {@link X402Error} if the facilitator returns a non-2xx response.
-     */
-    settlePayment(payment: X402SignedPayment, paymentRequirements: PaymentRequirementsV1, facilitatorUrl: string): Promise<X402SettledPayment>;
-    protected requestTab(x402Version: number, paymentRequirements: PaymentRequirementsV1 | PaymentRequirementsV2, userAddress: string, resource?: X402ResourceInfo): Promise<TabResponse>;
-    protected buildClaims(requirements: PaymentRequirementsV1 | PaymentRequirementsV2, tab: TabResponse, userAddress: string): PaymentGuaranteeRequestClaims;
-    protected buildClaimsV2(requirements: PaymentRequirementsV2, tab: TabResponse, userAddress: string): PaymentGuaranteeRequestClaimsV2;
-    private static validateScheme;
-    private static decodePaymentHeader;
-}

package/dist/src/x402/index.js

@@ -1,243 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.X402Flow = void 0;
-const models_1 = require("../models");
-const utils_1 = require("../utils");
-const errors_1 = require("../errors");
-const payment_1 = require("../payment");
-const validation_1 = require("../validation");
-__exportStar(require("./models"), exports);
-function hasValidationPolicy(extra) {
-    return !!(extra?.validationRegistryAddress &&
-        extra?.validatorAddress &&
-        extra?.validatorAgentId !== undefined &&
-        extra?.minValidationScore !== undefined &&
-        extra?.validationChainId !== undefined &&
-        extra?.jobHash);
-}
-/**
- * Handles the x402 HTTP 402 payment protocol for 4Mica.
- *
- * Orchestrates the full client-side x402 flow: resolving a tab from the recipient's
- * tab endpoint, building and signing payment claims (V1 or V2), and optionally settling
- * the payment against a facilitator service.
- *
- * @example
- * ```ts
- * const flow = X402Flow.fromClient(client);
- * const signed = await flow.signPayment(paymentRequirements, userAddress);
- * // attach signed.header as the X-PAYMENT header on the protected request
- * ```
- */
-class X402Flow {
-    signer;
-    fetchFn;
-    /**
-     * @param signer - Payment signer, typically `client.user`.
-     * @param fetchFn - HTTP fetch implementation. Defaults to global `fetch`.
-     */
-    constructor(signer, fetchFn = fetch) {
-        this.signer = signer;
-        this.fetchFn = fetchFn;
-    }
-    /**
-     * Convenience factory — creates an `X402Flow` from the user sub-client of a `Client`.
-     *
-     * @param client - Any object with a `.user` property implementing {@link FlowSigner}.
-     */
-    static fromClient(client) {
-        return new X402Flow(client.user);
-    }
-    /**
-     * Sign an x402 V1 payment.
-     *
-     * Resolves a tab from `paymentRequirements.extra.tabEndpoint`, builds V1 claims,
-     * signs them with EIP-712, and returns the base64-encoded payment header together
-     * with the raw payload and signature.
-     *
-     * @param paymentRequirements - V1 payment requirements from the `402 Payment Required` response.
-     * @param userAddress - Address of the paying user.
-     * @returns Signed payment ready to attach as the `X-PAYMENT` request header.
-     * @throws {@link X402Error} if the scheme is not a 4Mica scheme or the tab endpoint fails.
-     */
-    async signPayment(paymentRequirements, userAddress) {
-        X402Flow.validateScheme(paymentRequirements.scheme);
-        const tab = await this.requestTab(1, paymentRequirements, userAddress);
-        const claims = this.buildClaims(paymentRequirements, tab, userAddress);
-        const signature = await this.signer.signPayment(claims, models_1.SigningScheme.EIP712);
-        const paymentPayload = (0, payment_1.buildPaymentPayload)(claims, signature);
-        const envelope = {
-            x402Version: 1,
-            scheme: paymentRequirements.scheme,
-            network: paymentRequirements.network,
-            payload: paymentPayload,
-        };
-        const header = Buffer.from(JSON.stringify(envelope)).toString('base64');
-        return { header, payload: paymentPayload, signature };
-    }
-    /**
-     * Sign an x402 V2 payment, optionally including a V2 validation policy.
-     *
-     * If `accepted.extra` contains all required validation policy fields
-     * (`validationRegistryAddress`, `validatorAddress`, `validatorAgentId`,
-     * `minValidationScore`, `validationChainId`, `jobHash`), the claims are built as V2 with
-     * the computed `validationSubjectHash` and `validationRequestHash`. Otherwise
-     * falls back to V1 claims.
-     *
-     * @param paymentRequired - The original `402 Payment Required` response object.
-     * @param accepted - The accepted V2 payment requirements.
-     * @param userAddress - Address of the paying user.
-     * @returns Signed payment ready to attach as the `X-PAYMENT` request header.
-     * @throws {@link X402Error} if the scheme is not a 4Mica scheme or the tab endpoint fails.
-     */
-    async signPaymentV2(paymentRequired, accepted, userAddress) {
-        X402Flow.validateScheme(accepted.scheme);
-        const isV2Claims = hasValidationPolicy(accepted.extra);
-        const tab = await this.requestTab(isV2Claims ? 2 : 1, accepted, userAddress, paymentRequired.resource);
-        const claims = isV2Claims
-            ? this.buildClaimsV2(accepted, tab, userAddress)
-            : this.buildClaims(accepted, tab, userAddress);
-        const signature = await this.signer.signPayment(claims, models_1.SigningScheme.EIP712);
-        const paymentPayload = (0, payment_1.buildPaymentPayload)(claims, signature);
-        const envelope = {
-            x402Version: 2,
-            accepted: accepted,
-            payload: paymentPayload,
-            resource: paymentRequired.resource,
-        };
-        const header = Buffer.from(JSON.stringify(envelope)).toString('base64');
-        return { header, payload: paymentPayload, signature };
-    }
-    /**
-     * Submit a signed payment to a facilitator for on-chain settlement.
-     *
-     * Sends a POST request to `{facilitatorUrl}/settle` with the payment header,
-     * decoded payload, and payment requirements. Use this when the protected resource
-     * requires facilitator-confirmed settlement before granting access.
-     *
-     * @param payment - Signed payment returned by {@link signPayment} or {@link signPaymentV2}.
-     * @param paymentRequirements - V1 payment requirements included in the settlement request.
-     * @param facilitatorUrl - Base URL of the facilitator service.
-     * @returns The original payment plus the raw settlement response from the facilitator.
-     * @throws {@link X402Error} if the facilitator returns a non-2xx response.
-     */
-    async settlePayment(payment, paymentRequirements, facilitatorUrl) {
-        const url = `${facilitatorUrl.replace(/\/$/, '')}/settle`;
-        const paymentPayload = X402Flow.decodePaymentHeader(payment.header);
-        const x402Version = typeof paymentPayload === 'object' && paymentPayload && 'x402Version' in paymentPayload
-            ? paymentPayload.x402Version
-            : undefined;
-        const response = await this.fetchFn(url, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                ...(x402Version ? { x402Version } : {}),
-                paymentHeader: payment.header,
-                paymentPayload,
-                paymentRequirements,
-            }),
-        });
-        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 { payment, settlement };
-    }
-    async requestTab(x402Version, paymentRequirements, userAddress, resource) {
-        const tabEndpoint = paymentRequirements.extra?.tabEndpoint;
-        if (!tabEndpoint || typeof tabEndpoint !== 'string') {
-            throw new errors_1.X402Error('missing tabEndpoint in paymentRequirements.extra');
-        }
-        const resp = await this.fetchFn(tabEndpoint, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                x402Version,
-                userAddress,
-                paymentRequirements,
-                resource,
-            }),
-        });
-        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 {
-            tabId: body.tabId ?? body.tab_id,
-            userAddress: body.userAddress ?? body.user_address,
-            nextReqId: 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)('maxAmountRequired' in requirements ? requirements.maxAmountRequired : requirements.amount);
-        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);
-    }
-    buildClaimsV2(requirements, tab, userAddress) {
-        const base = this.buildClaims(requirements, tab, userAddress);
-        const extra = requirements.extra;
-        const validationSubjectHash = (0, validation_1.computeValidationSubjectHash)(base);
-        const partialClaims = new models_1.PaymentGuaranteeRequestClaimsV2({
-            userAddress: base.userAddress,
-            recipientAddress: base.recipientAddress,
-            tabId: base.tabId,
-            reqId: base.reqId,
-            amount: base.amount,
-            timestamp: base.timestamp,
-            assetAddress: base.assetAddress,
-            validationRegistryAddress: extra.validationRegistryAddress,
-            validationRequestHash: '0x' + '00'.repeat(32),
-            validationChainId: extra.validationChainId,
-            validatorAddress: extra.validatorAddress,
-            validatorAgentId: (0, utils_1.parseU256)(extra.validatorAgentId),
-            minValidationScore: extra.minValidationScore,
-            validationSubjectHash,
-            jobHash: extra.jobHash,
-            requiredValidationTag: extra.requiredValidationTag ?? '',
-        });
-        const validationRequestHash = (0, validation_1.computeValidationRequestHash)(partialClaims);
-        return new models_1.PaymentGuaranteeRequestClaimsV2({
-            ...partialClaims,
-            validationRequestHash,
-        });
-    }
-    static validateScheme(scheme) {
-        if (!scheme.toLowerCase().includes('4mica')) {
-            throw new errors_1.X402Error(`invalid scheme: ${scheme}`);
-        }
-    }
-    static decodePaymentHeader(header) {
-        if (!header || typeof header !== 'string') {
-            throw new errors_1.X402Error('missing payment header');
-        }
-        try {
-            const decoded = Buffer.from(header, 'base64').toString('utf8');
-            return JSON.parse(decoded);
-        }
-        catch (err) {
-            throw new errors_1.X402Error(`invalid payment header: ${String(err)}`);
-        }
-    }
-}
-exports.X402Flow = X402Flow;

package/dist/src/x402/models.d.ts

@@ -1,75 +0,0 @@
-import { PaymentSignature } from '../models';
-import type { PaymentPayload } from '../payment';
-export interface PaymentRequirementsV1 {
-    scheme: string;
-    network: string;
-    maxAmountRequired: string;
-    payTo: string;
-    asset: string;
-    resource?: string;
-    description?: string;
-    mimeType?: string;
-    outputSchema?: unknown;
-    maxTimeoutSeconds?: number;
-    extra?: PaymentRequirementsExtra;
-}
-export interface PaymentRequirementsV2 {
-    scheme: string;
-    network: string;
-    asset: string;
-    amount: string;
-    payTo: string;
-    maxTimeoutSeconds?: number;
-    extra?: PaymentRequirementsExtra;
-}
-export type PaymentRequirements = PaymentRequirementsV2;
-export interface PaymentRequirementsExtra {
-    tabEndpoint?: string;
-    validationRegistryAddress?: string;
-    validationChainId?: number;
-    validatorAddress?: string;
-    validatorAgentId?: string;
-    minValidationScore?: number;
-    jobHash?: string;
-    requiredValidationTag?: string;
-}
-export interface TabResponse {
-    tabId: string;
-    userAddress: string;
-    nextReqId?: string;
-}
-export type X402PaymentPayloadClaims = PaymentPayload['claims'];
-export type X402PaymentPayload = PaymentPayload;
-export interface X402PaymentEnvelopeV1 {
-    x402Version: number;
-    scheme: string;
-    network: string;
-    payload: X402PaymentPayload;
-}
-export interface X402ResourceInfo {
-    url: string;
-    description: string;
-    mimeType: string;
-}
-export interface X402PaymentEnvelopeV2 {
-    x402Version: number;
-    accepted: PaymentRequirementsV2;
-    payload: X402PaymentPayload;
-    resource: X402ResourceInfo;
-}
-export interface X402SignedPayment {
-    header: string;
-    payload: X402PaymentPayload;
-    signature: PaymentSignature;
-}
-export interface X402SettledPayment {
-    payment: X402SignedPayment;
-    settlement: unknown;
-}
-export interface X402PaymentRequired {
-    x402Version: number;
-    error?: string;
-    resource: X402ResourceInfo;
-    accepts: PaymentRequirementsV2[];
-    extensions?: Record<string, unknown>;
-}

package/dist/src/x402/models.js

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