envoy-pay 0.1.0

package/dist/types/contracts/facilitator.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Typed viem client for `EnvoyFacilitator.sol`.
+ *
+ * Provides three layers:
+ *
+ *   1. Pure helpers — `paymentAuthDomain`, `paymentAuthTypes`, the typed-data
+ *      builder. Useful for any code that just needs to sign a `PaymentAuth`
+ *      without taking a Facilitator client dependency.
+ *   2. `signPaymentAuth(...)` — convenience wrapper around
+ *      `walletClient.signTypedData(...)` for the agent's signing wallet.
+ *   3. `createEnvoyFacilitator(...)` — full client bundling reads + writes +
+ *      sign + the contract address.
+ *
+ * All amounts are bigints in the token's smallest unit. cKES is 18 decimals;
+ * USDC is 6.
+ */
+import { type Account, type Address, type Hash, type Hex, type PublicClient, type WalletClient } from 'viem';
+/** The EIP-712 message the agent's wallet signs to authorize a single payment. */
+export interface PaymentAuth {
+    agentId: bigint;
+    token: Address;
+    merchant: Address;
+    amount: bigint;
+    challengeId: Hex;
+    nonce: bigint;
+    /** Unix seconds. Use a `uint64` value — the contract will revert past this. */
+    deadline: bigint;
+}
+/** Spending policy storage shape, as returned by `getLimit(...)`. */
+export interface LimitView {
+    perTx: bigint;
+    perPeriod: bigint;
+    spentInPeriod: bigint;
+    periodStart: bigint;
+    periodLen: number;
+    enabled: boolean;
+}
+export interface SettledEvent {
+    challengeId: Hex;
+    agentId: bigint;
+    merchant: Address;
+    token: Address;
+    amount: bigint;
+    fee: bigint;
+    nonce: bigint;
+    signer: Address;
+    txHash: Hash;
+    blockNumber: bigint;
+}
+export declare function paymentAuthDomain(args: {
+    chainId: number;
+    facilitatorAddress: Address;
+}): {
+    readonly name: "EnvoyFacilitator";
+    readonly version: "1";
+    readonly chainId: number;
+    readonly verifyingContract: `0x${string}`;
+};
+export declare const PAYMENT_AUTH_TYPES: {
+    readonly PaymentAuth: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "merchant";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "challengeId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint64";
+    }];
+};
+/** Build a viem-compatible typed-data payload for `walletClient.signTypedData`. */
+export declare function paymentAuthTypedData(args: {
+    chainId: number;
+    facilitatorAddress: Address;
+    auth: PaymentAuth;
+}): {
+    domain: {
+        readonly name: "EnvoyFacilitator";
+        readonly version: "1";
+        readonly chainId: number;
+        readonly verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly PaymentAuth: readonly [{
+            readonly name: "agentId";
+            readonly type: "uint256";
+        }, {
+            readonly name: "token";
+            readonly type: "address";
+        }, {
+            readonly name: "merchant";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "challengeId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint64";
+        }];
+    };
+    primaryType: "PaymentAuth";
+    message: PaymentAuth;
+};
+/** Sign a `PaymentAuth` with the agent's signing wallet. */
+export declare function signPaymentAuth(walletClient: WalletClient, args: {
+    chainId: number;
+    facilitatorAddress: Address;
+    auth: PaymentAuth;
+}): Promise<Hex>;
+export interface EnvoyFacilitatorClientOptions {
+    /** Address of the deployed `EnvoyFacilitator`. */
+    address: Address;
+    /** Public client for reads + receipt waiting. */
+    publicClient: PublicClient;
+    /** Optional wallet client for writes. Omit for read-only usage. */
+    walletClient?: WalletClient;
+    /** EIP-155 chainId. If omitted, the publicClient's chain is used. */
+    chainId?: number;
+}
+export interface EnvoyFacilitatorClient {
+    /** Resolved address of the deployed Facilitator. */
+    readonly address: Address;
+    /** Resolved chain id used for EIP-712 binding. */
+    readonly chainId: number;
+    getFeeBps(): Promise<number>;
+    getMaxFeeBps(): Promise<number>;
+    getTreasury(): Promise<Address>;
+    getIdentityRegistry(): Promise<Address>;
+    getLimit(agentId: bigint, token: Address): Promise<LimitView>;
+    isNonceUsed(agentId: bigint, nonce: bigint): Promise<boolean>;
+    /** Returns the on-chain digest the agent's wallet must sign. */
+    paymentAuthHash(auth: PaymentAuth): Promise<Hex>;
+    domainSeparator(): Promise<Hex>;
+    setLimit(args: {
+        agentId: bigint;
+        token: Address;
+        perTx: bigint;
+        perPeriod: bigint;
+        periodLen: number;
+        account?: Account | Address;
+    }): Promise<Hash>;
+    disableLimit(args: {
+        agentId: bigint;
+        token: Address;
+        account?: Account | Address;
+    }): Promise<Hash>;
+    setTreasury(newTreasury: Address, account?: Account | Address): Promise<Hash>;
+    pay(auth: PaymentAuth, signature: Hex, opts?: {
+        account?: Account | Address;
+    }): Promise<SettledEvent>;
+    signPaymentAuth(auth: PaymentAuth): Promise<Hex>;
+}
+export declare function createEnvoyFacilitator(opts: EnvoyFacilitatorClientOptions): EnvoyFacilitatorClient;
+//# sourceMappingURL=facilitator.d.ts.map

