@nehorai/payments 0.1.0

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

@@ -0,0 +1,556 @@
+/**
+ * @nehorai/payments Repository - Base Interfaces
+ *
+ * Common types and base interface for all repositories.
+ * Framework-agnostic - works with any database adapter.
+ */
+/**
+ * Pagination parameters
+ */
+interface PaginationParams {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Paginated response wrapper
+ */
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+/**
+ * Date range filter
+ */
+interface DateRangeFilter {
+    from?: Date;
+    to?: Date;
+}
+/**
+ * Sort direction
+ */
+type SortDirection = 'asc' | 'desc';
+/**
+ * Sort parameter
+ */
+interface SortParam<T extends string = string> {
+    field: T;
+    direction: SortDirection;
+}
+/**
+ * Base repository interface with common CRUD operations
+ */
+interface IBaseRepository<T, TCreate, TUpdate, TId = string> {
+    /**
+     * Find entity by ID
+     */
+    findById(id: TId): Promise<T | null>;
+    /**
+     * Create new entity
+     */
+    create(data: TCreate): Promise<T>;
+    /**
+     * Update existing entity
+     */
+    update(id: TId, data: TUpdate): Promise<T | null>;
+    /**
+     * Delete entity by ID
+     */
+    delete(id: TId): Promise<boolean>;
+}
+
+/**
+ * @nehorai/payments Repository - Transaction Interface
+ *
+ * Defines operations for payment transaction persistence.
+ * Implement this interface to integrate with your database.
+ */
+
+/**
+ * Transaction status (maps to state machine)
+ */
+type TransactionStatus = 'created' | 'pending_authorization' | 'authorized' | 'capturing' | 'captured' | 'voided' | 'failed' | 'expired' | 'partially_refunded' | 'fully_refunded';
+/**
+ * Transaction type
+ */
+type TransactionType = 'one_time_purchase' | 'subscription_initial' | 'subscription_renewal' | 'refund';
+/**
+ * Tax invoice status
+ */
+type TaxInvoiceStatus = 'pending' | 'generated' | 'sent' | 'failed';
+/**
+ * Provider name - generic string identifier
+ */
+type ProviderName = string;
+/**
+ * Transaction entity
+ */
+interface Transaction {
+    id: string;
+    internalPaymentId: string;
+    idempotencyKey: string | null;
+    userId: string;
+    transactionType: TransactionType;
+    status: TransactionStatus;
+    amountMinor: number;
+    currency: string;
+    originalAmountMinor: number | null;
+    originalCurrency: string | null;
+    currencyConversionRate: number | null;
+    provider: ProviderName;
+    providerTransactionId: string | null;
+    providerAuthorizationCode: string | null;
+    providerMetadata: Record<string, unknown> | null;
+    authorizedAt: Date | null;
+    capturedAt: Date | null;
+    voidedAt: Date | null;
+    captureDeadline: Date | null;
+    refundedAmountMinor: number;
+    lastRefundAt: Date | null;
+    taxInvoiceStatus: TaxInvoiceStatus;
+    taxInvoiceNumber: string | null;
+    taxInvoiceUrl: string | null;
+    failureCode: string | null;
+    failureMessage: string | null;
+    failureDetails: Record<string, unknown> | null;
+    description: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Create transaction input
+ */
+interface CreateTransactionInput {
+    internalPaymentId: string;
+    idempotencyKey?: string;
+    userId: string;
+    transactionType: TransactionType;
+    status?: TransactionStatus;
+    amountMinor: number;
+    currency: string;
+    provider: ProviderName;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Update transaction input
+ */
+interface UpdateTransactionInput {
+    status?: TransactionStatus;
+    providerTransactionId?: string;
+    providerAuthorizationCode?: string;
+    providerMetadata?: Record<string, unknown>;
+    authorizedAt?: Date;
+    capturedAt?: Date;
+    voidedAt?: Date;
+    captureDeadline?: Date;
+    refundedAmountMinor?: number;
+    lastRefundAt?: Date;
+    taxInvoiceStatus?: TaxInvoiceStatus;
+    taxInvoiceNumber?: string;
+    taxInvoiceUrl?: string;
+    failureCode?: string;
+    failureMessage?: string;
+    failureDetails?: Record<string, unknown>;
+}
+/**
+ * Transaction filter options
+ */
+interface TransactionFilter {
+    userId?: string;
+    status?: TransactionStatus | TransactionStatus[];
+    provider?: ProviderName | ProviderName[];
+    transactionType?: TransactionType | TransactionType[];
+    dateRange?: DateRangeFilter;
+}
+/**
+ * Transaction repository interface
+ */
+interface ITransactionRepository extends IBaseRepository<Transaction, CreateTransactionInput, UpdateTransactionInput> {
+    /**
+     * Find transaction by internal payment ID
+     */
+    findByInternalPaymentId(internalPaymentId: string): Promise<Transaction | null>;
+    /**
+     * Find transaction by idempotency key
+     */
+    findByIdempotencyKey(idempotencyKey: string): Promise<Transaction | null>;
+    /**
+     * Find transaction by provider transaction ID
+     */
+    findByProviderTransactionId(provider: ProviderName, providerTransactionId: string): Promise<Transaction | null>;
+    /**
+     * Find transactions with filters and pagination
+     */
+    findMany(filter: TransactionFilter, pagination?: PaginationParams): Promise<PaginatedResult<Transaction>>;
+    /**
+     * Find transactions by user ID
+     */
+    findByUserId(userId: string, pagination?: PaginationParams): Promise<PaginatedResult<Transaction>>;
+    /**
+     * Update transaction status (with validation)
+     */
+    updateStatus(id: string, status: TransactionStatus, additionalData?: Partial<UpdateTransactionInput>): Promise<Transaction | null>;
+    /**
+     * Increment refunded amount
+     */
+    incrementRefundedAmount(id: string, amountMinor: number): Promise<Transaction | null>;
+    /**
+     * Find expired authorizations (for cleanup)
+     */
+    findExpiredAuthorizations(beforeDate: Date): Promise<Transaction[]>;
+    /**
+     * Count transactions by status
+     */
+    countByStatus(filter?: TransactionFilter): Promise<Record<TransactionStatus, number>>;
+}
+
+/**
+ * @nehorai/payments Repository - Payment Method Interface
+ *
+ * Defines operations for saved payment method persistence.
+ * Implement this interface to integrate with your database.
+ */
+
+/**
+ * Payment method type
+ */
+type PaymentMethodType = 'card' | 'bank_account' | 'paypal';
+/**
+ * Card brand
+ */
+type CardBrand = 'visa' | 'mastercard' | 'amex' | 'discover' | 'isracard' | 'diners' | 'unknown';
+/**
+ * Payment method entity
+ */
+interface PaymentMethod {
+    id: string;
+    userId: string;
+    type: PaymentMethodType;
+    provider: ProviderName;
+    providerPaymentMethodId: string;
+    cardBrand: CardBrand | null;
+    cardLast4: string | null;
+    cardExpMonth: string | null;
+    cardExpYear: string | null;
+    cardBin: string | null;
+    isDefault: boolean;
+    isActive: boolean;
+    providerMetadata: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+    lastUsedAt: Date | null;
+}
+/**
+ * Create payment method input
+ */
+interface CreatePaymentMethodInput {
+    userId: string;
+    type: PaymentMethodType;
+    provider: ProviderName;
+    providerPaymentMethodId: string;
+    cardBrand?: CardBrand;
+    cardLast4?: string;
+    cardExpMonth?: string;
+    cardExpYear?: string;
+    cardBin?: string;
+    isDefault?: boolean;
+    providerMetadata?: Record<string, unknown>;
+}
+/**
+ * Update payment method input
+ */
+interface UpdatePaymentMethodInput {
+    isDefault?: boolean;
+    isActive?: boolean;
+    cardExpMonth?: string;
+    cardExpYear?: string;
+    lastUsedAt?: Date;
+    providerMetadata?: Record<string, unknown>;
+}
+/**
+ * Payment method filter options
+ */
+interface PaymentMethodFilter {
+    userId?: string;
+    provider?: ProviderName | ProviderName[];
+    type?: PaymentMethodType | PaymentMethodType[];
+    isDefault?: boolean;
+    isActive?: boolean;
+    cardBin?: string;
+}
+/**
+ * Payment method repository interface
+ */
+interface IPaymentMethodRepository extends IBaseRepository<PaymentMethod, CreatePaymentMethodInput, UpdatePaymentMethodInput> {
+    findByProviderPaymentMethodId(provider: ProviderName, providerPaymentMethodId: string): Promise<PaymentMethod | null>;
+    findByUserId(userId: string, filter?: Partial<PaymentMethodFilter>): Promise<PaymentMethod[]>;
+    findDefaultForUser(userId: string): Promise<PaymentMethod | null>;
+    findMany(filter: PaymentMethodFilter, pagination?: PaginationParams): Promise<PaginatedResult<PaymentMethod>>;
+    setAsDefault(id: string, userId: string): Promise<PaymentMethod | null>;
+    deactivate(id: string): Promise<boolean>;
+    markAsUsed(id: string): Promise<PaymentMethod | null>;
+    findByCardBin(userId: string, cardBin: string): Promise<PaymentMethod[]>;
+    countActiveForUser(userId: string): Promise<number>;
+}
+
+/**
+ * @nehorai/payments Repository - Webhook Event Interface
+ *
+ * Defines operations for webhook event persistence.
+ * Used for idempotent webhook processing.
+ */
+
+/**
+ * Webhook event processing status
+ */
+type WebhookEventStatus = 'pending' | 'processing' | 'processed' | 'failed' | 'ignored';
+/**
+ * Webhook event entity
+ */
+interface WebhookEvent {
+    id: string;
+    provider: ProviderName;
+    providerEventId: string;
+    eventType: string;
+    status: WebhookEventStatus;
+    attempts: number;
+    lastAttemptAt: Date | null;
+    transactionId: string | null;
+    payload: Record<string, unknown>;
+    signature: string | null;
+    errorMessage: string | null;
+    errorDetails: Record<string, unknown> | null;
+    receivedAt: Date;
+    processedAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Create webhook event input
+ */
+interface CreateWebhookEventInput {
+    provider: ProviderName;
+    providerEventId: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+    signature?: string;
+}
+/**
+ * Update webhook event input
+ */
+interface UpdateWebhookEventInput {
+    status?: WebhookEventStatus;
+    attempts?: number;
+    lastAttemptAt?: Date;
+    transactionId?: string;
+    processedAt?: Date;
+    errorMessage?: string;
+    errorDetails?: Record<string, unknown>;
+}
+/**
+ * Webhook event filter options
+ */
+interface WebhookEventFilter {
+    provider?: ProviderName | ProviderName[];
+    eventType?: string | string[];
+    status?: WebhookEventStatus | WebhookEventStatus[];
+    transactionId?: string;
+    dateRange?: DateRangeFilter;
+}
+/**
+ * Webhook event repository interface
+ */
+interface IWebhookEventRepository extends IBaseRepository<WebhookEvent, CreateWebhookEventInput, UpdateWebhookEventInput> {
+    findByProviderEventId(provider: ProviderName, providerEventId: string): Promise<WebhookEvent | null>;
+    findByTransactionId(transactionId: string): Promise<WebhookEvent[]>;
+    findMany(filter: WebhookEventFilter, pagination?: PaginationParams): Promise<PaginatedResult<WebhookEvent>>;
+    findFailedForRetry(maxAttempts: number, olderThan?: Date): Promise<WebhookEvent[]>;
+    findPending(limit?: number): Promise<WebhookEvent[]>;
+    markAsProcessing(id: string): Promise<boolean>;
+    markAsProcessed(id: string, transactionId?: string): Promise<WebhookEvent | null>;
+    markAsFailed(id: string, errorMessage: string, errorDetails?: Record<string, unknown>): Promise<WebhookEvent | null>;
+    incrementAttempts(id: string): Promise<WebhookEvent | null>;
+    isAlreadyProcessed(provider: ProviderName, providerEventId: string): Promise<boolean>;
+    countByStatus(filter?: WebhookEventFilter): Promise<Record<WebhookEventStatus, number>>;
+}
+
+/**
+ * @nehorai/payments Repository - Audit Log Interface
+ *
+ * Defines operations for payment audit log persistence.
+ * Audit logs are immutable - only create and read operations.
+ */
+
+/**
+ * Audit log action types
+ */
+type AuditLogAction = 'created' | 'status_changed' | 'authorized' | 'captured' | 'voided' | 'refund_initiated' | 'refund_completed' | 'webhook_received' | 'webhook_processed' | 'error_occurred' | 'retry_attempted' | 'manual_intervention';
+/**
+ * Who/what triggered the action
+ */
+type AuditLogTrigger = 'user' | 'webhook' | 'system' | 'admin' | 'cron' | 'api';
+/**
+ * Audit log entity
+ */
+interface AuditLogEntry {
+    id: string;
+    transactionId: string;
+    action: AuditLogAction;
+    previousState: Record<string, unknown> | null;
+    newState: Record<string, unknown>;
+    triggeredBy: AuditLogTrigger;
+    triggeredById: string | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    correlationId: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+}
+/**
+ * Create audit log entry input
+ */
+interface CreateAuditLogInput {
+    transactionId: string;
+    action: AuditLogAction;
+    previousState?: Record<string, unknown>;
+    newState: Record<string, unknown>;
+    triggeredBy: AuditLogTrigger;
+    triggeredById?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    correlationId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Audit log filter options
+ */
+interface AuditLogFilter {
+    transactionId?: string;
+    action?: AuditLogAction | AuditLogAction[];
+    triggeredBy?: AuditLogTrigger | AuditLogTrigger[];
+    triggeredById?: string;
+    correlationId?: string;
+    dateRange?: DateRangeFilter;
+}
+/**
+ * Audit log repository interface
+ * Note: Audit logs are immutable - no update or delete operations
+ */
+interface IAuditLogRepository {
+    findById(id: string): Promise<AuditLogEntry | null>;
+    create(data: CreateAuditLogInput): Promise<AuditLogEntry>;
+    createMany(entries: CreateAuditLogInput[]): Promise<AuditLogEntry[]>;
+    findByTransactionId(transactionId: string, pagination?: PaginationParams): Promise<PaginatedResult<AuditLogEntry>>;
+    findMany(filter: AuditLogFilter, pagination?: PaginationParams): Promise<PaginatedResult<AuditLogEntry>>;
+    findByCorrelationId(correlationId: string): Promise<AuditLogEntry[]>;
+    getTransactionHistory(transactionId: string): Promise<AuditLogEntry[]>;
+    countByAction(filter?: AuditLogFilter): Promise<Record<AuditLogAction, number>>;
+}
+
+/**
+ * @nehorai/payments Repository - Provider Health Interface
+ *
+ * Defines operations for provider health/circuit breaker persistence.
+ * Used for tracking provider availability and performance.
+ */
+
+/**
+ * Circuit breaker states
+ */
+type CircuitBreakerState = 'closed' | 'open' | 'half_open';
+/**
+ * Health check result
+ */
+interface HealthCheckResult {
+    healthy: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+/**
+ * Provider health entity
+ */
+interface ProviderHealth {
+    id: string;
+    provider: ProviderName;
+    circuitState: CircuitBreakerState;
+    failureCount: number;
+    successCount: number;
+    lastFailureAt: Date | null;
+    lastSuccessAt: Date | null;
+    circuitOpenedAt: Date | null;
+    nextRetryAt: Date | null;
+    avgLatencyMs: number | null;
+    errorRate: number | null;
+    requestCountWindow: number;
+    lastHealthCheckAt: Date | null;
+    healthCheckResult: HealthCheckResult | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Create provider health input
+ */
+interface CreateProviderHealthInput {
+    provider: ProviderName;
+    circuitState?: CircuitBreakerState;
+}
+/**
+ * Update provider health input
+ */
+interface UpdateProviderHealthInput {
+    circuitState?: CircuitBreakerState;
+    failureCount?: number;
+    successCount?: number;
+    lastFailureAt?: Date;
+    lastSuccessAt?: Date;
+    circuitOpenedAt?: Date;
+    nextRetryAt?: Date;
+    avgLatencyMs?: number;
+    errorRate?: number;
+    requestCountWindow?: number;
+    lastHealthCheckAt?: Date;
+    healthCheckResult?: HealthCheckResult;
+}
+/**
+ * Provider health repository interface
+ */
+interface IProviderHealthRepository {
+    findByProvider(provider: ProviderName): Promise<ProviderHealth | null>;
+    getOrCreate(provider: ProviderName): Promise<ProviderHealth>;
+    update(provider: ProviderName, data: UpdateProviderHealthInput): Promise<ProviderHealth | null>;
+    findAll(): Promise<ProviderHealth[]>;
+    recordSuccess(provider: ProviderName, latencyMs: number): Promise<void>;
+    recordFailure(provider: ProviderName, error?: string): Promise<void>;
+    openCircuit(provider: ProviderName, retryAfterMs: number): Promise<void>;
+    closeCircuit(provider: ProviderName): Promise<void>;
+    halfOpenCircuit(provider: ProviderName): Promise<void>;
+    updateHealthCheck(provider: ProviderName, result: HealthCheckResult): Promise<void>;
+    findOpenCircuits(): Promise<ProviderHealth[]>;
+    findReadyForRetry(): Promise<ProviderHealth[]>;
+    resetStats(provider: ProviderName): Promise<void>;
+    updateErrorRate(provider: ProviderName): Promise<number>;
+}
+
+/**
+ * @nehorai/payments Repository - Interface Exports
+ *
+ * All repository interfaces for database-agnostic payment operations.
+ * Implement these interfaces to integrate with your database.
+ */
+
+/**
+ * Combined repository interface for all payment operations.
+ * Implement this interface to provide a complete database adapter.
+ */
+interface IPaymentRepositories {
+    transactions: ITransactionRepository;
+    paymentMethods: IPaymentMethodRepository;
+    webhookEvents: IWebhookEventRepository;
+    auditLog: IAuditLogRepository;
+    providerHealth: IProviderHealthRepository;
+}
+
+export type { AuditLogAction, AuditLogEntry, AuditLogFilter, AuditLogTrigger, CardBrand, CircuitBreakerState, CreateAuditLogInput, CreatePaymentMethodInput, CreateProviderHealthInput, CreateTransactionInput, CreateWebhookEventInput, DateRangeFilter, HealthCheckResult, IAuditLogRepository, IBaseRepository, IPaymentMethodRepository, IPaymentRepositories, IProviderHealthRepository, ITransactionRepository, IWebhookEventRepository, PaginatedResult, PaginationParams, PaymentMethod, PaymentMethodFilter, PaymentMethodType, ProviderHealth, ProviderName, SortDirection, SortParam, TaxInvoiceStatus, Transaction, TransactionFilter, TransactionStatus, TransactionType, UpdatePaymentMethodInput, UpdateProviderHealthInput, UpdateTransactionInput, UpdateWebhookEventInput, WebhookEvent, WebhookEventFilter, WebhookEventStatus };

package/dist/repository/interfaces/index.js

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

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

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