# Products — Scratchpad

**Plan date:** 2026-01-01

## Why this plan exists
Add a first-class “Products” capability (MSP offer catalog) integrated with contracts, invoices, taxes, and accounting exports.

## Discovery notes (repo)
### Existing primitives that overlap with “Products”
- **Service Catalog already exists** (`service_catalog`) and is used as the authoritative sellable item source in billing, tax hooks, and accounting mapping.
- Multi-currency pricing exists for catalog items via `IServicePrice` and service pricing UI (`server/src/components/settings/billing/ServiceCatalogManager.tsx`).
- Tax selection for catalog items already uses `tax_rate_id` (nullable = non-taxable).
- Accounting mapping resolution currently resolves mappings for `service` (service_catalog row) and optionally `service_category` (`server/src/lib/services/accountingMappingResolver.ts`).

### Billing engine gaps
- `BillingEngine.calculateProductCharges` and `calculateLicenseCharges` exist but are placeholders returning an empty `planServices` list (`server/src/lib/billing/billingEngine.ts`).
- There are TODOs implying `service_catalog.service_type` is missing, but migrations show the schema has evolved; current app code relies on `custom_service_type_id` + `billing_method` instead.

### Contracts / line types
- `contract_lines.contract_line_type` is stored as free text in the DB (`server/migrations/20251008000001_rename_billing_to_contracts.cjs`), but TypeScript types in `server/src/interfaces/billing.interfaces.ts` and the API service layer are narrower (often `'Fixed' | 'Hourly' | 'Usage'`).
- Tests/reference code mention additional types like `'Bucket'`, and billing engine supports bucket charges; product/license line types likely need formalization.

## Working hypothesis (recommended direction)
Implement **Products as a “kind” of catalog item** and keep a single sellable-item id flowing through:
- contract services (`client_contract_services`)
- invoice items (`invoice_items`)
- mapping resolution (accounting export)
- tax assignment (`tax_rate_id`)

This avoids duplicating tax/mapping/pricing logic and keeps a clean path for future inventory augmentation.

## Links / references
- Billing domain overview: `docs/billing/billing.md`
- Multi-currency billing plan: `ee/docs/plans/2025-11-17-multi-currency-billing-plan.md`
- Tax system completion plan: `ee/docs/plans/2025-11-24-tax-system-completion-and-external-passthrough-plan.md`

## Open decisions to confirm
- ✅ Products as `service_catalog` subset/view (single catalog id).
- ✅ Contracts: start with recurring only (no bill-once in V1).
- ✅ Price overrides allowed (no audit trail in V1).
- ✅ No line-level discounts in V1.
- ✅ Products must be usable on: contracts + invoices + tickets + projects + time entries.
- License handling: needs term/period semantics; likely implement as properties on the product (may still emit `type: 'license'` charges).
- ✅ Materials model: separate “materials” records; V1 starts with materials on tickets/projects only (defer time-entry linkage).
- ✅ Ticket/project materials: auto-bill in V1.
- ✅ Billing path: ticket/project materials roll into billing engine like usage/time (not direct invoice items at entry-time).
- ✅ License semantics: term metadata only in V1 (no start/end, no proration).

## Commands used during discovery
- `rg -n "calculateProductCharges|calculateLicenseCharges" -S server/src`
- `rg -n "service_catalog" -S server/src ee docs`

## Implementation gotchas / notes
- `getServices()` now defaults to `item_kind: 'service'` to preserve legacy expectations; use `getServices(..., { item_kind: 'product' })` or `{ item_kind: 'any' }` explicitly when you need products included.
- `server/src/components/ui/Button` requires an `id` prop; new buttons added for Products/Materials include explicit IDs.
- **Archive semantics (Products):** “Delete product” is implemented as **archive** (`service_catalog.is_active=false`). Archived products:
  - are hidden from product pickers by default (pickers now request `is_active: true`)
  - cannot be attached to new contract lines (server-side enforcement in `addServiceToContractLine`)
  - can be restored via Products UI (sets `is_active=true`).
- **Contracts/templates:** Client Contract Wizard + Template Wizard now have an explicit **Products** step; products are created on their own fixed contract line (“… - Products”) to avoid mixing with fixed-fee base rates.
- **Billing safety:** Billing engine now throws a clear error if a product has no catalog price in the contract currency and no custom rate override (prevents accidental $0 product charges).
- **Manual invoices:** Manual invoice service picker now uses multi-currency catalog prices (and includes products) instead of `default_rate` (which is often 0 for products).
- **Guardrails added:**
  - Service catalog mutations (create/update/delete) and service price mutations now enforce RBAC via `hasPermission(user, 'service', ...)`.
  - Catalog rates (`default_rate`, `cost`, `service_prices.rate`) are normalized to integer cents and rejected if negative.
  - Manual invoice API now requires `quantity > 0` for non-discount line items.
- **Scalable catalog pickers (contracts):**
  - Added `server/src/components/ui/AsyncSearchableSelect.tsx` (debounced, server-side search, 10-item limit + “more results” indicator).
  - Added `server/src/components/billing-dashboard/contracts/ServiceCatalogPicker.tsx` to search **services + products** (filters by `billing_method`, `item_kind`, `is_active`).
  - Wired into contract dialogs that previously loaded `getServices(1, 999, ...)` and filtered client-side.
- **Product update reliability:** `Service.update()` now strips `undefined` keys before calling Knex `update()` to avoid invalid/undefined bindings when optional product fields are omitted.
- **Product categories (V1):** Products use the existing `service_categories` reference data via `service_catalog.category_id` for controlled categorization (filtering + accounting mapping); the legacy freeform `product_category` is treated as an optional “label” field in the UI.
- **Product money formatting:** Product list/pricing surfaces avoid hard-coded `$` and always display currency context (symbol + `(CODE)`), consistent with multi-currency catalog pricing.
- **API surface added/updated:**
  - `/api/v1/products` and `/api/v1/products/{id}` provide product catalog CRUD over API keys (RBAC resource: `service`).
  - `/api/v1/services` list query now supports `item_kind` (`service|product|any`) and `is_active` filters; `billing_method` now includes `per_unit`.
  - Contract Lines API v2 now resolves plan services from `service_catalog` (not `services`) and accepts `per_unit` billing methods for product services.
- **OpenAPI/metadata:** `MetadataService.discoverSchemas()` originally looked for `server/src/lib/api/schemas` relative to `process.cwd()`, which is wrong in Next (cwd is `server/`). Fixed to scan `src/lib/api/schemas`, added support for `z.object(shapeName)` schema patterns, and tagged `/api/v1/products` under `Configuration`.
- **Invoice preview (drafts) bug:** Draft invoice preview failed with Postgres error `column reference "tenant" is ambiguous` due to an unqualified `.where({ tenant })` after joining `invoice_charges as ic` with `service_catalog as sc` in `Invoice.getInvoiceCharges`. Fixed by qualifying the where clause to `ic.tenant`/`ic.invoice_id` (`server/src/lib/models/invoice.ts`).
  - **Dev stack note:** In this worktree the Next.js server runs from a built image (not a bind-mount), so code changes may require `docker compose ... build server` + recreate to take effect.
- Local build sanity checks:
  - TypeScript passes under `NEXTAUTH_SECRET='local-build-secret' NODE_OPTIONS='--max-old-space-size=8192' npm -w server run build`
  - Next.js prerender currently fails on `/_global-error` (`useContext` null) in this environment; appears unrelated to Products work.

## Scope trims (confirmed)
- Removed “Convert Service Catalog Item to Product” UI: users can create products directly; no explicit in-app “convert service → product” workflow is required for V1.