@nehorai/payments 0.1.0 → 0.2.0

package/dist/types/index.d.cts

@@ -1,5 +1,5 @@
-import { k as PaymentProvider } from '../payment-types-68W-PlGg.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, 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';
+import { n as PaymentProvider } from '../payment-types-DUs8IALw.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, 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';
 import { c as TransactionStatus } from '../state-machine-Cu6_qKnv.cjs';
 export { D as DEFAULT_AUTH_HOLD_DAYS, H as HOLD_STATES, S as SUCCESS_STATES, a as StateTransitionResult, T as TERMINAL_STATES, b as TransactionEvent, V as VALID_TRANSITIONS, 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';
 

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
-import { k as PaymentProvider } from '../payment-types-68W-PlGg.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, 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';
+import { n as PaymentProvider } from '../payment-types-DUs8IALw.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, 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';
 import { c as TransactionStatus } from '../state-machine-Cu6_qKnv.js';
 export { D as DEFAULT_AUTH_HOLD_DAYS, H as HOLD_STATES, S as SUCCESS_STATES, a as StateTransitionResult, T as TERMINAL_STATES, b as TransactionEvent, V as VALID_TRANSITIONS, 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';
 

package/dist/utils/index.d.cts

@@ -1,4 +1,4 @@
-import { k as PaymentProvider } from '../payment-types-68W-PlGg.cjs';
+import { n as PaymentProvider } from '../payment-types-DUs8IALw.cjs';
 
 /**
  * @nehorai/payments - Idempotency Utilities

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { k as PaymentProvider } from '../payment-types-68W-PlGg.js';
+import { n as PaymentProvider } from '../payment-types-DUs8IALw.js';
 
 /**
  * @nehorai/payments - Idempotency Utilities

package/dist/webhook-handler.interface-BP_Ew2Mu.d.ts

@@ -0,0 +1,79 @@
+import { n as PaymentProvider } from './payment-types-DUs8IALw.js';
+import { c as TransactionStatus } from './state-machine-Cu6_qKnv.js';
+import { WebhookProcessingResult, ReconciliationResult } from './types/index.js';
+
+/**
+ * @nehorai/payments - Webhook Handler Interface
+ *
+ * Defines the contract for processing incoming webhooks from payment providers.
+ * Handles idempotency, reconciliation, and event-to-action mapping.
+ */
+
+/**
+ * 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
+ *
+ * Provider-specific webhook handlers implement this interface.
+ * Enables consistent webhook processing across all providers.
+ */
+interface IWebhookHandler {
+    /**
+     * Provider this handler is for
+     */
+    readonly provider: PaymentProvider;
+    /**
+     * Event types this handler can process
+     */
+    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;
+}
+
+export type { EventHandler as E, IWebhookHandler as I, ParseWebhookResult as P, EventHandlerMap as a, ParsedWebhookEvent as b };

package/dist/webhook-handler.interface-Dq9hNM80.d.cts

@@ -0,0 +1,79 @@
+import { n as PaymentProvider } from './payment-types-DUs8IALw.cjs';
+import { c as TransactionStatus } from './state-machine-Cu6_qKnv.cjs';
+import { WebhookProcessingResult, ReconciliationResult } from './types/index.cjs';
+
+/**
+ * @nehorai/payments - Webhook Handler Interface
+ *
+ * Defines the contract for processing incoming webhooks from payment providers.
+ * Handles idempotency, reconciliation, and event-to-action mapping.
+ */
+
+/**
+ * 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
+ *
+ * Provider-specific webhook handlers implement this interface.
+ * Enables consistent webhook processing across all providers.
+ */
+interface IWebhookHandler {
+    /**
+     * Provider this handler is for
+     */
+    readonly provider: PaymentProvider;
+    /**
+     * Event types this handler can process
+     */
+    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;
+}
+
+export type { EventHandler as E, IWebhookHandler as I, ParseWebhookResult as P, EventHandlerMap as a, ParsedWebhookEvent as b };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nehorai/payments",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Generic payment orchestration library with circuit breaker and multi-provider routing",
   "type": "module",
   "main": "./dist/index.js",