@warpgogol/werkstatt-shared 0.2.0

package/src/integration-adapter-supabase-crm/tests/funnel-persistence.test.ts

@@ -0,0 +1,409 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0188 Phase 4: prove the supabase-buffer adapter writes the rich canonical funnel
+state — funnel_stage (bridged to the generic stage), the deal-time offer snapshot, the typed
+append-only funnel-event row, and append-only consent evidence — and that plain leads keep the
+back-compatible generic path. The CrmBufferClient is faked; no network.</purpose>
+<responsibilities>
+  <item>offer.selected → deal.funnel_stage + bridged stage + offer_snapshot + funnel-event row; no consent.</item>
+  <item>legal.consent.recorded → append-only consent row with the right consent_kind.</item>
+  <item>plain lead → no funnel-event, generic stage, no funnel_stage.</item>
+</responsibilities>
+<non-goals><item>No network — the buffer client is a capturing fake.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-0188 Phase 4: initial adapter funnel-persistence test.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import type { IntegrationEvent } from "@warpgogol/werkstatt-shared/integration/port";
+import type { CrmBufferWriter } from "@warpgogol/werkstatt-shared/integration/crm-buffer";
+import { persistEventToBuffer } from "../adapter.ts";
+
+function makeFakeClient() {
+  const calls = {
+    deals: [] as unknown[],
+    funnelEvents: [] as unknown[],
+    consents: [] as unknown[],
+    orgs: [] as unknown[],
+    transitions: [] as unknown[],
+    outbox: [] as unknown[],
+    invoices: [] as unknown[],
+    subs: [] as unknown[],
+    balanceAdjusts: [] as unknown[],
+  };
+  const stubs: {
+    org: { id: string } | null;
+    sub: {
+      id: string;
+      included_changes_per_cycle: number;
+      included_changes_balance: number;
+    } | null;
+    activeSub: { id: string; included_changes_balance: number } | null;
+  } = { org: null, sub: null, activeSub: null };
+  const client: CrmBufferWriter = {
+    upsertContact: async () => ({ id: "contact_1", created: true }),
+    upsertOrganization: async (_t, d) => {
+      calls.orgs.push(d);
+      return { id: "org_1", created: true };
+    },
+    findOrganizationByStripeCustomer: async () => stubs.org,
+    upsertDeal: async (_t, d) => {
+      calls.deals.push(d);
+      return { id: "deal_1", created: true };
+    },
+    appendStageTransition: async (_t, d) => {
+      calls.transitions.push(d);
+      return "tr_1";
+    },
+    appendFunnelEvent: async (_t, d) => {
+      calls.funnelEvents.push(d);
+      return "fe_1";
+    },
+    appendConsentEvent: async (_t, d) => {
+      calls.consents.push(d);
+      return "ce_1";
+    },
+    upsertSubscription: async (_t, d) => {
+      calls.subs.push(d);
+      return { id: "sub_1", created: true };
+    },
+    findSubscriptionByStripeId: async () => stubs.sub,
+    findActiveSubscriptionByOrganization: async () => stubs.activeSub,
+    appendInvoice: async (_t, d) => {
+      calls.invoices.push(d);
+      return "inv_1";
+    },
+    adjustChangeBalance: async (_t, subscriptionId, delta) => {
+      calls.balanceAdjusts.push({ subscriptionId, delta });
+      return delta;
+    },
+    writeOutbox: async (_t, tasks) => {
+      calls.outbox.push(...tasks);
+      return { ids: [] };
+    },
+  };
+  return { client, calls, stubs };
+}
+
+test("offer.selected: writes funnel_stage, bridged stage, offer snapshot, and a funnel-event row", async () => {
+  const { client, calls } = makeFakeClient();
+  const event: IntegrationEvent = {
+    eventId: "uchat:offer.selected:1",
+    kind: "message",
+    source: "uchat",
+    locale: "de",
+    occurredAt: "2026-06-12T10:00:00Z",
+    contact: { name: "Anna" },
+    payload: {
+      funnelVersion: "1.0.0",
+      eventKind: "offer.selected",
+      stage: "offer_presented",
+      previousStage: "qualification_region",
+      organization: { name: "Bäckerei Müller" },
+      offer: { plan: "digital_foundation_monthly", priceSnapshot: { monthly: "70 € / Monat" } },
+    },
+  };
+
+  await persistEventToBuffer(client, "t1", event);
+
+  expect(calls.deals[0].funnel_stage).toBe("offer_presented");
+  expect(calls.deals[0].stage).toBe("proposal"); // bridge offer_presented → proposal
+  expect(calls.deals[0].offer_snapshot.monthly).toBe("70 € / Monat");
+  expect(calls.deals[0].organization_id).toBe("org_1");
+  expect(calls.orgs[0].name).toBe("Bäckerei Müller");
+  expect(calls.funnelEvents.length).toBe(1);
+  expect(calls.funnelEvents[0].event_kind).toBe("offer.selected");
+  expect(calls.funnelEvents[0].idempotency_key).toBe("uchat:offer.selected:1");
+  expect(calls.funnelEvents[0].to_stage).toBe("offer_presented");
+  expect(calls.funnelEvents[0].actor).toBe("uchat");
+  expect(calls.consents.length).toBe(0);
+});
+
+test("legal.consent.recorded (business): appends a B2B consent row", async () => {
+  const { client, calls } = makeFakeClient();
+  const event: IntegrationEvent = {
+    eventId: "uchat:legal.consent.recorded:1",
+    kind: "message",
+    source: "uchat",
+    locale: "de",
+    occurredAt: "2026-06-12T10:05:00Z",
+    payload: {
+      funnelVersion: "1.0.0",
+      eventKind: "legal.consent.recorded",
+      stage: "start_approved",
+      previousStage: "b2b_start_consent_pending",
+      legal: { buyerType: "business", startBeforeWithdrawalPeriod: true },
+    },
+  };
+
+  await persistEventToBuffer(client, "t1", event);
+
+  expect(calls.consents.length).toBe(1);
+  expect(calls.consents[0].buyer_type).toBe("business");
+  expect(calls.consents[0].consent_kind).toBe("b2b_start_before_completion");
+  expect(calls.consents[0].start_before_withdrawal_period).toBe(true);
+  expect(calls.deals[0].funnel_stage).toBe("start_approved");
+  expect(calls.deals[0].stage).toBe("negotiation"); // bridge
+});
+
+test("lifecycle invoice.paid: appends an invoice against the resolved Organization (no funnel deal)", async () => {
+  const { client, calls } = makeFakeClient();
+  const event: IntegrationEvent = {
+    eventId: "evt_in_1",
+    kind: "message",
+    source: "stripe",
+    locale: "de",
+    occurredAt: "2026-06-12T11:00:00Z",
+    payload: { eventKind: "invoice.paid", stripeCustomerId: "cus_1" },
+    lifecycle: {
+      eventKind: "invoice.paid",
+      stripeEventId: "evt_in_1",
+      stripeCustomerId: "cus_1",
+      stripeInvoiceId: "in_1",
+      invoiceKind: "cycle",
+      amountCents: 7000,
+      currency: "EUR",
+      lagebildOrganizationId: "org_9",
+      lagebildDealId: "deal_1",
+    },
+  };
+
+  const res = await persistEventToBuffer(client, "t1", event);
+
+  expect(res).toBeTruthy();
+  expect(calls.invoices.length).toBe(1);
+  expect(calls.invoices[0].organization_id).toBe("org_9");
+  expect(calls.invoices[0].stripe_invoice_id).toBe("in_1");
+  expect(calls.invoices[0].kind).toBe("cycle");
+  expect(calls.invoices[0].amount_cents).toBe(7000);
+  expect(calls.invoices[0].status).toBe("paid");
+  expect(calls.invoices[0].paid_at).toBe("2026-06-12T11:00:00Z");
+  // The funnel deal flow is NOT taken for a lifecycle event.
+  expect(calls.deals.length).toBe(0);
+  expect(calls.funnelEvents.length).toBe(0);
+});
+
+test("lifecycle subscription.created: upserts the subscription with balance = per-cycle allowance", async () => {
+  const { client, calls } = makeFakeClient();
+  const event: IntegrationEvent = {
+    eventId: "evt_sub_c",
+    kind: "message",
+    source: "stripe",
+    locale: "de",
+    occurredAt: "2026-06-12T11:00:00Z",
+    payload: { eventKind: "subscription.created", stripeCustomerId: "cus_1" },
+    lifecycle: {
+      eventKind: "subscription.created",
+      stripeEventId: "evt_sub_c",
+      stripeCustomerId: "cus_1",
+      stripeSubscriptionId: "sub_x",
+      subscriptionStatus: "active",
+      plan: "digital_foundation_monthly",
+      mrrCents: 7000,
+      currency: "EUR",
+      lagebildOrganizationId: "org_9",
+      lagebildDealId: "deal_p3",
+      includedChangesPerCycle: 1,
+    },
+  };
+
+  await persistEventToBuffer(client, "t1", event);
+
+  expect(calls.subs.length).toBe(1);
+  expect(calls.subs[0].stripe_subscription_id).toBe("sub_x");
+  expect(calls.subs[0].plan).toBe("digital_foundation_monthly");
+  expect(calls.subs[0].mrr_cents).toBe(7000);
+  expect(calls.subs[0].included_changes_per_cycle).toBe(1);
+  expect(calls.subs[0].included_changes_balance).toBe(1); // set on create
+  expect(calls.invoices.length).toBe(0);
+});
+
+test("lifecycle subscription.updated: omits included_changes_balance (preserves mid-cycle decrements)", async () => {
+  const { client, calls } = makeFakeClient();
+  const event: IntegrationEvent = {
+    eventId: "evt_sub_u",
+    kind: "message",
+    source: "stripe",
+    locale: "de",
+    occurredAt: "2026-06-12T11:00:00Z",
+    payload: { eventKind: "subscription.updated", stripeCustomerId: "cus_1" },
+    lifecycle: {
+      eventKind: "subscription.updated",
+      stripeEventId: "evt_sub_u",
+      stripeCustomerId: "cus_1",
+      stripeSubscriptionId: "sub_x",
+      subscriptionStatus: "active",
+      plan: "digital_foundation_monthly",
+      mrrCents: 9900,
+      lagebildOrganizationId: "org_9",
+      lagebildDealId: "deal_p3",
+      includedChangesPerCycle: 1,
+    },
+  };
+
+  await persistEventToBuffer(client, "t1", event);
+
+  expect(calls.subs.length).toBe(1);
+  expect(calls.subs[0].mrr_cents).toBe(9900);
+  expect("included_changes_balance" in calls.subs[0]).toBe(false); // omitted on update
+});
+
+test("lifecycle paid cycle invoice resets the included-changes balance to per-cycle", async () => {
+  const { client, calls, stubs } = makeFakeClient();
+  stubs.sub = { id: "sub_buf_1", included_changes_per_cycle: 1, included_changes_balance: 0 };
+  const event: IntegrationEvent = {
+    eventId: "evt_cycle",
+    kind: "message",
+    source: "stripe",
+    locale: "de",
+    occurredAt: "2026-06-12T11:00:00Z",
+    payload: { eventKind: "invoice.paid", stripeCustomerId: "cus_1" },
+    lifecycle: {
+      eventKind: "invoice.paid",
+      stripeEventId: "evt_cycle",
+      stripeCustomerId: "cus_1",
+      stripeSubscriptionId: "sub_x",
+      stripeInvoiceId: "in_cycle",
+      invoiceKind: "cycle",
+      amountCents: 7000,
+      lagebildOrganizationId: "org_9",
+    },
+  };
+
+  await persistEventToBuffer(client, "t1", event);
+
+  expect(calls.invoices.length).toBe(1);
+  expect(calls.balanceAdjusts.length).toBe(1);
+  expect(calls.balanceAdjusts[0].subscriptionId).toBe("sub_buf_1");
+  expect(calls.balanceAdjusts[0].delta).toBe(1); // reset 0 → 1
+});
+
+test("lifecycle with an unknown Stripe Customer → soft no-op (null), no invoice", async () => {
+  const { client, calls } = makeFakeClient(); // findOrganizationByStripeCustomer returns null
+  const event: IntegrationEvent = {
+    eventId: "evt_in_2",
+    kind: "message",
+    source: "stripe",
+    locale: "de",
+    occurredAt: "2026-06-12T11:05:00Z",
+    payload: { eventKind: "invoice.paid", stripeCustomerId: "cus_unknown" },
+    lifecycle: {
+      eventKind: "invoice.paid",
+      stripeEventId: "evt_in_2",
+      stripeCustomerId: "cus_unknown",
+      stripeInvoiceId: "in_2",
+      amountCents: 1500,
+    },
+  };
+
+  const res = await persistEventToBuffer(client, "t1", event);
+
+  expect(res).toBe(null);
+  expect(calls.invoices.length).toBe(0);
+});
+
+test("funnel change.requested (described, included): decrements the subscription balance", async () => {
+  const { client, calls, stubs } = makeFakeClient();
+  stubs.activeSub = { id: "sub_buf_1", included_changes_balance: 1 };
+  const event: IntegrationEvent = {
+    eventId: "uchat:change.requested:1",
+    kind: "message",
+    source: "uchat",
+    locale: "de",
+    occurredAt: "2026-06-12T12:00:00Z",
+    payload: {
+      funnelVersion: "1.0.0",
+      eventKind: "change.requested",
+      stage: "change_description_requested",
+      organization: { name: "Bäckerei Müller" },
+      changeRequest: { description: "Neue Öffnungszeiten" },
+    },
+  };
+
+  await persistEventToBuffer(client, "t1", event);
+
+  expect(calls.balanceAdjusts.length).toBe(1);
+  expect(calls.balanceAdjusts[0].subscriptionId).toBe("sub_buf_1");
+  expect(calls.balanceAdjusts[0].delta).toBe(-1);
+});
+
+test("funnel change.requested with no included balance (or at balance-check): no decrement", async () => {
+  const { client, calls, stubs } = makeFakeClient();
+  stubs.activeSub = { id: "sub_buf_1", included_changes_balance: 0 }; // exhausted → paid path
+  const described: IntegrationEvent = {
+    eventId: "uchat:change.requested:2",
+    kind: "message",
+    source: "uchat",
+    locale: "de",
+    occurredAt: "2026-06-12T12:00:00Z",
+    payload: {
+      eventKind: "change.requested",
+      stage: "change_description_requested",
+      organization: { name: "Org" },
+    },
+  };
+  await persistEventToBuffer(client, "t1", described);
+  expect(calls.balanceAdjusts.length).toBe(0); // balance 0 → no decrement
+
+  // and at the balance-check stage there is no decrement even with balance > 0
+  stubs.activeSub = { id: "sub_buf_1", included_changes_balance: 1 };
+  const checked: IntegrationEvent = {
+    ...described,
+    eventId: "uchat:change.requested:3",
+    payload: {
+      eventKind: "change.requested",
+      stage: "change_balance_checked",
+      organization: { name: "Org" },
+    },
+  };
+  await persistEventToBuffer(client, "t1", checked);
+  expect(calls.balanceAdjusts.length).toBe(0);
+});
+
+test("lifecycle payment.refunded: records a negative void ad-hoc ledger entry", async () => {
+  const { client, calls } = makeFakeClient();
+  const event: IntegrationEvent = {
+    eventId: "evt_refund",
+    kind: "message",
+    source: "stripe",
+    locale: "de",
+    occurredAt: "2026-06-12T12:30:00Z",
+    payload: { eventKind: "payment.refunded", stripeCustomerId: "cus_1" },
+    lifecycle: {
+      eventKind: "payment.refunded",
+      stripeEventId: "evt_refund",
+      stripeCustomerId: "cus_1",
+      stripeInvoiceId: "ch_1",
+      amountCents: 1500,
+      currency: "EUR",
+      lagebildOrganizationId: "org_9",
+    },
+  };
+
+  await persistEventToBuffer(client, "t1", event);
+
+  expect(calls.invoices.length).toBe(1);
+  expect(calls.invoices[0].amount_cents).toBe(-1500);
+  expect(calls.invoices[0].status).toBe("void");
+  expect(calls.invoices[0].kind).toBe("adhoc");
+});
+
+test("plain lead (no eventKind): generic path, no funnel-event, no funnel_stage", async () => {
+  const { client, calls } = makeFakeClient();
+  const event: IntegrationEvent = {
+    eventId: "lead_1",
+    kind: "lead",
+    source: "send-message",
+    locale: "de",
+    occurredAt: "2026-06-12T10:10:00Z",
+    payload: { message: "Hi, I want a website" },
+  };
+
+  await persistEventToBuffer(client, "t1", event);
+
+  expect(calls.funnelEvents.length).toBe(0);
+  expect(calls.consents.length).toBe(0);
+  expect(calls.deals[0].funnel_stage).toBe(undefined);
+  expect(calls.deals[0].stage).toBe("new"); // lead default
+  expect(calls.orgs.length).toBe(0); // no organization in the payload
+});

