@nehorai/payments 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,12 +1,13 @@
 export { PaymentServices, PaymentServicesConfig, createPaymentServices, getPaymentServices, registerProvider, resetPaymentServices } from './factory.cjs';
 export { ConfiguredProviderAvailability, EnvMappingConfig, EnvVarMapping, PaymentConfig, ProviderConfig, ProviderEnvMapping, ProvidersConfig, createConfig, createConfigFromEnv, createPartialConfig, getConfiguredProviderList, getConfiguredProviders, isProductionReady, validateConfig } from './config/index.cjs';
-export { A as AuthorizationResult, a as AuthorizePaymentParams, C as CapturePaymentParams, b as CaptureResult, c as CardBrand, d as CreatePaymentIntentParams, e as CurrencyConversion, P as PaymentAmount, f as PaymentError, g as PaymentErrorCode, h as PaymentIntentResult, i as PaymentMetadata, j as PaymentMethodType, k as PaymentProvider, l as ProviderHealthStatus, m as ProviderMetadata, R as RefundParams, n as RefundResult, T as TaxInvoiceStatus, o as TransactionType, V as VoidPaymentParams, p as VoidResult } from './payment-types-68W-PlGg.cjs';
+export { A as AuthorizationResult, a as AuthorizePaymentParams, C as CancelSubscriptionParams, b as CancelSubscriptionResult, c as CapturePaymentParams, d as CaptureResult, e as CardBrand, f as CreatePaymentIntentParams, g as CreateSubscriptionParams, h as CurrencyConversion, P as PaymentAmount, i as PaymentError, j as PaymentErrorCode, k as PaymentIntentResult, l as PaymentMetadata, m as PaymentMethodType, n as PaymentProvider, o as ProviderHealthStatus, p as ProviderMetadata, R as RefundParams, q as RefundResult, S as SubscriptionInterval, r as SubscriptionResult, s as SubscriptionStatus, T as TaxInvoiceStatus, t as TransactionType, V as VoidPaymentParams, u as VoidResult } from './payment-types-DUs8IALw.cjs';
 export { S as SUCCESS_STATES, a as StateTransitionResult, T as TERMINAL_STATES, b as TransactionEvent, c as TransactionStatus, d as attemptTransition, e as calculateCaptureDeadline, f as canCapture, g as canRefund, h as canTransition, i as canVoid, j as getNextStatus, k as isAuthorizationExpired, l as isHoldState, m as isSuccessState, n as isTerminalState } from './state-machine-Cu6_qKnv.cjs';
 export { ReconciliationResult, WebhookAction, WebhookEvent, WebhookProcessingResult, WebhookStatus } from './types/index.cjs';
-export { C as CardBinRule, a as CircuitBreaker, b as CircuitBreakerConfig, c as CircuitBreakerDeps, d as CircuitBreakerState, e as CircuitBreakerStateRecord, f as CircuitState, g as ConfirmPaymentParams, h as CurrencyRule, I as ICircuitBreakerStorage, i as InitiatePaymentParams, j as OrchestratorCaptureParams, P as PaymentCaptureResult, k as PaymentConfirmationResult, l as PaymentInitiationResult, m as PaymentOrchestrator, n as PaymentOrchestratorDeps, o as ProviderPriorityRule, R as RoutingEngine, p as RoutingEngineDeps, q as RoutingRules, S as StoredCircuitState, r as createCircuitBreaker, s as createDefaultState, t as createPaymentOrchestrator, u as createRoutingEngine, v as getCircuitBreaker, w as getRoutingEngine, x as isCircuitOpen, y as resetCircuitBreaker, z as resetRoutingEngine, A as shouldAttemptHalfOpen } from './payment-orchestrator-Co_X6T_V.cjs';
+export { C as CardBinRule, a as CircuitBreaker, b as CircuitBreakerConfig, c as CircuitBreakerDeps, d as CircuitBreakerState, e as CircuitBreakerStateRecord, f as CircuitState, g as ConfirmPaymentParams, h as CurrencyRule, I as ICircuitBreakerStorage, i as InitiatePaymentParams, j as OrchestratorCaptureParams, P as PaymentCaptureResult, k as PaymentConfirmationResult, l as PaymentInitiationResult, m as PaymentOrchestrator, n as PaymentOrchestratorDeps, o as ProviderPriorityRule, R as RoutingEngine, p as RoutingEngineDeps, q as RoutingRules, S as StoredCircuitState, r as createCircuitBreaker, s as createDefaultState, t as createPaymentOrchestrator, u as createRoutingEngine, v as getCircuitBreaker, w as getRoutingEngine, x as isCircuitOpen, y as resetCircuitBreaker, z as resetRoutingEngine, A as shouldAttemptHalfOpen } from './payment-orchestrator-BmAZcr84.cjs';
 export { InMemoryCircuitBreakerStorage, getInMemoryStorage, migrateFromLegacyMap, resetInMemoryStorage } from './services/index.cjs';
-export { C as CreateCustomerParams, a as CreateCustomerResult, b as CreateSetupIntentParams, I as IPaymentProvider, c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, S as SavePaymentMethodParams, e as SavePaymentMethodResult, f as SetupIntentResult } from './routing-engine.interface-DJzGXor9.cjs';
-export { IWebhookHandler } from './providers/interfaces/index.cjs';
+export { C as CreateCustomerParams, a as CreateCustomerResult, b as CreateSetupIntentParams, I as IPaymentProvider, c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, S as SavePaymentMethodParams, e as SavePaymentMethodResult, f as SetupIntentResult } from './routing-engine.interface-B8tYJvJO.cjs';
+export { I as IWebhookHandler } from './webhook-handler.interface-Dq9hNM80.cjs';
+export { ISubscriptionProvider } from './providers/interfaces/index.cjs';
 export { SignatureVerificationParams, SignatureVerificationResult, SignatureVerifier, generateDeterministicKey, generateIdempotencyKey, generateInternalPaymentId, generateOperationKey, getSignatureHeaderName, getSignatureVerifier, isValidIdempotencyKey, isValidInternalPaymentId, registerSignatureVerifier, verifyHmacSha256Signature, verifySortedFieldsHmacSignature, verifyStripeStyleSignature, verifyWebhookSignature } from './utils/index.cjs';
 import { ITransactionRepository, Transaction, CreateTransactionInput, UpdateTransactionInput, TransactionFilter, PaginationParams, PaginatedResult, TransactionStatus } from './repository/interfaces/index.cjs';
 export { AuditLogEntry, DateRangeFilter, IAuditLogRepository, IPaymentMethodRepository, IPaymentRepositories, IProviderHealthRepository, IWebhookEventRepository, PaymentMethod, ProviderHealth, WebhookEvent as WebhookEventEntity } from './repository/interfaces/index.cjs';

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 export { PaymentServices, PaymentServicesConfig, createPaymentServices, getPaymentServices, registerProvider, resetPaymentServices } from './factory.js';
 export { ConfiguredProviderAvailability, EnvMappingConfig, EnvVarMapping, PaymentConfig, ProviderConfig, ProviderEnvMapping, ProvidersConfig, createConfig, createConfigFromEnv, createPartialConfig, getConfiguredProviderList, getConfiguredProviders, isProductionReady, validateConfig } from './config/index.js';
-export { A as AuthorizationResult, a as AuthorizePaymentParams, C as CapturePaymentParams, b as CaptureResult, c as CardBrand, d as CreatePaymentIntentParams, e as CurrencyConversion, P as PaymentAmount, f as PaymentError, g as PaymentErrorCode, h as PaymentIntentResult, i as PaymentMetadata, j as PaymentMethodType, k as PaymentProvider, l as ProviderHealthStatus, m as ProviderMetadata, R as RefundParams, n as RefundResult, T as TaxInvoiceStatus, o as TransactionType, V as VoidPaymentParams, p as VoidResult } from './payment-types-68W-PlGg.js';
+export { A as AuthorizationResult, a as AuthorizePaymentParams, C as CancelSubscriptionParams, b as CancelSubscriptionResult, c as CapturePaymentParams, d as CaptureResult, e as CardBrand, f as CreatePaymentIntentParams, g as CreateSubscriptionParams, h as CurrencyConversion, P as PaymentAmount, i as PaymentError, j as PaymentErrorCode, k as PaymentIntentResult, l as PaymentMetadata, m as PaymentMethodType, n as PaymentProvider, o as ProviderHealthStatus, p as ProviderMetadata, R as RefundParams, q as RefundResult, S as SubscriptionInterval, r as SubscriptionResult, s as SubscriptionStatus, T as TaxInvoiceStatus, t as TransactionType, V as VoidPaymentParams, u as VoidResult } from './payment-types-DUs8IALw.js';
 export { S as SUCCESS_STATES, a as StateTransitionResult, T as TERMINAL_STATES, b as TransactionEvent, c as TransactionStatus, d as attemptTransition, e as calculateCaptureDeadline, f as canCapture, g as canRefund, h as canTransition, i as canVoid, j as getNextStatus, k as isAuthorizationExpired, l as isHoldState, m as isSuccessState, n as isTerminalState } from './state-machine-Cu6_qKnv.js';
 export { ReconciliationResult, WebhookAction, WebhookEvent, WebhookProcessingResult, WebhookStatus } from './types/index.js';
-export { C as CardBinRule, a as CircuitBreaker, b as CircuitBreakerConfig, c as CircuitBreakerDeps, d as CircuitBreakerState, e as CircuitBreakerStateRecord, f as CircuitState, g as ConfirmPaymentParams, h as CurrencyRule, I as ICircuitBreakerStorage, i as InitiatePaymentParams, j as OrchestratorCaptureParams, P as PaymentCaptureResult, k as PaymentConfirmationResult, l as PaymentInitiationResult, m as PaymentOrchestrator, n as PaymentOrchestratorDeps, o as ProviderPriorityRule, R as RoutingEngine, p as RoutingEngineDeps, q as RoutingRules, S as StoredCircuitState, r as createCircuitBreaker, s as createDefaultState, t as createPaymentOrchestrator, u as createRoutingEngine, v as getCircuitBreaker, w as getRoutingEngine, x as isCircuitOpen, y as resetCircuitBreaker, z as resetRoutingEngine, A as shouldAttemptHalfOpen } from './payment-orchestrator-CPaLmDM5.js';
+export { C as CardBinRule, a as CircuitBreaker, b as CircuitBreakerConfig, c as CircuitBreakerDeps, d as CircuitBreakerState, e as CircuitBreakerStateRecord, f as CircuitState, g as ConfirmPaymentParams, h as CurrencyRule, I as ICircuitBreakerStorage, i as InitiatePaymentParams, j as OrchestratorCaptureParams, P as PaymentCaptureResult, k as PaymentConfirmationResult, l as PaymentInitiationResult, m as PaymentOrchestrator, n as PaymentOrchestratorDeps, o as ProviderPriorityRule, R as RoutingEngine, p as RoutingEngineDeps, q as RoutingRules, S as StoredCircuitState, r as createCircuitBreaker, s as createDefaultState, t as createPaymentOrchestrator, u as createRoutingEngine, v as getCircuitBreaker, w as getRoutingEngine, x as isCircuitOpen, y as resetCircuitBreaker, z as resetRoutingEngine, A as shouldAttemptHalfOpen } from './payment-orchestrator-Bf2XX07D.js';
 export { InMemoryCircuitBreakerStorage, getInMemoryStorage, migrateFromLegacyMap, resetInMemoryStorage } from './services/index.js';
