Registry / payments / stripe-sync-engine

stripe-sync-engine

library0.1.0jsnpmunverified

A TypeScript library for syncing Stripe objects (customers, invoices, products, etc.) to PostgreSQL in real-time via webhooks, with support for backfilling and entity revalidation. Version 0.1.0 is the initial release, offering a configurable sync engine that creates tables under a configurable schema (default: 'stripe') and handles webhook signature verification. It requires the 'stripe' npm package (peer dependency > 11) and pg (for database connections). Designed for Node.js and serverless environments, with first-class TypeScript support and optional pino logger integration.

payments database

npm install stripe-sync-engine

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STRIPE-SYNC-ENGINE

stripe-sync-engine

paymentsjavascriptv0.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

StripeSync

✓ import { StripeSync } from 'stripe-sync-engine'

✗ const StripeSync = require('stripe-sync-engine').default

ESM-only; do not use CommonJS require with .default. The package exports a named export.

processWebhook

✓ import { StripeSync } from 'stripe-sync-engine'

✗ import { processWebhook } from 'stripe-sync-engine'

processWebhook is a method on the StripeSync class, not a standalone export.

StripeSync (type)

✓ import type { StripeSync } from 'stripe-sync-engine'

✗ import { StripeSync } from 'stripe-sync-engine' // if only used as type

TypeScript users should use 'import type' for type-only imports to avoid runtime overhead.

Shows how to initialize StripeSync with PostgreSQL connection and Stripe keys, then process a webhook event.

import { StripeSync } from 'stripe-sync-engine' import { config } from 'dotenv' // optional for env vars config() const sync = new StripeSync({ poolConfig: { connectionString: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost:5432/mydb', max: 10, }, schema: 'stripe', tablePrefix: 'sync_', stripeSecretKey: process.env.STRIPE_SECRET_KEY ?? '', stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET ?? '', stripeApiVersion: '2020-08-27', }) // Example: process a webhook payload const payload = JSON.stringify({ id: 'evt_123', type: 'customer.created', data: { object: { id: 'cus_123', email: 'test@example.com' } } }) const signature = 't=...' // from Stripe webhook header await sync.processWebhook(payload, signature)

Debug

Known issues

deprecatedThe `databaseUrl` option is deprecated. Use `poolConfig` with a `connectionString` instead.

fix

Replace `databaseUrl` with `poolConfig: { connectionString: '...' }`

affects: >=0.1.0

gotchaWhen setting `tablePrefix`, an underscore is automatically appended if the prefix does not end with one. Example: 'billing' becomes 'billing_' prefix, resulting in table names like 'billing_products'.

fix

Ensure your prefix logic accounts for the auto-appended underscore or include it explicitly.

affects: >=0.1.0

breakingThe `stripe` peer dependency must be version >11. Older versions of the Stripe SDK are incompatible.

fix

Update stripe to >=12 (recommended) by running `npm install stripe@latest`.

affects: >=0.1.0

gotchaThe library uses a default schema named 'stripe'. If you already have a schema named 'stripe' or want a different one, set the `schema` option explicitly.

fix

Pass `schema: 'your_schema_name'` during StripeSync construction.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'stripe-sync-engine' or its corresponding type declarations.

Package not installed or missing `stripe` peer dependency.

fix

Run `npm install stripe-sync-engine stripe` to install both.

Error: Missing stripeSecretKey. Please provide a valid Stripe secret key.

Stripe secret key is not provided or is empty in configuration.

fix

Set `stripeSecretKey` in the options object to a valid Stripe secret key (e.g., from environment variable).

error: The `databaseUrl` option is deprecated. Use `poolConfig` with a connection string instead.

Using the deprecated `databaseUrl` configuration option.

fix

Replace `databaseUrl` with `poolConfig: { connectionString: 'your_connection_string' }`.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

striperequiredRequired to interact with the Stripe API and verify webhook signatures.

pgrequiredPostgreSQL client for database operations.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ashutoshpw/stripe-sync-engine ↗

packagestripe-sync-engine ↗

homepagehttps://github.com/ashutoshpw/stripe-sync-engine#readme ↗