jazz-webhook 0.18.28

package/dist/webhook.js

@@ -0,0 +1,281 @@
+import { co, z, Account } from "jazz-tools";
+import { getTransactionsToTry, getTxIdKey, markSuccessful, SuccessMap, } from "./successMap.js";
+export const WebhookRegistration = co.map({
+    webhookUrl: z.string(),
+    coValueId: z.string(),
+    active: z.boolean(),
+    successMap: SuccessMap,
+});
+export const RegistryState = co.record(z.string(), WebhookRegistration);
+export const DEFAULT_JazzWebhookOptions = {
+    maxRetries: 3,
+    baseDelayMs: 20000,
+};
+export class WebhookRegistry {
+    constructor(registry, options = {}) {
+        this.options = options;
+        this.activeSubscriptions = new Map();
+        this.rootUnsubscribe = null;
+        this.state = registry;
+    }
+    static createRegistry(owner) {
+        return RegistryState.create({}, owner);
+    }
+    static async loadAndStart(registryId, options = {}) {
+        const registry = await RegistryState.load(registryId);
+        if (!registry) {
+            throw new Error(`Webhook registry with ID ${registryId} not found`);
+        }
+        const webhook = new WebhookRegistry(registry, options);
+        webhook.start();
+        return webhook;
+    }
+    /**
+     * Registers a new webhook for a CoValue.
+     *
+     * @param webhookUrl - The HTTP URL to call when the CoValue changes
+     * @param coValueId - The ID of the CoValue to monitor (must start with "co_z")
+     * @returns The ID of the registered webhook
+     */
+    async register(webhookUrl, coValueId) {
+        const registrationId = await registerWebhook({
+            registryId: this.state.$jazz.id,
+            webhookUrl,
+            coValueId,
+        });
+        // wait for registration to become visible in the registry
+        return new Promise((resolve) => {
+            this.state.$jazz.subscribe((state, unsubscribe) => {
+                if (state.$jazz.refs[registrationId]) {
+                    resolve(registrationId);
+                    unsubscribe();
+                }
+            });
+        });
+    }
+    /**
+     * Unregisters a webhook and stops monitoring the CoValue.
+     *
+     * @param webhookId - The ID of the webhook to unregister
+     */
+    unregister(webhookId) {
+        const webhook = this.state[webhookId];
+        if (!webhook) {
+            throw new Error(`Webhook with ID ${webhookId} not found`);
+        }
+        this.state.$jazz.delete(webhookId);
+        webhook.$jazz.set("active", false);
+    }
+    /**
+     * Starts monitoring a CoValue and emitting webhooks when it changes.
+     *
+     * @param webhookId - The ID of the webhook to start monitoring
+     */
+    subscribe(webhook) {
+        const emitter = new WebhookEmitter(webhook, this.options);
+        this.activeSubscriptions.set(webhook.$jazz.id, () => {
+            emitter.stop();
+            this.activeSubscriptions.delete(webhook.$jazz.id);
+        });
+    }
+    /**
+     * Starts monitoring all active webhooks in the registry.
+     *
+     * This method iterates through all webhooks in the registry and starts
+     * subscriptions for any active webhooks that don't already have active
+     * subscriptions. This is useful for resuming webhook monitoring after
+     * a shutdown or when loading an existing registry.
+     */
+    async start() {
+        if (this.rootUnsubscribe) {
+            return;
+        }
+        // TODO: this would be much more efficient with subscription diffs
+        const createAndDeleteSubscriptions = (registry) => {
+            for (const webhook of Object.values(registry)) {
+                const exists = this.activeSubscriptions.has(webhook.$jazz.id);
+                if (webhook.active && !exists) {
+                    this.subscribe(webhook);
+                }
+            }
+            for (const [id, unsubscribe] of this.activeSubscriptions.entries()) {
+                if (!registry[id]) {
+                    unsubscribe();
+                    this.activeSubscriptions.delete(id);
+                }
+            }
+        };
+        this.rootUnsubscribe = this.state.$jazz.subscribe({
+            resolve: {
+                $each: true,
+            },
+        }, createAndDeleteSubscriptions);
+    }
+    shutdown() {
+        for (const unsubscribe of this.activeSubscriptions.values()) {
+            unsubscribe();
+        }
+        this.rootUnsubscribe?.();
+        this.rootUnsubscribe = null;
+    }
+}
+class WebhookError extends Error {
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * Manages webhook emission with queuing, retry logic, and exponential backoff.
+ *
+ * The WebhookEmitter handles sending HTTP POST requests to webhook callbacks when
+ * a CoValue changes. It implements several key behaviors:
+ *
+ */
+class WebhookEmitter {
+    constructor(webhook, options = {}) {
+        this.webhook = webhook;
+        this.options = options;
+        this.pending = new Map();
+        const unsubscribeWebhook = this.webhook.$jazz.subscribe((webhook) => {
+            this.webhook = webhook;
+        });
+        const unsubscribeValue = this.webhook.$jazz.localNode.subscribe(this.webhook.coValueId, async (value) => {
+            if (value === "unavailable") {
+                return;
+            }
+            if (!this.webhook.active) {
+                return;
+            }
+            const todo = getTransactionsToTry(await this.loadSuccessMap(), value.core.knownState());
+            for (const txID of todo) {
+                if (!this.pending.has(getTxIdKey(txID))) {
+                    this.makeAttempt(txID);
+                }
+            }
+        });
+        this.unsubscribe = () => {
+            unsubscribeWebhook();
+            unsubscribeValue();
+        };
+    }
+    async loadSuccessMap() {
+        if (this.loadedSuccessMap) {
+            return this.loadedSuccessMap;
+        }
+        if (!this.successMap) {
+            this.successMap = this.webhook.$jazz
+                .ensureLoaded({ resolve: { successMap: true } })
+                .then((loaded) => loaded.successMap);
+        }
+        this.loadedSuccessMap = await this.successMap;
+        return this.loadedSuccessMap;
+    }
+    getRetryDelay(nRetries) {
+        const baseDelayMs = this.options.baseDelayMs || DEFAULT_JazzWebhookOptions.baseDelayMs;
+        return baseDelayMs * 2 ** nRetries;
+    }
+    getMaxRetries() {
+        return this.options.maxRetries || DEFAULT_JazzWebhookOptions.maxRetries;
+    }
+    stop() {
+        this.pending.forEach((entry) => {
+            clearTimeout(entry.timeout);
+        });
+        this.pending.clear();
+        this.unsubscribe();
+    }
+    makeAttempt(txID) {
+        const txIdKey = getTxIdKey(txID);
+        let entry = this.pending.get(txIdKey);
+        if (entry && entry.nRetries >= this.getMaxRetries()) {
+            // TODO: should we track failed transactions?
+            this.pending.delete(txIdKey);
+            clearTimeout(entry.timeout);
+            console.error(`Max retries reached for txID: ${txIdKey} on webhook: ${this.webhook.$jazz.id}`);
+            return;
+        }
+        if (entry) {
+            entry.nRetries++;
+            clearTimeout(entry.timeout);
+        }
+        else {
+            entry = { nRetries: 0 };
+            this.pending.set(txIdKey, entry);
+        }
+        const scheduleRetry = (delayMs) => {
+            const delay = delayMs ?? this.getRetryDelay(entry?.nRetries || 0);
+            entry.timeout = setTimeout(() => {
+                this.makeAttempt(txID);
+            }, delay);
+        };
+        fetch(this.webhook.webhookUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                coValueId: this.webhook.coValueId,
+                txID: txID,
+            }),
+        })
+            .then(async (response) => {
+            if (response.ok) {
+                const successMap = await this.loadSuccessMap();
+                markSuccessful(successMap, txID);
+                this.pending.delete(txIdKey);
+                clearTimeout(entry.timeout);
+                return;
+            }
+            let retryAfterMs;
+            if (response.headers.has("Retry-After")) {
+                try {
+                    retryAfterMs =
+                        parseFloat(response.headers.get("Retry-After")) * 1000;
+                }
+                catch {
+                    console.warn(`Invalid Retry-After header: ${response.headers.get("Retry-After")}`);
+                }
+            }
+            throw new WebhookError(`HTTP ${response.status}: ${response.statusText}`, retryAfterMs);
+        })
+            .catch((error) => {
+            scheduleRetry(error instanceof WebhookError ? error.retryAfterMs : undefined);
+        });
+    }
+}
+export const registerWebhook = async (options) => {
+    const { webhookUrl, coValueId, registryId } = {
+        registryId: process.env.JAZZ_WEBHOOK_REGISTRY_ID,
+        ...options,
+    };
+    if (!registryId) {
+        throw new Error("Invalid webhook secret");
+    }
+    try {
+        new URL(webhookUrl);
+    }
+    catch {
+        throw new Error(`Invalid webhook URL: ${webhookUrl}`);
+    }
+    if (!registryId.startsWith("co_z")) {
+        throw new Error(`Invalid Registry ID format: ${coValueId}. Expected format: co_z...`);
+    }
+    if (!coValueId.startsWith("co_z")) {
+        throw new Error(`Invalid CoValue ID format: ${coValueId}. Expected format: co_z...`);
+    }
+    const registry = await RegistryState.load(registryId);
+    if (!registry) {
+        throw new Error(`Couldn't load registry with ID ${registryId}`);
+    }
+    const registration = WebhookRegistration.create({
+        webhookUrl,
+        coValueId,
+        active: true,
+        successMap: SuccessMap.create({}, registry.$jazz.owner),
+    }, registry.$jazz.owner);
+    registry.$jazz.set(registration.$jazz.id, registration);
+    await Account.getMe().$jazz.waitForAllCoValuesSync();
+    return registration.$jazz.id;
+};
+//# sourceMappingURL=webhook.js.map