package/dist/types/contracts/facilitator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../../src/contracts/facilitator.ts"],"names":[],"mappings":"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"}

package/dist/types/contracts/index.d.ts

@@ -0,0 +1,6 @@
+export { ENVOY_CONTRACT_ADDRESSES, getEnvoyAddresses, CELO_MAINNET, CELO_SEPOLIA, } from './addresses';
+export type { EnvoyContractAddresses } from './addresses';
+export { createEnvoyFacilitator, signPaymentAuth, paymentAuthDomain, paymentAuthTypedData, PAYMENT_AUTH_TYPES, } from './facilitator';
+export type { PaymentAuth, LimitView, SettledEvent, EnvoyFacilitatorClient, EnvoyFacilitatorClientOptions, } from './facilitator';
+export { ENVOY_FACILITATOR_ABI } from './abis/EnvoyFacilitator';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,sBAAsB,EACtB,6BAA6B,GAC9B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/types/facilitator/facilitator-service.d.ts

@@ -0,0 +1,69 @@
+/**
+ * FacilitatorService — Core payment processing + fee extraction.
+ *
+ * This is where money is made. The FacilitatorService:
+ * 1. Validates the API key and checks rate limits
+ * 2. Calculates the facilitator fee
+ * 3. Routes the payment through UnifiedWallet
+ * 4. Extracts the fee before settlement
+ * 5. Records usage for billing
+ * 6. Returns a receipt
+ *
+ * Revenue flow:
+ * Agent pays $5.00 → envoy extracts $0.025 (0.5%) → Merchant gets $4.975
+ */
+import { ApiKeyRecord, FacilitateRequest, FacilitateResponse, PricingPlan, UsageRecord, RevenueSummary } from './types';
+export declare class FacilitatorService {
+    private apiKeys;
+    private transactions;
+    private feeCalculator;
+    private log;
+    constructor(options?: {
+        logger?: (msg: string) => void;
+    });
+    /**
+     * Create a new API key for a merchant.
+     */
+    createApiKey(ownerId: string, name: string, plan?: PricingPlan): ApiKeyRecord;
+    /**
+     * Validate an API key.
+     */
+    validateApiKey(key: string): {
+        valid: boolean;
+        reason?: string;
+    };
+    /**
+     * Revoke an API key.
+     */
+    revokeApiKey(key: string): boolean;
+    /**
+     * Upgrade an API key's plan.
+     */
+    upgradePlan(key: string, newPlan: PricingPlan): boolean;
+    /**
+     * Process a payment facilitation request.
+     * This is the core revenue-generating method.
+     */
+    facilitate(apiKey: string, request: FacilitateRequest): Promise<FacilitateResponse>;
+    /**
+     * Get usage for an API key in the current period.
+     */
+    getUsage(apiKey: string): UsageRecord | null;
+    /**
+     * Get revenue summary across all API keys.
+     */
+    getRevenueSummary(period?: 'day' | 'week' | 'month' | 'all-time'): RevenueSummary;
+    /**
+     * Get total API keys count.
+     */
+    getApiKeyCount(): number;
+    /**
+     * Get all active API keys.
+     */
+    getActiveKeys(): ApiKeyRecord[];
+    private failedResponse;
+    private getRateLimit;
+    private chainName;
+    private getVolumeForKey;
+}
+//# sourceMappingURL=facilitator-service.d.ts.map

