@dainamite/cpq-billing-connector 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @dainamite/cpq-billing-connector
 
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [34d3ac4]
+- Updated dependencies [d86651d]
+  - @dainamite/billing@0.22.0
+  - @dainamite/cpq@0.7.0
+
+## 3.1.0
+
+### Minor Changes
+
+- 486db4d: Bill runs catch up on every due cycle, bill recurring items in advance or in arrears, and prorate partial periods (billing Spec A).
+
+  **`@dainamite/billing`**
+
+  - **Every run catches up.** Manual or scheduled, in real, test or dry mode, a run bills every due bill date up to `asOfDate`, with one draft per bill date (capped at 60 per account). Test and dry runs simulate every cycle in memory without changing the account. **Breaking:** the `catchUp` trigger flag and the `catch_up` run column/response field are removed. A `catchUp` sent by an old client is ignored.
+  - **Charge timing per item.** Recurring items carry `chargeTiming` (`in_advance` by default, or `in_arrears`). **Behaviour change:** recurring items are now billed in advance by default, so `next_bill_date` marks the start of the period billed.
+  - **Proration per item.** `prorate` defaults to `true`. A partial period (the item starts or ends mid-cycle) is charged by calendar days instead of being skipped. An in-advance item that ends after it was billed gets a negative credit line for the unused days. With `prorate: false`, partial periods are skipped and reported.
+  - **Run outcomes** carry `cycles` (bill date, service period, status, lines, net, invoice). `warnings.skipped_items` lists items that were not billed and why. The run summary adds `cycles_processed`. The run detail page shows a Cycles table and a Skipped items table.
+  - **Draft invoices** carry `metadata.bill_date`, the de-duplication key, together with `test_run`. Test drafts and real drafts never block each other. Lines carry `service_period_start` / `service_period_end`, plus `proration` and `credit_for` where they apply.
+  - **Item form** gets Charge timing and Prorate partial periods fields. The items list gets a Timing column.
+  - **Migration** `Migration20261114100000_billing_cycle_semantics`. Run `yarn mercato db migrate`. See `MIGRATION.md`; reseeding is recommended.
+
+  **`@dainamite/cpq-billing-connector`**
+
+  - **Proration moves to billing.** `cpq.subscription.amended` no longer posts `one_time` proration items, because the billing engine prorates. Release together with billing: an older connector would double-charge.
+  - **First bill date.** New billing accounts start billing on the activation date (they used to start one month later), so the first period is billed in advance.
+  - Removes `lib/prorationHelper` and the runtime import of billing's `cycleContaining`.
+
+### Patch Changes
+
+- d126be2: Billing accounts for persons (B2C), an invoice-language picklist, and pages that return to their billing account.
+
+  **`@dainamite/billing`**
+
+  - **B2C accounts.** `BillingAccount.customer_kind` (`company` | `person`, default `company`) records which customers collection `customer_id` points into. It is set on create (`customerKind`) and immutable afterwards, like `customerId`. `GET /api/billing/accounts` returns `customer_kind` and accepts a `customerKind` filter. Migration `Migration20261114000000_billing_customer_kind` adds the column (additive; existing rows become `company`). Run `yarn mercato db migrate`.
+  - **Account form.** A Company / Person switch picks the customer lookup (`/api/customers/companies` or `/api/customers/people`). Picking a customer prefills name, invoice email and the primary address into empty fields only. Prefill that the operator has not edited is rolled back when they pick another customer.
+  - **Account list and detail** show the customer's name with a company / person icon (one batched lookup per kind per page) and add a Customer type filter. The detail links to the customer record. If the customers module is unavailable, the raw id is shown.
+  - **Invoice language** is now a picklist of the languages the invoice template supports (`en`, `pl`).
+    **Behaviour change:** `invoiceLanguage` values other than `en` / `pl` are now rejected with 400 on create and update. On create, `invoiceLanguage` is optional and defaults to `en`.
+  - **Navigation.** Item pages opened from a billing account return to that account (back link, after delete). Creating an item from an account returns to the account after save or cancel. Items opened from the global Items list (`?from=items`) still return to the list.
+
+  **`@dainamite/cpq-billing-connector`**
+
+  - Passes an optional `customerKind` from `cpq.subscription.activated` to the billing account it creates.
+  - Normalises `invoiceLanguage` and falls back to `en` for languages billing does not support, so onboarding never fails on an unsupported code.
+
+- c8a1bf7: Billing invoices become real VAT documents with a PDF and email delivery (billing Spec B).
+
+  - **VAT per line.** Billing items carry `taxRate` (filled from the new organization default, 23 %, when omitted). Every invoice line gets net / VAT / gross; proration and credit lines inherit the item rate; manual lines accept `taxRate`. Existing items are migrated at 0 % (no silent re-pricing).
+  - **Seller settings.** Settings → Billing adds the seller block, bank / IBAN (checksum validated) / BIC, default payment terms and VAT rate, invoice footer and logo. **Posting is refused with 409 `billing.settings.incomplete` until legal name, address, tax id and IBAN are filled.**
+  - **Due dates and overdue.** Posting sets `due_date` (account terms or the default). The invoice list filters by `overdue`, `dueFrom`, `dueTo` and shows days overdue; the account page gets an Invoices section and `GET /api/billing/accounts/{id}/summary`.
+  - **PDF.** `GET /api/billing/invoices/{id}/pdf` — built-in A4 template in the account's invoice language (en / pl), frozen as an attachment at post; drafts are watermarked previews.
+  - **Email.** `POST /api/billing/invoices/{id}/send` (feature `billing.invoice.send`) and automatic sending per account (`autoSendInvoice`), through the platform `sendEmail()`. Deliveries are logged on the invoice; events `billing.invoice.sent` / `billing.invoice.send_failed`.
+  - **Dependencies:** `requires` adds `attachments`; new dependencies `pdf-lib` and `@pdf-lib/fontkit`.
+  - Connector: `ItemCreatePayload` accepts an optional `taxRate` (unused until CPQ exposes a per-charge rate).
+  - Run `yarn mercato db migrate` (`Migration20261116000000_billing_invoice_documents`).
+
+- Updated dependencies [d126be2]
+- Updated dependencies [486db4d]
+- Updated dependencies [c8a1bf7]
+- Updated dependencies [6c138f8]
+- Updated dependencies [418d67c]
+- Updated dependencies [3dc3fa5]
+- Updated dependencies [418d67c]
+  - @dainamite/billing@0.21.0
+
 ## 3.0.0
 
 ### Patch Changes

