@revstackhq/providers-core 0.0.0-dev-20260209034148

package/LICENSE

@@ -0,0 +1,38 @@
+BUSINESS SOURCE LICENSE 1.1
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and make use of the Licensed Work for any purpose, except as limited by the Additional Use Grant below.
+
+Redistribution is allowed only if this License is included with the Licensed Work and any derivative works.
+
+ADDITIONAL USE GRANT:
+
+You may make use of the Licensed Work, provided that you do not use the Licensed Work to provide a "Managed Payment Orchestration Service".
+
+A "Managed Payment Orchestration Service" is defined as a commercial service, product, or offering where the Licensed Work is used to provide payment routing, checkout orchestration, or connection management to third parties as a service (SaaS, PaaS, or IaaS), whether for a fee or free of charge.
+
+For clarity:
+1. You MAY use the Licensed Work internally to process payments for your own business or merchandise.
+2. You MAY NOT use the Licensed Work to build a competitor service to Revstack that allows your customers to orchestrate their own payments.
+
+CHANGE DATE:
+
+January 1, 2031
+
+CHANGE LICENSE:
+
+Apache License, Version 2.0
+
+ERROR CORRECTIONS AND SECURITY UPDATES:
+
+The Licensor may, at its option, provide error corrections and security updates to the Licensed Work. If the Licensor provides such error corrections and security updates, they are considered part of the Licensed Work and are subject to this License.
+
+MANAGED SERVICE EXCEPTION:
+
+If you have a separate written agreement with the Licensor (e.g., an Enterprise License) that specifically grants you the right to provide a Managed Payment Orchestration Service, that agreement supersedes the limitations of the Additional Use Grant.
+
+*****************************************************************************
+
+LICENSOR:           Revstack Inc.
+LICENSED WORK:      The Revstack OS software and associated documentation.
+
+*****************************************************************************

package/dist/index.d.ts