package/dist/types/facilitator/facilitator-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facilitator-service.d.ts","sourceRoot":"","sources":["../../../src/facilitator/facilitator-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EAEX,WAAW,EACX,cAAc,EACf,MAAM,SAAS,CAAC;AAYjB,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAAwC;IACvD,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,GAAG,CAAwB;gBAEvB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE;IAOxD;;OAEG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,WAAmB,GACxB,YAAY;IA4Bf;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAkBhE;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQlC;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO;IAWvD;;;OAGG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,kBAAkB,CAAC;IAsE9B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAyB5C;;OAEG;IACH,iBAAiB,CAAC,MAAM,GAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,UAAuB,GAAG,cAAc;IAqE7F;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,aAAa,IAAI,YAAY,EAAE;IAM/B,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,eAAe;CAKxB"}

package/dist/types/facilitator/fee-calculator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * FeeCalculator — Compute facilitator fees per transaction.
+ *
+ * This is the core revenue logic. Every transaction through envoy
+ * gets a fee calculated based on:
+ * 1. The merchant's pricing plan (dev/growth/scale/enterprise)
+ * 2. The payment protocol (x402 vs MPP)
+ * 3. The transaction amount (micropayment premiums)
+ * 4. Volume discounts
+ *
+ * Fee = max(amount × feePercent, minFee) + networkCost
+ */
+import { FeeBreakdown, PricingPlan, PricingTier } from './types';
+export declare class FeeCalculator {
+    private tiers;
+    constructor(customTiers?: Partial<Record<PricingPlan, PricingTier>>);
+    /**
+     * Calculate the full fee breakdown for a transaction.
+     */
+    calculate(amountUsd: number, plan: PricingPlan, protocol?: 'x402' | 'mpp', chain?: string): FeeBreakdown;
+    /**
+     * Quick fee estimate (just the fee amount, no breakdown).
+     */
+    estimateFee(amountUsd: number, plan?: PricingPlan, protocol?: 'x402' | 'mpp'): number;
+    /**
+     * Calculate net revenue from a transaction (what envoy makes).
+     */
+    netRevenue(amountUsd: number, plan?: PricingPlan, protocol?: 'x402' | 'mpp', chain?: string): number;
+    /**
+     * Calculate revenue from N transactions at given plan.
+     * Useful for financial modeling.
+     */
+    projectRevenue(avgTransactionUsd: number, transactionCount: number, plan: PricingPlan, protocol?: 'x402' | 'mpp', chain?: string): {
+        grossFees: number;
+        networkCosts: number;
+        netRevenue: number;
+        margin: number;
+    };
+    /**
+     * Get the pricing tier for a plan.
+     */
+    getTier(plan: PricingPlan): PricingTier;
+    /**
+     * Get all pricing tiers.
+     */
+    getAllTiers(): Record<PricingPlan, PricingTier>;
+}
+//# sourceMappingURL=fee-calculator.d.ts.map

package/dist/types/facilitator/fee-calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fee-calculator.d.ts","sourceRoot":"","sources":["../../../src/facilitator/fee-calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,WAAW,EAEZ,MAAM,SAAS,CAAC;AAoCjB,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAmC;gBAEpC,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IASnE;;OAEG;IACH,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,WAAW,EACjB,QAAQ,GAAE,MAAM,GAAG,KAAc,EACjC,KAAK,GAAE,MAAuB,GAC7B,YAAY;IAqCf;;OAEG;IACH,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,WAAsB,EAC5B,QAAQ,GAAE,MAAM,GAAG,KAAc,GAChC,MAAM;IAKT;;OAEG;IACH,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,WAAsB,EAC5B,QAAQ,GAAE,MAAM,GAAG,KAAc,EACjC,KAAK,GAAE,MAAuB,GAC7B,MAAM;IAIT;;;OAGG;IACH,cAAc,CACZ,iBAAiB,EAAE,MAAM,EACzB,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,WAAW,EACjB,QAAQ,GAAE,MAAM,GAAG,KAAc,EACjC,KAAK,GAAE,MAAuB,GAC7B;QACD,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB;IAeD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW;IAIvC;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC;CAGhD"}

