stripe-experiment-sync 1.0.6 → 1.0.8

package/dist/index.cjs

@@ -33,24 +33,25 @@ __export(index_exports, {
   PostgresClient: () => PostgresClient,
   StripeSync: () => StripeSync,
   VERSION: () => VERSION,
+  createStripeWebSocketClient: () => createStripeWebSocketClient,
   hashApiKey: () => hashApiKey,
   runMigrations: () => runMigrations
 });
 module.exports = __toCommonJS(index_exports);
 
-// ../../node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_tsx@4.20.6_typescript@5.9.3_yaml@2.8.1/node_modules/tsup/assets/cjs_shims.js
+// ../../node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3_yaml@2.8.1/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.src || new URL("main.js", document.baseURI).href;
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
 // package.json
 var package_default = {
   name: "stripe-experiment-sync",
-  version: "1.0.6",
+  version: "1.0.8-beta.1765856228",
   private: false,
   description: "Stripe Sync Engine to sync Stripe data to Postgres",
   type: "module",
   main: "./dist/index.cjs",
-  bin: "./dist/cli/index.cjs",
+  bin: "./dist/cli/index.js",
   exports: {
     ".": {
       types: "./dist/index.d.ts",
@@ -61,12 +62,17 @@ var package_default = {
       types: "./dist/supabase/index.d.ts",
       import: "./dist/supabase/index.js",
       require: "./dist/supabase/index.cjs"
+    },
+    "./cli": {
+      types: "./dist/cli/lib.d.ts",
+      import: "./dist/cli/lib.js",
+      require: "./dist/cli/lib.cjs"
     }
   },
   scripts: {
     clean: "rimraf dist",
     prebuild: "npm run clean",
-    build: "tsup src/index.ts src/supabase/index.ts --format esm,cjs --dts --shims && cp -r src/database/migrations dist/migrations",
+    build: "tsup src/index.ts src/supabase/index.ts src/cli/index.ts src/cli/lib.ts --format esm,cjs --dts --shims && cp -r src/database/migrations dist/migrations",
     lint: "eslint src --ext .ts",
     test: "vitest"
   },
@@ -74,21 +80,28 @@ var package_default = {
     "dist"
   ],
   dependencies: {
+    "@ngrok/ngrok": "^1.4.1",
+    chalk: "^5.3.0",
+    commander: "^12.1.0",
+    dotenv: "^16.4.7",
+    express: "^4.18.2",
+    inquirer: "^12.3.0",
     pg: "^8.16.3",
     "pg-node-migrations": "0.0.8",
+    stripe: "^17.7.0",
     "supabase-management-js": "^0.1.6",
     ws: "^8.18.0",
     yesql: "^7.0.0"
   },
-  peerDependencies: {
-    stripe: "> 11"
-  },
   devDependencies: {
+    "@types/express": "^4.17.21",
+    "@types/inquirer": "^9.0.7",
     "@types/node": "^24.10.1",
     "@types/pg": "^8.15.5",
     "@types/ws": "^8.5.13",
     "@types/yesql": "^4.1.4",
     "@vitest/ui": "^4.0.9",
+    tsx: "^4.19.2",
     vitest: "^3.2.4"
   },
   repository: {
@@ -143,9 +156,9 @@ var ORDERED_STRIPE_TABLES = [
   "reviews",
   "_managed_webhooks",
   "customers",
-  "_sync_obj_run",
-  // Must be deleted before _sync_run (foreign key)
-  "_sync_run"
+  "_sync_obj_runs",
+  // Must be deleted before _sync_runs (foreign key)
+  "_sync_runs"
 ];
 var TABLES_WITH_ACCOUNT_ID = /* @__PURE__ */ new Set(["_managed_webhooks"]);
 var PostgresClient = class {
@@ -436,7 +449,7 @@ var PostgresClient = class {
   // Observable Sync System Methods
   // =============================================================================
   // These methods support long-running syncs with full observability.
-  // Uses two tables: _sync_run (parent) and _sync_obj_run (children)
+  // Uses two tables: _sync_runs (parent) and _sync_obj_runs (children)
   // RunKey = (accountId, runStartedAt) - natural composite key
   /**
    * Cancel stale runs (running but no object updated in 5 minutes).
@@ -446,7 +459,7 @@ var PostgresClient = class {
    */
   async cancelStaleRuns(accountId) {
     await this.query(
-      `UPDATE "${this.config.schema}"."_sync_obj_run" o
+      `UPDATE "${this.config.schema}"."_sync_obj_runs" o
        SET status = 'error',
            error_message = 'Auto-cancelled: stale (no update in 5 min)',
            completed_at = now()
@@ -456,17 +469,17 @@ var PostgresClient = class {
       [accountId]
     );
     await this.query(
-      `UPDATE "${this.config.schema}"."_sync_run" r
+      `UPDATE "${this.config.schema}"."_sync_runs" r
        SET closed_at = now()
        WHERE r."_account_id" = $1
          AND r.closed_at IS NULL
          AND EXISTS (
-           SELECT 1 FROM "${this.config.schema}"."_sync_obj_run" o
+           SELECT 1 FROM "${this.config.schema}"."_sync_obj_runs" o
            WHERE o."_account_id" = r."_account_id"
              AND o.run_started_at = r.started_at
          )
          AND NOT EXISTS (
-           SELECT 1 FROM "${this.config.schema}"."_sync_obj_run" o
+           SELECT 1 FROM "${this.config.schema}"."_sync_obj_runs" o
            WHERE o."_account_id" = r."_account_id"
              AND o.run_started_at = r.started_at
              AND o.status IN ('pending', 'running')
@@ -484,7 +497,7 @@ var PostgresClient = class {
   async getOrCreateSyncRun(accountId, triggeredBy) {
     await this.cancelStaleRuns(accountId);
     const existing = await this.query(
-      `SELECT "_account_id", started_at FROM "${this.config.schema}"."_sync_run"
+      `SELECT "_account_id", started_at FROM "${this.config.schema}"."_sync_runs"
        WHERE "_account_id" = $1 AND closed_at IS NULL`,
       [accountId]
     );
@@ -494,7 +507,7 @@ var PostgresClient = class {
     }
     try {
       const result = await this.query(
-        `INSERT INTO "${this.config.schema}"."_sync_run" ("_account_id", triggered_by, started_at)
+        `INSERT INTO "${this.config.schema}"."_sync_runs" ("_account_id", triggered_by, started_at)
          VALUES ($1, $2, date_trunc('milliseconds', now()))
          RETURNING "_account_id", started_at`,
         [accountId, triggeredBy ?? null]
@@ -513,7 +526,7 @@ var PostgresClient = class {
    */
   async getActiveSyncRun(accountId) {
     const result = await this.query(
-      `SELECT "_account_id", started_at FROM "${this.config.schema}"."_sync_run"
+      `SELECT "_account_id", started_at FROM "${this.config.schema}"."_sync_runs"
        WHERE "_account_id" = $1 AND closed_at IS NULL`,
       [accountId]
     );
@@ -523,12 +536,12 @@ var PostgresClient = class {
   }
   /**
    * Get sync run config (for concurrency control).
-   * Status is derived from sync_dashboard view.
+   * Status is derived from sync_runs view.
    */
   async getSyncRun(accountId, runStartedAt) {
     const result = await this.query(
       `SELECT "_account_id", started_at, max_concurrent, closed_at
-       FROM "${this.config.schema}"."_sync_run"
+       FROM "${this.config.schema}"."_sync_runs"
        WHERE "_account_id" = $1 AND started_at = $2`,
       [accountId, runStartedAt]
     );
@@ -547,7 +560,7 @@ var PostgresClient = class {
    */
   async closeSyncRun(accountId, runStartedAt) {
     await this.query(
-      `UPDATE "${this.config.schema}"."_sync_run"
+      `UPDATE "${this.config.schema}"."_sync_runs"
        SET closed_at = now()
        WHERE "_account_id" = $1 AND started_at = $2 AND closed_at IS NULL`,
       [accountId, runStartedAt]
@@ -561,7 +574,7 @@ var PostgresClient = class {
     if (objects.length === 0) return;
     const values = objects.map((_, i) => `($1, $2, $${i + 3})`).join(", ");
     await this.query(
-      `INSERT INTO "${this.config.schema}"."_sync_obj_run" ("_account_id", run_started_at, object)
+      `INSERT INTO "${this.config.schema}"."_sync_obj_runs" ("_account_id", run_started_at, object)
        VALUES ${values}
        ON CONFLICT ("_account_id", run_started_at, object) DO NOTHING`,
       [accountId, runStartedAt, ...objects]
@@ -580,7 +593,7 @@ var PostgresClient = class {
     const runningCount = await this.countRunningObjects(accountId, runStartedAt);
     if (runningCount >= run.maxConcurrent) return false;
     const result = await this.query(
-      `UPDATE "${this.config.schema}"."_sync_obj_run"
+      `UPDATE "${this.config.schema}"."_sync_obj_runs"
        SET status = 'running', started_at = now(), updated_at = now()
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3 AND status = 'pending'
        RETURNING *`,
@@ -594,7 +607,7 @@ var PostgresClient = class {
   async getObjectRun(accountId, runStartedAt, object) {
     const result = await this.query(
       `SELECT object, status, processed_count, cursor
-       FROM "${this.config.schema}"."_sync_obj_run"
+       FROM "${this.config.schema}"."_sync_obj_runs"
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object]
     );
@@ -613,7 +626,7 @@ var PostgresClient = class {
    */
   async incrementObjectProgress(accountId, runStartedAt, object, count) {
     await this.query(
-      `UPDATE "${this.config.schema}"."_sync_obj_run"
+      `UPDATE "${this.config.schema}"."_sync_obj_runs"
        SET processed_count = processed_count + $4, updated_at = now()
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object, count]
@@ -629,7 +642,7 @@ var PostgresClient = class {
     const isNumeric = cursor !== null && /^\d+$/.test(cursor);
     if (isNumeric) {
       await this.query(
-        `UPDATE "${this.config.schema}"."_sync_obj_run"
+        `UPDATE "${this.config.schema}"."_sync_obj_runs"
          SET cursor = GREATEST(COALESCE(cursor::bigint, 0), $4::bigint)::text,
              updated_at = now()
          WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
@@ -637,7 +650,7 @@ var PostgresClient = class {
       );
     } else {
       await this.query(
-        `UPDATE "${this.config.schema}"."_sync_obj_run"
+        `UPDATE "${this.config.schema}"."_sync_obj_runs"
          SET cursor = $4, updated_at = now()
          WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
         [accountId, runStartedAt, object, cursor]
@@ -653,7 +666,7 @@ var PostgresClient = class {
   async getLastCompletedCursor(accountId, object) {
     const result = await this.query(
       `SELECT MAX(o.cursor::bigint)::text as cursor
-       FROM "${this.config.schema}"."_sync_obj_run" o
+       FROM "${this.config.schema}"."_sync_obj_runs" o
        WHERE o."_account_id" = $1
          AND o.object = $2
          AND o.cursor IS NOT NULL`,
@@ -667,10 +680,10 @@ var PostgresClient = class {
    */
   async deleteSyncRuns(accountId) {
     await this.query(
-      `DELETE FROM "${this.config.schema}"."_sync_obj_run" WHERE "_account_id" = $1`,
+      `DELETE FROM "${this.config.schema}"."_sync_obj_runs" WHERE "_account_id" = $1`,
       [accountId]
     );
-    await this.query(`DELETE FROM "${this.config.schema}"."_sync_run" WHERE "_account_id" = $1`, [
+    await this.query(`DELETE FROM "${this.config.schema}"."_sync_runs" WHERE "_account_id" = $1`, [
       accountId
     ]);
   }
@@ -680,7 +693,7 @@ var PostgresClient = class {
    */
   async completeObjectSync(accountId, runStartedAt, object) {
     await this.query(
-      `UPDATE "${this.config.schema}"."_sync_obj_run"
+      `UPDATE "${this.config.schema}"."_sync_obj_runs"
        SET status = 'complete', completed_at = now()
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object]
@@ -696,7 +709,7 @@ var PostgresClient = class {
    */
   async failObjectSync(accountId, runStartedAt, object, errorMessage) {
     await this.query(
-      `UPDATE "${this.config.schema}"."_sync_obj_run"
+      `UPDATE "${this.config.schema}"."_sync_obj_runs"
        SET status = 'error', error_message = $4, completed_at = now()
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object, errorMessage]
@@ -711,7 +724,7 @@ var PostgresClient = class {
    */
   async hasAnyObjectErrors(accountId, runStartedAt) {
     const result = await this.query(
-      `SELECT COUNT(*) as count FROM "${this.config.schema}"."_sync_obj_run"
+      `SELECT COUNT(*) as count FROM "${this.config.schema}"."_sync_obj_runs"
        WHERE "_account_id" = $1 AND run_started_at = $2 AND status = 'error'`,
       [accountId, runStartedAt]
     );
@@ -722,7 +735,7 @@ var PostgresClient = class {
    */
   async countRunningObjects(accountId, runStartedAt) {
     const result = await this.query(
-      `SELECT COUNT(*) as count FROM "${this.config.schema}"."_sync_obj_run"
+      `SELECT COUNT(*) as count FROM "${this.config.schema}"."_sync_obj_runs"
        WHERE "_account_id" = $1 AND run_started_at = $2 AND status = 'running'`,
       [accountId, runStartedAt]
     );
@@ -738,7 +751,7 @@ var PostgresClient = class {
     const runningCount = await this.countRunningObjects(accountId, runStartedAt);
     if (runningCount >= run.maxConcurrent) return null;
     const result = await this.query(
-      `SELECT object FROM "${this.config.schema}"."_sync_obj_run"
+      `SELECT object FROM "${this.config.schema}"."_sync_obj_runs"
        WHERE "_account_id" = $1 AND run_started_at = $2 AND status = 'pending'
        ORDER BY object
        LIMIT 1`,
@@ -751,7 +764,7 @@ var PostgresClient = class {
    */
   async areAllObjectsComplete(accountId, runStartedAt) {
     const result = await this.query(
-      `SELECT COUNT(*) as count FROM "${this.config.schema}"."_sync_obj_run"
+      `SELECT COUNT(*) as count FROM "${this.config.schema}"."_sync_obj_runs"
        WHERE "_account_id" = $1 AND run_started_at = $2 AND status IN ('pending', 'running')`,
       [accountId, runStartedAt]
     );
@@ -1717,19 +1730,8 @@ var StripeSync = class {
     if (params?.runStartedAt) {
       runStartedAt = params.runStartedAt;
     } else {
-      const runKey = await this.postgresClient.getOrCreateSyncRun(
-        accountId,
-        params?.triggeredBy ?? "processNext"
-      );
-      if (!runKey) {
-        const activeRun = await this.postgresClient.getActiveSyncRun(accountId);
-        if (!activeRun) {
-          throw new Error("Failed to get or create sync run");
-        }
-        runStartedAt = activeRun.runStartedAt;
-      } else {
-        runStartedAt = runKey.runStartedAt;
-      }
+      const { runKey } = await this.joinOrCreateSyncRun(params?.triggeredBy ?? "processNext");
+      runStartedAt = runKey.runStartedAt;
     }
     await this.postgresClient.createObjectRuns(accountId, runStartedAt, [resourceName]);
     const objRun = await this.postgresClient.getObjectRun(accountId, runStartedAt, resourceName);
@@ -1892,18 +1894,39 @@ var StripeSync = class {
     }
     return { synced: totalSynced };
   }
-  async processUntilDone(params) {
-    const { object } = params ?? { object: "all" };
+  /**
+   * Join existing sync run or create a new one.
+   * Returns sync run key and list of supported objects to sync.
+   *
+   * Cooperative behavior: If a sync run already exists, joins it instead of failing.
+   * This is used by workers and background processes that should cooperate.
+   *
+   * @param triggeredBy - What triggered this sync (for observability)
+   * @returns Run key and list of objects to sync
+   */
+  async joinOrCreateSyncRun(triggeredBy = "worker") {
     await this.getCurrentAccount();
     const accountId = await this.getAccountId();
-    const runKey = await this.postgresClient.getOrCreateSyncRun(accountId, "processUntilDone");
-    if (!runKey) {
+    const result = await this.postgresClient.getOrCreateSyncRun(accountId, triggeredBy);
+    if (!result) {
       const activeRun = await this.postgresClient.getActiveSyncRun(accountId);
       if (!activeRun) {
         throw new Error("Failed to get or create sync run");
       }
-      return this.processUntilDoneWithRun(activeRun.runStartedAt, object, params);
+      return {
+        runKey: { accountId: activeRun.accountId, runStartedAt: activeRun.runStartedAt },
+        objects: this.getSupportedSyncObjects()
+      };
     }
+    const { accountId: runAccountId, runStartedAt } = result;
+    return {
+      runKey: { accountId: runAccountId, runStartedAt },
+      objects: this.getSupportedSyncObjects()
+    };
+  }
+  async processUntilDone(params) {
+    const { object } = params ?? { object: "all" };
+    const { runKey } = await this.joinOrCreateSyncRun("processUntilDone");
     return this.processUntilDoneWithRun(runKey.runStartedAt, object, params);
   }
   /**
@@ -2518,14 +2541,14 @@ var StripeSync = class {
       throw error;
     }
   }
-  async fetchAndUpsert(fetch, upsert, accountId, resourceName, runStartedAt) {
+  async fetchAndUpsert(fetch2, upsert, accountId, resourceName, runStartedAt) {
     const CHECKPOINT_SIZE = 100;
     let totalSynced = 0;
     let currentBatch = [];
     try {
       this.config.logger?.info("Fetching items to sync from Stripe");
       try {
-        for await (const item of fetch()) {
+        for await (const item of fetch2()) {
           currentBatch.push(item);
           if (currentBatch.length >= CHECKPOINT_SIZE) {
             this.config.logger?.info(`Upserting batch of ${currentBatch.length} items`);
@@ -3251,11 +3274,11 @@ var StripeSync = class {
       }
     }
   }
-  async fetchMissingEntities(ids, fetch) {
+  async fetchMissingEntities(ids, fetch2) {
     if (!ids.length) return [];
     const entities = [];
     for (const id of ids) {
-      const entity = await fetch(id);
+      const entity = await fetch2(id);
       entities.push(entity);
     }
     return entities;
@@ -3362,6 +3385,167 @@ async function runMigrations(config) {
   }
 }
 
+// src/websocket-client.ts
+var import_ws = __toESM(require("ws"), 1);
+var CLI_VERSION = "1.33.0";
+var PONG_WAIT = 10 * 1e3;
+var PING_PERIOD = PONG_WAIT * 2 / 10;
+function getClientUserAgent() {
+  return JSON.stringify({
+    name: "stripe-cli",
+    version: CLI_VERSION,
+    publisher: "stripe",
+    os: process.platform
+  });
+}
+async function createCliSession(stripeApiKey) {
+  const params = new URLSearchParams();
+  params.append("device_name", "stripe-sync-engine");
+  params.append("websocket_features[]", "webhooks");
+  const response = await fetch("https://api.stripe.com/v1/stripecli/sessions", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${stripeApiKey}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+      "User-Agent": `Stripe/v1 stripe-cli/${CLI_VERSION}`,
+      "X-Stripe-Client-User-Agent": getClientUserAgent()
+    },
+    body: params.toString()
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to create CLI session: ${error}`);
+  }
+  return await response.json();
+}
+async function createStripeWebSocketClient(options) {
+  const { stripeApiKey, onEvent, onReady, onError, onClose } = options;
+  const session = await createCliSession(stripeApiKey);
+  let ws = null;
+  let pingInterval = null;
+  let connected = false;
+  let shouldReconnect = true;
+  function connect() {
+    const wsUrl = `${session.websocket_url}?websocket_feature=${encodeURIComponent(session.websocket_authorized_feature)}`;
+    ws = new import_ws.default(wsUrl, {
+      headers: {
+        "Accept-Encoding": "identity",
+        "User-Agent": `Stripe/v1 stripe-cli/${CLI_VERSION}`,
+        "X-Stripe-Client-User-Agent": getClientUserAgent(),
+        "Websocket-Id": session.websocket_id
+      }
+    });
+    ws.on("pong", () => {
+    });
+    ws.on("open", () => {
+      connected = true;
+      pingInterval = setInterval(() => {
+        if (ws && ws.readyState === import_ws.default.OPEN) {
+          ws.ping();
+        }
+      }, PING_PERIOD);
+      if (onReady) {
+        onReady(session.secret);
+      }
+    });
+    ws.on("message", async (data) => {
+      try {
+        const message = JSON.parse(data.toString());
+        const ack = {
+          type: "event_ack",
+          event_id: message.webhook_id,
+          webhook_conversation_id: message.webhook_conversation_id,
+          webhook_id: message.webhook_id
+        };
+        if (ws && ws.readyState === import_ws.default.OPEN) {
+          ws.send(JSON.stringify(ack));
+        }
+        let response;
+        try {
+          const result = await onEvent(message);
+          response = {
+            type: "webhook_response",
+            webhook_id: message.webhook_id,
+            webhook_conversation_id: message.webhook_conversation_id,
+            forward_url: "stripe-sync-engine",
+            status: result?.status ?? 200,
+            http_headers: {},
+            body: JSON.stringify({
+              event_type: result?.event_type,
+              event_id: result?.event_id,
+              database_url: result?.databaseUrl,
+              error: result?.error
+            }),
+            request_headers: message.http_headers,
+            request_body: message.event_payload,
+            notification_id: message.webhook_id
+          };
+        } catch (err) {
+          const errorMessage = err instanceof Error ? err.message : String(err);
+          response = {
+            type: "webhook_response",
+            webhook_id: message.webhook_id,
+            webhook_conversation_id: message.webhook_conversation_id,
+            forward_url: "stripe-sync-engine",
+            status: 500,
+            http_headers: {},
+            body: JSON.stringify({ error: errorMessage }),
+            request_headers: message.http_headers,
+            request_body: message.event_payload,
+            notification_id: message.webhook_id
+          };
+          if (onError) {
+            onError(err instanceof Error ? err : new Error(errorMessage));
+          }
+        }
+        if (ws && ws.readyState === import_ws.default.OPEN) {
+          ws.send(JSON.stringify(response));
+        }
+      } catch (err) {
+        if (onError) {
+          onError(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+    });
+    ws.on("error", (error) => {
+      if (onError) {
+        onError(error);
+      }
+    });
+    ws.on("close", (code, reason) => {
+      connected = false;
+      if (pingInterval) {
+        clearInterval(pingInterval);
+        pingInterval = null;
+      }
+      if (onClose) {
+        onClose(code, reason.toString());
+      }
+      if (shouldReconnect) {
+        const delay = (session.reconnect_delay || 5) * 1e3;
+        setTimeout(() => {
+          connect();
+        }, delay);
+      }
+    });
+  }
+  connect();
+  return {
+    close: () => {
+      shouldReconnect = false;
+      if (pingInterval) {
+        clearInterval(pingInterval);
+        pingInterval = null;
+      }
+      if (ws) {
+        ws.close(1e3, "Connection Done");
+        ws = null;
+      }
+    },
+    isConnected: () => connected
+  };
+}
+
 // src/index.ts
 var VERSION = package_default.version;
 // Annotate the CommonJS export names for ESM import in node:
@@ -3369,6 +3553,7 @@ var VERSION = package_default.version;
   PostgresClient,
   StripeSync,
   VERSION,
+  createStripeWebSocketClient,
   hashApiKey,
   runMigrations
 });

package/dist/index.d.cts

@@ -105,7 +105,7 @@ declare class PostgresClient {
     } | null>;
     /**
      * Get sync run config (for concurrency control).
-     * Status is derived from sync_dashboard view.
+     * Status is derived from sync_runs view.
      */
     getSyncRun(accountId: string, runStartedAt: Date): Promise<{
         accountId: string;
@@ -335,6 +335,13 @@ interface ProcessNextParams extends SyncParams {
     triggeredBy?: string;
 }
 
+/**
+ * Identifies a specific sync run.
+ */
+type RunKey = {
+    accountId: string;
+    runStartedAt: Date;
+};
 declare class StripeSync {
     private config;
     stripe: Stripe;
@@ -470,6 +477,20 @@ declare class StripeSync {
      * @returns Sync result with count of synced items
      */
     private processObjectUntilDone;
+    /**
+     * Join existing sync run or create a new one.
+     * Returns sync run key and list of supported objects to sync.
+     *
+     * Cooperative behavior: If a sync run already exists, joins it instead of failing.
+     * This is used by workers and background processes that should cooperate.
+     *
+     * @param triggeredBy - What triggered this sync (for observability)
+     * @returns Run key and list of objects to sync
+     */
+    joinOrCreateSyncRun(triggeredBy?: string): Promise<{
+        runKey: RunKey;
+        objects: Exclude<SyncObject, 'all' | 'customer_with_entitlements'>[];
+    }>;
     processUntilDone(params?: SyncParams): Promise<SyncBackfill>;
     /**
      * Internal implementation of processUntilDone with an existing run.
@@ -600,6 +621,37 @@ declare function runMigrations(config: MigrationConfig): Promise<void>;
  */
 declare function hashApiKey(apiKey: string): string;
 
+interface WebhookProcessingResult {
+    status: number;
+    databaseUrl: string;
+    event_type?: string;
+    event_id?: string;
+    error?: string;
+}
+interface StripeWebSocketOptions {
+    stripeApiKey: string;
+    onEvent: (event: StripeWebhookEvent) => Promise<WebhookProcessingResult | void> | WebhookProcessingResult | void;
+    onReady?: (secret: string) => void;
+    onError?: (error: Error) => void;
+    onClose?: (code: number, reason: string) => void;
+}
+interface StripeWebSocketClient {
+    close: () => void;
+    isConnected: () => boolean;
+}
+interface StripeWebhookEvent {
+    type: string;
+    webhook_id: string;
+    webhook_conversation_id: string;
+    event_payload: string;
+    http_headers: Record<string, string>;
+    endpoint: {
+        url: string;
+        status: string;
+    };
+}
+declare function createStripeWebSocketClient(options: StripeWebSocketOptions): Promise<StripeWebSocketClient>;
+
 declare const VERSION: string;
 
-export { type Logger, PostgresClient, type ProcessNextParams, type ProcessNextResult, type RevalidateEntity, StripeSync, type StripeSyncConfig, type Sync, type SyncBackfill, type SyncEntitlementsParams, type SyncFeaturesParams, type SyncObject, type SyncParams, VERSION, hashApiKey, runMigrations };
+export { type Logger, PostgresClient, type ProcessNextParams, type ProcessNextResult, type RevalidateEntity, StripeSync, type StripeSyncConfig, type StripeWebSocketClient, type StripeWebSocketOptions, type StripeWebhookEvent, type Sync, type SyncBackfill, type SyncEntitlementsParams, type SyncFeaturesParams, type SyncObject, type SyncParams, VERSION, type WebhookProcessingResult, createStripeWebSocketClient, hashApiKey, runMigrations };