From 493f64fe851abe0f7d5b06f3dc5a04afae7cf646 Mon Sep 17 00:00:00 2001 From: Mateusz Janota Date: Tue, 23 Sep 2025 10:15:06 +0200 Subject: [PATCH 1/6] docs: update typescript.md to deprecate databaseUrl and introduce poolConfig with SSL configuration examples --- docs/typescript.md | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/docs/typescript.md b/docs/typescript.md index 0f3f06da..6617bb7e 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -38,7 +38,7 @@ await sync.processWebhook(payload, signature) | Option | Type | Description | | ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `databaseUrl` | string | Postgres connection string | +| `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 | @@ -46,9 +46,45 @@ await sync.processWebhook(payload, signature) | `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 | -| `maxPostgresConnections` | number | Maximum Postgres connections | +| `poolConfig` | object | Configuration for the PostgreSQL connection pool. Supports options like `connectionString`, `max`, and `keepAlive`. | | `logger` | Logger | Logger instance (pino) | +### Example `poolConfig` + +```typescript +const config = { + poolConfig: { + connectionString: 'postgresql://user:password@localhost:5432/mydb', + max: 20, // Maximum number of connections + keepAlive: true, // Keep connections alive + }, +}; +``` + +For more details, refer to the [Node-Postgres Pool API documentation](https://node-postgres.com/apis/pool). + +### SSL CA Certificate in Base64 Format + +To pass an SSL CA certificate in base64 format, follow these steps: + +1. Encode your SSL CA certificate in base64 format: + - Download the certificate file from Supabase Dashboard (e.g., `prod-ca-2021.crt`). + - Encode it using a command like `base64 -i prod-ca-2021.crt -o CA.base64` on Unix-based systems. + - Read the contents of `CA.base64` and copy the base64 string to your ENV variables value. +2. Add the base64 string to your configuration: + +```typescript +const config = { + poolConfig: { + ssl: { + ca: Buffer.from('').toString('utf-8'), + }, + }, +}; +``` + +> **Note:** Replace `` with your actual base64-encoded certificate (development only) or the environment variable containing it (recommended for production). + ## Database Schema The library will create and manage a `stripe` schema in your Postgres database, with tables for all supported Stripe objects (products, customers, invoices, etc.). From 845ad442378315fa9d4d15cfb06277cd3c8584bc Mon Sep 17 00:00:00 2001 From: Mateusz Janota Date: Tue, 23 Sep 2025 10:45:24 +0200 Subject: [PATCH 2/6] feat: add SSL configuration options for Docker and TypeScript documentation --- docs/docker.md | 54 +++++++++++++++++++++++++++++++++++++++++++ docs/edge-function.md | 29 +++++++++++++++++++++-- docs/typescript.md | 28 ++++++++++++++-------- 3 files changed, 99 insertions(+), 12 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index b47f2450..a6650592 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -52,6 +52,11 @@ Set your webhook endpoint in the Stripe dashboard to point to your server’s `/ | `MAX_POSTGRES_CONNECTIONS` | Max Postgres connection pool size (default: 10) | No | | `REVALIDATE_OBJECTS_VIA_STRIPE_API` | Always fetch latest entity from Stripe (default: false) | No | | `DISABLE_MIGRATIONS` | Disable the automated database migrations on app startup (default: false) | No | +| `PG_SSL_CONFIG_ENABLED` | Enables SSL configuration. Set to `true` to enable. | No | +| `PG_SSL_REJECT_UNAUTHORIZED` | Rejects unauthorized SSL connections. Set to `true` to enforce. | No | +| `PG_SSL_CA` | Base64-encoded CA certificate for SSL connections. | No | +| `PG_SSL_CERT` | Certificate chain in PEM format for SSL connections. | No | +| `PG_SSL_REQUEST_CERT` | Requests a certificate from clients and attempts to verify it. Set to `true` to enable. | No | ## Endpoints @@ -136,3 +141,52 @@ POST /sync/single/cus_12345 ``` The entity type is recognized automatically, based on the prefix. + +#### SSL CA Certificate in Base64 Format + +To pass an SSL CA certificate in base64 format for the Dockerized application, follow these steps: + +1. Obtain the CA certificate file (e.g., `prod-ca-2021.crt`). +2. Encode it in base64 format using the following command on Unix-based systems: + + ```sh + base64 -i prod-ca-2021.crt -o CA.base64 + ``` + +3. Open the `CA.base64` file and copy its contents. +4. Add the base64 string to your environment variables (e.g., `PG_SSL_CA`). +5. Pass the environment variable to the Docker container: + + ```sh + docker run -d \ + -e DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres \ + -e PG_SSL_CA="$(cat CA.base64)" \ + -e STRIPE_SECRET_KEY=sk_test_... \ + -e STRIPE_WEBHOOK_SECRET=... \ + -e API_KEY="my-secret" \ + -p 8080:8080 \ + supabase/stripe-sync-engine:latest + ``` + +> **Note:** The `PG_SSL_CA` environment variable should contain the base64-encoded CA certificate. The application will decode and use it automatically during runtime. + +### Example Usage + +To pass these variables to the Docker container, use the following command: + +```sh +docker run -d \ + -e DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres \ + -e PG_SSL_CONFIG_ENABLED=true \ + -e PG_SSL_REJECT_UNAUTHORIZED=true \ + -e PG_SSL_CA="$(cat CA.base64)" \ + -e PG_SSL_CERT="$(cat cert.pem)" \ + -e PG_SSL_REQUEST_CERT=true \ + -e STRIPE_SECRET_KEY=sk_test_... \ + -e STRIPE_WEBHOOK_SECRET=... \ + -e API_KEY="my-secret" \ + -p 8080:8080 \ + supabase/stripe-sync-engine:latest +``` + +> **Note:** Ensure the `PG_SSL_CA` and `PG_SSL_CERT` variables contain valid base64-encoded or PEM-formatted certificates as required. diff --git a/docs/edge-function.md b/docs/edge-function.md index 5bb91fba..17a8d95a 100644 --- a/docs/edge-function.md +++ b/docs/edge-function.md @@ -27,13 +27,20 @@ import 'jsr:@supabase/functions-js/edge-runtime.d.ts' import { StripeSync } from 'npm:@supabase/stripe-sync-engine@0.37.2' // Load secrets from environment variables -const databaseUrl = Deno.env.get('DATABASE_URL')! const stripeWebhookSecret = Deno.env.get('STRIPE_WEBHOOK_SECRET')! const stripeSecretKey = Deno.env.get('STRIPE_SECRET_KEY')! // Initialize StripeSync const stripeSync = new StripeSync({ - databaseUrl, + poolConfig: { + connectionString: Deno.env.get('DATABASE_URL')!, + max: 20, + keepAlive: true, + // optional SSL configuration + ssl: { + ca: Buffer.from(Deno.env.get('DATABASE_SSL_CA')!).toString('utf-8'), + }, + }, stripeWebhookSecret, stripeSecretKey, backfillRelatedEntities: false, @@ -64,6 +71,7 @@ Create a new .env file in the `supabase` directory. ```.env DATABASE_URL="postgresql://postgres:..@db..supabase.co:5432/postgres" +DATABASE_SSL_CA="" STRIPE_WEBHOOK_SECRET="whsec_" STRIPE_SECRET_KEY="sk_test_..." ``` @@ -73,3 +81,20 @@ Load the secrets: `sh supabase secrets set --env-file ./supabase/.env `. + +> **Note:** +> Replace `` with your actual base64-encoded certificate. + +### Generating Base64 from CA Certificate + +To generate a base64-encoded CA certificate, follow these steps: + +1. Obtain the CA certificate file (e.g., `prod-ca-2021.crt`). +2. Use the following command on Unix-based systems: + + ```sh + base64 -i prod-ca-2021.crt -o CA.base64 + ``` + +3. Open the `CA.base64` file and copy its contents. +4. Use the base64 string in your configuration or environment variables. diff --git a/docs/typescript.md b/docs/typescript.md index 6617bb7e..7edc3c86 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -65,25 +65,33 @@ For more details, refer to the [Node-Postgres Pool API documentation](https://no ### SSL CA Certificate in Base64 Format -To pass an SSL CA certificate in base64 format, follow these steps: - -1. Encode your SSL CA certificate in base64 format: - - Download the certificate file from Supabase Dashboard (e.g., `prod-ca-2021.crt`). - - Encode it using a command like `base64 -i prod-ca-2021.crt -o CA.base64` on Unix-based systems. - - Read the contents of `CA.base64` and copy the base64 string to your ENV variables value. -2. Add the base64 string to your configuration: - ```typescript const config = { poolConfig: { + // optional SSL configuration ssl: { - ca: Buffer.from('').toString('utf-8'), + ca: Buffer.from(process.env.SSL_CA_CERT).toString('utf-8'), }, }, }; ``` -> **Note:** Replace `` with your actual base64-encoded certificate (development only) or the environment variable containing it (recommended for production). +> **Note:** +> Replace `` with your actual base64-encoded certificate (development only) or the environment variable containing it (recommended for production). + +### Generating Base64 from CA Certificate + +To generate a base64-encoded CA certificate, follow these steps: + +1. Obtain the CA certificate file (e.g., `prod-ca-2021.crt`). +2. Use the following command on Unix-based systems: + + ```sh + base64 -i prod-ca-2021.crt -o CA.base64 + ``` + +3. Open the `CA.base64` file and copy its contents. +4. Use the base64 string in your configuration or environment variables. ## Database Schema From 4cd05a57f69fbe92a5322bf715e7afa4a8783840 Mon Sep 17 00:00:00 2001 From: Mateusz Janota Date: Tue, 23 Sep 2025 10:56:54 +0200 Subject: [PATCH 3/6] docs: deprecate databaseUrl in favor of poolConfig for PostgreSQL connection --- docs/typescript.md | 1 + packages/sync-engine/README.md | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/typescript.md b/docs/typescript.md index 7edc3c86..5550a894 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -47,6 +47,7 @@ await sync.processWebhook(payload, signature) | `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 the PostgreSQL connection pool. Supports options like `connectionString`, `max`, and `keepAlive`. | +| `maxPostgresConnections` | number | **Deprecated**: Use `poolConfig.max` instead to configure the maximum number of Postgres connections. | | `logger` | Logger | Logger instance (pino) | ### Example `poolConfig` diff --git a/packages/sync-engine/README.md b/packages/sync-engine/README.md index 8f3a092b..f58951ee 100644 --- a/packages/sync-engine/README.md +++ b/packages/sync-engine/README.md @@ -41,7 +41,7 @@ await sync.processWebhook(payload, signature) | Option | Type | Description | | ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `databaseUrl` | string | Postgres connection string | +| `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 | @@ -49,7 +49,8 @@ await sync.processWebhook(payload, signature) | `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 | -| `maxPostgresConnections` | number | Maximum Postgres connections | +| `poolConfig` | object | Configuration for Postgres connection pooling. Supports options like `connectionString`, `max`, and `keepAlive`. For more details, refer to the [Node-Postgres Pool API documentation](https://node-postgres.com/apis/pool). | +| `maxPostgresConnections` | number | **Deprecated:** Use `poolConfig.max` instead to configure the maximum number of Postgres connections. | | `logger` | Logger | Logger instance (pino) | ## Database Schema From 701cf1b999147e66f89bf327213df0a419e0f950 Mon Sep 17 00:00:00 2001 From: Mateusz Janota Date: Tue, 23 Sep 2025 10:58:37 +0200 Subject: [PATCH 4/6] feat: update README to replace databaseUrl with poolConfig for connection settings --- packages/sync-engine/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/sync-engine/README.md b/packages/sync-engine/README.md index f58951ee..ca053fce 100644 --- a/packages/sync-engine/README.md +++ b/packages/sync-engine/README.md @@ -27,7 +27,10 @@ yarn add @supabase/stripe-sync-engine stripe import { StripeSync } from '@supabase/stripe-sync-engine' const sync = new StripeSync({ - databaseUrl: 'postgres://user:pass@host:port/db', + poolConfig: { + connectionString: 'postgres://user:pass@host:port/db', + max: 10, // Maximum number of connections + }, stripeSecretKey: 'sk_test_...', stripeWebhookSecret: 'whsec_...', // logger: From 5fae409ecbcfc3567e04633338566ba3cec869db Mon Sep 17 00:00:00 2001 From: Mateusz Janota Date: Tue, 23 Sep 2025 10:59:40 +0200 Subject: [PATCH 5/6] feat: update TypeScript example to use poolConfig instead of databaseUrl for connection settings --- docs/typescript.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/typescript.md b/docs/typescript.md index 5550a894..ba42c945 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -24,7 +24,10 @@ yarn add @supabase/stripe-sync-engine stripe import { StripeSync } from '@supabase/stripe-sync-engine' const sync = new StripeSync({ - databaseUrl: 'postgres://user:pass@host:port/db', + poolConfig: { + connectionString: 'postgres://user:pass@host:port/db', + max: 10, // Maximum number of connections + }, stripeSecretKey: 'sk_test_...', stripeWebhookSecret: 'whsec_...', // logger: From 69dd39ad8efa0a7e736f2659daaa7d7c2e7bcc9b Mon Sep 17 00:00:00 2001 From: Mateusz Janota Date: Tue, 23 Sep 2025 11:11:40 +0200 Subject: [PATCH 6/6] docs: update documentation to consistently use PostgreSQL terminology and improve clarity --- README.md | 16 +++++----- docs/contributing.md | 10 +++--- docs/docker.md | 56 ++++++++++++++++----------------- docs/edge-function.md | 10 +++--- docs/index.md | 8 ++--- docs/typescript.md | 34 ++++++++++---------- packages/fastify-app/README.md | 57 +++++++++++++++++----------------- packages/sync-engine/README.md | 32 +++++++++---------- 8 files changed, 111 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index f7b5c0e5..b5df6202 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,12 @@ ![NPM Version](https://img.shields.io/npm/v/%40supabase%2Fstripe-sync-engine) ![Docker Image Version](https://img.shields.io/docker/v/supabase/stripe-sync-engine?label=Docker) -This monorepo contains two packages for synchronizing your Stripe account with a Postgres database: +This monorepo contains two packages for synchronizing your Stripe account with a PostgreSQL database: -- [`@supabase/stripe-sync-engine`](./packages/sync-engine/README.md): A TypeScript library for syncing Stripe data to Postgres, designed for integration into your own Node.js backend or serverless environment. -- [`stripe-sync-fastify`](./packages/fastify-app/README.md): A Fastify-based server and Docker image that exposes a `/webhooks` endpoint for Stripe, providing a ready-to-run service for real-time Stripe-to-Postgres sync. +- [`@supabase/stripe-sync-engine`](./packages/sync-engine/README.md): A TypeScript library for syncing Stripe data to PostgreSQL, designed for integration into your own Node.js backend or serverless environment. +- [`stripe-sync-fastify`](./packages/fastify-app/README.md): A Fastify-based server and Docker image that exposes a `/webhooks` endpoint for Stripe, providing a ready-to-run service for real-time Stripe-to-PostgreSQL sync. -![Sync Stripe with Postgres](./docs/stripe-sync-engine.jpg) +![Sync Stripe with PostgreSQL](./docs/stripe-sync-engine.jpg) --- @@ -17,7 +17,7 @@ This monorepo contains two packages for synchronizing your Stripe account with a Sometimes you want to analyze your billing data using SQL. Even more importantly, you want to join your billing data to your product/business data. -This project synchronizes your Stripe account to a Postgres database. It can be a new database, or an existing Postgres database. +This project synchronizes your Stripe account to a PostgreSQL database. It can be a new database, or an existing PostgreSQL database. --- @@ -25,9 +25,9 @@ This project synchronizes your Stripe account to a Postgres database. It can be ![How it works](./docs/sync-engine-how.png) -- Creates a new schema `stripe` in a Postgres database, with tables & columns matching Stripe. +- Creates a new schema `stripe` in a PostgreSQL database, with tables and columns matching Stripe. - Exposes a `/webhooks` endpoint that listens to any Stripe webhooks (via the Fastify app). -- Inserts/updates/deletes changes into the tables whenever there is a change to Stripe. +- Inserts, updates, or deletes changes into the tables whenever there is a change to Stripe. --- @@ -42,7 +42,7 @@ Each package has its own README with installation, configuration, and usage inst ## Supabase Edge Function -To deploy the sync-engine to a Supabase edge function, follow this [guide](./edge-function.md). +To deploy the sync-engine to a Supabase Edge Function, follow this [guide](./docs/edge-function.md). ## Webhook Support diff --git a/docs/contributing.md b/docs/contributing.md index 54351b7b..c7f075b3 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,6 +1,6 @@ # Contributing -Contributions are welcome. +Contributions are welcome! This document provides guidelines for contributing to the Stripe Sync Engine project. ## Contributing to the Docs @@ -10,7 +10,7 @@ Building documentation requires Python 3.8+ and uv. Create a virtual environment and install mkdocs, themes, and extensions using uv. -```shell +```sh source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -r docs/requirements_docs.txt ``` @@ -19,7 +19,7 @@ uv pip install -r docs/requirements_docs.txt To serve the documentation locally, make sure your virtual environment is activated and run: -```shell +```sh source .venv/bin/activate # On Windows: .venv\Scripts\activate mkdocs serve ``` @@ -28,8 +28,8 @@ and visit the docs at [http://127.0.0.1:8000/](http://127.0.0.1:8000/) ### Deploying -If you have write access to the repo, docs can be updated using +If you have write access to the repository, documentation can be updated using: -``` +```sh mkdocs gh-deploy ``` diff --git a/docs/docker.md b/docs/docker.md index a6650592..4537250e 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -3,11 +3,11 @@ ![GitHub License](https://img.shields.io/github/license/supabase/stripe-sync-engine) ![Docker Image Version](https://img.shields.io/docker/v/supabase/stripe-sync-engine?label=Docker) -A Fastify-based server for syncing your Stripe account to a Postgres database in real time. Built on top of the Stripe Sync Engine. +A Fastify-based server for syncing your Stripe account to a PostgreSQL database in real time. Built on top of the Stripe Sync Engine. ## Features -- Exposes a `/webhooks` endpoint to receive Stripe webhooks and sync data to Postgres +- Exposes a `/webhooks` endpoint to receive Stripe webhooks and sync data to PostgreSQL - Supports syncing customers, invoices, products, subscriptions, and more - Runs as a lightweight Docker container - Designed for easy deployment to any cloud or self-hosted environment @@ -38,31 +38,31 @@ Set your webhook endpoint in the Stripe dashboard to point to your server’s `/ ## Environment Variables -| Variable | Description | Required | -| ---------------------------------- | ------------------------------------------------------------------- | -------- | -| `DATABASE_URL` | Postgres connection string (with `search_path=stripe`) | Yes | -| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret | Yes | -| `API_KEY` | API key for admin endpoints (backfilling, etc.) | Yes | -| `SCHEMA` | Database schema name (default: `stripe`) | No | -| `STRIPE_SECRET_KEY` | Stripe secret key (needed for active sync/backfill) | No | -| `PORT` | Port to run the server on (default: 8080) | No | -| `STRIPE_API_VERSION` | Stripe API version (default: `2020-08-27`) | No | -| `AUTO_EXPAND_LISTS` | Fetch all list items from Stripe (default: false) | No | -| `BACKFILL_RELATED_ENTITIES` | Backfill related entities for foreign key integrity (default: true) | No | -| `MAX_POSTGRES_CONNECTIONS` | Max Postgres connection pool size (default: 10) | No | -| `REVALIDATE_OBJECTS_VIA_STRIPE_API` | Always fetch latest entity from Stripe (default: false) | No | -| `DISABLE_MIGRATIONS` | Disable the automated database migrations on app startup (default: false) | No | -| `PG_SSL_CONFIG_ENABLED` | Enables SSL configuration. Set to `true` to enable. | No | -| `PG_SSL_REJECT_UNAUTHORIZED` | Rejects unauthorized SSL connections. Set to `true` to enforce. | No | -| `PG_SSL_CA` | Base64-encoded CA certificate for SSL connections. | No | -| `PG_SSL_CERT` | Certificate chain in PEM format for SSL connections. | No | -| `PG_SSL_REQUEST_CERT` | Requests a certificate from clients and attempts to verify it. Set to `true` to enable. | No | +| Variable | Description | Required | +| -------- | ----------- | -------- | +| `DATABASE_URL` | PostgreSQL connection string (with `search_path=stripe`) | Yes | +| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret | Yes | +| `API_KEY` | API key for admin endpoints (backfilling, etc.) | Yes | +| `SCHEMA` | Database schema name (default: `stripe`) | No | +| `STRIPE_SECRET_KEY` | Stripe secret key (needed for active sync/backfill) | No | +| `PORT` | Port to run the server on (default: 8080) | No | +| `STRIPE_API_VERSION` | Stripe API version (default: `2020-08-27`) | No | +| `AUTO_EXPAND_LISTS` | Fetch all list items from Stripe (default: false) | No | +| `BACKFILL_RELATED_ENTITIES` | Backfill related entities for foreign key integrity (default: true) | No | +| `MAX_POSTGRES_CONNECTIONS` | Max PostgreSQL connection pool size (default: 10) | No | +| `REVALIDATE_OBJECTS_VIA_STRIPE_API` | Always fetch latest entity from Stripe (default: false) | No | +| `DISABLE_MIGRATIONS` | Disable the automated database migrations on app startup (default: false) | No | +| `PG_SSL_CONFIG_ENABLED` | Enables SSL configuration. Set to `true` to enable | No | +| `PG_SSL_REJECT_UNAUTHORIZED` | Rejects unauthorized SSL connections. Set to `true` to enforce | No | +| `PG_SSL_CA` | Base64-encoded CA certificate for SSL connections | No | +| `PG_SSL_CERT` | Certificate chain in PEM format for SSL connections | No | +| `PG_SSL_REQUEST_CERT` | Requests a certificate from clients and attempts to verify it. Set to `true` to enable | No | ## Endpoints -- `POST /webhooks` — Receives Stripe webhook events and syncs data to Postgres +- `POST /webhooks` — Receives Stripe webhook events and syncs data to PostgreSQL - `GET /health` — Health check endpoint -- `POST /sync` — Backfill Stripe data to Postgres (API key required) +- `POST /sync` — Backfill Stripe data to PostgreSQL (API key required) - `POST /sync/single/:stripeId` — Backfill or update a single Stripe entity by ID (API key required) - `POST /daily` — Backfill data from the last 24 hours (API key required) - `POST /weekly` — Backfill data from the last 7 days (API key required) @@ -119,13 +119,13 @@ body: { - `object` **all** | **charge** | **customer** | **dispute** | **invoice** | **payment_method** | **payment_intent** | **plan** | **price** | **product** | **setup_intent** | **subscription** | **early_fraud_warning** | **refund** | **credit_note** | **tax_id** | **subscription_schedules** - `created` is Stripe.RangeQueryParam. It supports **gt**, **gte**, **lt**, **lte** -#### Alternative routes to sync `daily/weekly/monthly` data +### Alternative routes to sync `daily/weekly/monthly` data ``` POST /sync/daily +``` ---- - +``` POST /sync/daily body: { "object": "product" @@ -134,7 +134,7 @@ body: { ### Syncing single entity -To backfill/update a single entity, you can use +To backfill/update a single entity, you can use: ``` POST /sync/single/cus_12345 @@ -142,7 +142,7 @@ POST /sync/single/cus_12345 The entity type is recognized automatically, based on the prefix. -#### SSL CA Certificate in Base64 Format +### SSL CA Certificate in Base64 Format To pass an SSL CA certificate in base64 format for the Dockerized application, follow these steps: diff --git a/docs/edge-function.md b/docs/edge-function.md index 17a8d95a..a60c4914 100644 --- a/docs/edge-function.md +++ b/docs/edge-function.md @@ -1,10 +1,10 @@ # With Supabase Edge Functions -Create a new [Supabase](https://supabase.com) and create a new [Edge Function](https://supabase.com/docs/guides/functions/quickstart). +Create a new [Supabase](https://supabase.com) project and create a new [Edge Function](https://supabase.com/docs/guides/functions/quickstart). ## Prepare your database -Make sure to run the [migrations](./packages/sync-engine/src/database/migrations/), either by executing them manually, adding them into your CI or running this locally once: +Make sure to run the [migrations](../packages/sync-engine/src/database/migrations/), either by executing them manually, adding them into your CI, or running this locally once: ```ts import { runMigrations } from '@supabase/stripe-sync-engine' @@ -65,7 +65,7 @@ Deno.serve(async (req) => { Deploy your Edge Function initially. -Set up a Stripe webhook with the newly deployed Supabase Edge Function url. +Set up a Stripe webhook with the newly deployed Supabase Edge Function URL. Create a new .env file in the `supabase` directory. @@ -78,9 +78,9 @@ STRIPE_SECRET_KEY="sk_test_..." Load the secrets: -`sh +```sh supabase secrets set --env-file ./supabase/.env -`. +``` > **Note:** > Replace `` with your actual base64-encoded certificate. diff --git a/docs/index.md b/docs/index.md index eaa7b61c..56464381 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,10 @@ -![Sync Stripe with Postgres](./stripe-sync-engine.jpg) +![Sync Stripe with PostgreSQL](./stripe-sync-engine.jpg) # Stripe Sync Engine Sometimes you want to analyze your billing data using SQL. Even more importantly, you want to join your billing data to your product/business data. -This project synchronizes your Stripe account to a Postgres database. It can be a new database, or an existing Postgres database. +This project synchronizes your Stripe account to a PostgreSQL database. It can be a new database, or an existing PostgreSQL database. --- @@ -12,9 +12,9 @@ This project synchronizes your Stripe account to a Postgres database. It can be ![How it works](./sync-engine-how.png) -- Creates a new schema `stripe` in a Postgres database, with tables & columns matching Stripe. +- Creates a new schema `stripe` in a PostgreSQL database, with tables and columns matching Stripe. - Exposes a `/webhooks` endpoint that listens to any Stripe webhooks (via the Fastify app). -- Inserts/updates/deletes changes into the tables whenever there is a change to Stripe. +- Inserts, updates, or deletes changes into the tables whenever there is a change to Stripe. ## Webhook Support diff --git a/docs/typescript.md b/docs/typescript.md index ba42c945..8ebd62de 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -1,10 +1,10 @@ -# With Typescript +# With TypeScript -A TypeScript library to synchronize Stripe data into a Postgres database, designed for use in Node.js backends and serverless environments. +A TypeScript library to synchronize Stripe data into a PostgreSQL database, designed for use in Node.js backends and serverless environments. ## Features -- Sync Stripe objects (customers, invoices, products, etc.) to your Postgres database. +- Sync Stripe objects (customers, invoices, products, etc.) to your PostgreSQL database. - Handles Stripe webhooks for real-time updates. - Supports backfilling and entity revalidation. @@ -39,19 +39,19 @@ await sync.processWebhook(payload, signature) ## 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`) | -| `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 the PostgreSQL connection pool. Supports options like `connectionString`, `max`, and `keepAlive`. | -| `maxPostgresConnections` | number | **Deprecated**: Use `poolConfig.max` instead to configure the maximum number of Postgres connections. | -| `logger` | Logger | Logger instance (pino) | +| 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`) | +| `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 the PostgreSQL connection pool. Supports options like `connectionString`, `max`, and `keepAlive`. | +| `maxPostgresConnections` | number | **Deprecated:** Use `poolConfig.max` instead to configure the maximum number of PostgreSQL connections. | +| `logger` | Logger | Logger instance (pino) | ### Example `poolConfig` @@ -99,7 +99,7 @@ To generate a base64-encoded CA certificate, follow these steps: ## Database Schema -The library will create and manage a `stripe` schema in your Postgres database, with tables for all supported Stripe objects (products, customers, invoices, etc.). +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 diff --git a/packages/fastify-app/README.md b/packages/fastify-app/README.md index 3e700874..18b9292b 100644 --- a/packages/fastify-app/README.md +++ b/packages/fastify-app/README.md @@ -1,13 +1,13 @@ -# Stripe Sync - Fastify App +# Stripe Sync Engine - Fastify App ![GitHub License](https://img.shields.io/github/license/supabase/stripe-sync-engine) ![Docker Image Version](https://img.shields.io/docker/v/supabase/stripe-sync-engine?label=Docker) -A Fastify-based server for syncing your Stripe account to a Postgres database in real time. Built on top of the Stripe Sync Engine. +A Fastify-based server for syncing your Stripe account to a PostgreSQL database in real time. Built on top of the Stripe Sync Engine. ## Features -- Exposes a `/webhooks` endpoint to receive Stripe webhooks and sync data to Postgres +- Exposes a `/webhooks` endpoint to receive Stripe webhooks and sync data to PostgreSQL - Supports syncing customers, invoices, products, subscriptions, and more - Runs as a lightweight Docker container - Designed for easy deployment to any cloud or self-hosted environment @@ -38,32 +38,31 @@ Set your webhook endpoint in the Stripe dashboard to point to your server’s `/ ## Environment Variables -| Variable | Description | Required | -| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| `DATABASE_URL` | Postgres connection string (with `search_path=stripe`) | Yes | -| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret | Yes | -| `API_KEY` | API key for admin endpoints (backfilling, etc.) | Yes | -| `SCHEMA` | Database schema name (default: `stripe`) | No | -| `STRIPE_SECRET_KEY` | Stripe secret key (needed for active sync/backfill) | No | -| `PORT` | Port to run the server on (default: 8080) | No | -| `STRIPE_API_VERSION` | Stripe API version (default: `2020-08-27`) | No | -| `AUTO_EXPAND_LISTS` | Fetch all list items from Stripe (default: false) | No | -| `BACKFILL_RELATED_ENTITIES` | Backfill related entities for foreign key integrity (default: true) | No | -| `MAX_POSTGRES_CONNECTIONS` | Max Postgres connection pool size (default: 10) | No | -| `REVALIDATE_OBJECTS_VIA_STRIPE_API` | 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 | No | -| `DISABLE_MIGRATIONS` | Disable the automated database migrations on app startup | -| `PG_SSL_CONFIG_ENABLED` | Whether to explicitly use the SSL configuration, (default: false) | No | -| `PG_SSL_REJECT_UNAUTHORIZED` | If true the server will reject any connection which is not authorized with the list of supplied CAs. This option only has an effect if requestCert is true. | No | -| `PG_SSL_REQUEST_CERT` | If true the server will request a certificate from clients that connect and attempt to verify that certificate. Defaults to false. | No | -| `PG_SSL_CA` | Optionally override the trusted CA certificates. | No | -| `PG_SSL_CERT` | Cert Chain in PEM format | No | -| No | +| Variable | Description | Required | +| -------- | ----------- | -------- | +| `DATABASE_URL` | PostgreSQL connection string (with `search_path=stripe`) | Yes | +| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret | Yes | +| `API_KEY` | API key for admin endpoints (backfilling, etc.) | Yes | +| `SCHEMA` | Database schema name (default: `stripe`) | No | +| `STRIPE_SECRET_KEY` | Stripe secret key (needed for active sync/backfill) | No | +| `PORT` | Port to run the server on (default: 8080) | No | +| `STRIPE_API_VERSION` | Stripe API version (default: `2020-08-27`) | No | +| `AUTO_EXPAND_LISTS` | Fetch all list items from Stripe (default: false) | No | +| `BACKFILL_RELATED_ENTITIES` | Backfill related entities for foreign key integrity (default: true) | No | +| `MAX_POSTGRES_CONNECTIONS` | Max PostgreSQL connection pool size (default: 10) | No | +| `REVALIDATE_OBJECTS_VIA_STRIPE_API` | 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 | No | +| `DISABLE_MIGRATIONS` | Disable the automated database migrations on app startup (default: false) | No | +| `PG_SSL_CONFIG_ENABLED` | Whether to explicitly use the SSL configuration (default: false) | No | +| `PG_SSL_REJECT_UNAUTHORIZED` | If true the server will reject any connection which is not authorized with the list of supplied CAs. This option only has an effect if requestCert is true | No | +| `PG_SSL_REQUEST_CERT` | If true the server will request a certificate from clients that connect and attempt to verify that certificate. Defaults to false | No | +| `PG_SSL_CA` | Optionally override the trusted CA certificates | No | +| `PG_SSL_CERT` | Certificate chain in PEM format | No | ## Endpoints -- `POST /webhooks` — Receives Stripe webhook events and syncs data to Postgres +- `POST /webhooks` — Receives Stripe webhook events and syncs data to PostgreSQL - `GET /health` — Health check endpoint -- `POST /sync` — Backfill Stripe data to Postgres (API key required) +- `POST /sync` — Backfill Stripe data to PostgreSQL (API key required) - `POST /sync/single/:stripeId` — Backfill or update a single Stripe entity by ID (API key required) - `POST /daily` — Backfill data from the last 24 hours (API key required) - `POST /weekly` — Backfill data from the last 7 days (API key required) @@ -120,13 +119,13 @@ body: { - `object` **all** | **charge** | **customer** | **dispute** | **invoice** | **payment_method** | **payment_intent** | **plan** | **price** | **product** | **setup_intent** | **subscription** | **early_fraud_warning** | **refund** | **credit_note** | **tax_id** | **subscription_schedules** - `created` is Stripe.RangeQueryParam. It supports **gt**, **gte**, **lt**, **lte** -#### Alternative routes to sync `daily/weekly/monthly` data +### Alternative routes to sync `daily/weekly/monthly` data ``` POST /sync/daily +``` ---- - +``` POST /sync/daily body: { "object": "product" @@ -135,7 +134,7 @@ body: { ### Syncing single entity -To backfill/update a single entity, you can use +To backfill/update a single entity, you can use: ``` POST /sync/single/cus_12345 diff --git a/packages/sync-engine/README.md b/packages/sync-engine/README.md index ca053fce..b11555f8 100644 --- a/packages/sync-engine/README.md +++ b/packages/sync-engine/README.md @@ -3,11 +3,11 @@ ![GitHub License](https://img.shields.io/github/license/supabase/stripe-sync-engine) ![NPM Version](https://img.shields.io/npm/v/%40supabase%2Fstripe-sync-engine) -A TypeScript library to synchronize Stripe data into a Postgres database, designed for use in Node.js backends and serverless environments. +A TypeScript library to synchronize Stripe data into a PostgreSQL database, designed for use in Node.js backends and serverless environments. ## Features -- Sync Stripe objects (customers, invoices, products, etc.) to your Postgres database. +- Sync Stripe objects (customers, invoices, products, etc.) to your PostgreSQL database. - Handles Stripe webhooks for real-time updates. - Supports backfilling and entity revalidation. @@ -42,23 +42,23 @@ await sync.processWebhook(payload, signature) ## 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`) | -| `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 Postgres connection pooling. Supports options like `connectionString`, `max`, and `keepAlive`. For more details, refer to the [Node-Postgres Pool API documentation](https://node-postgres.com/apis/pool). | -| `maxPostgresConnections` | number | **Deprecated:** Use `poolConfig.max` instead to configure the maximum number of Postgres connections. | -| `logger` | Logger | Logger instance (pino) | +| 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`) | +| `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](https://node-postgres.com/apis/pool). | +| `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 Postgres database, with tables for all supported Stripe objects (products, customers, invoices, etc.). +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