@autopayprotocol/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,295 @@
+type IntervalPreset = 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'yearly';
+interface CheckoutOptions {
+    /** Merchant wallet address (0x-prefixed, 40 hex chars) */
+    merchant: string;
+    /** Charge amount in human-readable USDC (e.g. 9.99) */
+    amount: number;
+    /** Billing interval — preset string, or seconds */
+    interval: IntervalPreset | number;
+    /** URL to plan metadata JSON */
+    metadataUrl: string;
+    /** Redirect URL on successful subscription */
+    successUrl: string;
+    /** Redirect URL on cancel */
+    cancelUrl: string;
+    /** Optional spending cap in human-readable USDC. Omit for unlimited. */
+    spendingCap?: number;
+    /** Optional base URL override (default: https://app.autopay.xyz) */
+    baseUrl?: string;
+}
+interface SuccessRedirect {
+    policyId: string;
+    txHash: string;
+}
+type WebhookEventType = 'charge.succeeded' | 'charge.failed' | 'policy.created' | 'policy.revoked' | 'policy.cancelled_by_failure';
+interface WebhookBase {
+    timestamp: string;
+    data: {
+        policyId: string;
+        chainId: number;
+        payer: string;
+        merchant: string;
+    };
+}
+interface ChargeSucceededEvent extends WebhookBase {
+    type: 'charge.succeeded';
+    data: WebhookBase['data'] & {
+        amount: string;
+        protocolFee: string;
+        txHash: string;
+    };
+}
+interface ChargeFailedEvent extends WebhookBase {
+    type: 'charge.failed';
+    data: WebhookBase['data'] & {
+        reason: string;
+    };
+}
+interface PolicyCreatedEvent extends WebhookBase {
+    type: 'policy.created';
+    data: WebhookBase['data'] & {
+        chargeAmount: string;
+        interval: number;
+        spendingCap: string;
+        metadataUrl: string;
+    };
+}
+interface PolicyRevokedEvent extends WebhookBase {
+    type: 'policy.revoked';
+    data: WebhookBase['data'] & {
+        endTime: number;
+    };
+}
+interface PolicyCancelledByFailureEvent extends WebhookBase {
+    type: 'policy.cancelled_by_failure';
+    data: WebhookBase['data'] & {
+        consecutiveFailures: number;
+        endTime: number;
+    };
+}
+type WebhookEvent = ChargeSucceededEvent | ChargeFailedEvent | PolicyCreatedEvent | PolicyRevokedEvent | PolicyCancelledByFailureEvent;
+interface CheckoutMetadata {
+    version: string;
+    plan: {
+        name: string;
+        description: string;
+        tier?: string;
+        features?: string[];
+    };
+    merchant: {
+        name: string;
+        logo?: string;
+        website?: string;
+        supportEmail?: string;
+    };
+    display?: {
+        color?: string;
+        badge?: string;
+    };
+}
+interface FeeBreakdown {
+    /** Total charge in human-readable USDC (e.g. "9.99") */
+    total: string;
+    /** Amount merchant receives after fee */
+    merchantReceives: string;
+    /** Protocol fee deducted */
+    protocolFee: string;
+    /** Fee as percentage string (e.g. "2.5%") */
+    feePercentage: string;
+}
+
+declare class AutoPayError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare class AutoPayWebhookError extends AutoPayError {
+    constructor(message: string);
+}
+declare class AutoPayCheckoutError extends AutoPayError {
+    constructor(message: string);
+}
+declare class AutoPayMetadataError extends AutoPayError {
+    constructor(message: string);
+}
+
+declare const intervals: {
+    /** 1 minute — useful for testing */
+    readonly minute: 60;
+    /** 7 days */
+    readonly weekly: 604800;
+    /** 14 days */
+    readonly biweekly: 1209600;
+    /** 30 days */
+    readonly monthly: 2592000;
+    /** 90 days */
+    readonly quarterly: 7776000;
+    /** 365 days */
+    readonly yearly: 31536000;
+    /** Build a custom interval from a count and unit */
+    readonly custom: (count: number, unit: "minutes" | "hours" | "days" | "months" | "years") => number;
+};
+/** Protocol fee in basis points (2.5%) */
+declare const PROTOCOL_FEE_BPS = 250;
+/** USDC uses 6 decimals */
+declare const USDC_DECIMALS = 6;
+/** Minimum interval (1 minute) */
+declare const MIN_INTERVAL = 60;
+/** Maximum interval (365 days) */
+declare const MAX_INTERVAL = 31536000;
+/** Max consecutive failures before auto-cancel */
+declare const MAX_RETRIES = 3;
+interface ChainConfig {
+    name: string;
+    chainId: number;
+    cctpDomain: number;
+    usdc: string;
+    explorer: string;
+}
+declare const chains: Record<string, ChainConfig>;
+/** Default checkout base URL */
+declare const DEFAULT_CHECKOUT_BASE_URL = "https://app.autopay.xyz";
+
+/** Resolve an interval preset or number to seconds */
+declare function resolveInterval(interval: IntervalPreset | number): number;
+/**
+ * Build a checkout URL that a merchant can redirect users to.
+ *
+ * @example
+ * ```ts
+ * const url = createCheckoutUrl({
+ *   merchant: '0x2B8b...',
+ *   amount: 9.99,
+ *   interval: 'monthly',
+ *   metadataUrl: 'https://mysite.com/plans/pro.json',
+ *   successUrl: 'https://mysite.com/success',
+ *   cancelUrl: 'https://mysite.com/cancel',
+ * })
+ * ```
+ */
+declare function createCheckoutUrl(options: CheckoutOptions): string;
+/**
+ * Parse the query params from the success redirect URL.
+ *
+ * After a user subscribes, they are redirected to the merchant's `successUrl`
+ * with `?policyId=0x...&txHash=0x...` appended.
+ *
+ * @example
+ * ```ts
+ * // On your success page:
+ * const { policyId, txHash } = parseSuccessRedirect(window.location.search)
+ * ```
+ */
+declare function parseSuccessRedirect(queryString: string): SuccessRedirect;
+
+/**
+ * Sign a payload string with HMAC-SHA256.
+ * Used by the relayer — exposed here so merchants can test locally.
+ */
+declare function signPayload(payload: string, secret: string): string;
+/**
+ * Verify an HMAC-SHA256 signature using constant-time comparison.
+ */
+declare function verifySignature(payload: string, signature: string, secret: string): boolean;
+/**
+ * Verify and parse a webhook from AutoPay.
+ *
+ * @param rawBody  - The raw request body string (JSON.stringify of the body)
+ * @param signature - The `x-autopay-signature` header value
+ * @param secret   - Your webhook secret
+ * @returns A fully-typed {@link WebhookEvent} with discriminated union on `type`
+ *
+ * @example
+ * ```ts
+ * const event = verifyWebhook(rawBody, req.headers['x-autopay-signature'], secret)
+ * if (event.type === 'charge.succeeded') {
+ *   console.log(event.data.amount) // TypeScript knows this exists
+ * }
+ * ```
+ */
+declare function verifyWebhook(rawBody: string, signature: string | undefined, secret: string): WebhookEvent;
+
+/**
+ * Format a raw USDC amount (6-decimal string) to a human-readable string.
+ *
+ * @example
+ * ```ts
+ * formatUSDC('9990000') // "9.99"
+ * formatUSDC('100000')  // "0.10"
+ * ```
+ */
+declare function formatUSDC(rawAmount: string): string;
+/**
+ * Parse a human-readable USDC amount to a raw 6-decimal string.
+ *
+ * @example
+ * ```ts
+ * parseUSDC(9.99)  // "9990000"
+ * parseUSDC(0.10)  // "100000"
+ * ```
+ */
+declare function parseUSDC(amount: number): string;
+/**
+ * Calculate the fee breakdown for a charge amount.
+ *
+ * @param rawAmount - Raw USDC amount (6-decimal string) OR human-readable number
+ *
+ * @example
+ * ```ts
+ * calculateFeeBreakdown('9990000')
+ * // { total: "9.99", merchantReceives: "9.74", protocolFee: "0.25", feePercentage: "2.5%" }
+ * ```
+ */
+declare function calculateFeeBreakdown(rawAmount: string): FeeBreakdown;
+/**
+ * Format an interval in seconds to a human-readable label.
+ *
+ * @example
+ * ```ts
+ * formatInterval(2592000)  // "monthly"
+ * formatInterval(604800)   // "weekly"
+ * formatInterval(86400)    // "1 day"
+ * formatInterval(172800)   // "2 days"
+ * ```
+ */
+declare function formatInterval(seconds: number): string;
+
+interface MetadataValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate a metadata JSON object against the AutoPay metadata schema.
+ *
+ * @example
+ * ```ts
+ * const { valid, errors } = validateMetadata(jsonData)
+ * if (!valid) console.error(errors)
+ * ```
+ */
+declare function validateMetadata(data: unknown): MetadataValidationResult;
+/**
+ * Create a valid metadata object with sensible defaults.
+ *
+ * @example
+ * ```ts
+ * const metadata = createMetadata({
+ *   planName: 'Pro',
+ *   planDescription: 'All premium features',
+ *   merchantName: 'Acme Corp',
+ * })
+ * ```
+ */
+declare function createMetadata(options: {
+    planName: string;
+    planDescription: string;
+    merchantName: string;
+    tier?: string;
+    features?: string[];
+    logo?: string;
+    website?: string;
+    supportEmail?: string;
+    color?: string;
+    badge?: string;
+}): CheckoutMetadata;
+
+export { AutoPayCheckoutError, AutoPayError, AutoPayMetadataError, AutoPayWebhookError, type ChainConfig, type ChargeFailedEvent, type ChargeSucceededEvent, type CheckoutMetadata, type CheckoutOptions, DEFAULT_CHECKOUT_BASE_URL, type FeeBreakdown, type IntervalPreset, MAX_INTERVAL, MAX_RETRIES, MIN_INTERVAL, type MetadataValidationResult, PROTOCOL_FEE_BPS, type PolicyCancelledByFailureEvent, type PolicyCreatedEvent, type PolicyRevokedEvent, type SuccessRedirect, USDC_DECIMALS, type WebhookEvent, type WebhookEventType, calculateFeeBreakdown, chains, createCheckoutUrl, createMetadata, formatInterval, formatUSDC, intervals, parseSuccessRedirect, parseUSDC, resolveInterval, signPayload, validateMetadata, verifySignature, verifyWebhook };

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+type IntervalPreset = 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'yearly';
+interface CheckoutOptions {
+    /** Merchant wallet address (0x-prefixed, 40 hex chars) */
+    merchant: string;
+    /** Charge amount in human-readable USDC (e.g. 9.99) */
+    amount: number;
+    /** Billing interval — preset string, or seconds */
+    interval: IntervalPreset | number;
+    /** URL to plan metadata JSON */
+    metadataUrl: string;
+    /** Redirect URL on successful subscription */
+    successUrl: string;
+    /** Redirect URL on cancel */
+    cancelUrl: string;
+    /** Optional spending cap in human-readable USDC. Omit for unlimited. */
+    spendingCap?: number;
+    /** Optional base URL override (default: https://app.autopay.xyz) */
+    baseUrl?: string;
+}
+interface SuccessRedirect {
+    policyId: string;
+    txHash: string;
+}
+type WebhookEventType = 'charge.succeeded' | 'charge.failed' | 'policy.created' | 'policy.revoked' | 'policy.cancelled_by_failure';
+interface WebhookBase {
+    timestamp: string;
+    data: {
+        policyId: string;
+        chainId: number;
+        payer: string;
+        merchant: string;
+    };
+}
+interface ChargeSucceededEvent extends WebhookBase {
+    type: 'charge.succeeded';
+    data: WebhookBase['data'] & {
+        amount: string;
+        protocolFee: string;
+        txHash: string;
+    };
+}
+interface ChargeFailedEvent extends WebhookBase {
+    type: 'charge.failed';
+    data: WebhookBase['data'] & {
+        reason: string;
+    };
+}
+interface PolicyCreatedEvent extends WebhookBase {
+    type: 'policy.created';
+    data: WebhookBase['data'] & {
+        chargeAmount: string;
+        interval: number;
+        spendingCap: string;
+        metadataUrl: string;
+    };
+}
+interface PolicyRevokedEvent extends WebhookBase {
+    type: 'policy.revoked';
+    data: WebhookBase['data'] & {
+        endTime: number;
+    };
+}
+interface PolicyCancelledByFailureEvent extends WebhookBase {
+    type: 'policy.cancelled_by_failure';
+    data: WebhookBase['data'] & {
+        consecutiveFailures: number;
+        endTime: number;
+    };
+}
+type WebhookEvent = ChargeSucceededEvent | ChargeFailedEvent | PolicyCreatedEvent | PolicyRevokedEvent | PolicyCancelledByFailureEvent;
+interface CheckoutMetadata {
+    version: string;
+    plan: {
+        name: string;
+        description: string;
+        tier?: string;
+        features?: string[];
+    };
+    merchant: {
+        name: string;
+        logo?: string;
+        website?: string;
+        supportEmail?: string;
+    };
+    display?: {
+        color?: string;
+        badge?: string;
+    };
+}
+interface FeeBreakdown {
+    /** Total charge in human-readable USDC (e.g. "9.99") */
+    total: string;
+    /** Amount merchant receives after fee */
+    merchantReceives: string;
+    /** Protocol fee deducted */
+    protocolFee: string;
+    /** Fee as percentage string (e.g. "2.5%") */
+    feePercentage: string;
+}
+
+declare class AutoPayError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare class AutoPayWebhookError extends AutoPayError {
+    constructor(message: string);
+}
+declare class AutoPayCheckoutError extends AutoPayError {
+    constructor(message: string);
+}
+declare class AutoPayMetadataError extends AutoPayError {
+    constructor(message: string);
+}
+
+declare const intervals: {
+    /** 1 minute — useful for testing */
+    readonly minute: 60;
+    /** 7 days */
+    readonly weekly: 604800;
+    /** 14 days */
+    readonly biweekly: 1209600;
+    /** 30 days */
+    readonly monthly: 2592000;
+    /** 90 days */
+    readonly quarterly: 7776000;
+    /** 365 days */
+    readonly yearly: 31536000;
+    /** Build a custom interval from a count and unit */
+    readonly custom: (count: number, unit: "minutes" | "hours" | "days" | "months" | "years") => number;
+};
+/** Protocol fee in basis points (2.5%) */
+declare const PROTOCOL_FEE_BPS = 250;
+/** USDC uses 6 decimals */
+declare const USDC_DECIMALS = 6;
+/** Minimum interval (1 minute) */
+declare const MIN_INTERVAL = 60;
+/** Maximum interval (365 days) */
+declare const MAX_INTERVAL = 31536000;
+/** Max consecutive failures before auto-cancel */
+declare const MAX_RETRIES = 3;
+interface ChainConfig {
+    name: string;
+    chainId: number;
+    cctpDomain: number;
+    usdc: string;
+    explorer: string;
+}
+declare const chains: Record<string, ChainConfig>;
+/** Default checkout base URL */
+declare const DEFAULT_CHECKOUT_BASE_URL = "https://app.autopay.xyz";
+
+/** Resolve an interval preset or number to seconds */
+declare function resolveInterval(interval: IntervalPreset | number): number;
+/**
+ * Build a checkout URL that a merchant can redirect users to.
+ *
+ * @example
+ * ```ts
+ * const url = createCheckoutUrl({
+ *   merchant: '0x2B8b...',
+ *   amount: 9.99,
+ *   interval: 'monthly',
+ *   metadataUrl: 'https://mysite.com/plans/pro.json',
+ *   successUrl: 'https://mysite.com/success',
+ *   cancelUrl: 'https://mysite.com/cancel',
+ * })
+ * ```
+ */
+declare function createCheckoutUrl(options: CheckoutOptions): string;
+/**
+ * Parse the query params from the success redirect URL.
+ *
+ * After a user subscribes, they are redirected to the merchant's `successUrl`
+ * with `?policyId=0x...&txHash=0x...` appended.
+ *
+ * @example
+ * ```ts
+ * // On your success page:
+ * const { policyId, txHash } = parseSuccessRedirect(window.location.search)
+ * ```
+ */
+declare function parseSuccessRedirect(queryString: string): SuccessRedirect;
+
+/**
+ * Sign a payload string with HMAC-SHA256.
+ * Used by the relayer — exposed here so merchants can test locally.
+ */
+declare function signPayload(payload: string, secret: string): string;
+/**
+ * Verify an HMAC-SHA256 signature using constant-time comparison.
+ */
+declare function verifySignature(payload: string, signature: string, secret: string): boolean;
+/**
+ * Verify and parse a webhook from AutoPay.
+ *
+ * @param rawBody  - The raw request body string (JSON.stringify of the body)
+ * @param signature - The `x-autopay-signature` header value
+ * @param secret   - Your webhook secret
+ * @returns A fully-typed {@link WebhookEvent} with discriminated union on `type`
+ *
+ * @example
+ * ```ts
+ * const event = verifyWebhook(rawBody, req.headers['x-autopay-signature'], secret)
+ * if (event.type === 'charge.succeeded') {
+ *   console.log(event.data.amount) // TypeScript knows this exists
+ * }
+ * ```
+ */
+declare function verifyWebhook(rawBody: string, signature: string | undefined, secret: string): WebhookEvent;
+
+/**
+ * Format a raw USDC amount (6-decimal string) to a human-readable string.
+ *
+ * @example
+ * ```ts
+ * formatUSDC('9990000') // "9.99"
+ * formatUSDC('100000')  // "0.10"
+ * ```
+ */
+declare function formatUSDC(rawAmount: string): string;
+/**
+ * Parse a human-readable USDC amount to a raw 6-decimal string.
+ *
+ * @example
+ * ```ts
+ * parseUSDC(9.99)  // "9990000"
+ * parseUSDC(0.10)  // "100000"
+ * ```
+ */
+declare function parseUSDC(amount: number): string;
+/**
+ * Calculate the fee breakdown for a charge amount.
+ *
+ * @param rawAmount - Raw USDC amount (6-decimal string) OR human-readable number
+ *
+ * @example
+ * ```ts
+ * calculateFeeBreakdown('9990000')
+ * // { total: "9.99", merchantReceives: "9.74", protocolFee: "0.25", feePercentage: "2.5%" }
+ * ```
+ */
+declare function calculateFeeBreakdown(rawAmount: string): FeeBreakdown;
+/**
+ * Format an interval in seconds to a human-readable label.
+ *
+ * @example
+ * ```ts
+ * formatInterval(2592000)  // "monthly"
+ * formatInterval(604800)   // "weekly"
+ * formatInterval(86400)    // "1 day"
+ * formatInterval(172800)   // "2 days"
+ * ```
+ */
+declare function formatInterval(seconds: number): string;
+
+interface MetadataValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate a metadata JSON object against the AutoPay metadata schema.
+ *
+ * @example
+ * ```ts
+ * const { valid, errors } = validateMetadata(jsonData)
+ * if (!valid) console.error(errors)
+ * ```
+ */
+declare function validateMetadata(data: unknown): MetadataValidationResult;
+/**
+ * Create a valid metadata object with sensible defaults.
+ *
+ * @example
+ * ```ts
+ * const metadata = createMetadata({
+ *   planName: 'Pro',
+ *   planDescription: 'All premium features',
+ *   merchantName: 'Acme Corp',
+ * })
+ * ```
+ */
+declare function createMetadata(options: {
+    planName: string;
+    planDescription: string;
+    merchantName: string;
+    tier?: string;
+    features?: string[];
+    logo?: string;
+    website?: string;
+    supportEmail?: string;
+    color?: string;
+    badge?: string;
+}): CheckoutMetadata;
+
+export { AutoPayCheckoutError, AutoPayError, AutoPayMetadataError, AutoPayWebhookError, type ChainConfig, type ChargeFailedEvent, type ChargeSucceededEvent, type CheckoutMetadata, type CheckoutOptions, DEFAULT_CHECKOUT_BASE_URL, type FeeBreakdown, type IntervalPreset, MAX_INTERVAL, MAX_RETRIES, MIN_INTERVAL, type MetadataValidationResult, PROTOCOL_FEE_BPS, type PolicyCancelledByFailureEvent, type PolicyCreatedEvent, type PolicyRevokedEvent, type SuccessRedirect, USDC_DECIMALS, type WebhookEvent, type WebhookEventType, calculateFeeBreakdown, chains, createCheckoutUrl, createMetadata, formatInterval, formatUSDC, intervals, parseSuccessRedirect, parseUSDC, resolveInterval, signPayload, validateMetadata, verifySignature, verifyWebhook };