@nehorai/payments 0.1.0

package/dist/payment-types-68W-PlGg.d.ts

@@ -0,0 +1,211 @@
+/**
+ * @nehorai/payments - Core Payment Types
+ *
+ * Defines the fundamental types for the payment system.
+ * Follows TypeScript conventions with literal union types.
+ */
+/**
+ * Supported payment providers - extensible string identifier
+ */
+type PaymentProvider = string;
+/**
+ * Types of payment transactions
+ */
+type TransactionType = 'one_time_purchase' | 'subscription_initial' | 'subscription_renewal' | 'refund';
+/**
+ * Tax invoice status
+ */
+type TaxInvoiceStatus = 'pending' | 'generated' | 'sent' | 'failed';
+/**
+ * Payment method types
+ */
+type PaymentMethodType = 'card' | 'bank_account' | 'paypal';
+/**
+ * Card brands supported
+ */
+type CardBrand = 'visa' | 'mastercard' | 'amex' | 'discover' | 'isracard' | 'diners' | 'unknown';
+/**
+ * Monetary amount in smallest currency unit (cents, agorot, etc.)
+ * Zero Trust: All amounts validated server-side, never trust client
+ */
+interface PaymentAmount {
+    /** Amount in smallest currency unit (e.g., 1000 = $10.00) */
+    amountMinor: number;
+    /** ISO 4217 currency code (e.g., 'USD', 'ILS') */
+    currency: string;
+}
+/**
+ * Result of currency conversion
+ */
+interface CurrencyConversion {
+    originalAmount: PaymentAmount;
+    convertedAmount: PaymentAmount;
+    exchangeRate: number;
+    convertedAt: Date;
+}
+/**
+ * Parameters for creating a payment intent
+ */
+interface CreatePaymentIntentParams {
+    amount: PaymentAmount;
+    userId: string;
+    idempotencyKey: string;
+    description?: string;
+    metadata?: PaymentMetadata;
+    returnUrl?: string;
+    paymentMethodId?: string;
+    /** If true, only authorize (J5 hold), don't capture */
+    captureMethod?: 'automatic' | 'manual';
+}
+/**
+ * Result from creating a payment intent
+ */
+interface PaymentIntentResult {
+    success: boolean;
+    /** Provider's payment intent ID */
+    providerIntentId?: string;
+    /** Client secret for frontend SDK (Stripe Elements) */
+    clientSecret?: string;
+    /** Redirect URL for redirect-based flows */
+    redirectUrl?: string;
+    /** Current status of the payment */
+    status?: string;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * Parameters for authorizing a payment (J5 hold)
+ */
+interface AuthorizePaymentParams {
+    providerIntentId: string;
+    idempotencyKey: string;
+}
+/**
+ * Result from authorization
+ */
+interface AuthorizationResult {
+    success: boolean;
+    /** Authorization code for capture */
+    authorizationCode?: string;
+    status?: string;
+    /** Deadline to capture before auth expires (typically 7 days) */
+    captureDeadline?: Date;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * Parameters for capturing an authorized payment
+ */
+interface CapturePaymentParams {
+    providerIntentId: string;
+    authorizationCode: string;
+    /** For partial capture */
+    amount?: PaymentAmount;
+    idempotencyKey: string;
+}
+/**
+ * Result from capture
+ */
+interface CaptureResult {
+    success: boolean;
+    providerTransactionId?: string;
+    status?: string;
+    capturedAmount?: PaymentAmount;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * Parameters for voiding an authorization
+ */
+interface VoidPaymentParams {
+    providerIntentId: string;
+    authorizationCode: string;
+    idempotencyKey: string;
+    reason?: string;
+}
+/**
+ * Result from void
+ */
+interface VoidResult {
+    success: boolean;
+    status?: string;
+    error?: string;
+}
+/**
+ * Parameters for refunding a payment
+ */
+interface RefundParams {
+    providerTransactionId: string;
+    /** For partial refund */
+    amount?: PaymentAmount;
+    reason?: string;
+    idempotencyKey: string;
+}
+/**
+ * Result from refund
+ */
+interface RefundResult {
+    success: boolean;
+    providerRefundId?: string;
+    refundedAmount?: PaymentAmount;
+    status?: 'pending' | 'succeeded' | 'failed';
+    error?: string;
+}
+/**
+ * Application-specific metadata attached to payments
+ */
+interface PaymentMetadata {
+    /** Credit package being purchased */
+    creditPackageId?: string;
+    /** Subscription plan being purchased */
+    subscriptionPlanId?: string;
+    /** Number of credits being purchased */
+    creditsAmount?: number;
+    /** Custom fields */
+    [key: string]: unknown;
+}
+/**
+ * Provider-specific metadata (raw response data)
+ */
+interface ProviderMetadata {
+    /** Raw response from provider for debugging */
+    rawResponse?: Record<string, unknown>;
+    /** Provider-specific transaction ID */
+    providerTransactionId?: string;
+    /** Provider-specific authorization code */
+    authorizationCode?: string;
+    /** Additional provider data */
+    [key: string]: unknown;
+}
+/**
+ * Provider health status for circuit breaker
+ */
+interface ProviderHealthStatus {
+    provider: PaymentProvider;
+    healthy: boolean;
+    lastChecked: Date;
+    /** Average response time in milliseconds */
+    avgLatencyMs?: number;
+    /** Error rate (0-1) */
+    errorRate?: number;
+    /** Whether circuit breaker is open */
+    circuitBreakerOpen: boolean;
+    /** When circuit breaker will attempt to close */
+    nextRetryAt?: Date;
+}
+/**
+ * Standardized payment error codes
+ */
+type PaymentErrorCode = 'insufficient_funds' | 'invalid_card' | 'expired_card' | 'card_declined' | 'processing_error' | 'provider_timeout' | 'provider_unavailable' | 'rate_limit' | 'webhook_signature_invalid' | 'idempotency_conflict' | 'invalid_amount' | 'invalid_currency' | 'authentication_required' | 'unknown';
+/**
+ * Payment error with structured information
+ */
+interface PaymentError {
+    code: PaymentErrorCode;
+    message: string;
+    provider?: PaymentProvider;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}
+
+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 };

package/dist/providers/interfaces/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/providers/interfaces/index.ts
+var interfaces_exports = {};
+module.exports = __toCommonJS(interfaces_exports);
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +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":[]}

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

@@ -0,0 +1,80 @@
+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';
+
+/**
+ * @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, EventHandlerMap, IWebhookHandler, ParseWebhookResult, ParsedWebhookEvent };

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

@@ -0,0 +1,80 @@
+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';
+
+/**
+ * @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, EventHandlerMap, IWebhookHandler, ParseWebhookResult, ParsedWebhookEvent };

package/dist/providers/interfaces/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/repository/interfaces/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/repository/interfaces/index.ts
+var interfaces_exports = {};
+module.exports = __toCommonJS(interfaces_exports);
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/repository/interfaces/index.ts"],"sourcesContent":["/**\r\n * @nehorai/payments Repository - Interface Exports\r\n *\r\n * All repository interfaces for database-agnostic payment operations.\r\n * Implement these interfaces to integrate with your database.\r\n */\r\n\r\n// ============================================================================\r\n// Imports for Aggregate Interface\r\n// ============================================================================\r\n\r\nimport type { ITransactionRepository } from './transaction.repository.js'\r\nimport type { IPaymentMethodRepository } from './payment-method.repository.js'\r\nimport type { IWebhookEventRepository } from './webhook-event.repository.js'\r\nimport type { IAuditLogRepository } from './audit-log.repository.js'\r\nimport type { IProviderHealthRepository } from './provider-health.repository.js'\r\n\r\n// ============================================================================\r\n// Base Types\r\n// ============================================================================\r\n\r\nexport type {\r\n  PaginationParams,\r\n  PaginatedResult,\r\n  DateRangeFilter,\r\n  SortDirection,\r\n  SortParam,\r\n  IBaseRepository,\r\n} from './base.interface.js'\r\n\r\n// ============================================================================\r\n// Transaction Repository\r\n// ============================================================================\r\n\r\nexport type {\r\n  TransactionStatus,\r\n  TransactionType,\r\n  TaxInvoiceStatus,\r\n  ProviderName,\r\n  Transaction,\r\n  CreateTransactionInput,\r\n  UpdateTransactionInput,\r\n  TransactionFilter,\r\n  ITransactionRepository,\r\n} from './transaction.repository.js'\r\n\r\n// ============================================================================\r\n// Payment Method Repository\r\n// ============================================================================\r\n\r\nexport type {\r\n  PaymentMethodType,\r\n  CardBrand,\r\n  PaymentMethod,\r\n  CreatePaymentMethodInput,\r\n  UpdatePaymentMethodInput,\r\n  PaymentMethodFilter,\r\n  IPaymentMethodRepository,\r\n} from './payment-method.repository.js'\r\n\r\n// ============================================================================\r\n// Webhook Event Repository\r\n// ============================================================================\r\n\r\nexport type {\r\n  WebhookEventStatus,\r\n  WebhookEvent,\r\n  CreateWebhookEventInput,\r\n  UpdateWebhookEventInput,\r\n  WebhookEventFilter,\r\n  IWebhookEventRepository,\r\n} from './webhook-event.repository.js'\r\n\r\n// ============================================================================\r\n// Audit Log Repository\r\n// ============================================================================\r\n\r\nexport type {\r\n  AuditLogAction,\r\n  AuditLogTrigger,\r\n  AuditLogEntry,\r\n  CreateAuditLogInput,\r\n  AuditLogFilter,\r\n  IAuditLogRepository,\r\n} from './audit-log.repository.js'\r\n\r\n// ============================================================================\r\n// Provider Health Repository\r\n// ============================================================================\r\n\r\nexport type {\r\n  CircuitBreakerState,\r\n  HealthCheckResult,\r\n  ProviderHealth,\r\n  CreateProviderHealthInput,\r\n  UpdateProviderHealthInput,\r\n  IProviderHealthRepository,\r\n} from './provider-health.repository.js'\r\n\r\n// ============================================================================\r\n// Aggregate Repository Interface\r\n// ============================================================================\r\n\r\n/**\r\n * Combined repository interface for all payment operations.\r\n * Implement this interface to provide a complete database adapter.\r\n */\r\nexport interface IPaymentRepositories {\r\n  transactions: ITransactionRepository\r\n  paymentMethods: IPaymentMethodRepository\r\n  webhookEvents: IWebhookEventRepository\r\n  auditLog: IAuditLogRepository\r\n  providerHealth: IProviderHealthRepository\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}