@opencxh/domain 1.296.1 → 1.300.0

package/dist/entities/agreement/types.d.ts

@@ -63,11 +63,10 @@ export interface Commitment {
 }
 /** A price fixed on the line when it was agreed, instead of the ladder at billing time. */
 export interface LinePrice {
+    /** Per the line's `unitKey`. */
     cents: Cents;
     currency: string;
     per?: PricePer;
-    /** The unit the price is for, when it is not the product's (a supplier's box of 10). */
-    unit?: string;
 }
 export type AgreementInterval = "month" | "quarter" | "year";
 export interface AgreementLine {
@@ -75,6 +74,10 @@ export interface AgreementLine {
     productId: string;
     /** Copied from the product, like a transaction line: the agreement must stay readable. */
     name: string;
+    /** The unit it is counted in (a supplier's box of 10); absent = the article's base unit. */
+    unitKey?: string;
+    /** Base units in one `unitKey`, fixed when the line was made (plan 046 #14). Absent = 1. */
+    factor?: number;
     /**
      * One line through its changes: 10 seats ending on 12 May and 12 seats from then share it. A
      * billed line never changes; a change ends it and starts a successor in the same series.
@@ -161,6 +164,8 @@ export interface RunLine {
     name: string;
     productId: string;
     unitKey: string;
+    /** Base units in one `unitKey`, from the agreement line (a box of 10). Absent = 1. */
+    factor?: number;
     taxRateKey: string;
     quantity: number;
     unitPriceCents: Cents;

package/dist/entities/bookkeeping/types.d.ts

@@ -112,5 +112,6 @@ export interface WorkQueueItem {
 /**
  * The rule a line books under: product, then category, then VAT code, then the rule without a
  * match. `undefined` when nothing applies — the caller refuses rather than guessing an account.
+ * With a `direction`, only rules for that direction count: a sale rule never books a purchase.
  */
-export declare function ledgerRuleFor(line: Pick<BookingLine, "productId" | "ledgerCategoryKey" | "taxRateKey">, rules: readonly LedgerMappingRule[]): LedgerMappingRule | undefined;
+export declare function ledgerRuleFor(line: Pick<BookingLine, "productId" | "ledgerCategoryKey" | "taxRateKey">, rules: readonly LedgerMappingRule[], direction?: "sale" | "purchase"): LedgerMappingRule | undefined;

package/dist/entities/catalog/article.d.ts

@@ -0,0 +1,28 @@
+import { Cents } from '../money/money';
+import { PricePer } from '../money/period-price';
+import { Product, ProductRelease, ReferenceCost } from './types';
+/**
+ * `qty` of `unitKey` in the article's base unit: 3 rolls of 500 m are 1,500 m. Throws on a unit
+ * the article does not know — a guessed factor of 1 is how a box of ten gets billed as one.
+ */
+export declare function toBaseUnits(product: Pick<Product, "unitKey" | "units">, unitKey: string, qty: number): number;
+/** Base units in one `unitKey`; 1 for the base unit itself. */
+export declare function unitFactor(product: Pick<Product, "unitKey" | "units">, unitKey: string): number;
+/** What is wrong with a set of units, as an error code; `null` when nothing is. */
+export declare function unitsProblem(product: Pick<Product, "unitKey" | "units">): string | null;
+/** A parent with variants is a container, never on a line: its variants are what is traded. */
+export declare function isTradeable(product: Pick<Product, "id">, all: readonly Pick<Product, "parentId">[]): boolean;
+/**
+ * Why a variant does not fit its parent, as an error code; `null` when it does. Every variant
+ * carries exactly the parent's option keys, and no two share a combination — what a shop sync
+ * (Shopify's `selectedOptions`) requires.
+ */
+export declare function variantOptionsProblem(parent: Pick<Product, "optionKeys">, variant: Pick<Product, "id" | "options">, siblings: readonly Pick<Product, "id" | "options">[]): string | null;
+/**
+ * Whether a **new** commitment may name this article in this administration (a line added, a
+ * quote sent, an order confirmed, a PO sent) — as an error code, `null` when it may. Carrying out
+ * a commitment that already exists (an agreement run, receiving a sent PO) never asks this.
+ */
+export declare function commitProblem(product: Pick<Product, "archived">, release: Pick<ProductRelease, "blocked"> | undefined): string | null;
+/** The reference cost restated to another period, in its own currency (€ 240/year → € 20/month). */
+export declare function referenceCostIn(cost: ReferenceCost, per: PricePer | undefined): Cents;

package/dist/entities/catalog/article.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/catalog/index.d.ts

@@ -1,3 +1,4 @@
+export * from './article';
 export * from './codes';
 export * from './pricing';
 export * from './rate-csv';

package/dist/entities/catalog/pricing.d.ts

@@ -1,7 +1,9 @@
 import { Cents } from '../money/money';
 import { PricePer } from '../money/period-price';
 import { TransactionLine } from '../transaction/types';
-import { PriceRule, Product } from './types';
+import { PriceRule, SellableProduct } from './types';
+/** What the ladder reads of an article: its identity and sales' price row. */
+export type PricedProduct = Pick<SellableProduct, "id" | "categoryKey" | "listPriceCents" | "currency" | "pricePer" | "rateCardId">;
 /**
  * The ladder: the most specific rule wins, whole. No sum, no stacking.
  *
@@ -24,21 +26,23 @@ export interface PriceContext {
     companyId?: string;
     segmentKey?: string;
     contractId?: string;
+    /** In the article's **base** unit: 2 boxes of 10 reach a tier "from 20" (plan 046 #10). */
     quantity: number;
     /** Epoch ms; the validity window is judged against this, not against "now". */
     at: number;
 }
 /** Amount, currency and period travel together: € 222 means nothing without "per year". */
 export interface ResolvedPrice {
-    unitPriceCents: Cents;
+    /** Absent with `sourceKey: "missing"`: no list price and no rule. Never a silent € 0. */
+    unitPriceCents?: Cents;
     currency: string;
     /** Absent = once, or per unit. */
     per?: PricePer;
-    /** Where this amount came from. Almost free, and the only question a salesperson asks. */
+    /** Where this amount came from. Almost free, and the only question a salesperson asks. `missing` = no price. */
     sourceKey: string;
     ruleId?: string;
 }
-export declare function resolvePrice(product: Product, ctx: PriceContext, rules: readonly PriceRule[]): ResolvedPrice;
+export declare function resolvePrice(product: PricedProduct, ctx: PriceContext, rules: readonly PriceRule[]): ResolvedPrice;
 export interface ResolvedRateCard {
     rateCardId: string;
     sourceKey: string;
@@ -48,12 +52,14 @@ export interface ResolvedRateCard {
  * The rate card a `rated` product is billed on for this customer: the same ladder as a price,
  * over the rules whose outcome is a card, then the product's own card. `null` = it has none.
  */
-export declare function resolveRateCard(product: Product, ctx: PriceContext, rules: readonly PriceRule[]): ResolvedRateCard | null;
+export declare function resolveRateCard(product: PricedProduct, ctx: PriceContext, rules: readonly PriceRule[]): ResolvedRateCard | null;
 /** The `priceSourceKey` of a price somebody typed themselves. The ladder never overwrites it. */
 export declare const MANUAL_PRICE_SOURCE = "manual";
+/** Nothing priced it: sending or confirming refuses (`price_missing`) until a person types one. */
+export declare const MISSING_PRICE_SOURCE = "missing";
 /**
  * The ladder again, for lines already on a document: after the quantity or the customer changed,
  * a tier or an agreement may now apply. A typed price stays, and so does a line whose product
  * is no longer in `products`.
  */
-export declare function repriceLines(lines: readonly TransactionLine[], products: readonly Product[], rules: readonly PriceRule[], ctx: Omit<PriceContext, "quantity">): TransactionLine[];
+export declare function repriceLines(lines: readonly TransactionLine[], products: readonly PricedProduct[], rules: readonly PriceRule[], ctx: Omit<PriceContext, "quantity">): TransactionLine[];

package/dist/entities/catalog/rating.d.ts

@@ -120,3 +120,15 @@ export interface RatingResult {
 }
 /** A period's records, rated and grouped per rate. Cents are rounded once per group. */
 export declare function rateRecords(records: readonly UsageRecord[], rates: readonly Rate[], aggregation?: UsageAggregation): RatingResult;
+/**
+ * A rated group as an invoice line: hours × the hourly price when a flat rate says so exactly,
+ * else 1 piece × the group's total (tiers, a markup, a setup fee, a price below a cent).
+ */
+export declare function ratedLineAmount(group: RatedGroup, rate: Rate | undefined, display: {
+    unit: string;
+    per: number;
+}): {
+    quantity: number;
+    unitKey: string;
+    unitPriceCents: Cents;
+};

package/dist/entities/catalog/types.d.ts

@@ -1,18 +1,21 @@
 import { Cents } from '../money/money';
 import { PricePer } from '../money/period-price';
 /**
- * What we sell, variants included.
+ * An article: what we sell, buy, stock or make, variants included (plan 046). Catalog's, shared by
+ * every administration; what differs per administration is its {@link ProductRelease}. Prices are
+ * sales' ({@link SalesProduct}), offers purchase's.
  *
  * One self-referencing table instead of a product/variant pair: a variant has exactly the same
- * fields as its parent and misses none of them. What it adds is {@link Product.options} — and that
- * is a column, not an entity.
+ * fields as its parent and misses none of them. What it adds is {@link Product.options}.
  */
 export interface Product {
     id: string;
     organizationId: string;
-    /** The parent this is a variant of. Absent = a product in its own right. */
+    /** The parent this is a variant of. Absent = a product in its own right. A parent is never traded. */
     parentId?: string;
-    /** What makes this variant different: `[{ key: "colour", value: "black" }]`. A label, nothing more. */
+    /** On a parent: the option keys every variant carries, in this order (`["colour", "size"]`). */
+    optionKeys?: string[];
+    /** What makes this variant different: `[{ key: "colour", value: "black" }]`. */
     options?: {
         key: string;
         value: string;
@@ -23,28 +26,115 @@ export interface Product {
     sku?: string;
     /** The global code: EAN-13, UPC-12, GTIN-14. Stored normalised — see `normalizeGtin`. */
     gtin?: string;
-    /** Whatever else is scannable (outer case, our own Code128), as scanned. */
+    /** Whatever else is scannable without a quantity of its own, as scanned. */
     barcodes?: string[];
-    /**
-     * The category this falls under — a key from a small table of its own, not free text.
-     *
-     * Having to be stable is the whole requirement: together with {@link Product.taxRateKey} this is
-     * the key the bookkeeping bridge picks a ledger account on. A free text field where one person
-     * types "Services" and another "services " cannot carry that.
-     */
+    /** References to this product elsewhere (`shopify:<shop>:<gid>`). A reference, never a copy. */
+    externalIds?: string[];
+    /** A {@link ProductCategory} key: groups the offering, and price agreements name it. */
     categoryKey?: string;
+    /** Is anything delivered? Fulfilment reads it; a service is done, goods are shipped. */
+    kind: ProductKind;
+    /** Serial or batch numbers on receipt and delivery. Absent = none; goods only. */
+    tracking?: ProductTracking;
+    /** The base unit everything counts in: stock, deliveries, allocations. Locked once used. */
+    unitKey: string;
+    /** Other units it comes in: a roll of 500 m, a box of 10. See {@link toBaseUnits}. */
+    units?: ProductUnit[];
+    /** On quotes, invoices and agreements. Absent = yes; steel plate you only buy is `false`. */
+    sellable?: boolean;
+    /** On purchase orders. Absent = no. */
+    purchasable?: boolean;
+    /** When it was first put on a document: locks {@link Product.unitKey} and forbids a delete. */
+    usedAt?: number;
+    archived?: boolean;
+    order?: number;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export type ProductKind = "goods" | "service";
+export type ProductTracking = "none" | "serial" | "batch";
+/** Another unit an article comes in. `factor` = base units in one: a roll of 500 m is 500. */
+export interface ProductUnit {
+    key: string;
+    /** A pack of this article's own ("tray van 24"); absent = the fixed unit's name for `key`. */
+    label?: string;
+    factor: number;
+    /** One GTIN per packaging level (GS1): scanning the box counts ten at once. */
+    gtin?: string;
+}
+/**
+ * An article in use in one administration. No release = not offered there. A variant has its own
+ * (its own cost); a parent with variants has none.
+ */
+export interface ProductRelease {
+    id: string;
+    organizationId: string;
+    productId: string;
+    businessEntityId: string;
+    /** Key into that administration's VAT codes, never the percentage itself. */
+    taxRateKey: string;
+    /** A {@link ProductLedgerCategory} key: which revenue or cost account a line books to. */
+    ledgerCategoryKey?: string;
     /**
-     * Which revenue account a line books to, copied onto the line. Not `categoryKey`: that one
-     * groups the offering for price agreements, and "discount on services" names no account.
+     * What we normally pay for this. **Not** a cost price out of an inventory valuation. Shielded by
+     * `catalog.product.cost`, and never in a template context.
      */
-    ledgerCategoryKey?: string;
-    /** References to this product elsewhere (`moneybird:412`). A reference, never a copy. */
-    externalIds?: string[];
+    referenceCost?: ReferenceCost;
+    /** Stopped in this administration only: no new commitments, running ones carry on. */
+    blocked?: boolean;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/** A cost with its own currency, period and date: $ 240 per year, as of 28-09. */
+export interface ReferenceCost {
+    cents: Cents;
+    currency: string;
+    per?: PricePer;
+    asOf: number;
+    /** The purchase offer it comes from; absent = typed by hand. Read-only in the form then. */
+    offerId?: string;
+    supplierCompanyId?: string;
+}
+/** A small table of its own, never free text: price agreements and reports name it. */
+export interface ProductCategory {
+    id: string;
+    organizationId: string;
+    key: string;
+    name: string;
+    order?: number;
+    archived?: boolean;
+}
+/**
+ * Which account a line books to, in either direction: "hardware" is revenue 8000 on a sale and
+ * cost 7000 on a purchase, through finance's mapping. Catalog's list; finance reads it as the
+ * contract's `LedgerCategory { key, label }` and maps it.
+ */
+export interface ProductLedgerCategory {
+    id: string;
+    organizationId: string;
+    key: string;
+    name: string;
+    order?: number;
+    archived?: boolean;
+}
+/**
+ * Sales' own row per article and administration: the price and how it bills. Absent row, or no
+ * `listPriceCents` = no price — which is not € 0 (plan 046 #12).
+ */
+export interface SalesProduct {
+    id: string;
+    organizationId: string;
+    productId: string;
+    businessEntityId: string;
+    listPriceCents?: Cents;
+    currency: string;
     /**
-     * Hours booked on this `WorkType.key` are invoiced as this product. Here and not on the work
-     * type: time must not know sales, and several products may share one type (junior/senior).
+     * The period the list price is for: € 222 per year. Absent = once, or per unit. A recurring
+     * agreement line needs one; the run bills its share of each window.
      */
-    workTypeKey?: string;
+    pricePer?: PricePer;
     /**
      * `unit`: a price per unit through the ladder (list price, tiers, customer agreements).
      * `rated`: every record priced on a rate card by its dimensions (calls, traffic).
@@ -52,61 +142,34 @@ export interface Product {
     pricing?: ProductPricing;
     /** The default card of a `rated` product. A price agreement may name another. */
     rateCardId?: string;
-    /** See {@link FIXED_UNITS}. Drives the form and the word after the quantity. */
-    unitKey: string;
-    /** Key into the organisation's VAT table, never the percentage itself. */
-    taxRateKey: string;
-    listPriceCents: Cents;
-    currency: string;
-    /**
-     * The period the list and cost price are for: € 222 per year. Absent = once, or per unit.
-     * A recurring agreement line needs one; the run bills its share of each window.
-     */
-    pricePer?: PricePer;
-    /**
-     * What we normally pay for this. **Not** a cost price out of an inventory valuation.
-     *
-     * Copied onto the line when it is added, and shielded: margin is not for everyone holding
-     * `sales.product.read`. It never reaches a template context either — `{line.cost}` on a quote
-     * would be one typo away.
-     */
-    costPriceCents?: Cents;
-    /** The period the cost price is for, when it differs from {@link Product.pricePer}. */
-    costPricePer?: PricePer;
-    /** The purchase offer the cost comes from; absent = typed by hand. Read-only in the form then. */
-    costOfferId?: string;
-    /** Who we buy it from. A `Company` in crm, so free — and all a later purchase order needs. */
-    supplierCompanyId?: string;
-    /**
-     * The administration this belongs to. Unset = the default one — see `belongsToEntity`.
-     *
-     * Exactly one, not a list: two administrations that both sell this keep two rows, with their
-     * own sku, their own price and their own ledger category. That is the price of a hard split and
-     * it is what was chosen.
-     */
-    businessEntityId?: string;
-    /** On quotes, invoices and agreements. Absent = yes; steel plate you only buy is `false`. */
-    sellable?: boolean;
-    /** On purchase orders. Absent = no. */
-    purchasable?: boolean;
-    archived?: boolean;
-    order?: number;
-    createdBy: string;
-    createdAt?: number;
+    /** The unit a new line starts in (a box); absent = the base unit. */
+    unitKey?: string;
     updatedAt?: number;
 }
-/** The cost price in the period of the list price, for a margin. Absent without a cost price. */
-export declare function costInPricePeriod(product: Pick<Product, "costPriceCents" | "costPricePer" | "pricePer">): Cents | undefined;
+/**
+ * An article as sales sees it in one administration: catalog's article, its release, and sales'
+ * own row, flat. A read model — nothing stores it. See {@link sellableProduct}.
+ */
+export interface SellableProduct extends Product, Partial<Pick<ProductRelease, "taxRateKey" | "ledgerCategoryKey" | "referenceCost" | "blocked">>, Omit<Partial<SalesProduct>, "id" | "organizationId" | "productId" | "unitKey" | "updatedAt"> {
+    /** The price list's currency, else the administration's: what price rules are matched on. */
+    currency: string;
+    /** Sales' default unit for a new line. */
+    salesUnitKey?: string;
+    /** Whether this administration has released it at all. */
+    released: boolean;
+}
+/** Puts the three rows together. `currency` is the administration's, for an article without a price. */
+export declare function sellableProduct(product: Product, release: ProductRelease | undefined, sales: SalesProduct | undefined, currency: string): SellableProduct;
 /** Whether a sales picker offers it: absent counts as sellable, so older products stay. */
 export declare function isSellable(product: Pick<Product, "sellable" | "archived">): boolean;
 /** Whether a purchase picker offers it. */
 export declare function isPurchasable(product: Pick<Product, "purchasable" | "archived">): boolean;
+export type ProductPricing = "unit" | "rated";
 /**
  * Units follow work's `FIXED_TYPES` pattern: a fixed list plus a namespaced fallback, so an
  * unknown key reads as itself instead of breaking.
  */
-export type ProductPricing = "unit" | "rated";
-export declare const FIXED_UNITS: readonly ["piece", "hour", "day", "month", "km", "license", "minute", "kg", "ton", "m", "m2", "m3", "liter"];
+export declare const FIXED_UNITS: readonly ["piece", "hour", "day", "month", "km", "license", "minute", "kg", "ton", "m", "m2", "m3", "liter", "box", "roll", "pallet", "pack"];
 export type FixedUnit = (typeof FIXED_UNITS)[number];
 /**
  * A price for a customer, a segment or a contract.
@@ -179,6 +242,10 @@ export interface SaveProductRequest extends Partial<Omit<Product, "id" | "organi
     id?: string;
     name: string;
 }
+export interface SaveReleaseRequest extends Partial<Omit<ProductRelease, "id" | "organizationId" | "createdBy" | "createdAt" | "updatedAt">> {
+    productId: string;
+    businessEntityId: string;
+}
 export interface SavePriceRuleRequest extends Partial<Omit<PriceRule, "id" | "organizationId" | "createdBy" | "createdAt">> {
     id?: string;
 }

package/dist/entities/catalog/usage-source.d.ts

@@ -34,6 +34,17 @@ export interface UsageMeter {
      * is nothing to pick, and the customer's id is the account. Absent = `source`.
      */
     account?: "source" | "customer";
+    /**
+     * Billing increments worth offering beyond the generic ones (as used, first unit whole, per
+     * started unit): hours per started quarter. In meter units; `label` is a `locales` key.
+     */
+    increments?: UsageIncrement[];
+}
+/** `{ first: 900, next: 900 }` = per started quarter of an hour, in seconds. */
+export interface UsageIncrement {
+    first: number;
+    next: number;
+    label: string;
 }
 export interface UsageDimension {
     key: string;

package/dist/entities/organization/types.d.ts

@@ -34,6 +34,8 @@ export interface Organization {
     scopes: string[];
     domain: string;
     defaultApp?: string;
+    /** Where a member lands with no deeplink or last tab (plan 048); absent = the first visible. */
+    defaultWorkspace?: string;
     permissions?: string[];
     /** Tenant slug, mirrored from system.tenants. */
     slug?: string;

package/dist/entities/purchase/logic.d.ts

@@ -11,17 +11,23 @@ export interface GoodsReceiptProblem {
 }
 /**
  * Why a receipt cannot be booked: more in than still open, more back than came in, or serial
- * numbers that do not match the count. No serials is fine (bulk goods); some serials must be all.
+ * numbers that do not match the count in base units. No serials is fine (bulk goods); some serials
+ * must be all.
  */
-export declare function goodsReceiptProblems(receipt: Pick<GoodsReceipt, "movement" | "lines">, poLines: readonly Pick<PurchaseLine, "id" | "quantity">[], booked: readonly GoodsReceipt[]): GoodsReceiptProblem[];
+export declare function goodsReceiptProblems(receipt: Pick<GoodsReceipt, "movement" | "lines">, poLines: readonly Pick<PurchaseLine, "id" | "quantity" | "factor">[], booked: readonly GoodsReceipt[]): GoodsReceiptProblem[];
 /** Lines of a receipt worth keeping: a positive quantity, serials trimmed and unique. */
 export declare function cleanReceiptLines(lines: readonly GoodsReceiptLine[]): GoodsReceiptLine[];
 /** Valid on `at`. */
 export declare function offerValid(offer: Pick<SupplierOffer, "validFrom" | "validTo">, at: number): boolean;
 /** The offer that prices the product: the marked default if valid, else the first valid one. */
 export declare function defaultOffer<T extends SupplierOffer>(offers: readonly T[], at: number): T | null;
-/** Purchase units → product units: two rolls of 500 m are 1,000 m. */
-export declare function toProductUnits(offer: Pick<SupplierOffer, "unitsPerPurchaseUnit">, qty: number): number;
+/**
+ * Purchase units → base units: two rolls of 500 m are 1,000 m. Takes an offer or an order line —
+ * a receipt counts with the factor the line was ordered at, never today's offer (plan 046 #14).
+ */
+export declare function toProductUnits(source: {
+    factor?: number;
+}, qty: number): number;
 /**
  * The offer's cost per product unit, as amount, currency and period — what is written back to the
  * product. Never a monthly equivalent: € 222 per year stays € 222 per year.

package/dist/entities/purchase/types.d.ts

@@ -1,4 +1,5 @@
 import { ProvisioningAction, ProvisioningState } from '../../platform/provisioning';
+import { LineRhythm } from '../agreement/types';
 import { Cents } from '../money/money';
 import { PricePer } from '../money/period-price';
 import { PostalAddress } from '../organization/types';
@@ -24,14 +25,17 @@ export interface SupplierOffer {
     costCents: Cents;
     currency: string;
     per?: PricePer;
-    /** The supplier's term: an NCE yearly licence is `year` even when billed monthly. */
-    term?: "month" | "year" | "3year";
+    /**
+     * The supplier's commitment in months (1, 12, 24, 36), in sales' words (`Commitment.termMonths`):
+     * an NCE yearly licence is 12 even when billed monthly. Absent = cancel any time.
+     */
+    termMonths?: number;
     /** How often they invoice; `costCents` is per `per`, not per invoice. */
-    billedEvery?: "month" | "year" | "once";
-    /** What you order in: a roll, a pallet, a box of 50. Absent = the product's own unit. */
-    purchaseUnit?: string;
-    /** Product units in one purchase unit: a roll of 500 m is 500. */
-    unitsPerPurchaseUnit?: number;
+    billedEvery?: LineRhythm;
+    /** What you order in: a roll, a pallet, a box of 50. Absent = the article's base unit. */
+    unitKey?: string;
+    /** Base units in one `unitKey` (a roll of 500 m is 500). Absent = the article's own factor, else 1. */
+    factor?: number;
     validFrom?: number;
     validTo?: number;
     minQty?: number;

package/dist/entities/transaction/types.d.ts

@@ -181,7 +181,13 @@ export interface TransactionLine {
     name: string;
     description?: string;
     unitKey: string;
+    /**
+     * Base units in one `unitKey`, fixed when the line was added (a box of 10 is 10). Absent = 1.
+     * Receipt, delivery and invoice count with this, never with today's article (plan 046 #14).
+     */
+    factor?: number;
     quantity: number;
+    /** Per `unitKey`: a box of 10 at € 3 a piece is € 30. */
     unitPriceCents: Cents;
     /** The period the unit price is for ("€ 25 per month"). Absent = once, per unit. */
     pricePer?: PricePer;
@@ -193,7 +199,10 @@ export interface TransactionLine {
     netCents: Cents;
     /** This line's share of its rate group's VAT. Shielded, like the cost price. */
     taxCents: Cents;
-    /** The cost price as it stood when the line was added. Shielded by `sales.product.cost`. */
+    /**
+     * The cost price as it stood when the line was added, per `unitKey`, **in the document's
+     * currency** (converted on that day, plan 046 #16). Shielded by `catalog.product.cost`.
+     */
     costPriceCents?: Cents;
     /** The mapping axis onto a chart of accounts, copied from the product's category. */
     ledgerCategoryKey?: string;