stripe-experiment-sync 0.0.5 → 1.0.1

package/dist/index.d.cts

@@ -1,78 +1,212 @@
-import { Express } from 'express';
-import pg, { PoolConfig, QueryResult } from 'pg';
-import pino from 'pino';
 import Stripe from 'stripe';
+import pg, { PoolConfig, QueryResult } from 'pg';
 import { ConnectionOptions } from 'node:tls';
 
-interface StripeAutoSyncOptions {
-    databaseUrl: string;
-    stripeApiKey: string;
-    baseUrl: () => string;
-    webhookPath?: string;
-    schema?: string;
-    stripeApiVersion?: string;
-    autoExpandLists?: boolean;
-    backfillRelatedEntities?: boolean;
-    keepWebhooksOnShutdown?: boolean;
-}
-interface StripeAutoSyncInfo {
-    baseUrl: string;
-    webhookUrl: string;
-    webhookUuid: string;
-}
-/**
- * Manages Stripe webhook auto-sync infrastructure:
- * - Runs database migrations
- * - Creates managed webhook in Stripe
- * - Mounts webhook handler on Express app
- */
-declare class StripeAutoSync {
-    private options;
-    private webhookId;
-    private webhookUuid;
-    private stripeSync;
-    constructor(options: StripeAutoSyncOptions);
-    /**
-     * Starts the Stripe Sync infrastructure and mounts webhook handler:
-     * 1. Runs database migrations
-     * 2. Creates StripeSync instance
-     * 3. Creates managed webhook endpoint
-     * 4. Mounts webhook handler on provided Express app
-     * 5. Applies body parsing middleware (automatically skips webhook routes)
+type PostgresConfig = {
+    schema: string;
+    poolConfig: PoolConfig;
+};
+declare class PostgresClient {
+    private config;
+    pool: pg.Pool;
+    constructor(config: PostgresConfig);
+    delete(table: string, id: string): Promise<boolean>;
+    query(text: string, params?: any[]): Promise<QueryResult>;
+    upsertMany<T extends {
+        [Key: string]: any;
+    }>(entries: T[], table: string): Promise<T[]>;
+    upsertManyWithTimestampProtection<T extends {
+        [Key: string]: any;
+    }>(entries: T[], table: string, accountId: string, syncTimestamp?: string): Promise<T[]>;
+    private cleanseArrayField;
+    findMissingEntries(table: string, ids: string[]): Promise<string[]>;
+    upsertAccount(accountData: {
+        id: string;
+        raw_data: any;
+    }, apiKeyHash: string): Promise<void>;
+    getAllAccounts(): Promise<any[]>;
+    /**
+     * Looks up an account ID by API key hash
+     * Uses the GIN index on api_key_hashes for fast lookups
+     * @param apiKeyHash - SHA-256 hash of the Stripe API key
+     * @returns Account ID if found, null otherwise
+     */
+    getAccountIdByApiKeyHash(apiKeyHash: string): Promise<string | null>;
+    /**
+     * Looks up full account data by API key hash
+     * @param apiKeyHash - SHA-256 hash of the Stripe API key
+     * @returns Account raw data if found, null otherwise
+     */
+    getAccountByApiKeyHash(apiKeyHash: string): Promise<any | null>;
+    private getAccountIdColumn;
+    getAccountRecordCounts(accountId: string): Promise<{
+        [tableName: string]: number;
+    }>;
+    deleteAccountWithCascade(accountId: string, useTransaction: boolean): Promise<{
+        [tableName: string]: number;
+    }>;
+    /**
+     * Hash a string to a 32-bit integer for use with PostgreSQL advisory locks.
+     * Uses a simple hash algorithm that produces consistent results.
+     */
+    private hashToInt32;
+    /**
+     * Acquire a PostgreSQL advisory lock for the given key.
+     * This lock is automatically released when the connection is closed or explicitly released.
+     * Advisory locks are session-level and will block until the lock is available.
+     *
+     * @param key - A string key to lock on (will be hashed to an integer)
+     */
+    acquireAdvisoryLock(key: string): Promise<void>;
+    /**
+     * Release a PostgreSQL advisory lock for the given key.
      *
-     * @param app - Express app to mount webhook handler on
-     * @returns Information about the running instance
+     * @param key - The same string key used to acquire the lock
      */
-    start(app: Express): Promise<StripeAutoSyncInfo>;
+    releaseAdvisoryLock(key: string): Promise<void>;
     /**
-     * Stops all services and cleans up resources:
-     * 1. Optionally deletes Stripe webhook endpoint from Stripe and database (based on keepWebhooksOnShutdown)
+     * Execute a function while holding an advisory lock.
+     * The lock is automatically released after the function completes (success or error).
+     *
+     * IMPORTANT: This acquires a dedicated connection from the pool and holds it for the
+     * duration of the function execution. PostgreSQL advisory locks are session-level,
+     * so we must use the same connection for lock acquisition, operations, and release.
+     *
+     * @param key - A string key to lock on (will be hashed to an integer)
+     * @param fn - The function to execute while holding the lock
+     * @returns The result of the function
+     */
+    withAdvisoryLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Cancel stale runs (running but no object updated in 5 minutes).
+     * Called before creating a new run to clean up crashed syncs.
+     * Only cancels runs that have objects AND none have recent activity.
+     * Runs without objects yet (just created) are not considered stale.
+     */
+    cancelStaleRuns(accountId: string): Promise<void>;
+    /**
+     * Get or create a sync run for this account.
+     * Returns existing run if one is active, otherwise creates new one.
+     * Auto-cancels stale runs before checking.
+     *
+     * @returns RunKey with isNew flag, or null if constraint violation (race condition)
+     */
+    getOrCreateSyncRun(accountId: string, triggeredBy?: string): Promise<{
+        accountId: string;
+        runStartedAt: Date;
+        isNew: boolean;
+    } | null>;
+    /**
+     * Get the active sync run for an account (if any).
      */
-    stop(): Promise<void>;
+    getActiveSyncRun(accountId: string): Promise<{
+        accountId: string;
+        runStartedAt: Date;
+    } | null>;
     /**
-     * Returns Express middleware for body parsing that automatically skips webhook routes.
-     * This middleware applies JSON and URL-encoded parsers to all routes EXCEPT the webhook path,
-     * which needs raw body for signature verification.
+     * Get full sync run details.
+     */
+    getSyncRun(accountId: string, runStartedAt: Date): Promise<{
+        accountId: string;
+        runStartedAt: Date;
+        status: string;
+        maxConcurrent: number;
+    } | null>;
+    /**
+     * Mark a sync run as complete.
+     */
+    completeSyncRun(accountId: string, runStartedAt: Date): Promise<void>;
+    /**
+     * Mark a sync run as failed.
+     */
+    failSyncRun(accountId: string, runStartedAt: Date, errorMessage: string): Promise<void>;
+    /**
+     * Create object run entries for a sync run.
+     * All objects start as 'pending'.
+     */
+    createObjectRuns(accountId: string, runStartedAt: Date, objects: string[]): Promise<void>;
+    /**
+     * Try to start an object sync (respects max_concurrent).
+     * Returns true if claimed, false if already running or at concurrency limit.
      *
-     * @returns Express middleware function
+     * Note: There's a small race window where concurrent calls could result in
+     * max_concurrent + 1 objects running. This is acceptable behavior.
+     */
+    tryStartObjectSync(accountId: string, runStartedAt: Date, object: string): Promise<boolean>;
+    /**
+     * Get object run details.
+     */
+    getObjectRun(accountId: string, runStartedAt: Date, object: string): Promise<{
+        object: string;
+        status: string;
+        processedCount: number;
+        cursor: string | null;
+    } | null>;
+    /**
+     * Update progress for an object sync.
+     * Also touches updated_at for stale detection.
+     */
+    incrementObjectProgress(accountId: string, runStartedAt: Date, object: string, count: number): Promise<void>;
+    /**
+     * Update the cursor for an object sync.
+     * Only updates if the new cursor is higher than the existing one (cursors should never decrease).
+     * For numeric cursors (timestamps), uses GREATEST to ensure monotonic increase.
+     * For non-numeric cursors, just sets the value directly.
+     */
+    updateObjectCursor(accountId: string, runStartedAt: Date, object: string, cursor: string | null): Promise<void>;
+    /**
+     * Get the highest cursor from previous syncs for an object type.
+     * This considers completed, error, AND running runs to ensure recovery syncs
+     * don't re-process data that was already synced before a crash.
+     * A 'running' status with a cursor means the process was killed mid-sync.
+     */
+    getLastCompletedCursor(accountId: string, object: string): Promise<string | null>;
+    /**
+     * Delete all sync runs and object runs for an account.
+     * Useful for testing or resetting sync state.
+     */
+    deleteSyncRuns(accountId: string): Promise<void>;
+    /**
+     * Mark an object sync as complete.
+     */
+    completeObjectSync(accountId: string, runStartedAt: Date, object: string): Promise<void>;
+    /**
+     * Mark an object sync as failed.
+     */
+    failObjectSync(accountId: string, runStartedAt: Date, object: string, errorMessage: string): Promise<void>;
+    /**
+     * Count running objects in a run.
+     */
+    countRunningObjects(accountId: string, runStartedAt: Date): Promise<number>;
+    /**
+     * Get the next pending object to process.
+     * Returns null if no pending objects or at concurrency limit.
      */
-    private getBodyParserMiddleware;
+    getNextPendingObject(accountId: string, runStartedAt: Date): Promise<string | null>;
     /**
-     * Mounts the Stripe webhook handler on the provided Express app.
-     * Applies raw body parser middleware for signature verification.
-     * IMPORTANT: Must be called BEFORE app.use(express.json()) to ensure raw body parsing.
+     * Check if all objects in a run are complete (or error).
      */
-    private mountWebhook;
+    areAllObjectsComplete(accountId: string, runStartedAt: Date): Promise<boolean>;
 }
 
