stripe-experiment-sync 1.0.21 → 1.0.23

package/dist/index.d.ts

@@ -41,6 +41,11 @@ declare class PostgresClient {
         raw_data: any;
     }, apiKeyHash: string): Promise<void>;
     getAllAccounts(): Promise<any[]>;
+    /**
+     * Get all accounts that have been synced to the database.
+     * Throws a descriptive error if the query fails.
+     */
+    getAllSyncedAccounts(): Promise<any[]>;
     /**
      * Looks up an account ID by API key hash
      * Uses the GIN index on api_key_hashes for fast lookups
@@ -58,6 +63,34 @@ declare class PostgresClient {
     getAccountRecordCounts(accountId: string): Promise<{
         [tableName: string]: number;
     }>;
+    deletePlan(id: string): Promise<boolean>;
+    deleteProduct(id: string): Promise<boolean>;
+    columnExists(table: string, column: string): Promise<boolean>;
+    deleteTaxId(id: string): Promise<boolean>;
+    deletePrice(id: string): Promise<boolean>;
+    deleteRemovedActiveEntitlements(customerId: string, currentActiveEntitlementIds: string[]): Promise<{
+        rowCount: number;
+    }>;
+    /**
+     * 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[];
+    }>;
     deleteAccountWithCascade(accountId: string, useTransaction: boolean): Promise<{
         [tableName: string]: number;
     }>;
@@ -106,12 +139,47 @@ declare class PostgresClient {
      * Auto-cancels stale runs before checking.
      *
      * @param triggeredBy - Worker type (e.g., 'worker', 'sigma-worker'). Runs are isolated per triggeredBy.
-     * @returns RunKey with isNew flag, or null if constraint violation (race condition)
+     * @returns RunKey with isNew flag. Always returns a run (retries on race condition).
      */
     getOrCreateSyncRun(accountId: string, triggeredBy?: string): Promise<{
         accountId: string;
         runStartedAt: Date;
         isNew: boolean;
+    }>;
+    /**
+     * Join an existing sync run or create a new one, and ensure object run rows exist.
+     *
+     * Combines getOrCreateSyncRun + createObjectRuns into a single atomic-ish operation.
+     * Object runs are created idempotently (ON CONFLICT DO NOTHING) so this is safe
+     * to call from multiple workers adding objects to the same run.
+     *
+     * @param accountId - The Stripe account ID
+     * @param triggeredBy - What triggered this sync (for observability)
+     * @param resourceNames - Database resource names (e.g. 'products', 'customers')
+     * @returns Run key with accountId and runStartedAt
+     */
+    joinOrCreateSyncRun(accountId: string, triggeredBy: string, resourceNames: string[], priorities?: Record<string, number>): Promise<{
+        accountId: string;
+        runStartedAt: Date;
+    }>;
+    /**
+     * Find a run that completed successfully (closed with no object errors)
+     * within the given time window.
+     *
+     * @param intervalSeconds - How far back to look, in seconds.
+     */
+    getCompletedRun(accountId: string, intervalSeconds: number): Promise<{
+        accountId: string;
+        runStartedAt: Date;
+    } | null>;
+    /**
+     * Start a reconciliation run only if no run completed successfully in the last 24 hours.
+     *
+     * @returns Run key if a new run was created, or null if a recent successful run exists.
+     */
+    reconciliationRun(accountId: string, triggeredBy: string, resourceNames: string[], interval?: number, priorities?: Record<string, number>): Promise<{
+        accountId: string;
+        runStartedAt: Date;
     } | null>;
     /**
      * Get the active sync run for an account (if any).
@@ -145,8 +213,11 @@ declare class PostgresClient {
      * All objects start as 'pending'.
      *
      * @param resourceNames - Database resource names (e.g. 'products', 'customers', NOT 'product', 'customer')
+     * @param priorities - Optional map of resource name → priority (from resourceRegistry order).
+     *                     Lower values are processed first.
      */
-    createObjectRuns(accountId: string, runStartedAt: Date, resourceNames: string[]): Promise<void>;
+    createObjectRuns(accountId: string, runStartedAt: Date, resourceNames: string[], priorities?: Record<string, number>): Promise<void>;
+    createChunkedObjectRuns(accountId: string, runStartedAt: Date, chunkCursors: Record<string, number[]>, priorities?: Record<string, number>): Promise<void>;
     /**
      * Try to start an object sync (respects max_concurrent).
      * Returns true if claimed, false if already running or at concurrency limit.
@@ -155,6 +226,20 @@ declare class PostgresClient {
      * max_concurrent + 1 objects running. This is acceptable behavior.
      */
     tryStartObjectSync(accountId: string, runStartedAt: Date, object: string): Promise<boolean>;
