@warpgogol/werkstatt-shared 0.2.0

package/src/integration-adapter-supabase-crm/tests/stage-map.test.ts

@@ -0,0 +1,80 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for resolvePipedriveStageUpdate: verifies every BUFFER_DEAL_STAGES entry
+produces the correct Pipedrive payload fragment, and that won/lost use the `status` field
+rather than a stage_id. Acts as regression guard against catalog/STAGE_MAP desync.</purpose>
+<responsibilities>
+  <item>Every active stage maps to { stage_id: number }.</item>
+  <item>won maps to { status: "won" } — no stage_id.</item>
+  <item>lost maps to { status: "lost" } — no stage_id.</item>
+  <item>No stage falls back to { stage_id: 1 } (new) silently.</item>
+</responsibilities>
+<non-goals><item>No network — pure function tests.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>Initial regression guard for won/lost Pipedrive stage mapping fix.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { BUFFER_DEAL_STAGES } from "@warpgogol/werkstatt-shared/integration/crm-buffer";
+import type { BufferDealStage } from "@warpgogol/werkstatt-shared/integration/crm-buffer";
+import { STAGE_MAP, resolvePipedriveStageUpdate } from "../pipedrive-sync-target.ts";
+
+// ---------------------------------------------------------------------------
+// Exhaustiveness: every BUFFER_DEAL_STAGES entry must be a key of STAGE_MAP
+// ---------------------------------------------------------------------------
+
+test("STAGE_MAP covers every BUFFER_DEAL_STAGES entry (exhaustiveness guard)", () => {
+  for (const stage of BUFFER_DEAL_STAGES) {
+    expect(Object.prototype.hasOwnProperty.call(STAGE_MAP, stage)).toBeTruthy();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// won / lost must use Pipedrive status, never stage_id
+// ---------------------------------------------------------------------------
+
+test("won resolves to { status: 'won' } (not a stage_id)", () => {
+  const result = resolvePipedriveStageUpdate("won");
+  expect(!("stage_id" in result)).toBeTruthy();
+  expect(result).toEqual({ status: "won" });
+});
+
+test("lost resolves to { status: 'lost' } (not a stage_id)", () => {
+  const result = resolvePipedriveStageUpdate("lost");
+  expect(!("stage_id" in result)).toBeTruthy();
+  expect(result).toEqual({ status: "lost" });
+});
+
+// ---------------------------------------------------------------------------
+// Active stages must produce stage_id, not status, and never fall back to 1
+// ---------------------------------------------------------------------------
+
+const ACTIVE_STAGES: Array<{ stage: BufferDealStage; expectedId: number }> = [
+  { stage: "new", expectedId: 1 },
+  { stage: "contacted", expectedId: 2 },
+  { stage: "qualified", expectedId: 3 },
+  { stage: "proposal", expectedId: 4 },
+  { stage: "negotiation", expectedId: 5 },
+];
+
+for (const { stage, expectedId } of ACTIVE_STAGES) {
+  test(`"${stage}" resolves to { stage_id: ${expectedId} }`, () => {
+    const result = resolvePipedriveStageUpdate(stage);
+    expect("stage_id" in result).toBeTruthy();
+    expect(result).toEqual({ stage_id: expectedId });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Old typo spellings must NOT silently succeed with stage_id 1
+// ---------------------------------------------------------------------------
+
+test("closed_won (old typo) does not map to stage_id 1 (new)", () => {
+  const result = resolvePipedriveStageUpdate("closed_won");
+  // Falls back to STAGE_MAP.new = 1 since it's not in catalog.
+  // This test documents the fallback behavior and ensures "won" (correct) is used instead.
+  // The real bug was using "closed_won" as the key — this test guards the fix.
+  if ("stage_id" in result) {
+    expect(result.stage_id).toBe(1);
+  }
+});

package/src/integration-adapter-supabase-crm/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});

package/src/integration-adapter-supabase-crm/worker.ts

@@ -0,0 +1,223 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0186: Shared Lagebild sync worker (multi-tenant). Reads enabled tenants from
+sync_tenants registry, resolves their secret references from Worker env, and processes each
+tenant's pending sync_outbox rows with isolation: per-tenant batch size, concurrency, and circuit
+breaker. One Worker serves all clients; tenant lifecycle is data-driven.</purpose>
+<non-goals>
+  <item>Do not store or transmit secret values other than to destination APIs.</item>
+  <item>Do not process tenants with missing secret references.</item>
+  <item>Do not mix tenant data (strict RLS via tenant_id).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0186: Refactored from single-tenant factory to multi-tenant shared worker.</item>
+  <item>Extracted Pipedrive sync logic behind CrmSyncTarget port — worker is now a thin orchestrator.</item>
+  <item>RFC-0386: Added upsert_subscription / upsert_invoice dispatch and P3/P4 stage-map pass-through.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ScheduledEvent, ExecutionContext } from "@cloudflare/workers-types";
+import { createSupabaseCrmBufferClient } from "./client.ts";
+import type {
+  CrmBufferReader,
+  SyncOutboxRow,
+} from "@warpgogol/werkstatt-shared/integration/crm-buffer";
+import { createSyncTarget, type CrmSyncTarget } from "./pipedrive-sync-target.ts";
+import {
+  type SyncTenant,
+  type TenantWithSecrets,
+  resolveTenantSecrets,
+  getEnabledTenants,
+  updateTenantHealth,
+  type RegistryClient,
+} from "./tenant-registry.ts";
+import { createMetricsPusher } from "@warpgogol/werkstatt-shared/observability";
+
+/** RFC-0186: Shared Worker env bindings. Includes registry connection + tenant secrets namespace. */
+export interface LagebildSharedWorkerEnv {
+  // Registry (same Supabase project as buffer)
+  LAGEBILD_REGISTRY_URL: string;
+  LAGEBILD_REGISTRY_API_KEY: string;
+  // Optional: override default cron group
+  LAGEBILD_CRON_GROUP?: string;
+  // RFC-0807: OTLP metrics push
+  WARPGOGOL_OTLP_ENDPOINT: string;
+  WARPGOGOL_OTLP_TOKEN: string;
+  // Tenant secrets are resolved dynamically via sync_tenants.secret_ref fields
+  // Pattern: TENANT_{SITE_NAME}_{KIND} injected by wrangler secret put
+  [key: string]: string | undefined;
+}
+
+/** RFC-0186: Factory returning the shared multi-tenant scheduled handler. */
+export function createLagebildSharedSyncWorker() {
+  return {
+    async scheduled(
+      _event: ScheduledEvent,
+      env: LagebildSharedWorkerEnv,
+      _ctx: ExecutionContext,
+    ): Promise<void> {
+      const pusher = createMetricsPusher(
+        { serviceName: "lagebild-sync", layer: "back", environment: "production" },
+        { endpoint: env.WARPGOGOL_OTLP_ENDPOINT, token: env.WARPGOGOL_OTLP_TOKEN },
+      );
+
+      const registry: RegistryClient = {
+        url: env.LAGEBILD_REGISTRY_URL,
+        apiKey: env.LAGEBILD_REGISTRY_API_KEY,
+      };
+
+      const cronGroup = env.LAGEBILD_CRON_GROUP ?? "default";
+      let tenants: SyncTenant[];
+      try {
+        tenants = await getEnabledTenants(registry, cronGroup);
+      } catch (err) {
+        console.error("[lagebild] failed to load tenants:", (err as Error).message);
+        if (pusher) {
+          pusher.gaugeSet("warpgogol_back_up", 0, { service: "lagebild-sync" });
+          pusher.counterAdd("warpgogol_back_last_run_total", 1, {
+            service: "lagebild-sync",
+            status: "failure",
+          });
+          pusher.counterAdd("warpgogol_back_last_error_total", 1, { service: "lagebild-sync" });
+          await pusher.flush();
+        }
+        return;
+      }
+
+      if (tenants.length === 0) {
+        console.log("[lagebild] no enabled tenants");
+        if (pusher) {
+          pusher.gaugeSet("warpgogol_back_up", 1, { service: "lagebild-sync" });
+          pusher.counterAdd("warpgogol_back_last_run_total", 1, {
+            service: "lagebild-sync",
+            status: "success",
+          });
+          await pusher.flush();
+        }
+        return;
+      }
+
+      console.log(`[lagebild] processing ${tenants.length} tenants`);
+
+      let hadError = false;
+
+      for (const tenant of tenants) {
+        const resolved = resolveTenantSecrets(tenant, env);
+        if (resolved.secrets === null) {
+          const msg = `missing secrets: ${resolved.missing.join(", ")}`;
+          console.warn(`[lagebild][${tenant.site_name}] ${msg}`);
+          await updateTenantHealth(registry, tenant.tenant_id, {
+            last_seen_at: new Date().toISOString(),
+            last_error_at: new Date().toISOString(),
+            last_error: msg,
+          });
+          continue;
+        }
+
+        try {
+          await processTenant(tenant, resolved, registry);
+          await updateTenantHealth(registry, tenant.tenant_id, {
+            last_seen_at: new Date().toISOString(),
+            last_success_at: new Date().toISOString(),
+            last_error: null,
+          });
+        } catch (err) {
+          hadError = true;
+          const msg = (err as Error).message;
+          console.error(`[lagebild][${tenant.site_name}] tenant failed:`, msg);
+          await updateTenantHealth(registry, tenant.tenant_id, {
+            last_seen_at: new Date().toISOString(),
+            last_error_at: new Date().toISOString(),
+            last_error: msg,
+          });
+        }
+      }
+
+      if (pusher) {
+        pusher.gaugeSet("warpgogol_back_up", hadError ? 0 : 1, { service: "lagebild-sync" });
+        pusher.counterAdd("warpgogol_back_last_run_total", 1, {
+          service: "lagebild-sync",
+          status: hadError ? "failure" : "success",
+        });
+        if (hadError) {
+          pusher.counterAdd("warpgogol_back_last_error_total", 1, { service: "lagebild-sync" });
+        }
+        await pusher.flush();
+      }
+    },
+  };
+}
+
+/** RFC-0186: Process one tenant's outbox with per-tenant limits. */
+async function processTenant(
+  tenant: SyncTenant,
+  resolved: TenantWithSecrets,
+  _registry: RegistryClient,
+): Promise<void> {
+  const secrets = resolved.secrets!; // null checked by caller
+
+  const client = createSupabaseCrmBufferClient({
+    url: secrets.supabase_url,
+    serviceKey: secrets.supabase_service_key,
+    tenantId: tenant.tenant_id,
+  });
+
+  const target = createSyncTarget(tenant.destination_vendor, {
+    destination_token: secrets.destination_token,
+    destination_domain: secrets.destination_domain,
+    p3StageMap: secrets.p3StageMap,
+    p4StageMap: secrets.p4StageMap,
+  });
+
+  const tasks = await client.readPendingOutbox(tenant.tenant_id, tenant.batch_size);
+  if (tasks.length === 0) return;
+
+  console.log(`[lagebild][${tenant.site_name}] ${tasks.length} tasks`);
+
+  let consecutiveErrors = 0;
+  const threshold = tenant.circuit_breaker_threshold;
+
+  // Simple semaphore for max_concurrency (1 = sequential)
+  for (const task of tasks) {
+    if (consecutiveErrors >= threshold) {
+      console.warn(`[lagebild][${tenant.site_name}] circuit open`);
+      break;
+    }
+
+    try {
+      await processTask(task, client, target);
+      consecutiveErrors = 0;
+      await client.updateOutboxStatus(task.id, "done");
+    } catch (err) {
+      consecutiveErrors++;
+      const msg = (err as Error).message;
+      console.error(`[lagebild][${tenant.site_name}] task ${task.id} failed:`, msg);
+      await client.updateOutboxStatus(task.id, "failed");
+    }
+  }
+}
+
+/** Route task to the sync target by operation. */
+async function processTask(
+  task: SyncOutboxRow,
+  buffer: CrmBufferReader,
+  target: CrmSyncTarget,
+): Promise<void> {
+  switch (task.op) {
+    case "upsert_contact":
+      return target.syncContact(task, buffer);
+    case "upsert_organization":
+      return target.syncOrganization(task, buffer);
+    case "upsert_deal":
+      return target.syncDeal(task, buffer);
+    case "update_deal_stage":
+      return target.syncDealStage(task, buffer);
+    case "upsert_subscription":
+      return target.syncSubscription(task, buffer);
+    case "upsert_invoice":
+      return target.syncInvoice(task, buffer);
+    default:
+      throw new Error(`unknown op: ${(task as { op: string }).op}`);
+  }
+}

package/src/observability/conventions.ts

@@ -0,0 +1,93 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Closed telemetry vocabularies and OTLP resource-attribute builder for the Warpgogol observability port (RFC-0337).</purpose>
+<non-goals>
+  <item>Do not import node: modules — must be Workers-compatible.</item>
+  <item>Do not define metric specs — those live in metric-registry.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0337: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type WarpgogolLayer = "site" | "back" | "factory" | "probe" | "delivery";
+export type WarpgogolEnvironment = "production" | "preview" | "development" | "ci";
+
+export const WARPGOGOL_LAYERS: readonly WarpgogolLayer[] = [
+  "site",
+  "back",
+  "factory",
+  "probe",
+  "delivery",
+];
+
+export const WARPGOGOL_ENVIRONMENTS: readonly WarpgogolEnvironment[] = [
+  "production",
+  "preview",
+  "development",
+  "ci",
+];
+
+export interface WarpgogolResourceInput {
+  serviceName: string;
+  layer: WarpgogolLayer;
+  environment?: WarpgogolEnvironment;
+  siteId?: string;
+  serviceVersion?: string;
+}
+
+export const OTLP_ENDPOINT_ENV = "WARPGOGOL_OTLP_ENDPOINT";
+export const OTLP_TOKEN_ENV = "WARPGOGOL_OTLP_TOKEN";
+
+export interface OtlpKeyValue {
+  key: string;
+  value: { stringValue: string };
+}
+
+const LAYERS_REQUIRING_SITE_ID: ReadonlySet<WarpgogolLayer> = new Set([
+  "site",
+  "probe",
+  "delivery",
+]);
+
+export function buildResourceAttributes(input: WarpgogolResourceInput): OtlpKeyValue[] {
+  if (!input.serviceName) {
+    throw new Error("[observability] serviceName is required");
+  }
+  if (!WARPGOGOL_LAYERS.includes(input.layer)) {
+    throw new Error(
+      `[observability] layer "${input.layer}" is not in the closed vocabulary ${WARPGOGOL_LAYERS.join(" | ")}`,
+    );
+  }
+  const env = input.environment;
+  if (env !== undefined && !WARPGOGOL_ENVIRONMENTS.includes(env)) {
+    throw new Error(
+      `[observability] environment "${env}" is not in the closed vocabulary ${WARPGOGOL_ENVIRONMENTS.join(" | ")}`,
+    );
+  }
+  if (input.siteId === undefined && LAYERS_REQUIRING_SITE_ID.has(input.layer)) {
+    throw new Error(`[observability] siteId is required for layer "${input.layer}"`);
+  }
+
+  const attrs: OtlpKeyValue[] = [
+    { key: "service.name", value: { stringValue: input.serviceName } },
+    {
+      key: "deployment.environment",
+      value: { stringValue: input.environment ?? "development" },
+    },
+    { key: "warpgogol.layer", value: { stringValue: input.layer } },
+  ];
+
+  if (input.siteId !== undefined) {
+    attrs.push({ key: "warpgogol.site_id", value: { stringValue: input.siteId } });
+  }
+  if (input.serviceVersion !== undefined) {
+    attrs.push({
+      key: "service.version",
+      value: { stringValue: input.serviceVersion },
+    });
+  }
+
+  return attrs;
+}

package/src/observability/env-resolver.ts

@@ -0,0 +1,57 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  Environment resolver for observability — extracts OTLP endpoint/token
+  and deployment environment from a MetricsPusherEnv or global process.env.
+  Extracted from pusher.ts for testability and reuse.
+</purpose>
+<non-goals>
+  <item>Do not import node: modules — must be Workers-compatible.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Architecture review 2026-07-14: extract env resolution from pusher.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { WarpgogolEnvironment } from "./conventions.ts";
+
+export interface MetricsPusherEnv {
+  endpoint?: string;
+  token?: string;
+}
+
+interface ProcessEnvLike {
+  env?: Record<string, string | undefined>;
+}
+
+function getGlobalProcess(): ProcessEnvLike | undefined {
+  if (typeof globalThis === "undefined") return undefined;
+  const g = globalThis as Record<string, unknown>;
+  return typeof g["process"] === "object" && g["process"] !== null
+    ? (g["process"] as ProcessEnvLike)
+    : undefined;
+}
+
+export function resolvePusherEnv(env?: MetricsPusherEnv): { endpoint?: string; token?: string } {
+  if (env) return env;
+  const proc = getGlobalProcess();
+  if (proc?.env) {
+    return {
+      endpoint: proc.env["WARPGOGOL_OTLP_ENDPOINT"],
+      token: proc.env["WARPGOGOL_OTLP_TOKEN"],
+    };
+  }
+  return {};
+}
+
+export function detectEnvironment(): WarpgogolEnvironment {
+  const proc = getGlobalProcess();
+  const raw = proc?.env
+    ? (proc.env["WARPGOGOL_DEPLOYMENT_ENV"] ?? proc.env["NODE_ENV"])
+    : undefined;
+  if (raw === "production") return "production";
+  if (raw === "preview") return "preview";
+  if (raw === "ci") return "ci";
+  return "development";
+}

package/src/observability/index.ts

@@ -0,0 +1,57 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for @warpgogol/werkstatt-shared/observability — the observability port package (RFC-0337).</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0337: initial implementation.</item>
+  <item>Deepening: extract convertAccumulatedToOtlp pure function, add METRIC_REFS typed references, remove speculative exports.</item>
+</CHANGE_SUMMARY>
+*/
+
+export {
+  buildResourceAttributes,
+  OTLP_ENDPOINT_ENV,
+  OTLP_TOKEN_ENV,
+  WARPGOGOL_ENVIRONMENTS,
+  WARPGOGOL_LAYERS,
+  type OtlpKeyValue,
+  type WarpgogolEnvironment,
+  type WarpgogolLayer,
+  type WarpgogolResourceInput,
+} from "./conventions.ts";
+
+export {
+  findMetricSpec,
+  isLabelKeyForbidden,
+  isMetricNameValid,
+  FORBIDDEN_LABEL_KEYS,
+  METRIC_NAME_PATTERN,
+  WARPGOGOL_METRIC_REGISTRY,
+  type WarpgogolMetricKind,
+  type WarpgogolMetricSpec,
+} from "./metric-registry.ts";
+
+export {
+  encodeOtlpMetrics,
+  nowUnixNano,
+  type OtlpGaugePoint,
+  type OtlpHistogramPoint,
+  type OtlpMetricPoint,
+  type OtlpMetricsEnvelope,
+  type OtlpSumPoint,
+  type UnixNanoString,
+} from "./otlp-json.ts";
+
+export { createMetricsPusher, type MetricsPusher, type MetricsPusherEnv } from "./pusher.ts";
+
+export { redactUrl } from "./redact.ts";
+
+export {
+  METRIC_REFS,
+  type TypedCounter,
+  type TypedGauge,
+  type TypedHistogram,
+} from "./typed-refs.ts";