package/src/integration-adapter-supabase-crm/tests/lifecycle-sync.test.ts

@@ -0,0 +1,288 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0386: Unit tests for lifecycle sync (syncSubscription, syncInvoice).
+Verifies P3 deal creation/linking, stage moves, invoice recording, change-balance
+reset on paid cycles, and P4 change-deal opening. All tests use stubbed buffer
+and fetch — no network calls.</purpose>
+<non-goals>
+  <item>No network calls — all Pipedrive API calls are stubbed.</item>
+  <item>No real Supabase — buffer reads are stubbed via a fake CrmBufferReader.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0386: Initial lifecycle sync unit tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, vi } from "vitest";
+import type {
+  CrmBufferReader,
+  SyncOutboxRow,
+  BufferSubscription,
+  BufferInvoice,
+  BufferOrganization,
+} from "@warpgogol/werkstatt-shared/integration/crm-buffer";
+import { PipedriveSyncTarget } from "../pipedrive-sync-target.ts";
+
+// ---------------------------------------------------------------------------
+// Stubs
+// ---------------------------------------------------------------------------
+
+function makeFakeBuffer(
+  overrides: {
+    subscription?: Partial<BufferSubscription> & { id: string };
+    invoice?: Partial<BufferInvoice> & { id: string };
+    organization?: Partial<BufferOrganization> & { id: string };
+  } = {},
+): CrmBufferReader {
+  const sub: BufferSubscription = {
+    id: overrides.subscription?.id ?? "sub-1",
+    tenant_id: "t1",
+    organization_id: overrides.subscription?.organization_id ?? "org-1",
+    deal_id: overrides.subscription?.deal_id ?? "deal-1",
+    stripe_subscription_id: overrides.subscription?.stripe_subscription_id ?? "sub_stripe_123",
+    status: overrides.subscription?.status ?? "active",
+    plan: overrides.subscription?.plan ?? "base",
+    mrr_cents: overrides.subscription?.mrr_cents ?? 7000,
+    currency: overrides.subscription?.currency ?? "EUR",
+    included_changes_balance: overrides.subscription?.included_changes_balance ?? 3,
+    included_changes_per_cycle: overrides.subscription?.included_changes_per_cycle ?? 5,
+    pipedrive_deal_id: overrides.subscription?.pipedrive_deal_id,
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    ...overrides.subscription,
+  } as BufferSubscription;
+
+  const inv: BufferInvoice = {
+    id: overrides.invoice?.id ?? "inv-1",
+    tenant_id: "t1",
+    organization_id: overrides.invoice?.organization_id ?? "org-1",
+    stripe_invoice_id: overrides.invoice?.stripe_invoice_id ?? "in_stripe_456",
+    kind: overrides.invoice?.kind ?? "cycle",
+    amount_cents: overrides.invoice?.amount_cents ?? 7000,
+    currency: overrides.invoice?.currency ?? "EUR",
+    status: overrides.invoice?.status ?? "paid",
+    paid_at: overrides.invoice?.paid_at ?? "2026-01-01T00:00:00Z",
+    subscription_id: overrides.invoice?.subscription_id ?? "sub-1",
+    created_at: "2026-01-01T00:00:00Z",
+    ...overrides.invoice,
+  } as BufferInvoice;
+
+  const org: BufferOrganization = {
+    id: overrides.organization?.id ?? "org-1",
+    tenant_id: "t1",
+    name: "Test Org",
+    pipedrive_org_id: overrides.organization?.pipedrive_org_id ?? 999,
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    ...overrides.organization,
+  } as BufferOrganization;
+
+  return {
+    readPendingOutbox: vi.fn(),
+    updateOutboxStatus: vi.fn(),
+    getContact: vi.fn(),
+    getDeal: vi.fn(),
+    getOrganization: vi.fn(async (_t: string, _id: string) => org),
+    patchContactPipedriveId: vi.fn(),
+    patchOrganizationPipedriveId: vi.fn(),
+    patchDealPipedriveIds: vi.fn(),
+    getSubscription: vi.fn(async (_t: string, _id: string) => sub),
+    getInvoice: vi.fn(async (_t: string, _id: string) => inv),
+    patchSubscriptionPipedriveDealId: vi.fn(),
+    adjustChangeBalance: vi.fn(async () => 5),
+  } as unknown as CrmBufferReader;
+}
+
+function makeTask(
+  op: "upsert_subscription" | "upsert_invoice",
+  payload: Record<string, unknown>,
+): SyncOutboxRow {
+  return {
+    id: "task-1",
+    tenant_id: "t1",
+    op,
+    payload,
+    status: "pending",
+    scheduled_at: "2026-01-01T00:00:00Z",
+    retry_count: 0,
+    max_retries: 5,
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+  };
+}
+
+function makeFetchStub(): typeof fetch & {
+  calls: Array<{ url: string; method: string; body?: unknown }>;
+} {
+  const calls: Array<{ url: string; method: string; body?: unknown }> = [];
+  const stub = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+    const urlStr = typeof url === "string" ? url : url.toString();
+    const method = init?.method ?? "GET";
+    let body: unknown;
+    if (init?.body) {
+      try {
+        body = JSON.parse(init.body as string);
+      } catch {
+        body = init.body;
+      }
+    }
+    calls.push({ url: urlStr, method, body });
+    return new Response(JSON.stringify({ data: { id: 42 } }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  }) as unknown as typeof fetch & { calls: Array<{ url: string; method: string; body?: unknown }> };
+  stub.calls = calls;
+  return stub;
+}
+
+// ---------------------------------------------------------------------------
+// syncSubscription
+// ---------------------------------------------------------------------------
+
+test("syncSubscription creates P3 deal when no pipedrive_deal_id exists", async () => {
+  const buffer = makeFakeBuffer({ subscription: { id: "sub-1", pipedrive_deal_id: undefined } });
+  const fetchStub = makeFetchStub();
+  const target = new PipedriveSyncTarget(
+    { token: "tok", domain: "dom", p3StageMap: { active: 10, past_due: 11, canceled: 12 } },
+    fetchStub,
+  );
+
+  await target.syncSubscription(
+    makeTask("upsert_subscription", { subscription_id: "sub-1" }),
+    buffer,
+  );
+
+  expect(fetchStub.calls).toHaveLength(1);
+  expect(fetchStub.calls[0].method).toBe("POST");
+  expect(fetchStub.calls[0].body).toMatchObject({ stage_id: 10 });
+  expect(buffer.patchSubscriptionPipedriveDealId).toHaveBeenCalledWith("t1", "sub-1", 42);
+});
+
+test("syncSubscription moves P3 deal stage when pipedrive_deal_id exists", async () => {
+  const buffer = makeFakeBuffer({
+    subscription: { id: "sub-1", status: "past_due", pipedrive_deal_id: 99 },
+  });
+  const fetchStub = makeFetchStub();
+  const target = new PipedriveSyncTarget(
+    { token: "tok", domain: "dom", p3StageMap: { active: 10, past_due: 11, canceled: 12 } },
+    fetchStub,
+  );
+
+  await target.syncSubscription(
+    makeTask("upsert_subscription", { subscription_id: "sub-1" }),
+    buffer,
+  );
+
+  expect(fetchStub.calls).toHaveLength(1);
+  expect(fetchStub.calls[0].method).toBe("PUT");
+  expect(fetchStub.calls[0].url).toContain("/deals/99");
+  expect(fetchStub.calls[0].body).toMatchObject({ stage_id: 11 });
+  expect(buffer.patchSubscriptionPipedriveDealId).not.toHaveBeenCalled();
+});
+
+test("syncSubscription throws on missing subscription_id", async () => {
+  const buffer = makeFakeBuffer();
+  const target = new PipedriveSyncTarget({ token: "tok", domain: "dom" }, makeFetchStub());
+
+  await expect(
+    target.syncSubscription(makeTask("upsert_subscription", {}), buffer),
+  ).rejects.toThrow("missing subscription_id");
+});
+
+// ---------------------------------------------------------------------------
+// syncInvoice
+// ---------------------------------------------------------------------------
+
+test("syncInvoice resets change balance on paid cycle invoice", async () => {
+  const buffer = makeFakeBuffer({
+    subscription: {
+      id: "sub-1",
+      included_changes_balance: 2,
+      included_changes_per_cycle: 5,
+      pipedrive_deal_id: 99,
+    },
+    invoice: { id: "inv-1", kind: "cycle", status: "paid", subscription_id: "sub-1" },
+  });
+  const fetchStub = makeFetchStub();
+  const target = new PipedriveSyncTarget({ token: "tok", domain: "dom" }, fetchStub);
+
+  await target.syncInvoice(makeTask("upsert_invoice", { invoice_id: "inv-1" }), buffer);
+
+  // delta = 5 - 2 = 3
+  expect(buffer.adjustChangeBalance).toHaveBeenCalledWith("t1", "sub-1", 3);
+});
+
+test("syncInvoice does not reset balance on non-paid invoice", async () => {
+  const buffer = makeFakeBuffer({
+    subscription: {
+      id: "sub-1",
+      included_changes_balance: 2,
+      included_changes_per_cycle: 5,
+      pipedrive_deal_id: 99,
+    },
+    invoice: { id: "inv-1", kind: "cycle", status: "open", subscription_id: "sub-1" },
+  });
+  const fetchStub = makeFetchStub();
+  const target = new PipedriveSyncTarget({ token: "tok", domain: "dom" }, fetchStub);
+
+  await target.syncInvoice(makeTask("upsert_invoice", { invoice_id: "inv-1" }), buffer);
+
+  expect(buffer.adjustChangeBalance).not.toHaveBeenCalled();
+});
+
+test("syncInvoice does not reset balance on non-cycle invoice", async () => {
+  const buffer = makeFakeBuffer({
+    subscription: {
+      id: "sub-1",
+      included_changes_balance: 2,
+      included_changes_per_cycle: 5,
+      pipedrive_deal_id: 99,
+    },
+    invoice: { id: "inv-1", kind: "setup", status: "paid", subscription_id: "sub-1" },
+  });
+  const fetchStub = makeFetchStub();
+  const target = new PipedriveSyncTarget({ token: "tok", domain: "dom" }, fetchStub);
+
+  await target.syncInvoice(makeTask("upsert_invoice", { invoice_id: "inv-1" }), buffer);
+
+  expect(buffer.adjustChangeBalance).not.toHaveBeenCalled();
+});
+
+test("syncInvoice opens P4 change deal for change invoice", async () => {
+  const buffer = makeFakeBuffer({
+    subscription: { id: "sub-1", pipedrive_deal_id: 99 },
+    invoice: { id: "inv-1", kind: "change", status: "paid", subscription_id: "sub-1" },
+  });
+  const fetchStub = makeFetchStub();
+  const target = new PipedriveSyncTarget(
+    { token: "tok", domain: "dom", p4StageMap: { change_requested: 20 } },
+    fetchStub,
+  );
+
+  await target.syncInvoice(makeTask("upsert_invoice", { invoice_id: "inv-1" }), buffer);
+
+  // First call: note on P3 deal. Second call: P4 deal creation.
+  expect(fetchStub.calls.length).toBeGreaterThanOrEqual(2);
+  const p4Call = fetchStub.calls.find((c) => {
+    const b = c.body as Record<string, unknown> | undefined;
+    return (
+      c.method === "POST" &&
+      c.url.endsWith("/deals") &&
+      typeof b?.title === "string" &&
+      b.title.startsWith("P4")
+    );
+  });
+  expect(p4Call).toBeDefined();
+  expect(p4Call!.body).toMatchObject({ stage_id: 20 });
+});
+
+test("syncInvoice throws on missing invoice_id", async () => {
+  const buffer = makeFakeBuffer();
+  const target = new PipedriveSyncTarget({ token: "tok", domain: "dom" }, makeFetchStub());
+
+  await expect(target.syncInvoice(makeTask("upsert_invoice", {}), buffer)).rejects.toThrow(
+    "missing invoice_id",
+  );
+});