fix: release (#148)

Author: kevcodez

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: release
+name: Release
 
 on:
   #push:
@@ -86,6 +86,14 @@ jobs:
     runs-on: ubuntu-24.04
 
     steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            packages/sync-engine
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Set new version in sync-engine
         run: |
           cd packages/sync-engine
@@ -94,6 +102,9 @@ jobs:
       - name: Publish sync-engine to npm
         run: |
           cd packages/sync-engine
+          pnpm install --frozen-lockfile
+          pnpm run build
+          pnpm pack
           npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -4,3 +4,5 @@ node_modules/
 .env
 .env.*
 !.env.sample
+.idea
+*.tgz

README.md

@@ -1,29 +1,46 @@
-# Stripe Sync Engine
+# Stripe Sync Engine Monorepo
 
-Continuously synchronizes a Stripe account to a Postgres database.
+![GitHub License](https://img.shields.io/github/license/supabase/stripe-sync-engine)
+![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:
+
+- [`@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.
 
 ![Sync Stripe with Postgres](./docs/stripe-sync-engine.jpg)
 
+---
+
 ## Motivation
 
 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 server 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 Postgres database. It can be a new database, or an existing Postgres database.
+
+---
 
 ## How it works
 
 ![How it works](./docs/sync-engine-how.png)
 
 - Creates a new schema `stripe` in a Postgres database, with tables & columns matching Stripe.
-- Exposes a `/webhooks` endpoint that listens to any Stripe webhooks.
+- 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.
 
-**Not implemented**
+---
+
+## Packages
+
+- [Library: @supabase/stripe-sync-engine](./packages/sync-engine/README.md)
+- [Docker/Server: supabase/stripe-sync-engine](./packages/fastify-app/README.md)
 
-- This will not do an initial load of existing Stripe data. You should use CSV loads for this. We might implement this in the future.
-- We are progressively working through webhooks.
+Each package has its own README with installation, configuration, and usage instructions.
+
+---
 
-## Webhook Progress
+## Webhook Support
 
 - [ ] `balance.available`
 - [x] `charge.captured` 🟢
@@ -120,89 +137,3 @@ This server synchronizes your Stripe account to a Postgres database. It can be a
 - [x] `subscription_schedule.expiring` 🟢
 - [x] `subscription_schedule.released` 🟢
 - [x] `subscription_schedule.updated` 🟢
-
-## Usage
-
-- Update your Stripe account with all valid webhooks and get the webhook secret
-- `mv .env.sample .env` and then rename all the variables
-- Make sure the database URL has search_path `stripe`. eg: `DATABASE_URL=postgres://postgres:postgres@hostname:5432/postgres?sslmode=disable&search_path=stripe`
-- Deploy the [docker image](https://hub.docker.com/r/supabase/stripe-sync-engine) to your favourite hosting service and expose port `8080`
-  - eg: `docker run -e PORT=8080 --env-file .env supabase/stripe-sync-engine`
-  - This will automatically run any migrations on your database
-- Point your Stripe webooks to your deployed app.
-
-## Backfill from Stripe
-
-```
-POST /sync
-body: {
-  "object": "product",
-  "created": {
-    "gte": 1643872333
-  }
-}
-```
-
-- `object` **all** | **charge** | **customer** | **dispute** | **invoice** | **payment_method** | **payment_intent** | **plan** | **price** | **product** | **setup_intent** | **subscription**
-- `created` is Stripe.RangeQueryParam. It supports **gt**, **gte**, **lt**, **lte**
-
-#### Alternative routes to sync `daily/weekly/monthly` data
-
-```
-POST /sync/daily
-
----
-
-POST /sync/daily
-body: {
-  "object": "product"
-}
-```
-
-### Syncing single entity
-
-To backfill/update a single entity, you can use
-
-```
-POST /sync/single/cus_12345
-```
-
-The entity type is recognized automatically, based on the prefix.
-
-## Future ideas
-
-- Expose an "initialize" endpoint that will fetch data from Stripe and do an initial load (or perhaps `POST` a CSV to an endpoint).
-
-## Development
-
-**Set up**
-
-- Create a Postgres database on [supabase.com](https://supabase.com) (or another Postgres provider)
-- Update Stripe with all valid webhooks and get the webhook secret
-- `mv .env.sample .env` and then rename all the variables
-
-**Develop**
-
-- `pnpm dev` to start the local server
-- `pnpm t` to run tests
-
-**Building Docker**
-
-```bash
-docker build -t stripe-sync-engine .
-docker run -p 8080:8080 stripe-sync-engine
-```
-
-**Release**
-
-Handled by GitHub actions whenever their is a commit to the `main` branch with `fix` or `feat` in the description.
-
-## License
-
-Apache 2.0
-
-## Sponsors
-
-Supabase is building the features of Firebase using enterprise-grade, open source products. We support existing communities wherever possible, and if the products don’t exist we build them and open source them ourselves.
-
-[![New Sponsor](https://user-images.githubusercontent.com/10214025/90518111-e74bbb00-e198-11ea-8f88-c9e3c1aa4b5b.png)](https://github.com/sponsors/supabase)

package.json

@@ -24,6 +24,7 @@
     "pino": "^9.7.0",
     "prettier": "^3.5.3",
     "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vite": "^6.3.5"
   },

packages/fastify-app/README.md

@@ -0,0 +1,137 @@
+# Stripe Sync - 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.
+
+## Features
+
+- Exposes a `/webhooks` endpoint to receive Stripe webhooks and sync data to Postgres
+- 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
+
+## Quick Start
+
+### 1. Pull the image
+
+```sh
+docker pull supabase/stripe-sync-engine:latest
+```
+
+### 2. Run the container
+
+```sh
+docker run -d \
+  -e DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres \
+  -e STRIPE_SECRET_KEY=sk_test_... \
+  -e STRIPE_WEBHOOK_SECRET=... \
+  -e API_KEY="my-secret" \
+  -p 8080:8080 \
+  supabase/stripe-sync-engine:latest
+```
+
+### 3. Configuration
+
+Set your webhook endpoint in the Stripe dashboard to point to your server’s `/webhooks` route (e.g., `https://yourdomain.com/webhooks`).
+
+## 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_ENTITY_VIA_STRIPE_API` | Always fetch latest entity from Stripe (default: false)             | No       |
+
+## Endpoints
+
+- `POST /webhooks` — Receives Stripe webhook events and syncs data to Postgres
+- `GET /health` — Health check endpoint
+- `POST /sync` — Backfill Stripe data to Postgres (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)
+- `POST /monthly` — Backfill data from the last 30 days (API key required)
+
+## Example Docker Compose
+
+```yaml
+version: '3'
+services:
+  postgres:
+    image: postgres:17
+    restart: always
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: postgres
+    ports:
+      - 5432:5432
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+  stripe-sync:
+    image: supabase/stripe-sync-fastify:latest
+    depends_on:
+      - postgres
+    ports:
+      - 8080:8080
+    environment:
+      DATABASE_URL: postgres://postgres:postgres@postgres:5432/postgres?sslmode=disable&search_path=stripe
+      STRIPE_SECRET_KEY: sk_test_...
+      STRIPE_WEBHOOK_SECRET: whsec_...
+      API_KEY: my-secret
+
+volumes:
+  pgdata:
+```
+
+## Backfill from Stripe
+
+> **Note:**
+> The `/sync` endpoints are **NOT** recommended for use if you have more than 10,000 objects in Stripe. For large backfills, it is best to write a script that loops through each day and sets the `created` date filters to the start and end of day.
+
+```
+POST /sync
+body: {
+  "object": "product",
+  "created": {
+    "gte": 1643872333
+  }
+}
+```
+
+- `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
+
+```
+POST /sync/daily
+
+---
+
+POST /sync/daily
+body: {
+  "object": "product"
+}
+```
+
+### Syncing single entity
+
+To backfill/update a single entity, you can use
+
+```
+POST /sync/single/cus_12345
+```
+
+The entity type is recognized automatically, based on the prefix.

packages/fastify-app/src/app.ts

@@ -2,7 +2,7 @@ import fastify, { FastifyInstance, FastifyServerOptions } from 'fastify'
 import autoload from '@fastify/autoload'
 import fastifySwagger from '@fastify/swagger'
 import fastifySwaggerUi from '@fastify/swagger-ui'
-import path from 'node:path'
+import { join } from 'node:path'
 import { getConfig } from './utils/config'
 import { StripeSync } from '@supabase/stripe-sync-engine'
 import { errorSchema } from './error'
@@ -55,9 +55,7 @@ export async function createServer(opts: buildOpts = {}): Promise<FastifyInstanc
       }
       done(null, newBody)
     } catch (error) {
-      // @ts-expect-error
       error.statusCode = 400
-      // @ts-expect-error
       done(error, undefined)
     }
   })
@@ -71,7 +69,7 @@ export async function createServer(opts: buildOpts = {}): Promise<FastifyInstanc
    * Expose all routes in './routes'
    */
   await app.register(autoload, {
-    dir: path.join(__dirname, 'routes'),
+    dir: join(__dirname, 'routes'),
   })
 
   await app.ready()

packages/fastify-app/src/utils/config.ts

@@ -1,4 +1,4 @@
-import dotenv from 'dotenv'
+import { config } from 'dotenv'
 
 function getConfigFromEnv(key: string, defaultValue?: string): string {
   const value = process.env[key]
@@ -47,7 +47,7 @@ export type StripeSyncServerConfig = {
 }
 
 export function getConfig(): StripeSyncServerConfig {
-  dotenv.config()
+  config()
 
   return {
     databaseUrl: getConfigFromEnv('DATABASE_URL'),

packages/fastify-app/tsconfig.json

@@ -1,16 +1,14 @@
 {
-  "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "rootDir": ".",
     "module": "commonjs",
     "outDir": "dist",
     "declaration": true,
     "declarationMap": true,
-    "composite": true,
     "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo",
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "skipLibCheck": true
   },
   "include": ["src"],
-  "exclude": ["src/test", "node_modules", "dist"],
-  "references": [{ "path": "../sync-engine" }]
+  "exclude": ["src/test", "node_modules", "dist"]
 }