@resvary/sdk 0.5.0-alpha.1

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025-2026 horn111
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,17 @@
+# @resvary/sdk
+
+Open-source prepaid credits and usage billing for AI products.
+
+Primary imports:
+
+```typescript
+import { CreditLedger } from '@resvary/sdk/credits';
+import { createMeterDefinition, createPriceVersion, rateUsage } from '@resvary/sdk/pricing';
+import { ArcCreditFunding } from '@resvary/sdk/funding/arc';
+```
+
+The SDK provides USD credit accounts, manual grants, reserve/commit/release, immutable usage receipts, idempotency, a transactional outbox, and signed credit webhooks. It has no database or AI provider dependency.
+
+Legacy stablecoin payment imports under `/receipts`, `/middleware`, `/client`, and `/gateway` remain compatible. `UsageMeter` and `createBillingPlan` are deprecated for new balance systems.
+
+See the repository README and `docs/` for the complete quickstart and security model.

package/dist/billing/index.d.ts

@@ -0,0 +1,3 @@
+export { UsageMeter, type UsageRecord, type MeterConfig, type UsageSummary } from './meter.js';
+export { createBillingPlan, type BillingPlan, type PricingModel, type PerRequestPricing, type PerSecondPricing, type PerJobPricing, type UsageInput, } from './plans.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC"}

package/dist/billing/index.js

@@ -0,0 +1,3 @@
+export { UsageMeter } from './meter.js';
+export { createBillingPlan, } from './plans.js';
+//# sourceMappingURL=index.js.map

package/dist/billing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAyD,MAAM,YAAY,CAAC;AAC/F,OAAO,EACL,iBAAiB,GAOlB,MAAM,YAAY,CAAC"}