package/dist/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "jazz-webhook",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "license": "MIT",
+  "version": "0.18.28",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "cojson": "0.18.28",
+    "cojson-storage-sqlite": "0.18.28",
+    "cojson-transport-ws": "0.18.28",
+    "jazz-tools": "0.18.28"
+  },
+  "devDependencies": {
+    "@types/ws": "8.5.10",
+    "typescript": "5.6.2",
+    "vitest": "3.2.4"
+  },
+  "scripts": {
+    "format-and-lint": "biome check .",
+    "format-and-lint:fix": "biome check . --write",
+    "build": "rm -rf ./dist && tsc --sourceMap --outDir dist && chmod +x ./dist/index.js",
+    "test": "vitest --run --root ../../ --project jazz-webhook",
+    "dev": "tsc --watch --sourceMap --outDir dist",
+    "build-and-run": "pnpm turbo build && ./dist/index.js sync --in-memory"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./webhook.js";
+export * from "./types.js";

package/src/successMap.ts

@@ -0,0 +1,55 @@
+import { CojsonInternalTypes, SessionID } from "cojson";
+import { co, z } from "jazz-tools";
+
+export const SuccessMap = co.record(
+  z.string(), // stringified transaction ID
+  z.boolean(),
+);
+export type SuccessMap = co.loaded<typeof SuccessMap>;
+
+export type TxIdKey = `${SessionID}:${number}`;
+
+export function getTxIdKey(txID: {
+  sessionID: SessionID;
+  txIndex: number;
+}): TxIdKey {
+  return `${txID.sessionID}:${txID.txIndex}`;
+}
+
+export function markSuccessful(
+  successMap: SuccessMap,
+  txID: CojsonInternalTypes.TransactionID,
+) {
+  let success = successMap[getTxIdKey(txID)];
+  if (!success) {
+    successMap.$jazz.set(getTxIdKey(txID), true);
+  }
+}
+
+export function getTransactionsToTry(
+  successMap: SuccessMap,
+  knownState: CojsonInternalTypes.CoValueKnownState,
+) {
+  const result: CojsonInternalTypes.TransactionID[] = [];
+  // TODO: optimisation: we can likely avoid even constructing a CoMap view
+  // and just get/set raw transactions from the CoValueCore of SuccessMap
+  for (const [sessionID, knownTxCount] of Object.entries(knownState.sessions)) {
+    for (let txIndex = 0; txIndex < knownTxCount; txIndex++) {
+      if (!successMap[`${sessionID}:${txIndex}`]) {
+        result.push({
+          sessionID: sessionID as SessionID,
+          txIndex: txIndex,
+        });
+      }
+    }
+  }
+
+  return result;
+}
+
+export function isTxSuccessful(
+  successMap: SuccessMap,
+  txID: CojsonInternalTypes.TransactionID,
+) {
+  return successMap[getTxIdKey(txID)] ?? false;
+}

package/src/test/http-server.ts

@@ -0,0 +1,233 @@
+import { createServer, IncomingMessage, ServerResponse, Server } from "http";
+import { AddressInfo } from "net";
+import { EventEmitter } from "events";
+import { CojsonInternalTypes } from "cojson";
+
+export interface WebhookRequest {
+  coValueId: string;
+  txID: CojsonInternalTypes.TransactionID;
+  timestamp: number;
+}
+
+export interface WebhookResponse {
+  statusCode: number;
+  body?: string;
+  delay?: number;
+  headers?: Record<string, string>;
+}
+
+export class WebhookTestServer {
+  private server: Server;
+  private port: number = 0;
+  private url: string = "";
+  private responseIndex: number = 0;
+
+  public readonly requests: WebhookRequest[] = [];
+  public readonly responses: WebhookResponse[] = [];
+
+  constructor() {
+    this.server = createServer(this.handleRequest.bind(this));
+  }
+
+  listeners = new Set<() => void>();
+  addRequestListener(listener: () => void): void {
+    this.listeners.add(listener);
+  }
+  removeRequestListener(listener: () => void): void {
+    this.listeners.delete(listener);
+  }
+
+  emitRequest(): void {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+
+  private handleRequest(req: IncomingMessage, res: ServerResponse): void {
+    if (req.method === "POST" && req.url === "/webhook") {
+      let body = "";
+
+      req.on("data", (chunk) => {
+        body += chunk.toString();
+      });
+
+      req.on("end", async () => {
+        try {
+          const response = this.responses[this.responseIndex] || {
+            statusCode: 200,
+          };
+          this.responseIndex++;
+
+          // Add delay if specified
+          if (response.delay) {
+            await new Promise((resolve) => setTimeout(resolve, response.delay));
+          }
+
+          res.statusCode = response.statusCode;
+          res.setHeader("Content-Type", "application/json");
+          if (response.headers) {
+            for (const [key, value] of Object.entries(response.headers)) {
+              res.setHeader(key, value);
+            }
+          }
+          res.end(response.body || JSON.stringify({ received: true }));
+        } catch (error) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ error: "Invalid JSON" }));
+        }
+
+        const webhookData: WebhookRequest = JSON.parse(body);
+        this.requests.push(webhookData);
+
+        console.log("request " + this.requests.length, webhookData);
+
+        this.emitRequest();
+      });
+    } else {
+      res.statusCode = 404;
+      res.end("Not Found");
+    }
+  }
+
+  /**
+   * Starts the server on an available port
+   */
+  async start(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      this.server.listen(0, () => {
+        try {
+          const address = this.server.address() as AddressInfo;
+          this.port = address.port;
+          this.url = `http://localhost:${this.port}/webhook`;
+          resolve();
+        } catch (error) {
+          reject(error);
+        }
+      });
+
+      this.server.on("error", reject);
+    });
+  }
+
+  /**
+   * Stops the server
+   */
+  async close(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.server.close(() => {
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Resets all stored requests and responses
+   */
+  reset(): void {
+    this.requests.length = 0;
+    this.responses.length = 0;
+    this.responseIndex = 0;
+  }
+
+  /**
+   * Sets a response for a specific request index
+   */
+  setResponse(
+    index: number,
+    statusCode: number,
+    body?: string,
+    delay?: number,
+    headers?: Record<string, string>,
+  ): void {
+    this.responses[index] = { statusCode, body, delay, headers };
+  }
+
+  /**
+   * Waits for a specific number of requests to be received
+   */
+  async waitForRequests(
+    count: number,
+    timeout: number = 5000,
+  ): Promise<WebhookRequest[]> {
+    return new Promise<WebhookRequest[]>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.removeRequestListener(onRequest);
+        reject(
+          new Error(
+            `Timeout waiting for ${count} requests. Got ${this.requests.length}`,
+          ),
+        );
+      }, timeout);
+
+      const onRequest = () => {
+        if (this.requests.length >= count) {
+          clearTimeout(timer);
+          this.removeRequestListener(onRequest);
+          resolve(this.requests);
+        }
+      };
+
+      this.addRequestListener(onRequest);
+      onRequest();
+    });
+  }
+
+  /**
+   * Gets the server port
+   */
+  getPort(): number {
+    return this.port;
+  }
+
+  /**
+   * Gets the webhook URL
+   */
+  getUrl(): string {
+    return this.url;
+  }
+
+  /**
+   * Gets the number of requests received
+   */
+  getRequestCount(): number {
+    return this.requests.length;
+  }
+
+  expectSingleRequest(): WebhookRequest {
+    if (this.requests.length !== 1) {
+      throw new Error("Expected 1 request, got " + this.requests.length);
+    }
+
+    return this.getLastRequest();
+  }
+
+  /**
+   * Gets the last request received
+   */
+  getLastRequest(): WebhookRequest {
+    const lastRequest = this.requests.at(-1);
+    if (!lastRequest) {
+      throw new Error("No requests received");
+    }
+
+    return lastRequest;
+  }
+
+  /**
+   * Checks if the server is running
+   */
+  isRunning(): boolean {
+    return this.server.listening;
+  }
+}
+
+/**
+ * Factory function to create and start a webhook test server
+ * @deprecated Use WebhookTestServer class directly
+ */
+export async function createWebhookTestServer(): Promise<WebhookTestServer> {
+  const server = new WebhookTestServer();
+  await server.start();
+  return server;
+}

package/src/test/setup.ts

@@ -0,0 +1,12 @@
+import { beforeEach, afterEach } from "vitest";
+import { setupJazzTestSync } from "jazz-tools/testing";
+
+// Global test setup
+beforeEach(async () => {
+  await setupJazzTestSync();
+});
+
+// Clean up after each test
+afterEach(async () => {
+  // Clean up any global state if needed
+});