@plyaz/types 1.11.3 → 1.12.0

package/dist/payments/provider/core/types.d.ts

@@ -0,0 +1,508 @@
+import type { CURRENCY } from '../../currency';
+import type { FeeBreakdown, Money } from '../../transaction';
+import type { PAYMENTMETHOD, PAYMENTPROVIDERTYPE, PAYMENTSTATUS } from '../provider-capability';
+/**
+ * High-level configuration for initializing a payment provider.
+ *
+ * This configuration is passed to the provider adapter during initialization.
+ * It must contain everything required to:
+ * - Authenticate with the provider
+ * - Configure operational behavior
+ * - Enable webhook verification
+ * - Support different environments (sandbox, production, etc.)
+ */
+export interface PaymentProviderConfig<TExtra extends object = object, TCustomHeaders extends Record<string, string> = Record<string, string>> {
+    /** Provider type identifier (e.g., stripe, paypal) */
+    provider: PAYMENTPROVIDERTYPE;
+    /** Primary authentication */
+    apiKey?: string;
+    secretKey?: string;
+    /** For Stripe client-side integrations */
+    publishableKey?: string;
+    /** Optional merchant/account identifiers */
+    merchantId?: string;
+    accountId?: string;
+    /** Optional API version pinning */
+    apiVersion?: string;
+    /** Environment */
+    environment: 'sandbox' | 'staging' | 'production';
+    apiBaseUrl?: string;
+    /** Currency and region support */
+    supportedCurrencies?: CURRENCY[];
+    supportedRegions?: string[];
+    /** Webhook configuration */
+    webhook?: {
+        url: string;
+        secret?: string;
+        /** Support multiple webhook endpoints if needed */
+        secrets?: Record<string, string>;
+        events?: string[];
+        tolerance?: number;
+    };
+    /** Request config */
+    requestTimeout?: number;
+    retryPolicy?: {
+        maxRetries: number;
+        backoffMs: number;
+    };
+    /** Debug and advanced options */
+    debug?: boolean;
+    customHeaders?: TCustomHeaders;
+    extra?: TExtra;
+    /** Optional secondary credentials (e.g., key rotation) */
+    secondaryCredentials?: {
+        apiKey?: string;
+        secretKey?: string;
+    };
+}
+/**
+ * Core parameters for initiating a payment transaction with any provider.
+ * This type is **provider-agnostic** and later normalized/translated
+ * inside the provider adapter.
+ */
+export interface CreatePaymentParams<TMetadata extends object = object> {
+    /** Amount to be charged, always in smallest currency unit */
+    amount: Money;
+    /** Payment method selected for this transaction */
+    method: PAYMENTMETHOD;
+    /** Currency of the transaction */
+    currency: CURRENCY;
+    /** Unique identifier for the user initiating the transaction */
+    userId: string;
+    /** Product or service being paid for */
+    productId: string;
+    /** Description for statement or receipt */
+    description?: string;
+    /** URL to redirect user after successful payment */
+    returnUrl?: string;
+    /** URL to redirect user after failed/cancelled payment */
+    cancelUrl?: string;
+    /** Optional idempotency key to prevent duplicate charges */
+    idempotencyKey?: string;
+    /** Additional metadata (campaign, subscription, geo info, etc.) */
+    metadata?: TMetadata;
+}
+/**
+ * Parameters required to initiate a refund.
+ * Refunds can be full or partial.
+ */
+export interface RefundParams<TMetadata extends object = object> {
+    provider: string;
+    /** Internal Plyaz transaction ID */
+    transactionId: string;
+    /** Provider transaction ID (optional but useful for some providers) */
+    providerTransactionId?: string;
+    /** Amount to refund — required for partial refunds */
+    amount?: Money;
+    /** Reason for refund (optional, useful for reporting) */
+    reason?: string;
+    /** Initiator of refund (system, user, admin) */
+    initiatedBy?: 'system' | 'user' | 'admin';
+    /** Additional metadata for audit */
+    metadata?: TMetadata;
+}
+/**
+ * Result returned after processing a refund request.
+ */
+export interface RefundResult<TMetadata extends object = object> {
+    /** Unique refund transaction ID in Plyaz system */
+    refundId: string;
+    /** Provider-specific refund ID (if available) */
+    providerRefundId?: string;
+    /** Status of the refund transaction */
+    status: PAYMENTSTATUS;
+    /** Refunded amount */
+    amount: Money;
+    /** Any applicable refund fees (if provider charges fees on refunds) */
+    fees?: FeeBreakdown;
+    /** Message or reason in case of failure */
+    failureReason?: string;
+    /** Timestamp when refund was processed */
+    processedAt?: Date;
+    /** Raw provider response for debugging */
+    providerResponse?: TMetadata;
+}
+/**
+ * Result returned when checking payment transaction status from a provider.
+ */
+export interface PaymentStatusResult<TMetadata extends object = object> {
+    /** Current normalized payment status */
+    status: PAYMENTSTATUS;
+    /** Internal Plyaz transaction ID */
+    transactionId: string;
+    /** Provider transaction ID */
+    providerTransactionId?: string;
+    /** Amount charged */
+    amount: Money;
+    /** Any refund amount if already processed */
+    refundedAmount?: Money;
+    /** Timestamp of the latest status update */
+    updatedAt: Date;
+    /** Additional metadata or raw provider payload */
+    metadata?: TMetadata;
+}
+/**
+ * Generic webhook payload structure used for parsing
+ * incoming events from any payment provider.
+ */
+export interface WebhookPayload {
+    event: string;
+    /** Raw body of the webhook request */
+    rawBody: string;
+    /** Headers of the webhook request (for signature validation) */
+    headers: Record<string, string | string[]>;
+    /** Signature extracted from headers */
+    signature?: string;
+    /** Provider type (e.g., stripe, paypal, etc.) */
+    provider: PAYMENTPROVIDERTYPE;
+}
+/**
+ * Normalized webhook result returned after processing provider webhook.
+ */
+export interface WebhookResult<TMetadata extends object = object> {
+    /** Whether the webhook was successfully processed */
+    success: boolean;
+    /** Event type normalized to Plyaz domain */
+    eventType: string;
+    /** Transaction ID this event relates to */
+    transactionId?: string;
+    /** Updated payment status if applicable */
+    updatedStatus?: PAYMENTSTATUS;
+    /** Optional message for logging or auditing */
+    message?: string;
+    /** Raw provider webhook payload */
+    providerPayload?: TMetadata;
+}
+/**
+ * Options for calculating transaction fees before actual processing.
+ */
+export interface FeeCalculationOptions<TMetadata extends object = object> {
+    /** Indicates whether this is a test transaction */
+    testMode?: boolean;
+    /** Whether to include platform fees */
+    includePlatformFees?: boolean;
+    /** User location or region for tax/fee calculation */
+    geoInfo?: {
+        country: string;
+        region?: string;
+        city?: string;
+    };
+    /** Transaction metadata that can influence fees */
+    metadata?: TMetadata;
+}
+/**
+ * Parameters for creating a customer profile with a provider
+ * (only used if provider supports saving customer data).
+ */
+export interface CreateCustomerParams<TMetadata extends object = object> {
+    /** Unique Plyaz user ID */
+    userId: string;
+    /** Email address of the customer */
+    email: string;
+    /** Full name of the customer */
+    name?: string;
+    /** Optional phone number */
+    phone?: string;
+    /** Billing address */
+    address?: {
+        line1: string;
+        line2?: string;
+        city: string;
+        state?: string;
+        postalCode?: string;
+        country: string;
+    };
+    /** Additional metadata */
+    metadata?: TMetadata;
+}
+/**
+ * Result returned after successfully creating a customer with a provider.
+ */
+export interface CustomerResult<TMetadata extends object = object> {
+    /** Plyaz customer ID */
+    customerId: string;
+    /** Provider-specific customer ID */
+    providerCustomerId: string;
+    /** Confirmation message or notes */
+    message?: string;
+    /** Raw provider response */
+    providerResponse?: TMetadata;
+}
+/**
+ * Parameters for saving a payment method with a provider.
+ */
+export interface SavePaymentMethodParams<TMetadata extends object = object> {
+    /** Plyaz user ID */
+    userId: string;
+    /** Provider customer ID */
+    providerCustomerId: string;
+    /** Type of payment method (card, bank account, wallet, etc.) */
+    method: PAYMENTMETHOD;
+    /** Token or ID returned from provider after authorization */
+    paymentToken: string;
+    /** Whether this should be the default method for the user */
+    setDefault?: boolean;
+    /** Additional metadata */
+    metadata?: TMetadata;
+}
+/**
+ * Result returned after saving a payment method with a provider.
+ */
+export interface SavedPaymentMethodResult<TMetadata extends object = object> {
+    /** Internal ID for the saved payment method */
+    paymentMethodId: string;
+    /** Provider-specific payment method ID */
+    providerPaymentMethodId: string;
+    /** Last four digits (for cards) or display info */
+    displayInfo?: string;
+    /** Whether this method is set as default */
+    isDefault?: boolean;
+    /** Timestamp when method was saved */
+    savedAt: Date;
+    /** Raw provider response */
+    providerResponse?: TMetadata;
+}
+/**
+ * Query parameters for fetching transaction history from a provider.
+ */
+export interface TransactionHistoryParams {
+    /** Plyaz user ID */
+    userId: string;
+    /** Date range for transactions */
+    dateRange?: {
+        from: Date;
+        to: Date;
+    };
+    /** Filter by payment status */
+    status?: PAYMENTSTATUS;
+    /** Maximum number of records to return */
+    limit?: number;
+    /** Pagination cursor or token */
+    cursor?: string;
+}
+/**
+ * Transaction history result returned by provider.
+ */
+export interface TransactionHistory<TMetadata extends object = object> {
+    /** List of transactions */
+    transactions: Array<{
+        transactionId: string;
+        providerTransactionId?: string;
+        amount: Money;
+        status: PAYMENTSTATUS;
+        createdAt: Date;
+        updatedAt?: Date;
+        method: PAYMENTMETHOD;
+        metadata?: TMetadata;
+    }>;
+    /** Pagination cursor for next page */
+    nextCursor?: string;
+    /** Whether there are more records available */
+    hasMore: boolean;
+}
+export interface PaymentAdapterConfig<TExtra extends object = object> {
+    /** Default region used if no specific mapping is found */
+    defaultRegion?: string;
+    /** Region → Provider mapping */
+    regionProviderMapping?: Record<string, PAYMENTPROVIDERTYPE>;
+    /** Provider credentials and environment configuration */
+    providers: {
+        [key in PAYMENTPROVIDERTYPE]?: {
+            apiKey?: string;
+            secretKey?: string;
+            merchantId?: string;
+            apiBaseUrl?: string;
+            webhookUrl?: string;
+            webhookSecret?: string;
+            environment: 'sandbox' | 'staging' | 'production';
+            extra?: TExtra;
+        };
+    };
+    /** Fallback configuration (optional) */
+    fallbackRules?: {
+        enabled: boolean;
+        strategy: 'round_robin' | 'priority' | 'failover';
+        priorityList?: PAYMENTPROVIDERTYPE[];
+    };
+    /** Global settings (timeouts, logging, etc.) */
+    globalSettings?: {
+        timeout?: number;
+        enableLogging?: boolean;
+        retryAttempts?: number;
+    };
+}
+export interface NormalizedPaymentRequest<TMetadata extends object = object> {
+    /** Amount to charge */
+    amount: Money;
+    /** Payment method */
+    method: PAYMENTMETHOD;
+    /** Currency */
+    currency: CURRENCY;
+    /** User initiating the transaction */
+    userId: string;
+    /** Product or service being purchased */
+    productId: string;
+    /** Optional statement description */
+    description?: string;
+    /** Redirect URL after successful payment */
+    returnUrl?: string;
+    /** Redirect URL after failure/cancellation */
+    cancelUrl?: string;
+    /** Idempotency key to prevent duplicates */
+    idempotencyKey?: string;
+    /** Extra metadata for business logic */
+    metadata?: TMetadata;
+}
+export interface TransactionDetails<TMetadata extends object = object> {
+    /** Internal Plyaz transaction ID */
+    transactionId: string;
+    /** Provider transaction ID */
+    providerTransactionId?: string;
+    /** Current payment status */
+    status: PAYMENTSTATUS;
+    /** Total amount of the transaction */
+    amount: Money;
+    /** Refunded amount (if applicable) */
+    refundedAmount?: Money;
+    /** Fees applied to this transaction */
+    fees?: FeeBreakdown;
+    /** Payment method used */
+    method: PAYMENTMETHOD;
+    /** Currency of the transaction */
+    currency: CURRENCY;
+    /** Timestamp when transaction was created */
+    createdAt: Date;
+    /** Timestamp of the latest status update */
+    updatedAt: Date;
+    /** Optional description or statement text */
+    description?: string;
+    /** Metadata and raw provider response */
+    metadata?: TMetadata;
+}
+export interface FeeStructure {
+    /** Percentage fee applied (e.g. 0.029 = 2.9%) */
+    percentageFee: number;
+    /** Fixed fee applied per transaction */
+    fixedFee: Money;
+    /** Optional additional fees for special cases */
+    additionalFees?: Array<{
+        name: string;
+        amount: Money;
+        description?: string;
+    }>;
+    /** Whether this fee structure includes taxes or surcharges */
+    includesTaxes?: boolean;
+    /** Last updated timestamp for fee structure */
+    updatedAt: Date;
+}
+export interface AdapterConfiguration<TMetadata extends object = object> {
+    /** Provider type identifier */
+    provider: string;
+    /** Environment (sandbox, staging, production) */
+    environment: 'sandbox' | 'staging' | 'production';
+    /** Enabled capabilities/features */
+    features: Record<string, boolean>;
+    /** Webhook configuration */
+    webhook?: {
+        endpointUrl?: string;
+        secret?: string;
+        subscribedEvents?: string[];
+    };
+    /** Supported payment methods and currencies */
+    supportedMethods: PAYMENTMETHOD[];
+    supportedCurrencies: CURRENCY[];
+    /** Additional configuration or metadata */
+    metadata?: TMetadata;
+}
+export interface SavedPaymentMethod<TMetadata extends object = object> {
+    /** Internal ID for the saved payment method */
+    id: string;
+    /** Provider-specific payment method ID */
+    providerPaymentMethodId: string;
+    /** Type of payment method (card, wallet, etc.) */
+    method: PAYMENTMETHOD;
+    /** Display-friendly label (e.g. “Visa •••• 4242”) */
+    label?: string;
+    /** Whether this is the default payment method */
+    isDefault: boolean;
+    /** Date the method was saved */
+    savedAt: Date;
+    /** Extra provider-specific metadata */
+    metadata?: TMetadata;
+}
+export interface CreateSubscriptionParams<TMetadata extends object = object> {
+    /** Plyaz user ID */
+    userId: string;
+    /** Amount per billing cycle */
+    amount: Money;
+    /** Billing cycle (in ISO 8601 duration or custom format) */
+    billingCycle: string;
+    /** Payment method to charge */
+    paymentMethodId: string;
+    /** Optional trial period in days */
+    trialDays?: number;
+    /** Subscription metadata */
+    metadata?: TMetadata;
+}
+export interface SubscriptionResult<TMetadata extends object = object> {
+    /** Internal Plyaz subscription ID */
+    subscriptionId: string;
+    /** Provider subscription ID */
+    providerSubscriptionId?: string;
+    /** Current subscription status */
+    status: 'active' | 'trialing' | 'paused' | 'canceled' | 'expired';
+    /** Next billing date */
+    nextBillingDate?: Date;
+    /** Start date of subscription */
+    startedAt: Date;
+    /** Metadata and provider payload */
+    metadata?: TMetadata;
+}
+export interface PayoutParams<TMetadata extends object = object> {
+    /** Unique ID of the recipient (e.g. merchant ID) */
+    recipientId: string;
+    /** Amount to pay out */
+    amount: Money;
+    /** Currency of payout */
+    currency: CURRENCY;
+    /** Optional bank account / wallet ID at provider */
+    destinationId?: string;
+    /** Optional description */
+    description?: string;
+    /** Optional metadata */
+    metadata?: TMetadata;
+}
+export interface PayoutResult<TMetadata extends object = object> {
+    /** Plyaz payout ID */
+    payoutId: string;
+    /** Provider payout ID */
+    providerPayoutId?: string;
+    /** Payout status */
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** Timestamp of payout initiation */
+    createdAt: Date;
+    /** Timestamp of payout completion (if any) */
+    completedAt?: Date;
+    /** Metadata and provider response */
+    metadata?: TMetadata;
+}
+export interface SavedPaymentMethodInfo {
+    id: string;
+    label: string;
+    method: PAYMENTMETHOD;
+    isDefault: boolean;
+}
+export interface ReceiptData<TMetadata extends object = object> {
+    receiptId: string;
+    issuedAt: Date;
+    amount: Money;
+    currency: CURRENCY;
+    lineItems?: Array<{
+        name: string;
+        quantity: number;
+        unitAmount: Money;
+    }>;
+    tax?: Money;
+    total: Money;
+    providerMetadata?: TMetadata;
+}

package/dist/payments/provider/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './adapter';
+export type * from './core';
+export type * from './payment-provider';
+export * from './provider-capability';

package/dist/payments/provider/payment-provider/index.d.ts

@@ -0,0 +1 @@
+export type * from './types';