hybridq 0.1.1

package/README.md

@@ -0,0 +1,165 @@
+# hybridq
+
+A lightweight, **embedded hybrid background worker** for serverless. Run safe,
+batched, deferred tasks directly inside Vercel / Next.js / Cloudflare Workers /
+AWS Lambda — **no persistent worker server**. Incoming traffic ("hybrid
+triggers") drains the queue, with strict self-limiting budgets so you never blow
+past a function timeout.
+
+```bash
+pnpm add hybridq
+# optional drivers (pick one)
+pnpm add @upstash/redis   # edge / connectionless
+pnpm add ioredis          # node TCP
+```
+
+## How it works
+
+1. **Producers** call `queue.enqueue(payload)` from any API route.
+2. Jobs live in a **pluggable store** (`MemoryAdapter` for dev, `RedisAdapter`
+   for prod) — serverless is stateless, so the queue must be external.
+3. **Triggers** drain the queue: either piggy-backing on normal inbound requests
+   (`withTrigger`) or a dedicated authenticated endpoint (`createTriggerEndpoint`)
+   that your browser or a cron pings.
+4. Every run respects a **budget** (`maxJobsPerTrigger`, `maxExecutionTimeMs`,
+   optional `maxCpuBudgetPct`). When the budget is hit, unprocessed jobs are
+   released back and the function returns cleanly.
+
+Crash-safety is built in: claimed jobs hold a short **lease**; if the function
+dies mid-run, the lease lapses and the work is reclaimed — nothing is lost.
+
+## Quick start (local / dev)
+
+```ts
+import { defineQueue, MemoryAdapter } from "hybridq/server";
+
+const queue = defineQueue<{ to: string }>({
+  name: "emails",
+  adapter: new MemoryAdapter(),
+  budget: { maxJobsPerTrigger: 25, maxExecutionTimeMs: 8000 },
+});
+
+await queue.enqueue({ to: "user@example.com" });
+
+const report = await queue.process(async (job) => {
+  await sendEmail(job.payload.to);
+});
+// { processed, failed, released, stoppedBy, elapsedMs }
+```
+
+## Production (Upstash Redis + encryption + lock)
+
+```ts
+import { Redis } from "@upstash/redis";
+import {
+  defineQueue,
+  RedisAdapter,
+  fromUpstash,
+  RedisLock,
+  createPayloadCipher,
+} from "hybridq/server";
+
+const driver = fromUpstash(Redis.fromEnv());
+const cipher = createPayloadCipher(process.env.HYBRIDQ_ENC_KEY); // payload-at-rest
+
+export const queue = defineQueue<{ email: string }>({
+  name: "emails",
+  adapter: new RedisAdapter(driver, { cipher }),
+  lock: new RedisLock(driver), // single-flight: no double-processing
+  budget: { maxJobsPerTrigger: 50, maxExecutionTimeMs: 9000 },
+});
+```
+
+For `ioredis`, reuse one socket across invocations:
+
+```ts
+import IORedis from "ioredis";
+import { fromIORedis, getSharedIORedis } from "hybridq/server";
+
+const driver = getSharedIORedis(() =>
+  fromIORedis(new IORedis(process.env.REDIS_URL!)),
+);
+```
+
+## Hybrid trigger inside a Next.js route handler
+
+```ts
+// app/api/orders/route.ts
+import { withTrigger } from "hybridq/server";
+import { queue } from "@/lib/queue";
+
+export const POST = withTrigger(
+  async (req) => {
+    await queue.enqueue({ email: "buyer@example.com" });
+    return Response.json({ ok: true }); // user gets this immediately…
+  },
+  {
+    queue,
+    handler: async (job) => sendReceipt(job.payload.email),
+    // …draining happens AFTER the response, on the same warm function:
+    // ctx is Cloudflare's ExecutionContext; on Vercel pass `{ waitUntil }`.
+    skipIfEmpty: true,
+  },
+);
+```
+
+## Dedicated authenticated trigger endpoint
+
+```ts
+// app/api/_worker/route.ts
+import { createTriggerEndpoint } from "hybridq/server";
+import { queue } from "@/lib/queue";
+
+export const POST = createTriggerEndpoint({
+  queue,
+  handler: async (job) => sendReceipt(job.payload.email),
+  auth: {
+    secret: process.env.WORKER_SECRET,        // X-Worker-Trigger-Secret, or…
+    hmacSecret: process.env.WORKER_HMAC,       // short-lived signed tokens
+  },
+});
+```
+
+## Browser ambient triggers
+
+The browser never holds the worker secret. Mint a short-lived HMAC token on the
+server and inject it into the page; the client just forwards it.
+
+```ts
+// server: mint a token for the page
+import { signTrigger } from "hybridq/server";
+const token = signTrigger(process.env.WORKER_HMAC!, "/api/_worker");
+```
+
+```ts
+// client: ping on activity + during idle time, throttled
+import { startTriggerClient } from "hybridq/client";
+
+const trigger = startTriggerClient({
+  endpoint: "/api/_worker",
+  token,             // from the server-rendered page
+  throttleMs: 5000,
+  useIdleCallback: true,
+});
+// trigger.stop() on SPA unmount
+```
+
+## Security
+
+| Concern | Mechanism |
+| --- | --- |
+| Trigger abuse / DDoS | Pre-shared `X-Worker-Trigger-Secret` (constant-time compare) **or** replay-resistant HMAC tokens (`signTrigger`/`verifyTrigger`). |
+| Sensitive payloads in Redis | Optional AES-256-GCM `createPayloadCipher` — payloads are sealed before they touch the store. |
+| Duplicate processing | `RedisLock` (SET NX PX + compare-and-delete) gives single-flight drains; lease TTLs auto-recover crashes. |
+
+## API surface
+
+- `hybridq/server`: `defineQueue` / `Queue`, `MemoryAdapter`, `RedisAdapter`
+  (`fromUpstash`, `fromIORedis`, `getSharedIORedis`), `drain`, `RedisLock` /
+  `MemoryLock`, `withTrigger`, `createTriggerEndpoint`, `authorizeTrigger`,
+  `createPayloadCipher`, `signTrigger`, `verifyTrigger`, plus all types.
+- `hybridq/client`: `startTriggerClient`.
+
+## License
+
+MIT

package/dist/client/index.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+// src/client/trigger.ts
+var DEFAULT_EVENTS = ["click", "keydown", "visibilitychange"];
+function resolveToken(token) {
+  return typeof token === "function" ? token() : token;
+}
+function startTriggerClient(opts) {
+  const noop = { ping() {
+  }, stop() {
+  } };
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return noop;
+  }
+  const {
+    endpoint,
+    token,
+    throttleMs = 5e3,
+    events = DEFAULT_EVENTS,
+    useIdleCallback = true,
+    idleIntervalMs = 3e4,
+    pingOnHide = true
+  } = opts;
+  let lastPing = 0;
+  let stopped = false;
+  let idleTimer;
+  const send = (useBeacon) => {
+    const tok = resolveToken(token);
+    const headers = { "content-type": "text/plain" };
+    if (tok) headers["x-worker-trigger-token"] = tok;
+    if (useBeacon && !tok && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(endpoint);
+      return;
+    }
+    void fetch(endpoint, {
+      method: "POST",
+      headers,
+      // keepalive lets the request outlive a navigation.
+      keepalive: true,
+      credentials: "same-origin",
+      body: ""
+    }).catch(() => {
+    });
+  };
+  const ping = (useBeacon = false) => {
+    if (stopped) return;
+    const now = Date.now();
+    if (now - lastPing < throttleMs) return;
+    lastPing = now;
+    send(useBeacon);
+  };
+  const onEvent = () => {
+    if (document.visibilityState === "hidden") return;
+    ping(false);
+  };
+  for (const ev of events) {
+    document.addEventListener(ev, onEvent, { passive: true });
+  }
+  const onHide = () => {
+    if (pingOnHide && document.visibilityState === "hidden") {
+      lastPing = Date.now();
+      send(true);
+    }
+  };
+  if (pingOnHide) document.addEventListener("visibilitychange", onHide);
+  const ric = typeof requestIdleCallback === "function" ? requestIdleCallback : void 0;
+  const scheduleIdle = () => {
+    if (stopped || !useIdleCallback) return;
+    idleTimer = setTimeout(() => {
+      const run = () => {
+        if (document.visibilityState === "visible") ping(false);
+        scheduleIdle();
+      };
+      if (ric) ric(run, { timeout: 1e3 });
+      else run();
+    }, idleIntervalMs);
+  };
+  scheduleIdle();
+  return {
+    ping: () => ping(false),
+    stop: () => {
+      stopped = true;
+      for (const ev of events) document.removeEventListener(ev, onEvent);
+      if (pingOnHide) document.removeEventListener("visibilitychange", onHide);
+      if (idleTimer) clearTimeout(idleTimer);
+    }
+  };
+}
+
+exports.startTriggerClient = startTriggerClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/trigger.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Browser-side ambient trigger.\n *\n * Turns ordinary user activity into safe, throttled pings that nudge the\n * serverless worker to drain its queue. Strictly browser-only: no node\n * builtins, so it tree-shakes into a tiny client bundle.\n *\n * Security model: the browser NEVER holds the worker's real secret. Instead the\n * server mints a short-lived HMAC token (see server `signTrigger`) and injects\n * it into the page; the client just forwards it. Same-origin requests can also\n * rely on the session cookie, in which case no token is needed.\n */\n\nexport interface TriggerClientOptions {\n  /** Endpoint created with `createTriggerEndpoint` (e.g. \"/api/_worker\"). */\n  endpoint: string;\n  /**\n   * Short-lived signed token minted server-side and embedded in the page.\n   * Sent as `X-Worker-Trigger-Token`. Omit for cookie-authenticated endpoints.\n   */\n  token?: string | (() => string | undefined);\n  /** Minimum ms between pings regardless of activity. Default 5000. */\n  throttleMs?: number;\n  /** Fire on these DOM events. Default click + keydown + visibilitychange. */\n  events?: string[];\n  /** Also ping during browser idle time via requestIdleCallback. Default true. */\n  useIdleCallback?: boolean;\n  /** Idle poll cadence in ms when nothing else fires. Default 30000. */\n  idleIntervalMs?: number;\n  /** Send a final ping on page hide so tail jobs aren't stranded. Default true. */\n  pingOnHide?: boolean;\n}\n\nexport interface TriggerHandle {\n  /** Force a ping immediately (respects throttle). */\n  ping(): void;\n  /** Detach all listeners and stop idle polling. */\n  stop(): void;\n}\n\nconst DEFAULT_EVENTS = [\"click\", \"keydown\", \"visibilitychange\"];\n\nfunction resolveToken(\n  token: TriggerClientOptions[\"token\"],\n): string | undefined {\n  return typeof token === \"function\" ? token() : token;\n}\n\n/**\n * Start ambient triggering. Returns a handle to stop it (e.g. on SPA unmount).\n * No-ops gracefully in non-browser environments (SSR safe).\n */\nexport function startTriggerClient(\n  opts: TriggerClientOptions,\n): TriggerHandle {\n  const noop: TriggerHandle = { ping() {}, stop() {} };\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") {\n    return noop; // SSR / non-browser: do nothing.\n  }\n\n  const {\n    endpoint,\n    token,\n    throttleMs = 5000,\n    events = DEFAULT_EVENTS,\n    useIdleCallback = true,\n    idleIntervalMs = 30_000,\n    pingOnHide = true,\n  } = opts;\n\n  let lastPing = 0;\n  let stopped = false;\n  let idleTimer: ReturnType<typeof setTimeout> | undefined;\n\n  const send = (useBeacon: boolean): void => {\n    const tok = resolveToken(token);\n    const headers: Record<string, string> = { \"content-type\": \"text/plain\" };\n    if (tok) headers[\"x-worker-trigger-token\"] = tok;\n\n    // sendBeacon survives page unload but can't set headers; only use it on\n    // hide and when no token header is required (cookie-auth path).\n    if (useBeacon && !tok && typeof navigator.sendBeacon === \"function\") {\n      navigator.sendBeacon(endpoint);\n      return;\n    }\n\n    void fetch(endpoint, {\n      method: \"POST\",\n      headers,\n      // keepalive lets the request outlive a navigation.\n      keepalive: true,\n      credentials: \"same-origin\",\n      body: \"\",\n    }).catch(() => {\n      /* triggering is best-effort; ignore network errors */\n    });\n  };\n\n  const ping = (useBeacon = false): void => {\n    if (stopped) return;\n    const now = Date.now();\n    if (now - lastPing < throttleMs) return; // throttle\n    lastPing = now;\n    send(useBeacon);\n  };\n\n  const onEvent = (): void => {\n    if (document.visibilityState === \"hidden\") return; // handled by hide path\n    ping(false);\n  };\n\n  for (const ev of events) {\n    document.addEventListener(ev, onEvent, { passive: true });\n  }\n\n  const onHide = (): void => {\n    if (pingOnHide && document.visibilityState === \"hidden\") {\n      // Bypass throttle on hide: this is our last chance to flush.\n      lastPing = Date.now();\n      send(true);\n    }\n  };\n  if (pingOnHide) document.addEventListener(\"visibilitychange\", onHide);\n\n  // Idle loop: only pings when the tab is visible to avoid background spam.\n  const ric: typeof requestIdleCallback | undefined =\n    typeof requestIdleCallback === \"function\"\n      ? requestIdleCallback\n      : undefined;\n\n  const scheduleIdle = (): void => {\n    if (stopped || !useIdleCallback) return;\n    idleTimer = setTimeout(() => {\n      const run = () => {\n        if (document.visibilityState === \"visible\") ping(false);\n        scheduleIdle();\n      };\n      if (ric) ric(run, { timeout: 1000 });\n      else run();\n    }, idleIntervalMs);\n  };\n  scheduleIdle();\n\n  return {\n    ping: () => ping(false),\n    stop: () => {\n      stopped = true;\n      for (const ev of events) document.removeEventListener(ev, onEvent);\n      if (pingOnHide) document.removeEventListener(\"visibilitychange\", onHide);\n      if (idleTimer) clearTimeout(idleTimer);\n    },\n  };\n}\n"]}

package/dist/client/index.d.cts

@@ -0,0 +1,44 @@
+/**
+ * Browser-side ambient trigger.
+ *
+ * Turns ordinary user activity into safe, throttled pings that nudge the
+ * serverless worker to drain its queue. Strictly browser-only: no node
+ * builtins, so it tree-shakes into a tiny client bundle.
+ *
+ * Security model: the browser NEVER holds the worker's real secret. Instead the
+ * server mints a short-lived HMAC token (see server `signTrigger`) and injects
+ * it into the page; the client just forwards it. Same-origin requests can also
+ * rely on the session cookie, in which case no token is needed.
+ */
+interface TriggerClientOptions {
+    /** Endpoint created with `createTriggerEndpoint` (e.g. "/api/_worker"). */
+    endpoint: string;
+    /**
+     * Short-lived signed token minted server-side and embedded in the page.
+     * Sent as `X-Worker-Trigger-Token`. Omit for cookie-authenticated endpoints.
+     */
+    token?: string | (() => string | undefined);
+    /** Minimum ms between pings regardless of activity. Default 5000. */
+    throttleMs?: number;
+    /** Fire on these DOM events. Default click + keydown + visibilitychange. */
+    events?: string[];
+    /** Also ping during browser idle time via requestIdleCallback. Default true. */
+    useIdleCallback?: boolean;
+    /** Idle poll cadence in ms when nothing else fires. Default 30000. */
+    idleIntervalMs?: number;
+    /** Send a final ping on page hide so tail jobs aren't stranded. Default true. */
+    pingOnHide?: boolean;
+}
+interface TriggerHandle {
+    /** Force a ping immediately (respects throttle). */
+    ping(): void;
+    /** Detach all listeners and stop idle polling. */
+    stop(): void;
+}
+/**
+ * Start ambient triggering. Returns a handle to stop it (e.g. on SPA unmount).
+ * No-ops gracefully in non-browser environments (SSR safe).
+ */
+declare function startTriggerClient(opts: TriggerClientOptions): TriggerHandle;
+
+export { type TriggerClientOptions, type TriggerHandle, startTriggerClient };

package/dist/client/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Browser-side ambient trigger.
+ *
+ * Turns ordinary user activity into safe, throttled pings that nudge the
+ * serverless worker to drain its queue. Strictly browser-only: no node
+ * builtins, so it tree-shakes into a tiny client bundle.
+ *
+ * Security model: the browser NEVER holds the worker's real secret. Instead the
+ * server mints a short-lived HMAC token (see server `signTrigger`) and injects
+ * it into the page; the client just forwards it. Same-origin requests can also
+ * rely on the session cookie, in which case no token is needed.
+ */
+interface TriggerClientOptions {
+    /** Endpoint created with `createTriggerEndpoint` (e.g. "/api/_worker"). */
+    endpoint: string;
+    /**
+     * Short-lived signed token minted server-side and embedded in the page.
+     * Sent as `X-Worker-Trigger-Token`. Omit for cookie-authenticated endpoints.
+     */
+    token?: string | (() => string | undefined);
+    /** Minimum ms between pings regardless of activity. Default 5000. */
+    throttleMs?: number;
+    /** Fire on these DOM events. Default click + keydown + visibilitychange. */
+    events?: string[];
+    /** Also ping during browser idle time via requestIdleCallback. Default true. */
+    useIdleCallback?: boolean;
+    /** Idle poll cadence in ms when nothing else fires. Default 30000. */
+    idleIntervalMs?: number;
+    /** Send a final ping on page hide so tail jobs aren't stranded. Default true. */
+    pingOnHide?: boolean;
+}
+interface TriggerHandle {
+    /** Force a ping immediately (respects throttle). */
+    ping(): void;
+    /** Detach all listeners and stop idle polling. */
+    stop(): void;
+}
+/**
+ * Start ambient triggering. Returns a handle to stop it (e.g. on SPA unmount).
+ * No-ops gracefully in non-browser environments (SSR safe).
+ */
+declare function startTriggerClient(opts: TriggerClientOptions): TriggerHandle;
+
+export { type TriggerClientOptions, type TriggerHandle, startTriggerClient };

package/dist/client/index.js

@@ -0,0 +1,90 @@
+// src/client/trigger.ts
+var DEFAULT_EVENTS = ["click", "keydown", "visibilitychange"];
+function resolveToken(token) {
+  return typeof token === "function" ? token() : token;
+}
+function startTriggerClient(opts) {
+  const noop = { ping() {
+  }, stop() {
+  } };
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return noop;
+  }
+  const {
+    endpoint,
+    token,
+    throttleMs = 5e3,
+    events = DEFAULT_EVENTS,
+    useIdleCallback = true,
+    idleIntervalMs = 3e4,
+    pingOnHide = true
+  } = opts;
+  let lastPing = 0;
+  let stopped = false;
+  let idleTimer;
+  const send = (useBeacon) => {
+    const tok = resolveToken(token);
+    const headers = { "content-type": "text/plain" };
+    if (tok) headers["x-worker-trigger-token"] = tok;
+    if (useBeacon && !tok && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(endpoint);
+      return;
+    }
+    void fetch(endpoint, {
+      method: "POST",
+      headers,
+      // keepalive lets the request outlive a navigation.
+      keepalive: true,
+      credentials: "same-origin",
+      body: ""
+    }).catch(() => {
+    });
+  };
+  const ping = (useBeacon = false) => {
+    if (stopped) return;
+    const now = Date.now();
+    if (now - lastPing < throttleMs) return;
+    lastPing = now;
+    send(useBeacon);
+  };
+  const onEvent = () => {
+    if (document.visibilityState === "hidden") return;
+    ping(false);
+  };
+  for (const ev of events) {
+    document.addEventListener(ev, onEvent, { passive: true });
+  }
+  const onHide = () => {
+    if (pingOnHide && document.visibilityState === "hidden") {
+      lastPing = Date.now();
+      send(true);
+    }
+  };
+  if (pingOnHide) document.addEventListener("visibilitychange", onHide);
+  const ric = typeof requestIdleCallback === "function" ? requestIdleCallback : void 0;
+  const scheduleIdle = () => {
+    if (stopped || !useIdleCallback) return;
+    idleTimer = setTimeout(() => {
+      const run = () => {
+        if (document.visibilityState === "visible") ping(false);
+        scheduleIdle();
+      };
+      if (ric) ric(run, { timeout: 1e3 });
+      else run();
+    }, idleIntervalMs);
+  };
+  scheduleIdle();
+  return {
+    ping: () => ping(false),
+    stop: () => {
+      stopped = true;
+      for (const ev of events) document.removeEventListener(ev, onEvent);
+      if (pingOnHide) document.removeEventListener("visibilitychange", onHide);
+      if (idleTimer) clearTimeout(idleTimer);
+    }
+  };
+}
+
+export { startTriggerClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/trigger.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Browser-side ambient trigger.\n *\n * Turns ordinary user activity into safe, throttled pings that nudge the\n * serverless worker to drain its queue. Strictly browser-only: no node\n * builtins, so it tree-shakes into a tiny client bundle.\n *\n * Security model: the browser NEVER holds the worker's real secret. Instead the\n * server mints a short-lived HMAC token (see server `signTrigger`) and injects\n * it into the page; the client just forwards it. Same-origin requests can also\n * rely on the session cookie, in which case no token is needed.\n */\n\nexport interface TriggerClientOptions {\n  /** Endpoint created with `createTriggerEndpoint` (e.g. \"/api/_worker\"). */\n  endpoint: string;\n  /**\n   * Short-lived signed token minted server-side and embedded in the page.\n   * Sent as `X-Worker-Trigger-Token`. Omit for cookie-authenticated endpoints.\n   */\n  token?: string | (() => string | undefined);\n  /** Minimum ms between pings regardless of activity. Default 5000. */\n  throttleMs?: number;\n  /** Fire on these DOM events. Default click + keydown + visibilitychange. */\n  events?: string[];\n  /** Also ping during browser idle time via requestIdleCallback. Default true. */\n  useIdleCallback?: boolean;\n  /** Idle poll cadence in ms when nothing else fires. Default 30000. */\n  idleIntervalMs?: number;\n  /** Send a final ping on page hide so tail jobs aren't stranded. Default true. */\n  pingOnHide?: boolean;\n}\n\nexport interface TriggerHandle {\n  /** Force a ping immediately (respects throttle). */\n  ping(): void;\n  /** Detach all listeners and stop idle polling. */\n  stop(): void;\n}\n\nconst DEFAULT_EVENTS = [\"click\", \"keydown\", \"visibilitychange\"];\n\nfunction resolveToken(\n  token: TriggerClientOptions[\"token\"],\n): string | undefined {\n  return typeof token === \"function\" ? token() : token;\n}\n\n/**\n * Start ambient triggering. Returns a handle to stop it (e.g. on SPA unmount).\n * No-ops gracefully in non-browser environments (SSR safe).\n */\nexport function startTriggerClient(\n  opts: TriggerClientOptions,\n): TriggerHandle {\n  const noop: TriggerHandle = { ping() {}, stop() {} };\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") {\n    return noop; // SSR / non-browser: do nothing.\n  }\n\n  const {\n    endpoint,\n    token,\n    throttleMs = 5000,\n    events = DEFAULT_EVENTS,\n    useIdleCallback = true,\n    idleIntervalMs = 30_000,\n    pingOnHide = true,\n  } = opts;\n\n  let lastPing = 0;\n  let stopped = false;\n  let idleTimer: ReturnType<typeof setTimeout> | undefined;\n\n  const send = (useBeacon: boolean): void => {\n    const tok = resolveToken(token);\n    const headers: Record<string, string> = { \"content-type\": \"text/plain\" };\n    if (tok) headers[\"x-worker-trigger-token\"] = tok;\n\n    // sendBeacon survives page unload but can't set headers; only use it on\n    // hide and when no token header is required (cookie-auth path).\n    if (useBeacon && !tok && typeof navigator.sendBeacon === \"function\") {\n      navigator.sendBeacon(endpoint);\n      return;\n    }\n\n    void fetch(endpoint, {\n      method: \"POST\",\n      headers,\n      // keepalive lets the request outlive a navigation.\n      keepalive: true,\n      credentials: \"same-origin\",\n      body: \"\",\n    }).catch(() => {\n      /* triggering is best-effort; ignore network errors */\n    });\n  };\n\n  const ping = (useBeacon = false): void => {\n    if (stopped) return;\n    const now = Date.now();\n    if (now - lastPing < throttleMs) return; // throttle\n    lastPing = now;\n    send(useBeacon);\n  };\n\n  const onEvent = (): void => {\n    if (document.visibilityState === \"hidden\") return; // handled by hide path\n    ping(false);\n  };\n\n  for (const ev of events) {\n    document.addEventListener(ev, onEvent, { passive: true });\n  }\n\n  const onHide = (): void => {\n    if (pingOnHide && document.visibilityState === \"hidden\") {\n      // Bypass throttle on hide: this is our last chance to flush.\n      lastPing = Date.now();\n      send(true);\n    }\n  };\n  if (pingOnHide) document.addEventListener(\"visibilitychange\", onHide);\n\n  // Idle loop: only pings when the tab is visible to avoid background spam.\n  const ric: typeof requestIdleCallback | undefined =\n    typeof requestIdleCallback === \"function\"\n      ? requestIdleCallback\n      : undefined;\n\n  const scheduleIdle = (): void => {\n    if (stopped || !useIdleCallback) return;\n    idleTimer = setTimeout(() => {\n      const run = () => {\n        if (document.visibilityState === \"visible\") ping(false);\n        scheduleIdle();\n      };\n      if (ric) ric(run, { timeout: 1000 });\n      else run();\n    }, idleIntervalMs);\n  };\n  scheduleIdle();\n\n  return {\n    ping: () => ping(false),\n    stop: () => {\n      stopped = true;\n      for (const ev of events) document.removeEventListener(ev, onEvent);\n      if (pingOnHide) document.removeEventListener(\"visibilitychange\", onHide);\n      if (idleTimer) clearTimeout(idleTimer);\n    },\n  };\n}\n"]}