@warpgogol/werkstatt-shared 0.2.0

package/src/integration/tests/hub-runtime.test.ts

@@ -0,0 +1,128 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0176: verify the inbound/queue runtime — authenticateInbound, IntegrationEventSchema,
+routeEventToReady (self-enabling Pipedrive route), and consumeIntegrationBatch dedup via a KV-backed
+seen-set. fetch + KV are stubbed so the full producer→consumer flow is exercised without Cloudflare.</purpose>
+<responsibilities>
+  <item>Assert a valid event routes once to the pipedrive gogol-adapter destination.</item>
+  <item>Assert a queue redelivery is deduped (no double-write) via the KV seen-set.</item>
+  <item>Assert inbound auth + event-shape validation are fail-closed.</item>
+</responsibilities>
+<non-goals>
+  <item>Do not hit the network — fetch is stubbed.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0176: initial queue/inbound runtime test.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, afterEach, beforeEach } from "vitest";
+import {
+  IntegrationEventSchema,
+  authenticateInbound,
+  consumeIntegrationBatch,
+  kvDedup,
+  routeEventToReady,
+  type IntegrationEvent,
+  type IntegrationSecrets,
+  type KvDedupStore,
+} from "../index.ts";
+
+const SECRETS: IntegrationSecrets = {
+  INTEGRATION_PIPEDRIVE_API_TOKEN: "tok",
+  INTEGRATION_PIPEDRIVE_DOMAIN: "acme",
+};
+
+const EVENT: IntegrationEvent = {
+  eventId: "evt-1",
+  kind: "lead",
+  source: "uchat",
+  locale: "de",
+  occurredAt: "2026-06-08T00:00:00.000Z",
+  contact: { name: "Max", email: "max@example.org" },
+  payload: { note: "Hello from the chat" },
+};
+
+/** In-memory KV implementing the dedup store contract. */
+function memoryKv(): KvDedupStore & { size(): number } {
+  const map = new Map<string, string>();
+  return {
+    async get(key) {
+      return map.has(key) ? (map.get(key) ?? null) : null;
+    },
+    async put(key, value) {
+      map.set(key, value);
+    },
+    size: () => map.size,
+  };
+}
+
+let fetchCalls: string[] = [];
+const realFetch = globalThis.fetch;
+
+beforeEach(() => {
+  fetchCalls = [];
+  // Stub Pipedrive persons + leads endpoints — both return a usable id.
+  globalThis.fetch = (async (url: string | URL | Request) => {
+    fetchCalls.push(String(url));
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ data: { id: 1 } }),
+    } as unknown as Response;
+  }) as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+test("routeEventToReady routes a lead to the pipedrive gogol-adapter destination", async () => {
+  const result = await routeEventToReady(EVENT, SECRETS);
+  expect(result.routed).toEqual(["crm:pipedrive"]);
+  expect(result.failed.length).toBe(0);
+  // pipedrive adapter performs persons + leads calls.
+  expect(fetchCalls.length).toBe(2);
+});
+
+test("routeEventToReady skips when destination secrets are absent", async () => {
+  const result = await routeEventToReady(EVENT, {});
+  expect(result.skipped).toEqual(["crm:pipedrive"]);
+  expect(result.routed.length).toBe(0);
+  expect(fetchCalls.length).toBe(0);
+});
+
+test("consumeIntegrationBatch dedups a queue redelivery via KV (no double-write)", async () => {
+  const kv = memoryKv();
+  const dedup = kvDedup(kv);
+
+  const first = await consumeIntegrationBatch([EVENT], SECRETS, dedup);
+  expect(first[0].routed).toEqual(["crm:pipedrive"]);
+  const afterFirst = fetchCalls.length;
+  expect(afterFirst).toBe(2);
+
+  // Redeliver the SAME eventId — must be skipped by dedup, no new fetches.
+  const second = await consumeIntegrationBatch([EVENT], SECRETS, dedup);
+  expect(second[0].skipped).toEqual(["crm:pipedrive"]);
+  expect(fetchCalls.length).toBe(afterFirst);
+  expect(kv.size()).toBe(1);
+});
+
+test("authenticateInbound is fail-closed (bearer + header, unset secret rejects)", () => {
+  const ok = new Headers({ authorization: "Bearer s3cret" });
+  const okHeader = new Headers({ "x-integration-secret": "s3cret" });
+  const wrong = new Headers({ authorization: "Bearer nope" });
+  expect(authenticateInbound(ok, "s3cret")).toBe(true);
+  expect(authenticateInbound(okHeader, "s3cret")).toBe(true);
+  expect(authenticateInbound(wrong, "s3cret")).toBe(false);
+  expect(authenticateInbound(ok, undefined)).toBe(false);
+  expect(authenticateInbound(new Headers(), "s3cret")).toBe(false);
+});
+
+test("IntegrationEventSchema rejects malformed payloads", () => {
+  expect(IntegrationEventSchema.safeParse(EVENT).success).toBe(true);
+  expect(IntegrationEventSchema.safeParse({ ...EVENT, kind: "bogus" }).success).toBe(false);
+  expect(IntegrationEventSchema.safeParse({ ...EVENT, eventId: "" }).success).toBe(false);
+  expect(IntegrationEventSchema.safeParse({}).success).toBe(false);
+});