package/dist/types/facilitator/index.d.ts

@@ -0,0 +1,5 @@
+export { FacilitatorService } from './facilitator-service';
+export { FeeCalculator } from './fee-calculator';
+export type { PricingPlan, PricingTier, ApiKeyRecord, FacilitateRequest, FacilitateResponse, FeeBreakdown, UsageRecord, RevenueSummary, CardPlan, CardTier, } from './types';
+export { PRICING_TIERS, CARD_TIERS } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/facilitator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/facilitator/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,QAAQ,EACR,QAAQ,GACT,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}

package/dist/types/facilitator/types.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Facilitator Types — Hosted payment facilitation with fee extraction.
+ *
+ * The Facilitator API is the PRIMARY revenue engine. It processes
+ * agent payments, extracts a configurable fee (0.5-1.5%), and
+ * settles to the merchant.
+ *
+ * Revenue model:
+ * - x402 on-chain: 0.5% facilitator fee
+ * - MPP fiat: 1.5% + $0.05
+ * - Cross-chain: 1.0%
+ * - Micropayments (<$1): 2% (min $0.001)
+ *
+ * @see Stripe Connect — inspiration for fee model
+ */
+/** Pricing plan for API access. */
+export type PricingPlan = 'dev' | 'growth' | 'scale' | 'enterprise';
+/** Full pricing tier configuration. */
+export interface PricingTier {
+    plan: PricingPlan;
+    /** Monthly base price (USD). */
+    monthlyPrice: number;
+    /** Included transactions per month. */
+    includedTransactions: number;
+    /** Price per transaction over the included amount. */
+    overageRate: number;
+    /** Facilitator fee percentage (0-100). */
+    feePercent: number;
+    /** Minimum fee per transaction (USD). */
+    minFee: number;
+    /** Chains available. */
+    chains: 'single' | 'all';
+    /** Priority routing available. */
+    priorityRouting: boolean;
+    /** SLA uptime guarantee. */
+    slaUptime?: number;
+    /** Dedicated infrastructure. */
+    dedicatedInfra: boolean;
+}
+/** Default pricing tiers. */
+export declare const PRICING_TIERS: Record<PricingPlan, PricingTier>;
+/** API key record for authentication and billing. */
+export interface ApiKeyRecord {
+    /** API key string (e.g., "asg_live_..."). */
+    key: string;
+    /** Display name. */
+    name: string;
+    /** Owner identifier (user/org ID). */
+    ownerId: string;
+    /** Pricing plan. */
+    plan: PricingPlan;
+    /** Is the key active? */
+    isActive: boolean;
+    /** When the key was created. */
+    createdAt: Date;
+    /** Current billing period start. */
+    periodStart: Date;
+    /** Current billing period end. */
+    periodEnd: Date;
+    /** Transactions used this period. */
+    transactionsUsed: number;
+    /** Total revenue generated for envoy this period. */
+    revenueGenerated: number;
+    /** Rate limit per minute. */
+    rateLimit: number;
+    /** Metadata. */
+    metadata?: Record<string, string>;
+}
+/** Input to the Facilitator API. */
+export interface FacilitateRequest {
+    /** Payment protocol to use. */
+    protocol: 'x402' | 'mpp' | 'auto';
+    /** Amount in USD. */
+    amount: string;
+    /** Currency (default: USDC). */
+    currency?: string;
+    /** Merchant/destination address. */
+    destination: string;
+    /** Routing strategy. */
+    routing?: 'cheapest' | 'fastest' | 'prefer-crypto' | 'prefer-fiat';
+    /** Preferred chain (CAIP-2 ID). */
+    preferredChain?: string;
+    /** Agent DID (optional, for identity tracking). */
+    agentDid?: string;
+    /** Idempotency key. */
+    idempotencyKey?: string;
+    /** Memo/reference. */
+    memo?: string;
+}
+/** Successful facilitation response. */
+export interface FacilitateResponse {
+    /** Was the payment successful? */
+    success: boolean;
+    /** Unique facilitation ID. */
+    facilitationId: string;
+    /** Transaction hash (if on-chain). */
+    transactionHash: string | null;
+    /** Protocol used. */
+    protocol: 'x402' | 'mpp';
+    /** Chain used. */
+    chain: string;
+    /** CAIP-2 chain ID. */
+    caip2Id: string;
+    /** Amount settled to merchant (USD). */
+    amountSettled: string;
+    /** envoy facilitator fee (USD). */
+    fee: string;
+    /** Fee percentage applied. */
+    feePercent: number;
+    /** Total cost to agent (amount + fee). */
+    totalCost: string;
+    /** Settlement status. */
+    settlement: 'instant' | 'pending' | 'failed';
+    /** Timestamp. */
+    timestamp: Date;
+    /** Error message (if failed). */
+    error?: string;
+}
+/** Detailed fee calculation. */
+export interface FeeBreakdown {
+    /** Base amount (USD). */
+    baseAmount: number;
+    /** Fee percentage applied. */
+    feePercent: number;
+    /** Calculated fee (USD). */
+    calculatedFee: number;
+    /** Minimum fee applied? */
+    minFeeApplied: boolean;
+    /** Final fee (USD). */
+    finalFee: number;
+    /** Gas/network cost estimate (USD). */
+    networkCost: number;
+    /** envoy net revenue from this tx. */
+    netRevenue: number;
+    /** Total cost to agent. */
+    totalCost: number;
+}
+/** Usage record for a billing period. */
+export interface UsageRecord {
+    /** API key. */
+    apiKey: string;
+    /** Billing period start. */
+    periodStart: Date;
+    /** Billing period end. */
+    periodEnd: Date;
+    /** Total transactions. */
+    totalTransactions: number;
+    /** Included transactions (from plan). */
+    includedTransactions: number;
+    /** Overage transactions. */
+    overageTransactions: number;
+    /** Total volume processed (USD). */
+    totalVolume: number;
+    /** Total fees collected (USD). */
+    totalFees: number;
+    /** Overage charges (USD). */
+    overageCharges: number;
+    /** Subscription charge (USD). */
+    subscriptionCharge: number;
+    /** Grand total billing amount. */
+    totalBilling: number;
+}
+/** Revenue summary for the operator. */
+export interface RevenueSummary {
+    /** Time period. */
+    period: 'day' | 'week' | 'month' | 'all-time';
+    /** Total transactions processed. */
+    totalTransactions: number;
+    /** Total payment volume (USD). */
+    totalVolume: number;
+    /** Total fees collected (USD). */
+    totalFees: number;
+    /** Total subscription revenue (USD). */
+    subscriptionRevenue: number;
+    /** Total overage revenue (USD). */
+    overageRevenue: number;
+    /** Grand total revenue (USD). */
+    totalRevenue: number;
+    /** Average transaction size (USD). */
+    avgTransactionSize: number;
+    /** Average fee per transaction (USD). */
+    avgFee: number;
+    /** Active API keys. */
+    activeKeys: number;
+    /** Breakdown by protocol. */
+    byProtocol: {
+        x402: {
+            count: number;
+            volume: number;
+            fees: number;
+        };
+        mpp: {
+            count: number;
+            volume: number;
+            fees: number;
+        };
+    };
+    /** Breakdown by chain. */
+    byChain: Record<string, {
+        count: number;
+        volume: number;
+        fees: number;
+    }>;
+}
+/** Card pricing plan. */
+export type CardPlan = 'starter' | 'pro' | 'business' | 'enterprise';
+/** Card tier configuration. */
+export interface CardTier {
+    plan: CardPlan;
+    /** Monthly subscription price. */
+    monthlyPrice: number;
+    /** Maximum virtual cards. */
+    maxCards: number;
+    /** Per-card spending limit (USD/month). */
+    perCardLimit: number;
+    /** Estimated interchange rate (%). */
+    interchangeRate: number;
+}
+/** Default card tiers. */
+export declare const CARD_TIERS: Record<CardPlan, CardTier>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/facilitator/types.ts"],"names":[],"mappings":"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"}

