@paymentsdb/sync-engine 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,815 @@
+import Stripe from 'stripe';
+import pg, { PoolConfig, QueryResult } from 'pg';
+import { ConnectionOptions } from 'node:tls';
+
+type PostgresConfig = {
+    schema: string;
+    poolConfig: PoolConfig;
+};
+type RawJsonUpsertOptions = {
+    /**
+     * Columns to use as the ON CONFLICT target.
+     * Example: ['id'] for standard Stripe objects, or a composite key for Sigma tables.
+     */
+    conflictTarget: string[];
+    /**
+     * Additional typed columns to insert alongside `_raw_data` (for tables that don't have `id` keys).
+     * Values are read from `entry[entryKey]` and cast to `pgType` in SQL.
+     */
+    extraColumns?: Array<{
+        column: string;
+        pgType: string;
+        entryKey: string;
+    }>;
+};
+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, upsertOptions?: RawJsonUpsertOptions): 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 key - The same string key used to acquire the lock
+     */
+    releaseAdvisoryLock(key: string): Promise<void>;
+    /**
+     * 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).
+     */
+    getActiveSyncRun(accountId: string): Promise<{
+        accountId: string;
+        runStartedAt: Date;
+    } | null>;
+    /**
+     * Get sync run config (for concurrency control).
+     * Status is derived from sync_runs view.
+     */
+    getSyncRun(accountId: string, runStartedAt: Date): Promise<{
+        accountId: string;
+        runStartedAt: Date;
+        maxConcurrent: number;
+        closedAt: Date | null;
+    } | null>;
+    /**
+     * Close a sync run (mark as done).
+     * Status (complete/error) is derived from object run states.
+     */
+    closeSyncRun(accountId: string, runStartedAt: Date): Promise<void>;
+    /**
+     * Create object run entries for a sync run.
+     * All objects start as 'pending'.
+     *
+     * @param resourceNames - Database resource names (e.g. 'products', 'customers', NOT 'product', 'customer')
+     */
+    createObjectRuns(accountId: string, runStartedAt: Date, resourceNames: string[]): Promise<void>;
+    /**
+     * Try to start an object sync (respects max_concurrent).
+     * Returns true if claimed, false if already running or at concurrency limit.
+     *
+     * 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;
+        pageCursor: 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 pagination page_cursor used for backfills using Stripe list calls.
+     */
+    updateObjectPageCursor(accountId: string, runStartedAt: Date, object: string, pageCursor: string | null): Promise<void>;
+    /**
+     * Clear the pagination page_cursor for an object sync.
+     */
+    clearObjectPageCursor(accountId: string, runStartedAt: Date, object: string): 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.
+     * Uses only completed object runs.
+     * - During the initial backfill we page through history, but we also update the cursor as we go.
+     *   If we crash mid-backfill and reuse that cursor, we can accidentally switch into incremental mode
+     *   too early and only ever fetch the newest page (breaking the historical backfill).
+     *
+     * Handles two cursor formats:
+     * - Numeric: compared as bigint for correct ordering
+     * - Composite cursors: compared as strings with COLLATE "C"
+     */
+    getLastCompletedCursor(accountId: string, object: string): Promise<string | null>;
+    /**
+     * Get the highest cursor from previous syncs for an object type, excluding the current run.
+     */
+    getLastCursorBeforeRun(accountId: string, object: string, runStartedAt: Date): 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.
+     * Auto-closes the run when all objects are done.
+     */
+    completeObjectSync(accountId: string, runStartedAt: Date, object: string): Promise<void>;
+    /**
+     * Mark an object sync as failed.
+     * Auto-closes the run when all objects are done.
+     */
+    failObjectSync(accountId: string, runStartedAt: Date, object: string, errorMessage: string): Promise<void>;
+    /**
+     * Check if any object in a run has errored.
+     */
+    hasAnyObjectErrors(accountId: string, runStartedAt: Date): Promise<boolean>;
+    /**
+     * 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.
+     */
+    getNextPendingObject(accountId: string, runStartedAt: Date): Promise<string | null>;
+    /**
+     * Check if all objects in a run are complete (or error).
+     */
+    areAllObjectsComplete(accountId: string, runStartedAt: Date): Promise<boolean>;
+    /**
+     * Closes the database connection pool and cleans up resources.
+     * Call this when you're done using the PostgresClient instance.
+     */
+    close(): Promise<void>;
+}
+
+type SigmaCursorColumnType = 'timestamp' | 'string' | 'number';
+type SigmaCursorColumnSpec = {
+    column: string;
+    type: SigmaCursorColumnType;
+};
+type SigmaCursorSpec = {
+    version: 1;
+    columns: SigmaCursorColumnSpec[];
+};
+type SigmaIngestionConfig = {
+    /**
+     * The Sigma table name to query (no quoting, no schema).
+     */
+    sigmaTable: string;
+    /**
+     * Destination Postgres table name (in the `stripe` schema by convention).
+     */
+    destinationTable: string;
+    /** Limit for each Sigma query page. */
+    pageSize: number;
+    /**
+     * Defines the ordering and cursor semantics. The columns must form a total order (i.e. be unique together) or pagination can be incorrect.
+     */
+    cursor: SigmaCursorSpec;
+    /** Optional additional WHERE clause appended with AND (must not include leading WHERE). */
+    additionalWhere?: string;
+    /** Columns to SELECT (defaults to `*`). */
+    select?: '*' | string[];
+    /** Postgres upsert behavior for this table (conflict target and typed columns). */
+    upsert: RawJsonUpsertOptions;
+};
+
+/**
+ * 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;
+    /** Stripe secret key used to authenticate requests to the Stripe API. Defaults to empty string */
+    stripeSecretKey: string;
+    /**
+     * Enables syncing Stripe Sigma (reporting) tables via the Sigma API.
+     *
+     * Default: false (opt-in, so workers don't enqueue Sigma jobs unexpectedly).
+     */
+    enableSigma?: boolean;
+    /** 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;
+    /**
+     * Stripe limits related lists like invoice items in an invoice to 10 by default.
+     * By enabling this, sync-engine automatically fetches the remaining elements before saving
+     * */
+    autoExpandLists?: boolean;
+    /**
+     * If true, the sync engine will backfill related entities, i.e. when a invoice webhook comes in, it ensures that the customer is present and synced.
+     * This ensures foreign key integrity, but comes at the cost of additional queries to the database (and added latency for Stripe calls if the entity is actually missing).
+     */
+    backfillRelatedEntities?: boolean;
+    /**
+     * If true, the webhook data is not used and instead the webhook is just a trigger to fetch the entity from Stripe again. This ensures that a race condition with failed webhooks can never accidentally overwrite the data with an older state.
+     *
+     * Default: false
+     */
+    revalidateObjectsViaStripeApi?: Array<RevalidateEntity>;
+    /** @deprecated Use `poolConfig` instead. */
+    maxPostgresConnections?: number;
+    poolConfig: PoolConfig;
+    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;
+    /**
+     * Maximum number of customers to process concurrently when syncing payment methods.
+     * Lower values reduce API load but increase sync time.
+     * Default: 10
+     */
+    maxConcurrentCustomers?: number;
+};
+type SyncObject = 'all' | 'customer' | 'customer_with_entitlements' | 'invoice' | 'price' | 'product' | 'subscription' | 'subscription_schedules' | 'setup_intent' | 'payment_method' | 'dispute' | 'charge' | 'balance_transaction' | 'payment_intent' | 'plan' | 'tax_id' | 'credit_note' | 'early_fraud_warning' | 'refund' | 'checkout_sessions' | 'subscription_item_change_events_v2_beta' | 'exchange_rates_from_usd';
+interface Sync {
+    synced: number;
+}
+interface SyncBackfill {
+    products?: Sync;
+    prices?: Sync;
+    plans?: Sync;
+    customers?: Sync;
+    subscriptions?: Sync;
+    subscriptionSchedules?: Sync;
+    invoices?: Sync;
+    setupIntents?: Sync;
+    paymentIntents?: Sync;
+    paymentMethods?: Sync;
+    disputes?: Sync;
+    charges?: Sync;
+    balanceTransactions?: Sync;
+    taxIds?: Sync;
+    creditNotes?: Sync;
+    earlyFraudWarnings?: Sync;
+    refunds?: Sync;
+    checkoutSessions?: Sync;
+    subscriptionItemChangeEventsV2Beta?: Sync;
+    exchangeRatesFromUsd?: Sync;
+}
+interface SyncParams {
+    created?: {
+        /**
+         * Minimum value to filter by (exclusive)
+         */
+        gt?: number;
+        /**
+         * Minimum value to filter by (inclusive)
+         */
+        gte?: number;
+        /**
+         * Maximum value to filter by (exclusive)
+         */
+        lt?: number;
+        /**
+         * Maximum value to filter by (inclusive)
+         */
+        lte?: number;
+    };
+    object?: SyncObject;
+    backfillRelatedEntities?: boolean;
+}
+interface SyncEntitlementsParams {
+    object: 'entitlements';
+    customerId: string;
+    pagination?: Pick<Stripe.PaginationParams, 'starting_after' | 'ending_before'>;
+}
+interface SyncFeaturesParams {
+    object: 'features';
+    pagination?: Pick<Stripe.PaginationParams, 'starting_after' | 'ending_before'>;
+}
+/**
+ * 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;
+}
+/**
+ * Syncable resource configuration
+ */
+type BaseResourceConfig = {
+    /** Backfill order: lower numbers sync first; parents before children for FK dependencies */
+    order: number;
+    /** Whether this resource supports incremental sync via 'created' filter or cursor */
+    supportsCreatedFilter: boolean;
+};
+type StripeListResourceConfig = BaseResourceConfig & {
+    /** Function to list items from Stripe API */
+    listFn: (params: Stripe.PaginationParams & {
+        created?: Stripe.RangeQueryParam;
+    }) => Promise<{
+        data: unknown[];
+        has_more: boolean;
+    }>;
+    /** Function to upsert items to database */
+    upsertFn: (items: unknown[], accountId: string, backfillRelated?: boolean) => Promise<unknown[] | void>;
+    /** discriminator */
+    sigma?: undefined;
+};
+/**
+ * Configuration for Sigma query-backed resources.
+ * Uses Stripe Sigma SQL queries with composite cursor pagination.
+ */
+type SigmaResourceConfig = BaseResourceConfig & {
+    /** Sigma uses composite cursors, not created filter */
+    supportsCreatedFilter: false;
+    /** Sigma ingestion configuration (query, cursor spec, upsert options) */
+    sigma: SigmaIngestionConfig;
+    /** discriminator */
+    listFn?: undefined;
+    /** discriminator */
+    upsertFn?: undefined;
+};
+/** Union of all resource configuration types */
+type ResourceConfig = StripeListResourceConfig | SigmaResourceConfig;
+/**
+ * Installation status of the stripe-sync package
+ */
+type InstallationStatus = 'not_installed' | 'installing' | 'installed' | 'error';
+/**
+ * Sync status for a single account (from sync_runs view)
+ */
+interface StripeSyncAccountState {
+    account_id: string;
+    started_at: string;
+    closed_at: string | null;
+    status: 'pending' | 'running' | 'complete' | 'error';
+    error_message: string | null;
+    total_processed: number;
+    total_objects: number;
+    complete_count: number;
+    error_count: number;
+    running_count: number;
+    pending_count: number;
+    triggered_by: string;
+    max_concurrent: number;
+}
+/**
+ * Response schema for the sync status endpoint
+ */
+interface StripeSyncState {
+    package_version: string;
+    installation_status: InstallationStatus;
+    sync_status: StripeSyncAccountState[];
+}
+
+/**
+ * Identifies a specific sync run.
+ */
+type RunKey = {
+    accountId: string;
+    runStartedAt: Date;
+};
+declare class StripeSync {
+    private config;
+    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;
+    /**
+     * 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)
+     */
+    getCurrentAccount(objectAccountId?: string): Promise<Stripe.Account | null>;
+    /**
+     * 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!
+     *
+     * @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.
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * // Queue worker
+     * const { hasMore, runStartedAt } = await stripeSync.processNext('customer')
+     * if (hasMore) {
+     *   await queue.send({ object: 'customer', runStartedAt })
+     * }
+     * ```
+     */
+    processNext(object: Exclude<SyncObject, 'all' | 'customer_with_entitlements'>, params?: ProcessNextParams): Promise<ProcessNextResult>;
+    private appendMigrationHint;
+    /**
+     * 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;
+    private getSigmaFallbackCursorFromDestination;
+    private fetchOneSigmaPage;
+    /**
+     * 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;
+    /**
+     * Join existing sync run or create a new one.
+     * Returns sync run key and list of supported objects to sync.
+     *
+     * Cooperative behavior: If a sync run already exists, joins it instead of failing.
+     * This is used by workers and background processes that should cooperate.
+     *
+     * @param triggeredBy - What triggered this sync (for observability)
+     * @param objectFilter - Optional specific object to sync (e.g. 'payment_intent'). If 'all' or undefined, syncs all objects.
+     * @returns Run key and list of objects to sync
+     */
+    joinOrCreateSyncRun(triggeredBy?: string, objectFilter?: SyncObject): Promise<{
+        runKey: RunKey;
+        objects: Exclude<SyncObject, 'all' | 'customer_with_entitlements'>[];
+    }>;
+    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>;
+    syncBalanceTransactions(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 upsertBalanceTransactions;
+    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.
+     * Uses manual pagination - each fetch() gets automatic retry protection.
+     */
+    private expandEntity;
+    private fetchMissingEntities;
+    /**
+     * Closes the database connection pool and cleans up resources.
+     * Call this when you're done using the StripeSync instance.
+     */
+    close(): Promise<void>;
+}
+
+type MigrationConfig = {
+    databaseUrl: string;
+    ssl?: ConnectionOptions;
+    logger?: Logger;
+};
+declare function runMigrations(config: MigrationConfig): Promise<void>;
+
+/**
+ * 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;
+
+interface WebhookProcessingResult {
+    status: number;
+    databaseUrl: string;
+    event_type?: string;
+    event_id?: string;
+    error?: string;
+}
+interface StripeWebSocketOptions {
+    stripeApiKey: string;
+    onEvent: (event: StripeWebhookEvent) => Promise<WebhookProcessingResult | void> | WebhookProcessingResult | void;
+    onReady?: (secret: string) => void;
+    onError?: (error: Error) => void;
+    onClose?: (code: number, reason: string) => void;
+}
+interface StripeWebSocketClient {
+    close: () => void;
+    isConnected: () => boolean;
+}
+interface StripeWebhookEvent {
+    type: string;
+    webhook_id: string;
+    webhook_conversation_id: string;
+    event_payload: string;
+    http_headers: Record<string, string>;
+    endpoint: {
+        url: string;
+        status: string;
+    };
+}
+declare function createStripeWebSocketClient(options: StripeWebSocketOptions): Promise<StripeWebSocketClient>;
+
+declare const VERSION: string;
+
+export { type BaseResourceConfig, type InstallationStatus, type Logger, PostgresClient, type ProcessNextParams, type ProcessNextResult, type ResourceConfig, type RevalidateEntity, type SigmaResourceConfig, type StripeListResourceConfig, StripeSync, type StripeSyncAccountState, type StripeSyncConfig, type StripeSyncState, type StripeWebSocketClient, type StripeWebSocketOptions, type StripeWebhookEvent, type Sync, type SyncBackfill, type SyncEntitlementsParams, type SyncFeaturesParams, type SyncObject, type SyncParams, VERSION, type WebhookProcessingResult, createStripeWebSocketClient, hashApiKey, runMigrations };