package/src/integration/tests/lifecycle.test.ts

@@ -0,0 +1,69 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0191: prove the lifecycle event contracts — the closed kind catalog, the typed
+payload schema the Stripe adapter validates against, and the guard. Pure — no I/O, no Stripe.</purpose>
+<responsibilities>
+  <item>LifecycleEventPayloadSchema accepts a valid Stripe-mapped payload and rejects bad input.</item>
+  <item>isLifecycleEventKind guards the closed catalog.</item>
+</responsibilities>
+<non-goals><item>No network, no Stripe SDK — the schema is pure.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-0191: initial lifecycle contract test.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import {
+  LIFECYCLE_EVENT_KINDS,
+  LifecycleEventPayloadSchema,
+  isLifecycleEventKind,
+} from "../lifecycle.ts";
+
+test("the lifecycle catalog covers invoice, subscription, and refund events", () => {
+  for (const k of [
+    "invoice.paid",
+    "invoice.payment_failed",
+    "subscription.created",
+    "subscription.updated",
+    "subscription.canceled",
+    "payment.refunded",
+  ]) {
+    expect((LIFECYCLE_EVENT_KINDS as readonly string[]).includes(k)).toBeTruthy();
+  }
+});
+
+test("the payload schema accepts a Stripe-mapped invoice.paid event", () => {
+  const r = LifecycleEventPayloadSchema.safeParse({
+    eventKind: "invoice.paid",
+    stripeEventId: "evt_123",
+    stripeCustomerId: "cus_123",
+    stripeInvoiceId: "in_123",
+    invoiceKind: "cycle",
+    invoiceStatus: "paid",
+    amountCents: 7000,
+    currency: "EUR",
+  });
+  expect(r.success).toBe(true);
+});
+
+test("the payload schema rejects an unknown event kind and a negative amount", () => {
+  expect(
+    LifecycleEventPayloadSchema.safeParse({
+      eventKind: "invoice.exploded",
+      stripeEventId: "evt_1",
+      stripeCustomerId: "cus_1",
+    }).success,
+  ).toBe(false);
+  expect(
+    LifecycleEventPayloadSchema.safeParse({
+      eventKind: "invoice.paid",
+      stripeEventId: "evt_1",
+      stripeCustomerId: "cus_1",
+      amountCents: -5,
+    }).success,
+  ).toBe(false);
+});
+
+test("isLifecycleEventKind guards the closed catalog", () => {
+  expect(isLifecycleEventKind("subscription.updated")).toBe(true);
+  expect(isLifecycleEventKind("offer.selected")).toBe(false); // a funnel kind, not lifecycle
+});

package/src/integration/tests/qstash.test.ts

@@ -0,0 +1,83 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0181: verify the EU delivery substrate. buildQstashPublish targets the EU region, pins
+dedup to the eventId, and never leaks the token into the body; restRedisLedger gives first-seen-once
+semantics and fails closed on transport error. fetch is stubbed — no network.</purpose>
+<responsibilities>
+  <item>publish Request hits the EU base, carries dedup id + retries, body is the event (no token).</item>
+  <item>ledger.firstSeen is true on OK, false on null (redelivery), throws on non-2xx (fail-closed).</item>
+</responsibilities>
+<non-goals><item>No network — fetch stubbed.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-0181: initial EU delivery substrate test.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { QSTASH_EU_BASE, buildQstashPublish, restRedisLedger } from "../qstash.ts";
+import type { IntegrationEvent } from "../port.ts";
+
+const EVENT: IntegrationEvent = {
+  eventId: "evt-42",
+  kind: "lead",
+  source: "send-message",
+  locale: "de",
+  occurredAt: new Date().toISOString(),
+  contact: { name: "A", email: "a@example.de" },
+  payload: { message: "hallo" },
+};
+
+test("buildQstashPublish targets the EU region and pins dedup to the eventId", async () => {
+  const req = buildQstashPublish(EVENT, {
+    token: "qstash-secret",
+    callbackUrl: "https://warpgogol.com/internal/integration-route",
+  });
+  expect(req.url.startsWith(`${QSTASH_EU_BASE}/v2/publish/`)).toBeTruthy();
+  expect(req.url.includes("https://warpgogol.com/internal/integration-route")).toBeTruthy();
+  expect(req.headers.get("upstash-deduplication-id")).toBe("evt-42");
+  expect(req.headers.get("upstash-retries")).toBe("3");
+});
+
+test("buildQstashPublish puts the event (not the token) in the body", async () => {
+  const req = buildQstashPublish(EVENT, {
+    token: "qstash-secret",
+    callbackUrl: "https://warpgogol.com/internal/integration-route",
+  });
+  const body = await req.text();
+  expect(!body.includes("qstash-secret")).toBeTruthy();
+  expect(JSON.parse(body).eventId).toBe("evt-42");
+});
+
+test("buildQstashPublish honours an explicit retry count", () => {
+  const req = buildQstashPublish(EVENT, {
+    token: "t",
+    callbackUrl: "https://x/cb",
+    retries: 5,
+  });
+  expect(req.headers.get("upstash-retries")).toBe("5");
+});
+
+function stubFetch(status: number, result: string | null) {
+  return async () => new Response(JSON.stringify({ result }), { status });
+}
+
+test("restRedisLedger.firstSeen is true on OK (first) and false on null (redelivery)", async () => {
+  const first = restRedisLedger(
+    { url: "https://eu-redis.upstash.io", token: "redis-secret" },
+    stubFetch(200, "OK") as unknown as typeof fetch,
+  );
+  expect(await first.firstSeen("evt-42")).toBe(true);
+
+  const repeat = restRedisLedger(
+    { url: "https://eu-redis.upstash.io", token: "redis-secret" },
+    stubFetch(200, null) as unknown as typeof fetch,
+  );
+  expect(await repeat.firstSeen("evt-42")).toBe(false);
+});
+
+test("restRedisLedger fails closed (throws) on a transport error", async () => {
+  const ledger = restRedisLedger(
+    { url: "https://eu-redis.upstash.io", token: "redis-secret" },
+    stubFetch(500, null) as unknown as typeof fetch,
+  );
+  await expect(() => ledger.firstSeen("evt-42")).rejects.toThrow();
+});

