@revstackhq/providers-core 0.2.0

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,592 @@
+/**
+ * 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;
+}
+
+/**
+ * src/types/models.ts
+ * * 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
+    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;
+};
+type Payment = {
+    /** Unique ID in Revstack (UUID) */
+    id: string;
+    /** The slug of the provider (e.g., 'stripe') */
+    providerId: string;
+    /** The ID generated by the provider (e.g., 'pi_12345') */
+    externalId: string;
+    /** Total amount in lowest currency unit (e.g., cents) */
+    amount: number;
+    /** Amount refunded so far */
+    amountRefunded: number;
+    /** ISO 4217 Currency Code (e.g., 'USD') */
+    currency: string;
+    status: PaymentStatus;
+    method?: PaymentMethodDetails;
+    description?: string;
+    /** Revstack internal Customer ID */
+    customerId?: string;
+    /** Provider-specific Customer ID (e.g., 'cus_999') */
+    externalCustomerId?: string;
+    /** * The fee charged by the provider for this transaction.
+     * Crucial for Net Revenue calculations.
+     */
+    fee?: number;
+    /** ISO Date String */
+    createdAt: string;
+    /** ISO Date String */
+    updatedAt?: string;
+    metadata?: Record<string, any>;
+    /** Optional: The raw object from the provider for debugging/audit */
+    raw?: any;
+};
+declare enum SubscriptionStatus {
+    Trialing = "trialing",
+    Active = "active",
+    PastDue = "past_due",// Payment failed, in grace period
+    Canceled = "canceled",
+    Unpaid = "unpaid",// Grace period ended, service cut
+    Incomplete = "incomplete",// Created but waiting for first payment (3DS)
+    IncompleteExpired = "incomplete_expired",
+    Paused = "paused"
+}
+type SubscriptionInterval = "day" | "week" | "month" | "year";
+type Subscription = {
+    id: string;
+    providerId: string;
+    externalId: string;
+    status: SubscriptionStatus;
+    /** Internal Plan ID */
+    planId?: string;
+    /** Provider Plan/Price ID (e.g., 'price_Hk123') */
+    externalPlanId?: string;
+    amount: number;
+    currency: string;
+    interval: SubscriptionInterval;
+    customerId: string;
+    /** Start of the current billing period (ISO Date) */
+    currentPeriodStart: string;
+    /** End of the current billing period (ISO Date) */
+    currentPeriodEnd: string;
+    /** If true, the subscription will cancel at the end of the current period */
+    cancelAtPeriodEnd: boolean;
+    canceledAt?: string;
+    startedAt: string;
+    endedAt?: string;
+    trialStart?: string;
+    trialEnd?: string;
+    metadata?: Record<string, any>;
+};
+type CreatePaymentInput = {
+    amount: number;
+    currency: string;
+    customerId?: string;
+    paymentMethodId?: string;
+    description?: string;
+    metadata?: Record<string, any>;
+    /** Pass-through options for the specific provider */
+    providerOptions?: any;
+};
+type PaymentResult = {
+    payment: Payment;
+    /** If the payment requires 3DS or redirect */
+    nextAction?: {
+        type: "redirect" | "modal";
+        url: string;
+    };
+};
+type CreateSubscriptionInput = {
+    customerId: string;
+    planId?: string;
+    priceId?: string;
+    amount?: number;
+    currency?: string;
+    trialDays?: number;
+    metadata?: Record<string, any>;
+};
+type SubscriptionResult = {
+    subscription: Subscription;
+};
+type CheckoutSessionInput = {
+    customerId?: string;
+    /** Items to purchase */
+    lineItems: {
+        name: string;
+        amount: number;
+        quantity: number;
+        currency: string;
+        images?: string[];
+    }[];
+    successUrl: string;
+    cancelUrl: string;
+    mode: "payment" | "subscription";
+    metadata?: Record<string, any>;
+};
+type CheckoutSessionResult = {
+    id: string;
+    url: string;
+    expiresAt?: string;
+};
+
+/**
+ * src/interfaces/features.ts
+ * * Defines the specific capabilities a provider can implement.
+ * This adheres to the Interface Segregation Principle.
+ */
+
+/**
+ * Contract for providers that support one-time payments.
+ */
+interface IPaymentFeature {
+    createPayment(ctx: ProviderContext, input: CreatePaymentInput): Promise<PaymentResult>;
+    getPayment(ctx: ProviderContext, id: string): Promise<PaymentResult>;
+}
+/**
+ * Contract for providers that support native recurring billing.
+ * (e.g., Stripe, Paddle, but NOT simple bank transfers).
+ */
+interface ISubscriptionFeature {
+    createSubscription(ctx: ProviderContext, input: CreateSubscriptionInput): Promise<SubscriptionResult>;
+    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>;
+}
+/**
+ * Contract for providers that offer a hosted checkout page.
+ */
+interface ICheckoutFeature {
+    createCheckoutSession(ctx: ProviderContext, input: CheckoutSessionInput): Promise<CheckoutSessionResult>;
+}
+/**
+ * The unified contract that all Revstack Providers must technically satisfy.
+ * * Even if a provider doesn't support a feature, it must implement the interface
+ * (usually by throwing a 'Not Implemented' error via the BaseProvider).
+ */
+interface IProvider extends IPaymentFeature, ISubscriptionFeature, ICheckoutFeature {
+}
+
+type EventType = "PAYMENT_SUCCEEDED" | "PAYMENT_FAILED" | "REFUND_PROCESSED" | "SUBSCRIPTION_CREATED" | "SUBSCRIPTION_UPDATED" | "SUBSCRIPTION_CANCELED" | "DISPUTE_CREATED" | "DISPUTE_RESOLVED";
+/**
+ * A normalized event ready to be consumed by the Revstack Core.
+ */
+interface RevstackEvent {
+    /** The standardized event type */
+    type: EventType;
+    /** The provider's original event ID */
+    providerEventId: string;
+    /** ISO timestamp of when the event happened */
+    createdAt: Date;
+    /** The raw original payload (for debugging) */
+    originalPayload: any;
+    /** * The primary resource affected (Payment ID, Subscription ID).
+     * Used to link the event to internal records.
+     */
+    resourceId: string;
+    /** Additional context */
+    metadata?: Record<string, any>;
+}
+interface WebhookResponse {
+    /** HTTP Status code to return to the provider (e.g., 200) */
+    statusCode: number;
+    /** Body to return (e.g., { received: true }) */
+    body: any;
+}
+
+/**
+ * Defines how the checkout flow is presented to the user.
+ */
+type CheckoutStrategy = "redirect" | "native_sdk" | "sdui";
+/**
+ * Defines who orchestrates the recurring billing logic.
+ */
+type SubscriptionMode = "native" | "virtual";
+interface CheckoutCapabilities {
+    /**
+     * If true, this provider can be used in the Hosted Checkout flow.
+     */
+    supported: boolean;
+    /**
+     * The primary UX strategy used to collect payment details.
+     * The frontend uses this to determine which adapter to load.
+     */
+    strategy: CheckoutStrategy;
+}
+interface PaymentCapabilities {
+    /**
+     * If true, the provider supports processing standard One-Time Payments.
+     * This is the fundamental capability of any payment provider.
+     */
+    supported: boolean;
+    /**
+     * Advanced transactional features supported by the provider.
+     */
+    features: {
+        /**
+         * Can the provider process full refunds via API?
+         */
+        refunds: boolean;
+        /**
+         * Can the provider process partial refunds (returning a specific amount)?
+         */
+        partialRefunds: boolean;
+        /**
+         * Supports "Authorization & Capture" flow.
+         * Useful for e-commerce (shipping) or rentals, where funds are held first
+         * and charged later.
+         */
+        capture: boolean;
+        /**
+         * Can the provider fetch or list disputes/chargebacks via API?
+         */
+        disputes: boolean;
+    };
+}
+interface SubscriptionCapabilities {
+    /**
+     * If true, the provider supports recurring billing flows.
+     */
+    supported: boolean;
+    /**
+     * The engine responsible for recurrence logic.
+     * - 'native': We delegate logic to the provider.
+     * - 'virtual': We emulate logic using one-time payments.
+     */
+    mode: SubscriptionMode;
+    /**
+     * Specific lifecycle actions supported by the provider.
+     */
+    features: {
+        /**
+         * Can a subscription be paused temporarily without canceling it?
+         */
+        pause: boolean;
+        /**
+         * Can a paused subscription be resumed?
+         */
+        resume: boolean;
+        /**
+         * Can a subscription be canceled via API?
+         */
+        cancellation: boolean;
+        /**
+         * Does the provider support native proration for upgrades/downgrades?
+         * (Only relevant if mode is 'native').
+         */
+        proration?: boolean;
+    };
+}
+interface WebhookCapabilities {
+    /**
+     * Does the provider send asynchronous events (webhooks)?
+     */
+    supported: boolean;
+    /**
+     * How the webhook payload is verified for security.
+     * - 'signature': HMAC/RSA signature header (Best).
+     * - 'secret': Simple shared secret in header/body.
+     * - 'none': No verification (Insecure).
+     */
+    verification: "signature" | "secret" | "none";
+}
+interface ProviderCapabilities {
+    checkout: CheckoutCapabilities;
+    payments: PaymentCapabilities;
+    subscriptions: SubscriptionCapabilities;
+    webhooks: WebhookCapabilities;
+}
+
+/**
+ * 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 {
+    /**
+     * La configuración ingresada por el usuario en el formulario (API Keys, etc).
+     */
+    config: Record<string, any>;
+    /**
+     * La URL absoluta donde Revstack espera recibir los eventos para este merchant.
+     * El Core la genera: https://api.revstack.os/webhooks/{provider}/{merchantId}
+     */
+    webhookUrl: string;
+}
+interface InstallResult {
+    success: boolean;
+    /**
+     * Datos finales a guardar en la DB.
+     * Aquí el provider puede inyectar datos generados (como el webhookSecret).
+     */
+    data?: Record<string, any>;
+    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;
+    }[];
+}
+/**
+ * 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>;
+    /**
+     * 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 {
+    /**
+     * 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>;
+    /**
+     * 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(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>;
+    /**
+     * Retrieve details of a payment by its ID.
+     */
+    getPayment(ctx: ProviderContext, id: string): 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>;
+
+export { BaseProvider, CATEGORY_LABELS, type CheckoutCapabilities, type CheckoutSessionInput, type CheckoutSessionResult, type CheckoutStrategy, type ConfigFieldDefinition, type ConfigFieldType, type CreatePaymentInput, type CreateSubscriptionInput, type EventType, type ICheckoutFeature, type IPaymentFeature, type IProvider, type ISubscriptionFeature, type InstallInput, type InstallResult, type Payment, type PaymentCapabilities, type PaymentMethodDetails, type PaymentResult, PaymentStatus, type ProviderCapabilities, ProviderCategory, type ProviderContext, type ProviderManifest, RevstackError, RevstackErrorCode, type RevstackEvent, type Subscription, type SubscriptionCapabilities, type SubscriptionInterval, type SubscriptionMode, type SubscriptionResult, SubscriptionStatus, type WebhookCapabilities, type WebhookResponse, createError, isRevstackError, validateAndCastConfig };

package/dist/index.js

@@ -0,0 +1,295 @@
+// 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 {
+  /**
+   * 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.`
+    );
+  }
+  /**
+   * Retrieve details of a payment by its ID.
+   */
+  async getPayment(ctx, id) {
+    throw new Error(
+      `Provider '${this.manifest.slug}' does not support getPayment.`
+    );
+  }
+  // ===========================================================================
+  // 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;
+}
+export {
+  BaseProvider,
+  CATEGORY_LABELS,
+  PaymentStatus,
+  ProviderCategory,
+  RevstackError,
+  RevstackErrorCode,
+  SubscriptionStatus,
+  createError,
+  isRevstackError,
+  validateAndCastConfig
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@revstackhq/providers-core",
+  "version": "0.2.0",
+  "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}\""
+  }
+}