package/dist/billing/meter.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Usage metering for tracking API consumption and billing.
+ *
+ * @example
+ * ```typescript
+ * import { UsageMeter } from '@resvary/sdk/billing';
+ *
+ * const meter = new UsageMeter({ endpoint: '/api/data' });
+ *
+ * // Record usage
+ * meter.record({ buyer: '0x...', amount: '0.001' });
+ *
+ * // Get usage summary
+ * const summary = meter.getSummary('0x...');
+ * console.log(summary.totalSpent); // '0.003'
+ * ```
+ */
+/** Configuration for the usage meter */
+export interface MeterConfig {
+    /** Endpoint being metered */
+    endpoint: string;
+    /** Maximum records to keep in memory (default: 10000) */
+    maxRecords?: number;
+}
+/** A single usage record */
+export interface UsageRecord {
+    /** Buyer's wallet address */
+    buyer: `0x${string}`;
+    /** Amount paid in USDC */
+    amount: string;
+    /** Endpoint accessed */
+    endpoint: string;
+    /** Timestamp of the request */
+    timestamp: number;
+    /** Settlement status */
+    status: 'pending' | 'batched' | 'settled';
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Usage summary for a buyer */
+export interface UsageSummary {
+    /** Buyer's address */
+    buyer: `0x${string}`;
+    /** Total amount spent in USDC */
+    totalSpent: string;
+    /** Total number of requests */
+    totalRequests: number;
+    /** First usage timestamp */
+    firstSeen: number;
+    /** Last usage timestamp */
+    lastSeen: number;
+    /** Average cost per request */
+    avgCostPerRequest: string;
+}
+/**
+ * In-memory usage meter for tracking API consumption.
+ *
+ * For production use, extend with a persistent store
+ * (Supabase, Postgres, Redis, etc.)
+ */
+/** @deprecated Use CreditLedger with meters, price versions, and usage receipts instead. */
+export declare class UsageMeter {
+    private readonly records;
+    private readonly endpoint;
+    private readonly maxRecords;
+    constructor(config: MeterConfig);
+    /**
+     * Record a usage event.
+     */
+    record(params: {
+        buyer: `0x${string}`;
+        amount: string;
+        metadata?: Record<string, unknown>;
+    }): UsageRecord;
+    /**
+     * Get usage summary for a specific buyer.
+     */
+    getSummary(buyer: `0x${string}`): UsageSummary;
+    /**
+     * Get all usage records, optionally filtered.
+     */
+    getRecords(filter?: {
+        buyer?: `0x${string}`;
+        since?: number;
+        status?: UsageRecord['status'];
+    }): UsageRecord[];
+    /**
+     * Get aggregate stats across all buyers.
+     */
+    getAggregateStats(): {
+        totalRevenue: string;
+        totalRequests: number;
+        uniqueBuyers: number;
+        avgRevenuePerRequest: string;
+    };
+}
+//# sourceMappingURL=meter.d.ts.map

package/dist/billing/meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../src/billing/meter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,4BAA4B;AAC5B,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;IACrB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,sBAAsB;IACtB,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;IACrB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,4FAA4F;AAC5F,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,EAAE,WAAW;IAK/B;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,WAAW;IAoBzG;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,KAAK,MAAM,EAAE,GAAG,YAAY;IA+B9C;;OAEG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE;QAClB,KAAK,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;KAChC,GAAG,WAAW,EAAE;IAoBjB;;OAEG;IACH,iBAAiB,IAAI;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,oBAAoB,EAAE,MAAM,CAAC;KAC9B;CAiBF"}

package/dist/billing/meter.js

@@ -0,0 +1,109 @@
+/**
+ * Usage metering for tracking API consumption and billing.
+ *
+ * @example
+ * ```typescript
+ * import { UsageMeter } from '@resvary/sdk/billing';
+ *
+ * const meter = new UsageMeter({ endpoint: '/api/data' });
+ *
+ * // Record usage
+ * meter.record({ buyer: '0x...', amount: '0.001' });
+ *
+ * // Get usage summary
+ * const summary = meter.getSummary('0x...');
+ * console.log(summary.totalSpent); // '0.003'
+ * ```
+ */
+/**
+ * In-memory usage meter for tracking API consumption.
+ *
+ * For production use, extend with a persistent store
+ * (Supabase, Postgres, Redis, etc.)
+ */
+/** @deprecated Use CreditLedger with meters, price versions, and usage receipts instead. */
+export class UsageMeter {
+    records = [];
+    endpoint;
+    maxRecords;
+    constructor(config) {
+        this.endpoint = config.endpoint;
+        this.maxRecords = config.maxRecords ?? 10_000;
+    }
+    /**
+     * Record a usage event.
+     */
+    record(params) {
+        const record = {
+            buyer: params.buyer,
+            amount: params.amount,
+            endpoint: this.endpoint,
+            timestamp: Date.now(),
+            status: 'pending',
+            metadata: params.metadata,
+        };
+        this.records.push(record);
+        // Evict oldest records if over limit
+        if (this.records.length > this.maxRecords) {
+            this.records.splice(0, this.records.length - this.maxRecords);
+        }
+        return record;
+    }
+    /**
+     * Get usage summary for a specific buyer.
+     */
+    getSummary(buyer) {
+        const buyerRecords = this.records.filter((r) => r.buyer.toLowerCase() === buyer.toLowerCase());
+        if (buyerRecords.length === 0) {
+            return {
+                buyer,
+                totalSpent: '0',
+                totalRequests: 0,
+                firstSeen: 0,
+                lastSeen: 0,
+                avgCostPerRequest: '0',
+            };
+        }
+        const totalSpent = buyerRecords.reduce((sum, r) => sum + parseFloat(r.amount), 0);
+        return {
+            buyer,
+            totalSpent: totalSpent.toFixed(6),
+            totalRequests: buyerRecords.length,
+            firstSeen: buyerRecords[0].timestamp,
+            lastSeen: buyerRecords[buyerRecords.length - 1].timestamp,
+            avgCostPerRequest: (totalSpent / buyerRecords.length).toFixed(6),
+        };
+    }
+    /**
+     * Get all usage records, optionally filtered.
+     */
+    getRecords(filter) {
+        let filtered = [...this.records];
+        if (filter?.buyer) {
+            filtered = filtered.filter((r) => r.buyer.toLowerCase() === filter.buyer.toLowerCase());
+        }
+        if (filter?.since) {
+            filtered = filtered.filter((r) => r.timestamp >= filter.since);
+        }
+        if (filter?.status) {
+            filtered = filtered.filter((r) => r.status === filter.status);
+        }
+        return filtered;
+    }
+    /**
+     * Get aggregate stats across all buyers.
+     */
+    getAggregateStats() {
+        const totalRevenue = this.records.reduce((sum, r) => sum + parseFloat(r.amount), 0);
+        const uniqueBuyers = new Set(this.records.map((r) => r.buyer.toLowerCase())).size;
+        return {
+            totalRevenue: totalRevenue.toFixed(6),
+            totalRequests: this.records.length,
+            uniqueBuyers,
+            avgRevenuePerRequest: this.records.length > 0
+                ? (totalRevenue / this.records.length).toFixed(6)
+                : '0',
+        };
+    }
+}
+//# sourceMappingURL=meter.js.map

package/dist/billing/meter.js.map

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

package/dist/billing/plans.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Billing plan definitions for different pricing models.
+ *
+ * @example
+ * ```typescript
+ * import { createBillingPlan } from '@resvary/sdk/billing';
+ *
+ * const apiPlan = createBillingPlan({
+ *   name: 'API Standard',
+ *   pricing: { model: 'per-request', pricePerRequest: '0.001' },
+ * });
+ *
+ * const cost = apiPlan.calculateCost({ requests: 100 });
+ * console.log(cost); // '0.1'
+ * ```
+ */
+/** Per-request pricing: fixed cost per API call */
+export interface PerRequestPricing {
+    model: 'per-request';
+    /** Price in USDC per request */
+    pricePerRequest: string;
+}
+/** Per-second pricing: time-based billing */
+export interface PerSecondPricing {
+    model: 'per-second';
+    /** Price in USDC per second */
+    pricePerSecond: string;
+    /** Minimum billable seconds (default: 1) */
+    minimumSeconds?: number;
+}
+/** Per-job pricing: batch operation billing */
+export interface PerJobPricing {
+    model: 'per-job';
+    /** Base price in USDC per job */
+    basePrice: string;
+    /** Additional price per unit of work (e.g., per MB, per token) */
+    pricePerUnit?: string;
+    /** Name of the unit (e.g., 'MB', 'token', 'row') */
+    unitName?: string;
+}
+/** Union of all pricing model types */
+export type PricingModel = PerRequestPricing | PerSecondPricing | PerJobPricing;
+/** Billing plan configuration */
+export interface BillingPlan {
+    /** Plan name */
+    name: string;
+    /** Plan description */
+    description?: string;
+    /** Pricing model */
+    pricing: PricingModel;
+    /** Calculate cost based on usage */
+    calculateCost: (usage: UsageInput) => string;
+    /** Get the minimum payment amount for this plan */
+    getMinimumPayment: () => string;
+}
+/** Input for cost calculation */
+export interface UsageInput {
+    /** Number of requests (for per-request model) */
+    requests?: number;
+    /** Duration in seconds (for per-second model) */
+    seconds?: number;
+    /** Number of units processed (for per-job model) */
+    units?: number;
+}
+/**
+ * Create a billing plan with a specific pricing model.
+ *
+ * @param config - Plan configuration
+ * @returns A billing plan with cost calculation methods
+ */
+/** @deprecated Use createMeterDefinition, createPriceVersion, and rateUsage instead. */
+export declare function createBillingPlan(config: {
+    name: string;
+    description?: string;
+    pricing: PricingModel;
+}): BillingPlan;
+//# sourceMappingURL=plans.d.ts.map

package/dist/billing/plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../../src/billing/plans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,+BAA+B;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,CAAC;IACjB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,uCAAuC;AACvC,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAEhF,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB;IACpB,OAAO,EAAE,YAAY,CAAC;IACtB,oCAAoC;IACpC,aAAa,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;IAC7C,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,MAAM,CAAC;CACjC;AAED,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;CACvB,GAAG,WAAW,CAmDd"}

package/dist/billing/plans.js

@@ -0,0 +1,65 @@
+/**
+ * Billing plan definitions for different pricing models.
+ *
+ * @example
+ * ```typescript
+ * import { createBillingPlan } from '@resvary/sdk/billing';
+ *
+ * const apiPlan = createBillingPlan({
+ *   name: 'API Standard',
+ *   pricing: { model: 'per-request', pricePerRequest: '0.001' },
+ * });
+ *
+ * const cost = apiPlan.calculateCost({ requests: 100 });
+ * console.log(cost); // '0.1'
+ * ```
+ */
+/**
+ * Create a billing plan with a specific pricing model.
+ *
+ * @param config - Plan configuration
+ * @returns A billing plan with cost calculation methods
+ */
+/** @deprecated Use createMeterDefinition, createPriceVersion, and rateUsage instead. */
+export function createBillingPlan(config) {
+    const { name, description, pricing } = config;
+    return {
+        name,
+        description,
+        pricing,
+        calculateCost(usage) {
+            switch (pricing.model) {
+                case 'per-request': {
+                    const requests = usage.requests ?? 1;
+                    return (requests * parseFloat(pricing.pricePerRequest)).toFixed(6);
+                }
+                case 'per-second': {
+                    const seconds = Math.max(usage.seconds ?? 1, pricing.minimumSeconds ?? 1);
+                    return (seconds * parseFloat(pricing.pricePerSecond)).toFixed(6);
+                }
+                case 'per-job': {
+                    const base = parseFloat(pricing.basePrice);
+                    const unitCost = pricing.pricePerUnit
+                        ? (usage.units ?? 0) * parseFloat(pricing.pricePerUnit)
+                        : 0;
+                    return (base + unitCost).toFixed(6);
+                }
+                default:
+                    throw new Error(`Unknown pricing model: ${pricing.model}`);
+            }
+        },
+        getMinimumPayment() {
+            switch (pricing.model) {
+                case 'per-request':
+                    return pricing.pricePerRequest;
+                case 'per-second':
+                    return (parseFloat(pricing.pricePerSecond) * (pricing.minimumSeconds ?? 1)).toFixed(6);
+                case 'per-job':
+                    return pricing.basePrice;
+                default:
+                    return '0.000001';
+            }
+        },
+    };
+}
+//# sourceMappingURL=plans.js.map

package/dist/billing/plans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.js","sourceRoot":"","sources":["../../src/billing/plans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAwDH;;;;;GAKG;AACH,wFAAwF;AACxF,MAAM,UAAU,iBAAiB,CAAC,MAIjC;IACC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAE9C,OAAO;QACL,IAAI;QACJ,WAAW;QACX,OAAO;QAEP,aAAa,CAAC,KAAiB;YAC7B,QAAQ,OAAO,CAAC,KAAK,EAAE,CAAC;gBACtB,KAAK,aAAa,CAAC,CAAC,CAAC;oBACnB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;oBACrC,OAAO,CAAC,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBACrE,CAAC;gBAED,KAAK,YAAY,CAAC,CAAC,CAAC;oBAClB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CACtB,KAAK,CAAC,OAAO,IAAI,CAAC,EAClB,OAAO,CAAC,cAAc,IAAI,CAAC,CAC5B,CAAC;oBACF,OAAO,CAAC,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBACnE,CAAC;gBAED,KAAK,SAAS,CAAC,CAAC,CAAC;oBACf,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;oBAC3C,MAAM,QAAQ,GAAG,OAAO,CAAC,YAAY;wBACnC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC;wBACvD,CAAC,CAAC,CAAC,CAAC;oBACN,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBACtC,CAAC;gBAED;oBACE,MAAM,IAAI,KAAK,CAAC,0BAA2B,OAAwB,CAAC,KAAK,EAAE,CAAC,CAAC;YACjF,CAAC;QACH,CAAC;QAED,iBAAiB;YACf,QAAQ,OAAO,CAAC,KAAK,EAAE,CAAC;gBACtB,KAAK,aAAa;oBAChB,OAAO,OAAO,CAAC,eAAe,CAAC;gBACjC,KAAK,YAAY;oBACf,OAAO,CACL,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC,CACnE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBACf,KAAK,SAAS;oBACZ,OAAO,OAAO,CAAC,SAAS,CAAC;gBAC3B;oBACE,OAAO,UAAU,CAAC;YACtB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/client/buyer.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Buyer SDK for automated x402 payment flow.
+ *
+ * Handles the complete payment lifecycle:
+ * 1. Send request to a paywalled endpoint
+ * 2. Receive 402 + payment requirements
+ * 3. Sign EIP-3009 transferWithAuthorization
+ * 4. Retry request with X-PAYMENT header
+ *
+ * @example
+ * ```typescript
+ * import { BuyerClient } from '@resvary/sdk/client';
+ *
+ * const buyer = new BuyerClient({
+ *   privateKey: '0x...',
+ *   rpcUrl: 'https://rpc.testnet.arc.network',
+ * });
+ *
+ * const response = await buyer.request('https://api.example.com/premium/data');
+ * console.log(response.data);
+ * ```
+ */
+/** Configuration for the BuyerClient */
+export interface BuyerClientConfig {
+    /** Buyer's private key (hex string with 0x prefix) */
+    privateKey: `0x${string}`;
+    /** RPC URL for the target network (default: Arc Testnet) */
+    rpcUrl?: string;
+    /** Chain ID (default: Arc Testnet) */
+    chainId?: number;
+    /** Maximum number of payment retries */
+    maxRetries?: number;
+    /** Custom fetch implementation */
+    fetch?: typeof globalThis.fetch;
+}
+/** Response from a paid request */
+export interface PaidResponse<T = unknown> {
+    /** Response data */
+    data: T;
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Payment details (if payment was made) */
+    payment?: {
+        amount: string;
+        to: `0x${string}`;
+        network: string;
+    };
+}
+/**
+ * Client for consuming x402-paywalled APIs.
+ *
+ * Automatically handles the 402 payment flow: detects paywalled endpoints,
+ * signs payment authorizations, and retries requests with valid payments.
+ */
+export declare class BuyerClient {
+    private readonly account;
+    private readonly chainId;
+    private readonly fetchFn;
+    constructor(config: BuyerClientConfig);
+    /** Get the buyer's wallet address */
+    get address(): `0x${string}`;
+    /**
+     * Make a request to a potentially paywalled endpoint.
+     * Automatically handles 402 → sign → retry flow.
+     *
+     * @param url - The endpoint URL
+     * @param init - Optional fetch init options
+     * @returns Response with data and payment info
+     */
+    request<T = unknown>(url: string, init?: RequestInit): Promise<PaidResponse<T>>;
+    /**
+     * Parse payment requirements from a 402 response.
+     */
+    private parsePaymentRequirements;
+    /**
+     * Sign a payment authorization using EIP-3009.
+     */
+    private signPayment;
+}
+//# sourceMappingURL=buyer.d.ts.map

package/dist/client/buyer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buyer.d.ts","sourceRoot":"","sources":["../../src/client/buyer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,UAAU,EAAE,KAAK,MAAM,EAAE,CAAC;IAC1B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,mCAAmC;AACnC,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,oBAAoB;IACpB,IAAI,EAAE,CAAC,CAAC;IACR,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,4CAA4C;IAC5C,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,EAAE,EAAE,KAAK,MAAM,EAAE,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAEtC,MAAM,EAAE,iBAAiB;IAMrC,qCAAqC;IACrC,IAAI,OAAO,IAAI,KAAK,MAAM,EAAE,CAE3B;IAED;;;;;;;OAOG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAkD3B;;OAEG;YACW,wBAAwB;IAmBtC;;OAEG;YACW,WAAW;CA2D1B"}

package/dist/client/buyer.js

@@ -0,0 +1,168 @@
+/**
+ * Buyer SDK for automated x402 payment flow.
+ *
+ * Handles the complete payment lifecycle:
+ * 1. Send request to a paywalled endpoint
+ * 2. Receive 402 + payment requirements
+ * 3. Sign EIP-3009 transferWithAuthorization
+ * 4. Retry request with X-PAYMENT header
+ *
+ * @example
+ * ```typescript
+ * import { BuyerClient } from '@resvary/sdk/client';
+ *
+ * const buyer = new BuyerClient({
+ *   privateKey: '0x...',
+ *   rpcUrl: 'https://rpc.testnet.arc.network',
+ * });
+ *
+ * const response = await buyer.request('https://api.example.com/premium/data');
+ * console.log(response.data);
+ * ```
+ */
+import { privateKeyToAccount } from 'viem/accounts';
+import { ARC_TESTNET, DEFAULTS, HTTP_402, USDC_DECIMALS, X402_HEADER, PAYMENT_REQUIRED_HEADER } from '../constants.js';
+/**
+ * Client for consuming x402-paywalled APIs.
+ *
+ * Automatically handles the 402 payment flow: detects paywalled endpoints,
+ * signs payment authorizations, and retries requests with valid payments.
+ */
+export class BuyerClient {
+    account;
+    chainId;
+    fetchFn;
+    constructor(config) {
+        this.account = privateKeyToAccount(config.privateKey);
+        this.chainId = config.chainId ?? ARC_TESTNET.chainId;
+        this.fetchFn = config.fetch ?? globalThis.fetch;
+    }
+    /** Get the buyer's wallet address */
+    get address() {
+        return this.account.address;
+    }
+    /**
+     * Make a request to a potentially paywalled endpoint.
+     * Automatically handles 402 → sign → retry flow.
+     *
+     * @param url - The endpoint URL
+     * @param init - Optional fetch init options
+     * @returns Response with data and payment info
+     */
+    async request(url, init) {
+        // Initial request
+        const initialResponse = await this.fetchFn(url, init);
+        // If not 402, return directly
+        if (initialResponse.status !== HTTP_402) {
+            const data = await initialResponse.json();
+            return {
+                data,
+                status: initialResponse.status,
+                headers: Object.fromEntries(initialResponse.headers.entries()),
+            };
+        }
+        // Parse payment requirements from 402 response
+        const requirements = await this.parsePaymentRequirements(initialResponse);
+        if (!requirements) {
+            throw new Error('Received 402 but could not parse payment requirements');
+        }
+        // Sign the payment
+        const paymentPayload = await this.signPayment(requirements);
+        // Encode payment as base64
+        const encodedPayment = Buffer.from(JSON.stringify(paymentPayload)).toString('base64');
+        // Retry with payment header
+        const paidResponse = await this.fetchFn(url, {
+            ...init,
+            headers: {
+                ...init?.headers,
+                [X402_HEADER]: encodedPayment,
+            },
+        });
+        const data = await paidResponse.json();
+        return {
+            data,
+            status: paidResponse.status,
+            headers: Object.fromEntries(paidResponse.headers.entries()),
+            payment: {
+                amount: requirements.maxAmountRequired,
+                to: requirements.payTo,
+                network: requirements.network,
+            },
+        };
+    }
+    /**
+     * Parse payment requirements from a 402 response.
+     */
+    async parsePaymentRequirements(response) {
+        try {
+            // Try to get requirements from header
+            const headerValue = response.headers.get(PAYMENT_REQUIRED_HEADER);
+            if (headerValue) {
+                const decoded = Buffer.from(headerValue, 'base64').toString('utf-8');
+                return JSON.parse(decoded);
+            }
+            // Fallback: try to get from response body
+            const body = await response.json();
+            return body.requirements ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Sign a payment authorization using EIP-3009.
+     */
+    async signPayment(requirements) {
+        const now = Math.floor(Date.now() / 1000);
+        const nonce = `0x${Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('hex')}`;
+        const authorization = {
+            from: this.account.address,
+            to: requirements.payTo,
+            value: String(BigInt(Math.ceil(parseFloat(requirements.maxAmountRequired) * 10 ** USDC_DECIMALS))),
+            validAfter: String(now - 60), // Valid from 1 minute ago (clock skew buffer)
+            validBefore: String(now + DEFAULTS.paymentValiditySeconds),
+            nonce,
+        };
+        // Sign the authorization using EIP-712 typed data
+        if (!this.account.signTypedData) {
+            throw new Error('Account does not support signTypedData');
+        }
+        const signature = await this.account.signTypedData({
+            domain: {
+                name: 'USD Coin',
+                version: '2',
+                chainId: BigInt(this.chainId),
+                verifyingContract: ARC_TESTNET.usdcAddress,
+            },
+            types: {
+                TransferWithAuthorization: [
+                    { name: 'from', type: 'address' },
+                    { name: 'to', type: 'address' },
+                    { name: 'value', type: 'uint256' },
+                    { name: 'validAfter', type: 'uint256' },
+                    { name: 'validBefore', type: 'uint256' },
+                    { name: 'nonce', type: 'bytes32' },
+                ],
+            },
+            primaryType: 'TransferWithAuthorization',
+            message: {
+                from: authorization.from,
+                to: authorization.to,
+                value: BigInt(authorization.value),
+                validAfter: BigInt(authorization.validAfter),
+                validBefore: BigInt(authorization.validBefore),
+                nonce: authorization.nonce,
+            },
+        });
+        return {
+            x402Version: DEFAULTS.x402Version,
+            scheme: requirements.scheme ?? 'exact',
+            network: requirements.network,
+            payload: {
+                signature,
+                authorization,
+            },
+        };
+    }
+}
+//# sourceMappingURL=buyer.js.map