@claxedo/workspace-relay 0.6.0 → 0.7.0

package/dist/main.d.ts

@@ -4,48 +4,68 @@ import { type RelayHostPublicKey, type RevocationLookup, type WorkspaceRelayTarg
 import type { RelayKey } from "./auth";
 export { createCachedRevocationClient, createCachedTargetClient } from "./server";
 /**
- * D12 observability: Sentry on the relay (ops floor ADR
- * docs/plans/2026-07-11-016-wp-ops-floor-design.md §4).
+ * W2c (2026-07-28-001): PostHog is the relay's error sink — one vendor
+ * carries error tracking for every runtime behind one distinct_id space.
  *
- * Gated on `CLAXEDO_RELAY_SENTRY_DSN` (the relay's OWN DSN env — separate
- * Sentry project from the control plane). Absent DSN → `Sentry.init` is never
- * called: zero SDK overhead, zero network — the documented no-op posture, safe
- * before the Sentry account exists. Release = git SHA passed by the D11
- * deploy workflow (`CLAXEDO_RELEASE`; `GIT_SHA` accepted as alias); events are
- * tagged unit=relay + deployment_mode (absent → "self-host", mirroring D9's
- * default). Tracing stays off (ADR: it is where Sentry gets expensive).
+ * Sending requires two independent opt-ins: `CLAXEDO_TELEMETRY_MODE=on` AND
+ * `CLAXEDO_POSTHOG_KEY` (`POSTHOG_KEY` accepted as a fallback — the same
+ * unprefixed name claxedo-server's posthog.ts already reads). Any other
+ * combination → no `PostHog` client is ever constructed: zero SDK overhead,
+ * zero network — a clean no-op safe to ship before the telemetry account
+ * exists. Host defaults to `https://us.i.posthog.com` (the canonical ingest
+ * host — NOT the legacy `app.posthog.com` default some SDKs ship). Release =
+ * git SHA passed by the D11 deploy workflow (`CLAXEDO_RELEASE`; `GIT_SHA`
+ * accepted as alias); captures are tagged unit=relay + deployment_mode
+ * (absent → "self-host", mirroring D9's default).
  *
- * The relay is a Bun process (`Bun.serve`), so this uses `@sentry/bun` —
- * Sentry's Bun-native SDK with the same init-gated pattern as @sentry/node
- * (https://docs.sentry.io/platforms/javascript/guides/bun/).
+ * `posthog-node` runs fine on Bun (`Bun.serve`), unlike the Cloudflare
+ * Worker, which keeps it off its import graph entirely (see worker.ts).
  */
 export type RelayObservabilityEnv = {
-    CLAXEDO_RELAY_SENTRY_DSN?: string | undefined;
+    /** Only `on` permits sending, matched case-insensitively after trimming. */
+    CLAXEDO_TELEMETRY_MODE?: string | undefined;
+    CLAXEDO_POSTHOG_KEY?: string | undefined;
+    POSTHOG_KEY?: string | undefined;
+    CLAXEDO_POSTHOG_HOST?: string | undefined;
     CLAXEDO_RELEASE?: string | undefined;
     GIT_SHA?: string | undefined;
     CLAXEDO_DEPLOYMENT_MODE?: string | undefined;
     /** Accept process.env verbatim (extra keys are ignored). */
     [key: string]: string | undefined;
 };
-export type RelaySentryOptions = {
-    dsn: string;
+export type RelayTelemetryOptions = {
+    key: string;
+    host: string;
     release?: string;
-    tracesSampleRate: 0;
-    initialScope: {
-        tags: {
-            unit: "relay";
-            deployment_mode: string;
-        };
+    tags: {
+        unit: "relay";
+        deployment_mode: string;
     };
 };
 /**
- * Pure env → Sentry options resolver. `undefined` = DSN absent = do NOT init
- * (no client, no network). Exported for tests.
+ * Pure env → PostHog options resolver. `undefined` = do NOT construct a client
+ * (no client, no network), which is the answer unless BOTH opt-ins are
+ * present. The mode is read before the key so that a deployment which has not
+ * said `on` stays silent no matter which keys reach its environment.
+ * Exported for tests.
  */
-export declare function relaySentryOptions(env: RelayObservabilityEnv): RelaySentryOptions | undefined;
+export declare function relayTelemetryOptions(env: RelayObservabilityEnv): RelayTelemetryOptions | undefined;
 export declare function initRelayObservability(env?: RelayObservabilityEnv): {
     enabled: boolean;
 };
+/**
+ * Capture-and-flush used by the fatal handlers and the startup catch. With no
+ * initialized client (key absent) this is a documented no-op. Never throws —
+ * observability must not preempt the exit path.
+ *
+ * `distinctId: "system"` mirrors the ops-plane convention: process-fatal
+ * events carry no user identity. `client.flush()` has no built-in timeout,
+ * so it races a 2s timer; the flush promise's
+ * rejection is swallowed even when the timer wins the race, so a slow network
+ * failure that resolves after the timeout never surfaces as a second
+ * unhandledRejection mid-shutdown.
+ */
+export declare function reportFatal(error: unknown): Promise<void>;
 /**
  * Production fail-closed gate for the relay → claxedo-server resolver channel.
  *
@@ -212,9 +232,9 @@ export type FatalProcessHandlerOptions = {
     log?: (message: string) => void;
     register?: boolean;
     /**
-     * D12: error-tracker hook, invoked (and awaited) before teardown so a fatal
-     * crash reaches Sentry before the process exits. Failures are logged and
-     * never block the exit path. Defaults to none (tests, DSN-absent runs).
+     * W2c: error-tracker hook, invoked (and awaited) before teardown so a fatal
+     * crash reaches PostHog before the process exits. Failures are logged and
+     * never block the exit path. Defaults to none (tests, key-absent runs).
      */
     report?: (error: unknown, source: "uncaughtException" | "unhandledRejection") => void | Promise<void>;
     stopServer?: () => Promise<void> | void;