@parsrun/payments 0.1.0

package/dist/billing-service-LsAFesou.d.ts

@@ -0,0 +1,578 @@
+import { PaymentProvider, PaymentProviderType, Subscription, Customer, WebhookEventType, WebhookHandler } from './types.js';
+import { WebhookProcessResult } from './webhooks/index.js';
+
+/**
+ * @parsrun/payments - Billing Types
+ * Types for multi-provider billing service
+ */
+
+/**
+ * Supported regions for provider routing
+ */
+type BillingRegion = "TR" | "EU" | "US" | "UK" | "APAC" | "LATAM" | "GLOBAL" | string;
+/**
+ * Region detection result
+ */
+interface RegionDetectionResult {
+    /** Detected region code */
+    region: BillingRegion;
+    /** Country code (ISO 3166-1 alpha-2) */
+    countryCode?: string;
+    /** Detection method used */
+    method: "ip" | "customer" | "explicit" | "default";
+    /** Confidence level */
+    confidence: "high" | "medium" | "low";
+}
+/**
+ * Region detector function type
+ */
+type RegionDetector = (context: RegionDetectionContext) => BillingRegion | Promise<BillingRegion>;
+/**
+ * Context for region detection
+ */
+interface RegionDetectionContext {
+    /** Customer ID if available */
+    customerId?: string | undefined;
+    /** Customer email */
+    email?: string | undefined;
+    /** Explicit country code */
+    countryCode?: string | undefined;
+    /** IP address */
+    ipAddress?: string | undefined;
+    /** Request headers */
+    headers?: Record<string, string> | undefined;
+    /** Custom context data */
+    custom?: Record<string, unknown> | undefined;
+}
+/**
+ * Provider routing rule
+ */
+interface ProviderRoutingRule {
+    /** Regions this rule applies to */
+    regions: BillingRegion[];
+    /** Provider to use */
+    provider: PaymentProvider;
+    /** Priority (lower = higher priority) */
+    priority?: number;
+    /** Rule condition (optional) */
+    condition?: (context: RegionDetectionContext) => boolean;
+}
+/**
+ * Provider strategy configuration
+ */
+interface ProviderStrategyConfig {
+    /** Default provider (used when no region matches) */
+    default: PaymentProvider;
+    /**
+     * Region-based provider mapping
+     * @example { TR: iyzicoProvider, EU: stripeProvider }
+     */
+    regions?: Record<BillingRegion, PaymentProvider>;
+    /**
+     * Advanced routing rules (takes precedence over regions)
+     */
+    rules?: ProviderRoutingRule[];
+    /**
+     * Custom region detector
+     * Default: uses countryCode from context or "GLOBAL"
+     */
+    regionDetector?: RegionDetector;
+}
+/**
+ * Fallback configuration
+ */
+interface FallbackConfig {
+    /**
+     * Enable fallback to alternative providers
+     * @default false
+     *
+     * WARNING: Enable with caution! Fallback may cause:
+     * - Double charges if not handled properly
+     * - Inconsistent customer records across providers
+     * - Webhook handling complexity
+     *
+     * Recommended only for:
+     * - One-time payments (not subscriptions)
+     * - Idempotent operations
+     * - When you have proper reconciliation in place
+     */
+    enabled: boolean;
+    /**
+     * Fallback providers in order of preference
+     * If not specified, uses all configured providers except the failed one
+     */
+    providers?: PaymentProvider[];
+    /**
+     * Operations that allow fallback
+     * @default ["createCheckout"] - Only checkout is safe by default
+     */
+    allowedOperations?: FallbackOperation[];
+    /**
+     * Maximum fallback attempts
+     * @default 1
+     */
+    maxAttempts?: number;
+    /**
+     * Errors that should trigger fallback
+     * @default ["API_ERROR", "RATE_LIMITED", "PROVIDER_UNAVAILABLE"]
+     */
+    retryableErrors?: string[];
+    /**
+     * Callback when fallback is triggered
+     */
+    onFallback?: (context: FallbackContext) => void | Promise<void>;
+    /**
+     * Callback when all providers fail
+     */
+    onAllFailed?: (context: FallbackContext) => void | Promise<void>;
+}
+/**
+ * Operations that can trigger fallback
+ */
+type FallbackOperation = "createCheckout" | "createCustomer" | "createSubscription" | "createPayment";
+/**
+ * Fallback context for callbacks
+ */
+interface FallbackContext {
+    /** Operation that failed */
+    operation: FallbackOperation;
+    /** Original provider that failed */
+    originalProvider: PaymentProviderType;
+    /** Fallback provider being tried */
+    fallbackProvider?: PaymentProviderType;
+    /** Error that triggered fallback */
+    error: Error;
+    /** Attempt number */
+    attempt: number;
+    /** Total attempts made */
+    totalAttempts: number;
+    /** Whether all providers failed */
+    allFailed: boolean;
+}
+/**
+ * Billing service configuration
+ */
+interface BillingServiceConfig {
+    /**
+     * Provider strategy configuration
+     */
+    providers: ProviderStrategyConfig;
+    /**
+     * Fallback configuration
+     * @default { enabled: false }
+     */
+    fallback?: FallbackConfig;
+    /**
+     * Tenant ID for multi-tenant setups
+     */
+    tenantId?: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Custom logger
+     */
+    logger?: BillingLogger;
+    /**
+     * Webhook configuration
+     */
+    webhooks?: {
+        /**
+         * Normalize events from all providers to unified format
+         * @default true
+         */
+        normalize?: boolean;
+        /**
+         * Secret keys for each provider
+         */
+        secrets?: Partial<Record<PaymentProviderType, string>>;
+    };
+}
+/**
+ * Logger interface for billing service
+ */
+interface BillingLogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Subscribe options (high-level)
+ */
+interface SubscribeOptions {
+    /** Customer email */
+    email: string;
+    /** Customer name */
+    name?: string;
+    /** Plan/Price ID */
+    planId: string;
+    /** Success redirect URL */
+    successUrl: string;
+    /** Cancel redirect URL */
+    cancelUrl: string;
+    /** Trial days */
+    trialDays?: number;
+    /** Country code for region routing */
+    countryCode?: string;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+    /**
+     * Existing customer ID (skip customer creation)
+     */
+    customerId?: string;
+    /**
+     * Force specific provider (bypass region routing)
+     */
+    forceProvider?: PaymentProviderType;
+}
+/**
+ * Subscribe result
+ */
+interface SubscribeResult {
+    /** Checkout URL to redirect user */
+    checkoutUrl: string;
+    /** Checkout session ID */
+    sessionId: string;
+    /** Customer ID (created or existing) */
+    customerId: string;
+    /** Provider used */
+    provider: PaymentProviderType;
+    /** Region detected */
+    region: BillingRegion;
+}
+/**
+ * Cancel subscription options
+ */
+interface CancelOptions {
+    /** Subscription ID */
+    subscriptionId: string;
+    /** Cancel immediately or at period end */
+    immediate?: boolean;
+    /** Reason for cancellation */
+    reason?: string;
+    /** Provider (if known, for faster lookup) */
+    provider?: PaymentProviderType;
+}
+/**
+ * Cancel result
+ */
+interface CancelResult {
+    /** Subscription ID */
+    subscriptionId: string;
+    /** New status */
+    status: string;
+    /** When subscription will end */
+    endsAt: Date;
+    /** Provider used */
+    provider: PaymentProviderType;
+}
+/**
+ * Get subscription options
+ */
+interface GetSubscriptionOptions {
+    /** Customer ID */
+    customerId?: string;
+    /** Customer email (alternative to customerId) */
+    email?: string;
+    /** Specific subscription ID */
+    subscriptionId?: string;
+    /** Provider hint */
+    provider?: PaymentProviderType;
+}
+/**
+ * Subscription with provider info
+ */
+interface BillingSubscription extends Subscription {
+    /** Provider that manages this subscription */
+    provider: PaymentProviderType;
+}
+/**
+ * Customer with provider info
+ */
+interface BillingCustomer extends Customer {
+    /** Provider that manages this customer */
+    provider: PaymentProviderType;
+    /** Region */
+    region?: BillingRegion;
+}
+/**
+ * Provider selection result
+ */
+interface ProviderSelection {
+    /** Selected provider */
+    provider: PaymentProvider;
+    /** Provider type */
+    type: PaymentProviderType;
+    /** Region used for selection */
+    region: BillingRegion;
+    /** Selection reason */
+    reason: "region" | "rule" | "default" | "forced" | "fallback";
+}
+/**
+ * Billing error codes
+ */
+declare const BillingErrorCodes: {
+    readonly NO_PROVIDER_CONFIGURED: "NO_PROVIDER_CONFIGURED";
+    readonly PROVIDER_UNAVAILABLE: "PROVIDER_UNAVAILABLE";
+    readonly ALL_PROVIDERS_FAILED: "ALL_PROVIDERS_FAILED";
+    readonly REGION_NOT_SUPPORTED: "REGION_NOT_SUPPORTED";
+    readonly SUBSCRIPTION_NOT_FOUND: "SUBSCRIPTION_NOT_FOUND";
+    readonly CUSTOMER_NOT_FOUND: "CUSTOMER_NOT_FOUND";
+    readonly FALLBACK_DISABLED: "FALLBACK_DISABLED";
+    readonly OPERATION_NOT_ALLOWED: "OPERATION_NOT_ALLOWED";
+};
+type BillingErrorCode = keyof typeof BillingErrorCodes;
+/**
+ * Billing error
+ */
+declare class BillingError extends Error {
+    readonly code: BillingErrorCode;
+    readonly provider?: PaymentProviderType | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: BillingErrorCode, provider?: PaymentProviderType | undefined, cause?: Error | undefined);
+}
+
+/**
+ * @parsrun/payments - Billing Service
+ * High-level billing API with multi-provider support
+ */
+
+/**
+ * Billing Service
+ *
+ * High-level billing API with:
+ * - Multi-provider support (Stripe, Paddle, iyzico)
+ * - Region-based provider routing
+ * - Optional fallback mechanism
+ * - Unified webhook handling
+ *
+ * @example Basic usage
+ * ```typescript
+ * const billing = createBillingService({
+ *   providers: {
+ *     default: stripeProvider,
+ *     regions: {
+ *       TR: iyzicoProvider,
+ *       EU: stripeProvider,
+ *     },
+ *   },
+ * });
+ *
+ * // Subscribe a customer
+ * const result = await billing.subscribe({
+ *   email: "user@example.com",
+ *   planId: "price_xxx",
+ *   successUrl: "https://app.com/success",
+ *   cancelUrl: "https://app.com/cancel",
+ *   countryCode: "TR", // Will use iyzico
+ * });
+ *
+ * // Redirect to checkout
+ * redirect(result.checkoutUrl);
+ * ```
+ *
+ * @example With fallback (opt-in)
+ * ```typescript
+ * const billing = createBillingService({
+ *   providers: {
+ *     default: stripeProvider,
+ *     regions: { TR: iyzicoProvider },
+ *   },
+ *   fallback: {
+ *     enabled: true, // WARNING: Enable with caution
+ *     allowedOperations: ["createCheckout"],
+ *     maxAttempts: 1,
+ *     onFallback: (ctx) => {
+ *       logger.warn("Payment fallback triggered", ctx);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare class BillingService {
+    private readonly strategy;
+    private readonly fallback;
+    private readonly webhookRegistry;
+    private readonly webhookProcessors;
+    private readonly logger;
+    private readonly tenantId;
+    private readonly debug;
+    constructor(config: BillingServiceConfig);
+    /**
+     * Subscribe a customer to a plan
+     *
+     * This is the recommended way to handle subscriptions:
+     * 1. Creates or retrieves customer
+     * 2. Selects provider based on region
+     * 3. Creates checkout session
+     * 4. Returns checkout URL for redirect
+     *
+     * @example
+     * ```typescript
+     * const { checkoutUrl } = await billing.subscribe({
+     *   email: "user@example.com",
+     *   planId: "price_monthly",
+     *   successUrl: "https://app.com/success",
+     *   cancelUrl: "https://app.com/cancel",
+     *   countryCode: "TR",
+     * });
+     * redirect(checkoutUrl);
+     * ```
+     */
+    subscribe(options: SubscribeOptions): Promise<SubscribeResult>;
+    /**
+     * Cancel a subscription
+     *
+     * @example
+     * ```typescript
+     * const result = await billing.cancel({
+     *   subscriptionId: "sub_xxx",
+     *   immediate: false, // Cancel at period end
+     * });
+     * ```
+     */
+    cancel(options: CancelOptions): Promise<CancelResult>;
+    /**
+     * Get subscription(s) for a customer
+     *
+     * @example
+     * ```typescript
+     * // Get by customer ID
+     * const subs = await billing.getSubscriptions({ customerId: "cus_xxx" });
+     *
+     * // Get specific subscription
+     * const sub = await billing.getSubscription({ subscriptionId: "sub_xxx" });
+     * ```
+     */
+    getSubscriptions(options: GetSubscriptionOptions): Promise<BillingSubscription[]>;
+    /**
+     * Get a single subscription
+     */
+    getSubscription(options: GetSubscriptionOptions): Promise<BillingSubscription | null>;
+    /**
+     * Get customer by ID
+     */
+    getCustomer(customerId: string, provider?: PaymentProviderType): Promise<BillingCustomer | null>;
+    /**
+     * Create a customer portal session
+     */
+    createPortalSession(customerId: string, returnUrl: string, provider?: PaymentProviderType): Promise<{
+        url: string;
+        provider: PaymentProviderType;
+    }>;
+    /**
+     * Select provider for a region/context
+     */
+    selectProvider(context: RegionDetectionContext, forceProvider?: PaymentProviderType): Promise<ProviderSelection>;
+    /**
+     * Get all configured providers
+     */
+    getProviders(): PaymentProvider[];
+    /**
+     * Get provider by type
+     */
+    getProvider(type: PaymentProviderType): PaymentProvider | undefined;
+    /**
+     * Get supported regions
+     */
+    getSupportedRegions(): BillingRegion[];
+    /**
+     * Register webhook handler for all providers
+     *
+     * @example
+     * ```typescript
+     * billing.onWebhook("subscription.created", async (event) => {
+     *   console.log(`New subscription from ${event.provider}:`, event.data);
+     * });
+     *
+     * // Handle all events
+     * billing.onWebhook("*", async (event) => {
+     *   await saveToAuditLog(event);
+     * });
+     * ```
+     */
+    onWebhook(type: WebhookEventType | "*", handler: WebhookHandler): this;
+    /**
+     * Handle webhook request
+     *
+     * @example
+     * ```typescript
+     * app.post("/webhooks/:provider", async (c) => {
+     *   const provider = c.req.param("provider") as PaymentProviderType;
+     *   const result = await billing.handleWebhook(c.req.raw, provider);
+     *   return c.json({ received: result.success });
+     * });
+     * ```
+     */
+    handleWebhook(request: Request, provider: PaymentProviderType): Promise<WebhookProcessResult>;
+    /**
+     * Handle raw webhook payload
+     */
+    handleWebhookRaw(payload: string | Uint8Array, signature: string, provider: PaymentProviderType): Promise<WebhookProcessResult>;
+    /**
+     * Execute operation on specific provider
+     *
+     * Use this for advanced operations not covered by high-level API
+     *
+     * @example
+     * ```typescript
+     * const prices = await billing.withProvider("stripe", async (provider) => {
+     *   return provider.listPrices?.("prod_xxx") ?? [];
+     * });
+     * ```
+     */
+    withProvider<T>(type: PaymentProviderType, operation: (provider: PaymentProvider) => Promise<T>): Promise<T>;
+    /**
+     * Execute operation with fallback support
+     */
+    private executeWithFallback;
+    /**
+     * Find which provider owns a subscription
+     */
+    private findSubscriptionProvider;
+    /**
+     * Find which provider owns a customer
+     */
+    private findCustomerProvider;
+}
+/**
+ * Create billing service
+ *
+ * @example
+ * ```typescript
+ * import { createBillingService, createStripeProvider, createIyzicoProvider } from "@parsrun/payments";
+ *
+ * const stripeProvider = createStripeProvider({
+ *   secretKey: process.env.STRIPE_SECRET_KEY!,
+ *   webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+ * });
+ *
+ * const iyzicoProvider = createIyzicoProvider({
+ *   apiKey: process.env.IYZICO_API_KEY!,
+ *   secretKey: process.env.IYZICO_SECRET_KEY!,
+ *   baseUrl: "https://api.iyzipay.com",
+ * });
+ *
+ * const billing = createBillingService({
+ *   providers: {
+ *     default: stripeProvider,
+ *     regions: {
+ *       TR: iyzicoProvider,
+ *       EU: stripeProvider,
+ *       US: stripeProvider,
+ *     },
+ *   },
+ *   fallback: {
+ *     enabled: false, // Disabled by default - enable with caution!
+ *   },
+ *   debug: process.env.NODE_ENV === "development",
+ * });
+ *
+ * export { billing };
+ * ```
+ */
+declare function createBillingService(config: BillingServiceConfig): BillingService;
+
+export { BillingService as B, type CancelOptions as C, type FallbackConfig as F, type GetSubscriptionOptions as G, type ProviderRoutingRule as P, type RegionDetectionResult as R, type SubscribeOptions as S, BillingError as a, BillingErrorCodes as b, createBillingService as c, type BillingRegion as d, type RegionDetector as e, type RegionDetectionContext as f, type ProviderStrategyConfig as g, type FallbackOperation as h, type FallbackContext as i, type BillingServiceConfig as j, type BillingLogger as k, type SubscribeResult as l, type CancelResult as m, type BillingSubscription as n, type BillingCustomer as o, type ProviderSelection as p, type BillingErrorCode as q };