package/dist/modules/cpq_billing_connector/lib/billingApiClient.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/cpq_billing_connector/lib/billingApiClient.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport type { AwilixContainer } from 'awilix'\nimport type { CommandBus } from '@open-mercato/shared/lib/commands/command-bus'\n// TODO(L2-boundary): direct entity-class import couples the connector to\n// billing's internal ORM shape \u2014 violates the dainamite-layering rule that\n// cross-package coupling should be FK strings or REST. Tolerable at v0.1.x\n// because reads are em-driven for performance (one round-trip vs serialise/\n// deserialise via REST), but a `BillingAccount` / `BillingItem` rename in\n// `@dainamite/billing` will manifest here as a silent runtime crash.\n// Migrate to billing REST list endpoints once the connector graduates to\n// stable v1 \u2014 track in the dainamite-cpq packaging plan.\nimport { BillingAccount, BillingItem } from '@dainamite/billing/modules/billing/data/entities'\n\n/**\n * Thin facade the connector uses to talk to billing.\n *\n * Reads (existence checks, lookups by subscription) go through the\n * EM directly \u2014 billing's REST list endpoints would work, but going\n * via the EM is one round-trip instead of a serialize-then-deserialize\n * loop. Writes go through the billing command bus exclusively, so\n * there is one and only one write path for every billing state\n * mutation (the same path the REST routes invoke).\n *\n * Auth context: subscribers run as a system identity, not as a user.\n * The command-bus `ctx` therefore carries `auth: null` and the\n * tenant/organization explicitly. `ensureTenantScope` /\n * `ensureOrganizationScope` are no-ops when `ctx.auth` is null\n * (verified against `@open-mercato/shared/lib/commands/scope`) so\n * the explicit fields in the payload are the authority.\n */\n\nexport type Scope = {\n  tenantId: string\n  organizationId: string\n}\n\nexport type AccountSeed = {\n  customerId: string\n  name: string\n  currencyCode: string\n  billCycle: 'monthly' | 'quarterly' | 'annually' | 'weekly'\n  billCycleAnchor: string\n  invoiceEmail: string\n  invoiceLanguage: string\n  invoiceAddress: Record<string, unknown>\n  nextBillDate: Date\n  taxId?: string | null\n}\n\nexport type ItemCreatePayload = {\n  billAccountId: string\n  type: 'one_time' | 'recurring' | 'usage'\n  billStartDate: Date | string\n  billEndDate?: Date | string | null\n  description: string\n  rateJson: Record<string, unknown>\n  uomCode?: string\n  subscriptionId?: string\n  subscriptionItemId?: string\n  sourceRef?: string\n}\n\nexport type ItemUpdatePayload = {\n  id: string\n  billEndDate?: Date | string | null\n  subscriptionId?: string | null\n  subscriptionItemId?: string | null\n  isActive?: boolean\n}\n\nfunction buildSystemCtx(container: AwilixContainer, scope: Scope) {\n  return {\n    container,\n    auth: null,\n    organizationScope: null,\n    selectedOrganizationId: scope.organizationId,\n    organizationIds: [scope.organizationId],\n  }\n}\n\nexport class BillingApiClient {\n  private readonly em: EntityManager\n  private readonly commandBus: CommandBus\n\n  constructor(private readonly container: AwilixContainer) {\n    this.em = (container.resolve('em') as EntityManager).fork()\n    this.commandBus = container.resolve('commandBus') as CommandBus\n  }\n\n  // \u2500\u2500\u2500 Accounts \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n  /**\n   * Find a non-deleted Billing Account for `(tenant, organization,\n   * customer)`. Returns the first match or `null`. The connector\n   * uses this to skip account creation when the customer already\n   * has one.\n   */\n  async findAccountByCustomer(scope: Scope, customerId: string): Promise<BillingAccount | null> {\n    return this.em.findOne(BillingAccount, {\n      tenantId: scope.tenantId,\n      organizationId: scope.organizationId,\n      customerId,\n      deletedAt: null,\n    })\n  }\n\n  async createAccount(scope: Scope, seed: AccountSeed): Promise<{ id: string }> {\n    const result = await this.commandBus.execute('billing.accounts.create', {\n      input: {\n        tenantId: scope.tenantId,\n        organizationId: scope.organizationId,\n        ...seed,\n      },\n      ctx: buildSystemCtx(this.container, scope),\n    })\n    return (result as { result?: { id: string } }).result ?? { id: '' }\n  }\n\n  async getOrCreateAccount(scope: Scope, seed: AccountSeed): Promise<{ id: string; created: boolean }> {\n    const existing = await this.findAccountByCustomer(scope, seed.customerId)\n    if (existing) return { id: existing.id, created: false }\n    const created = await this.createAccount(scope, seed)\n    return { id: created.id, created: true }\n  }\n\n  // \u2500\u2500\u2500 Items \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n  async findItemsBySubscription(scope: Scope, subscriptionId: string): Promise<BillingItem[]> {\n    return this.em.find(BillingItem, {\n      tenantId: scope.tenantId,\n      organizationId: scope.organizationId,\n      subscriptionId,\n      deletedAt: null,\n    } as never)\n  }\n\n  async findItemsBySubscriptionItem(\n    scope: Scope,\n    subscriptionItemId: string,\n  ): Promise<BillingItem[]> {\n    return this.em.find(BillingItem, {\n      tenantId: scope.tenantId,\n      organizationId: scope.organizationId,\n      subscriptionItemId,\n      deletedAt: null,\n    } as never)\n  }\n\n  async createItem(\n    scope: Scope,\n    payload: ItemCreatePayload,\n  ): Promise<{ id: string; deduplicated: boolean }> {\n    const result = await this.commandBus.execute('billing.items.create', {\n      input: {\n        tenantId: scope.tenantId,\n        organizationId: scope.organizationId,\n        ...payload,\n      },\n      ctx: buildSystemCtx(this.container, scope),\n    })\n    const r = (result as { result?: { id: string; deduplicated: boolean } }).result\n    return r ?? { id: '', deduplicated: false }\n  }\n\n  /**\n   * Batch-create items in a single `billing.items.bulk_create`\n   * command. Use this whenever a subscriber has more than one item\n   * to create \u2014 it collapses N command-bus round-trips + N flushes\n   * into one. Idempotent per `source_ref` exactly like `createItem`.\n   *\n   * No-ops on an empty payload so callers skip the length guard.\n   */\n  async bulkCreateItems(\n    scope: Scope,\n    items: ItemCreatePayload[],\n  ): Promise<{\n    created: number\n    deduplicated: number\n    items: Array<{ sourceRef: string | null; id: string; deduplicated: boolean }>\n  }> {\n    if (items.length === 0) {\n      return { created: 0, deduplicated: 0, items: [] }\n    }\n    const result = await this.commandBus.execute('billing.items.bulk_create', {\n      input: {\n        tenantId: scope.tenantId,\n        organizationId: scope.organizationId,\n        items,\n      },\n      ctx: buildSystemCtx(this.container, scope),\n    })\n    const r = (\n      result as {\n        result?: {\n          created: number\n          deduplicated: number\n          items: Array<{ sourceRef: string | null; id: string; deduplicated: boolean }>\n        }\n      }\n    ).result\n    return r ?? { created: 0, deduplicated: 0, items: [] }\n  }\n\n  async updateItem(scope: Scope, payload: ItemUpdatePayload): Promise<{ id: string }> {\n    const result = await this.commandBus.execute('billing.items.update', {\n      input: {\n        tenantId: scope.tenantId,\n        organizationId: scope.organizationId,\n        ...payload,\n      },\n      ctx: buildSystemCtx(this.container, scope),\n    })\n    return (result as { result?: { id: string } }).result ?? { id: '' }\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport type { AwilixContainer } from 'awilix'\nimport type { CommandBus } from '@open-mercato/shared/lib/commands/command-bus'\n// TODO(L2-boundary): direct entity-class import couples the connector to\n// billing's internal ORM shape \u2014 violates the dainamite-layering rule that\n// cross-package coupling should be FK strings or REST. Tolerable at v0.1.x\n// because reads are em-driven for performance (one round-trip vs serialise/\n// deserialise via REST), but a `BillingAccount` / `BillingItem` rename in\n// `@dainamite/billing` will manifest here as a silent runtime crash.\n// Migrate to billing REST list endpoints once the connector graduates to\n// stable v1 \u2014 track in the dainamite-cpq packaging plan.\nimport { BillingAccount, BillingItem } from '@dainamite/billing/modules/billing/data/entities'\n\n/**\n * Thin facade the connector uses to talk to billing.\n *\n * Reads (existence checks, lookups by subscription) go through the\n * EM directly \u2014 billing's REST list endpoints would work, but going\n * via the EM is one round-trip instead of a serialize-then-deserialize\n * loop. Writes go through the billing command bus exclusively, so\n * there is one and only one write path for every billing state\n * mutation (the same path the REST routes invoke).\n *\n * Auth context: subscribers run as a system identity, not as a user.\n * The command-bus `ctx` therefore carries `auth: null` and the\n * tenant/organization explicitly. `ensureTenantScope` /\n * `ensureOrganizationScope` are no-ops when `ctx.auth` is null\n * (verified against `@open-mercato/shared/lib/commands/scope`) so\n * the explicit fields in the payload are the authority.\n */\n\nexport type Scope = {\n  tenantId: string\n  organizationId: string\n}\n\nexport type AccountSeed = {\n  customerId: string\n  /** 'company' (default when omitted) | 'person' \u2014 B2C accounts (billing Spec E). */\n  customerKind?: 'company' | 'person'\n  name: string\n  currencyCode: string\n  billCycle: 'monthly' | 'quarterly' | 'annually' | 'weekly'\n  billCycleAnchor: string\n  invoiceEmail: string\n  invoiceLanguage: string\n  invoiceAddress: Record<string, unknown>\n  nextBillDate: Date\n  taxId?: string | null\n}\n\nexport type ItemCreatePayload = {\n  billAccountId: string\n  type: 'one_time' | 'recurring' | 'usage'\n  billStartDate: Date | string\n  billEndDate?: Date | string | null\n  description: string\n  rateJson: Record<string, unknown>\n  uomCode?: string\n  subscriptionId?: string\n  subscriptionItemId?: string\n  sourceRef?: string\n  /**\n   * Billing Spec B: VAT % of the charge. CPQ charges carry no tax rate yet,\n   * so the connector omits it and billing applies the organization default\n   * at creation. Set it once CPQ exposes a per-charge rate.\n   */\n  taxRate?: number\n}\n\nexport type ItemUpdatePayload = {\n  id: string\n  billEndDate?: Date | string | null\n  subscriptionId?: string | null\n  subscriptionItemId?: string | null\n  isActive?: boolean\n}\n\nfunction buildSystemCtx(container: AwilixContainer, scope: Scope) {\n  return {\n    container,\n    auth: null,\n    organizationScope: null,\n    selectedOrganizationId: scope.organizationId,\n    organizationIds: [scope.organizationId],\n  }\n}\n\nexport class BillingApiClient {\n  private readonly em: EntityManager\n  private readonly commandBus: CommandBus\n\n  constructor(private readonly container: AwilixContainer) {\n    this.em = (container.resolve('em') as EntityManager).fork()\n    this.commandBus = container.resolve('commandBus') as CommandBus\n  }\n\n  // \u2500\u2500\u2500 Accounts \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n  /**\n   * Find a non-deleted Billing Account for `(tenant, organization,\n   * customer)`. Returns the first match or `null`. The connector\n   * uses this to skip account creation when the customer already\n   * has one.\n   */\n  async findAccountByCustomer(scope: Scope, customerId: string): Promise<BillingAccount | null> {\n    return this.em.findOne(BillingAccount, {\n      tenantId: scope.tenantId,\n      organizationId: scope.organizationId,\n      customerId,\n      deletedAt: null,\n    })\n  }\n\n  async createAccount(scope: Scope, seed: AccountSeed): Promise<{ id: string }> {\n    const result = await this.commandBus.execute('billing.accounts.create', {\n      input: {\n        tenantId: scope.tenantId,\n        organizationId: scope.organizationId,\n        ...seed,\n      },\n      ctx: buildSystemCtx(this.container, scope),\n    })\n    return (result as { result?: { id: string } }).result ?? { id: '' }\n  }\n\n  async getOrCreateAccount(scope: Scope, seed: AccountSeed): Promise<{ id: string; created: boolean }> {\n    const existing = await this.findAccountByCustomer(scope, seed.customerId)\n    if (existing) return { id: existing.id, created: false }\n    const created = await this.createAccount(scope, seed)\n    return { id: created.id, created: true }\n  }\n\n  // \u2500\u2500\u2500 Items \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n  async findItemsBySubscription(scope: Scope, subscriptionId: string): Promise<BillingItem[]> {\n    return this.em.find(BillingItem, {\n      tenantId: scope.tenantId,\n      organizationId: scope.organizationId,\n      subscriptionId,\n      deletedAt: null,\n    } as never)\n  }\n\n  async findItemsBySubscriptionItem(\n    scope: Scope,\n    subscriptionItemId: string,\n  ): Promise<BillingItem[]> {\n    return this.em.find(BillingItem, {\n      tenantId: scope.tenantId,\n      organizationId: scope.organizationId,\n      subscriptionItemId,\n      deletedAt: null,\n    } as never)\n  }\n\n  async createItem(\n    scope: Scope,\n    payload: ItemCreatePayload,\n  ): Promise<{ id: string; deduplicated: boolean }> {\n    const result = await this.commandBus.execute('billing.items.create', {\n      input: {\n        tenantId: scope.tenantId,\n        organizationId: scope.organizationId,\n        ...payload,\n      },\n      ctx: buildSystemCtx(this.container, scope),\n    })\n    const r = (result as { result?: { id: string; deduplicated: boolean } }).result\n    return r ?? { id: '', deduplicated: false }\n  }\n\n  /**\n   * Batch-create items in a single `billing.items.bulk_create`\n   * command. Use this whenever a subscriber has more than one item\n   * to create \u2014 it collapses N command-bus round-trips + N flushes\n   * into one. Idempotent per `source_ref` exactly like `createItem`.\n   *\n   * No-ops on an empty payload so callers skip the length guard.\n   */\n  async bulkCreateItems(\n    scope: Scope,\n    items: ItemCreatePayload[],\n  ): Promise<{\n    created: number\n    deduplicated: number\n    items: Array<{ sourceRef: string | null; id: string; deduplicated: boolean }>\n  }> {\n    if (items.length === 0) {\n      return { created: 0, deduplicated: 0, items: [] }\n    }\n    const result = await this.commandBus.execute('billing.items.bulk_create', {\n      input: {\n        tenantId: scope.tenantId,\n        organizationId: scope.organizationId,\n        items,\n      },\n      ctx: buildSystemCtx(this.container, scope),\n    })\n    const r = (\n      result as {\n        result?: {\n          created: number\n          deduplicated: number\n          items: Array<{ sourceRef: string | null; id: string; deduplicated: boolean }>\n        }\n      }\n    ).result\n    return r ?? { created: 0, deduplicated: 0, items: [] }\n  }\n\n  async updateItem(scope: Scope, payload: ItemUpdatePayload): Promise<{ id: string }> {\n    const result = await this.commandBus.execute('billing.items.update', {\n      input: {\n        tenantId: scope.tenantId,\n        organizationId: scope.organizationId,\n        ...payload,\n      },\n      ctx: buildSystemCtx(this.container, scope),\n    })\n    return (result as { result?: { id: string } }).result ?? { id: '' }\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

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