@@ -0,0 +1,621 @@
+/**
+ * The execution context for any provider operation.
+ * Contains the decrypted configuration and environment info.
+ */
+interface ProviderContext {
+    /**
+     * The decrypted credentials/settings for this specific merchant connection.
+     * e.g., { apiKey: "sk_live_...", webhookSecret: "whsec_..." }
+     */
+    config: Record<string, any>;
+    /**
+     * Optional: The webhook ID or relevant correlation ID for logging/tracing.
+     */
+    traceId?: string;
+    /**
+     * Indicates if the operation is running in Sandbox/Test mode.
+     */
+    isTestMode: boolean;
+    /**
+     * Optional: Idempotency key for duplicate request prevention.
+     */
+    idempotencyKey?: string;
+}
+
+/**
+ * * Normalized data models for the Revstack ecosystem.
+ * These types represent the "Internal Source of Truth" for the OS.
+ */
+declare enum PaymentStatus {
+    Pending = "pending",
+    Authorized = "authorized",// Funds held but not captured yet
+    Succeeded = "succeeded",
+    Failed = "failed",
+    Refunded = "refunded",
+    PartiallyRefunded = "partially_refunded",
+    Disputed = "disputed",
+    Canceled = "canceled"
+}
+type PaymentMethodDetails = {
+    type: "card" | "bank_transfer" | "wallet" | "crypto" | "checkout";
+    brand?: string;
+    last4?: string;
+    email?: string;
+    expiryMonth?: number;
+    expiryYear?: number;
+    cardHolderName?: string;
+};
+type Payment = {
+    id: string;
+    providerId: string;
+    externalId: string;
+    amount: number;
+    /** * Financial breakdown, vital for invoicing and tax calculation.
+     */
+    amountDetails?: {
+        subtotal: number;
+        tax: number;
+        shipping: number;
+        discount: number;
+        fee?: number;
+    };
+    amountRefunded: number;
+    currency: string;
+    status: PaymentStatus;
+    method?: PaymentMethodDetails;
+    description?: string;
+    customerId?: string;
+    externalCustomerId?: string;
+    createdAt: string;
+    updatedAt?: string;
+    metadata?: Record<string, any>;
+    raw?: any;
+};
+declare enum SubscriptionStatus {
+    Trialing = "trialing",
+    Active = "active",
+    PastDue = "past_due",
+    Canceled = "canceled",
+    Unpaid = "unpaid",
+    Incomplete = "incomplete",
+    IncompleteExpired = "incomplete_expired",
+    Paused = "paused"
+}
+type Subscription = {
+    id: string;
+    providerId: string;
+    externalId: string;
+    status: SubscriptionStatus;
+    planId?: string;
+    externalPlanId?: string;
+    amount: number;
+    currency: string;
+    interval: "day" | "week" | "month" | "year";
+    customerId: string;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    canceledAt?: string;
+    startedAt: string;
+    endedAt?: string;
+    trialStart?: string;
+    trialEnd?: string;
+    metadata?: Record<string, any>;
+};
+type SubscriptionInterval = "day" | "week" | "month" | "year";
+type CreateCustomerInput = {
+    email: string;
+    name?: string;
+    phone?: string;
+    description?: string;
+    address?: Address;
+    metadata?: Record<string, any>;
+};
+type UpdateCustomerInput = Partial<CreateCustomerInput>;
+type CreatePaymentInput = {
+    amount: number;
+    currency: string;
+    customerId?: string;
+    paymentMethodId?: string;
+    description?: string;
+    capture?: boolean;
+    billingAddress?: Address;
+    shippingAddress?: Address;
+    metadata?: Record<string, any>;
+    providerOptions?: any;
+};
+type RefundPaymentInput = {
+    paymentId: string;
+    externalPaymentId?: string;
+    amount?: number;
+    reason?: "duplicate" | "fraudulent" | "requested_by_customer";
+    metadata?: Record<string, any>;
+};
+type SetupPaymentMethodInput = {
+    customerId: string;
+    returnUrl: string;
+    metadata?: Record<string, any>;
+};
+type CheckoutSessionInput = {
+    customerId?: string;
+    customerEmail?: string;
+    setupFutureUsage?: boolean;
+    lineItems: {
+        name: string;
+        amount: number;
+        quantity: number;
+        currency: string;
+        images?: string[];
+        taxRates?: string[];
+    }[];
+    successUrl: string;
+    cancelUrl: string;
+    billingAddressCollection?: "auto" | "required";
+    mode: "payment" | "subscription" | "setup";
+    metadata?: Record<string, any>;
+};
+type CreateSubscriptionInput = {
+    customerId: string;
+    planId?: string;
+    priceId?: string;
+    quantity?: number;
+    trialDays?: number;
+    metadata?: Record<string, any>;
+};
+type PaymentResult = {
+    payment: Payment;
+    /**
+     * Action required to complete the payment (e.g., 3DS Redirect).
+     */
+    nextAction?: {
+        type: "redirect" | "modal";
+        url: string;
+    };
+};
+type SubscriptionResult = {
+    subscription: Subscription;
+};
+type CheckoutSessionResult = {
+    id: string;
+    url: string;
+    expiresAt?: string;
+};
+type PaginationOptions = {
+    limit?: number;
+    cursor?: string;
+    startingAfter?: string;
+    page?: number;
+};
+type PaginatedResult<T> = {
+    data: T[];
+    hasMore: boolean;
+    nextCursor?: string;
+};
+type Address = {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    country: string;
+};
+type Customer = {
+    id: string;
+    providerId: string;
+    externalId: string;
+    email: string;
+    name?: string;
+    phone?: string;
+    metadata?: Record<string, any>;
+    createdAt: string;
+};
+type PaymentMethod = {
+    id: string;
+    customerId: string;
+    externalId: string;
+    type: "card" | "bank_transfer" | "wallet";
+    details: PaymentMethodDetails;
+    isDefault: boolean;
+    metadata?: Record<string, any>;
+};
+
+interface IPaymentFeature {
+    createPayment(ctx: ProviderContext, input: CreatePaymentInput): Promise<PaymentResult>;
+    getPayment(ctx: ProviderContext, id: string): Promise<Payment>;
+    refundPayment(ctx: ProviderContext, input: RefundPaymentInput): Promise<Payment>;
+    listPayments?(ctx: ProviderContext, pagination: PaginationOptions): Promise<PaginatedResult<Payment>>;
+}
+interface ISubscriptionFeature {
+    createSubscription(ctx: ProviderContext, input: CreateSubscriptionInput): Promise<SubscriptionResult>;
+    cancelSubscription(ctx: ProviderContext, id: string, reason?: string): Promise<SubscriptionResult>;
+    pauseSubscription(ctx: ProviderContext, id: string): Promise<SubscriptionResult>;
+    resumeSubscription(ctx: ProviderContext, id: string): Promise<SubscriptionResult>;
+    getSubscription(ctx: ProviderContext, id: string): Promise<Subscription>;
+}
+interface ICheckoutFeature {
+    createCheckoutSession(ctx: ProviderContext, input: CheckoutSessionInput): Promise<CheckoutSessionResult>;
+}
+interface ICustomerFeature {
+    createCustomer(ctx: ProviderContext, input: CreateCustomerInput): Promise<Customer>;
+    updateCustomer(ctx: ProviderContext, id: string, input: UpdateCustomerInput): Promise<Customer>;
+    deleteCustomer(ctx: ProviderContext, id: string): Promise<boolean>;
+    getCustomer(ctx: ProviderContext, id: string): Promise<Customer>;
+}
+interface IPaymentMethodFeature {
+    listPaymentMethods(ctx: ProviderContext, customerId: string): Promise<PaymentMethod[]>;
+    deletePaymentMethod(ctx: ProviderContext, id: string): Promise<boolean>;
+}
+/**
+ * Unified interface that all providers must satisfy.
+ * (Even if they just throw 'Not Implemented' errors for unsupported features).
+ */
+interface IProvider extends IPaymentFeature, ISubscriptionFeature, ICheckoutFeature, ICustomerFeature, IPaymentMethodFeature {
+}
+
+type EventType = "PAYMENT_SUCCEEDED" | "PAYMENT_FAILED" | "PAYMENT_AUTHORIZED" | "PAYMENT_CAPTURED" | "REFUND_PROCESSED" | "REFUND_FAILED" | "SUBSCRIPTION_CREATED" | "SUBSCRIPTION_UPDATED" | "SUBSCRIPTION_CANCELED" | "DISPUTE_CREATED" | "DISPUTE_RESOLVED" | "MANDATE_CREATED";
+interface RevstackEvent {
+    type: EventType;
+    providerEventId: string;
+    createdAt: Date;
+    resourceId: string;
+    originalPayload: any;
+    metadata?: Record<string, any>;
+}
+interface WebhookResponse {
+    statusCode: number;
+    body: any;
+}
+
+type CheckoutStrategy = "redirect" | "native_sdk" | "sdui";
+/**
+ * Defines who orchestrates the recurring billing logic.
+ */
+type SubscriptionMode = "native" | "virtual";
+interface ProviderCapabilities {
+    checkout: {
+        supported: boolean;
+        strategy: "redirect" | "native_sdk" | "sdui";
+    };
+    payments: {
+        supported: boolean;
+        features: {
+            refunds: boolean;
+            partialRefunds: boolean;
+            capture: boolean;
+            disputes: boolean;
+        };
+    };
+    subscriptions: {
+        supported: boolean;
+        mode: "native" | "virtual";
+        features: {
+            pause: boolean;
+            resume: boolean;
+            cancellation: boolean;
+            proration?: boolean;
+        };
+    };
+    customers: {
+        supported: boolean;
+        features: {
+            create: boolean;
+            update: boolean;
+            delete: boolean;
+        };
+    };
+    webhooks: {
+        supported: boolean;
+        verification: "signature" | "secret" | "none";
+    };
+}
+
+/**
+ * Catálogo completo de errores estandarizados para Revstack.
+ * Agrupados por dominio para facilitar su manejo en el Frontend/API.
+ */
+declare enum RevstackErrorCode {
+    UnknownError = "unknown_error",
+    InternalError = "internal_error",
+    NotImplemented = "not_implemented",// Para features opcionales no soportadas por un provider
+    Timeout = "timeout",
+    RateLimitExceeded = "rate_limit_exceeded",
+    InvalidCredentials = "invalid_credentials",// API Key incorrecta
+    Unauthorized = "unauthorized",// No tiene permisos
+    MisconfiguredProvider = "misconfigured_provider",// Faltan campos en el dashboard
+    AccountSuspended = "account_suspended",// La cuenta del merchant en Stripe/etc está bloqueada
+    InvalidInput = "invalid_input",
+    MissingRequiredField = "missing_required_field",
+    InvalidEmail = "invalid_email",
+    InvalidAmount = "invalid_amount",// Monto negativo o cero
+    InvalidCurrency = "invalid_currency",// Provider no soporta esa moneda
+    ResourceNotFound = "resource_not_found",
+    ResourceAlreadyExists = "resource_already_exists",
+    IdempotencyKeyConflict = "idempotency_key_conflict",
+    PaymentFailed = "payment_failed",// Fallo genérico
+    CardDeclined = "card_declined",// El banco rechazó la tarjeta
+    InsufficientFunds = "insufficient_funds",// No hay saldo
+    ExpiredCard = "expired_card",
+    IncorrectCvc = "incorrect_cvc",
+    AuthenticationRequired = "authentication_required",// Requiere 3D Secure / SCA
+    LimitExceeded = "limit_exceeded",// Límite de la tarjeta excedido
+    DuplicateTransaction = "duplicate_transaction",
+    SubscriptionNotFound = "subscription_not_found",
+    SubscriptionAlreadyActive = "subscription_already_active",
+    SubscriptionCancelled = "subscription_cancelled",// Intentar operar sobre una cancelada
+    PlanNotFound = "plan_not_found",
+    RefundFailed = "refund_failed",
+    DisputeLost = "dispute_lost",
+    ProviderUnavailable = "provider_unavailable",// Stripe está caído
+    ProviderRejected = "provider_rejected",// El provider rechazó la conexión (ej: riesgo alto)
+    WebhookSignatureVerificationFailed = "webhook_signature_verification_failed"
+}
+/**
+ * Estructura del Error.
+ * Extendemos la clase nativa 'Error' para mantener el stack trace
+ * y permitir 'instanceof RevstackError'.
+ */
+declare class RevstackError extends Error {
+    readonly code: RevstackErrorCode;
+    readonly provider?: string;
+    readonly cause?: any;
+    readonly statusCode: number;
+    readonly documentationUrl?: string;
+    constructor(opts: {
+        code: RevstackErrorCode;
+        message: string;
+        provider?: string;
+        cause?: any;
+        documentationUrl?: string;
+    });
+    /**
+     * Mapea el código de error interno a un HTTP Status Code estándar.
+     * Útil para que la API responda correctamente sin lógica extra en el controller.
+     */
+    private mapToStatusCode;
+}
+/**
+ * Helper factory para compatibilidad con código funcional o uso rápido.
+ */
+declare function createError(code: RevstackErrorCode, message: string, provider?: string, cause?: any): RevstackError;
+/**
+ * Type Guard para verificar si un error es de Revstack.
+ */
+declare function isRevstackError(error: unknown): error is RevstackError;
+
+interface InstallInput {
+    config: Record<string, any>;
+    /**
+     * The absolute URL where Revstack expects to receive events for this merchant.
+     */
+    webhookUrl: string;
+}
+interface InstallResult {
+    success: boolean;
+    data?: Record<string, any>;
+    error?: RevstackError;
+}
+interface UninstallInput {
+    config: Record<string, any>;
+    data: Record<string, any>;
+}
+interface UninstallResult {
+    success: boolean;
+    error?: RevstackError;
+}
+
+declare enum ProviderCategory {
+    Card = "card",// Stripe, Adyen, dLocal
+    BankTransfer = "bank",// PSE, PIX, Wire, Spei
+    Wallet = "wallet",// PayPal, MercadoPago, ApplePay
+    Crypto = "crypto",// Coinbase, BitPay
+    Cash = "cash",// OXXO, Rapipago, PagoFácil
+    BuyNowPayLater = "bnpl"
+}
+declare const CATEGORY_LABELS: Record<ProviderCategory, string>;
+
+/**
+ * Defines the input field type for the installation UI.
+ */
+type ConfigFieldType = "text" | "password" | "switch" | "select" | "number" | "json";
+/**
+ * Configuration schema for a provider setting.
+ * Used to generate the UI and handle encryption.
+ */
+interface ConfigFieldDefinition {
+    /** Label to display in the UI */
+    label: string;
+    /** Input type */
+    type: ConfigFieldType;
+    /** If true, this field must be encrypted in the DB */
+    secure: boolean;
+    /** Is this field required? */
+    required: boolean;
+    /** Description or tooltip for the user */
+    description?: string;
+    /** Options for 'select' type */
+    options?: {
+        label: string;
+        value: string;
+    }[];
+}
+interface DataFieldDefinition {
+    /**
+     * If true, the value of this field will be encrypted in the DB.
+     */
+    secure: boolean;
+    /**
+     * Description for internal documentation (optional)
+     */
+    description?: string;
+}
+/**
+ * The Provider Manifest.
+ * Acts as the source of truth for the provider's metadata and capabilities.
+ */
+interface ProviderManifest {
+    /** Unique identifier (e.g., 'stripe', 'polar') */
+    slug: string;
+    /** Display name (e.g., 'Stripe') */
+    name: string;
+    /** Provider category */
+    category: ProviderCategory;
+    /** * Semantic version of the provider package (e.g., '1.0.0').
+     * Vital for managing updates in the marketplace.
+     */
+    version: string;
+    /** Short description displayed in the marketplace card. */
+    description?: string;
+    /** URL to the provider's logo */
+    logoUrl?: string;
+    /** The organization or developer maintaining this provider. */
+    author?: string;
+    /** Link to the official documentation for this specific provider. */
+    documentationUrl?: string;
+    /** Link to the support page or repository issue tracker. */
+    supportUrl?: string;
+    /** * List of supported ISO 3166-1 alpha-2 country codes (e.g., ['US', 'GB', 'BR']).
+     * Use ['global'] if the provider works worldwide.
+     * Used to filter providers in the UI based on the merchant's location.
+     */
+    regions?: string[];
+    /**
+     * List of supported ISO 4217 currency codes (e.g., ['USD', 'EUR']).
+     * Use ['*'] if the provider supports all currencies.
+     */
+    currencies?: string[];
+    /** * Indicates if the provider supports a dedicated sandbox/test mode.
+     * If true, the UI should allow switching between Test and Live credentials.
+     */
+    sandboxAvailable?: boolean;
+    /** * Schema to generate the installation form.
+     * Key is the internal config key (e.g., 'apiKey').
+     */
+    configSchema: Record<string, ConfigFieldDefinition>;
+    /**
+     * Defines the fields that the provider generates and stores internally (Outputs).
+     * The Core uses this to know which fields to encrypt in the 'data' column.
+     */
+    dataSchema?: Record<string, DataFieldDefinition>;
+    /**
+     * What this provider can do. Used for feature flagging in the core.
+     */
+    capabilities: ProviderCapabilities;
+}
+
+/**
+ * src/base.ts
+ * * The Foundation of the Provider Development Kit (PDK).
+ */
+
+/**
+ * The Abstract Base Class for all Revstack Providers.
+ * * It implements the IProvider interface with default behaviors (throwing errors).
+ * Specific providers (e.g., Stripe) will override only the methods they actually support.
+ */
+declare abstract class BaseProvider implements IProvider {
+    getPayment(ctx: ProviderContext, id: string): Promise<Payment>;
+    refundPayment(ctx: ProviderContext, input: RefundPaymentInput): Promise<Payment>;
+    listPayments?(ctx: ProviderContext, pagination: PaginationOptions): Promise<PaginatedResult<Payment>>;
+    getSubscription(ctx: ProviderContext, id: string): Promise<Subscription>;
+    createCustomer(ctx: ProviderContext, input: CreateCustomerInput): Promise<Customer>;
+    updateCustomer(ctx: ProviderContext, id: string, input: UpdateCustomerInput): Promise<Customer>;
+    deleteCustomer(ctx: ProviderContext, id: string): Promise<boolean>;
+    getCustomer(ctx: ProviderContext, id: string): Promise<Customer>;
+    listPaymentMethods(ctx: ProviderContext, customerId: string): Promise<PaymentMethod[]>;
+    deletePaymentMethod(ctx: ProviderContext, id: string): Promise<boolean>;
+    /**
+     * The static manifest definition.
+     * Defines capabilities, metadata, and config schema (UI).
+     */
+    abstract readonly manifest: ProviderManifest;
+    /**
+     * Called when a merchant installs or updates this provider.
+     * * RESPONSIBILITY:
+     * 1. Instantiate the provider SDK with the input config.
+     * 2. Validate credentials (e.g., make a 'ping' or 'get balance' request).
+     * 3. Return the payload to be saved in the database.
+     * * @param ctx - The execution context (includes environment info).
+     * @param input - The input data provided by the user in the UI.
+     * @returns The success status and the data to be stored (encrypted by Core).
+     */
+    abstract onInstall(ctx: ProviderContext, input: InstallInput): Promise<InstallResult>;
+    /**
+     * Called when a merchant uninstalls this provider.
+     * * RESPONSIBILITY:
+     * 1. Instantiate the provider SDK with the input config.
+     * 2. Validate credentials (e.g., make a 'ping' or 'get balance' request).
+     * 3. Return the success status.
+     * * @param ctx - The execution context (includes environment info).
+     * @param input - The input data provided by the user in the UI.
+     * @returns The success status.
+     */
+    abstract onUninstall(ctx: ProviderContext, input: UninstallInput): Promise<boolean>;
+    /**
+     * Verifies the cryptographic signature of an incoming webhook.
+     * * SECURITY CRITICAL:
+     * This ensures that the request actually originated from the Payment Provider
+     * and hasn't been tampered with.
+     * * @param payload - The raw body of the request (string or buffer).
+     * @param headers - The request headers.
+     * @param secret - The webhook signing secret stored in the DB.
+     */
+    abstract verifyWebhookSignature(ctx: ProviderContext, payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<boolean>;
+    /**
+     * Transforms a raw provider payload into a standardized Revstack Event.
+     * * This acts as the "Translation Layer" or "Adapter" for incoming events.
+     * * @param payload - The raw JSON body from the provider.
+     * @returns A normalized RevstackEvent or null if the event is irrelevant.
+     */
+    abstract parseWebhookEvent(payload: any): Promise<RevstackEvent | null>;
+    /**
+     * Returns the HTTP response that should be sent back to the Provider
+     * after receiving a webhook.
+     * * Default implementation returns 200 OK. Override if the provider expects
+     * a specific XML or JSON confirmation.
+     */
+    getWebhookResponse(): Promise<WebhookResponse>;
+    /**
+     * Process a one-time payment.
+     * Override this if manifest.capabilities.payments.oneTime is true.
+     * * @throws Error if not implemented by the specific provider.
+     */
+    createPayment(ctx: ProviderContext, input: CreatePaymentInput): Promise<PaymentResult>;
+    /**
+     * Create a recurring subscription.
+     * Override this if manifest.capabilities.subscriptions.native is true.
+     */
+    createSubscription(ctx: ProviderContext, input: CreateSubscriptionInput): Promise<SubscriptionResult>;
+    /**
+     * Cancel an active subscription immediately or at period end.
+     */
+    cancelSubscription(ctx: ProviderContext, id: string, reason?: string): Promise<SubscriptionResult>;
+    pauseSubscription(ctx: ProviderContext, id: string, reason?: string): Promise<SubscriptionResult>;
+    resumeSubscription(ctx: ProviderContext, id: string, reason?: string): Promise<SubscriptionResult>;
+    /**
+     * Generate a hosted checkout session URL (e.g., Stripe Checkout).
+     * Override this if manifest.capabilities.checkout.supported is true.
+     */
+    createCheckoutSession(ctx: ProviderContext, input: CheckoutSessionInput): Promise<CheckoutSessionResult>;
+}
+
+/**
+ * Validates and casts raw input (e.g. from a POST request) against the Provider's schema.
+ * Ensures that numbers are numbers, booleans are booleans, etc.
+ */
+declare function validateAndCastConfig(rawConfig: Record<string, any>, schema: Record<string, ConfigFieldDefinition>): Record<string, any>;
+
+/**
+ * Generic HMAC signature verification.
+ * usable by ~80% of providers (Shopify, MercadoPago, PayPal, etc.)
+ */
+declare function verifyHmacSignature(payload: string, secret: string, signature: string, algorithm?: "sha256" | "sha1", encoding?: "hex" | "base64"): boolean;
+
+interface SmokeConfig {
+    provider: IProvider;
+    ctx: ProviderContext;
+    scenarios: Record<string, (ctx: ProviderContext) => Promise<any>>;
+    manifest: ProviderManifest;
+}
+declare function runSmoke(config: SmokeConfig): Promise<void>;
+
+export { type Address, BaseProvider, CATEGORY_LABELS, type CheckoutSessionInput, type CheckoutSessionResult, type CheckoutStrategy, type ConfigFieldDefinition, type ConfigFieldType, type CreateCustomerInput, type CreatePaymentInput, type CreateSubscriptionInput, type Customer, type DataFieldDefinition, type EventType, type ICheckoutFeature, type ICustomerFeature, type IPaymentFeature, type IPaymentMethodFeature, type IProvider, type ISubscriptionFeature, type InstallInput, type InstallResult, type PaginatedResult, type PaginationOptions, type Payment, type PaymentMethod, type PaymentMethodDetails, type PaymentResult, PaymentStatus, type ProviderCapabilities, ProviderCategory, type ProviderContext, type ProviderManifest, type RefundPaymentInput, RevstackError, RevstackErrorCode, type RevstackEvent, type SetupPaymentMethodInput, type SmokeConfig, type Subscription, type SubscriptionInterval, type SubscriptionMode, type SubscriptionResult, SubscriptionStatus, type UninstallInput, type UninstallResult, type UpdateCustomerInput, type WebhookResponse, createError, isRevstackError, runSmoke, validateAndCastConfig, verifyHmacSignature };

package/dist/index.js

@@ -0,0 +1,362 @@
+// src/types/models.ts
+var PaymentStatus = /* @__PURE__ */ ((PaymentStatus2) => {
+  PaymentStatus2["Pending"] = "pending";
+  PaymentStatus2["Authorized"] = "authorized";
+  PaymentStatus2["Succeeded"] = "succeeded";
+  PaymentStatus2["Failed"] = "failed";
+  PaymentStatus2["Refunded"] = "refunded";
+  PaymentStatus2["PartiallyRefunded"] = "partially_refunded";
+  PaymentStatus2["Disputed"] = "disputed";
+  PaymentStatus2["Canceled"] = "canceled";
+  return PaymentStatus2;
+})(PaymentStatus || {});
+var SubscriptionStatus = /* @__PURE__ */ ((SubscriptionStatus2) => {
+  SubscriptionStatus2["Trialing"] = "trialing";
+  SubscriptionStatus2["Active"] = "active";
+  SubscriptionStatus2["PastDue"] = "past_due";
+  SubscriptionStatus2["Canceled"] = "canceled";
+  SubscriptionStatus2["Unpaid"] = "unpaid";
+  SubscriptionStatus2["Incomplete"] = "incomplete";
+  SubscriptionStatus2["IncompleteExpired"] = "incomplete_expired";
+  SubscriptionStatus2["Paused"] = "paused";
+  return SubscriptionStatus2;
+})(SubscriptionStatus || {});
+
+// src/types/errors.ts
+var RevstackErrorCode = /* @__PURE__ */ ((RevstackErrorCode2) => {
+  RevstackErrorCode2["UnknownError"] = "unknown_error";
+  RevstackErrorCode2["InternalError"] = "internal_error";
+  RevstackErrorCode2["NotImplemented"] = "not_implemented";
+  RevstackErrorCode2["Timeout"] = "timeout";
+  RevstackErrorCode2["RateLimitExceeded"] = "rate_limit_exceeded";
+  RevstackErrorCode2["InvalidCredentials"] = "invalid_credentials";
+  RevstackErrorCode2["Unauthorized"] = "unauthorized";
+  RevstackErrorCode2["MisconfiguredProvider"] = "misconfigured_provider";
+  RevstackErrorCode2["AccountSuspended"] = "account_suspended";
+  RevstackErrorCode2["InvalidInput"] = "invalid_input";
+  RevstackErrorCode2["MissingRequiredField"] = "missing_required_field";
+  RevstackErrorCode2["InvalidEmail"] = "invalid_email";
+  RevstackErrorCode2["InvalidAmount"] = "invalid_amount";
+  RevstackErrorCode2["InvalidCurrency"] = "invalid_currency";
+  RevstackErrorCode2["ResourceNotFound"] = "resource_not_found";
+  RevstackErrorCode2["ResourceAlreadyExists"] = "resource_already_exists";
+  RevstackErrorCode2["IdempotencyKeyConflict"] = "idempotency_key_conflict";
+  RevstackErrorCode2["PaymentFailed"] = "payment_failed";
+  RevstackErrorCode2["CardDeclined"] = "card_declined";
+  RevstackErrorCode2["InsufficientFunds"] = "insufficient_funds";
+  RevstackErrorCode2["ExpiredCard"] = "expired_card";
+  RevstackErrorCode2["IncorrectCvc"] = "incorrect_cvc";
+  RevstackErrorCode2["AuthenticationRequired"] = "authentication_required";
+  RevstackErrorCode2["LimitExceeded"] = "limit_exceeded";
+  RevstackErrorCode2["DuplicateTransaction"] = "duplicate_transaction";
+  RevstackErrorCode2["SubscriptionNotFound"] = "subscription_not_found";
+  RevstackErrorCode2["SubscriptionAlreadyActive"] = "subscription_already_active";
+  RevstackErrorCode2["SubscriptionCancelled"] = "subscription_cancelled";
+  RevstackErrorCode2["PlanNotFound"] = "plan_not_found";
+  RevstackErrorCode2["RefundFailed"] = "refund_failed";
+  RevstackErrorCode2["DisputeLost"] = "dispute_lost";
+  RevstackErrorCode2["ProviderUnavailable"] = "provider_unavailable";
+  RevstackErrorCode2["ProviderRejected"] = "provider_rejected";
+  RevstackErrorCode2["WebhookSignatureVerificationFailed"] = "webhook_signature_verification_failed";
+  return RevstackErrorCode2;
+})(RevstackErrorCode || {});
+var RevstackError = class _RevstackError extends Error {
+  code;
+  provider;
+  // Slug del provider (ej: 'stripe')
+  cause;
+  // El error original del SDK (raw)
+  statusCode;
+  // Sugerencia de HTTP Status Code
+  documentationUrl;
+  constructor(opts) {
+    super(opts.message);
+    Object.setPrototypeOf(this, _RevstackError.prototype);
+    this.name = "RevstackError";
+    this.code = opts.code;
+    this.provider = opts.provider;
+    this.cause = opts.cause;
+    this.documentationUrl = opts.documentationUrl;
+    this.statusCode = this.mapToStatusCode(opts.code);
+  }
+  /**
+   * Mapea el código de error interno a un HTTP Status Code estándar.
+   * Útil para que la API responda correctamente sin lógica extra en el controller.
+   */
+  mapToStatusCode(code) {
+    switch (code) {
+      // 400 Bad Request
+      case "invalid_input" /* InvalidInput */:
+      case "missing_required_field" /* MissingRequiredField */:
+      case "invalid_email" /* InvalidEmail */:
+      case "invalid_amount" /* InvalidAmount */:
+      case "invalid_currency" /* InvalidCurrency */:
+      case "payment_failed" /* PaymentFailed */:
+      // Fallo de negocio, no del server
+      case "card_declined" /* CardDeclined */:
+      case "insufficient_funds" /* InsufficientFunds */:
+      case "expired_card" /* ExpiredCard */:
+      case "incorrect_cvc" /* IncorrectCvc */:
+        return 400;
+      // 401 Unauthorized
+      case "invalid_credentials" /* InvalidCredentials */:
+      case "unauthorized" /* Unauthorized */:
+      case "webhook_signature_verification_failed" /* WebhookSignatureVerificationFailed */:
+        return 401;
+      // 402 Payment Required (Especialmente útil para SCA/3DS)
+      case "authentication_required" /* AuthenticationRequired */:
+        return 402;
+      // 403 Forbidden
+      case "account_suspended" /* AccountSuspended */:
+      case "provider_rejected" /* ProviderRejected */:
+        return 403;
+      // 404 Not Found
+      case "resource_not_found" /* ResourceNotFound */:
+      case "subscription_not_found" /* SubscriptionNotFound */:
+      case "plan_not_found" /* PlanNotFound */:
+        return 404;
+      // 409 Conflict
+      case "resource_already_exists" /* ResourceAlreadyExists */:
+      case "idempotency_key_conflict" /* IdempotencyKeyConflict */:
+      case "subscription_already_active" /* SubscriptionAlreadyActive */:
+        return 409;
+      // 429 Too Many Requests
+      case "rate_limit_exceeded" /* RateLimitExceeded */:
+        return 429;
+      // 501 Not Implemented
+      case "not_implemented" /* NotImplemented */:
+        return 501;
+      // 502 Bad Gateway (Culpa del provider)
+      case "provider_unavailable" /* ProviderUnavailable */:
+      case "timeout" /* Timeout */:
+        return 502;
+      // 500 Internal Server Error (Default)
+      default:
+        return 500;
+    }
+  }
+};
+function createError(code, message, provider, cause) {
+  return new RevstackError({ code, message, provider, cause });
+}
+function isRevstackError(error) {
+  return error instanceof RevstackError;
+}
+
+// src/types/categories.ts
+var ProviderCategory = /* @__PURE__ */ ((ProviderCategory2) => {
+  ProviderCategory2["Card"] = "card";
+  ProviderCategory2["BankTransfer"] = "bank";
+  ProviderCategory2["Wallet"] = "wallet";
+  ProviderCategory2["Crypto"] = "crypto";
+  ProviderCategory2["Cash"] = "cash";
+  ProviderCategory2["BuyNowPayLater"] = "bnpl";
+  return ProviderCategory2;
+})(ProviderCategory || {});
+var CATEGORY_LABELS = {
+  ["card" /* Card */]: "Credit / Debit Card",
+  ["bank" /* BankTransfer */]: "Bank Transfer",
+  ["wallet" /* Wallet */]: "Digital Wallet",
+  ["crypto" /* Crypto */]: "Cryptocurrency",
+  ["cash" /* Cash */]: "Cash Payment",
+  ["bnpl" /* BuyNowPayLater */]: "Buy Now, Pay Later"
+};
+
+// src/base.ts
+var BaseProvider = class {
+  getPayment(ctx, id) {
+    throw new Error("Method not implemented.");
+  }
+  refundPayment(ctx, input) {
+    throw new Error("Method not implemented.");
+  }
+  listPayments(ctx, pagination) {
+    throw new Error("Method not implemented.");
+  }
+  getSubscription(ctx, id) {
+    throw new Error("Method not implemented.");
+  }
+  createCustomer(ctx, input) {
+    throw new Error("Method not implemented.");
+  }
+  updateCustomer(ctx, id, input) {
+    throw new Error("Method not implemented.");
+  }
+  deleteCustomer(ctx, id) {
+    throw new Error("Method not implemented.");
+  }
+  getCustomer(ctx, id) {
+    throw new Error("Method not implemented.");
+  }
+  listPaymentMethods(ctx, customerId) {
+    throw new Error("Method not implemented.");
+  }
+  deletePaymentMethod(ctx, id) {
+    throw new Error("Method not implemented.");
+  }
+  /**
+   * Returns the HTTP response that should be sent back to the Provider
+   * after receiving a webhook.
+   * * Default implementation returns 200 OK. Override if the provider expects
+   * a specific XML or JSON confirmation.
+   */
+  async getWebhookResponse() {
+    return { statusCode: 200, body: { received: true } };
+  }
+  // ===========================================================================
+  // PAYMENT FEATURE IMPLEMENTATION (IProvider)
+  // ===========================================================================
+  /**
+   * Process a one-time payment.
+   * Override this if manifest.capabilities.payments.oneTime is true.
+   * * @throws Error if not implemented by the specific provider.
+   */
+  async createPayment(ctx, input) {
+    throw new Error(
+      `Provider '${this.manifest.slug}' does not support createPayment.`
+    );
+  }
+  // ===========================================================================
+  // SUBSCRIPTION FEATURE IMPLEMENTATION (IProvider)
+  // ===========================================================================
+  /**
+   * Create a recurring subscription.
+   * Override this if manifest.capabilities.subscriptions.native is true.
+   */
+  async createSubscription(ctx, input) {
+    throw new Error(
+      `Provider '${this.manifest.slug}' does not support createSubscription.`
+    );
+  }
+  /**
+   * Cancel an active subscription immediately or at period end.
+   */
+  async cancelSubscription(ctx, id, reason) {
+    throw new Error(
+      `Provider '${this.manifest.slug}' does not support cancelSubscription.`
+    );
+  }
+  pauseSubscription(ctx, id, reason) {
+    throw new Error("Method not implemented.");
+  }
+  resumeSubscription(ctx, id, reason) {
+    throw new Error("Method not implemented.");
+  }
+  // ===========================================================================
+  // CHECKOUT FEATURE IMPLEMENTATION (IProvider)
+  // ===========================================================================
+  /**
+   * Generate a hosted checkout session URL (e.g., Stripe Checkout).
+   * Override this if manifest.capabilities.checkout.supported is true.
+   */
+  async createCheckoutSession(ctx, input) {
+    throw new Error(
+      `Provider '${this.manifest.slug}' does not support createCheckoutSession.`
+    );
+  }
+};
+
+// src/lib/config-validator.ts
+function validateAndCastConfig(rawConfig, schema) {
+  const processedConfig = {};
+  for (const [key, definition] of Object.entries(schema)) {
+    let value = rawConfig[key];
+    if (definition.required && (value === void 0 || value === null || value === "")) {
+      throw new RevstackError({
+        code: "missing_required_field" /* MissingRequiredField */,
+        message: `Field '${definition.label}' (${key}) is required.`
+      });
+    }
+    if (value === void 0 || value === null || value === "") {
+      continue;
+    }
+    switch (definition.type) {
+      case "text":
+      case "password":
+      case "select":
+        processedConfig[key] = String(value).trim();
+        break;
+      case "number":
+        const num = Number(value);
+        if (isNaN(num)) {
+          throw new RevstackError({
+            code: "invalid_input" /* InvalidInput */,
+            message: `Field '${definition.label}' must be a valid number.`
+          });
+        }
+        processedConfig[key] = num;
+        break;
+      case "switch":
+        processedConfig[key] = value === "true" || value === true || value === 1 || value === "1";
+        break;
+      case "json":
+        try {
+          processedConfig[key] = typeof value === "object" ? value : JSON.parse(value);
+        } catch (e) {
+          throw new RevstackError({
+            code: "invalid_input" /* InvalidInput */,
+            message: `Invalid JSON for ${key}`
+          });
+        }
+        break;
+    }
+  }
+  return processedConfig;
+}
+
+// src/utils/crypto.ts
+import * as crypto from "crypto";
+function verifyHmacSignature(payload, secret, signature, algorithm = "sha256", encoding = "hex") {
+  if (!payload || !secret || !signature) return false;
+  const hmac = crypto.createHmac(algorithm, secret);
+  const digest = hmac.update(payload).digest(encoding);
+  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
+}
+
+// src/smoke-runner.ts
+async function runSmoke(config) {
+  const method = process.argv[2] || "onInstall";
+  const providerName = config.manifest.name;
+  console.log(`
+\u{1F6AC} \x1B[36mSmoking Provider:\x1B[0m ${providerName}`);
+  console.log(`\u{1F449} \x1B[33mMethod:\x1B[0m ${method}
+`);
+  if (method === "list") {
+    console.log("\u{1F4CB} Available scenarios:");
+    console.log(
+      Object.keys(config.scenarios).map((k) => `  - ${k}`).join("\n")
+    );
+    return;
+  }
+  const scenario = config.scenarios[method];
+  if (!scenario) {
+    console.error(`\u274C \x1B[31mError:\x1B[0m Scenario '${method}' not found.`);
+    console.log(`   Run 'list' to see available scenarios.`);
+    process.exit(1);
+  }
+  try {
+    console.time("\u23F1\uFE0F Execution time");
+    const result = await scenario(config.ctx);
+    console.timeEnd("\u23F1\uFE0F Execution time");
+    console.log("\n\u2705 \x1B[32mSUCCESS RESULT:\x1B[0m");
+    console.dir(result, { depth: null, colors: true });
+  } catch (e) {
+    console.error("\n\u{1F525} \x1B[31mFAILED:\x1B[0m");
+    console.error(e);
+    process.exit(1);
+  }
+}
+export {
+  BaseProvider,
+  CATEGORY_LABELS,
+  PaymentStatus,
+  ProviderCategory,
+  RevstackError,
+  RevstackErrorCode,
+  SubscriptionStatus,
+  createError,
+  isRevstackError,
+  runSmoke,
+  validateAndCastConfig,
+  verifyHmacSignature
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@revstackhq/providers-core",
+  "version": "0.0.0-dev-20260209034148",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "5.9.2",
+    "tsup": "^8.1.0",
+    "eslint": "^9.39.1",
+    "@eslint/js": "^9.39.1",
+    "typescript-eslint": "^8.50.0",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-plugin-turbo": "^2.7.1",
+    "@types/node": "^20.11.30",
+    "@revstackhq/eslint-config": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint \"src/**/*.{ts,tsx}\""
+  }
+}