package/dist/types/identity/agent-card.d.ts

@@ -0,0 +1,83 @@
+/**
+ * AgentCard — Capability and metadata registry for AI agents.
+ *
+ * Implements the ERC-8004 Identity Registry concept: each agent has
+ * a structured card describing its capabilities, service endpoints,
+ * owner, and multi-chain addresses.
+ *
+ * AgentCards are portable — they can be serialized to JSON and stored
+ * on IPFS, or registered on-chain as NFT metadata (ERC-721).
+ *
+ * @see ERC-8004 — Identity Registry (NFT-based agent IDs)
+ * @see Google A2A Protocol — AgentCard discovery
+ */
+import { AgentCardData } from './types';
+export declare class AgentCard {
+    private data;
+    readonly createdAt: Date;
+    private updatedAt;
+    constructor(data: AgentCardData);
+    get name(): string;
+    get version(): string;
+    get description(): string | undefined;
+    get capabilities(): string[];
+    get owner(): string;
+    get endpoints(): {
+        a2a?: string;
+        mcp?: string;
+        payment?: string;
+        webhook?: string;
+    } | undefined;
+    get addresses(): {
+        chain: string;
+        caip2Id: string;
+        address: string;
+    }[] | undefined;
+    get tags(): string[];
+    get iconUrl(): string | undefined;
+    /**
+     * Check if this agent has a specific capability.
+     */
+    hasCapability(capability: string): boolean;
+    /**
+     * Check if this agent has ALL of the specified capabilities.
+     */
+    hasAllCapabilities(capabilities: string[]): boolean;
+    /**
+     * Check if this agent has ANY of the specified capabilities.
+     */
+    hasAnyCapability(capabilities: string[]): boolean;
+    /**
+     * Add a capability to the agent card.
+     */
+    addCapability(capability: string): void;
+    /**
+     * Remove a capability from the agent card.
+     */
+    removeCapability(capability: string): boolean;
+    /**
+     * Update a service endpoint.
+     */
+    setEndpoint(type: 'a2a' | 'mcp' | 'payment' | 'webhook', url: string): void;
+    /**
+     * Add a chain address to the agent card.
+     */
+    addAddress(chain: string, caip2Id: string, address: string): void;
+    /**
+     * Serialize to JSON (for IPFS, on-chain storage, etc.)
+     */
+    toJSON(): AgentCardData & {
+        createdAt: string;
+        updatedAt: string;
+    };
+    /**
+     * Create an AgentCard from JSON.
+     */
+    static fromJSON(json: AgentCardData): AgentCard;
+    /**
+     * Get the raw data.
+     */
+    getData(): Readonly<AgentCardData>;
+    private validateCard;
+}
+//# sourceMappingURL=agent-card.d.ts.map

