stripe-experiment-sync 0.0.5 → 1.0.1

package/README.md

@@ -7,11 +7,8 @@ A TypeScript library to synchronize Stripe data into a PostgreSQL database, desi
 
 ## Features
 
-- Automatically manages Stripe webhooks for real-time updates
+- Programmatic management of Stripe webhooks for real-time updates
 - Sync Stripe objects (customers, invoices, products, etc.) to your PostgreSQL database
-- Automatic database migrations
-- Express middleware integration with automatic body parsing
-- UUID-based webhook routing for security
 
 ## Installation
 
@@ -23,45 +20,25 @@ pnpm add stripe-experiment-sync stripe
 yarn add stripe-experiment-sync stripe
 ```
 
-## StripeAutoSync
+## Usage
 
-The easiest way to integrate Stripe sync into your Express application:
+```ts
+import { StripeSync } from 'stripe-experiment-sync'
 
-```typescript
-import { StripeAutoSync } from 'stripe-experiment-sync'
-
-// baseUrl is a function for dynamic URL generation
-// (e.g., for ngrok tunnels, Replit domains, or environment-based URLs)
-const getPublicUrl = () => {
-  if (process.env.PUBLIC_URL) {
-    return process.env.PUBLIC_URL
-  }
-  // Or dynamically determine from request, ngrok, etc.
-  return `https://${process.env.REPLIT_DOMAINS?.split(',')[0]}`
-}
-
-const stripeAutoSync = new StripeAutoSync({
-  databaseUrl: process.env.DATABASE_URL,
-  stripeApiKey: process.env.STRIPE_SECRET_KEY,
-  baseUrl: getPublicUrl,
+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>
 })
 
-await stripeAutoSync.start(app) // Express app
-// ... later
-await stripeAutoSync.stop() // Cleanup
+// Example: process a Stripe webhook
+await sync.processWebhook(payload, signature)
 ```
 
-### Configuration Options
-
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `databaseUrl` | Yes | - | PostgreSQL connection string |
-| `stripeApiKey` | Yes | - | Stripe secret key (sk_...) |
-| `baseUrl` | Yes | - | Function returning your public URL |
-| `webhookPath` | No | `/stripe-webhooks` | Path where webhook handler is mounted |
-| `schema` | No | `stripe` | Database schema name |
-| `stripeApiVersion` | No | `2020-08-27` | Stripe API version |
-
 ## Low-Level API (Advanced)
 
 For more control, you can use the `StripeSync` class directly:
@@ -83,12 +60,50 @@ const sync = new StripeSync({
 await sync.processWebhook(payload, signature)
 ```
 
+### Processing Webhooks
+
+The `processWebhook` method validates and processes Stripe webhook events:
+
+```typescript
+// 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:
+
+```typescript
+// 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.                                                                                                                                                                                                                                       |
-| `schema`                        | string  | Database schema name (default: `stripe`)                                                                                                                                                                                                                                                                 |
 | `stripeSecretKey`               | string  | Stripe secret key                                                                                                                                                                                                                                                                                        |
 | `stripeWebhookSecret`           | string  | Stripe webhook signing secret                                                                                                                                                                                                                                                                            |
 | `stripeApiVersion`              | string  | Stripe API version (default: `2020-08-27`)                                                                                                                                                                                                                                                               |
@@ -103,16 +118,70 @@ await sync.processWebhook(payload, signature)
 
 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`, `_sync_run`, and `_sync_obj_run`.
+
 ### Migrations
 
 Migrations are included in the `db/migrations` directory. You can run them using the provided `runMigrations` function:
 
 ```ts
-import { runMigrations } from '@supabase/stripe-sync-engine'
+import { runMigrations } from 'stripe-experiment-sync'
 
 await runMigrations({ databaseUrl: 'postgres://...' })
 ```
 
+## Account Management
+
+### Getting Current Account
+
+Retrieve the currently authenticated Stripe account:
+
+```ts
+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:
+
+```ts
+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!
+
+```ts
+// 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
@@ -125,12 +194,12 @@ 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
+### Syncing Data
 
-To backfill Stripe data (e.g., all products created after a certain date), use the `syncBackfill` method:
+To sync Stripe data (e.g., all products created after a certain date), use the `processUntilDone` method:
 
 ```ts
-await sync.syncBackfill({
+await sync.processUntilDone({
   object: 'product',
   created: { gte: 1643872333 }, // Unix timestamp
 })
@@ -139,5 +208,7 @@ await sync.syncBackfill({
 - `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_run` and `_sync_obj_run` tables. 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.