+/**
+ * Simple logger interface compatible with both pino and console
+ */
+interface Logger {
+    info(message?: unknown, ...optionalParams: unknown[]): void;
+    warn(message?: unknown, ...optionalParams: unknown[]): void;
+    error(message?: unknown, ...optionalParams: unknown[]): void;
+}
 type RevalidateEntity = 'charge' | 'credit_note' | 'customer' | 'dispute' | 'invoice' | 'payment_intent' | 'payment_method' | 'plan' | 'price' | 'product' | 'refund' | 'review' | 'radar.early_fraud_warning' | 'setup_intent' | 'subscription' | 'subscription_schedule' | 'tax_id' | 'entitlements';
 type StripeSyncConfig = {
     /** @deprecated Use `poolConfig` with a connection string instead. */
     databaseUrl?: string;
-    /** Database schema name. */
-    schema?: string;
     /** Stripe secret key used to authenticate requests to the Stripe API. Defaults to empty string */
     stripeSecretKey: string;
+    /** Stripe account ID. If not provided, will be retrieved from Stripe API. Used as fallback option. */
+    stripeAccountId?: string;
+    /** Stripe webhook signing secret for validating webhook signatures. Required if not using managed webhooks. */
+    stripeWebhookSecret?: string;
     /** Stripe API version for the webhooks, defaults to 2020-08-27 */
     stripeApiVersion?: string;
     /**
@@ -94,7 +228,28 @@ type StripeSyncConfig = {
     /** @deprecated Use `poolConfig` instead. */
     maxPostgresConnections?: number;
     poolConfig: PoolConfig;
-    logger?: pino.Logger;
+    logger?: Logger;
+    /**
+     * Maximum number of retry attempts for 429 rate limit errors.
+     * Default: 5
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds before first retry attempt.
+     * Delay increases exponentially: 1s, 2s, 4s, 8s, 16s, etc.
+     * Default: 1000 (1 second)
+     */
+    initialRetryDelayMs?: number;
+    /**
+     * Maximum delay in milliseconds between retry attempts.
+     * Default: 60000 (60 seconds)
+     */
+    maxRetryDelayMs?: number;
+    /**
+     * Random jitter in milliseconds added to retry delays to prevent thundering herd.
+     * Default: 500
+     */
+    retryJitterMs?: number;
 };
 type SyncObject = 'all' | 'customer' | 'customer_with_entitlements' | 'invoice' | 'price' | 'product' | 'subscription' | 'subscription_schedules' | 'setup_intent' | 'payment_method' | 'dispute' | 'charge' | 'payment_intent' | 'plan' | 'tax_id' | 'credit_note' | 'early_fraud_warning' | 'refund' | 'checkout_sessions';
 interface Sync {
@@ -119,7 +274,7 @@ interface SyncBackfill {
     refunds?: Sync;
     checkoutSessions?: Sync;
 }
-interface SyncBackfillParams {
+interface SyncParams {
     created?: {
         /**
          * Minimum value to filter by (exclusive)
@@ -150,83 +305,287 @@ interface SyncFeaturesParams {
     object: 'features';
     pagination?: Pick<Stripe.PaginationParams, 'starting_after' | 'ending_before'>;
 }
-
-interface EntitySchema {
-    readonly properties: string[];
+/**
+ * Result of processing a single page of items via processNext()
+ */
+interface ProcessNextResult {
+    /** Number of items processed in this page */
+    processed: number;
+    /** Whether there are more items to process */
+    hasMore: boolean;
+    /** The sync run this processing belongs to */
+    runStartedAt: Date;
+}
+/**
+ * Parameters for processNext() including optional run context
+ */
+interface ProcessNextParams extends SyncParams {
+    /** Join an existing sync run instead of creating a new one */
+    runStartedAt?: Date;
+    /** Who/what triggered this sync (for observability) */
+    triggeredBy?: string;
 }
 
-type PostgresConfig = {
-    schema: string;
-    poolConfig: PoolConfig;
-};
-declare class PostgresClient {
+declare class StripeSync {
     private config;
-    pool: pg.Pool;
-    constructor(config: PostgresConfig);
-    delete(table: string, id: string): Promise<boolean>;
-    query(text: string, params?: string[]): Promise<QueryResult>;
-    upsertMany<T extends {
-        [Key: string]: any;
-    }>(entries: T[], table: string, tableSchema: EntitySchema): Promise<T[]>;
-    upsertManyWithTimestampProtection<T extends {
-        [Key: string]: any;
-    }>(entries: T[], table: string, tableSchema: EntitySchema, syncTimestamp?: string): Promise<T[]>;
-    findMissingEntries(table: string, ids: string[]): Promise<string[]>;
+    stripe: Stripe;
+    postgresClient: PostgresClient;
+    constructor(config: StripeSyncConfig);
+    /**
+     * Get the Stripe account ID. Delegates to getCurrentAccount() for the actual lookup.
+     */
+    getAccountId(objectAccountId?: string): Promise<string>;
+    /**
+     * Upsert Stripe account information to the database
+     * @param account - Stripe account object
+     * @param apiKeyHash - SHA-256 hash of API key to store for fast lookups
+     */
+    private upsertAccount;
     /**
-     * Returns an (yesql formatted) upsert function based on the key/vals of an object.
-     * eg,
-     *  insert into customers ("id", "name")
-     *  values (:id, :name)
-     *  on conflict (id)
-     *  do update set (
-     *   "id" = :id,
-     *   "name" = :name
-     *  )
+     * Get the current account being synced. Uses database lookup by API key hash,
+     * with fallback to Stripe API if not found (first-time setup or new API key).
+     * @param objectAccountId - Optional account ID from event data (Connect scenarios)
      */
-    private constructUpsertSql;
+    getCurrentAccount(objectAccountId?: string): Promise<Stripe.Account | null>;
     /**
-     * Returns an (yesql formatted) upsert function with timestamp protection.
+     * Get all accounts that have been synced to the database
+     */
+    getAllSyncedAccounts(): Promise<Stripe.Account[]>;
+    /**
+     * DANGEROUS: Delete an account and all associated data from the database
+     * This operation cannot be undone!
      *
-     * The WHERE clause in ON CONFLICT DO UPDATE only applies to the conflicting row
-     * (the row being updated), not to all rows in the table. PostgreSQL ensures that
-     * the condition is evaluated only for the specific row that conflicts with the INSERT.
+     * @param accountId - The Stripe account ID to delete
+     * @param options - Options for deletion behavior
+     * @param options.dryRun - If true, only count records without deleting (default: false)
+     * @param options.useTransaction - If true, use transaction for atomic deletion (default: true)
+     * @returns Deletion summary with counts and warnings
+     */
+    dangerouslyDeleteSyncedAccountData(accountId: string, options?: {
+        dryRun?: boolean;
+        useTransaction?: boolean;
+    }): Promise<{
+        deletedAccountId: string;
+        deletedRecordCounts: {
+            [tableName: string]: number;
+        };
+        warnings: string[];
+    }>;
+    processWebhook(payload: Buffer | string, signature: string | undefined): Promise<void>;
+    private readonly eventHandlers;
+    private readonly resourceRegistry;
+    processEvent(event: Stripe.Event): Promise<void>;
+    /**
+     * Returns an array of all webhook event types that this sync engine can handle.
+     * Useful for configuring webhook endpoints with specific event subscriptions.
+     */
+    getSupportedEventTypes(): Stripe.WebhookEndpointCreateParams.EnabledEvent[];
+    /**
+     * Returns an array of all object types that can be synced via processNext/processUntilDone.
+     * Ordered for backfill: parents before children (products before prices, customers before subscriptions).
+     * Order is determined by the `order` field in resourceRegistry.
+     */
+    getSupportedSyncObjects(): Exclude<SyncObject, 'all' | 'customer_with_entitlements'>[];
+    private handleChargeEvent;
+    private handleCustomerDeletedEvent;
+    private handleCustomerEvent;
+    private handleCheckoutSessionEvent;
+    private handleSubscriptionEvent;
+    private handleTaxIdEvent;
+    private handleTaxIdDeletedEvent;
+    private handleInvoiceEvent;
+    private handleProductEvent;
+    private handleProductDeletedEvent;
+    private handlePriceEvent;
+    private handlePriceDeletedEvent;
+    private handlePlanEvent;
+    private handlePlanDeletedEvent;
+    private handleSetupIntentEvent;
+    private handleSubscriptionScheduleEvent;
+    private handlePaymentMethodEvent;
+    private handleDisputeEvent;
+    private handlePaymentIntentEvent;
+    private handleCreditNoteEvent;
+    private handleEarlyFraudWarningEvent;
+    private handleRefundEvent;
+    private handleReviewEvent;
+    private handleEntitlementSummaryEvent;
+    private getSyncTimestamp;
+    private shouldRefetchEntity;
+    private fetchOrUseWebhookData;
+    syncSingleEntity(stripeId: string): Promise<Stripe.Product[] | Stripe.Price[] | (Stripe.Customer | Stripe.DeletedCustomer)[] | Stripe.Subscription[] | Stripe.Invoice[] | Stripe.Charge[] | Stripe.SetupIntent[] | Stripe.PaymentMethod[] | Stripe.PaymentIntent[] | Stripe.TaxId[] | Stripe.CreditNote[] | Stripe.Dispute[] | Stripe.Radar.EarlyFraudWarning[] | Stripe.Refund[] | Stripe.Checkout.Session[] | Stripe.Review[] | Stripe.Entitlements.Feature[] | undefined>;
+    /**
+     * Process one page of items for the specified object type.
+     * Returns the number of items processed and whether there are more pages.
      *
+     * This method is designed for queue-based consumption where each page
+     * is processed as a separate job. Uses the observable sync system for tracking.
      *
-     * eg:
-     *   INSERT INTO "stripe"."charges" (
-     *     "id", "amount", "created", "last_synced_at"
-     *   )
-     *   VALUES (
-     *     :id, :amount, :created, :last_synced_at
-     *   )
-     *   ON CONFLICT (id) DO UPDATE SET
-     *     "amount" = EXCLUDED."amount",
-     *     "created" = EXCLUDED."created",
-     *     last_synced_at = :last_synced_at
-     *   WHERE "charges"."last_synced_at" IS NULL
-     *      OR "charges"."last_synced_at" < :last_synced_at;
-     */
-    private constructUpsertWithTimestampProtectionSql;
-    /**
-     * For array object field like invoice.custom_fields
-     * ex: [{"name":"Project name","value":"Test Project"}]
+     * @param object - The Stripe object type to sync (e.g., 'customer', 'product')
+     * @param params - Optional parameters for filtering and run context
+     * @returns ProcessNextResult with processed count, hasMore flag, and runStartedAt
      *
-     * we need to stringify it first cos passing array object directly will end up with
-     * {
-     * invalid input syntax for type json
-     * detail: 'Expected ":", but found "}".',
-     * where: 'JSON data, line 1: ...\\":\\"Project name\\",\\"value\\":\\"Test Project\\"}"}',
+     * @example
+     * ```typescript
+     * // Queue worker
+     * const { hasMore, runStartedAt } = await stripeSync.processNext('customer')
+     * if (hasMore) {
+     *   await queue.send({ object: 'customer', runStartedAt })
      * }
+     * ```
      */
-    private cleanseArrayField;
+    processNext(object: Exclude<SyncObject, 'all' | 'customer_with_entitlements'>, params?: ProcessNextParams): Promise<ProcessNextResult>;
+    /**
+     * Get the database resource name for a SyncObject type
+     */
+    private getResourceName;
+    /**
+     * Fetch one page of items from Stripe and upsert to database.
+     * Uses resourceRegistry for DRY list/upsert operations.
+     * Uses the observable sync system for tracking progress.
+     */
+    private fetchOnePage;
+    /**
+     * Process all pages for all (or specified) object types until complete.
+     *
+     * @param params - Optional parameters for filtering and specifying object types
+     * @returns SyncBackfill with counts for each synced resource type
+     */
+    /**
+     * Process all pages for a single object type until complete.
+     * Loops processNext() internally until hasMore is false.
+     *
+     * @param object - The object type to sync
+     * @param runStartedAt - The sync run to use (for sharing across objects)
+     * @param params - Optional sync parameters
+     * @returns Sync result with count of synced items
+     */
+    private processObjectUntilDone;
+    processUntilDone(params?: SyncParams): Promise<SyncBackfill>;
+    /**
+     * Internal implementation of processUntilDone with an existing run.
+     */
+    private processUntilDoneWithRun;
+    /**
+     * Sync payment methods with an existing run (special case - iterates customers)
+     */
+    private syncPaymentMethodsWithRun;
+    syncProducts(syncParams?: SyncParams): Promise<Sync>;
+    syncPrices(syncParams?: SyncParams): Promise<Sync>;
+    syncPlans(syncParams?: SyncParams): Promise<Sync>;
+    syncCustomers(syncParams?: SyncParams): Promise<Sync>;
+    syncSubscriptions(syncParams?: SyncParams): Promise<Sync>;
+    syncSubscriptionSchedules(syncParams?: SyncParams): Promise<Sync>;
+    syncInvoices(syncParams?: SyncParams): Promise<Sync>;
+    syncCharges(syncParams?: SyncParams): Promise<Sync>;
+    syncSetupIntents(syncParams?: SyncParams): Promise<Sync>;
+    syncPaymentIntents(syncParams?: SyncParams): Promise<Sync>;
+    syncTaxIds(syncParams?: SyncParams): Promise<Sync>;
+    syncPaymentMethods(syncParams?: SyncParams): Promise<Sync>;
+    syncDisputes(syncParams?: SyncParams): Promise<Sync>;
+    syncEarlyFraudWarnings(syncParams?: SyncParams): Promise<Sync>;
+    syncRefunds(syncParams?: SyncParams): Promise<Sync>;
+    syncCreditNotes(syncParams?: SyncParams): Promise<Sync>;
+    syncFeatures(syncParams?: SyncFeaturesParams): Promise<Sync>;
+    syncEntitlements(customerId: string, syncParams?: SyncEntitlementsParams): Promise<Sync>;
+    syncCheckoutSessions(syncParams?: SyncParams): Promise<Sync>;
+    /**
+     * Helper to wrap a sync operation in the observable sync system.
+     * Creates/gets a sync run, sets up the object run, gets cursor, and handles completion.
+     *
+     * @param resourceName - The resource being synced (e.g., 'products', 'customers')
+     * @param triggeredBy - What triggered this sync (for observability)
+     * @param fn - The sync function to execute, receives cursor and runStartedAt
+     * @returns The result of the sync function
+     */
+    private withSyncRun;
+    private fetchAndUpsert;
+    private upsertCharges;
+    private backfillCharges;
+    private backfillPaymentIntents;
+    private upsertCreditNotes;
+    upsertCheckoutSessions(checkoutSessions: Stripe.Checkout.Session[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.Checkout.Session[]>;
+    upsertEarlyFraudWarning(earlyFraudWarnings: Stripe.Radar.EarlyFraudWarning[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.Radar.EarlyFraudWarning[]>;
+    upsertRefunds(refunds: Stripe.Refund[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.Refund[]>;
+    upsertReviews(reviews: Stripe.Review[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.Review[]>;
+    upsertCustomers(customers: (Stripe.Customer | Stripe.DeletedCustomer)[], accountId: string, syncTimestamp?: string): Promise<(Stripe.Customer | Stripe.DeletedCustomer)[]>;
+    backfillCustomers(customerIds: string[], accountId: string): Promise<void>;
+    upsertDisputes(disputes: Stripe.Dispute[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.Dispute[]>;
+    upsertInvoices(invoices: Stripe.Invoice[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.Invoice[]>;
+    backfillInvoices: (invoiceIds: string[], accountId: string) => Promise<void>;
+    backfillPrices: (priceIds: string[], accountId: string) => Promise<void>;
+    upsertPlans(plans: Stripe.Plan[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.Plan[]>;
+    deletePlan(id: string): Promise<boolean>;
+    upsertPrices(prices: Stripe.Price[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.Price[]>;
+    deletePrice(id: string): Promise<boolean>;
+    upsertProducts(products: Stripe.Product[], accountId: string, syncTimestamp?: string): Promise<Stripe.Product[]>;
+    deleteProduct(id: string): Promise<boolean>;
+    backfillProducts(productIds: string[], accountId: string): Promise<void>;
+    upsertPaymentIntents(paymentIntents: Stripe.PaymentIntent[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.PaymentIntent[]>;
+    upsertPaymentMethods(paymentMethods: Stripe.PaymentMethod[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.PaymentMethod[]>;
+    upsertSetupIntents(setupIntents: Stripe.SetupIntent[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.SetupIntent[]>;
+    upsertTaxIds(taxIds: Stripe.TaxId[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.TaxId[]>;
+    deleteTaxId(id: string): Promise<boolean>;
+    upsertSubscriptionItems(subscriptionItems: Stripe.SubscriptionItem[], accountId: string, syncTimestamp?: string): Promise<void>;
+    fillCheckoutSessionsLineItems(checkoutSessionIds: string[], accountId: string, syncTimestamp?: string): Promise<void>;
+    upsertCheckoutSessionLineItems(lineItems: Stripe.LineItem[], checkoutSessionId: string, accountId: string, syncTimestamp?: string): Promise<void>;
+    markDeletedSubscriptionItems(subscriptionId: string, currentSubItemIds: string[]): Promise<{
+        rowCount: number;
+    }>;
+    upsertSubscriptionSchedules(subscriptionSchedules: Stripe.SubscriptionSchedule[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.SubscriptionSchedule[]>;
+    upsertSubscriptions(subscriptions: Stripe.Subscription[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<Stripe.Subscription[]>;
+    deleteRemovedActiveEntitlements(customerId: string, currentActiveEntitlementIds: string[]): Promise<{
+        rowCount: number;
+    }>;
+    upsertFeatures(features: Stripe.Entitlements.Feature[], accountId: string, syncTimestamp?: string): Promise<Stripe.Entitlements.Feature[]>;
+    backfillFeatures(featureIds: string[], accountId: string): Promise<void>;
+    upsertActiveEntitlements(customerId: string, activeEntitlements: Stripe.Entitlements.ActiveEntitlement[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<{
+        id: string;
+        object: "entitlements.active_entitlement";
+        feature: string;
+        customer: string;
+        livemode: boolean;
+        lookup_key: string;
+    }[]>;
+    findOrCreateManagedWebhook(url: string, params?: Omit<Stripe.WebhookEndpointCreateParams, 'url'>): Promise<Stripe.WebhookEndpoint>;
+    getManagedWebhook(id: string): Promise<Stripe.WebhookEndpoint | null>;
+    /**
+     * Get a managed webhook by URL and account ID.
+     * Used for race condition recovery: when createManagedWebhook hits a unique constraint
+     * violation (another instance created the webhook), we need to fetch the existing webhook
+     * by URL since we only know the URL, not the ID of the webhook that won the race.
+     */
+    getManagedWebhookByUrl(url: string): Promise<Stripe.WebhookEndpoint | null>;
+    listManagedWebhooks(): Promise<Array<Stripe.WebhookEndpoint>>;
+    updateManagedWebhook(id: string, params: Stripe.WebhookEndpointUpdateParams): Promise<Stripe.WebhookEndpoint>;
+    deleteManagedWebhook(id: string): Promise<boolean>;
+    upsertManagedWebhooks(webhooks: Array<Stripe.WebhookEndpoint>, accountId: string, syncTimestamp?: string): Promise<Array<Stripe.WebhookEndpoint>>;
+    backfillSubscriptions(subscriptionIds: string[], accountId: string): Promise<void>;
+    backfillSubscriptionSchedules: (subscriptionIds: string[], accountId: string) => Promise<void>;
+    /**
+     * Stripe only sends the first 10 entries by default, the option will actively fetch all entries.
+     */
+    private expandEntity;
+    private fetchMissingEntities;
 }
 
 type MigrationConfig = {
-    schema: string;
     databaseUrl: string;
     ssl?: ConnectionOptions;
-    logger?: pino.Logger;
+    logger?: Logger;
 };
 declare function runMigrations(config: MigrationConfig): Promise<void>;
 
-export { PostgresClient, type RevalidateEntity, StripeAutoSync, type StripeAutoSyncInfo, type StripeAutoSyncOptions, type StripeSyncConfig, type Sync, type SyncBackfill, type SyncBackfillParams, type SyncEntitlementsParams, type SyncFeaturesParams, type SyncObject, runMigrations };
+/**
+ * Hashes a Stripe API key using SHA-256
+ * Used to store API key hashes in the database for fast account lookups
+ * without storing the actual API key or making Stripe API calls
+ *
+ * @param apiKey - The Stripe API key (e.g., sk_test_... or sk_live_...)
+ * @returns SHA-256 hash of the API key as a hex string
+ */
+declare function hashApiKey(apiKey: string): string;
+
+declare const VERSION: string;
+
+export { type Logger, PostgresClient, type ProcessNextParams, type ProcessNextResult, type RevalidateEntity, StripeSync, type StripeSyncConfig, type Sync, type SyncBackfill, type SyncEntitlementsParams, type SyncFeaturesParams, type SyncObject, type SyncParams, VERSION, hashApiKey, runMigrations };