package/dist/types/identity/agent-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-card.d.ts","sourceRoot":"","sources":["../../../src/identity/agent-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAgB;IAC5B,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,OAAO,CAAC,SAAS,CAAO;gBAEZ,IAAI,EAAE,aAAa;IAS/B,IAAI,IAAI,IAAI,MAAM,CAA2B;IAC7C,IAAI,OAAO,IAAI,MAAM,CAA8B;IACnD,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAAkC;IACvE,IAAI,YAAY,IAAI,MAAM,EAAE,CAAwC;IACpE,IAAI,KAAK,IAAI,MAAM,CAA4B;IAC/C,IAAI,SAAS;;;;;kBAA2E;IACxF,IAAI,SAAS;;;;oBAAyE;IACtF,IAAI,IAAI,IAAI,MAAM,EAAE,CAAsD;IAC1E,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAA8B;IAI/D;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI1C;;OAEG;IACH,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO;IAInD;;OAEG;IACH,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO;IAMjD;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAQvC;;OAEG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAU7C;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAQ3E;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAiBjE;;OAEG;IACH,MAAM,IAAI,aAAa,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAQlE;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS;IAI/C;;OAEG;IACH,OAAO,IAAI,QAAQ,CAAC,aAAa,CAAC;IAMlC,OAAO,CAAC,YAAY;CAcrB"}