Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

7.8 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

import {
  CONTROLLED_ENVIRONMENT,
  POSTHOG_API_HOST,
  POSTHOG_PROJECT_PUBLIC_KEY
} from "@carbon/env";
import { getLogger } from "@carbon/logger";
import { async } from "@carbon/utils";
import {
  WORK_EVENT_MODULE,
  WORK_EVENT_RECORD_KEY,
  type WorkEventName,
  type WorkEvents
} from "./events";
import { workEventId } from "./idempotency";

const log = getLogger("lib", "telemetry");

/**
 * Server-side work-event capture.
 *
 * ## Why there is no SDK here
 *
 * `posthog-node` is not a dependency and does not need to be. Capture is a JSON
 * POST with an api_key, and the two things the SDK adds on top — batching and
 * retry — are the wrong shape for this: a work event is low-frequency, and a
 * retry without a stable id is how you double-count a released job. This mirrors
 * `packages/stripe/src/gtm-events.server.ts`, which POSTs product events to the
 * GTM endpoint the same way.
 *
 * ## Exactly-once
 *
 * Each event carries a `uuid` derived from (companyId, event, recordId,
 * discriminator) — see `./idempotency.ts`. PostHog's own de-duplication on that
 * field is eventual and documented as not guaranteed, so this id is what the
 * warehouse de-duplicates on downstream. Emitting the same occurrence twice is
 * therefore safe by construction, which is what lets every call site here be
 * fire-and-forget.
 *
 * ## When nothing is sent
 *
 * Both conditions mirror the browser SDK's own gate exactly — see
 * `apps/erp/app/entry.client.tsx:31`, `if (POSTHOG_PROJECT_PUBLIC_KEY &&
 * !CONTROLLED_ENVIRONMENT)`. Server capture must not be reachable anywhere the
 * browser's is not, or a deployment that believes it has analytics switched off
 * would start emitting business records.
 *
 * - No `POSTHOG_PROJECT_PUBLIC_KEY`. Self-hosted deployments set no PostHog
 *   variables at all, so they stay silent.
 * - `CONTROLLED_ENVIRONMENT` is on. An ITAR deployment ships nothing about a
 *   U.S.-Persons-only environment to a third-party vendor.
 */

/**
 * The capture endpoint.
 *
 * `/e/` rather than the documented `/i/v0/e/`, and string concatenation rather
 * than `new URL`, for the same reason: this is the exact host and path
 * `posthog-js` already ingests through, so it is the one combination proven
 * against whatever `POSTHOG_API_HOST` is actually set to in production. Two
 * traps this avoids —
 *
 * - `new URL("/i/v0/e/", host)` silently discards any base path, so a host of
 *   `https://proxy.example.com/ingest` would resolve to
 *   `https://proxy.example.com/i/v0/e/` and 404.
 * - `/i/v0/e/` is documented against the ingestion host (`us.i.posthog.com`),
 *   while `.env.example:23` carries the app host (`us.posthog.com`).
 *
 * Either mistake loses every event silently: capture never throws, so the only
 * trace would be a log line. Getting this wrong is the single largest risk in
 * the whole path, which is why it copies a proven value instead of a documented
 * one.
 */
function captureUrl(): string {
  return `${(POSTHOG_API_HOST ?? "").replace(/\/+$/, "")}/e/`;
}

/** Abandon a capture rather than hold a request open behind it. */
const TIMEOUT_MS = 3_000;

export type CaptureResult =
  | { sent: true; eventId: string }
  | { sent: false; reason: "disabled" | "controlled_environment" | "failed" };

function isEnabled(): CaptureResult | null {
  // The host is as load-bearing as the key: without it the URL below would be
  // a bare "/e/", which fetch rejects. Treat it as not configured rather than
  // as an error on every write.
  if (!POSTHOG_PROJECT_PUBLIC_KEY || !POSTHOG_API_HOST)
    return { sent: false, reason: "disabled" };
  if (CONTROLLED_ENVIRONMENT)
    return { sent: false, reason: "controlled_environment" };
  return null;
}

/**
 * Record that a piece of work happened.
 *
 * Never throws and never rejects: a failed capture must not fail the action that
 * produced it. Callers may leave the promise unawaited.
 *
 * @param event   the work that happened
 * @param payload its properties — ids, enums, counts and quantities only
 * @param options `discriminator` distinguishes repeat work on one record, so a
 *                second production quantity against the same operation is not
 *                mistaken for a retry of the first
 */
export async function captureWorkEvent<E extends WorkEventName>(
  event: E,
  payload: WorkEvents[E],
  options?: { discriminator?: string | number | null }
): Promise<CaptureResult> {
  try {
    const disabled = isEnabled();
    if (disabled) return disabled;

    const { companyId, userId, ...properties } = payload;

    const recordId = String(
      (payload as Record<string, unknown>)[
        WORK_EVENT_RECORD_KEY[event] as string
      ] ?? ""
    );

    const eventId = workEventId({
      event,
      companyId,
      recordId,
      discriminator: options?.discriminator
    });

    // PostHog warns against a shared "backend" distinct_id: it rate-limits the
    // stream and bills every event as identified. A company-scoped id with
    // person processing off is their recommended shape for actorless events.
    // https://posthog.com/docs/product-analytics/identity-resolution
    const anonymous = !userId;

    const body = {
      api_key: POSTHOG_PROJECT_PUBLIC_KEY,
      event,
      // The browser calls posthog.identify(userId), so a server event keyed on
      // the same id lands on the same person with no merge.
      distinct_id: userId ?? `company:${companyId}`,
      uuid: eventId,
      timestamp: new Date().toISOString(),
      properties: {
        ...properties,
        companyId,
        module: WORK_EVENT_MODULE[event],
        /** Marks the row as a business fact rather than browser telemetry. */
        work_event: true,
        /** Attribution to the company group; does not create the group. */
        $groups: { company: companyId },
        ...(anonymous ? { $process_person_profile: false } : {})
      }
    };

    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);

    try {
      const res = await fetch(captureUrl(), {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(body),
        signal: controller.signal
      });

      if (!res.ok) {
        const text = await res.text().catch(() => "");
        log.error("work event rejected", {
          event,
          status: res.status,
          body: text.slice(0, 500)
        });
        return { sent: false, reason: "failed" };
      }

      return { sent: true, eventId };
    } finally {
      clearTimeout(timer);
    }
  } catch (err) {
    // Includes the abort. A lost measurement beats a failed action.
    log.error("work event failed", { event, err });
    return { sent: false, reason: "failed" };
  }
}

/**
 * Fire-and-forget form, for call sites that should not await telemetry.
 *
 * Prefer this everywhere in a request path. The capture runs as background
 * work (`async.background`), which the apps hand to Vercel's `waitUntil`
 * (`async.onBackground` in `entry.server.tsx`): a bare unawaited fetch froze
 * with the instance and finished, or was lost, a request later.
 */
export function trackWorkEvent<E extends WorkEventName>(
  event: E,
  payload: WorkEvents[E],
  options?: { discriminator?: string | number | null }
): void {
  async.background(
    () => captureWorkEvent(event, payload, options),
    (error) => log.error("work event failed", { event, error })
  );
}

export type {
  JobSource,
  WorkEventName,
  WorkEvents,
  WorkModule,
  WorkSource
} from "./events";
export {
  asJobSource,
  JOB_SOURCES,
  WORK_EVENT_MODULE,
  WORK_EVENT_NAMES
} from "./events";
export { workEventId } from "./idempotency";