+    /**
+     * Atomically claim the next pending task using FOR UPDATE SKIP LOCKED.
+     * Two concurrent workers will never claim the same row — the second worker
+     * skips the locked row and grabs the next one.
+     *
+     * Respects max_concurrent: returns null if already at the concurrency limit.
+     */
+    claimNextTask(accountId: string, runStartedAt: Date, rateLimit?: number): Promise<{
+        object: string;
+        cursor: string | null;
+        pageCursor: string | null;
+        created_gte: number | null;
+        created_lte: number | null;
+    } | null>;
     /**
      * Get object run details.
      */
@@ -169,27 +254,47 @@ declare class PostgresClient {
      * Update progress for an object sync.
      * Also touches updated_at for stale detection.
      */
-    incrementObjectProgress(accountId: string, runStartedAt: Date, object: string, count: number): Promise<void>;
+    incrementObjectProgress(accountId: string, runStartedAt: Date, object: string, count: number, createdGte?: number, createdLte?: number): Promise<number>;
+    /**
+     * Atomically update an object sync row in a single round-trip.
+     * Only the fields present in `updates` are written; omitted fields are left unchanged.
+     * Auto-closes the sync run when all objects reach 'complete'.
+     */
+    updateSyncObject(accountId: string, runStartedAt: Date, object: string, createdGte: number, createdLte: number, updates: {
+        processedCount?: number;
+        cursor?: string | null;
+        status?: 'pending' | 'complete' | 'error';
+        pageCursor?: string | null;
+        errorMessage?: string;
+    }): Promise<number>;
     /**
      * Update the pagination page_cursor used for backfills using Stripe list calls.
      */
     updateObjectPageCursor(accountId: string, runStartedAt: Date, object: string, pageCursor: string | null): Promise<void>;
+    /**
+     * Release a running object back to pending with an updated page_cursor.
+     * Used after processing a single page when more pages remain.
+     */
+    releaseObjectSync(accountId: string, runStartedAt: Date, object: string, pageCursor: string, createdGte?: number, createdLte?: number): 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.
+     * Clear the sync cursor on all previous completed runs for an object,
+     * so the next run starts from scratch (no created.gte filter).
      */
-    updateObjectCursor(accountId: string, runStartedAt: Date, object: string, cursor: string | null): Promise<void>;
+    clearObjectCursorHistory(accountId: string, object: string, runStartedAt: Date): Promise<void>;
+    updateObjectCursor(accountId: string, runStartedAt: Date, object: string, cursor: string | null, createdGte?: number, createdLte?: number): Promise<void>;
     setObjectCursor(accountId: string, runStartedAt: Date, object: string, cursor: string | null): Promise<void>;
     /**
      * List object names for a run by status, optionally filtered to a subset.
      */
     listObjectsByStatus(accountId: string, runStartedAt: Date, status: string, objectFilter?: string[]): Promise<string[]>;
+    /**
+     * Get per-object processed counts for a sync run.
+     */
+    getObjectSyncedCounts(accountId: string, runStartedAt: Date): Promise<Record<string, number>>;
     /**
      * Get the highest cursor from previous syncs for an object type.
      * Uses only completed object runs.
@@ -216,16 +321,23 @@ declare class PostgresClient {
      * Useful for testing or resetting sync state.
      */
     deleteSyncRuns(accountId: string): Promise<void>;
+    /**
+     * Reset orphaned 'running' object runs back to 'pending'.
+     * Used for crash recovery: if a worker was killed mid-sync, the object run
+     * is left in 'running' state with no active worker. Resetting to 'pending'
+     * allows new workers to re-claim and finish the work.
+     */
+    resetStuckRunningObjects(accountId: string, runStartedAt: Date, stuckThresholdSeconds?: number): Promise<number>;
     /**
      * Mark an object sync as complete.
      * Auto-closes the run when all objects are done.
      */
-    completeObjectSync(accountId: string, runStartedAt: Date, object: string): Promise<void>;
+    completeObjectSync(accountId: string, runStartedAt: Date, object: string, createdGte?: number, createdLte?: number): 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>;
+    failObjectSync(accountId: string, runStartedAt: Date, object: string, errorMessage: string, createdGte?: number, createdLte?: number): Promise<void>;
     /**
      * Check if any object in a run has errored.
      */
@@ -243,6 +355,7 @@ declare class PostgresClient {
      * Check if all objects in a run are complete (or error).
      */
     areAllObjectsComplete(accountId: string, runStartedAt: Date): Promise<boolean>;
+    countObjectRuns(accountId: string, runStartedAt: Date): Promise<number>;
     /**
      * Closes the database connection pool and cleans up resources.
      * Call this when you're done using the PostgresClient instance.
@@ -325,6 +438,8 @@ type StripeSyncConfig = {
     sigmaSchemaName?: string;
     /** Stripe account ID. If not provided, will be retrieved from Stripe API. Used as fallback option. */
     stripeAccountId?: string;
+    /** Optional Stripe partner ID embedded in appInfo for telemetry (e.g. "pp_supabase"). */
+    partnerId?: 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 */
@@ -347,29 +462,8 @@ type StripeSyncConfig = {
     revalidateObjectsViaStripeApi?: Array<RevalidateEntity>;
     /** @deprecated Use `poolConfig` instead. */
     maxPostgresConnections?: number;
-    poolConfig: PoolConfig;
+    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.
@@ -378,32 +472,10 @@ type StripeSyncConfig = {
     maxConcurrentCustomers?: 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';
+declare const SUPPORTED_WEBHOOK_EVENTS: Stripe.WebhookEndpointCreateParams.EnabledEvent[];
 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;
-    taxIds?: Sync;
-    creditNotes?: Sync;
-    earlyFraudWarnings?: Sync;
-    refunds?: Sync;
-    checkoutSessions?: Sync;
-    subscriptionItemChangeEventsV2Beta?: Sync;
-    exchangeRatesFromUsd?: Sync;
-    /** Sigma-backed results by table name (e.g. subscription_item_change_events_v2_beta). */
-    sigma?: Record<string, Sync>;
-}
 interface SyncParams {
     created?: {
         /**
@@ -463,8 +535,16 @@ interface ProcessNextParams extends SyncParams {
 type BaseResourceConfig = {
     /** Backfill order: lower numbers sync first; parents before children for FK dependencies */
     order: number;
+    /** Database table name for this resource (e.g. 'customers', 'invoices') */
+    tableName: string;
     /** Whether this resource supports incremental sync via 'created' filter or cursor */
     supportsCreatedFilter: boolean;
+    /** Whether this resource is included in sync runs by default. Default: true */
+    sync?: boolean;
+    /** Resource types that must be backfilled before this one (e.g. price depends on product) */
+    dependencies?: string[];
+    /** Function to check if an entity is in a final state and doesn't need revalidation */
+    isFinalState?: (entity: any) => boolean;
 };
 type StripeListResourceConfig = BaseResourceConfig & {
     /** Function to list items from Stripe API */
@@ -474,8 +554,12 @@ type StripeListResourceConfig = BaseResourceConfig & {
         data: unknown[];
         has_more: boolean;
     }>;
-    /** Function to upsert items to database */
-    upsertFn: (items: unknown[], accountId: string, backfillRelated?: boolean) => Promise<unknown[] | void>;
+    /** Function to retrieve a single item by ID from Stripe API */
+    retrieveFn: (id: string) => Promise<Stripe.Response<any>>;
+    /** Optional list of sub-resources to expand during upsert/fetching (e.g. 'refunds', 'listLineItems') */
+    listExpands?: Record<string, (id: string) => Promise<Stripe.ApiList<{
+        id?: string;
+    }>>>[];
     /** discriminator */
     sigma?: undefined;
 };
@@ -491,7 +575,11 @@ type SigmaResourceConfig = BaseResourceConfig & {
     /** discriminator */
     listFn?: undefined;
     /** discriminator */
-    upsertFn?: undefined;
+    retrieveFn?: undefined;
+    /** discriminator */
+    listExpands?: Record<string, (id: string) => Promise<Stripe.ApiList<{
+        id?: string;
+    }>>>[];
 };
 /** Union of all resource configuration types */
 type ResourceConfig = StripeListResourceConfig | SigmaResourceConfig;
@@ -526,6 +614,87 @@ interface StripeSyncState {
     sync_status: StripeSyncAccountState[];
 }
 
+type SigmaSyncProcessorConfig = {
+    stripeSecretKey: string;
+    enableSigma?: boolean;
+    sigmaPageSizeOverride?: number;
+    sigmaSchemaName?: string;
+    logger?: Logger;
+};
+/**
+ * Handles all Sigma-specific sync logic:
+ * - Building the sigma portion of the resource registry
+ * - Fetching a single Sigma page (query + CSV parse + upsert)
+ * - Resolving fallback cursors from destination tables
+ * - Utility helpers (isSigmaResource, getSupportedSigmaObjects)
+ */
+declare class SigmaSyncProcessor {
+    private readonly postgresClient;
+    private readonly config;
+    get sigmaSchemaName(): string;
+    constructor(postgresClient: PostgresClient, config: SigmaSyncProcessorConfig);
+    /**
+     * Build the sigma portion of the resource registry.
+     * Returns entries keyed by sigma table name with order starting after `maxCoreOrder`.
+     */
+    buildSigmaRegistryEntries(maxCoreOrder: number): Record<string, ResourceConfig>;
+    /**
+     * Check whether a resource exists in the sigma registry.
+     */
+    isSigmaResource(sigmaRegistry: Record<string, ResourceConfig>, object: string): boolean;
+    /**
+     * Get the list of Sigma-backed object types that can be synced.
+     * Only returns sigma objects when enableSigma is true.
+     */
+    getSupportedSigmaObjects(sigmaRegistry: Record<string, ResourceConfig>): string[];
+    /**
+     * Fetch the latest cursor from the destination table when no run cursor exists.
+     * Queries the sigma schema for the max cursor column values.
+     */
+    getSigmaFallbackCursorFromDestination(accountId: string, sigmaConfig: SigmaIngestionConfig): Promise<string | null>;
+    /**
+     * Fetch one page of Sigma data, upsert to Postgres, and advance the cursor.
+     */
+    fetchOneSigmaPage(accountId: string, resourceName: string, runStartedAt: Date, cursor: string | null, sigmaConfig: SigmaIngestionConfig): Promise<ProcessNextResult>;
+}
+
+type StripeSyncWebhookDeps = {
+    stripe: Stripe;
+    postgresClient: PostgresClient;
+    config: StripeSyncConfig;
+    readonly accountId: string;
+    getAccountId: (objectAccountId?: string) => Promise<string>;
+    upsertAny: (items: any[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string) => Promise<unknown[]>;
+    resourceRegistry: Record<string, ResourceConfig>;
+};
+declare class StripeSyncWebhook {
+    private readonly deps;
+    constructor(deps: StripeSyncWebhookDeps);
+    processWebhook(payload: Buffer | Uint8Array | string, signature: string | undefined): Promise<void>;
+    processEvent(event: Stripe.Event): Promise<void>;
+    getSupportedEventTypes(): Stripe.WebhookEndpointCreateParams.EnabledEvent[];
+    handleDeletedEvent(event: Stripe.Event, accountId: string): Promise<void>;
+    defaultHandler(event: Stripe.Event, accountId: string): Promise<void>;
+    handleEntitlementSummaryEvent(event: Stripe.Event, accountId: string): Promise<void>;
+    private static readonly RESOURCE_DELETE_EVENTS;
+    private isDeleteEvent;
+    handleAnyEvent(event: Stripe.Event, accountId: string): Promise<void>;
+    getSyncTimestamp(event: Stripe.Event, refetched: boolean): string;
+    findOrCreateManagedWebhook(url: string, params?: Omit<Stripe.WebhookEndpointCreateParams, 'url'>): Promise<Stripe.WebhookEndpoint>;
+    getManagedWebhook(id: string): Promise<Stripe.WebhookEndpoint | null>;
+    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>>;
+}
+
+type StripeObject = 'product' | 'price' | 'plan' | 'customer' | 'subscription' | 'subscription_schedules' | 'invoice' | 'charge' | 'setup_intent' | 'payment_method' | 'payment_intent' | 'tax_id' | 'credit_note' | 'dispute' | 'early_fraud_warning' | 'refund' | 'checkout_sessions' | 'active_entitlements' | 'review';
+/**
+ * Get the database table name for a SyncObject type from the resource registry.
+ */
+declare function getTableName(object: string, registry: Record<string, ResourceConfig>): string;
+
 /**
  * Identifies a specific sync run.
  */
@@ -534,177 +703,58 @@ type RunKey = {
     runStartedAt: Date;
 };
 declare class StripeSync {
-    private config;
     stripe: Stripe;
     postgresClient: PostgresClient;
-    private readonly resourceRegistry;
-    private get sigmaSchemaName();
-    constructor(config: StripeSyncConfig);
-    private buildResourceRegistry;
-    private isSigmaResource;
-    private sigmaResultKey;
+    config: StripeSyncConfig;
+    readonly resourceRegistry: Record<StripeObject, ResourceConfig>;
+    readonly sigmaRegistry: Record<string, ResourceConfig>;
+    webhook: StripeSyncWebhook;
+    readonly sigma: SigmaSyncProcessor;
+    accountId: string;
+    private savedLogger;
+    private previousLineCount;
+    get sigmaSchemaName(): string;
+    private disableLogger;
+    private enableLogger;
+    private constructor();
     /**
-     * Get the Stripe account ID. Delegates to getCurrentAccount() for the actual lookup.
+     * Create a new StripeSync instance. Resolves the default Stripe account,
+     * stores it in the database, and makes the account ID available immediately.
      */
-    getAccountId(objectAccountId?: string): Promise<string>;
+    static create(config: StripeSyncConfig): Promise<StripeSync>;
     /**
-     * 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
+     * Get the Stripe account ID. Returns the default account ID, or resolves
+     * a Connect sub-account ID when provided (Connect scenarios).
      */
-    private upsertAccount;
+    getAccountId(objectAccountId?: string): Promise<string>;
     /**
      * 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;
-    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[];
+    getCurrentAccount(objectAccountId?: string): Promise<Stripe.Account>;
     /**
-     * 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'>[];
-    /**
-     * Get the list of Sigma-backed object types that can be synced.
-     * Only returns sigma objects when enableSigma is true.
-     *
-     * @returns Array of sigma object names (e.g. 'subscription_item_change_events_v2_beta')
-     */
     getSupportedSigmaObjects(): string[];
-    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;
+    syncSingleEntity(stripeId: string): Promise<void>;
+    private getRegistryForObject;
+    findOldestItem(listfn: NonNullable<ResourceConfig['listFn']>): Promise<number | null>;
+    createChunks(objects: StripeObject[], workerCount?: number): Promise<{
+        chunkCursors: Record<string, number[]>;
+        nonChunkTables: string[];
+    }>;
     /**
-     * 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
+     * Build a map of table name → priority (order from resourceRegistry).
+     * Used when creating sync object runs so workers process parents before children.
      */
-    joinOrCreateSyncRun(triggeredBy?: string, objectFilter?: SyncObject): Promise<{
-        runKey: RunKey;
-        objects: Exclude<SyncObject, 'all' | 'customer_with_entitlements'>[];
-    }>;
-    private applySyncBackfillResult;
-    processUntilDoneParallel(params?: SyncParams & {
-        maxParallel?: number;
-        triggeredBy?: string;
-        continueOnError?: boolean;
-        skipInaccessibleSigmaTables?: boolean;
-    }): Promise<{
-        results: SyncBackfill;
+    private buildPriorityMap;
+    initializeSegment(runKey: RunKey, objects: StripeObject[], workerCount: number): Promise<RunKey>;
+    reconciliationSync(objects: StripeObject[], tableNames: string[], segmentedSync: boolean, triggeredBy?: string, interval?: number, workerCount?: number): Promise<RunKey | null>;
+    fullSync(tables?: StripeObject[], segmentedSync?: boolean, workerCount?: number, rateLimit?: number, monitorProgress?: boolean, interval?: number): Promise<{
+        results: Record<string, Sync>;
         totals: Record<string, number>;
         totalSynced: number;
         skipped: string[];
@@ -713,120 +763,80 @@ declare class StripeSync {
             message: string;
         }>;
     }>;
-    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>;
+    upsertAny(items: {
+        [Key: string]: any;
+    }[], // eslint-disable-line @typescript-eslint/no-explicit-any
+    accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<unknown[]>;
+    backfillAny(ids: string[], objectName: StripeObject, accountId: string, syncTimestamp?: string): Promise<unknown[]>;
+    /**
+     * Upsert subscription items into a separate table and mark removed items as deleted.
+     * Skips deleted subscriptions that have no items data.
+     */
+    private syncSubscriptionItems;
     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;
+    upsertActiveEntitlements(customerId: string, activeEntitlements: Stripe.Entitlements.ActiveEntitlement[], accountId: string, backfillRelatedEntities?: boolean, syncTimestamp?: string): Promise<unknown[]>;
+    fetchMissingEntities<T>(ids: string[], fetch: (id: string) => Promise<Stripe.Response<T>>): Promise<T[]>;
     /**
      * Closes the database connection pool and cleans up resources.
      * Call this when you're done using the StripeSync instance.
      */
     close(): Promise<void>;
+    printProgress(runKey: RunKey): Promise<void>;
+    /**
+     * Periodically logs row counts for all tables, refreshing in place.
+     * Returns the interval handle so the caller can clear it.
+     */
+    startTableMonitor(intervalMs: number | undefined, runKey: RunKey): ReturnType<typeof setInterval>;
 }
 
+type SyncTask = {
+    object: string;
+    cursor: string | null;
+    pageCursor: string | null;
+    created_gte: number;
+    created_lte: number;
+};
+declare class StripeSyncWorker {
+    private readonly stripe;
+    private readonly config;
+    private readonly sigma;
+    private readonly postgresClient;
+    private readonly accountId;
+    private readonly resourceRegistry;
+    private readonly sigmaRegistry;
+    private readonly runKey;
+    private readonly upsertAny;
+    private readonly taskLimit;
+    private readonly rateLimit;
+    private running;
+    private loopPromise;
+    private tasksCompleted;
+    constructor(stripe: Stripe, config: StripeSyncConfig, sigma: SigmaSyncProcessor, postgresClient: PostgresClient, accountId: string, resourceRegistry: Record<string, ResourceConfig>, sigmaRegistry: Record<string, ResourceConfig>, runKey: RunKey, upsertAny: (items: {
+        [Key: string]: any;
+    }[], accountId: string, backfillRelated?: boolean) => Promise<unknown[] | void>, taskLimit?: number, rateLimit?: number);
+    start(): void;
+    shutdown(): Promise<void>;
+    private loop;
+    waitUntilDone(): Promise<void>;
+    fetchOnePage(object: string, cursor: string | null, pageCursor: string | null, config: ResourceConfig, created_gte?: number | null, created_lte?: number | null): Promise<{
+        data: unknown[];
+        has_more: boolean;
+    }>;
+    getNextTask(): Promise<SyncTask | null>;
+    updateTaskProgress(task: SyncTask, data: Stripe.Response<Stripe.ApiList<unknown>>['data'], has_more: boolean): Promise<void>;
+    processSingleTask(task: SyncTask): Promise<ProcessNextResult>;
+    private getConfigForTaskObject;
+}
+
+type EmbeddedMigration = {
+    name: string;
+    sql: string;
+};
+declare const embeddedMigrations: EmbeddedMigration[];
+
 type MigrationConfig = {
     databaseUrl: string;
     ssl?: ConnectionOptions;
@@ -834,6 +844,11 @@ type MigrationConfig = {
     enableSigma?: boolean;
 };
 declare function runMigrations(config: MigrationConfig): Promise<void>;
+/**
+ * Run migrations from embedded content (for use in edge functions without filesystem access).
+ * This is compatible with pg-node-migrations table format.
+ */
+declare function runMigrationsFromContent(config: MigrationConfig, migrations: EmbeddedMigration[]): Promise<void>;
 
 /**
  * Hashes a Stripe API key using SHA-256
@@ -878,4 +893,4 @@ declare function createStripeWebSocketClient(options: StripeWebSocketOptions): P
 
 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 };
+export { type BaseResourceConfig, type EmbeddedMigration, type InstallationStatus, type Logger, PostgresClient, type ProcessNextParams, type ProcessNextResult, type ResourceConfig, type RevalidateEntity, SUPPORTED_WEBHOOK_EVENTS, type SigmaResourceConfig, type StripeListResourceConfig, StripeSync, type StripeSyncAccountState, type StripeSyncConfig, type StripeSyncState, StripeSyncWorker, type StripeWebSocketClient, type StripeWebSocketOptions, type StripeWebhookEvent, type Sync, type SyncEntitlementsParams, type SyncFeaturesParams, type SyncObject, type SyncParams, VERSION, type WebhookProcessingResult, createStripeWebSocketClient, embeddedMigrations, getTableName, hashApiKey, runMigrations, runMigrationsFromContent };