stripe-experiment-sync 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,222 @@
+import { Express } from 'express';
+import pg, { PoolConfig, QueryResult } from 'pg';
+import pino from 'pino';
+import Stripe from 'stripe';
+
+interface StripeAutoSyncOptions {
+    databaseUrl: string;
+    stripeApiKey: string;
+    baseUrl: () => string;
+    webhookPath?: string;
+    schema?: string;
+    stripeApiVersion?: string;
+    autoExpandLists?: boolean;
+    backfillRelatedEntities?: boolean;
+}
+interface StripeAutoSyncInfo {
+    baseUrl: string;
+    webhookUrl: string;
+    webhookUuid: string;
+}
+/**
+ * Manages Stripe webhook auto-sync infrastructure:
+ * - Runs database migrations
+ * - Creates managed webhook in Stripe
+ * - Mounts webhook handler on Express app
+ */
+declare class StripeAutoSync {
+    private options;
+    private webhookId;
+    private webhookUuid;
+    private stripeSync;
+    constructor(options: StripeAutoSyncOptions);
+    /**
+     * Starts the Stripe Sync infrastructure and mounts webhook handler:
+     * 1. Runs database migrations
+     * 2. Creates StripeSync instance
+     * 3. Creates managed webhook endpoint
+     * 4. Mounts webhook handler on provided Express app
+     * 5. Applies body parsing middleware (automatically skips webhook routes)
+     *
+     * @param app - Express app to mount webhook handler on
+     * @returns Information about the running instance
+     */
+    start(app: Express): Promise<StripeAutoSyncInfo>;
+    /**
+     * Stops all services and cleans up resources:
+     * 1. Deletes Stripe webhook endpoint from Stripe and database
+     */
+    stop(): Promise<void>;
+    /**
+     * Returns Express middleware for body parsing that automatically skips webhook routes.
+     * This middleware applies JSON and URL-encoded parsers to all routes EXCEPT the webhook path,
+     * which needs raw body for signature verification.
+     *
+     * @returns Express middleware function
+     */
+    private getBodyParserMiddleware;
+    /**
+     * Mounts the Stripe webhook handler on the provided Express app.
+     * Applies raw body parser middleware for signature verification.
+     * IMPORTANT: Must be called BEFORE app.use(express.json()) to ensure raw body parsing.
+     */
+    private mountWebhook;
+}
+
+type RevalidateEntity = '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' | 'entitlements';
+type StripeSyncConfig = {
+    /** @deprecated Use `poolConfig` with a connection string instead. */
+    databaseUrl?: string;
+    /** Database schema name. */
+    schema?: string;
+    /** Stripe secret key used to authenticate requests to the Stripe API. Defaults to empty string */
+    stripeSecretKey: string;
+    /** Stripe API version for the webhooks, defaults to 2020-08-27 */
+    stripeApiVersion?: string;
+    /**
+     * Stripe limits related lists like invoice items in an invoice to 10 by default.
+     * By enabling this, sync-engine automatically fetches the remaining elements before saving
+     * */
+    autoExpandLists?: boolean;
+    /**
+     * If true, the sync engine will backfill related entities, i.e. when a invoice webhook comes in, it ensures that the customer is present and synced.
+     * This ensures foreign key integrity, but comes at the cost of additional queries to the database (and added latency for Stripe calls if the entity is actually missing).
+     */
+    backfillRelatedEntities?: boolean;
+    /**
+     * If true, the webhook data is not used and instead the webhook is just a trigger to fetch the entity from Stripe again. This ensures that a race condition with failed webhooks can never accidentally overwrite the data with an older state.
+     *
+     * Default: false
+     */
+    revalidateObjectsViaStripeApi?: Array<RevalidateEntity>;
+    /** @deprecated Use `poolConfig` instead. */
+    maxPostgresConnections?: number;
+    poolConfig: PoolConfig;
+    logger?: pino.Logger;
+};
+type SyncObject = 'all' | 'customer' | 'customer_with_entitlements' | 'invoice' | 'price' | 'product' | 'subscription' | 'subscription_schedules' | 'setup_intent' | 'payment_method' | 'dispute' | 'charge' | 'payment_intent' | 'plan' | 'tax_id' | 'credit_note' | 'early_fraud_warning' | 'refund' | 'checkout_sessions';
+interface Sync {
+    synced: number;
+}
+interface SyncBackfill {
+    products?: Sync;
+    prices?: Sync;
+    plans?: Sync;
+    customers?: Sync;
+    subscriptions?: Sync;
+    subscriptionSchedules?: Sync;
+    invoices?: Sync;
+    setupIntents?: Sync;
+    paymentIntents?: Sync;
+    paymentMethods?: Sync;
+    disputes?: Sync;
+    charges?: Sync;
+    taxIds?: Sync;
+    creditNotes?: Sync;
+    earlyFraudWarnings?: Sync;
+    refunds?: Sync;
+    checkoutSessions?: Sync;
+}
+interface SyncBackfillParams {
+    created?: {
+        /**
+         * Minimum value to filter by (exclusive)
+         */
+        gt?: number;
+        /**
+         * Minimum value to filter by (inclusive)
+         */
+        gte?: number;
+        /**
+         * Maximum value to filter by (exclusive)
+         */
+        lt?: number;
+        /**
+         * Maximum value to filter by (inclusive)
+         */
+        lte?: number;
+    };
+    object?: SyncObject;
+    backfillRelatedEntities?: boolean;
+}
+interface SyncEntitlementsParams {
+    object: 'entitlements';
+    customerId: string;
+    pagination?: Pick<Stripe.PaginationParams, 'starting_after' | 'ending_before'>;
+}
+interface SyncFeaturesParams {
+    object: 'features';
+    pagination?: Pick<Stripe.PaginationParams, 'starting_after' | 'ending_before'>;
+}
+
+interface EntitySchema {
+    readonly properties: string[];
+}
+
+type PostgresConfig = {
+    schema: string;
+    poolConfig: PoolConfig;
+};
+declare class PostgresClient {
+    private config;
+    pool: pg.Pool;
+    constructor(config: PostgresConfig);
+    delete(table: string, id: string): Promise<boolean>;
+    query(text: string, params?: string[]): Promise<QueryResult>;
+    upsertMany<T extends {
+        [Key: string]: any;
+    }>(entries: T[], table: string, tableSchema: EntitySchema): Promise<T[]>;
+    upsertManyWithTimestampProtection<T extends {
+        [Key: string]: any;
+    }>(entries: T[], table: string, tableSchema: EntitySchema, syncTimestamp?: string): Promise<T[]>;
+    findMissingEntries(table: string, ids: string[]): Promise<string[]>;
+    /**
+     * Returns an (yesql formatted) upsert function based on the key/vals of an object.
+     * eg,
+     *  insert into customers ("id", "name")
+     *  values (:id, :name)
+     *  on conflict (id)
+     *  do update set (
+     *   "id" = :id,
+     *   "name" = :name
+     *  )
+     */
+    private constructUpsertSql;
+    /**
+     * Returns an (yesql formatted) upsert function with timestamp protection.
+     *
+     * The WHERE clause in ON CONFLICT DO UPDATE only applies to the conflicting row
+     * (the row being updated), not to all rows in the table. PostgreSQL ensures that
+     * the condition is evaluated only for the specific row that conflicts with the INSERT.
+     *
+     *
+     * eg:
+     *   INSERT INTO "stripe"."charges" (
+     *     "id", "amount", "created", "last_synced_at"
+     *   )
+     *   VALUES (
+     *     :id, :amount, :created, :last_synced_at
+     *   )
+     *   ON CONFLICT (id) DO UPDATE SET
+     *     "amount" = EXCLUDED."amount",
+     *     "created" = EXCLUDED."created",
+     *     last_synced_at = :last_synced_at
+     *   WHERE "charges"."last_synced_at" IS NULL
+     *      OR "charges"."last_synced_at" < :last_synced_at;
+     */
+    private constructUpsertWithTimestampProtectionSql;
+    /**
+     * For array object field like invoice.custom_fields
+     * ex: [{"name":"Project name","value":"Test Project"}]
+     *
+     * we need to stringify it first cos passing array object directly will end up with
+     * {
+     * invalid input syntax for type json
+     * detail: 'Expected ":", but found "}".',
+     * where: 'JSON data, line 1: ...\\":\\"Project name\\",\\"value\\":\\"Test Project\\"}"}',
+     * }
+     */
+    private cleanseArrayField;
+}
+
+export { PostgresClient, type RevalidateEntity, StripeAutoSync, type StripeAutoSyncInfo, type StripeAutoSyncOptions, type StripeSyncConfig, type Sync, type SyncBackfill, type SyncBackfillParams, type SyncEntitlementsParams, type SyncFeaturesParams, type SyncObject };

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+import { Express } from 'express';
+import pg, { PoolConfig, QueryResult } from 'pg';
+import pino from 'pino';
+import Stripe from 'stripe';
+
+interface StripeAutoSyncOptions {
+    databaseUrl: string;
+    stripeApiKey: string;
+    baseUrl: () => string;
+    webhookPath?: string;
+    schema?: string;
+    stripeApiVersion?: string;
+    autoExpandLists?: boolean;
+    backfillRelatedEntities?: boolean;
+}
+interface StripeAutoSyncInfo {
+    baseUrl: string;
+    webhookUrl: string;
+    webhookUuid: string;
+}
+/**
+ * Manages Stripe webhook auto-sync infrastructure:
+ * - Runs database migrations
+ * - Creates managed webhook in Stripe
+ * - Mounts webhook handler on Express app
+ */
+declare class StripeAutoSync {
+    private options;
+    private webhookId;
+    private webhookUuid;
+    private stripeSync;
+    constructor(options: StripeAutoSyncOptions);
+    /**
+     * Starts the Stripe Sync infrastructure and mounts webhook handler:
+     * 1. Runs database migrations
+     * 2. Creates StripeSync instance
+     * 3. Creates managed webhook endpoint
+     * 4. Mounts webhook handler on provided Express app
+     * 5. Applies body parsing middleware (automatically skips webhook routes)
+     *
+     * @param app - Express app to mount webhook handler on
+     * @returns Information about the running instance
+     */
+    start(app: Express): Promise<StripeAutoSyncInfo>;
+    /**
+     * Stops all services and cleans up resources:
+     * 1. Deletes Stripe webhook endpoint from Stripe and database
+     */
+    stop(): Promise<void>;
+    /**
+     * Returns Express middleware for body parsing that automatically skips webhook routes.
+     * This middleware applies JSON and URL-encoded parsers to all routes EXCEPT the webhook path,
+     * which needs raw body for signature verification.
+     *
+     * @returns Express middleware function
+     */
+    private getBodyParserMiddleware;
+    /**
+     * Mounts the Stripe webhook handler on the provided Express app.
+     * Applies raw body parser middleware for signature verification.
+     * IMPORTANT: Must be called BEFORE app.use(express.json()) to ensure raw body parsing.
+     */
+    private mountWebhook;
+}
+
+type RevalidateEntity = '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' | 'entitlements';
+type StripeSyncConfig = {
+    /** @deprecated Use `poolConfig` with a connection string instead. */
+    databaseUrl?: string;
+    /** Database schema name. */
+    schema?: string;
+    /** Stripe secret key used to authenticate requests to the Stripe API. Defaults to empty string */
+    stripeSecretKey: string;
+    /** Stripe API version for the webhooks, defaults to 2020-08-27 */
+    stripeApiVersion?: string;
+    /**
+     * Stripe limits related lists like invoice items in an invoice to 10 by default.
+     * By enabling this, sync-engine automatically fetches the remaining elements before saving
+     * */
+    autoExpandLists?: boolean;
+    /**
+     * If true, the sync engine will backfill related entities, i.e. when a invoice webhook comes in, it ensures that the customer is present and synced.
+     * This ensures foreign key integrity, but comes at the cost of additional queries to the database (and added latency for Stripe calls if the entity is actually missing).
+     */
+    backfillRelatedEntities?: boolean;
+    /**
+     * If true, the webhook data is not used and instead the webhook is just a trigger to fetch the entity from Stripe again. This ensures that a race condition with failed webhooks can never accidentally overwrite the data with an older state.
+     *
+     * Default: false
+     */
+    revalidateObjectsViaStripeApi?: Array<RevalidateEntity>;
+    /** @deprecated Use `poolConfig` instead. */
+    maxPostgresConnections?: number;
+    poolConfig: PoolConfig;
+    logger?: pino.Logger;
+};
+type SyncObject = 'all' | 'customer' | 'customer_with_entitlements' | 'invoice' | 'price' | 'product' | 'subscription' | 'subscription_schedules' | 'setup_intent' | 'payment_method' | 'dispute' | 'charge' | 'payment_intent' | 'plan' | 'tax_id' | 'credit_note' | 'early_fraud_warning' | 'refund' | 'checkout_sessions';
+interface Sync {
+    synced: number;
+}
+interface SyncBackfill {
+    products?: Sync;
+    prices?: Sync;
+    plans?: Sync;
+    customers?: Sync;
+    subscriptions?: Sync;
+    subscriptionSchedules?: Sync;
+    invoices?: Sync;
+    setupIntents?: Sync;
+    paymentIntents?: Sync;
+    paymentMethods?: Sync;
+    disputes?: Sync;
+    charges?: Sync;
+    taxIds?: Sync;
+    creditNotes?: Sync;
+    earlyFraudWarnings?: Sync;
+    refunds?: Sync;
+    checkoutSessions?: Sync;
+}
+interface SyncBackfillParams {
+    created?: {
+        /**
+         * Minimum value to filter by (exclusive)
+         */
+        gt?: number;
+        /**
+         * Minimum value to filter by (inclusive)
+         */
+        gte?: number;
+        /**
+         * Maximum value to filter by (exclusive)
+         */
+        lt?: number;
+        /**
+         * Maximum value to filter by (inclusive)
+         */
+        lte?: number;
+    };
+    object?: SyncObject;
+    backfillRelatedEntities?: boolean;
+}
+interface SyncEntitlementsParams {
+    object: 'entitlements';
+    customerId: string;
+    pagination?: Pick<Stripe.PaginationParams, 'starting_after' | 'ending_before'>;
+}
+interface SyncFeaturesParams {
+    object: 'features';
+    pagination?: Pick<Stripe.PaginationParams, 'starting_after' | 'ending_before'>;
+}
+
+interface EntitySchema {
+    readonly properties: string[];
+}
+
+type PostgresConfig = {
+    schema: string;
+    poolConfig: PoolConfig;
+};
+declare class PostgresClient {
+    private config;
+    pool: pg.Pool;
+    constructor(config: PostgresConfig);
+    delete(table: string, id: string): Promise<boolean>;
+    query(text: string, params?: string[]): Promise<QueryResult>;
+    upsertMany<T extends {
+        [Key: string]: any;
+    }>(entries: T[], table: string, tableSchema: EntitySchema): Promise<T[]>;
+    upsertManyWithTimestampProtection<T extends {
+        [Key: string]: any;
+    }>(entries: T[], table: string, tableSchema: EntitySchema, syncTimestamp?: string): Promise<T[]>;
+    findMissingEntries(table: string, ids: string[]): Promise<string[]>;
+    /**
+     * Returns an (yesql formatted) upsert function based on the key/vals of an object.
+     * eg,
+     *  insert into customers ("id", "name")
+     *  values (:id, :name)
+     *  on conflict (id)
+     *  do update set (
+     *   "id" = :id,
+     *   "name" = :name
+     *  )
+     */
+    private constructUpsertSql;
+    /**
+     * Returns an (yesql formatted) upsert function with timestamp protection.
+     *
+     * The WHERE clause in ON CONFLICT DO UPDATE only applies to the conflicting row
+     * (the row being updated), not to all rows in the table. PostgreSQL ensures that
+     * the condition is evaluated only for the specific row that conflicts with the INSERT.
+     *
+     *
+     * eg:
+     *   INSERT INTO "stripe"."charges" (
+     *     "id", "amount", "created", "last_synced_at"
+     *   )
+     *   VALUES (
+     *     :id, :amount, :created, :last_synced_at
+     *   )
+     *   ON CONFLICT (id) DO UPDATE SET
+     *     "amount" = EXCLUDED."amount",
+     *     "created" = EXCLUDED."created",
+     *     last_synced_at = :last_synced_at
+     *   WHERE "charges"."last_synced_at" IS NULL
+     *      OR "charges"."last_synced_at" < :last_synced_at;
+     */
+    private constructUpsertWithTimestampProtectionSql;
+    /**
+     * For array object field like invoice.custom_fields
+     * ex: [{"name":"Project name","value":"Test Project"}]
+     *
+     * we need to stringify it first cos passing array object directly will end up with
+     * {
+     * invalid input syntax for type json
+     * detail: 'Expected ":", but found "}".',
+     * where: 'JSON data, line 1: ...\\":\\"Project name\\",\\"value\\":\\"Test Project\\"}"}',
+     * }
+     */
+    private cleanseArrayField;
+}
+
+export { PostgresClient, type RevalidateEntity, StripeAutoSync, type StripeAutoSyncInfo, type StripeAutoSyncOptions, type StripeSyncConfig, type Sync, type SyncBackfill, type SyncBackfillParams, type SyncEntitlementsParams, type SyncFeaturesParams, type SyncObject };