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 validates and processes Stripe webhook events:

// Process a webhook event with signature validation
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:

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

// Create a new webhook endpoint (always creates new)
const webhook = 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')

Note: The library automatically manages webhook endpoints for you. When you call findOrCreateManagedWebhook() with a URL, it will reuse an existing webhook if one is found in the database, or create a new one if needed. Old or orphaned webhooks from this package are automatically cleaned up.

Race Condition Protection: The library uses PostgreSQL advisory locks to prevent race conditions when multiple instances call findOrCreateManagedWebhook() concurrently for the same URL. A unique constraint on (url, account_id) provides an additional safety net at the database level.

Configuration

| Option | Type | Description | | ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | databaseUrl | string | Deprecated: Use poolConfig with a connection string instead. | | stripeSecretKey | string | Stripe secret key | | stripeWebhookSecret | string | Stripe webhook signing secret | | stripeApiVersion | string | Stripe API version (default: 2020-08-27) | | autoExpandLists | boolean | Fetch all list items from Stripe (not just the default 10) | | backfillRelatedEntities | boolean | Ensure related entities are present for foreign key integrity | | revalidateObjectsViaStripeApi | Array | Always fetch latest entity from Stripe instead of trusting webhook payload, possible values: 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 | | poolConfig | object | Configuration for PostgreSQL connection pooling. Supports options like connectionString, max, and keepAlive. For more details, refer to the Node-Postgres Pool API documentation. | | maxPostgresConnections | number | Deprecated: Use poolConfig.max instead to configure the maximum number of PostgreSQL connections. | | logger | Logger | Logger instance (pino) |

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.).

Important: The library uses a fixed schema name of stripe. This cannot be configured as the SQL migrations hardcode this schema name.

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.