@dainamite/cpq-billing-connector 0.1.0

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-amended.js

@@ -0,0 +1,112 @@
+import { createRequestContainer } from "@open-mercato/shared/lib/di/container";
+import { cycleContaining } from "@dainamite/billing/modules/billing/lib/billPeriod";
+import { BillingApiClient } from "../lib/billingApiClient.js";
+import {
+  mapSubscriptionItemsToBillingItems
+} from "../lib/chargeMapper.js";
+import {
+  computeProration,
+  formatProrationDescription
+} from "../lib/prorationHelper.js";
+const metadata = {
+  event: "cpq.subscription.amended",
+  persistent: true,
+  id: "cpq-billing-connector:subscription-amended"
+};
+const DAY_MS = 864e5;
+function toMidnightMs(value) {
+  const d = value instanceof Date ? new Date(value.getTime()) : /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+  d.setUTCHours(0, 0, 0, 0);
+  return d.getTime();
+}
+function inclusiveDays(from, to) {
+  return Math.round((toMidnightMs(to) - toMidnightMs(from)) / DAY_MS) + 1;
+}
+function isoDateMinusOneDay(iso) {
+  const d = /* @__PURE__ */ new Date(`${iso}T00:00:00.000Z`);
+  d.setUTCDate(d.getUTCDate() - 1);
+  return d.toISOString().slice(0, 10);
+}
+async function handle(payload) {
+  if (!payload?.tenantId || !payload.organizationId) return;
+  if (!payload.subscriptionId || !payload.effectiveDate) return;
+  const added = payload.addedItems ?? [];
+  const removed = payload.removedSubscriptionItemIds ?? [];
+  if (added.length === 0 && removed.length === 0) return;
+  const container = await createRequestContainer();
+  const billingApi = new BillingApiClient(container);
+  const scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId
+  };
+  const account = await billingApi.findAccountByCustomer(scope, payload.customerId);
+  if (!account) return;
+  const itemsToCreate = mapSubscriptionItemsToBillingItems({
+    subscriptionId: payload.subscriptionId,
+    items: added,
+    billStartDate: payload.effectiveDate
+  }).map((item) => ({
+    billAccountId: account.id,
+    type: item.type,
+    billStartDate: item.billStartDate,
+    description: item.description,
+    rateJson: item.rateJson,
+    subscriptionId: item.subscriptionId,
+    subscriptionItemId: item.subscriptionItemId,
+    sourceRef: item.sourceRef
+  }));
+  if (added.length > 0) {
+    const period = cycleContaining(
+      account.nextBillDate,
+      account.billCycle,
+      payload.effectiveDate
+    );
+    const cycleEnd = period.periodEnd.toISOString().slice(0, 10);
+    const daysInPeriod = inclusiveDays(period.periodStart, period.periodEnd);
+    const daysRemaining = inclusiveDays(payload.effectiveDate, period.periodEnd);
+    for (const addedItem of added) {
+      for (const charge of addedItem.charges) {
+        if (charge.type !== "recurring" || typeof charge.unitPrice !== "number") {
+          continue;
+        }
+        const { amount } = computeProration({
+          unitPrice: charge.unitPrice,
+          quantity: addedItem.quantity,
+          daysInPeriod,
+          daysRemaining
+        });
+        if (amount === 0) continue;
+        itemsToCreate.push({
+          billAccountId: account.id,
+          type: "one_time",
+          billStartDate: payload.effectiveDate,
+          description: formatProrationDescription({
+            productName: addedItem.productName,
+            effectiveDate: payload.effectiveDate,
+            cycleEnd
+          }),
+          rateJson: { amount },
+          subscriptionId: payload.subscriptionId,
+          subscriptionItemId: addedItem.subscriptionItemId,
+          sourceRef: `cpq-${payload.subscriptionId}-${addedItem.subscriptionItemId}-proration-${payload.effectiveDate}`
+        });
+      }
+    }
+  }
+  await billingApi.bulkCreateItems(scope, itemsToCreate);
+  const endDate = isoDateMinusOneDay(payload.effectiveDate);
+  for (const removedSubItemId of removed) {
+    const items = await billingApi.findItemsBySubscriptionItem(scope, removedSubItemId);
+    for (const item of items) {
+      await billingApi.updateItem(scope, {
+        id: item.id,
+        billEndDate: endDate
+      });
+    }
+  }
+}
+export {
+  handle as default,
+  metadata
+};
+//# sourceMappingURL=cpq-subscription-amended.js.map

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-amended.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/cpq_billing_connector/subscribers/cpq-subscription-amended.ts"],
+  "sourcesContent": ["import { createRequestContainer } from '@open-mercato/shared/lib/di/container'\n// TODO(L2-boundary): `cycleContaining` is a runtime function imported from\n// `@dainamite/billing` internals (not a stable public surface). A breaking\n// rename or signature change in billing's `billPeriod` will manifest here\n// as a runtime crash on the first `cpq.subscription.amended` event. Same\n// trade-off as `billingApiClient.ts` \u2014 kept inline for now because the\n// proration math is non-trivial and we don't want to fork it. Promote\n// `cycleContaining` to a documented public export of @dainamite/billing\n// (or expose via a billing REST helper) before the connector hits v1.\nimport { cycleContaining } from '@dainamite/billing/modules/billing/lib/billPeriod'\nimport type { BillCycle } from '@dainamite/billing/modules/billing/data/validators'\nimport { BillingApiClient, type Scope } from '../lib/billingApiClient'\nimport {\n  mapSubscriptionItemsToBillingItems,\n  type CpqSubscriptionItem,\n} from '../lib/chargeMapper'\nimport {\n  computeProration,\n  formatProrationDescription,\n} from '../lib/prorationHelper'\n\n/**\n * Subscriber: `cpq.subscription.amended` \u2192 mid-cycle add / remove.\n *\n * CPQ's amended event carries `addedItems`, `removedSubscriptionItemIds`\n * and the `effectiveDate` of the amendment. The connector:\n *   1. Creates a Billing Item for every added charge \u2014 recurring items\n *      start on `effectiveDate`; the engine's mid-cycle rule skips the\n *      current cycle and bills from the next full cycle.\n *   2. For every added RECURRING charge, posts a `one_time` proration\n *      line covering the partial current cycle. The billing cycle is\n *      derived HERE (not in CPQ) \u2014 proration is a billing concept, so\n *      the connector computes it from the account's `nextBillDate` +\n *      `billCycle` via billing's `cycleContaining`.\n *   3. End-dates every Billing Item of each removed subscription item\n *      at `effectiveDate - 1 day`.\n */\n\nexport const metadata = {\n  event: 'cpq.subscription.amended',\n  persistent: true,\n  id: 'cpq-billing-connector:subscription-amended',\n}\n\ntype AmendedPayload = {\n  tenantId: string\n  organizationId: string\n  subscriptionId: string\n  customerId: string\n  /** YYYY-MM-DD; the date the amend takes effect mid-cycle. */\n  effectiveDate: string\n  addedItems?: CpqSubscriptionItem[]\n  removedSubscriptionItemIds?: string[]\n}\n\nconst DAY_MS = 86_400_000\n\nfunction toMidnightMs(value: Date | string): number {\n  const d =\n    value instanceof Date\n      ? new Date(value.getTime())\n      : new Date(`${value}T00:00:00.000Z`)\n  d.setUTCHours(0, 0, 0, 0)\n  return d.getTime()\n}\n\n/** Inclusive day count from `from` through `to`. */\nfunction inclusiveDays(from: Date | string, to: Date | string): number {\n  return Math.round((toMidnightMs(to) - toMidnightMs(from)) / DAY_MS) + 1\n}\n\nfunction isoDateMinusOneDay(iso: string): string {\n  const d = new Date(`${iso}T00:00:00.000Z`)\n  d.setUTCDate(d.getUTCDate() - 1)\n  return d.toISOString().slice(0, 10)\n}\n\nexport default async function handle(payload: AmendedPayload): Promise<void> {\n  if (!payload?.tenantId || !payload.organizationId) return\n  if (!payload.subscriptionId || !payload.effectiveDate) return\n\n  const added = payload.addedItems ?? []\n  const removed = payload.removedSubscriptionItemIds ?? []\n  if (added.length === 0 && removed.length === 0) return\n\n  const container = await createRequestContainer()\n  const billingApi = new BillingApiClient(container)\n  const scope: Scope = {\n    tenantId: payload.tenantId,\n    organizationId: payload.organizationId,\n  }\n\n  // Activation runs first and creates the account. If it's missing,\n  // there is nothing to amend \u2014 the queue will have retried activation.\n  const account = await billingApi.findAccountByCustomer(scope, payload.customerId)\n  if (!account) return\n\n  // 1. New Billing Items for every added charge.\n  const itemsToCreate = mapSubscriptionItemsToBillingItems({\n    subscriptionId: payload.subscriptionId,\n    items: added,\n    billStartDate: payload.effectiveDate,\n  }).map((item) => ({\n    billAccountId: account.id,\n    type: item.type,\n    billStartDate: item.billStartDate,\n    description: item.description,\n    rateJson: item.rateJson,\n    subscriptionId: item.subscriptionId,\n    subscriptionItemId: item.subscriptionItemId,\n    sourceRef: item.sourceRef,\n  }))\n\n  // 2. Mid-cycle proration. The billing cycle the amend lands in is\n  // derived from the account here \u2014 CPQ does not own the billing cycle.\n  if (added.length > 0) {\n    const period = cycleContaining(\n      account.nextBillDate,\n      account.billCycle as BillCycle,\n      payload.effectiveDate,\n    )\n    const cycleEnd = period.periodEnd.toISOString().slice(0, 10)\n    const daysInPeriod = inclusiveDays(period.periodStart, period.periodEnd)\n    const daysRemaining = inclusiveDays(payload.effectiveDate, period.periodEnd)\n\n    for (const addedItem of added) {\n      for (const charge of addedItem.charges) {\n        if (charge.type !== 'recurring' || typeof charge.unitPrice !== 'number') {\n          continue\n        }\n        const { amount } = computeProration({\n          unitPrice: charge.unitPrice,\n          quantity: addedItem.quantity,\n          daysInPeriod,\n          daysRemaining,\n        })\n        if (amount === 0) continue\n        itemsToCreate.push({\n          billAccountId: account.id,\n          type: 'one_time',\n          billStartDate: payload.effectiveDate,\n          description: formatProrationDescription({\n            productName: addedItem.productName,\n            effectiveDate: payload.effectiveDate,\n            cycleEnd,\n          }),\n          rateJson: { amount },\n          subscriptionId: payload.subscriptionId,\n          subscriptionItemId: addedItem.subscriptionItemId,\n          sourceRef: `cpq-${payload.subscriptionId}-${addedItem.subscriptionItemId}-proration-${payload.effectiveDate}`,\n        })\n      }\n    }\n  }\n\n  await billingApi.bulkCreateItems(scope, itemsToCreate)\n\n  // 3. End-date every Billing Item of each removed subscription item.\n  const endDate = isoDateMinusOneDay(payload.effectiveDate)\n  for (const removedSubItemId of removed) {\n    const items = await billingApi.findItemsBySubscriptionItem(scope, removedSubItemId)\n    for (const item of items) {\n      await billingApi.updateItem(scope, {\n        id: item.id,\n        billEndDate: endDate,\n      })\n    }\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,8BAA8B;AASvC,SAAS,uBAAuB;AAEhC,SAAS,wBAAoC;AAC7C;AAAA,EACE;AAAA,OAEK;AACP;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAmBA,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAaA,MAAM,SAAS;AAEf,SAAS,aAAa,OAA8B;AAClD,QAAM,IACJ,iBAAiB,OACb,IAAI,KAAK,MAAM,QAAQ,CAAC,IACxB,oBAAI,KAAK,GAAG,KAAK,gBAAgB;AACvC,IAAE,YAAY,GAAG,GAAG,GAAG,CAAC;AACxB,SAAO,EAAE,QAAQ;AACnB;AAGA,SAAS,cAAc,MAAqB,IAA2B;AACrE,SAAO,KAAK,OAAO,aAAa,EAAE,IAAI,aAAa,IAAI,KAAK,MAAM,IAAI;AACxE;AAEA,SAAS,mBAAmB,KAAqB;AAC/C,QAAM,IAAI,oBAAI,KAAK,GAAG,GAAG,gBAAgB;AACzC,IAAE,WAAW,EAAE,WAAW,IAAI,CAAC;AAC/B,SAAO,EAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AACpC;AAEA,eAAO,OAA8B,SAAwC;AAC3E,MAAI,CAAC,SAAS,YAAY,CAAC,QAAQ,eAAgB;AACnD,MAAI,CAAC,QAAQ,kBAAkB,CAAC,QAAQ,cAAe;AAEvD,QAAM,QAAQ,QAAQ,cAAc,CAAC;AACrC,QAAM,UAAU,QAAQ,8BAA8B,CAAC;AACvD,MAAI,MAAM,WAAW,KAAK,QAAQ,WAAW,EAAG;AAEhD,QAAM,YAAY,MAAM,uBAAuB;AAC/C,QAAM,aAAa,IAAI,iBAAiB,SAAS;AACjD,QAAM,QAAe;AAAA,IACnB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,EAC1B;AAIA,QAAM,UAAU,MAAM,WAAW,sBAAsB,OAAO,QAAQ,UAAU;AAChF,MAAI,CAAC,QAAS;AAGd,QAAM,gBAAgB,mCAAmC;AAAA,IACvD,gBAAgB,QAAQ;AAAA,IACxB,OAAO;AAAA,IACP,eAAe,QAAQ;AAAA,EACzB,CAAC,EAAE,IAAI,CAAC,UAAU;AAAA,IAChB,eAAe,QAAQ;AAAA,IACvB,MAAM,KAAK;AAAA,IACX,eAAe,KAAK;AAAA,IACpB,aAAa,KAAK;AAAA,IAClB,UAAU,KAAK;AAAA,IACf,gBAAgB,KAAK;AAAA,IACrB,oBAAoB,KAAK;AAAA,IACzB,WAAW,KAAK;AAAA,EAClB,EAAE;AAIF,MAAI,MAAM,SAAS,GAAG;AACpB,UAAM,SAAS;AAAA,MACb,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,QAAQ;AAAA,IACV;AACA,UAAM,WAAW,OAAO,UAAU,YAAY,EAAE,MAAM,GAAG,EAAE;AAC3D,UAAM,eAAe,cAAc,OAAO,aAAa,OAAO,SAAS;AACvE,UAAM,gBAAgB,cAAc,QAAQ,eAAe,OAAO,SAAS;AAE3E,eAAW,aAAa,OAAO;AAC7B,iBAAW,UAAU,UAAU,SAAS;AACtC,YAAI,OAAO,SAAS,eAAe,OAAO,OAAO,cAAc,UAAU;AACvE;AAAA,QACF;AACA,cAAM,EAAE,OAAO,IAAI,iBAAiB;AAAA,UAClC,WAAW,OAAO;AAAA,UAClB,UAAU,UAAU;AAAA,UACpB;AAAA,UACA;AAAA,QACF,CAAC;AACD,YAAI,WAAW,EAAG;AAClB,sBAAc,KAAK;AAAA,UACjB,eAAe,QAAQ;AAAA,UACvB,MAAM;AAAA,UACN,eAAe,QAAQ;AAAA,UACvB,aAAa,2BAA2B;AAAA,YACtC,aAAa,UAAU;AAAA,YACvB,eAAe,QAAQ;AAAA,YACvB;AAAA,UACF,CAAC;AAAA,UACD,UAAU,EAAE,OAAO;AAAA,UACnB,gBAAgB,QAAQ;AAAA,UACxB,oBAAoB,UAAU;AAAA,UAC9B,WAAW,OAAO,QAAQ,cAAc,IAAI,UAAU,kBAAkB,cAAc,QAAQ,aAAa;AAAA,QAC7G,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAEA,QAAM,WAAW,gBAAgB,OAAO,aAAa;AAGrD,QAAM,UAAU,mBAAmB,QAAQ,aAAa;AACxD,aAAW,oBAAoB,SAAS;AACtC,UAAM,QAAQ,MAAM,WAAW,4BAA4B,OAAO,gBAAgB;AAClF,eAAW,QAAQ,OAAO;AACxB,YAAM,WAAW,WAAW,OAAO;AAAA,QACjC,IAAI,KAAK;AAAA,QACT,aAAa;AAAA,MACf,CAAC;AAAA,IACH;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-cancelled.js

@@ -0,0 +1,39 @@
+import { createRequestContainer } from "@open-mercato/shared/lib/di/container";
+import { BillingApiClient } from "../lib/billingApiClient.js";
+const metadata = {
+  event: "cpq.subscription.cancelled",
+  persistent: true,
+  id: "cpq-billing-connector:subscription-cancelled"
+};
+function isoDateMinusOneDay(iso) {
+  const d = /* @__PURE__ */ new Date(`${iso}T00:00:00.000Z`);
+  d.setUTCDate(d.getUTCDate() - 1);
+  return d.toISOString().slice(0, 10);
+}
+async function handle(payload) {
+  if (!payload?.tenantId || !payload.organizationId) return;
+  if (!payload.subscriptionId || !payload.effectiveDate) return;
+  const container = await createRequestContainer();
+  const billingApi = new BillingApiClient(container);
+  const scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId
+  };
+  const items = await billingApi.findItemsBySubscription(scope, payload.subscriptionId);
+  if (items.length === 0) return;
+  const endDate = isoDateMinusOneDay(payload.effectiveDate);
+  for (const item of items) {
+    if (item.billEndDate && item.billEndDate.toISOString().slice(0, 10) === endDate) {
+      continue;
+    }
+    await billingApi.updateItem(scope, {
+      id: item.id,
+      billEndDate: endDate
+    });
+  }
+}
+export {
+  handle as default,
+  metadata
+};
+//# sourceMappingURL=cpq-subscription-cancelled.js.map

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-cancelled.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/cpq_billing_connector/subscribers/cpq-subscription-cancelled.ts"],
+  "sourcesContent": ["import { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport { BillingApiClient, type Scope } from '../lib/billingApiClient'\n\n/**\n * Subscriber: `cpq.subscription.cancelled` \u2192 set bill_end_date on\n * every billing item attached to the subscription.\n *\n * The connector uses the spec's `effectiveDate` (cancellation date)\n * minus one day as `bill_end_date` so the engine's recurring\n * selector stops including the item from the cycle containing the\n * cancellation onward.\n *\n * Final-period proration / refund credits (per spec) are issued by\n * CPQ \u2014 the connector does not invent them here. If a credit is\n * needed, CPQ posts a negative `one_time` Billing Item via this\n * same connector path (e.g. an `amend` event preceding the cancel).\n */\n\nexport const metadata = {\n  event: 'cpq.subscription.cancelled',\n  persistent: true,\n  id: 'cpq-billing-connector:subscription-cancelled',\n}\n\ntype CancelledPayload = {\n  tenantId: string\n  organizationId: string\n  subscriptionId: string\n  /** YYYY-MM-DD; the date the cancellation takes effect. */\n  effectiveDate: string\n}\n\nfunction isoDateMinusOneDay(iso: string): string {\n  const d = new Date(`${iso}T00:00:00.000Z`)\n  d.setUTCDate(d.getUTCDate() - 1)\n  return d.toISOString().slice(0, 10)\n}\n\nexport default async function handle(payload: CancelledPayload): Promise<void> {\n  if (!payload?.tenantId || !payload.organizationId) return\n  if (!payload.subscriptionId || !payload.effectiveDate) return\n\n  const container = await createRequestContainer()\n  const billingApi = new BillingApiClient(container)\n  const scope: Scope = {\n    tenantId: payload.tenantId,\n    organizationId: payload.organizationId,\n  }\n\n  const items = await billingApi.findItemsBySubscription(scope, payload.subscriptionId)\n  if (items.length === 0) return\n\n  const endDate = isoDateMinusOneDay(payload.effectiveDate)\n  for (const item of items) {\n    // Idempotency: skip if already end-dated to this exact date.\n    if (item.billEndDate && item.billEndDate.toISOString().slice(0, 10) === endDate) {\n      continue\n    }\n    await billingApi.updateItem(scope, {\n      id: item.id,\n      billEndDate: endDate,\n    })\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,8BAA8B;AACvC,SAAS,wBAAoC;AAiBtC,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAUA,SAAS,mBAAmB,KAAqB;AAC/C,QAAM,IAAI,oBAAI,KAAK,GAAG,GAAG,gBAAgB;AACzC,IAAE,WAAW,EAAE,WAAW,IAAI,CAAC;AAC/B,SAAO,EAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AACpC;AAEA,eAAO,OAA8B,SAA0C;AAC7E,MAAI,CAAC,SAAS,YAAY,CAAC,QAAQ,eAAgB;AACnD,MAAI,CAAC,QAAQ,kBAAkB,CAAC,QAAQ,cAAe;AAEvD,QAAM,YAAY,MAAM,uBAAuB;AAC/C,QAAM,aAAa,IAAI,iBAAiB,SAAS;AACjD,QAAM,QAAe;AAAA,IACnB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,EAC1B;AAEA,QAAM,QAAQ,MAAM,WAAW,wBAAwB,OAAO,QAAQ,cAAc;AACpF,MAAI,MAAM,WAAW,EAAG;AAExB,QAAM,UAAU,mBAAmB,QAAQ,aAAa;AACxD,aAAW,QAAQ,OAAO;AAExB,QAAI,KAAK,eAAe,KAAK,YAAY,YAAY,EAAE,MAAM,GAAG,EAAE,MAAM,SAAS;AAC/E;AAAA,IACF;AACA,UAAM,WAAW,WAAW,OAAO;AAAA,MACjC,IAAI,KAAK;AAAA,MACT,aAAa;AAAA,IACf,CAAC;AAAA,EACH;AACF;",
+  "names": []
+}

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-merged.js

