@revstackhq/providers-core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -16,16 +16,19 @@ interface ProviderContext {
      * Indicates if the operation is running in Sandbox/Test mode.
      */
     isTestMode: boolean;
+    /**
+     * Optional: Idempotency key for duplicate request prevention.
+     */
+    idempotencyKey?: string;
 }
 
 /**
- * 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
+    Authorized = "authorized",// Funds held but not captured yet
     Succeeded = "succeeded",
     Failed = "failed",
     Refunded = "refunded",
@@ -38,68 +41,59 @@ type PaymentMethodDetails = {
     brand?: string;
     last4?: string;
     email?: string;
+    expiryMonth?: number;
+    expiryYear?: number;
+    cardHolderName?: 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 */
+    /** * Financial breakdown, vital for invoicing and tax calculation.
+     */
+    amountDetails?: {
+        subtotal: number;
+        tax: number;
+        shipping: number;
+        discount: number;
+        fee?: number;
+    };
     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
+    PastDue = "past_due",
     Canceled = "canceled",
-    Unpaid = "unpaid",// Grace period ended, service cut
-    Incomplete = "incomplete",// Created but waiting for first payment (3DS)
+    Unpaid = "unpaid",
+    Incomplete = "incomplete",
     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;
+    interval: "day" | "week" | "month" | "year";
     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;
@@ -108,222 +102,211 @@ type Subscription = {
     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>;
-    /** 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;
+type RefundPaymentInput = {
+    paymentId: string;
+    externalPaymentId?: string;
     amount?: number;
-    currency?: string;
-    trialDays?: number;
+    reason?: "duplicate" | "fraudulent" | "requested_by_customer";
     metadata?: Record<string, any>;
 };
-type SubscriptionResult = {
-    subscription: Subscription;
+type SetupPaymentMethodInput = {
+    customerId: string;
+    returnUrl: string;
+    metadata?: Record<string, any>;
 };
 type CheckoutSessionInput = {
     customerId?: string;
-    /** Items to purchase */
+    customerEmail?: string;
+    setupFutureUsage?: boolean;
     lineItems: {
         name: string;
         amount: number;
         quantity: number;
         currency: string;
         images?: string[];
+        taxRates?: string[];
     }[];
     successUrl: string;
     cancelUrl: string;
-    mode: "payment" | "subscription";
+    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>;
+};
 
-/**
- * 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>;
+    getPayment(ctx: ProviderContext, id: string): Promise<Payment>;
+    refundPayment(ctx: ProviderContext, input: RefundPaymentInput): Promise<Payment>;
+    listPayments?(ctx: ProviderContext, pagination: PaginationOptions): Promise<PaginatedResult<Payment>>;
 }
-/**
- * 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>;
+    pauseSubscription(ctx: ProviderContext, id: string): Promise<SubscriptionResult>;
+    resumeSubscription(ctx: ProviderContext, id: string): Promise<SubscriptionResult>;
+    getSubscription(ctx: ProviderContext, id: string): Promise<Subscription>;
 }
-/**
- * Contract for providers that offer a hosted checkout page.
- */
 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>;
+}
 /**
- * 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).
+ * Unified interface that all providers must satisfy.
+ * (Even if they just throw 'Not Implemented' errors for unsupported features).
  */
-interface IProvider extends IPaymentFeature, ISubscriptionFeature, ICheckoutFeature {
+interface IProvider extends IPaymentFeature, ISubscriptionFeature, ICheckoutFeature, ICustomerFeature, IPaymentMethodFeature {
 }
 
-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.
- */
+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 {
-    /** 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 */
+    originalPayload: any;
     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 ProviderCapabilities {
+    checkout: {
+        supported: boolean;
+        strategy: "redirect" | "native_sdk" | "sdui";
     };
-}
-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;
+    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";
     };
-}
-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;
 }
 
 /**
@@ -400,25 +383,25 @@ declare function createError(code: RevstackErrorCode, message: string, provider?
 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}
+     * The absolute URL where Revstack expects to receive events for this merchant.
      */
     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;
 }
+interface UninstallInput {
+    config: Record<string, any>;
+    data: Record<string, any>;
+}
+interface UninstallResult {
+    success: boolean;
+    error?: RevstackError;
+}
 
 declare enum ProviderCategory {
     Card = "card",// Stripe, Adyen, dLocal
@@ -455,6 +438,16 @@ interface ConfigFieldDefinition {
         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.
@@ -498,6 +491,11 @@ interface ProviderManifest {
      * 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.
      */
@@ -515,6 +513,16 @@ interface ProviderManifest {
  * 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).
@@ -531,6 +539,17 @@ declare abstract class BaseProvider implements IProvider {
      * @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:
@@ -540,7 +559,7 @@ declare abstract class BaseProvider implements IProvider {
      * @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>;
+    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.
@@ -561,10 +580,6 @@ declare abstract class BaseProvider implements IProvider {
      * * @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.
@@ -589,4 +604,18 @@ declare abstract class BaseProvider implements IProvider {
  */
 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 };
+/**
+ * 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

@@ -164,6 +164,36 @@ var CATEGORY_LABELS = {
 
 // 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.
@@ -186,14 +216,6 @@ var BaseProvider = class {
       `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)
   // ===========================================================================
@@ -281,6 +303,49 @@ function validateAndCastConfig(rawConfig, schema) {
   }
   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,
@@ -291,5 +356,7 @@ export {
   SubscriptionStatus,
   createError,
   isRevstackError,
-  validateAndCastConfig
+  runSmoke,
+  validateAndCastConfig,
+  verifyHmacSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revstackhq/providers-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",