Stripe Sync Engine

A TypeScript library to synchronize Stripe data into a PostgreSQL database, designed for use in Node.js backends and serverless environments.

Features

• Programmatic management of Stripe webhooks for real-time updates
• Sync Stripe objects (customers, invoices, products, etc.) to your PostgreSQL database

Installation

npm install stripe-replit-sync stripe
# or
pnpm add stripe-replit-sync stripe
# or
yarn add stripe-replit-sync stripe

Usage

import { StripeSync } from 'stripe-replit-sync'

const sync = new StripeSync({
  poolConfig: {
    connectionString: 'postgres://user:pass@host:port/db',
    max: 10, // Maximum number of connections
  },
  stripeSecretKey: 'sk_test_...',
  stripeWebhookSecret: 'whsec_...',
  // logger: <a pino logger>
})

// Example: process a Stripe webhook
await sync.processWebhook(payload, signature)

Low-Level API (Advanced)

For more control, you can use the StripeSync class directly:

import { StripeSync } from 'stripe-experiment-sync'

const sync = new StripeSync({
  poolConfig: {
    connectionString: 'postgres://user:pass@host:port/db',
    max: 10, // Maximum number of connections
  },
  stripeSecretKey: 'sk_test_...',
  stripeWebhookSecret: 'whsec_...',
  // logger: <a pino logger>
})

// Example: process a Stripe webhook
await sync.processWebhook(payload, signature)

Processing Webhooks

The processWebhook method supports both standard and managed webhook approaches:

// For managed webhooks (with UUID-based routing):
await sync.processWebhook(payload, signature, uuid)

// For standard webhooks (requires stripeWebhookSecret in config):
await sync.processWebhook(payload, signature)

// Or process an event directly (no signature validation):
await sync.processEvent(event)

Managed Webhook Endpoints

The library provides methods to create and manage webhook endpoints with UUID-based routing for security:

// Create or reuse an existing webhook endpoint for a base URL
const { webhook, uuid } = await sync.findOrCreateManagedWebhook(
  'https://example.com/stripe-webhooks',
  {
    enabled_events: ['*'], // or specific events like ['customer.created', 'invoice.paid']
    description: 'My app webhook',
  }
)
// webhook.url will be: https://example.com/stripe-webhooks/{uuid}

// Create a new webhook endpoint (always creates new)
const { webhook, uuid } = await sync.createManagedWebhook('https://example.com/stripe-webhooks', {
  enabled_events: ['customer.created', 'customer.updated'],
})

// Get a managed webhook by ID
const webhook = await sync.getManagedWebhook('we_xxx')

// Delete a managed webhook
await sync.deleteManagedWebhook('we_xxx')

The UUID-based routing allows multiple webhook endpoints for the same base URL, making it ideal for:

• Development environments with ngrok/tunnels that change URLs
• Multi-tenant applications
• Testing and staging environments

Configuration

Database Schema

The library will create and manage a stripe schema in your PostgreSQL database, with tables for all supported Stripe objects (products, customers, invoices, etc.).

Note: Fields and tables prefixed with an underscore (_) are reserved for internal metadata managed by the sync engine and should not be modified directly. These include fields like _account, _cursor, _synced_at, and tables like _migrations, _accounts, and _sync_status.

Migrations

Migrations are included in the db/migrations directory. You can run them using the provided runMigrations function:

import { runMigrations } from 'stripe-replit-sync'

await runMigrations({ databaseUrl: 'postgres://...' })

Account Management

Getting Current Account

Retrieve the currently authenticated Stripe account:

const account = await sync.getCurrentAccount()
console.log(account.id) // e.g., "acct_xxx"

Listing Synced Accounts

Get all Stripe accounts that have been synced to the database:

const accounts = await sync.getAllSyncedAccounts()
// Returns array of Stripe account objects from database

Deleting Synced Account Data

⚠️ DANGEROUS: Delete all synced data for a specific Stripe account from the database. This operation cannot be undone!

// Preview what will be deleted (dry-run mode)
const preview = await sync.dangerouslyDeleteSyncedAccountData('acct_xxx', {
  dryRun: true,
  useTransaction: true,
})
console.log(preview.deletedRecordCounts) // Shows count per table

// Actually delete the data
const result = await sync.dangerouslyDeleteSyncedAccountData('acct_xxx', {
  dryRun: false, // default
  useTransaction: true, // default - wraps deletion in transaction
})

Options:

• dryRun (default: false): If true, only counts records without deleting
• useTransaction (default: true): If true, wraps all deletions in a database transaction for atomicity

The method returns:

• deletedAccountId: The account ID that was deleted
• deletedRecordCounts: Object mapping table names to number of records deleted
• warnings: Array of warning messages (e.g., if you're deleting your cached account)

Backfilling and Syncing Data

Syncing a Single Entity

You can sync or update a single Stripe entity by its ID using the syncSingleEntity method:

await sync.syncSingleEntity('cus_12345')

The entity type is detected automatically based on the Stripe ID prefix (e.g., cus_ for customer, prod_ for product). ent_ is not supported at the moment.

Backfilling Data

To backfill Stripe data (e.g., all products created after a certain date), use the syncBackfill method:

await sync.syncBackfill({
  object: 'product',
  created: { gte: 1643872333 }, // Unix timestamp
})

• object can be one of: all, charge, customer, dispute, invoice, payment_method, payment_intent, plan, price, product, setup_intent, subscription.
• created is a Stripe RangeQueryParam and supports gt, gte, lt, lte.

The sync engine automatically tracks per-account cursors in the _sync_status table. When you call sync methods without an explicit created filter, they will automatically resume from the last synced position for that account and resource. This enables incremental syncing that can resume after interruptions.

Note: For large Stripe accounts (more than 10,000 objects), it is recommended to write a script that loops through each day and sets the created date filters to the start and end of day. This avoids timeouts and memory issues when syncing large datasets.