@@ -0,0 +1,32 @@
+import { createRequestContainer } from "@open-mercato/shared/lib/di/container";
+import { BillingApiClient } from "../lib/billingApiClient.js";
+const metadata = {
+  event: "cpq.subscription.merged",
+  persistent: true,
+  id: "cpq-billing-connector:subscription-merged"
+};
+async function handle(payload) {
+  if (!payload?.tenantId || !payload.organizationId) return;
+  if (!payload.mergedSubscriptionId || !Array.isArray(payload.sourceSubscriptionIds)) return;
+  if (payload.sourceSubscriptionIds.length === 0) return;
+  const container = await createRequestContainer();
+  const billingApi = new BillingApiClient(container);
+  const scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId
+  };
+  for (const sourceId of payload.sourceSubscriptionIds) {
+    const items = await billingApi.findItemsBySubscription(scope, sourceId);
+    for (const item of items) {
+      await billingApi.updateItem(scope, {
+        id: item.id,
+        subscriptionId: payload.mergedSubscriptionId
+      });
+    }
+  }
+}
+export {
+  handle as default,
+  metadata
+};
+//# sourceMappingURL=cpq-subscription-merged.js.map

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-merged.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/cpq_billing_connector/subscribers/cpq-subscription-merged.ts"],
+  "sourcesContent": ["import { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport { BillingApiClient, type Scope } from '../lib/billingApiClient'\n\n/**\n * Subscriber: `cpq.subscription.merged` \u2192 re-link items to the\n * merged subscription.\n *\n * Per the spec: \"Move Billing Items from source subscriptions to\n * the merged subscription (update `subscription_id`).\" This keeps\n * the audit trail continuous \u2014 same Billing Items, just pointing\n * at the new subscription so any future lookup by subscription_id\n * lands at the merged target.\n *\n * The source subscriptions transition to the terminal `superseded`\n * status in CPQ; the `superseded` subscriber separately end-dates\n * any items still pointing at the source ids (defense in depth \u2014 if\n * a race left an item un-relinked, superseded catches it).\n */\n\nexport const metadata = {\n  event: 'cpq.subscription.merged',\n  persistent: true,\n  id: 'cpq-billing-connector:subscription-merged',\n}\n\ntype MergedPayload = {\n  tenantId: string\n  organizationId: string\n  /** The new merged subscription's id (the survivor). */\n  mergedSubscriptionId: string\n  /** The source subscriptions absorbed into the merge. */\n  sourceSubscriptionIds: string[]\n}\n\nexport default async function handle(payload: MergedPayload): Promise<void> {\n  if (!payload?.tenantId || !payload.organizationId) return\n  if (!payload.mergedSubscriptionId || !Array.isArray(payload.sourceSubscriptionIds)) return\n  if (payload.sourceSubscriptionIds.length === 0) return\n\n  const container = await createRequestContainer()\n  const billingApi = new BillingApiClient(container)\n  const scope: Scope = {\n    tenantId: payload.tenantId,\n    organizationId: payload.organizationId,\n  }\n\n  for (const sourceId of payload.sourceSubscriptionIds) {\n    const items = await billingApi.findItemsBySubscription(scope, sourceId)\n    for (const item of items) {\n      await billingApi.updateItem(scope, {\n        id: item.id,\n        subscriptionId: payload.mergedSubscriptionId,\n      })\n    }\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,8BAA8B;AACvC,SAAS,wBAAoC;AAkBtC,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAWA,eAAO,OAA8B,SAAuC;AAC1E,MAAI,CAAC,SAAS,YAAY,CAAC,QAAQ,eAAgB;AACnD,MAAI,CAAC,QAAQ,wBAAwB,CAAC,MAAM,QAAQ,QAAQ,qBAAqB,EAAG;AACpF,MAAI,QAAQ,sBAAsB,WAAW,EAAG;AAEhD,QAAM,YAAY,MAAM,uBAAuB;AAC/C,QAAM,aAAa,IAAI,iBAAiB,SAAS;AACjD,QAAM,QAAe;AAAA,IACnB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,EAC1B;AAEA,aAAW,YAAY,QAAQ,uBAAuB;AACpD,UAAM,QAAQ,MAAM,WAAW,wBAAwB,OAAO,QAAQ;AACtE,eAAW,QAAQ,OAAO;AACxB,YAAM,WAAW,WAAW,OAAO;AAAA,QACjC,IAAI,KAAK;AAAA,QACT,gBAAgB,QAAQ;AAAA,MAC1B,CAAC;AAAA,IACH;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-renewed.js

@@ -0,0 +1,53 @@
+import { createRequestContainer } from "@open-mercato/shared/lib/di/container";
+import { BillingApiClient } from "../lib/billingApiClient.js";
+import {
+  mapSubscriptionItemsToBillingItems
+} from "../lib/chargeMapper.js";
+const metadata = {
+  event: "cpq.subscription.renewed",
+  persistent: true,
+  id: "cpq-billing-connector:subscription-renewed"
+};
+async function handle(payload) {
+  if (!payload?.tenantId || !payload.organizationId) return;
+  if (!payload.subscriptionId || !payload.newTermStart) return;
+  const container = await createRequestContainer();
+  const billingApi = new BillingApiClient(container);
+  const scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId
+  };
+  const existingItems = await billingApi.findItemsBySubscription(scope, payload.subscriptionId);
+  for (const item of existingItems) {
+    if (!item.billEndDate) continue;
+    await billingApi.updateItem(scope, {
+      id: item.id,
+      billEndDate: payload.newTermEnd ?? null
+    });
+  }
+  const accountId = existingItems[0]?.billAccountId ?? (await billingApi.findAccountByCustomer(scope, payload.customerId))?.id ?? null;
+  if (!accountId) return;
+  const newPayloads = mapSubscriptionItemsToBillingItems({
+    subscriptionId: payload.subscriptionId,
+    items: payload.addedItems ?? [],
+    billStartDate: payload.newTermStart
+  });
+  await billingApi.bulkCreateItems(
+    scope,
+    newPayloads.map((item) => ({
+      billAccountId: accountId,
+      type: item.type,
+      billStartDate: item.billStartDate,
+      description: item.description,
+      rateJson: item.rateJson,
+      subscriptionId: item.subscriptionId,
+      subscriptionItemId: item.subscriptionItemId,
+      sourceRef: item.sourceRef
+    }))
+  );
+}
+export {
+  handle as default,
+  metadata
+};
+//# sourceMappingURL=cpq-subscription-renewed.js.map

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-renewed.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/cpq_billing_connector/subscribers/cpq-subscription-renewed.ts"],
+  "sourcesContent": ["import { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport { BillingApiClient, type Scope } from '../lib/billingApiClient'\nimport {\n  mapSubscriptionItemsToBillingItems,\n  type CpqSubscriptionItem,\n} from '../lib/chargeMapper'\n\n/**\n * Subscriber: `cpq.subscription.renewed` \u2192 extend term + add items.\n *\n * On renewal the existing items either:\n *   - Stay active (no `bill_end_date` set, so the engine keeps\n *     billing them as recurring) \u2014 connector touches nothing.\n *   - Had a previously-set `bill_end_date` (e.g. fixed-term\n *     subscription) \u2014 connector clears or extends it to the new\n *     term's end (`newTermEnd` from the payload).\n *\n * New items added at renewal (e.g. upsell at renewal time) are\n * created with `bill_start_date = newTermStart`, same shape as\n * activation.\n *\n * The connector does NOT post a proration line for renewals \u2014 by\n * definition renewal happens at the cycle boundary (or it's an early\n * renewal, which the integrator should issue as `amend` + `renew`\n * via the spec's ARC flow rather than this single event).\n */\n\nexport const metadata = {\n  event: 'cpq.subscription.renewed',\n  persistent: true,\n  id: 'cpq-billing-connector:subscription-renewed',\n}\n\ntype RenewedPayload = {\n  tenantId: string\n  organizationId: string\n  subscriptionId: string\n  customerId: string\n  newTermStart: string\n  newTermEnd?: string | null\n  addedItems?: CpqSubscriptionItem[]\n}\n\nexport default async function handle(payload: RenewedPayload): Promise<void> {\n  if (!payload?.tenantId || !payload.organizationId) return\n  if (!payload.subscriptionId || !payload.newTermStart) return\n\n  const container = await createRequestContainer()\n  const billingApi = new BillingApiClient(container)\n  const scope: Scope = {\n    tenantId: payload.tenantId,\n    organizationId: payload.organizationId,\n  }\n\n  const existingItems = await billingApi.findItemsBySubscription(scope, payload.subscriptionId)\n\n  // Extend the bill_end_date on items that had one. Items without\n  // an end date are open-ended; nothing to do.\n  for (const item of existingItems) {\n    if (!item.billEndDate) continue\n    await billingApi.updateItem(scope, {\n      id: item.id,\n      billEndDate: payload.newTermEnd ?? null,\n    })\n  }\n\n  // Add new items at the renewal boundary.\n  const accountId =\n    existingItems[0]?.billAccountId ??\n    (await billingApi.findAccountByCustomer(scope, payload.customerId))?.id ??\n    null\n  if (!accountId) return\n\n  const newPayloads = mapSubscriptionItemsToBillingItems({\n    subscriptionId: payload.subscriptionId,\n    items: payload.addedItems ?? [],\n    billStartDate: payload.newTermStart,\n  })\n  await billingApi.bulkCreateItems(\n    scope,\n    newPayloads.map((item) => ({\n      billAccountId: accountId,\n      type: item.type,\n      billStartDate: item.billStartDate,\n      description: item.description,\n      rateJson: item.rateJson,\n      subscriptionId: item.subscriptionId,\n      subscriptionItemId: item.subscriptionItemId,\n      sourceRef: item.sourceRef,\n    })),\n  )\n}\n"],
+  "mappings": "AAAA,SAAS,8BAA8B;AACvC,SAAS,wBAAoC;AAC7C;AAAA,EACE;AAAA,OAEK;AAsBA,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAYA,eAAO,OAA8B,SAAwC;AAC3E,MAAI,CAAC,SAAS,YAAY,CAAC,QAAQ,eAAgB;AACnD,MAAI,CAAC,QAAQ,kBAAkB,CAAC,QAAQ,aAAc;AAEtD,QAAM,YAAY,MAAM,uBAAuB;AAC/C,QAAM,aAAa,IAAI,iBAAiB,SAAS;AACjD,QAAM,QAAe;AAAA,IACnB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,EAC1B;AAEA,QAAM,gBAAgB,MAAM,WAAW,wBAAwB,OAAO,QAAQ,cAAc;AAI5F,aAAW,QAAQ,eAAe;AAChC,QAAI,CAAC,KAAK,YAAa;AACvB,UAAM,WAAW,WAAW,OAAO;AAAA,MACjC,IAAI,KAAK;AAAA,MACT,aAAa,QAAQ,cAAc;AAAA,IACrC,CAAC;AAAA,EACH;AAGA,QAAM,YACJ,cAAc,CAAC,GAAG,kBACjB,MAAM,WAAW,sBAAsB,OAAO,QAAQ,UAAU,IAAI,MACrE;AACF,MAAI,CAAC,UAAW;AAEhB,QAAM,cAAc,mCAAmC;AAAA,IACrD,gBAAgB,QAAQ;AAAA,IACxB,OAAO,QAAQ,cAAc,CAAC;AAAA,IAC9B,eAAe,QAAQ;AAAA,EACzB,CAAC;AACD,QAAM,WAAW;AAAA,IACf;AAAA,IACA,YAAY,IAAI,CAAC,UAAU;AAAA,MACzB,eAAe;AAAA,MACf,MAAM,KAAK;AAAA,MACX,eAAe,KAAK;AAAA,MACpB,aAAa,KAAK;AAAA,MAClB,UAAU,KAAK;AAAA,MACf,gBAAgB,KAAK;AAAA,MACrB,oBAAoB,KAAK;AAAA,MACzB,WAAW,KAAK;AAAA,IAClB,EAAE;AAAA,EACJ;AACF;",
+  "names": []
+}

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-superseded.js

