@opencxh/domain 1.294.0 → 1.295.1

package/dist/entities/purchase/contract.test.d.ts

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

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

@@ -0,0 +1,68 @@
+import { ProvisionableOffer, ProvisioningAction } from '../../platform/provisioning';
+import { Agreement } from '../agreement/types';
+import { PurchaseAgreement } from './contract';
+import { SupplierOffer } from './types';
+/** One thing to order, change or end, as "Te bestellen" lists it. */
+export interface DemandItem {
+    /** Stable: the sales series, or the customer's account at the supplier. */
+    key: string;
+    action: ProvisioningAction;
+    level: "account" | "item";
+    supplierCompanyId: string;
+    offerId: string;
+    productId: string;
+    name: string;
+    /** Purchase: how many. Change: by how many. End: the current count. */
+    quantity: number;
+    /** A change: the count it should be after, and the count it is now. */
+    targetQuantity?: number;
+    from?: number;
+    customerCompanyId: string;
+    salesLine?: {
+        agreementId: string;
+        seriesId: string;
+    };
+    contractLine?: {
+        contractId: string;
+        lineId: string;
+    };
+    /** Epoch ms it takes effect: the term's end for an end or a reduction outside the window. */
+    effectiveAt?: number;
+    /** The last day to send it for `effectiveAt`; past it, `effectiveAt` is the next term's end. */
+    deadline?: number;
+    /** A reduction outside the change window: not renewing the difference, not lowering now. */
+    atRenewal?: boolean;
+    /** The notice was too late for this term: it ends at the next one. */
+    nextTerm?: boolean;
+    /** The purchase runs on after the sale ends: we pay until then. */
+    runsOnUntil?: number;
+    /** The account item this waits for. */
+    waitsFor?: string;
+    /** It lands on another platform than the supplier's (a Telnyx number on Eylo). */
+    deliverTo?: {
+        app: string;
+        offer: string;
+    };
+}
+export interface DemandInput {
+    agreements: readonly Agreement[];
+    contracts: readonly PurchaseAgreement[];
+    offers: readonly SupplierOffer[];
+    /** Provider describes, by `app:offer`. */
+    provisionable: ReadonlyMap<string, ProvisionableOffer>;
+    /** Keys already on an order that has not settled: never proposed twice. */
+    open: ReadonlySet<string>;
+    now: number;
+}
+/**
+ * What to order, change or end so purchase follows sales (fase 9). Per sales series with a fixed
+ * count and a default offer:
+ * - no contract line passes it on: buy the count;
+ * - the contract has fewer: one change to the new count;
+ * - the contract has more: lower it now inside the supplier's change window, else do not renew
+ *   the difference at the term's end;
+ * - the sale has an end: end the purchase at the first term end the notice still reaches, with
+ *   the deadline to send it by, and a signal when we pay on after the customer stopped.
+ * An item that needs the customer's account at the supplier gets that account first.
+ */
+export declare function demandFor(input: DemandInput): DemandItem[];

package/dist/entities/purchase/demand.test.d.ts

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

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

@@ -0,0 +1,7 @@
+export * from './contract';
+export * from './demand';
+export * from './kinds';
+export * from './logic';
+export * from './match';
+export * from './packing-slip';
+export * from './types';

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

@@ -0,0 +1,8 @@
+import { TransactionKind } from '../transaction/kinds';
+/**
+ * What `apps/purchase` issues: the same engine as a quote, its own table. `sent` is issued (a
+ * number and the paper); the supplier confirms, and the goods coming in make it `received`.
+ * Walking back one step stays allowed — a return reopens a received order.
+ */
+export declare const PURCHASE_KINDS: readonly TransactionKind[];
+export declare const PURCHASE_ORDER_KIND = "purchase_order";

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