@@ -1,39 +1,42 @@
 import { createRequestContainer } from "@open-mercato/shared/lib/di/container";
 import { BillingApiClient } from "../lib/billingApiClient.js";
 import { mapSubscriptionItemsToBillingItems } from "../lib/chargeMapper.js";
+import {
+  DEFAULT_INVOICE_LANGUAGE,
+  isSupportedInvoiceLanguage
+} from "@dainamite/billing/modules/billing/lib/invoiceLanguages";
 const metadata = {
   event: "cpq.subscription.activated",
   persistent: true,
   id: "cpq-billing-connector:subscription-activated"
 };
-function isoDateAddMonths(months) {
-  const d = /* @__PURE__ */ new Date();
-  const targetYear = d.getUTCFullYear();
-  const targetMonth = d.getUTCMonth() + months;
-  const lastDayOfTargetMonth = new Date(Date.UTC(targetYear, targetMonth + 1, 0)).getUTCDate();
-  d.setUTCDate(Math.min(d.getUTCDate(), lastDayOfTargetMonth));
-  d.setUTCMonth(targetMonth);
-  return d.toISOString().slice(0, 10);
-}
 function todayIsoDate() {
   return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 }
+function resolveInvoiceLanguage(raw) {
+  const code = (raw ?? "").trim().toLowerCase();
+  return isSupportedInvoiceLanguage(code) ? code : DEFAULT_INVOICE_LANGUAGE;
+}
 function buildAccountSeed(payload) {
   return {
     customerId: payload.customerId,
+    ...payload.customerKind ? { customerKind: payload.customerKind } : {},
     name: payload.customerName ?? `Customer ${payload.customerId}`,
     currencyCode: payload.currencyCode,
     billCycle: payload.billCycle ?? "monthly",
     billCycleAnchor: payload.billCycleAnchor ?? "1",
     invoiceEmail: payload.invoiceEmail ?? `billing+${payload.customerId}@invalid.local`,
-    invoiceLanguage: payload.invoiceLanguage ?? "en",
+    invoiceLanguage: resolveInvoiceLanguage(payload.invoiceLanguage),
     invoiceAddress: payload.invoiceAddress ?? {
       line1: "TBD",
       city: "TBD",
       postal_code: "TBD",
       country: "XX"
     },
-    nextBillDate: payload.nextBillDate ? new Date(payload.nextBillDate) : new Date(isoDateAddMonths(1)),
+    // Billing Spec A: recurring items are billed in advance, so the first
+    // bill date is the subscription start — billing the first period on
+    // activation. (Was "today + 1 month", which skipped that period.)
+    nextBillDate: new Date(payload.nextBillDate ?? payload.activationDate ?? todayIsoDate()),
     taxId: payload.taxId ?? null
   };
 }