@@ -0,0 +1,39 @@
+import { createRequestContainer } from "@open-mercato/shared/lib/di/container";
+import { BillingApiClient } from "../lib/billingApiClient.js";
+const metadata = {
+  event: "cpq.subscription.superseded",
+  persistent: true,
+  id: "cpq-billing-connector:subscription-superseded"
+};
+function isoDateMinusOneDay(iso) {
+  const d = /* @__PURE__ */ new Date(`${iso}T00:00:00.000Z`);
+  d.setUTCDate(d.getUTCDate() - 1);
+  return d.toISOString().slice(0, 10);
+}
+async function handle(payload) {
+  if (!payload?.tenantId || !payload.organizationId) return;
+  if (!payload.subscriptionId || !payload.effectiveDate) return;
+  const container = await createRequestContainer();
+  const billingApi = new BillingApiClient(container);
+  const scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId
+  };
+  const stragglers = await billingApi.findItemsBySubscription(scope, payload.subscriptionId);
+  if (stragglers.length === 0) return;
+  const endDate = isoDateMinusOneDay(payload.effectiveDate);
+  for (const item of stragglers) {
+    if (item.billEndDate && item.billEndDate.toISOString().slice(0, 10) === endDate) {
+      continue;
+    }
+    await billingApi.updateItem(scope, {
+      id: item.id,
+      billEndDate: endDate
+    });
+  }
+}
+export {
+  handle as default,
+  metadata
+};
+//# sourceMappingURL=cpq-subscription-superseded.js.map