-export { C as CreateCustomerParams, a as CreateCustomerResult, b as CreateSetupIntentParams, I as IPaymentProvider, c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, S as SavePaymentMethodParams, e as SavePaymentMethodResult, f as SetupIntentResult } from './routing-engine.interface-h9_GmQ4b.js';
-export { IWebhookHandler } from './providers/interfaces/index.js';
+export { C as CreateCustomerParams, a as CreateCustomerResult, b as CreateSetupIntentParams, I as IPaymentProvider, c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, S as SavePaymentMethodParams, e as SavePaymentMethodResult, f as SetupIntentResult } from './routing-engine.interface-BrhDxYN6.js';
+export { I as IWebhookHandler } from './webhook-handler.interface-BP_Ew2Mu.js';
+export { ISubscriptionProvider } from './providers/interfaces/index.js';
 export { SignatureVerificationParams, SignatureVerificationResult, SignatureVerifier, generateDeterministicKey, generateIdempotencyKey, generateInternalPaymentId, generateOperationKey, getSignatureHeaderName, getSignatureVerifier, isValidIdempotencyKey, isValidInternalPaymentId, registerSignatureVerifier, verifyHmacSha256Signature, verifySortedFieldsHmacSignature, verifyStripeStyleSignature, verifyWebhookSignature } from './utils/index.js';
 import { ITransactionRepository, Transaction, CreateTransactionInput, UpdateTransactionInput, TransactionFilter, PaginationParams, PaginatedResult, TransactionStatus } from './repository/interfaces/index.js';
 export { AuditLogEntry, DateRangeFilter, IAuditLogRepository, IPaymentMethodRepository, IPaymentRepositories, IProviderHealthRepository, IWebhookEventRepository, PaymentMethod, ProviderHealth, WebhookEvent as WebhookEventEntity } from './repository/interfaces/index.js';

package/dist/{payment-orchestrator-CPaLmDM5.d.ts → payment-orchestrator-Bf2XX07D.d.ts}

@@ -1,6 +1,6 @@
-import { k as PaymentProvider, P as PaymentAmount, i as PaymentMetadata } from './payment-types-68W-PlGg.js';
+import { n as PaymentProvider, P as PaymentAmount, l as PaymentMetadata } from './payment-types-DUs8IALw.js';
 import { c as TransactionStatus } from './state-machine-Cu6_qKnv.js';