package/src/integration/tests/sharding.test.ts

@@ -0,0 +1,64 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0179: verify resolveShard is deterministic, distributes across the shared pool, names
+resources by the documented scheme, and isolates a dedicated-tier site onto its own queue. These
+properties are what registry-free placement and re-sharding safety depend on.</purpose>
+<responsibilities>
+  <item>Same siteId+region+shardCount ⇒ identical assignment (stable hash).</item>
+  <item>shared tier names gogol-int-{region}-shared-{NN}; dedicated names a per-site queue.</item>
+  <item>dedup namespace is region-scoped; DLQ/consumer derive from the queue.</item>
+</responsibilities>
+<non-goals><item>No I/O — resolveShard is pure.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-0179: initial sharding test.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { fnv1a, resolveShard } from "../sharding.ts";
+
+test("resolveShard is deterministic for the same inputs", () => {
+  const a = resolveShard("warpgogol-com", "eu", { shardCount: 4 });
+  const b = resolveShard("warpgogol-com", "eu", { shardCount: 4 });
+  expect(a).toEqual(b);
+});
+
+test("shared tier names the queue/dlq/consumer by the documented scheme", () => {
+  const s = resolveShard("warpgogol-com", "eu", { tier: "shared", shardCount: 4 });
+  expect(s.tier).toBe("shared");
+  expect(s.queue).toMatch(/^gogol-int-eu-shared-\d{2}$/);
+  expect(s.dlq).toBe(`${s.queue}-dlq`);
+  expect(s.consumer).toBe(`${s.queue}-consumer`);
+  expect(s.dedupNamespace).toBe("gogol-int-dedup-eu");
+  expect(s.shardIndex >= 0 && s.shardIndex < 4).toBeTruthy();
+});
+
+test("shard index is hash(siteId) mod shardCount", () => {
+  const s = resolveShard("acme-gmbh", "eu", { shardCount: 8 });
+  expect(s.shardIndex).toBe(fnv1a("acme-gmbh") % 8);
+});
+
+test("region pins the dedup namespace and queue prefix", () => {
+  const us = resolveShard("acme-gmbh", "us", { shardCount: 4 });
+  expect(us.dedupNamespace).toBe("gogol-int-dedup-us");
+  expect(us.queue).toMatch(/^gogol-int-us-shared-/);
+});
+
+test("dedicated tier isolates a site onto its own queue", () => {
+  const d = resolveShard("Busy Client!", "eu", { tier: "dedicated" });
+  expect(d.tier).toBe("dedicated");
+  expect(d.shardIndex).toBe(-1);
+  expect(d.queue).toBe("gogol-int-eu-ded-busy-client");
+  expect(d.dlq).toBe("gogol-int-eu-ded-busy-client-dlq");
+});
+
+test("the shared pool actually fans out across shards", () => {
+  const seen = new Set<number>();
+  for (let i = 0; i < 200; i += 1) {
+    seen.add(resolveShard(`site-${i}`, "eu", { shardCount: 4 }).shardIndex);
+  }
+  expect(seen.size).toBe(4);
+});
+
+test("resolveShard rejects an empty siteId", () => {
+  expect(() => resolveShard("", "eu")).toThrow();
+});

package/src/integration/vitest.config.ts

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