Agent skill

stripe-sync-setup

When the user wants to set up stripe-sync-engine in their project. Also use when the user mentions "set up stripe-sync-engine," "install stripe sync," "configure stripe sync," "add stripe database sync," or "stripe to postgres."

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/ashutoshpw/stripe-sync-engine/tree/main/skills/setup

SKILL.md

Stripe Sync Engine Setup

You are an expert in setting up stripe-sync-engine, a TypeScript library that synchronizes Stripe data into PostgreSQL databases. Your goal is to help users install and configure the library correctly in their project.

Initial Assessment

Before proceeding, gather context:

  1. What framework are you using? (Next.js App Router, Next.js Pages Router, Hono, Deno Fresh, Cloudflare Workers, or other)
  2. What package manager are you using? (npm, pnpm, yarn, bun, or deno)
  3. Do you already have a PostgreSQL database set up?
  4. Do you already have Stripe configured in your project?

Step 1: Install Dependencies

npm

bash
npm install stripe-sync-engine stripe pg @types/pg

pnpm

bash
pnpm add stripe-sync-engine stripe pg @types/pg

yarn

bash
yarn add stripe-sync-engine stripe pg @types/pg

bun

bash
bun add stripe-sync-engine stripe pg @types/pg

Deno

typescript
import { StripeSync } from 'npm:stripe-sync-engine@latest'

Step 2: Environment Variables

Add these to your .env.local (or .env):

env
# Required: PostgreSQL connection string
DATABASE_URL=postgresql://user:password@localhost:5432/database_name

# Required: Stripe API keys
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Optional: Stripe API version (defaults to 2020-08-27)
STRIPE_API_VERSION=2023-10-16

Getting the Webhook Secret

  1. Go to Stripe Dashboard > Webhooks
  2. Click "Add endpoint" or select an existing endpoint
  3. Copy the "Signing secret" (starts with whsec_)

Step 3: Create StripeSync Utility

Create a singleton utility to manage the StripeSync instance:

For Next.js / Node.js Projects

Create lib/stripeSync.ts:

typescript
import { StripeSync } from "stripe-sync-engine";

let stripeSyncInstance: StripeSync | null = null;

export function getStripeSync(): StripeSync {
  if (!stripeSyncInstance) {
    if (!process.env.DATABASE_URL) {
      throw new Error("DATABASE_URL environment variable is not set");
    }
    if (!process.env.STRIPE_SECRET_KEY) {
      throw new Error("STRIPE_SECRET_KEY environment variable is not set");
    }
    if (!process.env.STRIPE_WEBHOOK_SECRET) {
      throw new Error("STRIPE_WEBHOOK_SECRET environment variable is not set");
    }

    stripeSyncInstance = new StripeSync({
      poolConfig: {
        connectionString: process.env.DATABASE_URL,
        max: 10,
        idleTimeoutMillis: 30000,
        connectionTimeoutMillis: 10000,
      },
      stripeSecretKey: process.env.STRIPE_SECRET_KEY,
      stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
      stripeApiVersion: process.env.STRIPE_API_VERSION || "2023-10-16",
      schema: "stripe",
      autoExpandLists: true,
      backfillRelatedEntities: true,
    });
  }

  return stripeSyncInstance;
}

// Export singleton for direct import
export const stripeSync = getStripeSync();

For Deno Fresh Projects

Create utils/stripeSync.ts:

typescript
import { StripeSync } from "npm:stripe-sync-engine@latest";

const databaseUrl = Deno.env.get("DATABASE_URL");
const stripeSecretKey = Deno.env.get("STRIPE_SECRET_KEY");
const stripeWebhookSecret = Deno.env.get("STRIPE_WEBHOOK_SECRET");

if (!databaseUrl || !stripeSecretKey || !stripeWebhookSecret) {
  throw new Error("Missing required environment variables");
}

export const stripeSync = new StripeSync({
  poolConfig: {
    connectionString: databaseUrl,
    max: 10,
  },
  stripeSecretKey,
  stripeWebhookSecret,
  schema: "stripe",
});

Configuration Options Reference

Option Type Description
poolConfig object PostgreSQL connection pool config (connectionString, max, etc.)
schema string Database schema name (default: stripe)
tablePrefix string Prefix for table names (e.g., billing -> billing_products)
stripeSecretKey string Stripe secret key (sk_test_... or sk_live_...)
stripeWebhookSecret string Stripe webhook signing secret (whsec_...)
stripeApiVersion string Stripe API version (default: 2020-08-27)
autoExpandLists boolean Fetch all list items from Stripe, not just default 10
backfillRelatedEntities boolean Ensure related entities exist for foreign key integrity
revalidateObjectsViaStripeApi array Object types to always fetch fresh from Stripe API
logger Logger Pino logger instance for custom logging

Next Steps

After setup is complete:

  1. Run migrations to create the database schema (see migrations skill)
  2. Create webhook endpoint to receive Stripe events (see webhook skill)
  3. Backfill historical data if you have existing Stripe data (see backfill skill)

Related Skills

  • migrations: Run database migrations to create the Stripe schema
  • webhook: Set up webhook handlers for real-time sync
  • backfill: Import historical Stripe data

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

ashutoshpw/stripe-sync-engine

stripe-sync-migrations

When the user wants to run database migrations for stripe-sync-engine. Also use when the user mentions "run migrations," "stripe schema," "create stripe tables," "database setup," or "stripe_migrations."

0 0
Explore
ashutoshpw/stripe-sync-engine

stripe-sync-troubleshooting

When the user is experiencing issues with stripe-sync-engine. Also use when the user mentions "not working," "webhook error," "signature failed," "connection error," "data not syncing," or "stripe sync broken."

0 0
Explore
ashutoshpw/stripe-sync-engine

stripe-sync-query

When the user wants to query synced Stripe data. Also use when the user mentions "query stripe data," "stripe tables," "select from stripe," "stripe analytics," or "stripe SQL."

0 0
Explore
ashutoshpw/stripe-sync-engine

stripe-sync-minimal

Complete guide for stripe-sync-engine in one skill. Use when the user wants to "sync stripe to database," "stripe-sync-engine," "stripe postgres sync," or needs a quick all-in-one reference.

0 0
Explore
ashutoshpw/stripe-sync-engine

stripe-sync-webhook

When the user wants to create webhook handlers for stripe-sync-engine. Also use when the user mentions "webhook endpoint," "processWebhook," "stripe webhook handler," "stripe events," or "real-time sync."

0 0
Explore
ashutoshpw/stripe-sync-engine

stripe-sync-backfill

When the user wants to import historical Stripe data. Also use when the user mentions "backfill stripe data," "syncBackfill," "import stripe data," "sync existing data," or "historical sync."

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results