-import { c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, I as IPaymentProvider } from './routing-engine.interface-h9_GmQ4b.js';
+import { c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, I as IPaymentProvider } from './routing-engine.interface-BrhDxYN6.js';
 import { PaymentConfig } from './config/index.js';
 
 /**

package/dist/{payment-orchestrator-Co_X6T_V.d.cts → payment-orchestrator-BmAZcr84.d.cts}

@@ -1,6 +1,6 @@
-import { k as PaymentProvider, P as PaymentAmount, i as PaymentMetadata } from './payment-types-68W-PlGg.cjs';
+import { n as PaymentProvider, P as PaymentAmount, l as PaymentMetadata } from './payment-types-DUs8IALw.cjs';
 import { c as TransactionStatus } from './state-machine-Cu6_qKnv.cjs';
-import { c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, I as IPaymentProvider } from './routing-engine.interface-DJzGXor9.cjs';
+import { c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, I as IPaymentProvider } from './routing-engine.interface-B8tYJvJO.cjs';
 import { PaymentConfig } from './config/index.cjs';
 
 /**

package/dist/{payment-types-68W-PlGg.d.cts → payment-types-DUs8IALw.d.cts}

@@ -207,5 +207,76 @@ interface PaymentError {
     retryable: boolean;
     details?: Record<string, unknown>;
 }
+/**
+ * Lifecycle status of a recurring subscription / standing order.
+ * The provider is the source of truth for billing; the application maps
+ * this status onto its own subscription/credit logic.
+ */
+type SubscriptionStatus = 'active' | 'past_due' | 'canceled' | 'paused';
+/**
+ * Billing interval for a subscription.
+ * SUMIT standing orders are billed monthly; kept as a union for future intervals.
+ */
+type SubscriptionInterval = 'monthly';
+/**
+ * Parameters for creating a recurring subscription / standing order
+ */
+interface CreateSubscriptionParams {
+    /** Amount charged on every billing cycle */
+    amount: PaymentAmount;
+    userId: string;
+    idempotencyKey: string;
+    /** Billing interval (default: monthly) */
+    interval?: SubscriptionInterval;
+    /**
+     * Number of charges before the standing order ends.
+     * Omit for an open-ended subscription (charged until canceled).
+     */
+    recurrenceCount?: number;
+    /**
+     * Provider payment-method token representing a vaulted/single-use card.
+     * Required by providers (e.g. SUMIT) whose recurring API is server-to-server
+     * and cannot collect card details itself.
+     */
+    paymentMethodToken?: string;
+    description?: string;
+    metadata?: PaymentMetadata;
+    /** Return URL for hosted-page subscription setup (redirect flows) */
+    returnUrl?: string;
+}
+/**
+ * Result of creating a subscription
+ */
+interface SubscriptionResult {
+    success: boolean;
+    /** Provider's subscription / standing-order identifier */
+    providerSubscriptionId?: string;
+    /** Redirect URL when setup uses a hosted payment page */
+    redirectUrl?: string;
+    status?: SubscriptionStatus;
+    currentPeriodStart?: Date;
+    currentPeriodEnd?: Date;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * Parameters for canceling a subscription
+ */
+interface CancelSubscriptionParams {
+    providerSubscriptionId: string;
+    idempotencyKey: string;
+    /** Cancel at the end of the current period instead of immediately */
+    atPeriodEnd?: boolean;
+    reason?: string;
+}
+/**
+ * Result of canceling a subscription
+ */
+interface CancelSubscriptionResult {
+    success: boolean;
+    status?: SubscriptionStatus;
+    canceledAt?: Date;
+    error?: string;
+}
 
-export type { AuthorizationResult as A, CapturePaymentParams as C, PaymentAmount as P, RefundParams as R, TaxInvoiceStatus as T, VoidPaymentParams as V, AuthorizePaymentParams as a, CaptureResult as b, CardBrand as c, CreatePaymentIntentParams as d, CurrencyConversion as e, PaymentError as f, PaymentErrorCode as g, PaymentIntentResult as h, PaymentMetadata as i, PaymentMethodType as j, PaymentProvider as k, ProviderHealthStatus as l, ProviderMetadata as m, RefundResult as n, TransactionType as o, VoidResult as p };
+export type { AuthorizationResult as A, CancelSubscriptionParams as C, PaymentAmount as P, RefundParams as R, SubscriptionInterval as S, TaxInvoiceStatus as T, VoidPaymentParams as V, AuthorizePaymentParams as a, CancelSubscriptionResult as b, CapturePaymentParams as c, CaptureResult as d, CardBrand as e, CreatePaymentIntentParams as f, CreateSubscriptionParams as g, CurrencyConversion as h, PaymentError as i, PaymentErrorCode as j, PaymentIntentResult as k, PaymentMetadata as l, PaymentMethodType as m, PaymentProvider as n, ProviderHealthStatus as o, ProviderMetadata as p, RefundResult as q, SubscriptionResult as r, SubscriptionStatus as s, TransactionType as t, VoidResult as u };

package/dist/{payment-types-68W-PlGg.d.ts → payment-types-DUs8IALw.d.ts}

@@ -207,5 +207,76 @@ interface PaymentError {
     retryable: boolean;
     details?: Record<string, unknown>;
 }
+/**
+ * Lifecycle status of a recurring subscription / standing order.
+ * The provider is the source of truth for billing; the application maps
+ * this status onto its own subscription/credit logic.
+ */
+type SubscriptionStatus = 'active' | 'past_due' | 'canceled' | 'paused';
+/**
+ * Billing interval for a subscription.
+ * SUMIT standing orders are billed monthly; kept as a union for future intervals.
+ */
+type SubscriptionInterval = 'monthly';
+/**
+ * Parameters for creating a recurring subscription / standing order
+ */
+interface CreateSubscriptionParams {
+    /** Amount charged on every billing cycle */
+    amount: PaymentAmount;
+    userId: string;
+    idempotencyKey: string;
+    /** Billing interval (default: monthly) */
+    interval?: SubscriptionInterval;
+    /**
+     * Number of charges before the standing order ends.
+     * Omit for an open-ended subscription (charged until canceled).
+     */
+    recurrenceCount?: number;
+    /**
+     * Provider payment-method token representing a vaulted/single-use card.
+     * Required by providers (e.g. SUMIT) whose recurring API is server-to-server
+     * and cannot collect card details itself.
+     */
+    paymentMethodToken?: string;
+    description?: string;
+    metadata?: PaymentMetadata;
+    /** Return URL for hosted-page subscription setup (redirect flows) */
+    returnUrl?: string;
+}
+/**
+ * Result of creating a subscription
+ */
+interface SubscriptionResult {
+    success: boolean;
+    /** Provider's subscription / standing-order identifier */
+    providerSubscriptionId?: string;
+    /** Redirect URL when setup uses a hosted payment page */
+    redirectUrl?: string;
+    status?: SubscriptionStatus;
+    currentPeriodStart?: Date;
+    currentPeriodEnd?: Date;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * Parameters for canceling a subscription
+ */
+interface CancelSubscriptionParams {
+    providerSubscriptionId: string;
+    idempotencyKey: string;
+    /** Cancel at the end of the current period instead of immediately */
+    atPeriodEnd?: boolean;
+    reason?: string;
+}
+/**
+ * Result of canceling a subscription
+ */
+interface CancelSubscriptionResult {
+    success: boolean;
+    status?: SubscriptionStatus;
+    canceledAt?: Date;
+    error?: string;
+}
 
-export type { AuthorizationResult as A, CapturePaymentParams as C, PaymentAmount as P, RefundParams as R, TaxInvoiceStatus as T, VoidPaymentParams as V, AuthorizePaymentParams as a, CaptureResult as b, CardBrand as c, CreatePaymentIntentParams as d, CurrencyConversion as e, PaymentError as f, PaymentErrorCode as g, PaymentIntentResult as h, PaymentMetadata as i, PaymentMethodType as j, PaymentProvider as k, ProviderHealthStatus as l, ProviderMetadata as m, RefundResult as n, TransactionType as o, VoidResult as p };
+export type { AuthorizationResult as A, CancelSubscriptionParams as C, PaymentAmount as P, RefundParams as R, SubscriptionInterval as S, TaxInvoiceStatus as T, VoidPaymentParams as V, AuthorizePaymentParams as a, CancelSubscriptionResult as b, CapturePaymentParams as c, CaptureResult as d, CardBrand as e, CreatePaymentIntentParams as f, CreateSubscriptionParams as g, CurrencyConversion as h, PaymentError as i, PaymentErrorCode as j, PaymentIntentResult as k, PaymentMetadata as l, PaymentMethodType as m, PaymentProvider as n, ProviderHealthStatus as o, ProviderMetadata as p, RefundResult as q, SubscriptionResult as r, SubscriptionStatus as s, TransactionType as t, VoidResult as u };

package/dist/providers/interfaces/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/providers/interfaces/index.ts"],"sourcesContent":["/**\r\n * @nehorai/payments - Provider Interfaces Exports\r\n */\r\n\r\n// Payment Provider Interface\r\nexport type {\r\n  IPaymentProvider,\r\n  SavePaymentMethodParams,\r\n  SavePaymentMethodResult,\r\n  DeletePaymentMethodResult,\r\n  CreateSetupIntentParams,\r\n  SetupIntentResult,\r\n  CreateCustomerParams,\r\n  CreateCustomerResult,\r\n} from './payment-provider.interface.js';\r\n\r\n// Webhook Handler Interface\r\nexport type {\r\n  IWebhookHandler,\r\n  ParsedWebhookEvent,\r\n  ParseWebhookResult,\r\n  EventHandler,\r\n  EventHandlerMap,\r\n} from './webhook-handler.interface.js';\r\n\r\n// Routing Engine Interface\r\nexport type {\r\n  IRoutingEngine,\r\n  RoutingContext,\r\n  RoutingDecision,\r\n} from './routing-engine.interface.js';\r\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../../src/providers/interfaces/index.ts"],"sourcesContent":["/**\r\n * @nehorai/payments - Provider Interfaces Exports\r\n */\r\n\r\n// Payment Provider Interface\r\nexport type {\r\n  IPaymentProvider,\r\n  SavePaymentMethodParams,\r\n  SavePaymentMethodResult,\r\n  DeletePaymentMethodResult,\r\n  CreateSetupIntentParams,\r\n  SetupIntentResult,\r\n  CreateCustomerParams,\r\n  CreateCustomerResult,\r\n} from './payment-provider.interface.js';\r\n\r\n// Webhook Handler Interface\r\nexport type {\r\n  IWebhookHandler,\r\n  ParsedWebhookEvent,\r\n  ParseWebhookResult,\r\n  EventHandler,\r\n  EventHandlerMap,\r\n} from './webhook-handler.interface.js';\r\n\r\n// Subscription Provider Interface (optional capability)\r\nexport type {\r\n  ISubscriptionProvider,\r\n} from './subscription-provider.interface.js';\r\n\r\n// Routing Engine Interface\r\nexport type {\r\n  IRoutingEngine,\r\n  RoutingContext,\r\n  RoutingDecision,\r\n} from './routing-engine.interface.js';\r\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/providers/interfaces/index.d.cts

@@ -1,80 +1,49 @@
-export { C as CreateCustomerParams, a as CreateCustomerResult, b as CreateSetupIntentParams, D as DeletePaymentMethodResult, I as IPaymentProvider, c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, S as SavePaymentMethodParams, e as SavePaymentMethodResult, f as SetupIntentResult } from '../../routing-engine.interface-DJzGXor9.cjs';
-import { k as PaymentProvider } from '../../payment-types-68W-PlGg.cjs';
-import { c as TransactionStatus } from '../../state-machine-Cu6_qKnv.cjs';
-import { WebhookProcessingResult, ReconciliationResult } from '../../types/index.cjs';
+export { C as CreateCustomerParams, a as CreateCustomerResult, b as CreateSetupIntentParams, D as DeletePaymentMethodResult, I as IPaymentProvider, c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, S as SavePaymentMethodParams, e as SavePaymentMethodResult, f as SetupIntentResult } from '../../routing-engine.interface-B8tYJvJO.cjs';
+export { E as EventHandler, a as EventHandlerMap, I as IWebhookHandler, P as ParseWebhookResult, b as ParsedWebhookEvent } from '../../webhook-handler.interface-Dq9hNM80.cjs';
+import { n as PaymentProvider, g as CreateSubscriptionParams, r as SubscriptionResult, C as CancelSubscriptionParams, b as CancelSubscriptionResult } from '../../payment-types-DUs8IALw.cjs';
+import '../../state-machine-Cu6_qKnv.cjs';
+import '../../types/index.cjs';
 
 /**
- * @nehorai/payments - Webhook Handler Interface
+ * @nehorai/payments - Subscription Provider Interface
  *
- * Defines the contract for processing incoming webhooks from payment providers.
- * Handles idempotency, reconciliation, and event-to-action mapping.
+ * Optional capability interface for providers that support recurring
+ * billing / standing orders (e.g. SUMIT). This is intentionally separate
+ * from {@link IPaymentProvider} so that one-time-only providers are not
+ * forced to implement it.
+ *
+ * Capability detection at runtime:
+ * ```typescript
+ * if ('createSubscription' in provider) {
+ *   // provider implements ISubscriptionProvider
+ * }
+ * ```
+ *
+ * The provider is responsible for *billing* the customer on each cycle.
+ * The application's billing/domain layer remains responsible for credits,
+ * plans, permissions and usage — never the provider adapter.
  */
 
 /**
- * Parsed webhook event with standardized fields
- */
-interface ParsedWebhookEvent {
-    /** Provider that sent the webhook */
-    provider: PaymentProvider;
-    /** Provider's unique event ID */
-    eventId: string;
-    /** Standardized event type */
-    eventType: string;
-    /** Associated payment intent/transaction ID */
-    providerTransactionId?: string;
-    /** Amount in minor units (if applicable) */
-    amountMinor?: number;
-    /** Currency (if applicable) */
-    currency?: string;
-    /** New status (if status change event) */
-    newStatus?: TransactionStatus;
-    /** Error details (if failure event) */
-    error?: {
-        code: string;
-        message: string;
-    };
-    /** Original timestamp from provider */
-    timestamp: Date;
-    /** Full raw payload */
-    rawPayload: Record<string, unknown>;
-}
-/**
- * Result of parsing a webhook event
- */
-interface ParseWebhookResult {
-    success: boolean;
-    event?: ParsedWebhookEvent;
-    error?: string;
-}
-/**
- * Handler function for a specific event type
- */
-type EventHandler = (event: ParsedWebhookEvent) => Promise<WebhookProcessingResult>;
-/**
- * Map of event types to handler functions
- */
-type EventHandlerMap = Map<string, EventHandler>;
-/**
- * Webhook Handler Interface
+ * Subscription Provider Interface
  *
- * Provider-specific webhook handlers implement this interface.
- * Enables consistent webhook processing across all providers.
+ * Providers that bill recurring charges implement this in addition to
+ * {@link IPaymentProvider}.
  */
-interface IWebhookHandler {
+interface ISubscriptionProvider {
+    /** Provider identifier (must match the IPaymentProvider name) */
+    readonly name: PaymentProvider;
     /**
-     * Provider this handler is for
+     * Create a recurring subscription / standing order.
+     * For hosted-page providers this returns a `redirectUrl`; the
+     * subscription becomes `active` once the first charge succeeds
+     * (confirmed via webhook + provider query).
      */
-    readonly provider: PaymentProvider;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
     /**
-     * Event types this handler can process
+     * Cancel an existing subscription / standing order.
      */
-    readonly supportedEventTypes: readonly string[];
-    parseEvent(rawPayload: Record<string, unknown>): ParseWebhookResult;
-    processEvent(event: ParsedWebhookEvent): Promise<WebhookProcessingResult>;
-    canHandle(eventType: string): boolean;
-    reconcile(transactionId: string, providerTransactionId: string): Promise<ReconciliationResult>;
-    mapEventType(providerEventType: string): string;
-    mapStatus(providerStatus: string): TransactionStatus | null;
+    cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult>;
 }
 
-export type { EventHandler, EventHandlerMap, IWebhookHandler, ParseWebhookResult, ParsedWebhookEvent };
+export type { ISubscriptionProvider };

package/dist/providers/interfaces/index.d.ts

@@ -1,80 +1,49 @@
-export { C as CreateCustomerParams, a as CreateCustomerResult, b as CreateSetupIntentParams, D as DeletePaymentMethodResult, I as IPaymentProvider, c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, S as SavePaymentMethodParams, e as SavePaymentMethodResult, f as SetupIntentResult } from '../../routing-engine.interface-h9_GmQ4b.js';
-import { k as PaymentProvider } from '../../payment-types-68W-PlGg.js';
-import { c as TransactionStatus } from '../../state-machine-Cu6_qKnv.js';
-import { WebhookProcessingResult, ReconciliationResult } from '../../types/index.js';
+export { C as CreateCustomerParams, a as CreateCustomerResult, b as CreateSetupIntentParams, D as DeletePaymentMethodResult, I as IPaymentProvider, c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, S as SavePaymentMethodParams, e as SavePaymentMethodResult, f as SetupIntentResult } from '../../routing-engine.interface-BrhDxYN6.js';
+export { E as EventHandler, a as EventHandlerMap, I as IWebhookHandler, P as ParseWebhookResult, b as ParsedWebhookEvent } from '../../webhook-handler.interface-BP_Ew2Mu.js';
+import { n as PaymentProvider, g as CreateSubscriptionParams, r as SubscriptionResult, C as CancelSubscriptionParams, b as CancelSubscriptionResult } from '../../payment-types-DUs8IALw.js';
+import '../../state-machine-Cu6_qKnv.js';
+import '../../types/index.js';
 
 /**
- * @nehorai/payments - Webhook Handler Interface
+ * @nehorai/payments - Subscription Provider Interface
  *
- * Defines the contract for processing incoming webhooks from payment providers.
- * Handles idempotency, reconciliation, and event-to-action mapping.
+ * Optional capability interface for providers that support recurring
+ * billing / standing orders (e.g. SUMIT). This is intentionally separate
+ * from {@link IPaymentProvider} so that one-time-only providers are not
+ * forced to implement it.
+ *
+ * Capability detection at runtime:
+ * ```typescript
+ * if ('createSubscription' in provider) {
+ *   // provider implements ISubscriptionProvider
+ * }
+ * ```
+ *
+ * The provider is responsible for *billing* the customer on each cycle.
+ * The application's billing/domain layer remains responsible for credits,
+ * plans, permissions and usage — never the provider adapter.
  */
 
 /**
- * Parsed webhook event with standardized fields
- */
-interface ParsedWebhookEvent {
-    /** Provider that sent the webhook */
-    provider: PaymentProvider;
-    /** Provider's unique event ID */
-    eventId: string;
-    /** Standardized event type */
-    eventType: string;
-    /** Associated payment intent/transaction ID */
-    providerTransactionId?: string;
-    /** Amount in minor units (if applicable) */
-    amountMinor?: number;
-    /** Currency (if applicable) */
-    currency?: string;
-    /** New status (if status change event) */
-    newStatus?: TransactionStatus;
-    /** Error details (if failure event) */
-    error?: {
-        code: string;
-        message: string;
-    };
-    /** Original timestamp from provider */
-    timestamp: Date;
-    /** Full raw payload */
-    rawPayload: Record<string, unknown>;
-}
-/**
- * Result of parsing a webhook event
- */
-interface ParseWebhookResult {
-    success: boolean;
-    event?: ParsedWebhookEvent;
-    error?: string;
-}
-/**
- * Handler function for a specific event type
- */
-type EventHandler = (event: ParsedWebhookEvent) => Promise<WebhookProcessingResult>;
-/**
- * Map of event types to handler functions
- */
-type EventHandlerMap = Map<string, EventHandler>;
-/**
- * Webhook Handler Interface
+ * Subscription Provider Interface
  *
- * Provider-specific webhook handlers implement this interface.
- * Enables consistent webhook processing across all providers.
+ * Providers that bill recurring charges implement this in addition to
+ * {@link IPaymentProvider}.
  */
-interface IWebhookHandler {
+interface ISubscriptionProvider {
+    /** Provider identifier (must match the IPaymentProvider name) */
+    readonly name: PaymentProvider;
     /**
-     * Provider this handler is for
+     * Create a recurring subscription / standing order.
+     * For hosted-page providers this returns a `redirectUrl`; the
+     * subscription becomes `active` once the first charge succeeds
+     * (confirmed via webhook + provider query).
      */
-    readonly provider: PaymentProvider;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
     /**
-     * Event types this handler can process
+     * Cancel an existing subscription / standing order.
      */
-    readonly supportedEventTypes: readonly string[];
-    parseEvent(rawPayload: Record<string, unknown>): ParseWebhookResult;
-    processEvent(event: ParsedWebhookEvent): Promise<WebhookProcessingResult>;
-    canHandle(eventType: string): boolean;
-    reconcile(transactionId: string, providerTransactionId: string): Promise<ReconciliationResult>;
-    mapEventType(providerEventType: string): string;
-    mapStatus(providerStatus: string): TransactionStatus | null;
+    cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult>;
 }
 
-export type { EventHandler, EventHandlerMap, IWebhookHandler, ParseWebhookResult, ParsedWebhookEvent };
+export type { ISubscriptionProvider };

package/dist/{routing-engine.interface-DJzGXor9.d.cts → routing-engine.interface-B8tYJvJO.d.cts}

@@ -1,4 +1,4 @@
-import { k as PaymentProvider, d as CreatePaymentIntentParams, h as PaymentIntentResult, a as AuthorizePaymentParams, A as AuthorizationResult, C as CapturePaymentParams, b as CaptureResult, V as VoidPaymentParams, p as VoidResult, R as RefundParams, n as RefundResult, l as ProviderHealthStatus, P as PaymentAmount } from './payment-types-68W-PlGg.cjs';
+import { n as PaymentProvider, f as CreatePaymentIntentParams, k as PaymentIntentResult, a as AuthorizePaymentParams, A as AuthorizationResult, c as CapturePaymentParams, d as CaptureResult, V as VoidPaymentParams, u as VoidResult, R as RefundParams, q as RefundResult, o as ProviderHealthStatus, P as PaymentAmount } from './payment-types-DUs8IALw.cjs';
 
 /**
  * @nehorai/payments - Payment Provider Interface

package/dist/{routing-engine.interface-h9_GmQ4b.d.ts → routing-engine.interface-BrhDxYN6.d.ts}

@@ -1,4 +1,4 @@
-import { k as PaymentProvider, d as CreatePaymentIntentParams, h as PaymentIntentResult, a as AuthorizePaymentParams, A as AuthorizationResult, C as CapturePaymentParams, b as CaptureResult, V as VoidPaymentParams, p as VoidResult, R as RefundParams, n as RefundResult, l as ProviderHealthStatus, P as PaymentAmount } from './payment-types-68W-PlGg.js';
+import { n as PaymentProvider, f as CreatePaymentIntentParams, k as PaymentIntentResult, a as AuthorizePaymentParams, A as AuthorizationResult, c as CapturePaymentParams, d as CaptureResult, V as VoidPaymentParams, u as VoidResult, R as RefundParams, q as RefundResult, o as ProviderHealthStatus, P as PaymentAmount } from './payment-types-DUs8IALw.js';
 
 /**
  * @nehorai/payments - Payment Provider Interface

package/dist/services/index.d.cts

@@ -1,8 +1,8 @@
-import { I as ICircuitBreakerStorage, e as CircuitBreakerStateRecord } from '../payment-orchestrator-Co_X6T_V.cjs';
-export { j as CapturePaymentParams, C as CardBinRule, a as CircuitBreaker, b as CircuitBreakerConfig, c as CircuitBreakerDeps, d as CircuitBreakerState, f as CircuitState, g as ConfirmPaymentParams, h as CurrencyRule, i as InitiatePaymentParams, P as PaymentCaptureResult, k as PaymentConfirmationResult, l as PaymentInitiationResult, m as PaymentOrchestrator, n as PaymentOrchestratorDeps, o as ProviderPriorityRule, R as RoutingEngine, p as RoutingEngineDeps, q as RoutingRules, S as StoredCircuitState, r as createCircuitBreaker, s as createDefaultState, t as createPaymentOrchestrator, u as createRoutingEngine, v as getCircuitBreaker, w as getRoutingEngine, x as isCircuitOpen, y as resetCircuitBreaker, z as resetRoutingEngine, A as shouldAttemptHalfOpen } from '../payment-orchestrator-Co_X6T_V.cjs';
-import { k as PaymentProvider } from '../payment-types-68W-PlGg.cjs';
+import { I as ICircuitBreakerStorage, e as CircuitBreakerStateRecord } from '../payment-orchestrator-BmAZcr84.cjs';
+export { j as CapturePaymentParams, C as CardBinRule, a as CircuitBreaker, b as CircuitBreakerConfig, c as CircuitBreakerDeps, d as CircuitBreakerState, f as CircuitState, g as ConfirmPaymentParams, h as CurrencyRule, i as InitiatePaymentParams, P as PaymentCaptureResult, k as PaymentConfirmationResult, l as PaymentInitiationResult, m as PaymentOrchestrator, n as PaymentOrchestratorDeps, o as ProviderPriorityRule, R as RoutingEngine, p as RoutingEngineDeps, q as RoutingRules, S as StoredCircuitState, r as createCircuitBreaker, s as createDefaultState, t as createPaymentOrchestrator, u as createRoutingEngine, v as getCircuitBreaker, w as getRoutingEngine, x as isCircuitOpen, y as resetCircuitBreaker, z as resetRoutingEngine, A as shouldAttemptHalfOpen } from '../payment-orchestrator-BmAZcr84.cjs';
+import { n as PaymentProvider } from '../payment-types-DUs8IALw.cjs';
 import '../state-machine-Cu6_qKnv.cjs';
-import '../routing-engine.interface-DJzGXor9.cjs';
+import '../routing-engine.interface-B8tYJvJO.cjs';
 import '../config/index.cjs';
 
 /**

package/dist/services/index.d.ts

@@ -1,8 +1,8 @@
-import { I as ICircuitBreakerStorage, e as CircuitBreakerStateRecord } from '../payment-orchestrator-CPaLmDM5.js';
-export { j as CapturePaymentParams, C as CardBinRule, a as CircuitBreaker, b as CircuitBreakerConfig, c as CircuitBreakerDeps, d as CircuitBreakerState, f as CircuitState, g as ConfirmPaymentParams, h as CurrencyRule, i as InitiatePaymentParams, P as PaymentCaptureResult, k as PaymentConfirmationResult, l as PaymentInitiationResult, m as PaymentOrchestrator, n as PaymentOrchestratorDeps, o as ProviderPriorityRule, R as RoutingEngine, p as RoutingEngineDeps, q as RoutingRules, S as StoredCircuitState, r as createCircuitBreaker, s as createDefaultState, t as createPaymentOrchestrator, u as createRoutingEngine, v as getCircuitBreaker, w as getRoutingEngine, x as isCircuitOpen, y as resetCircuitBreaker, z as resetRoutingEngine, A as shouldAttemptHalfOpen } from '../payment-orchestrator-CPaLmDM5.js';
-import { k as PaymentProvider } from '../payment-types-68W-PlGg.js';
+import { I as ICircuitBreakerStorage, e as CircuitBreakerStateRecord } from '../payment-orchestrator-Bf2XX07D.js';
+export { j as CapturePaymentParams, C as CardBinRule, a as CircuitBreaker, b as CircuitBreakerConfig, c as CircuitBreakerDeps, d as CircuitBreakerState, f as CircuitState, g as ConfirmPaymentParams, h as CurrencyRule, i as InitiatePaymentParams, P as PaymentCaptureResult, k as PaymentConfirmationResult, l as PaymentInitiationResult, m as PaymentOrchestrator, n as PaymentOrchestratorDeps, o as ProviderPriorityRule, R as RoutingEngine, p as RoutingEngineDeps, q as RoutingRules, S as StoredCircuitState, r as createCircuitBreaker, s as createDefaultState, t as createPaymentOrchestrator, u as createRoutingEngine, v as getCircuitBreaker, w as getRoutingEngine, x as isCircuitOpen, y as resetCircuitBreaker, z as resetRoutingEngine, A as shouldAttemptHalfOpen } from '../payment-orchestrator-Bf2XX07D.js';
+import { n as PaymentProvider } from '../payment-types-DUs8IALw.js';
 import '../state-machine-Cu6_qKnv.js';
-import '../routing-engine.interface-h9_GmQ4b.js';
+import '../routing-engine.interface-BrhDxYN6.js';
 import '../config/index.js';
 
 /**

package/dist/types/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/index.ts","../../src/types/state-machine.ts","../../src/types/webhook-types.ts"],"sourcesContent":["/**\r\n * @nehorai/payments - Type Exports\r\n *\r\n * Central export for all payment system types.\r\n */\r\n\r\n// Core payment types\r\nexport type {\r\n  PaymentProvider,\r\n  TransactionType,\r\n  TaxInvoiceStatus,\r\n  PaymentMethodType,\r\n  CardBrand,\r\n  PaymentAmount,\r\n  CurrencyConversion,\r\n  CreatePaymentIntentParams,\r\n  PaymentIntentResult,\r\n  AuthorizePaymentParams,\r\n  AuthorizationResult,\r\n  CapturePaymentParams,\r\n  CaptureResult,\r\n  VoidPaymentParams,\r\n  VoidResult,\r\n  RefundParams,\r\n  RefundResult,\r\n  PaymentMetadata,\r\n  ProviderMetadata,\r\n  ProviderHealthStatus,\r\n  PaymentErrorCode,\r\n  PaymentError,\r\n} from './payment-types.js';\r\n\r\n// State machine types\r\nexport type {\r\n  TransactionStatus,\r\n  TransactionEvent,\r\n  StateTransitionResult,\r\n} from './state-machine.js';\r\n\r\nexport {\r\n  TERMINAL_STATES,\r\n  SUCCESS_STATES,\r\n  HOLD_STATES,\r\n  VALID_TRANSITIONS,\r\n  DEFAULT_AUTH_HOLD_DAYS,\r\n  canTransition,\r\n  getNextStatus,\r\n  isTerminalState,\r\n  isSuccessState,\r\n  isHoldState,\r\n  canRefund,\r\n  canCapture,\r\n  canVoid,\r\n  attemptTransition,\r\n  calculateCaptureDeadline,\r\n  isAuthorizationExpired,\r\n} from './state-machine.js';\r\n\r\n// Webhook types\r\nexport type {\r\n  WebhookStatus,\r\n  WebhookEvent,\r\n  WebhookProcessingResult,\r\n  WebhookAction,\r\n  StripeEventType,\r\n  WebhookVerificationParams,\r\n  WebhookVerificationResult,\r\n  WebhookQueueMessage,\r\n  QueueProcessingResult,\r\n  ReconciliationResult,\r\n  ReconciliationStrategy,\r\n} from './webhook-types.js';\r\n\r\nexport { STRIPE_EVENT_TO_STATUS } from './webhook-types.js';\r\n","/**\r\n * @nehorai/payments - Transaction State Machine\r\n *\r\n * Defines the strict state transitions for payment transactions.\r\n * Implements the J5 (Two-Phase Commit) pattern for authorize/capture flows.\r\n *\r\n * State Flow:\r\n * +-------------------------------------------------------------+\r\n * |  CREATED --------------------------------------------------+ |\r\n * |     |                                                  |   |\r\n * |     v                                                  v   |\r\n * |  PENDING_AUTHORIZATION -----------------------------> FAILED |\r\n * |     |                                                  ^   |\r\n * |     v                                                  |   |\r\n * |  AUTHORIZED ---------> VOIDED                          |   |\r\n * |     |                                                  |   |\r\n * |     +----------------> EXPIRED ------------------------+   |\r\n * |     |                                                  |   |\r\n * |     v                                                  |   |\r\n * |  CAPTURING --------------------------------------------+   |\r\n * |     |                                                      |\r\n * |     v                                                      |\r\n * |  CAPTURED ------> PARTIALLY_REFUNDED ------> FULLY_REFUNDED |\r\n * +-------------------------------------------------------------+\r\n */\r\n\r\n// ============================================================================\r\n// Transaction States\r\n// ============================================================================\r\n\r\n/**\r\n * All possible transaction states\r\n */\r\nexport type TransactionStatus =\r\n  | 'created'\r\n  | 'pending_authorization'\r\n  | 'authorized'\r\n  | 'capturing'\r\n  | 'captured'\r\n  | 'voided'\r\n  | 'failed'\r\n  | 'expired'\r\n  | 'partially_refunded'\r\n  | 'fully_refunded';\r\n\r\n/**\r\n * Terminal states - no further transitions possible\r\n */\r\nexport const TERMINAL_STATES: readonly TransactionStatus[] = [\r\n  'voided',\r\n  'failed',\r\n  'expired',\r\n  'fully_refunded',\r\n] as const;\r\n\r\n/**\r\n * States that indicate successful completion\r\n */\r\nexport const SUCCESS_STATES: readonly TransactionStatus[] = [\r\n  'captured',\r\n  'partially_refunded',\r\n  'fully_refunded',\r\n] as const;\r\n\r\n/**\r\n * States where funds are held but not captured\r\n */\r\nexport const HOLD_STATES: readonly TransactionStatus[] = [\r\n  'authorized',\r\n] as const;\r\n\r\n// ============================================================================\r\n// Transaction Events\r\n// ============================================================================\r\n\r\n/**\r\n * Events that trigger state transitions\r\n */\r\nexport type TransactionEvent =\r\n  | 'INITIATE'\r\n  | 'AUTHORIZE_PENDING'\r\n  | 'AUTHORIZE_SUCCESS'\r\n  | 'AUTHORIZE_FAILED'\r\n  | 'CAPTURE_STARTED'\r\n  | 'CAPTURE_SUCCESS'\r\n  | 'CAPTURE_FAILED'\r\n  | 'VOID_SUCCESS'\r\n  | 'VOID_FAILED'\r\n  | 'EXPIRED'\r\n  | 'PARTIAL_REFUND'\r\n  | 'FULL_REFUND';\r\n\r\n// ============================================================================\r\n// State Transition Map\r\n// ============================================================================\r\n\r\n/**\r\n * Valid transitions from each state\r\n */\r\nexport const VALID_TRANSITIONS: Record<TransactionStatus, TransactionEvent[]> = {\r\n  created: ['INITIATE', 'AUTHORIZE_PENDING', 'AUTHORIZE_FAILED'],\r\n  pending_authorization: ['AUTHORIZE_SUCCESS', 'AUTHORIZE_FAILED', 'EXPIRED'],\r\n  authorized: ['CAPTURE_STARTED', 'VOID_SUCCESS', 'VOID_FAILED', 'EXPIRED'],\r\n  capturing: ['CAPTURE_SUCCESS', 'CAPTURE_FAILED'],\r\n  captured: ['PARTIAL_REFUND', 'FULL_REFUND'],\r\n  voided: [], // Terminal state\r\n  failed: [], // Terminal state\r\n  expired: [], // Terminal state\r\n  partially_refunded: ['PARTIAL_REFUND', 'FULL_REFUND'],\r\n  fully_refunded: [], // Terminal state\r\n};\r\n\r\n/**\r\n * Event to next state mapping\r\n */\r\nconst EVENT_TO_STATE: Record<TransactionEvent, TransactionStatus> = {\r\n  INITIATE: 'pending_authorization',\r\n  AUTHORIZE_PENDING: 'pending_authorization',\r\n  AUTHORIZE_SUCCESS: 'authorized',\r\n  AUTHORIZE_FAILED: 'failed',\r\n  CAPTURE_STARTED: 'capturing',\r\n  CAPTURE_SUCCESS: 'captured',\r\n  CAPTURE_FAILED: 'failed',\r\n  VOID_SUCCESS: 'voided',\r\n  VOID_FAILED: 'authorized', // Remain authorized if void fails\r\n  EXPIRED: 'expired',\r\n  PARTIAL_REFUND: 'partially_refunded',\r\n  FULL_REFUND: 'fully_refunded',\r\n};\r\n\r\n// ============================================================================\r\n// State Machine Functions\r\n// ============================================================================\r\n\r\n/**\r\n * Check if a transition is valid\r\n */\r\nexport function canTransition(\r\n  currentStatus: TransactionStatus,\r\n  event: TransactionEvent\r\n): boolean {\r\n  return VALID_TRANSITIONS[currentStatus].includes(event);\r\n}\r\n\r\n/**\r\n * Get the next state after an event, or null if transition is invalid\r\n */\r\nexport function getNextStatus(\r\n  currentStatus: TransactionStatus,\r\n  event: TransactionEvent\r\n): TransactionStatus | null {\r\n  if (!canTransition(currentStatus, event)) {\r\n    return null;\r\n  }\r\n  return EVENT_TO_STATE[event];\r\n}\r\n\r\n/**\r\n * Check if a state is terminal (no further transitions)\r\n */\r\nexport function isTerminalState(status: TransactionStatus): boolean {\r\n  return TERMINAL_STATES.includes(status);\r\n}\r\n\r\n/**\r\n * Check if a state represents a successful payment\r\n */\r\nexport function isSuccessState(status: TransactionStatus): boolean {\r\n  return SUCCESS_STATES.includes(status);\r\n}\r\n\r\n/**\r\n * Check if funds are currently held (authorized but not captured)\r\n */\r\nexport function isHoldState(status: TransactionStatus): boolean {\r\n  return HOLD_STATES.includes(status);\r\n}\r\n\r\n/**\r\n * Check if a refund is possible from current state\r\n */\r\nexport function canRefund(status: TransactionStatus): boolean {\r\n  return status === 'captured' || status === 'partially_refunded';\r\n}\r\n\r\n/**\r\n * Check if capture is possible from current state\r\n */\r\nexport function canCapture(status: TransactionStatus): boolean {\r\n  return status === 'authorized';\r\n}\r\n\r\n/**\r\n * Check if void is possible from current state\r\n */\r\nexport function canVoid(status: TransactionStatus): boolean {\r\n  return status === 'authorized';\r\n}\r\n\r\n// ============================================================================\r\n// State Transition Result Types\r\n// ============================================================================\r\n\r\n/**\r\n * Result of a state transition attempt\r\n */\r\nexport interface StateTransitionResult {\r\n  success: boolean;\r\n  previousStatus: TransactionStatus;\r\n  newStatus: TransactionStatus;\r\n  event: TransactionEvent;\r\n  error?: string;\r\n}\r\n\r\n/**\r\n * Attempt a state transition with validation\r\n */\r\nexport function attemptTransition(\r\n  currentStatus: TransactionStatus,\r\n  event: TransactionEvent\r\n): StateTransitionResult {\r\n  const nextStatus = getNextStatus(currentStatus, event);\r\n\r\n  if (nextStatus === null) {\r\n    return {\r\n      success: false,\r\n      previousStatus: currentStatus,\r\n      newStatus: currentStatus,\r\n      event,\r\n      error: `Invalid transition: ${currentStatus} -> ${event}`,\r\n    };\r\n  }\r\n\r\n  return {\r\n    success: true,\r\n    previousStatus: currentStatus,\r\n    newStatus: nextStatus,\r\n    event,\r\n  };\r\n}\r\n\r\n// ============================================================================\r\n// Authorization Expiry\r\n// ============================================================================\r\n\r\n/**\r\n * Default authorization hold period (7 days for most providers)\r\n */\r\nexport const DEFAULT_AUTH_HOLD_DAYS = 7;\r\n\r\n/**\r\n * Calculate capture deadline from authorization time\r\n */\r\nexport function calculateCaptureDeadline(\r\n  authorizedAt: Date,\r\n  holdDays: number = DEFAULT_AUTH_HOLD_DAYS\r\n): Date {\r\n  const deadline = new Date(authorizedAt);\r\n  deadline.setDate(deadline.getDate() + holdDays);\r\n  return deadline;\r\n}\r\n\r\n/**\r\n * Check if authorization has expired\r\n */\r\nexport function isAuthorizationExpired(captureDeadline: Date): boolean {\r\n  return new Date() > captureDeadline;\r\n}\r\n","/**\r\n * @nehorai/payments - Webhook Types\r\n *\r\n * Types for processing incoming webhooks from payment providers.\r\n * Includes signature verification and idempotent event handling.\r\n */\r\n\r\nimport type { PaymentProvider } from './payment-types.js';\r\nimport type { TransactionStatus } from './state-machine.js';\r\n\r\n// ============================================================================\r\n// Webhook Event Types\r\n// ============================================================================\r\n\r\n/**\r\n * Status of webhook processing\r\n */\r\nexport type WebhookStatus =\r\n  | 'pending'\r\n  | 'processing'\r\n  | 'processed'\r\n  | 'failed'\r\n  | 'ignored';\r\n\r\n/**\r\n * Incoming webhook event from any provider\r\n */\r\nexport interface WebhookEvent {\r\n  /** Source payment provider */\r\n  provider: PaymentProvider;\r\n  /** Provider's unique event ID (for idempotency) */\r\n  eventId: string;\r\n  /** Type of event (e.g., 'payment_intent.succeeded') */\r\n  eventType: string;\r\n  /** When the event occurred */\r\n  timestamp: Date;\r\n  /** Raw event payload */\r\n  payload: Record<string, unknown>;\r\n  /** Signature from provider for verification */\r\n  signature: string;\r\n}\r\n\r\n/**\r\n * Result of processing a webhook event\r\n */\r\nexport interface WebhookProcessingResult {\r\n  success: boolean;\r\n  /** Associated transaction ID if applicable */\r\n  transactionId?: string;\r\n  /** What action was taken */\r\n  action?: WebhookAction;\r\n  /** Error message if failed */\r\n  error?: string;\r\n  /** Whether this was a duplicate event */\r\n  wasDuplicate?: boolean;\r\n}\r\n\r\n/**\r\n * Actions taken when processing webhooks\r\n */\r\nexport type WebhookAction =\r\n  | 'transaction_created'\r\n  | 'status_updated'\r\n  | 'refund_processed'\r\n  | 'dispute_created'\r\n  | 'skipped_duplicate'\r\n  | 'ignored_event_type'\r\n  | 'no_action_needed';\r\n\r\n// ============================================================================\r\n// Provider-Specific Event Types\r\n// ============================================================================\r\n\r\n/**\r\n * Stripe webhook event types we handle\r\n */\r\nexport type StripeEventType =\r\n  | 'payment_intent.created'\r\n  | 'payment_intent.processing'\r\n  | 'payment_intent.succeeded'\r\n  | 'payment_intent.payment_failed'\r\n  | 'payment_intent.canceled'\r\n  | 'payment_intent.amount_capturable_updated'\r\n  | 'charge.succeeded'\r\n  | 'charge.failed'\r\n  | 'charge.refunded'\r\n  | 'charge.dispute.created'\r\n  | 'charge.dispute.closed'\r\n  | 'customer.subscription.created'\r\n  | 'customer.subscription.updated'\r\n  | 'customer.subscription.deleted'\r\n  | 'invoice.paid'\r\n  | 'invoice.payment_failed';\r\n\r\n/**\r\n * Map of Stripe events to transaction status updates\r\n */\r\nexport const STRIPE_EVENT_TO_STATUS: Partial<Record<StripeEventType, TransactionStatus>> = {\r\n  'payment_intent.succeeded': 'captured',\r\n  'payment_intent.payment_failed': 'failed',\r\n  'payment_intent.canceled': 'voided',\r\n  'payment_intent.amount_capturable_updated': 'authorized',\r\n  'charge.refunded': 'partially_refunded', // or fully_refunded based on amount\r\n};\r\n\r\n// ============================================================================\r\n// Webhook Signature Verification\r\n// ============================================================================\r\n\r\n/**\r\n * Parameters for verifying webhook signature\r\n */\r\nexport interface WebhookVerificationParams {\r\n  payload: string;\r\n  signature: string;\r\n  secret: string;\r\n  /** Tolerance in seconds for timestamp validation */\r\n  tolerance?: number;\r\n}\r\n\r\n/**\r\n * Result of webhook signature verification\r\n */\r\nexport interface WebhookVerificationResult {\r\n  valid: boolean;\r\n  error?: string;\r\n}\r\n\r\n// ============================================================================\r\n// Webhook Queue Types (for SQS processing)\r\n// ============================================================================\r\n\r\n/**\r\n * Message format for webhook queue\r\n */\r\nexport interface WebhookQueueMessage {\r\n  /** Message ID for deduplication */\r\n  messageId: string;\r\n  /** Provider that sent the webhook */\r\n  provider: PaymentProvider;\r\n  /** Provider's event ID */\r\n  eventId: string;\r\n  /** Event type */\r\n  eventType: string;\r\n  /** Raw payload (JSON string) */\r\n  payload: string;\r\n  /** Signature for verification */\r\n  signature: string;\r\n  /** When received by our API */\r\n  receivedAt: string;\r\n  /** Number of processing attempts */\r\n  attemptCount: number;\r\n}\r\n\r\n/**\r\n * Result of queue message processing\r\n */\r\nexport interface QueueProcessingResult {\r\n  success: boolean;\r\n  messageId: string;\r\n  action?: WebhookAction;\r\n  shouldDelete: boolean;\r\n  shouldRetry: boolean;\r\n  error?: string;\r\n}\r\n\r\n// ============================================================================\r\n// Reconciliation Types\r\n// ============================================================================\r\n\r\n/**\r\n * Result of reconciling payment state\r\n * Handles race condition between redirect and webhook\r\n */\r\nexport interface ReconciliationResult {\r\n  reconciled: boolean;\r\n  /** Final determined status */\r\n  finalStatus: TransactionStatus;\r\n  /** Source of truth (redirect callback vs webhook) */\r\n  source: 'redirect' | 'webhook' | 'provider_query';\r\n  /** Whether status was updated */\r\n  statusChanged: boolean;\r\n}\r\n\r\n/**\r\n * Reconciliation strategy when redirect and webhook conflict\r\n */\r\nexport type ReconciliationStrategy =\r\n  | 'prefer_webhook'      // Wait for webhook (more reliable)\r\n  | 'prefer_redirect'     // Use redirect result immediately\r\n  | 'query_provider';     // Query provider API directly\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgDO,IAAM,kBAAgD;AAAA,EAC3D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAKO,IAAM,iBAA+C;AAAA,EAC1D;AAAA,EACA;AAAA,EACA;AACF;AAKO,IAAM,cAA4C;AAAA,EACvD;AACF;AA8BO,IAAM,oBAAmE;AAAA,EAC9E,SAAS,CAAC,YAAY,qBAAqB,kBAAkB;AAAA,EAC7D,uBAAuB,CAAC,qBAAqB,oBAAoB,SAAS;AAAA,EAC1E,YAAY,CAAC,mBAAmB,gBAAgB,eAAe,SAAS;AAAA,EACxE,WAAW,CAAC,mBAAmB,gBAAgB;AAAA,EAC/C,UAAU,CAAC,kBAAkB,aAAa;AAAA,EAC1C,QAAQ,CAAC;AAAA;AAAA,EACT,QAAQ,CAAC;AAAA;AAAA,EACT,SAAS,CAAC;AAAA;AAAA,EACV,oBAAoB,CAAC,kBAAkB,aAAa;AAAA,EACpD,gBAAgB,CAAC;AAAA;AACnB;AAKA,IAAM,iBAA8D;AAAA,EAClE,UAAU;AAAA,EACV,mBAAmB;AAAA,EACnB,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,iBAAiB;AAAA,EACjB,iBAAiB;AAAA,EACjB,gBAAgB;AAAA,EAChB,cAAc;AAAA,EACd,aAAa;AAAA;AAAA,EACb,SAAS;AAAA,EACT,gBAAgB;AAAA,EAChB,aAAa;AACf;AASO,SAAS,cACd,eACA,OACS;AACT,SAAO,kBAAkB,aAAa,EAAE,SAAS,KAAK;AACxD;AAKO,SAAS,cACd,eACA,OAC0B;AAC1B,MAAI,CAAC,cAAc,eAAe,KAAK,GAAG;AACxC,WAAO;AAAA,EACT;AACA,SAAO,eAAe,KAAK;AAC7B;AAKO,SAAS,gBAAgB,QAAoC;AAClE,SAAO,gBAAgB,SAAS,MAAM;AACxC;AAKO,SAAS,eAAe,QAAoC;AACjE,SAAO,eAAe,SAAS,MAAM;AACvC;AAKO,SAAS,YAAY,QAAoC;AAC9D,SAAO,YAAY,SAAS,MAAM;AACpC;AAKO,SAAS,UAAU,QAAoC;AAC5D,SAAO,WAAW,cAAc,WAAW;AAC7C;AAKO,SAAS,WAAW,QAAoC;AAC7D,SAAO,WAAW;AACpB;AAKO,SAAS,QAAQ,QAAoC;AAC1D,SAAO,WAAW;AACpB;AAoBO,SAAS,kBACd,eACA,OACuB;AACvB,QAAM,aAAa,cAAc,eAAe,KAAK;AAErD,MAAI,eAAe,MAAM;AACvB,WAAO;AAAA,MACL,SAAS;AAAA,MACT,gBAAgB;AAAA,MAChB,WAAW;AAAA,MACX;AAAA,MACA,OAAO,uBAAuB,aAAa,OAAO,KAAK;AAAA,IACzD;AAAA,EACF;AAEA,SAAO;AAAA,IACL,SAAS;AAAA,IACT,gBAAgB;AAAA,IAChB,WAAW;AAAA,IACX;AAAA,EACF;AACF;AASO,IAAM,yBAAyB;AAK/B,SAAS,yBACd,cACA,WAAmB,wBACb;AACN,QAAM,WAAW,IAAI,KAAK,YAAY;AACtC,WAAS,QAAQ,SAAS,QAAQ,IAAI,QAAQ;AAC9C,SAAO;AACT;AAKO,SAAS,uBAAuB,iBAAgC;AACrE,SAAO,oBAAI,KAAK,IAAI;AACtB;;;AC1KO,IAAM,yBAA8E;AAAA,EACzF,4BAA4B;AAAA,EAC5B,iCAAiC;AAAA,EACjC,2BAA2B;AAAA,EAC3B,4CAA4C;AAAA,EAC5C,mBAAmB;AAAA;AACrB;","names":[]}
+{"version":3,"sources":["../../src/types/index.ts","../../src/types/state-machine.ts","../../src/types/webhook-types.ts"],"sourcesContent":["/**\r\n * @nehorai/payments - Type Exports\r\n *\r\n * Central export for all payment system types.\r\n */\r\n\r\n// Core payment types\r\nexport type {\r\n  PaymentProvider,\r\n  TransactionType,\r\n  TaxInvoiceStatus,\r\n  PaymentMethodType,\r\n  CardBrand,\r\n  PaymentAmount,\r\n  CurrencyConversion,\r\n  CreatePaymentIntentParams,\r\n  PaymentIntentResult,\r\n  AuthorizePaymentParams,\r\n  AuthorizationResult,\r\n  CapturePaymentParams,\r\n  CaptureResult,\r\n  VoidPaymentParams,\r\n  VoidResult,\r\n  RefundParams,\r\n  RefundResult,\r\n  PaymentMetadata,\r\n  ProviderMetadata,\r\n  ProviderHealthStatus,\r\n  PaymentErrorCode,\r\n  PaymentError,\r\n  SubscriptionStatus,\r\n  SubscriptionInterval,\r\n  CreateSubscriptionParams,\r\n  SubscriptionResult,\r\n  CancelSubscriptionParams,\r\n  CancelSubscriptionResult,\r\n} from './payment-types.js';\r\n\r\n// State machine types\r\nexport type {\r\n  TransactionStatus,\r\n  TransactionEvent,\r\n  StateTransitionResult,\r\n} from './state-machine.js';\r\n\r\nexport {\r\n  TERMINAL_STATES,\r\n  SUCCESS_STATES,\r\n  HOLD_STATES,\r\n  VALID_TRANSITIONS,\r\n  DEFAULT_AUTH_HOLD_DAYS,\r\n  canTransition,\r\n  getNextStatus,\r\n  isTerminalState,\r\n  isSuccessState,\r\n  isHoldState,\r\n  canRefund,\r\n  canCapture,\r\n  canVoid,\r\n  attemptTransition,\r\n  calculateCaptureDeadline,\r\n  isAuthorizationExpired,\r\n} from './state-machine.js';\r\n\r\n// Webhook types\r\nexport type {\r\n  WebhookStatus,\r\n  WebhookEvent,\r\n  WebhookProcessingResult,\r\n  WebhookAction,\r\n  StripeEventType,\r\n  WebhookVerificationParams,\r\n  WebhookVerificationResult,\r\n  WebhookQueueMessage,\r\n  QueueProcessingResult,\r\n  ReconciliationResult,\r\n  ReconciliationStrategy,\r\n} from './webhook-types.js';\r\n\r\nexport { STRIPE_EVENT_TO_STATUS } from './webhook-types.js';\r\n","/**\r\n * @nehorai/payments - Transaction State Machine\r\n *\r\n * Defines the strict state transitions for payment transactions.\r\n * Implements the J5 (Two-Phase Commit) pattern for authorize/capture flows.\r\n *\r\n * State Flow:\r\n * +-------------------------------------------------------------+\r\n * |  CREATED --------------------------------------------------+ |\r\n * |     |                                                  |   |\r\n * |     v                                                  v   |\r\n * |  PENDING_AUTHORIZATION -----------------------------> FAILED |\r\n * |     |                                                  ^   |\r\n * |     v                                                  |   |\r\n * |  AUTHORIZED ---------> VOIDED                          |   |\r\n * |     |                                                  |   |\r\n * |     +----------------> EXPIRED ------------------------+   |\r\n * |     |                                                  |   |\r\n * |     v                                                  |   |\r\n * |  CAPTURING --------------------------------------------+   |\r\n * |     |                                                      |\r\n * |     v                                                      |\r\n * |  CAPTURED ------> PARTIALLY_REFUNDED ------> FULLY_REFUNDED |\r\n * +-------------------------------------------------------------+\r\n */\r\n\r\n// ============================================================================\r\n// Transaction States\r\n// ============================================================================\r\n\r\n/**\r\n * All possible transaction states\r\n */\r\nexport type TransactionStatus =\r\n  | 'created'\r\n  | 'pending_authorization'\r\n  | 'authorized'\r\n  | 'capturing'\r\n  | 'captured'\r\n  | 'voided'\r\n  | 'failed'\r\n  | 'expired'\r\n  | 'partially_refunded'\r\n  | 'fully_refunded';\r\n\r\n/**\r\n * Terminal states - no further transitions possible\r\n */\r\nexport const TERMINAL_STATES: readonly TransactionStatus[] = [\r\n  'voided',\r\n  'failed',\r\n  'expired',\r\n  'fully_refunded',\r\n] as const;\r\n\r\n/**\r\n * States that indicate successful completion\r\n */\r\nexport const SUCCESS_STATES: readonly TransactionStatus[] = [\r\n  'captured',\r\n  'partially_refunded',\r\n  'fully_refunded',\r\n] as const;\r\n\r\n/**\r\n * States where funds are held but not captured\r\n */\r\nexport const HOLD_STATES: readonly TransactionStatus[] = [\r\n  'authorized',\r\n] as const;\r\n\r\n// ============================================================================\r\n// Transaction Events\r\n// ============================================================================\r\n\r\n/**\r\n * Events that trigger state transitions\r\n */\r\nexport type TransactionEvent =\r\n  | 'INITIATE'\r\n  | 'AUTHORIZE_PENDING'\r\n  | 'AUTHORIZE_SUCCESS'\r\n  | 'AUTHORIZE_FAILED'\r\n  | 'CAPTURE_STARTED'\r\n  | 'CAPTURE_SUCCESS'\r\n  | 'CAPTURE_FAILED'\r\n  | 'VOID_SUCCESS'\r\n  | 'VOID_FAILED'\r\n  | 'EXPIRED'\r\n  | 'PARTIAL_REFUND'\r\n  | 'FULL_REFUND';\r\n\r\n// ============================================================================\r\n// State Transition Map\r\n// ============================================================================\r\n\r\n/**\r\n * Valid transitions from each state\r\n */\r\nexport const VALID_TRANSITIONS: Record<TransactionStatus, TransactionEvent[]> = {\r\n  created: ['INITIATE', 'AUTHORIZE_PENDING', 'AUTHORIZE_FAILED'],\r\n  pending_authorization: ['AUTHORIZE_SUCCESS', 'AUTHORIZE_FAILED', 'EXPIRED'],\r\n  authorized: ['CAPTURE_STARTED', 'VOID_SUCCESS', 'VOID_FAILED', 'EXPIRED'],\r\n  capturing: ['CAPTURE_SUCCESS', 'CAPTURE_FAILED'],\r\n  captured: ['PARTIAL_REFUND', 'FULL_REFUND'],\r\n  voided: [], // Terminal state\r\n  failed: [], // Terminal state\r\n  expired: [], // Terminal state\r\n  partially_refunded: ['PARTIAL_REFUND', 'FULL_REFUND'],\r\n  fully_refunded: [], // Terminal state\r\n};\r\n\r\n/**\r\n * Event to next state mapping\r\n */\r\nconst EVENT_TO_STATE: Record<TransactionEvent, TransactionStatus> = {\r\n  INITIATE: 'pending_authorization',\r\n  AUTHORIZE_PENDING: 'pending_authorization',\r\n  AUTHORIZE_SUCCESS: 'authorized',\r\n  AUTHORIZE_FAILED: 'failed',\r\n  CAPTURE_STARTED: 'capturing',\r\n  CAPTURE_SUCCESS: 'captured',\r\n  CAPTURE_FAILED: 'failed',\r\n  VOID_SUCCESS: 'voided',\r\n  VOID_FAILED: 'authorized', // Remain authorized if void fails\r\n  EXPIRED: 'expired',\r\n  PARTIAL_REFUND: 'partially_refunded',\r\n  FULL_REFUND: 'fully_refunded',\r\n};\r\n\r\n// ============================================================================\r\n// State Machine Functions\r\n// ============================================================================\r\n\r\n/**\r\n * Check if a transition is valid\r\n */\r\nexport function canTransition(\r\n  currentStatus: TransactionStatus,\r\n  event: TransactionEvent\r\n): boolean {\r\n  return VALID_TRANSITIONS[currentStatus].includes(event);\r\n}\r\n\r\n/**\r\n * Get the next state after an event, or null if transition is invalid\r\n */\r\nexport function getNextStatus(\r\n  currentStatus: TransactionStatus,\r\n  event: TransactionEvent\r\n): TransactionStatus | null {\r\n  if (!canTransition(currentStatus, event)) {\r\n    return null;\r\n  }\r\n  return EVENT_TO_STATE[event];\r\n}\r\n\r\n/**\r\n * Check if a state is terminal (no further transitions)\r\n */\r\nexport function isTerminalState(status: TransactionStatus): boolean {\r\n  return TERMINAL_STATES.includes(status);\r\n}\r\n\r\n/**\r\n * Check if a state represents a successful payment\r\n */\r\nexport function isSuccessState(status: TransactionStatus): boolean {\r\n  return SUCCESS_STATES.includes(status);\r\n}\r\n\r\n/**\r\n * Check if funds are currently held (authorized but not captured)\r\n */\r\nexport function isHoldState(status: TransactionStatus): boolean {\r\n  return HOLD_STATES.includes(status);\r\n}\r\n\r\n/**\r\n * Check if a refund is possible from current state\r\n */\r\nexport function canRefund(status: TransactionStatus): boolean {\r\n  return status === 'captured' || status === 'partially_refunded';\r\n}\r\n\r\n/**\r\n * Check if capture is possible from current state\r\n */\r\nexport function canCapture(status: TransactionStatus): boolean {\r\n  return status === 'authorized';\r\n}\r\n\r\n/**\r\n * Check if void is possible from current state\r\n */\r\nexport function canVoid(status: TransactionStatus): boolean {\r\n  return status === 'authorized';\r\n}\r\n\r\n// ============================================================================\r\n// State Transition Result Types\r\n// ============================================================================\r\n\r\n/**\r\n * Result of a state transition attempt\r\n */\r\nexport interface StateTransitionResult {\r\n  success: boolean;\r\n  previousStatus: TransactionStatus;\r\n  newStatus: TransactionStatus;\r\n  event: TransactionEvent;\r\n  error?: string;\r\n}\r\n\r\n/**\r\n * Attempt a state transition with validation\r\n */\r\nexport function attemptTransition(\r\n  currentStatus: TransactionStatus,\r\n  event: TransactionEvent\r\n): StateTransitionResult {\r\n  const nextStatus = getNextStatus(currentStatus, event);\r\n\r\n  if (nextStatus === null) {\r\n    return {\r\n      success: false,\r\n      previousStatus: currentStatus,\r\n      newStatus: currentStatus,\r\n      event,\r\n      error: `Invalid transition: ${currentStatus} -> ${event}`,\r\n    };\r\n  }\r\n\r\n  return {\r\n    success: true,\r\n    previousStatus: currentStatus,\r\n    newStatus: nextStatus,\r\n    event,\r\n  };\r\n}\r\n\r\n// ============================================================================\r\n// Authorization Expiry\r\n// ============================================================================\r\n\r\n/**\r\n * Default authorization hold period (7 days for most providers)\r\n */\r\nexport const DEFAULT_AUTH_HOLD_DAYS = 7;\r\n\r\n/**\r\n * Calculate capture deadline from authorization time\r\n */\r\nexport function calculateCaptureDeadline(\r\n  authorizedAt: Date,\r\n  holdDays: number = DEFAULT_AUTH_HOLD_DAYS\r\n): Date {\r\n  const deadline = new Date(authorizedAt);\r\n  deadline.setDate(deadline.getDate() + holdDays);\r\n  return deadline;\r\n}\r\n\r\n/**\r\n * Check if authorization has expired\r\n */\r\nexport function isAuthorizationExpired(captureDeadline: Date): boolean {\r\n  return new Date() > captureDeadline;\r\n}\r\n","/**\r\n * @nehorai/payments - Webhook Types\r\n *\r\n * Types for processing incoming webhooks from payment providers.\r\n * Includes signature verification and idempotent event handling.\r\n */\r\n\r\nimport type { PaymentProvider } from './payment-types.js';\r\nimport type { TransactionStatus } from './state-machine.js';\r\n\r\n// ============================================================================\r\n// Webhook Event Types\r\n// ============================================================================\r\n\r\n/**\r\n * Status of webhook processing\r\n */\r\nexport type WebhookStatus =\r\n  | 'pending'\r\n  | 'processing'\r\n  | 'processed'\r\n  | 'failed'\r\n  | 'ignored';\r\n\r\n/**\r\n * Incoming webhook event from any provider\r\n */\r\nexport interface WebhookEvent {\r\n  /** Source payment provider */\r\n  provider: PaymentProvider;\r\n  /** Provider's unique event ID (for idempotency) */\r\n  eventId: string;\r\n  /** Type of event (e.g., 'payment_intent.succeeded') */\r\n  eventType: string;\r\n  /** When the event occurred */\r\n  timestamp: Date;\r\n  /** Raw event payload */\r\n  payload: Record<string, unknown>;\r\n  /** Signature from provider for verification */\r\n  signature: string;\r\n}\r\n\r\n/**\r\n * Result of processing a webhook event\r\n */\r\nexport interface WebhookProcessingResult {\r\n  success: boolean;\r\n  /** Associated transaction ID if applicable */\r\n  transactionId?: string;\r\n  /** What action was taken */\r\n  action?: WebhookAction;\r\n  /** Error message if failed */\r\n  error?: string;\r\n  /** Whether this was a duplicate event */\r\n  wasDuplicate?: boolean;\r\n}\r\n\r\n/**\r\n * Actions taken when processing webhooks\r\n */\r\nexport type WebhookAction =\r\n  | 'transaction_created'\r\n  | 'status_updated'\r\n  | 'refund_processed'\r\n  | 'dispute_created'\r\n  | 'skipped_duplicate'\r\n  | 'ignored_event_type'\r\n  | 'no_action_needed';\r\n\r\n// ============================================================================\r\n// Provider-Specific Event Types\r\n// ============================================================================\r\n\r\n/**\r\n * Stripe webhook event types we handle\r\n */\r\nexport type StripeEventType =\r\n  | 'payment_intent.created'\r\n  | 'payment_intent.processing'\r\n  | 'payment_intent.succeeded'\r\n  | 'payment_intent.payment_failed'\r\n  | 'payment_intent.canceled'\r\n  | 'payment_intent.amount_capturable_updated'\r\n  | 'charge.succeeded'\r\n  | 'charge.failed'\r\n  | 'charge.refunded'\r\n  | 'charge.dispute.created'\r\n  | 'charge.dispute.closed'\r\n  | 'customer.subscription.created'\r\n  | 'customer.subscription.updated'\r\n  | 'customer.subscription.deleted'\r\n  | 'invoice.paid'\r\n  | 'invoice.payment_failed';\r\n\r\n/**\r\n * Map of Stripe events to transaction status updates\r\n */\r\nexport const STRIPE_EVENT_TO_STATUS: Partial<Record<StripeEventType, TransactionStatus>> = {\r\n  'payment_intent.succeeded': 'captured',\r\n  'payment_intent.payment_failed': 'failed',\r\n  'payment_intent.canceled': 'voided',\r\n  'payment_intent.amount_capturable_updated': 'authorized',\r\n  'charge.refunded': 'partially_refunded', // or fully_refunded based on amount\r\n};\r\n\r\n// ============================================================================\r\n// Webhook Signature Verification\r\n// ============================================================================\r\n\r\n/**\r\n * Parameters for verifying webhook signature\r\n */\r\nexport interface WebhookVerificationParams {\r\n  payload: string;\r\n  signature: string;\r\n  secret: string;\r\n  /** Tolerance in seconds for timestamp validation */\r\n  tolerance?: number;\r\n}\r\n\r\n/**\r\n * Result of webhook signature verification\r\n */\r\nexport interface WebhookVerificationResult {\r\n  valid: boolean;\r\n  error?: string;\r\n}\r\n\r\n// ============================================================================\r\n// Webhook Queue Types (for SQS processing)\r\n// ============================================================================\r\n\r\n/**\r\n * Message format for webhook queue\r\n */\r\nexport interface WebhookQueueMessage {\r\n  /** Message ID for deduplication */\r\n  messageId: string;\r\n  /** Provider that sent the webhook */\r\n  provider: PaymentProvider;\r\n  /** Provider's event ID */\r\n  eventId: string;\r\n  /** Event type */\r\n  eventType: string;\r\n  /** Raw payload (JSON string) */\r\n  payload: string;\r\n  /** Signature for verification */\r\n  signature: string;\r\n  /** When received by our API */\r\n  receivedAt: string;\r\n  /** Number of processing attempts */\r\n  attemptCount: number;\r\n}\r\n\r\n/**\r\n * Result of queue message processing\r\n */\r\nexport interface QueueProcessingResult {\r\n  success: boolean;\r\n  messageId: string;\r\n  action?: WebhookAction;\r\n  shouldDelete: boolean;\r\n  shouldRetry: boolean;\r\n  error?: string;\r\n}\r\n\r\n// ============================================================================\r\n// Reconciliation Types\r\n// ============================================================================\r\n\r\n/**\r\n * Result of reconciling payment state\r\n * Handles race condition between redirect and webhook\r\n */\r\nexport interface ReconciliationResult {\r\n  reconciled: boolean;\r\n  /** Final determined status */\r\n  finalStatus: TransactionStatus;\r\n  /** Source of truth (redirect callback vs webhook) */\r\n  source: 'redirect' | 'webhook' | 'provider_query';\r\n  /** Whether status was updated */\r\n  statusChanged: boolean;\r\n}\r\n\r\n/**\r\n * Reconciliation strategy when redirect and webhook conflict\r\n */\r\nexport type ReconciliationStrategy =\r\n  | 'prefer_webhook'      // Wait for webhook (more reliable)\r\n  | 'prefer_redirect'     // Use redirect result immediately\r\n  | 'query_provider';     // Query provider API directly\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgDO,IAAM,kBAAgD;AAAA,EAC3D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAKO,IAAM,iBAA+C;AAAA,EAC1D;AAAA,EACA;AAAA,EACA;AACF;AAKO,IAAM,cAA4C;AAAA,EACvD;AACF;AA8BO,IAAM,oBAAmE;AAAA,EAC9E,SAAS,CAAC,YAAY,qBAAqB,kBAAkB;AAAA,EAC7D,uBAAuB,CAAC,qBAAqB,oBAAoB,SAAS;AAAA,EAC1E,YAAY,CAAC,mBAAmB,gBAAgB,eAAe,SAAS;AAAA,EACxE,WAAW,CAAC,mBAAmB,gBAAgB;AAAA,EAC/C,UAAU,CAAC,kBAAkB,aAAa;AAAA,EAC1C,QAAQ,CAAC;AAAA;AAAA,EACT,QAAQ,CAAC;AAAA;AAAA,EACT,SAAS,CAAC;AAAA;AAAA,EACV,oBAAoB,CAAC,kBAAkB,aAAa;AAAA,EACpD,gBAAgB,CAAC;AAAA;AACnB;AAKA,IAAM,iBAA8D;AAAA,EAClE,UAAU;AAAA,EACV,mBAAmB;AAAA,EACnB,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,iBAAiB;AAAA,EACjB,iBAAiB;AAAA,EACjB,gBAAgB;AAAA,EAChB,cAAc;AAAA,EACd,aAAa;AAAA;AAAA,EACb,SAAS;AAAA,EACT,gBAAgB;AAAA,EAChB,aAAa;AACf;AASO,SAAS,cACd,eACA,OACS;AACT,SAAO,kBAAkB,aAAa,EAAE,SAAS,KAAK;AACxD;AAKO,SAAS,cACd,eACA,OAC0B;AAC1B,MAAI,CAAC,cAAc,eAAe,KAAK,GAAG;AACxC,WAAO;AAAA,EACT;AACA,SAAO,eAAe,KAAK;AAC7B;AAKO,SAAS,gBAAgB,QAAoC;AAClE,SAAO,gBAAgB,SAAS,MAAM;AACxC;AAKO,SAAS,eAAe,QAAoC;AACjE,SAAO,eAAe,SAAS,MAAM;AACvC;AAKO,SAAS,YAAY,QAAoC;AAC9D,SAAO,YAAY,SAAS,MAAM;AACpC;AAKO,SAAS,UAAU,QAAoC;AAC5D,SAAO,WAAW,cAAc,WAAW;AAC7C;AAKO,SAAS,WAAW,QAAoC;AAC7D,SAAO,WAAW;AACpB;AAKO,SAAS,QAAQ,QAAoC;AAC1D,SAAO,WAAW;AACpB;AAoBO,SAAS,kBACd,eACA,OACuB;AACvB,QAAM,aAAa,cAAc,eAAe,KAAK;AAErD,MAAI,eAAe,MAAM;AACvB,WAAO;AAAA,MACL,SAAS;AAAA,MACT,gBAAgB;AAAA,MAChB,WAAW;AAAA,MACX;AAAA,MACA,OAAO,uBAAuB,aAAa,OAAO,KAAK;AAAA,IACzD;AAAA,EACF;AAEA,SAAO;AAAA,IACL,SAAS;AAAA,IACT,gBAAgB;AAAA,IAChB,WAAW;AAAA,IACX;AAAA,EACF;AACF;AASO,IAAM,yBAAyB;AAK/B,SAAS,yBACd,cACA,WAAmB,wBACb;AACN,QAAM,WAAW,IAAI,KAAK,YAAY;AACtC,WAAS,QAAQ,SAAS,QAAQ,IAAI,QAAQ;AAC9C,SAAO;AACT;AAKO,SAAS,uBAAuB,iBAAgC;AACrE,SAAO,oBAAI,KAAK,IAAI;AACtB;;;AC1KO,IAAM,yBAA8E;AAAA,EACzF,4BAA4B;AAAA,EAC5B,iCAAiC;AAAA,EACjC,2BAA2B;AAAA,EAC3B,4CAA4C;AAAA,EAC5C,mBAAmB;AAAA;AACrB;","names":[]}