@@ -0,0 +1,35 @@
+import { PricePer } from '../money/period-price';
+import { GoodsReceipt, GoodsReceiptLine, PurchaseLine, SupplierOffer } from './types';
+/** What came in for one order line: booked receipts in, returns out. */
+export declare function receivedFor(poLineId: string, receipts: readonly GoodsReceipt[]): number;
+export type ReceiptState = "none" | "partial" | "full";
+/** Over the product lines of an order. */
+export declare function receiptState(lines: readonly Pick<PurchaseLine, "kind" | "quantity" | "receivedQty">[]): "none" | "partial" | "full";
+export interface GoodsReceiptProblem {
+    code: "receipt_over_ordered" | "receipt_return_over_received" | "receipt_serials_count";
+    poLineId: string;
+}
+/**
+ * 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.
+ */
+export declare function goodsReceiptProblems(receipt: Pick<GoodsReceipt, "movement" | "lines">, poLines: readonly Pick<PurchaseLine, "id" | "quantity">[], 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;
+/**
+ * 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.
+ */
+export declare function productCost(offer: SupplierOffer): {
+    cents: number;
+    currency: string;
+    per?: PricePer;
+};
+/** Offers side by side: each over one year, per product unit. A one-off stays itself. */
+export declare function costOverYear(offer: SupplierOffer): number;

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

@@ -0,0 +1,98 @@
+import { Cents } from '../money/money';
+import { PricePer } from '../money/period-price';
+import { MatchCandidate, MatchedVia } from './packing-slip';
+import { SupplierOffer } from './types';
+/** What an invoice line pays for: an order line, or a contract line over a period. */
+export type InvoiceTarget = {
+    kind: "po_line";
+    orderId: string;
+    lineId: string;
+} | {
+    kind: "contract_line";
+    contractId: string;
+    lineId: string;
+    period: {
+        from: number;
+        to: number;
+    };
+};
+/** A supplier invoice line as the match reads it — `ReceiptLine`, narrowed. */
+export interface InvoiceLine {
+    id: string;
+    description?: string;
+    sku?: string;
+    externalRef?: string;
+    quantity?: number;
+    netCents: Cents;
+    /** As printed: `to` inclusive. */
+    period?: {
+        from: string;
+        to: string;
+    };
+}
+/** An open order line or a running contract line of this supplier, with what it expects. */
+export interface InvoiceCandidate extends MatchCandidate {
+    kind: "po_line" | "contract_line";
+    /** The order or contract. */
+    parentId: string;
+    businessEntityId: string;
+    unitPriceCents: Cents;
+    pricePer?: PricePer;
+    discountPercent?: number;
+    /** Order line: what is still to invoice. Contract line: the agreed count, `null` when counted. */
+    openQty: number | null;
+    /** A contract line whose invoice decides the amount: nothing expected. */
+    variable?: boolean;
+    use?: "own" | "resale";
+    customerCompanyId?: string;
+}
+export interface MatchAllocation {
+    receiptLineId: string;
+    target: InvoiceTarget;
+    via: MatchedVia;
+    quantity: number;
+    amountCents: Cents;
+    /** What this part should have cost; `null` for a variable line. */
+    expectedCents: Cents | null;
+    /** More than the order line still had open, or another count than the contract's. */
+    overQuantity: boolean;
+    businessEntityId: string;
+    productId?: string;
+    use?: "own" | "resale";
+    customerCompanyId?: string;
+}
+/**
+ * Invoice lines onto order and contract lines, many to many. Each line goes to its best candidates
+ * ({@link lineAffinity}); a count larger than one order line has open runs on to the next of the
+ * same article (10 phones over two orders of 6 and 4), the amount split by count. A contract line
+ * takes the line whole, for the period printed on it or else `defaultPeriod` (the invoice's month).
+ */
+export declare function allocateInvoice(lines: readonly InvoiceLine[], candidates: readonly InvoiceCandidate[], offers: readonly Pick<SupplierOffer, "id" | "productId" | "vendorSku">[], defaultPeriod: {
+    from: number;
+    to: number;
+}): {
+    allocations: MatchAllocation[];
+    unmatched: string[];
+};
+export interface MatchTolerance {
+    percent: number;
+    cents: Cents;
+}
+/** One per cent or one euro, whichever is more: a rounding difference is not work. */
+export declare const DEFAULT_TOLERANCE: MatchTolerance;
+export type MatchIssue = "price" | "quantity" | "unmatched";
+export interface MatchVerdict {
+    /** Everything matched, at the expected price and count: approve without a person. */
+    ok: boolean;
+    issues: {
+        receiptLineId: string;
+        issue: MatchIssue;
+        expectedCents?: Cents;
+        amountCents?: Cents;
+    }[];
+}
+/**
+ * Whether an invoice is what was ordered or agreed: every line matched, every count within what
+ * was open, every amount within the tolerance (% and absolute). Anything else is work.
+ */
+export declare function matchVerdict(allocations: readonly MatchAllocation[], unmatched: readonly string[], tolerance?: MatchTolerance): MatchVerdict;

package/dist/entities/purchase/match.test.d.ts

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

package/dist/entities/purchase/packing-slip.d.ts

@@ -0,0 +1,82 @@
+import { GoodsReceipt, GoodsReceiptLine, PurchaseLine, PurchaseOrder, SupplierOffer } from './types';
+/** One line as a supplier's document states it: their code, their words, a count, serials. */
+export interface DocumentLine {
+    sku?: string;
+    description: string;
+    quantity: number;
+    serials: string[];
+}
+/** What a packing slip says, read from a pdf, a picture or a sheet. */
+export interface PackingSlipContent {
+    /** Their packing-slip number. */
+    supplierRef?: string;
+    /** Our order number as they printed it ("Uw referentie IO2026-0013"). */
+    orderRef?: string;
+    /** `YYYY-MM-DD`. */
+    deliveredOn?: string;
+    lines: DocumentLine[];
+}
+/**
+ * One line per article: a sheet lists devices one per row (1 × toestel, serial S1), and a person
+ * reads that as 4 × toestel with four serials.
+ */
+export declare function groupDocumentLines(lines: readonly DocumentLine[]): DocumentLine[];
+/** The order a document is about: our number first, then their reference on it. `null` = none. */
+export declare function orderForDocument<T extends Pick<PurchaseOrder, "number" | "reference">>(doc: Pick<PackingSlipContent, "orderRef" | "supplierRef">, orders: readonly T[]): T | null;
+export type MatchedVia = "reference" | "sku" | "description";
+/** Something a document line can be matched to: an order line, a contract line. */
+export interface MatchCandidate {
+    id: string;
+    productId?: string;
+    offerId?: string;
+    name: string;
+    /** Their subscription id, when the candidate knows it (a contract line). */
+    externalRef?: string;
+}
+export interface LineMatch {
+    docIndex: number;
+    poLineId: string;
+    via: MatchedVia;
+}
+/**
+ * How well a document line is this candidate, or not at all: their subscription id, then their
+ * article code (on the offer it was bought on, or any offer of that product), then the words.
+ * One ranking for packing slips and invoices alike.
+ */
+export declare function lineAffinity(doc: {
+    sku?: string;
+    description?: string;
+    externalRef?: string;
+}, candidate: MatchCandidate, offers: readonly Pick<SupplierOffer, "id" | "productId" | "vendorSku">[]): {
+    via: MatchedVia;
+    rank: number;
+} | null;
+/**
+ * Which order line each document line is, by {@link lineAffinity}; each order line is taken once,
+ * the best free one wins. What stays unmatched is an exception for a person.
+ */
+export declare function matchDocumentLines(docLines: readonly DocumentLine[], poLines: readonly Pick<PurchaseLine, "id" | "kind" | "productId" | "offerId" | "name">[], offers: readonly Pick<SupplierOffer, "id" | "productId" | "vendorSku">[]): {
+    matches: LineMatch[];
+    unmatched: number[];
+};
+export type SlipProblemCode = "slip_no_order" | "slip_unknown_item" | "receipt_over_ordered" | "receipt_serials_count";
+export interface SlipProblem {
+    code: SlipProblemCode;
+    docIndex?: number;
+    poLineId?: string;
+}
+export interface SlipProposal {
+    lines: (GoodsReceiptLine & {
+        docIndex: number;
+        via: MatchedVia;
+    })[];
+    problems: SlipProblem[];
+}
+/**
+ * A packing slip as a receipt to book: the matched lines with their counts and serials, and what a
+ * person has to decide — no order, an article not on it, more than is open, serials that do not
+ * match the count. Recomputed against the receipts booked so far, never stored stale.
+ */
+export declare function slipProposal(slip: PackingSlipContent, order: Pick<PurchaseOrder, "lines"> | null, offers: readonly Pick<SupplierOffer, "id" | "productId" | "vendorSku">[], booked: readonly GoodsReceipt[]): SlipProposal;
+/** A model's answer as slip content, as far as it holds; `null` when it is no JSON at all. */
+export declare function parsePackingSlip(answer: string): PackingSlipContent | null;

package/dist/entities/purchase/packing-slip.test.d.ts

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

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

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

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

@@ -0,0 +1,147 @@
+import { ProvisioningAction, ProvisioningState } from '../../platform/provisioning';
+import { Cents } from '../money/money';
+import { PricePer } from '../money/period-price';
+import { PostalAddress } from '../organization/types';
+import { Transaction, TransactionLine } from '../transaction/types';
+/**
+ * What a supplier asks for a product: one row per supplier and product (and validity window).
+ * The default offer is the product's cost price; the rest are the alternatives a buyer compares.
+ */
+export interface SupplierOffer {
+    id: string;
+    organizationId: string;
+    businessEntityId?: string;
+    supplierCompanyId: string;
+    productId: string;
+    /** Their article number. */
+    vendorSku?: string;
+    /**
+     * `unit`: a price per purchase unit. `rated`: per record on their rate card (telecom transit) —
+     * refused until that part exists, so nobody stores a price that means nothing yet.
+     */
+    pricing: "unit" | "rated";
+    /** Per purchase unit, for `per` (€ 222 per year) or once. */
+    costCents: Cents;
+    currency: string;
+    per?: PricePer;
+    /** The supplier's term: an NCE yearly licence is `year` even when billed monthly. */
+    term?: "month" | "year" | "3year";
+    /** 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;
+    validFrom?: number;
+    validTo?: number;
+    minQty?: number;
+    leadDays?: number;
+    /** Days from each term's start the supplier still takes a change (NCE: 7). */
+    changeWindowDays?: number;
+    /** Ordered through an app instead of by mail (fase 9). */
+    provider?: {
+        app: string;
+        offer: string;
+    };
+    /**
+     * Where it lands when that is not the supplier (fase 9b): a Telnyx number on the customer's
+     * Eylo account. The platform's own offer takes it in, after the purchase.
+     */
+    deliverTo?: {
+        app: string;
+        offer: string;
+    };
+    isDefault: boolean;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/** Ours to keep, or sold on to a customer — decides where the cost books (fase 6). */
+export type PurchaseUse = "own" | "resale";
+export interface PurchaseLine extends TransactionLine {
+    offerId?: string;
+    /** Sum of the booked receipts, in purchase units; recomputed, never added to. */
+    receivedQty: number;
+    /** Matched to supplier invoices (fase 7). */
+    billedQty: number;
+    use: PurchaseUse;
+    dimensions?: {
+        costCenterId?: string;
+        projectId?: string;
+    };
+    /** Absent = `purchase`. A change or an end points at the contract line it is about. */
+    action?: ProvisioningAction;
+    contractLine?: {
+        contractId: string;
+        lineId: string;
+    };
+    /** A change: the count it should be after. */
+    targetQuantity?: number;
+    /** When a change or end takes effect (epoch ms): the end of the term, not today. */
+    effectiveAt?: number;
+    /** Where this line came from in "Te bestellen", so it is not proposed twice. */
+    demandKey?: string;
+    /** The line of this order it waits for (the customer's account before its numbers). */
+    waitsFor?: string;
+    /** The supplier's ordering fields (a domain, a region). */
+    params?: Record<string, string>;
+    provisioning?: LineProvisioning;
+    /** The second step when the offer lands elsewhere (`deliverTo`): after a buy, before an end. */
+    delivery?: LineProvisioning;
+}
+/**
+ * A line's request at the supplier. `waiting`: its account is not there yet. `manual`: no API —
+ * a person does it and fills in the result.
+ */
+export interface LineProvisioning {
+    state: ProvisioningState | "waiting" | "manual";
+    requestId: string;
+    app?: string;
+    externalRef?: string;
+    fulfillment?: Record<string, string>;
+    missing?: {
+        key: string;
+        reason: string;
+    }[];
+    error?: string;
+    attempts?: number;
+    nextAttemptAt?: number;
+    updatedAt?: number;
+}
+export interface DeliverTo {
+    kind: "own" | "customer" | "site";
+    companyId?: string;
+    address?: PostalAddress;
+}
+/** A purchase order: a `Transaction` of kind `purchase_order`; `companyId` is the supplier. */
+export interface PurchaseOrder extends Omit<Transaction, "lines"> {
+    lines: PurchaseLine[];
+    deliverTo: DeliverTo;
+    /** Bought for this customer (the M365 seats for Acme). */
+    customerCompanyId?: string;
+}
+export interface GoodsReceiptLine {
+    poLineId: string;
+    /** Purchase units; positive, the movement says the direction. */
+    quantity: number;
+    serials: string[];
+    /** Still to come, as the packing slip says. */
+    backorderQty?: number;
+}
+/** Goods in (or back out). Booked is final: a mistake is corrected with a return. */
+export interface GoodsReceipt {
+    id: string;
+    organizationId: string;
+    businessEntityId?: string;
+    movement: "in" | "return";
+    purchaseOrderId: string;
+    supplierCompanyId: string;
+    receivedAt: number;
+    receivedBy: string;
+    source: "manual" | "upload" | "mail";
+    fileId?: string;
+    supplierRef?: string;
+    status: "draft" | "booked";
+    lines: GoodsReceiptLine[];
+    createdAt?: number;
+}

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

@@ -34,7 +34,7 @@ export type OwnerScope = {
     teamId: string;
 } | {
     kind: "org";
-    organizationId: string;
+    organizationId?: string;
 };
 /**
  * A scope that cannot be personal.

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

@@ -1,6 +1,7 @@
 import { DocumentBlock } from '../../platform/document-blocks';
 import { DocumentSlots, TemplateContext } from '../document-template/tokens';
 import { TemplateCondition } from '../document-template/types';
+import { PricePer } from '../money/period-price';
 import { TaxRate } from '../money/tax';
 import { PostalAddress } from '../organization/types';
 import { Transaction } from './types';
@@ -56,6 +57,8 @@ export interface SlotLabels {
     optional: string;
     quantity: string;
     unitPrice: string;
+    /** After a period price: "222,00 per jaar". */
+    per: Record<PricePer, string>;
     net: string;
     tax: string;
     gross: string;

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

@@ -7,19 +7,13 @@
  * `invoice:412` even if invoices ever move to a finance app; one branded `sales_document:412`
  * would mean a backfill across four apps.
  */
-export declare const TRANSACTION_SCOPE_KINDS: readonly string[];
+export declare const SALES_SCOPE_KINDS: readonly string[];
 export declare const PRODUCT_SCOPE_KIND = "product";
 /** An agreement: what a customer takes every period. Puts it in the customer file. */
 export declare const AGREEMENT_SCOPE_KIND = "agreement";
 /** `invoice:412`. The kind of a transaction *is* its kind key — no mapping table. */
 export declare function transactionScopeKey(kindKey: string, id: string): string;
 export declare function productScopeKey(id: string): string;
-/**
- * The shell path of a document, under the administration it belongs to.
- *
- * `fallbackEntityId` is for a row that predates administrations (`""` = the default one); without
- * either there is no screen to point at, and no link beats a dead one.
- */
 export declare function transactionHref(row: {
     id: string;
     kindKey: string;

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

@@ -53,6 +53,13 @@ export interface TransactionKind {
      */
     credits?: string;
 }
+/** What `apps/sales` issues. Another app's kinds live in their own list, same shape. */
+export declare const SALES_KINDS: readonly TransactionKind[];
+/**
+ * Every app's kinds, for looking one up by key. Keys are unique across apps (`invoice` is sales',
+ * `purchase_order` will be purchase's), so a key alone names its kind. Never enumerate this in an
+ * app: sales lists {@link SALES_KINDS}, or a purchase kind claims sales scopes and series.
+ */
 export declare const TRANSACTION_KINDS: readonly TransactionKind[];
 /**
  * Which kinds the app actually offers today.

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

@@ -3,6 +3,7 @@ import { DocumentBlock } from '../../platform/document-blocks';
 import { LineUsage } from '../agreement/types';
 import { DocumentSender } from '../document-template/types';
 import { Cents } from '../money/money';
+import { PricePer } from '../money/period-price';
 import { TaxRateKind } from '../money/tax';
 import { OwnerScope } from '../scope/types';
 import { TransactionPaymentTerm } from './payment-term';
@@ -47,6 +48,11 @@ export interface Transaction {
     title?: string;
     reference?: string;
     currency: string;
+    /**
+     * Euro per unit of `currency`, set when issued in a currency the administration does not keep
+     * its books in (the ECB rate of that day). Absent in the books' own currency.
+     */
+    fxRate?: string;
     status: TransactionStatus;
     /**
      * The lines, as a column and not a table.
@@ -154,7 +160,9 @@ export interface Transaction {
  * A union and not a free string: kinds and their statuses are **ours**, not the organisation's.
  * Labels follow from the key as `status_<key>`.
  */
-export type TransactionStatus = "draft" | "sent" | "accepted" | "rejected" | "expired" | "confirmed" | "delivered" | "open" | "cancelled"
+export type TransactionStatus = "draft" | "sent" | "accepted" | "rejected" | "expired" | "confirmed" | "delivered"
+/** A purchase order whose every line came in. */
+ | "received" | "open" | "cancelled"
 /** A newer version of this document went out. Set by the server, never by a person. */
  | "superseded";
 export interface IssuedPaper {
@@ -175,6 +183,8 @@ export interface TransactionLine {
     unitKey: string;
     quantity: number;
     unitPriceCents: Cents;
+    /** The period the unit price is for ("€ 25 per month"). Absent = once, per unit. */
+    pricePer?: PricePer;
     discountPercent?: number;
     taxRateKey: string;
     /** Which rung of the price ladder produced this amount. Purely to account for it. */