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

• Automatically manages Stripe webhooks for real-time updates
• Sync Stripe objects (customers, invoices, products, etc.) to your PostgreSQL database
• UUID-based webhook routing for managed webhooks

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

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.

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.