@@ -72,6 +75,7 @@ async function handle(payload) {
   );
 }
 export {
+  buildAccountSeed,
   handle as default,
   metadata
 };

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/cpq_billing_connector/subscribers/cpq-subscription-activated.ts"],
-  "sourcesContent": ["import { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport { BillingApiClient, type Scope, type AccountSeed } from '../lib/billingApiClient'\nimport { mapSubscriptionItemsToBillingItems } from '../lib/chargeMapper'\nimport type { CpqSubscriptionItem } from '../lib/chargeMapper'\n\n/**\n * Subscriber: `cpq.subscription.activated` \u2192 billing onboarding.\n *\n * `@dainamite/cpq` emits this event when a new-sale order is activated\n * (`cpqOrderService.activateOrder`).\n *\n * Behaviour when fired:\n *   1. Get-or-create the Billing Account for `(tenant, org, customerId)`.\n *      Missing account \u2192 shell account with placeholders (operator\n *      must configure before billing fires). `nextBillDate` defaults\n *      to today + one month so the Bill Run won't bill an under-\n *      configured account until the operator advances it.\n *   2. For every charge on every CPQ subscription item, create a\n *      Billing Item via `billing.items.create`. `source_ref` is the\n *      deterministic `cpq-<subId>-<subItemId>-<chargeType>` key, so\n *      re-firing the activation event hits the idempotency guard\n *      instead of duplicating items.\n *\n * Errors propagate to the persistent queue worker, which retries\n * per the OM queue contract.\n */\n\nexport const metadata = {\n  event: 'cpq.subscription.activated',\n  persistent: true,\n  id: 'cpq-billing-connector:subscription-activated',\n}\n\ntype ActivatedPayload = {\n  tenantId: string\n  organizationId: string\n  subscriptionId: string\n  customerId: string\n  currencyCode: string\n  /** Optional richer customer fields \u2014 used when present, otherwise placeholders. */\n  customerName?: string\n  invoiceEmail?: string\n  invoiceLanguage?: string\n  invoiceAddress?: Record<string, unknown>\n  billCycle?: 'monthly' | 'quarterly' | 'annually' | 'weekly'\n  billCycleAnchor?: string\n  nextBillDate?: string\n  taxId?: string | null\n  items: CpqSubscriptionItem[]\n  /** Activation date \u2014 used as bill_start_date on every created item. */\n  activationDate?: string\n}\n\nfunction isoDateAddMonths(months: number): string {\n  // Clamp the day to the last valid day of the target month so Jan 31 + 1\n  // month \u2192 Feb 28/29 (not Mar 3, which is what `setUTCMonth` alone would\n  // produce by overflowing into the next month).\n  const d = new Date()\n  const targetYear = d.getUTCFullYear()\n  const targetMonth = d.getUTCMonth() + months\n  const lastDayOfTargetMonth = new Date(Date.UTC(targetYear, targetMonth + 1, 0)).getUTCDate()\n  d.setUTCDate(Math.min(d.getUTCDate(), lastDayOfTargetMonth))\n  d.setUTCMonth(targetMonth)\n  return d.toISOString().slice(0, 10)\n}\n\nfunction todayIsoDate(): string {\n  return new Date().toISOString().slice(0, 10)\n}\n\nfunction buildAccountSeed(payload: ActivatedPayload): AccountSeed {\n  return {\n    customerId: payload.customerId,\n    name: payload.customerName ?? `Customer ${payload.customerId}`,\n    currencyCode: payload.currencyCode,\n    billCycle: payload.billCycle ?? 'monthly',\n    billCycleAnchor: payload.billCycleAnchor ?? '1',\n    invoiceEmail:\n      payload.invoiceEmail ?? `billing+${payload.customerId}@invalid.local`,\n    invoiceLanguage: payload.invoiceLanguage ?? 'en',\n    invoiceAddress: payload.invoiceAddress ?? {\n      line1: 'TBD',\n      city: 'TBD',\n      postal_code: 'TBD',\n      country: 'XX',\n    },\n    nextBillDate: payload.nextBillDate\n      ? new Date(payload.nextBillDate)\n      : new Date(isoDateAddMonths(1)),\n    taxId: payload.taxId ?? null,\n  }\n}\n\nexport default async function handle(payload: ActivatedPayload): Promise<void> {\n  if (!payload?.tenantId || !payload.organizationId || !payload.customerId) {\n    return\n  }\n  if (!payload.subscriptionId || !Array.isArray(payload.items) || payload.items.length === 0) {\n    return\n  }\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 account = await billingApi.getOrCreateAccount(scope, buildAccountSeed(payload))\n\n  const billStartDate = payload.activationDate ?? todayIsoDate()\n  const itemPayloads = mapSubscriptionItemsToBillingItems({\n    subscriptionId: payload.subscriptionId,\n    items: payload.items,\n    billStartDate,\n  })\n\n  // Bulk-create \u2014 one command for the whole subscription's charges\n  // instead of one round-trip per charge. Idempotent per source_ref,\n  // so a re-fired activation event is a no-op.\n  await billingApi.bulkCreateItems(\n    scope,\n    itemPayloads.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}\n"],
-  "mappings": "AAAA,SAAS,8BAA8B;AACvC,SAAS,wBAAsD;AAC/D,SAAS,0CAA0C;AAyB5C,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAsBA,SAAS,iBAAiB,QAAwB;AAIhD,QAAM,IAAI,oBAAI,KAAK;AACnB,QAAM,aAAa,EAAE,eAAe;AACpC,QAAM,cAAc,EAAE,YAAY,IAAI;AACtC,QAAM,uBAAuB,IAAI,KAAK,KAAK,IAAI,YAAY,cAAc,GAAG,CAAC,CAAC,EAAE,WAAW;AAC3F,IAAE,WAAW,KAAK,IAAI,EAAE,WAAW,GAAG,oBAAoB,CAAC;AAC3D,IAAE,YAAY,WAAW;AACzB,SAAO,EAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AACpC;AAEA,SAAS,eAAuB;AAC9B,UAAO,oBAAI,KAAK,GAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AAC7C;AAEA,SAAS,iBAAiB,SAAwC;AAChE,SAAO;AAAA,IACL,YAAY,QAAQ;AAAA,IACpB,MAAM,QAAQ,gBAAgB,YAAY,QAAQ,UAAU;AAAA,IAC5D,cAAc,QAAQ;AAAA,IACtB,WAAW,QAAQ,aAAa;AAAA,IAChC,iBAAiB,QAAQ,mBAAmB;AAAA,IAC5C,cACE,QAAQ,gBAAgB,WAAW,QAAQ,UAAU;AAAA,IACvD,iBAAiB,QAAQ,mBAAmB;AAAA,IAC5C,gBAAgB,QAAQ,kBAAkB;AAAA,MACxC,OAAO;AAAA,MACP,MAAM;AAAA,MACN,aAAa;AAAA,MACb,SAAS;AAAA,IACX;AAAA,IACA,cAAc,QAAQ,eAClB,IAAI,KAAK,QAAQ,YAAY,IAC7B,IAAI,KAAK,iBAAiB,CAAC,CAAC;AAAA,IAChC,OAAO,QAAQ,SAAS;AAAA,EAC1B;AACF;AAEA,eAAO,OAA8B,SAA0C;AAC7E,MAAI,CAAC,SAAS,YAAY,CAAC,QAAQ,kBAAkB,CAAC,QAAQ,YAAY;AACxE;AAAA,EACF;AACA,MAAI,CAAC,QAAQ,kBAAkB,CAAC,MAAM,QAAQ,QAAQ,KAAK,KAAK,QAAQ,MAAM,WAAW,GAAG;AAC1F;AAAA,EACF;AAEA,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,UAAU,MAAM,WAAW,mBAAmB,OAAO,iBAAiB,OAAO,CAAC;AAEpF,QAAM,gBAAgB,QAAQ,kBAAkB,aAAa;AAC7D,QAAM,eAAe,mCAAmC;AAAA,IACtD,gBAAgB,QAAQ;AAAA,IACxB,OAAO,QAAQ;AAAA,IACf;AAAA,EACF,CAAC;AAKD,QAAM,WAAW;AAAA,IACf;AAAA,IACA,aAAa,IAAI,CAAC,UAAU;AAAA,MAC1B,eAAe,QAAQ;AAAA,MACvB,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;",
+  "sourcesContent": ["import { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport { BillingApiClient, type Scope, type AccountSeed } from '../lib/billingApiClient'\nimport { mapSubscriptionItemsToBillingItems } from '../lib/chargeMapper'\nimport type { CpqSubscriptionItem } from '../lib/chargeMapper'\nimport {\n  DEFAULT_INVOICE_LANGUAGE,\n  isSupportedInvoiceLanguage,\n} from '@dainamite/billing/modules/billing/lib/invoiceLanguages'\n\n/**\n * Subscriber: `cpq.subscription.activated` \u2192 billing onboarding.\n *\n * `@dainamite/cpq` emits this event when a new-sale order is activated\n * (`cpqOrderService.activateOrder`).\n *\n * Behaviour when fired:\n *   1. Get-or-create the Billing Account for `(tenant, org, customerId)`.\n *      Missing account \u2192 shell account with placeholders (operator\n *      must configure before billing fires). `nextBillDate` defaults\n *      to the activation date: recurring items are billed in advance\n *      (billing Spec A), so the first period is billed from day one.\n *      An EXISTING account keeps its bill date \u2014 billing prorates the\n *      new subscription's partial first period.\n *   2. For every charge on every CPQ subscription item, create a\n *      Billing Item via `billing.items.create`. `source_ref` is the\n *      deterministic `cpq-<subId>-<subItemId>-<chargeType>` key, so\n *      re-firing the activation event hits the idempotency guard\n *      instead of duplicating items.\n *\n * Errors propagate to the persistent queue worker, which retries\n * per the OM queue contract.\n */\n\nexport const metadata = {\n  event: 'cpq.subscription.activated',\n  persistent: true,\n  id: 'cpq-billing-connector:subscription-activated',\n}\n\nexport type ActivatedPayload = {\n  tenantId: string\n  organizationId: string\n  subscriptionId: string\n  customerId: string\n  /** 'company' | 'person'. Omitted \u2192 billing defaults to 'company'. */\n  customerKind?: 'company' | 'person'\n  currencyCode: string\n  /** Optional richer customer fields \u2014 used when present, otherwise placeholders. */\n  customerName?: string\n  invoiceEmail?: string\n  invoiceLanguage?: string\n  invoiceAddress?: Record<string, unknown>\n  billCycle?: 'monthly' | 'quarterly' | 'annually' | 'weekly'\n  billCycleAnchor?: string\n  nextBillDate?: string\n  taxId?: string | null\n  items: CpqSubscriptionItem[]\n  /** Activation date \u2014 used as bill_start_date on every created item. */\n  activationDate?: string\n}\n\nfunction todayIsoDate(): string {\n  return new Date().toISOString().slice(0, 10)\n}\n\n/**\n * Billing only accepts invoice languages its document template supports.\n * An unsupported code from upstream must not fail onboarding (the persistent\n * queue would retry forever), so it falls back to billing's default \u2014 the\n * operator can change it on the account afterwards.\n */\nfunction resolveInvoiceLanguage(raw: string | undefined): string {\n  const code = (raw ?? '').trim().toLowerCase()\n  return isSupportedInvoiceLanguage(code) ? code : DEFAULT_INVOICE_LANGUAGE\n}\n\nexport function buildAccountSeed(payload: ActivatedPayload): AccountSeed {\n  return {\n    customerId: payload.customerId,\n    ...(payload.customerKind ? { customerKind: payload.customerKind } : {}),\n    name: payload.customerName ?? `Customer ${payload.customerId}`,\n    currencyCode: payload.currencyCode,\n    billCycle: payload.billCycle ?? 'monthly',\n    billCycleAnchor: payload.billCycleAnchor ?? '1',\n    invoiceEmail:\n      payload.invoiceEmail ?? `billing+${payload.customerId}@invalid.local`,\n    invoiceLanguage: resolveInvoiceLanguage(payload.invoiceLanguage),\n    invoiceAddress: payload.invoiceAddress ?? {\n      line1: 'TBD',\n      city: 'TBD',\n      postal_code: 'TBD',\n      country: 'XX',\n    },\n    // Billing Spec A: recurring items are billed in advance, so the first\n    // bill date is the subscription start \u2014 billing the first period on\n    // activation. (Was \"today + 1 month\", which skipped that period.)\n    nextBillDate: new Date(payload.nextBillDate ?? payload.activationDate ?? todayIsoDate()),\n    taxId: payload.taxId ?? null,\n  }\n}\n\nexport default async function handle(payload: ActivatedPayload): Promise<void> {\n  if (!payload?.tenantId || !payload.organizationId || !payload.customerId) {\n    return\n  }\n  if (!payload.subscriptionId || !Array.isArray(payload.items) || payload.items.length === 0) {\n    return\n  }\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 account = await billingApi.getOrCreateAccount(scope, buildAccountSeed(payload))\n\n  const billStartDate = payload.activationDate ?? todayIsoDate()\n  const itemPayloads = mapSubscriptionItemsToBillingItems({\n    subscriptionId: payload.subscriptionId,\n    items: payload.items,\n    billStartDate,\n  })\n\n  // Bulk-create \u2014 one command for the whole subscription's charges\n  // instead of one round-trip per charge. Idempotent per source_ref,\n  // so a re-fired activation event is a no-op.\n  await billingApi.bulkCreateItems(\n    scope,\n    itemPayloads.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}\n"],
+  "mappings": "AAAA,SAAS,8BAA8B;AACvC,SAAS,wBAAsD;AAC/D,SAAS,0CAA0C;AAEnD;AAAA,EACE;AAAA,EACA;AAAA,OACK;AA0BA,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAwBA,SAAS,eAAuB;AAC9B,UAAO,oBAAI,KAAK,GAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AAC7C;AAQA,SAAS,uBAAuB,KAAiC;AAC/D,QAAM,QAAQ,OAAO,IAAI,KAAK,EAAE,YAAY;AAC5C,SAAO,2BAA2B,IAAI,IAAI,OAAO;AACnD;AAEO,SAAS,iBAAiB,SAAwC;AACvE,SAAO;AAAA,IACL,YAAY,QAAQ;AAAA,IACpB,GAAI,QAAQ,eAAe,EAAE,cAAc,QAAQ,aAAa,IAAI,CAAC;AAAA,IACrE,MAAM,QAAQ,gBAAgB,YAAY,QAAQ,UAAU;AAAA,IAC5D,cAAc,QAAQ;AAAA,IACtB,WAAW,QAAQ,aAAa;AAAA,IAChC,iBAAiB,QAAQ,mBAAmB;AAAA,IAC5C,cACE,QAAQ,gBAAgB,WAAW,QAAQ,UAAU;AAAA,IACvD,iBAAiB,uBAAuB,QAAQ,eAAe;AAAA,IAC/D,gBAAgB,QAAQ,kBAAkB;AAAA,MACxC,OAAO;AAAA,MACP,MAAM;AAAA,MACN,aAAa;AAAA,MACb,SAAS;AAAA,IACX;AAAA;AAAA;AAAA;AAAA,IAIA,cAAc,IAAI,KAAK,QAAQ,gBAAgB,QAAQ,kBAAkB,aAAa,CAAC;AAAA,IACvF,OAAO,QAAQ,SAAS;AAAA,EAC1B;AACF;AAEA,eAAO,OAA8B,SAA0C;AAC7E,MAAI,CAAC,SAAS,YAAY,CAAC,QAAQ,kBAAkB,CAAC,QAAQ,YAAY;AACxE;AAAA,EACF;AACA,MAAI,CAAC,QAAQ,kBAAkB,CAAC,MAAM,QAAQ,QAAQ,KAAK,KAAK,QAAQ,MAAM,WAAW,GAAG;AAC1F;AAAA,EACF;AAEA,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,UAAU,MAAM,WAAW,mBAAmB,OAAO,iBAAiB,OAAO,CAAC;AAEpF,QAAM,gBAAgB,QAAQ,kBAAkB,aAAa;AAC7D,QAAM,eAAe,mCAAmC;AAAA,IACtD,gBAAgB,QAAQ;AAAA,IACxB,OAAO,QAAQ;AAAA,IACf;AAAA,EACF,CAAC;AAKD,QAAM,WAAW;AAAA,IACf;AAAA,IACA,aAAa,IAAI,CAAC,UAAU;AAAA,MAC1B,eAAe,QAAQ;AAAA,MACvB,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-amended.js