package/dist/modules/cpq_billing_connector/subscribers/cpq-subscription-superseded.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/cpq_billing_connector/subscribers/cpq-subscription-superseded.ts"],
+  "sourcesContent": ["import { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport { BillingApiClient, type Scope } from '../lib/billingApiClient'\n\n/**\n * Subscriber: `cpq.subscription.superseded` \u2192 end-date items still\n * pointing at a superseded source.\n *\n * Per the spec's XD-250 ARC notes, merge-renewal produces a brand\n * new subscription (the \"merge target\") and transitions the source\n * subscriptions to `superseded`. The `merged` subscriber already\n * re-links Billing Items to the target \u2014 this subscriber is the\n * defense-in-depth net: if any items remain attached to the\n * superseded source (re-link missed them, race, manual fix-up),\n * end-date them at the supersession effective date so the engine\n * stops billing them.\n *\n * In the steady-state \"no race\" path, this subscriber finds zero\n * items and is a no-op \u2014 which is fine.\n */\n\nexport const metadata = {\n  event: 'cpq.subscription.superseded',\n  persistent: true,\n  id: 'cpq-billing-connector:subscription-superseded',\n}\n\ntype SupersededPayload = {\n  tenantId: string\n  organizationId: string\n  /** The id that is being superseded (the OLD subscription). */\n  subscriptionId: string\n  /** YYYY-MM-DD; when the supersession took effect. */\n  effectiveDate: string\n}\n\nfunction isoDateMinusOneDay(iso: string): string {\n  const d = new Date(`${iso}T00:00:00.000Z`)\n  d.setUTCDate(d.getUTCDate() - 1)\n  return d.toISOString().slice(0, 10)\n}\n\nexport default async function handle(payload: SupersededPayload): Promise<void> {\n  if (!payload?.tenantId || !payload.organizationId) return\n  if (!payload.subscriptionId || !payload.effectiveDate) return\n\n  const container = await createRequestContainer()\n  const billingApi = new BillingApiClient(container)\n  const scope: Scope = {\n    tenantId: payload.tenantId,\n    organizationId: payload.organizationId,\n  }\n\n  const stragglers = await billingApi.findItemsBySubscription(scope, payload.subscriptionId)\n  if (stragglers.length === 0) return\n\n  const endDate = isoDateMinusOneDay(payload.effectiveDate)\n  for (const item of stragglers) {\n    if (item.billEndDate && item.billEndDate.toISOString().slice(0, 10) === endDate) {\n      continue\n    }\n    await billingApi.updateItem(scope, {\n      id: item.id,\n      billEndDate: endDate,\n    })\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,8BAA8B;AACvC,SAAS,wBAAoC;AAmBtC,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAWA,SAAS,mBAAmB,KAAqB;AAC/C,QAAM,IAAI,oBAAI,KAAK,GAAG,GAAG,gBAAgB;AACzC,IAAE,WAAW,EAAE,WAAW,IAAI,CAAC;AAC/B,SAAO,EAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AACpC;AAEA,eAAO,OAA8B,SAA2C;AAC9E,MAAI,CAAC,SAAS,YAAY,CAAC,QAAQ,eAAgB;AACnD,MAAI,CAAC,QAAQ,kBAAkB,CAAC,QAAQ,cAAe;AAEvD,QAAM,YAAY,MAAM,uBAAuB;AAC/C,QAAM,aAAa,IAAI,iBAAiB,SAAS;AACjD,QAAM,QAAe;AAAA,IACnB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,EAC1B;AAEA,QAAM,aAAa,MAAM,WAAW,wBAAwB,OAAO,QAAQ,cAAc;AACzF,MAAI,WAAW,WAAW,EAAG;AAE7B,QAAM,UAAU,mBAAmB,QAAQ,aAAa;AACxD,aAAW,QAAQ,YAAY;AAC7B,QAAI,KAAK,eAAe,KAAK,YAAY,YAAY,EAAE,MAAM,GAAG,EAAE,MAAM,SAAS;AAC/E;AAAA,IACF;AACA,UAAM,WAAW,WAAW,OAAO;AAAA,MACjC,IAAI,KAAK;AAAA,MACT,aAAa;AAAA,IACf,CAAC;AAAA,EACH;AACF;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@dainamite/cpq-billing-connector",
+  "version": "0.1.0",
+  "description": "Wires @dainamite/cpq subscription lifecycle events to @dainamite/billing API calls (activated / amended / renewed / cancelled / merged / superseded).",
+  "type": "module",
+  "main": "./dist/modules/cpq_billing_connector/index.js",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "chokidar": "^4.0.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/modules/cpq_billing_connector/index.ts",
+      "default": "./dist/modules/cpq_billing_connector/index.js"
+    },
+    "./modules/cpq_billing_connector": {
+      "types": "./src/modules/cpq_billing_connector/index.ts",
+      "default": "./dist/modules/cpq_billing_connector/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.tsx": {
+      "types": "./src/*.tsx",
+      "default": "./dist/*.js"
+    },
+    "./*.json": "./src/*.json",
+    "./*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*.json": "./src/*/*.json",
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts",
+        "./src/*/*.tsx"
+      ],
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*.json": "./src/*/*/*.json",
+    "./*/*/*": {
+      "types": [
+        "./src/*/*/*.ts",
+        "./src/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*/*.json": "./src/*/*/*/*.json",
+    "./*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*.ts",
+        "./src/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*.js"
+    },
+    "./*/*/*/*/*.json": "./src/*/*/*/*/*.json",
+    "./*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*.js"
+    },
+    "./*/*/*/*/*/*.json": "./src/*/*/*/*/*/*.json",
+    "./*/*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*/*.js"
+    },
+    "./*/*/*/*/*/*/*.json": "./src/*/*/*/*/*/*/*.json",
+    "./*/*/*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*/*/*.js"
+    }
+  },
+  "peerDependencies": {
+    "@dainamite/billing": "^0.17.0",
+    "@dainamite/cpq": "^0.3.0",
+    "@mikro-orm/core": "^7.0.0",
+    "@mikro-orm/decorators": "^7.0.0",
+    "@mikro-orm/postgresql": "^7.0.0",
+    "@open-mercato/core": "^0.6.0",
+    "@open-mercato/events": "^0.6.0",
+    "@open-mercato/shared": "^0.6.0",
+    "awilix": "^12.0.0",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dainamite-technologies/dainamite-core.git",
+    "directory": "packages/cpq-billing-connector"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/src/modules/cpq_billing_connector/__tests__/lib/chargeMapper.test.ts

@@ -0,0 +1,158 @@
+import {
+  buildSourceRef,
+  mapChargeToBillingItem,
+  mapSubscriptionItemsToBillingItems,
+  type CpqCharge,
+  type CpqSubscriptionItem,
+} from '../../lib/chargeMapper'
+
+const SUB_ID = 'sub-1'
+const SUB_ITEM_ID = 'sub-item-1'
+const BILL_START = '2026-05-01'
+
+function subItem(charges: CpqCharge[], overrides: Partial<CpqSubscriptionItem> = {}): CpqSubscriptionItem {
+  return {
+    subscriptionItemId: overrides.subscriptionItemId ?? SUB_ITEM_ID,
+    productName: overrides.productName ?? 'Plan Pro',
+    quantity: overrides.quantity ?? 1,
+    charges,
+  }
+}
+
+describe('buildSourceRef', () => {
+  it('produces a deterministic key including all 3 components', () => {
+    expect(buildSourceRef('s1', 'i1', 'recurring')).toBe('cpq-s1-i1-recurring')
+  })
+
+  it('different charge types yield different keys for the same item', () => {
+    expect(buildSourceRef('s1', 'i1', 'recurring')).not.toEqual(
+      buildSourceRef('s1', 'i1', 'one_time'),
+    )
+  })
+})
+
+describe('mapChargeToBillingItem — one_time', () => {
+  it('maps a well-formed one_time charge', () => {
+    const charge: CpqCharge = { type: 'one_time', amount: 99, description: 'Activation fee' }
+    const result = mapChargeToBillingItem({
+      subscriptionId: SUB_ID,
+      subscriptionItem: subItem([charge]),
+      charge,
+      billStartDate: BILL_START,
+    })
+    expect(result).toMatchObject({
+      type: 'one_time',
+      description: 'Plan Pro — Activation fee',
+      rateJson: { amount: 99 },
+      subscriptionId: SUB_ID,
+      subscriptionItemId: SUB_ITEM_ID,
+      sourceRef: `cpq-${SUB_ID}-${SUB_ITEM_ID}-one_time`,
+      billStartDate: BILL_START,
+    })
+  })
+
+  it('returns null when one_time is missing amount', () => {
+    const charge = { type: 'one_time' as const, description: 'No amount' }
+    const result = mapChargeToBillingItem({
+      subscriptionId: SUB_ID,
+      subscriptionItem: subItem([charge]),
+      charge,
+      billStartDate: BILL_START,
+    })
+    expect(result).toBeNull()
+  })
+})
+
+describe('mapChargeToBillingItem — recurring', () => {
+  it('maps a well-formed recurring charge to unit_price rate_json', () => {
+    const charge: CpqCharge = { type: 'recurring', unitPrice: 49.99, description: 'MRC' }
+    const result = mapChargeToBillingItem({
+      subscriptionId: SUB_ID,
+      subscriptionItem: subItem([charge]),
+      charge,
+      billStartDate: BILL_START,
+    })
+    expect(result).toMatchObject({
+      type: 'recurring',
+      description: 'Plan Pro — MRC',
+      rateJson: { unit_price: 49.99 },
+      sourceRef: `cpq-${SUB_ID}-${SUB_ITEM_ID}-recurring`,
+    })
+  })
+
+  it('returns null when recurring is missing unitPrice', () => {
+    const charge = { type: 'recurring' as const, description: 'No price' }
+    const result = mapChargeToBillingItem({
+      subscriptionId: SUB_ID,
+      subscriptionItem: subItem([charge]),
+      charge,
+      billStartDate: BILL_START,
+    })
+    expect(result).toBeNull()
+  })
+})
+
+describe('mapSubscriptionItemsToBillingItems', () => {
+  it('one item with both one_time + recurring → TWO billing items (spec rule)', () => {
+    const item = subItem([
+      { type: 'one_time', amount: 99, description: 'Activation' },
+      { type: 'recurring', unitPrice: 49.99, description: 'MRC' },
+    ])
+    const result = mapSubscriptionItemsToBillingItems({
+      subscriptionId: SUB_ID,
+      items: [item],
+      billStartDate: BILL_START,
+    })
+    expect(result).toHaveLength(2)
+    expect(result.map((r) => r.type)).toEqual(['one_time', 'recurring'])
+    // Both items share the same subscriptionItemId but differ in sourceRef
+    // because the type is embedded in the key.
+    expect(result[0].sourceRef).not.toEqual(result[1].sourceRef)
+  })
+
+  it('skips malformed charges (no amount on one_time, no unitPrice on recurring)', () => {
+    const item = subItem([
+      { type: 'one_time', amount: 99, description: 'OK' },
+      { type: 'recurring', description: 'No price' }, // skipped
+      { type: 'one_time', description: 'No amount' }, // skipped
+    ])
+    const result = mapSubscriptionItemsToBillingItems({
+      subscriptionId: SUB_ID,
+      items: [item],
+      billStartDate: BILL_START,
+    })
+    expect(result).toHaveLength(1)
+    expect(result[0].rateJson).toEqual({ amount: 99 })
+  })
+
+  it('walks multiple subscription items independently', () => {
+    const a = subItem(
+      [{ type: 'recurring', unitPrice: 10, description: 'Plan A MRC' }],
+      { subscriptionItemId: 'i-a', productName: 'Plan A' },
+    )
+    const b = subItem(
+      [{ type: 'recurring', unitPrice: 20, description: 'Plan B MRC' }],
+      { subscriptionItemId: 'i-b', productName: 'Plan B' },
+    )
+    const result = mapSubscriptionItemsToBillingItems({
+      subscriptionId: SUB_ID,
+      items: [a, b],
+      billStartDate: BILL_START,
+    })
+    expect(result.map((r) => r.subscriptionItemId)).toEqual(['i-a', 'i-b'])
+    expect(result.map((r) => r.description)).toEqual([
+      'Plan A — Plan A MRC',
+      'Plan B — Plan B MRC',
+    ])
+  })
+
+  it('empty items array → empty result', () => {
+    expect(
+      mapSubscriptionItemsToBillingItems({
+        subscriptionId: SUB_ID,
+        items: [],
+        billStartDate: BILL_START,
+      }),
+    ).toEqual([])
+  })
+})