@dotdo/do 0.1.0

package/dist/do/business/financial/payments.d.ts

@@ -0,0 +1,397 @@
+/**
+ * Payment Processing
+ *
+ * Handles payment lifecycle including:
+ * - Payment intent creation
+ * - Authorization and capture
+ * - Refunds (full and partial)
+ * - Platform fees and transfers
+ *
+ * @module financial/payments
+ */
+import type { Payment, PaymentOptions, ListPaymentsOptions, Transfer, Payout, ApplicationFee, PlatformFeeConfig } from '../../../types/financial';
+/**
+ * Configuration for payment processing
+ */
+export interface PaymentProcessorConfig {
+    /** Stripe secret API key */
+    secretKey: string;
+    /** Default currency (ISO 4217) */
+    defaultCurrency?: string;
+    /** Platform fee configuration */
+    platformFee?: PlatformFeeConfig;
+    /** Statement descriptor prefix */
+    statementDescriptorPrefix?: string;
+}
+/**
+ * Options for creating a payment intent
+ */
+export interface CreatePaymentOptions extends PaymentOptions {
+    /** Capture method (automatic or manual) */
+    captureMethod?: 'automatic' | 'manual';
+    /** Confirmation method */
+    confirmationMethod?: 'automatic' | 'manual';
+    /** Setup future usage */
+    setupFutureUsage?: 'on_session' | 'off_session';
+    /** Statement descriptor */
+    statementDescriptor?: string;
+    /** Receipt email */
+    receiptEmail?: string;
+}
+/**
+ * Options for refunding a payment
+ */
+export interface RefundOptions {
+    /** Refund amount (partial refund if less than payment amount) */
+    amount?: number;
+    /** Reason for refund */
+    reason?: 'duplicate' | 'fraudulent' | 'requested_by_customer';
+    /** Refund metadata */
+    metadata?: Record<string, string>;
+    /** Reverse the transfer to connected account */
+    reverseTransfer?: boolean;
+    /** Refund the application fee */
+    refundApplicationFee?: boolean;
+}
+/**
+ * Options for creating a transfer
+ */
+export interface CreateTransferOptions {
+    /** Description */
+    description?: string;
+    /** Transfer group for linking transfers */
+    transferGroup?: string;
+    /** Source transaction (charge ID) */
+    sourceTransaction?: string;
+    /** Metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for creating a payout
+ */
+export interface CreatePayoutOptions {
+    /** Payout method */
+    method?: 'standard' | 'instant';
+    /** Description */
+    description?: string;
+    /** Statement descriptor */
+    statementDescriptor?: string;
+    /** Metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Payment processor for Digital Objects
+ *
+ * Manages the full payment lifecycle including creation, capture,
+ * refunds, and integration with Stripe Connect for multi-party payments.
+ *
+ * @example
+ * ```typescript
+ * const processor = new PaymentProcessor({
+ *   secretKey: env.STRIPE_SECRET_KEY,
+ *   platformFee: { type: 'percentage', percentage: 10 }
+ * })
+ *
+ * // Create a payment
+ * const payment = await processor.createPayment(1000, 'usd', {
+ *   customerRef: 'https://example.com/customers/123',
+ *   transferDestination: 'acct_xxx'
+ * })
+ *
+ * // Capture after authorization
+ * await processor.capturePayment(payment.id)
+ * ```
+ */
+export declare class PaymentProcessor {
+    private readonly config;
+    /**
+     * Create a new PaymentProcessor instance
+     *
+     * @param config - Payment processor configuration
+     */
+    constructor(config: PaymentProcessorConfig);
+    /**
+     * Create a new payment intent
+     *
+     * Creates a Stripe PaymentIntent with optional platform fee and
+     * transfer to a connected account.
+     *
+     * @param amount - Amount in smallest currency unit (e.g., cents)
+     * @param currency - ISO 4217 currency code
+     * @param options - Additional payment options
+     * @returns The created payment
+     *
+     * @example
+     * ```typescript
+     * // Simple payment
+     * const payment = await processor.createPayment(1000, 'usd')
+     *
+     * // Payment with platform fee and transfer
+     * const payment = await processor.createPayment(1000, 'usd', {
+     *   applicationFeeAmount: 100,
+     *   transferDestination: 'acct_xxx'
+     * })
+     * ```
+     */
+    createPayment(amount: number, currency: string, options?: CreatePaymentOptions): Promise<Payment>;
+    /**
+     * Retrieve a payment by ID
+     *
+     * @param paymentId - The payment ID
+     * @returns The payment or null if not found
+     */
+    getPayment(paymentId: string): Promise<Payment | null>;
+    /**
+     * Update a payment intent
+     *
+     * Can only update payments that haven't been confirmed.
+     *
+     * @param paymentId - The payment ID
+     * @param updates - Fields to update
+     * @returns The updated payment
+     */
+    updatePayment(paymentId: string, updates: Partial<CreatePaymentOptions>): Promise<Payment>;
+    /**
+     * Confirm a payment intent
+     *
+     * @param paymentId - The payment ID
+     * @param paymentMethodId - Payment method to use
+     * @returns The confirmed payment
+     */
+    confirmPayment(paymentId: string, paymentMethodId?: string): Promise<Payment>;
+    /**
+     * Capture a payment that was authorized
+     *
+     * For payments created with capture_method: 'manual', this
+     * captures the funds after authorization.
+     *
+     * @param paymentId - The payment ID
+     * @param amount - Amount to capture (partial capture if less than authorized)
+     * @returns The captured payment
+     *
+     * @example
+     * ```typescript
+     * // Full capture
+     * await processor.capturePayment(paymentId)
+     *
+     * // Partial capture
+     * await processor.capturePayment(paymentId, 500)
+     * ```
+     */
+    capturePayment(paymentId: string, amount?: number): Promise<Payment>;
+    /**
+     * Cancel a payment intent
+     *
+     * @param paymentId - The payment ID
+     * @param cancellationReason - Reason for cancellation
+     * @returns The canceled payment
+     */
+    cancelPayment(paymentId: string, cancellationReason?: string): Promise<Payment>;
+    /**
+     * Refund a payment
+     *
+     * Supports full and partial refunds, with optional application
+     * fee refund and transfer reversal for Connect payments.
+     *
+     * @param paymentId - The payment ID
+     * @param options - Refund options
+     * @returns The updated payment with refund amount
+     *
+     * @example
+     * ```typescript
+     * // Full refund
+     * await processor.refundPayment(paymentId)
+     *
+     * // Partial refund with reason
+     * await processor.refundPayment(paymentId, {
+     *   amount: 500,
+     *   reason: 'requested_by_customer'
+     * })
+     * ```
+     */
+    refundPayment(paymentId: string, options?: RefundOptions): Promise<Payment>;
+    /**
+     * List payments with filtering
+     *
+     * @param options - Filter and pagination options
+     * @returns List of payments
+     *
+     * @example
+     * ```typescript
+     * // Get recent successful payments
+     * const payments = await processor.listPayments({
+     *   status: 'succeeded',
+     *   limit: 10
+     * })
+     *
+     * // Get payments for a customer
+     * const payments = await processor.listPayments({
+     *   customerRef: 'https://example.com/customers/123'
+     * })
+     * ```
+     */
+    listPayments(options?: ListPaymentsOptions): Promise<Payment[]>;
+    /**
+     * Create a transfer to a connected account
+     *
+     * Transfers funds from the platform balance to a connected account.
+     *
+     * @param destinationAccountId - Stripe account ID of destination
+     * @param amount - Amount in smallest currency unit
+     * @param currency - ISO 4217 currency code
+     * @param options - Additional transfer options
+     * @returns The created transfer
+     *
+     * @example
+     * ```typescript
+     * const transfer = await processor.createTransfer(
+     *   'acct_xxx',
+     *   900,
+     *   'usd',
+     *   { sourceTransaction: 'ch_xxx' }
+     * )
+     * ```
+     */
+    createTransfer(destinationAccountId: string, amount: number, currency: string, options?: CreateTransferOptions): Promise<Transfer>;
+    /**
+     * Retrieve a transfer
+     *
+     * @param transferId - The transfer ID
+     * @returns The transfer or null if not found
+     */
+    getTransfer(transferId: string): Promise<Transfer | null>;
+    /**
+     * Reverse a transfer
+     *
+     * @param transferId - The transfer ID
+     * @param amount - Amount to reverse (partial if less than transfer amount)
+     * @returns The updated transfer
+     */
+    reverseTransfer(transferId: string, amount?: number): Promise<Transfer>;
+    /**
+     * List transfers
+     *
+     * @param options - Filter and pagination options
+     * @returns List of transfers
+     */
+    listTransfers(options?: {
+        destinationAccountId?: string;
+        transferGroup?: string;
+        limit?: number;
+        startingAfter?: string;
+    }): Promise<Transfer[]>;
+    /**
+     * Create a payout to a bank account
+     *
+     * Initiates a payout from a Stripe balance to an external bank account.
+     *
+     * @param stripeAccountId - Stripe account ID (for connected accounts)
+     * @param bankAccountId - Destination bank account ID
+     * @param amount - Amount in smallest currency unit
+     * @param currency - ISO 4217 currency code
+     * @param options - Additional payout options
+     * @returns The created payout
+     *
+     * @example
+     * ```typescript
+     * // Standard payout (2-3 days)
+     * const payout = await processor.createPayout(
+     *   'acct_xxx',
+     *   'ba_xxx',
+     *   10000,
+     *   'usd'
+     * )
+     *
+     * // Instant payout
+     * const payout = await processor.createPayout(
+     *   'acct_xxx',
+     *   'ba_xxx',
+     *   10000,
+     *   'usd',
+     *   { method: 'instant' }
+     * )
+     * ```
+     */
+    createPayout(stripeAccountId: string, bankAccountId: string, amount: number, currency: string, options?: CreatePayoutOptions): Promise<Payout>;
+    /**
+     * Retrieve a payout
+     *
+     * @param payoutId - The payout ID
+     * @param stripeAccountId - Stripe account ID (for connected accounts)
+     * @returns The payout or null if not found
+     */
+    getPayout(payoutId: string, stripeAccountId?: string): Promise<Payout | null>;
+    /**
+     * Cancel a pending payout
+     *
+     * @param payoutId - The payout ID
+     * @param stripeAccountId - Stripe account ID (for connected accounts)
+     * @returns The canceled payout
+     */
+    cancelPayout(payoutId: string, stripeAccountId?: string): Promise<Payout>;
+    /**
+     * List payouts
+     *
+     * @param stripeAccountId - Stripe account ID (for connected accounts)
+     * @param options - Filter and pagination options
+     * @returns List of payouts
+     */
+    listPayouts(stripeAccountId?: string, options?: {
+        status?: Payout['status'];
+        limit?: number;
+        startingAfter?: string;
+    }): Promise<Payout[]>;
+    /**
+     * Get application fees collected
+     *
+     * @param options - Filter options
+     * @returns List of application fees
+     */
+    listApplicationFees(options?: {
+        connectedAccountId?: string;
+        chargeId?: string;
+        limit?: number;
+        startingAfter?: string;
+    }): Promise<ApplicationFee[]>;
+    /**
+     * Calculate platform fee for an amount
+     *
+     * @param amount - Base amount
+     * @returns The calculated fee amount
+     */
+    calculatePlatformFee(amount: number): number;
+    /**
+     * Handle a Stripe webhook event for payments
+     *
+     * @param payload - Raw webhook payload
+     * @param signature - Stripe-Signature header value
+     * @returns Processed event data
+     */
+    handleWebhook(payload: string | ArrayBuffer, signature: string): Promise<{
+        type: string;
+        data: unknown;
+    }>;
+}
+/**
+ * Payment error codes
+ */
+export declare const PaymentErrorCodes: {
+    readonly PAYMENT_NOT_FOUND: "PAYMENT_NOT_FOUND";
+    readonly PAYMENT_FAILED: "PAYMENT_FAILED";
+    readonly CAPTURE_FAILED: "CAPTURE_FAILED";
+    readonly REFUND_FAILED: "REFUND_FAILED";
+    readonly TRANSFER_FAILED: "TRANSFER_FAILED";
+    readonly PAYOUT_FAILED: "PAYOUT_FAILED";
+    readonly INSUFFICIENT_FUNDS: "INSUFFICIENT_FUNDS";
+    readonly INVALID_AMOUNT: "INVALID_AMOUNT";
+};
+export type PaymentErrorCode = typeof PaymentErrorCodes[keyof typeof PaymentErrorCodes];
+/**
+ * Payment processing error
+ */
+export declare class PaymentError extends Error {
+    readonly code: PaymentErrorCode;
+    readonly details?: unknown | undefined;
+    constructor(code: PaymentErrorCode, message: string, details?: unknown | undefined);
+}
+//# sourceMappingURL=payments.d.ts.map

package/dist/do/business/financial/payments.d.ts.map

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