@@ -1,32 +1,37 @@
 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);
 }
+function buildAddedItemPayloads(billAccountId, payload) {
+  return mapSubscriptionItemsToBillingItems({
+    subscriptionId: payload.subscriptionId,
+    items: payload.addedItems ?? [],
+    billStartDate: payload.effectiveDate
+  }).map((item) => ({
+    billAccountId,
+    type: item.type,
+    billStartDate: item.billStartDate,
+    description: item.description,
+    rateJson: item.rateJson,
+    subscriptionId: item.subscriptionId,
+    subscriptionItemId: item.subscriptionItemId,
+    sourceRef: item.sourceRef
+  }));
+}
+function removedItemEndDate(effectiveDate) {
+  return isoDateMinusOneDay(effectiveDate);
+}
 async function handle(payload) {
   if (!payload?.tenantId || !payload.organizationId) return;
   if (!payload.subscriptionId || !payload.effectiveDate) return;
@@ -41,60 +46,11 @@ async function handle(payload) {
   };
   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}`
-        });
-      }
-    }
+  const itemsToCreate = buildAddedItemPayloads(account.id, payload);
+  if (itemsToCreate.length > 0) {
+    await billingApi.bulkCreateItems(scope, itemsToCreate);
   }
-  await billingApi.bulkCreateItems(scope, itemsToCreate);
-  const endDate = isoDateMinusOneDay(payload.effectiveDate);
+  const endDate = removedItemEndDate(payload.effectiveDate);
   for (const removedSubItemId of removed) {
     const items = await billingApi.findItemsBySubscriptionItem(scope, removedSubItemId);
     for (const item of items) {
@@ -106,7 +62,9 @@ async function handle(payload) {
   }
 }
 export {
+  buildAddedItemPayloads,
   handle as default,
-  metadata
+  metadata,
+  removedItemEndDate
 };
 //# sourceMappingURL=cpq-subscription-amended.js.map

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

@@ -1,7 +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": "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",
+  "sourcesContent": ["import { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport { BillingApiClient, type ItemCreatePayload, type Scope } from '../lib/billingApiClient'\nimport {\n  mapSubscriptionItemsToBillingItems,\n  type CpqSubscriptionItem,\n} from '../lib/chargeMapper'\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, starting on\n *      `effectiveDate`.\n *   2. End-dates every Billing Item of each removed subscription item at\n *      `effectiveDate - 1 day`.\n *\n * Proration is billing's job (billing Spec A): the Bill Run engine prorates\n * the partial period of an item that starts mid-cycle, and credits the\n * unused days of an item billed in advance that ends mid-cycle. The\n * connector therefore no longer posts its own `one_time` proration lines \u2014\n * doing both would double-charge the customer. A \"no refund, end at period\n * end\" policy is expressed by CPQ choosing an `effectiveDate` on the period\n * boundary.\n */\n\nexport const metadata = {\n  event: 'cpq.subscription.amended',\n  persistent: true,\n  id: 'cpq-billing-connector:subscription-amended',\n}\n\nexport type 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\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\n/** Billing Item payloads for the added charges \u2014 pure, no proration lines. */\nexport function buildAddedItemPayloads(billAccountId: string, payload: AmendedPayload): ItemCreatePayload[] {\n  return mapSubscriptionItemsToBillingItems({\n    subscriptionId: payload.subscriptionId,\n    items: payload.addedItems ?? [],\n    billStartDate: payload.effectiveDate,\n  }).map((item) => ({\n    billAccountId,\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/** `bill_end_date` for the items of removed subscription items. */\nexport function removedItemEndDate(effectiveDate: string): string {\n  return isoDateMinusOneDay(effectiveDate)\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 (the engine prorates the stub).\n  const itemsToCreate = buildAddedItemPayloads(account.id, payload)\n  if (itemsToCreate.length > 0) {\n    await billingApi.bulkCreateItems(scope, itemsToCreate)\n  }\n\n  // 2. End-date every Billing Item of each removed subscription item.\n  const endDate = removedItemEndDate(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;AACvC,SAAS,wBAA4D;AACrE;AAAA,EACE;AAAA,OAEK;AAqBA,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAaA,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;AAGO,SAAS,uBAAuB,eAAuB,SAA8C;AAC1G,SAAO,mCAAmC;AAAA,IACxC,gBAAgB,QAAQ;AAAA,IACxB,OAAO,QAAQ,cAAc,CAAC;AAAA,IAC9B,eAAe,QAAQ;AAAA,EACzB,CAAC,EAAE,IAAI,CAAC,UAAU;AAAA,IAChB;AAAA,IACA,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;AACJ;AAGO,SAAS,mBAAmB,eAA+B;AAChE,SAAO,mBAAmB,aAAa;AACzC;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,uBAAuB,QAAQ,IAAI,OAAO;AAChE,MAAI,cAAc,SAAS,GAAG;AAC5B,UAAM,WAAW,gBAAgB,OAAO,aAAa;AAAA,EACvD;AAGA,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.map

@@ -1,7 +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;",
+  "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`. From there the billing engine\n * (billing Spec A) handles the money:\n *   - an item billed in arrears is charged pro rata up to the end date;\n *   - an item already billed in advance past the end date gets an\n *     automatic credit line for the unused days (when `prorate` is on).\n *\n * The cancellation POLICY belongs to CPQ: \"cancel at the end of the\n * current period, no refund\" means CPQ sends an `effectiveDate` on the\n * period boundary \u2014 then no credit arises. The connector never invents\n * credits itself (billing does), so CPQ must NOT also post a negative\n * `one_time` item for the same days.\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;AAoBtC,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dainamite/cpq-billing-connector",
-  "version": "3.0.0",
+  "version": "4.0.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",
@@ -93,8 +93,8 @@
     }
   },
   "peerDependencies": {
-    "@dainamite/billing": "^0.20.0",
-    "@dainamite/cpq": "^0.6.0",
+    "@dainamite/billing": "^0.22.0",
+    "@dainamite/cpq": "^0.7.0",
     "@mikro-orm/core": "^7.1.14",
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",

package/src/modules/cpq_billing_connector/__tests__/subscribers/accountSeed.test.ts

@@ -0,0 +1,47 @@
+import { buildAccountSeed, type ActivatedPayload } from '../../subscribers/cpq-subscription-activated'
+
+function payload(overrides: Partial<ActivatedPayload> = {}): ActivatedPayload {
+  return {
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    subscriptionId: 'sub-1',
+    customerId: 'cust-1',
+    currencyCode: 'PLN',
+    items: [],
+    ...overrides,
+  }
+}
+
+describe('buildAccountSeed', () => {
+  it('omits customerKind when upstream does not know it (billing defaults to company)', () => {
+    expect('customerKind' in buildAccountSeed(payload())).toBe(false)
+  })
+
+  it('passes customerKind through for B2C (person) customers', () => {
+    expect(buildAccountSeed(payload({ customerKind: 'person' })).customerKind).toBe('person')
+  })
+
+  it('keeps a supported invoice language, normalised', () => {
+    expect(buildAccountSeed(payload({ invoiceLanguage: ' PL ' })).invoiceLanguage).toBe('pl')
+  })
+
+  it.each(['en', 'es', 'de', 'pl'])('passes every billing invoice language through (%s)', (code) => {
+    expect(buildAccountSeed(payload({ invoiceLanguage: code.toUpperCase() })).invoiceLanguage).toBe(code)
+  })
+
+  it('falls back to the default language for unsupported or missing codes', () => {
+    expect(buildAccountSeed(payload({ invoiceLanguage: 'fr' })).invoiceLanguage).toBe('en')
+    expect(buildAccountSeed(payload()).invoiceLanguage).toBe('en')
+  })
+
+  it('starts billing on the activation date (billed in advance), not a month later', () => {
+    expect(buildAccountSeed(payload({ activationDate: '2026-11-14' })).nextBillDate.toISOString().slice(0, 10)).toBe(
+      '2026-11-14',
+    )
+    expect(
+      buildAccountSeed(payload({ activationDate: '2026-11-14', nextBillDate: '2026-12-01' })).nextBillDate
+        .toISOString()
+        .slice(0, 10),
+    ).toBe('2026-12-01')
+  })
+})

package/src/modules/cpq_billing_connector/__tests__/subscribers/amended.test.ts

@@ -0,0 +1,44 @@
+import {
+  buildAddedItemPayloads,
+  removedItemEndDate,
+  type AmendedPayload,
+} from '../../subscribers/cpq-subscription-amended'
+
+const payload: AmendedPayload = {
+  tenantId: 't-1',
+  organizationId: 'o-1',
+  subscriptionId: 'sub-1',
+  customerId: 'cust-1',
+  effectiveDate: '2026-11-14',
+  addedItems: [
+    {
+      subscriptionItemId: 'si-1',
+      productName: 'Static IP',
+      quantity: 1,
+      charges: [{ type: 'recurring', unitPrice: 30, description: 'Static IP' }],
+    },
+  ],
+}
+
+describe('cpq-subscription-amended', () => {
+  it('creates the added recurring item from the effective date and no proration line (billing prorates)', () => {
+    const items = buildAddedItemPayloads('acc-1', payload)
+    expect(items).toHaveLength(1)
+    expect(items[0]).toMatchObject({
+      billAccountId: 'acc-1',
+      type: 'recurring',
+      billStartDate: '2026-11-14',
+      subscriptionId: 'sub-1',
+      subscriptionItemId: 'si-1',
+    })
+    expect(items.some((item) => item.type === 'one_time')).toBe(false)
+  })
+
+  it('returns nothing to create when only removals are amended', () => {
+    expect(buildAddedItemPayloads('acc-1', { ...payload, addedItems: [] })).toEqual([])
+  })
+
+  it('end-dates removed items the day before the effective date', () => {
+    expect(removedItemEndDate('2026-12-01')).toBe('2026-11-30')
+  })
+})

package/src/modules/cpq_billing_connector/lib/billingApiClient.ts

@@ -36,6 +36,8 @@ export type Scope = {
 
 export type AccountSeed = {
   customerId: string
+  /** 'company' (default when omitted) | 'person' — B2C accounts (billing Spec E). */
+  customerKind?: 'company' | 'person'
   name: string
   currencyCode: string
   billCycle: 'monthly' | 'quarterly' | 'annually' | 'weekly'
@@ -58,6 +60,12 @@ export type ItemCreatePayload = {
   subscriptionId?: string
   subscriptionItemId?: string
   sourceRef?: string
+  /**
+   * Billing Spec B: VAT % of the charge. CPQ charges carry no tax rate yet,
+   * so the connector omits it and billing applies the organization default
+   * at creation. Set it once CPQ exposes a per-charge rate.
+   */
+  taxRate?: number
 }
 
 export type ItemUpdatePayload = {

package/src/modules/cpq_billing_connector/subscribers/cpq-subscription-activated.ts

@@ -2,6 +2,10 @@ import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { BillingApiClient, type Scope, type AccountSeed } from '../lib/billingApiClient'
 import { mapSubscriptionItemsToBillingItems } from '../lib/chargeMapper'
 import type { CpqSubscriptionItem } from '../lib/chargeMapper'
+import {
+  DEFAULT_INVOICE_LANGUAGE,
+  isSupportedInvoiceLanguage,
+} from '@dainamite/billing/modules/billing/lib/invoiceLanguages'
 
 /**
  * Subscriber: `cpq.subscription.activated` → billing onboarding.
@@ -13,8 +17,10 @@ import type { CpqSubscriptionItem } from '../lib/chargeMapper'
  *   1. Get-or-create the Billing Account for `(tenant, org, customerId)`.
  *      Missing account → shell account with placeholders (operator
  *      must configure before billing fires). `nextBillDate` defaults
- *      to today + one month so the Bill Run won't bill an under-
- *      configured account until the operator advances it.
+ *      to the activation date: recurring items are billed in advance
+ *      (billing Spec A), so the first period is billed from day one.
+ *      An EXISTING account keeps its bill date — billing prorates the
+ *      new subscription's partial first period.
  *   2. For every charge on every CPQ subscription item, create a
  *      Billing Item via `billing.items.create`. `source_ref` is the
  *      deterministic `cpq-<subId>-<subItemId>-<chargeType>` key, so
@@ -31,11 +37,13 @@ export const metadata = {
   id: 'cpq-billing-connector:subscription-activated',
 }
 
-type ActivatedPayload = {
+export type ActivatedPayload = {
   tenantId: string
   organizationId: string
   subscriptionId: string
   customerId: string
+  /** 'company' | 'person'. Omitted → billing defaults to 'company'. */
+  customerKind?: 'company' | 'person'
   currencyCode: string
   /** Optional richer customer fields — used when present, otherwise placeholders. */
   customerName?: string
@@ -51,42 +59,42 @@ type ActivatedPayload = {
   activationDate?: string
 }
 
-function isoDateAddMonths(months: number): string {
-  // Clamp the day to the last valid day of the target month so Jan 31 + 1
-  // month → Feb 28/29 (not Mar 3, which is what `setUTCMonth` alone would
-  // produce by overflowing into the next month).
-  const d = new Date()
-  const targetYear = d.getUTCFullYear()
-  const targetMonth = d.getUTCMonth() + months
-  const lastDayOfTargetMonth = new Date(Date.UTC(targetYear, targetMonth + 1, 0)).getUTCDate()
-  d.setUTCDate(Math.min(d.getUTCDate(), lastDayOfTargetMonth))
-  d.setUTCMonth(targetMonth)
-  return d.toISOString().slice(0, 10)
-}
-
 function todayIsoDate(): string {
   return new Date().toISOString().slice(0, 10)
 }
 
-function buildAccountSeed(payload: ActivatedPayload): AccountSeed {
+/**
+ * Billing only accepts invoice languages its document template supports.
+ * An unsupported code from upstream must not fail onboarding (the persistent
+ * queue would retry forever), so it falls back to billing's default — the
+ * operator can change it on the account afterwards.
+ */
+function resolveInvoiceLanguage(raw: string | undefined): string {
+  const code = (raw ?? '').trim().toLowerCase()
+  return isSupportedInvoiceLanguage(code) ? code : DEFAULT_INVOICE_LANGUAGE
+}
+
+export function buildAccountSeed(payload: ActivatedPayload): AccountSeed {
   return {
     customerId: payload.customerId,
+    ...(payload.customerKind ? { customerKind: payload.customerKind } : {}),
     name: payload.customerName ?? `Customer ${payload.customerId}`,
     currencyCode: payload.currencyCode,
     billCycle: payload.billCycle ?? 'monthly',
     billCycleAnchor: payload.billCycleAnchor ?? '1',
     invoiceEmail:
       payload.invoiceEmail ?? `billing+${payload.customerId}@invalid.local`,
-    invoiceLanguage: payload.invoiceLanguage ?? 'en',
+    invoiceLanguage: resolveInvoiceLanguage(payload.invoiceLanguage),
     invoiceAddress: payload.invoiceAddress ?? {
       line1: 'TBD',
       city: 'TBD',
       postal_code: 'TBD',
       country: 'XX',
     },
-    nextBillDate: payload.nextBillDate
-      ? new Date(payload.nextBillDate)
-      : new Date(isoDateAddMonths(1)),
+    // Billing Spec A: recurring items are billed in advance, so the first
+    // bill date is the subscription start — billing the first period on
+    // activation. (Was "today + 1 month", which skipped that period.)
+    nextBillDate: new Date(payload.nextBillDate ?? payload.activationDate ?? todayIsoDate()),
     taxId: payload.taxId ?? null,
   }
 }

package/src/modules/cpq_billing_connector/subscribers/cpq-subscription-amended.ts

@@ -1,39 +1,27 @@
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
-// TODO(L2-boundary): `cycleContaining` is a runtime function imported from
-// `@dainamite/billing` internals (not a stable public surface). A breaking
-// rename or signature change in billing's `billPeriod` will manifest here
-// as a runtime crash on the first `cpq.subscription.amended` event. Same
-// trade-off as `billingApiClient.ts` — kept inline for now because the
-// proration math is non-trivial and we don't want to fork it. Promote
-// `cycleContaining` to a documented public export of @dainamite/billing
-// (or expose via a billing REST helper) before the connector hits v1.
-import { cycleContaining } from '@dainamite/billing/modules/billing/lib/billPeriod'
-import type { BillCycle } from '@dainamite/billing/modules/billing/data/validators'
-import { BillingApiClient, type Scope } from '../lib/billingApiClient'
+import { BillingApiClient, type ItemCreatePayload, type Scope } from '../lib/billingApiClient'
 import {
   mapSubscriptionItemsToBillingItems,
   type CpqSubscriptionItem,
 } from '../lib/chargeMapper'
-import {
-  computeProration,
-  formatProrationDescription,
-} from '../lib/prorationHelper'
 
 /**
  * Subscriber: `cpq.subscription.amended` → mid-cycle add / remove.
  *
  * CPQ's amended event carries `addedItems`, `removedSubscriptionItemIds`
  * and the `effectiveDate` of the amendment. The connector:
- *   1. Creates a Billing Item for every added charge — recurring items
- *      start on `effectiveDate`; the engine's mid-cycle rule skips the
- *      current cycle and bills from the next full cycle.
- *   2. For every added RECURRING charge, posts a `one_time` proration
- *      line covering the partial current cycle. The billing cycle is
- *      derived HERE (not in CPQ) — proration is a billing concept, so
- *      the connector computes it from the account's `nextBillDate` +
- *      `billCycle` via billing's `cycleContaining`.
- *   3. End-dates every Billing Item of each removed subscription item
- *      at `effectiveDate - 1 day`.
+ *   1. Creates a Billing Item for every added charge, starting on
+ *      `effectiveDate`.
+ *   2. End-dates every Billing Item of each removed subscription item at
+ *      `effectiveDate - 1 day`.
+ *
+ * Proration is billing's job (billing Spec A): the Bill Run engine prorates
+ * the partial period of an item that starts mid-cycle, and credits the
+ * unused days of an item billed in advance that ends mid-cycle. The
+ * connector therefore no longer posts its own `one_time` proration lines —
+ * doing both would double-charge the customer. A "no refund, end at period
+ * end" policy is expressed by CPQ choosing an `effectiveDate` on the period
+ * boundary.
  */
 
 export const metadata = {
@@ -42,7 +30,7 @@ export const metadata = {
   id: 'cpq-billing-connector:subscription-amended',
 }
 
-type AmendedPayload = {
+export type AmendedPayload = {
   tenantId: string
   organizationId: string
   subscriptionId: string
@@ -53,28 +41,35 @@ type AmendedPayload = {
   removedSubscriptionItemIds?: string[]
 }
 
-const DAY_MS = 86_400_000
-
-function toMidnightMs(value: Date | string): number {
-  const d =
-    value instanceof Date
-      ? new Date(value.getTime())
-      : new Date(`${value}T00:00:00.000Z`)
-  d.setUTCHours(0, 0, 0, 0)
-  return d.getTime()
-}
-
-/** Inclusive day count from `from` through `to`. */
-function inclusiveDays(from: Date | string, to: Date | string): number {
-  return Math.round((toMidnightMs(to) - toMidnightMs(from)) / DAY_MS) + 1
-}
-
 function isoDateMinusOneDay(iso: string): string {
   const d = new Date(`${iso}T00:00:00.000Z`)
   d.setUTCDate(d.getUTCDate() - 1)
   return d.toISOString().slice(0, 10)
 }
 
+/** Billing Item payloads for the added charges — pure, no proration lines. */
+export function buildAddedItemPayloads(billAccountId: string, payload: AmendedPayload): ItemCreatePayload[] {
+  return mapSubscriptionItemsToBillingItems({
+    subscriptionId: payload.subscriptionId,
+    items: payload.addedItems ?? [],
+    billStartDate: payload.effectiveDate,
+  }).map((item) => ({
+    billAccountId,
+    type: item.type,
+    billStartDate: item.billStartDate,
+    description: item.description,
+    rateJson: item.rateJson,
+    subscriptionId: item.subscriptionId,
+    subscriptionItemId: item.subscriptionItemId,
+    sourceRef: item.sourceRef,
+  }))
+}
+
+/** `bill_end_date` for the items of removed subscription items. */
+export function removedItemEndDate(effectiveDate: string): string {
+  return isoDateMinusOneDay(effectiveDate)
+}
+
 export default async function handle(payload: AmendedPayload): Promise<void> {
   if (!payload?.tenantId || !payload.organizationId) return
   if (!payload.subscriptionId || !payload.effectiveDate) return
@@ -95,68 +90,14 @@ export default async function handle(payload: AmendedPayload): Promise<void> {
   const account = await billingApi.findAccountByCustomer(scope, payload.customerId)
   if (!account) return
 
-  // 1. New Billing Items for every added charge.
-  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,
-  }))
-
-  // 2. Mid-cycle proration. The billing cycle the amend lands in is
-  // derived from the account here — CPQ does not own the billing cycle.
-  if (added.length > 0) {
-    const period = cycleContaining(
-      account.nextBillDate,
-      account.billCycle as 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}`,
-        })
-      }
-    }
+  // 1. New Billing Items for every added charge (the engine prorates the stub).
+  const itemsToCreate = buildAddedItemPayloads(account.id, payload)
+  if (itemsToCreate.length > 0) {
+    await billingApi.bulkCreateItems(scope, itemsToCreate)
   }
 
-  await billingApi.bulkCreateItems(scope, itemsToCreate)
-
-  // 3. End-date every Billing Item of each removed subscription item.
-  const endDate = isoDateMinusOneDay(payload.effectiveDate)
+  // 2. End-date every Billing Item of each removed subscription item.
+  const endDate = removedItemEndDate(payload.effectiveDate)
   for (const removedSubItemId of removed) {
     const items = await billingApi.findItemsBySubscriptionItem(scope, removedSubItemId)
     for (const item of items) {

package/src/modules/cpq_billing_connector/subscribers/cpq-subscription-cancelled.ts

@@ -6,14 +6,17 @@ import { BillingApiClient, type Scope } from '../lib/billingApiClient'
  * every billing item attached to the subscription.
  *
  * The connector uses the spec's `effectiveDate` (cancellation date)
- * minus one day as `bill_end_date` so the engine's recurring
- * selector stops including the item from the cycle containing the
- * cancellation onward.
+ * minus one day as `bill_end_date`. From there the billing engine
+ * (billing Spec A) handles the money:
+ *   - an item billed in arrears is charged pro rata up to the end date;
+ *   - an item already billed in advance past the end date gets an
+ *     automatic credit line for the unused days (when `prorate` is on).
  *
- * Final-period proration / refund credits (per spec) are issued by
- * CPQ — the connector does not invent them here. If a credit is
- * needed, CPQ posts a negative `one_time` Billing Item via this
- * same connector path (e.g. an `amend` event preceding the cancel).
+ * The cancellation POLICY belongs to CPQ: "cancel at the end of the
+ * current period, no refund" means CPQ sends an `effectiveDate` on the
+ * period boundary — then no credit arises. The connector never invents
+ * credits itself (billing does), so CPQ must NOT also post a negative
+ * `one_time` item for the same days.
  */
 
 export const metadata = {

package/dist/modules/cpq_billing_connector/lib/prorationHelper.js

@@ -1,19 +0,0 @@
-function roundHalfUp2dp(value) {
-  return Math.round((value + Number.EPSILON) * 100) / 100;
-}
-function computeProration(input) {
-  if (input.daysInPeriod <= 0) {
-    return { amount: 0, amountString: "0.0000" };
-  }
-  const raw = input.unitPrice * input.quantity * Math.max(0, input.daysRemaining) / input.daysInPeriod;
-  const rounded = roundHalfUp2dp(raw);
-  return { amount: rounded, amountString: rounded.toFixed(4) };
-}
-function formatProrationDescription(params) {
-  return `Proration: ${params.productName} from ${params.effectiveDate} to ${params.cycleEnd}`;
-}
-export {
-  computeProration,
-  formatProrationDescription
-};
-//# sourceMappingURL=prorationHelper.js.map

package/dist/modules/cpq_billing_connector/lib/prorationHelper.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../src/modules/cpq_billing_connector/lib/prorationHelper.ts"],
-  "sourcesContent": ["/**\n * Proration math owned by the connector.\n *\n * Per spec: \"Connectors computing proration values should follow the\n * same convention for consistency on the draft\" \u2014 i.e. half-up 2dp,\n * matching billing's `roundHalfUp2dp` policy. Duplicated here (vs\n * imported from `@dainamite/billing`) on purpose so the connector\n * doesn't reach into billing's internals via a non-peer-dep path.\n *\n * The formula is the linear-day proration documented in the spec's\n * \"CPQ-side payload contracts\" section:\n *   `prorationAmount = unitPrice \u00D7 quantity \u00D7 daysRemaining / daysInPeriod`\n *\n * For mid-cycle additions (e.g. customer buys an add-on on 2026-05-15\n * for a monthly cycle anchored on the 1st), `daysRemaining` is the\n * number of full days from the effective date through the cycle end\n * (inclusive), and `daysInPeriod` is the cycle's calendar-day length.\n *\n * The CPQ event payload supplies both numbers \u2014 the connector trusts\n * the calendar arithmetic CPQ already did (it derived the period\n * boundaries from the subscription's lifecycle). It does NOT\n * re-compute them from `effectiveDate` and `cycleEnd` to avoid\n * disagreeing with CPQ's source of truth.\n */\n\n/**\n * Half-up 2dp rounding that survives JS floating-point edges\n * (e.g. `1.005 * 100 === 100.49999\u2026`). Matches billing's\n * `roundHalfUp2dp` policy.\n */\nfunction roundHalfUp2dp(value: number): number {\n  return Math.round((value + Number.EPSILON) * 100) / 100\n}\n\nexport type ProrationInput = {\n  unitPrice: number\n  quantity: number\n  daysInPeriod: number\n  daysRemaining: number\n}\n\nexport type ProrationResult = {\n  /** Numeric amount, half-up 2dp, suitable for `rate_json.amount`. */\n  amount: number\n  /** Computed string form for `billing.items.create.rateJson` (4dp). */\n  amountString: string\n}\n\nexport function computeProration(input: ProrationInput): ProrationResult {\n  // Guard against the degenerate \"0 days in period\" \u2014 should never\n  // happen if CPQ derived the values, but defending here avoids a\n  // silent NaN propagation if it ever does.\n  if (input.daysInPeriod <= 0) {\n    return { amount: 0, amountString: '0.0000' }\n  }\n  const raw =\n    (input.unitPrice * input.quantity * Math.max(0, input.daysRemaining)) /\n    input.daysInPeriod\n  const rounded = roundHalfUp2dp(raw)\n  return { amount: rounded, amountString: rounded.toFixed(4) }\n}\n\n/**\n * Helper used by subscribers to format the proration description so\n * the resulting invoice line reads naturally (matches spec example:\n * \"Proration: Package X from 2026-05-15 to 2026-05-31\").\n */\nexport function formatProrationDescription(params: {\n  productName: string\n  effectiveDate: string\n  cycleEnd: string\n}): string {\n  return `Proration: ${params.productName} from ${params.effectiveDate} to ${params.cycleEnd}`\n}\n"],
-  "mappings": "AA8BA,SAAS,eAAe,OAAuB;AAC7C,SAAO,KAAK,OAAO,QAAQ,OAAO,WAAW,GAAG,IAAI;AACtD;AAgBO,SAAS,iBAAiB,OAAwC;AAIvE,MAAI,MAAM,gBAAgB,GAAG;AAC3B,WAAO,EAAE,QAAQ,GAAG,cAAc,SAAS;AAAA,EAC7C;AACA,QAAM,MACH,MAAM,YAAY,MAAM,WAAW,KAAK,IAAI,GAAG,MAAM,aAAa,IACnE,MAAM;AACR,QAAM,UAAU,eAAe,GAAG;AAClC,SAAO,EAAE,QAAQ,SAAS,cAAc,QAAQ,QAAQ,CAAC,EAAE;AAC7D;AAOO,SAAS,2BAA2B,QAIhC;AACT,SAAO,cAAc,OAAO,WAAW,SAAS,OAAO,aAAa,OAAO,OAAO,QAAQ;AAC5F;",
-  "names": []
-}

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

@@ -1,93 +0,0 @@
-import {
-  computeProration,
-  formatProrationDescription,
-} from '../../lib/prorationHelper'
-
-describe('computeProration', () => {
-  it('canonical spec example: 29 EUR × 17/31 → 15.90 (Story 2)', () => {
-    const result = computeProration({
-      unitPrice: 29,
-      quantity: 1,
-      daysInPeriod: 31,
-      daysRemaining: 17,
-    })
-    // 29 × 17 / 31 = 15.903225… → 15.90
-    expect(result.amount).toBe(15.9)
-    expect(result.amountString).toBe('15.9000')
-  })
-
-  it('full-period proration equals full unit_price × quantity', () => {
-    const result = computeProration({
-      unitPrice: 49.99,
-      quantity: 2,
-      daysInPeriod: 30,
-      daysRemaining: 30,
-    })
-    expect(result.amount).toBe(99.98)
-  })
-
-  it('zero days remaining → zero amount', () => {
-    const result = computeProration({
-      unitPrice: 49,
-      quantity: 1,
-      daysInPeriod: 30,
-      daysRemaining: 0,
-    })
-    expect(result.amount).toBe(0)
-  })
-
-  it('rounds half-up to 2dp', () => {
-    // 1 × 1 × 1 / 200 = 0.005 → 0.01 (half-up)
-    const result = computeProration({
-      unitPrice: 1,
-      quantity: 1,
-      daysInPeriod: 200,
-      daysRemaining: 1,
-    })
-    expect(result.amount).toBe(0.01)
-    expect(result.amountString).toBe('0.0100')
-  })
-
-  it('defends against daysInPeriod === 0 (degenerate input)', () => {
-    const result = computeProration({
-      unitPrice: 49,
-      quantity: 1,
-      daysInPeriod: 0,
-      daysRemaining: 5,
-    })
-    expect(result.amount).toBe(0)
-  })
-
-  it('clamps negative daysRemaining to 0 (defensive)', () => {
-    const result = computeProration({
-      unitPrice: 49,
-      quantity: 1,
-      daysInPeriod: 30,
-      daysRemaining: -3,
-    })
-    expect(result.amount).toBe(0)
-  })
-
-  it('scales by quantity correctly', () => {
-    // 10 seats × 5 EUR × 15/30 = 25 EUR
-    const result = computeProration({
-      unitPrice: 5,
-      quantity: 10,
-      daysInPeriod: 30,
-      daysRemaining: 15,
-    })
-    expect(result.amount).toBe(25)
-  })
-})
-
-describe('formatProrationDescription', () => {
-  it('matches the spec example phrasing', () => {
-    expect(
-      formatProrationDescription({
-        productName: 'Package X',
-        effectiveDate: '2026-05-15',
-        cycleEnd: '2026-05-31',
-      }),
-    ).toBe('Proration: Package X from 2026-05-15 to 2026-05-31')
-  })
-})

package/src/modules/cpq_billing_connector/lib/prorationHelper.ts

@@ -1,74 +0,0 @@
-/**
- * Proration math owned by the connector.
- *
- * Per spec: "Connectors computing proration values should follow the
- * same convention for consistency on the draft" — i.e. half-up 2dp,
- * matching billing's `roundHalfUp2dp` policy. Duplicated here (vs
- * imported from `@dainamite/billing`) on purpose so the connector
- * doesn't reach into billing's internals via a non-peer-dep path.
- *
- * The formula is the linear-day proration documented in the spec's
- * "CPQ-side payload contracts" section:
- *   `prorationAmount = unitPrice × quantity × daysRemaining / daysInPeriod`
- *
- * For mid-cycle additions (e.g. customer buys an add-on on 2026-05-15
- * for a monthly cycle anchored on the 1st), `daysRemaining` is the
- * number of full days from the effective date through the cycle end
- * (inclusive), and `daysInPeriod` is the cycle's calendar-day length.
- *
- * The CPQ event payload supplies both numbers — the connector trusts
- * the calendar arithmetic CPQ already did (it derived the period
- * boundaries from the subscription's lifecycle). It does NOT
- * re-compute them from `effectiveDate` and `cycleEnd` to avoid
- * disagreeing with CPQ's source of truth.
- */
-
-/**
- * Half-up 2dp rounding that survives JS floating-point edges
- * (e.g. `1.005 * 100 === 100.49999…`). Matches billing's
- * `roundHalfUp2dp` policy.
- */
-function roundHalfUp2dp(value: number): number {
-  return Math.round((value + Number.EPSILON) * 100) / 100
-}
-
-export type ProrationInput = {
-  unitPrice: number
-  quantity: number
-  daysInPeriod: number
-  daysRemaining: number
-}
-
-export type ProrationResult = {
-  /** Numeric amount, half-up 2dp, suitable for `rate_json.amount`. */
-  amount: number
-  /** Computed string form for `billing.items.create.rateJson` (4dp). */
-  amountString: string
-}
-
-export function computeProration(input: ProrationInput): ProrationResult {
-  // Guard against the degenerate "0 days in period" — should never
-  // happen if CPQ derived the values, but defending here avoids a
-  // silent NaN propagation if it ever does.
-  if (input.daysInPeriod <= 0) {
-    return { amount: 0, amountString: '0.0000' }
-  }
-  const raw =
-    (input.unitPrice * input.quantity * Math.max(0, input.daysRemaining)) /
-    input.daysInPeriod
-  const rounded = roundHalfUp2dp(raw)
-  return { amount: rounded, amountString: rounded.toFixed(4) }
-}
-
-/**
- * Helper used by subscribers to format the proration description so
- * the resulting invoice line reads naturally (matches spec example:
- * "Proration: Package X from 2026-05-15 to 2026-05-31").
- */
-export function formatProrationDescription(params: {
-  productName: string
-  effectiveDate: string
-  cycleEnd: string
-}): string {
-  return `Proration: ${params.productName} from ${params.effectiveDate} to ${params.cycleEnd}`
-}