@opencxh/domain 1.293.0 → 1.295.0

package/dist/entities/ledger/template.d.ts

@@ -33,3 +33,8 @@ export interface LedgerTemplate {
  */
 export declare const NL_BV_TEMPLATE: LedgerTemplate;
 export declare const LEDGER_TEMPLATES: readonly LedgerTemplate[];
+/**
+ * The categories a payroll journal books on (HRM, or a package like Nmbrs or Loket), and the
+ * template account each lands on unless a posting rule says otherwise.
+ */
+export declare const PAYROLL_CATEGORIES: Readonly<Record<string, string>>;

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

@@ -19,6 +19,11 @@ export interface LedgerAccount {
     };
     /** Accounts with detail (bank, loan, current account) require a `subAccountId` on every line. */
     requiresSubAccount?: boolean;
+    /**
+     * The VAT code a line on this account usually carries (`TaxCode.key`, e.g. `high`): proposed
+     * when a bank line is booked straight onto it. Empty is none.
+     */
+    defaultTaxCode?: string;
     /** Where it sits in the reports: `"revenue.net"`, `"costs.office"`. The reports are not hard-coded. */
     reportGroup?: string;
     order?: number;
@@ -29,7 +34,9 @@ export interface LedgerAccount {
     createdAt?: number;
     updatedAt?: number;
 }
-export type LedgerAccountRole = "debtors" | "creditors" | "vat_payable" | "vat_receivable" | "revenue_default" | "expense_default" | "suspense" | "result";
+export type LedgerAccountRole = "debtors" | "creditors" | "vat_payable" | "vat_receivable" | "revenue_default" | "expense_default" | "suspense" | "result"
+/** Where the difference lands when a foreign document is paid at another rate than booked. */
+ | "fx_difference";
 export type JournalKind = "sales" | "purchase" | "bank" | "cash" | "memorial" | "opening";
 export interface Journal {
     id: string;
@@ -155,7 +162,7 @@ export interface PostingRule {
     organizationId: string;
     businessEntityId: string;
     appliesTo: {
-        direction: "sale" | "purchase";
+        direction: BookingDocument["direction"];
         kind?: BookingDocument["kind"];
     };
     match: {

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

@@ -1,3 +1,5 @@
 export * from './money';
+export * from './month-parts';
+export * from './period-price';
 export * from './tax';
 export * from './totals';

package/dist/entities/money/month-parts.d.ts

@@ -0,0 +1,19 @@
+import { Cents } from './money';
+/**
+ * `total` over the calendar months of a period (`to` inclusive, as printed): a whole month one
+ * share, a part of one by its days, in whole cents that add up exactly — leftover cents to the
+ * first months, as `allocate` does. One distribution for revenue and cost alike, so a month's
+ * margin is the same sum on both sides. `month` is each month's first day.
+ */
+export declare function monthParts(total: Cents, period: {
+    from: string;
+    to: string;
+}): {
+    month: string;
+    cents: Cents;
+}[];
+/** How many calendar months a period touches. */
+export declare function monthsIn(period: {
+    from: string;
+    to: string;
+}): number;

package/dist/entities/money/month-parts.test.d.ts

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

package/dist/entities/money/period-price.d.ts

@@ -0,0 +1,23 @@
+import { Cents } from './money';
+/** What a recurring price is for: € 25 per month, € 222 per year. */
+export type PricePer = "month" | "quarter" | "year";
+export declare const PRICE_PERS: readonly PricePer[];
+/**
+ * `total` (one `per`, all units together) over `window`, in whole cents.
+ *
+ * The distribution key is the calendar: a yearly total is split over its 12 months with
+ * `allocate` (leftover cents to the first months), a quarterly one over its 3. A month is billed
+ * as its own share, a part of a month by its days. So month 7 on its own is exactly month 7 of a
+ * yearly run, and twelve months of € 100/year add up to € 100,00. Rounded once, at the end.
+ */
+export declare function priceOver(total: Cents, per: PricePer, window: {
+    from: number;
+    to: number;
+}): Cents;
+/**
+ * An amount per `from` restated per `to` (€ 222 per year → € 18,50 per month), for comparing two
+ * prices side by side — a margin, a cost next to a list price. **Never stored**: billing goes
+ * through {@link priceOver}, which keeps the calendar split exact.
+ */
+export declare function restate(cents: Cents, from: PricePer | undefined, to: PricePer | undefined): Cents;
+export declare function isPricePer(value: unknown): value is PricePer;

package/dist/entities/money/period-price.test.d.ts

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

package/dist/entities/money/totals.d.ts

@@ -14,8 +14,12 @@ import { TaxRate } from './tax';
  * and the tax office do.
  *
  * `quantity` may be fractional (3.5 hours); a *price* never is.
+ *
+ * A price with a period (`pricePer`) on a line with a service period bills that period's share
+ * of the line total — `priceOver`, so the line total is rounded once and then split by calendar.
+ * Without a service period (a quote) it is one period's amount.
  */
-export declare function lineNet(line: TransactionLine): Cents;
+export declare function lineNet(line: Pick<TransactionLine, "kind" | "quantity" | "unitPriceCents" | "discountPercent" | "pricePer" | "servicePeriod">): Cents;
 export interface PricedTransaction {
     /** The same lines with `netCents` and `taxCents` filled in. */
     lines: TransactionLine[];

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

@@ -0,0 +1,124 @@
+import { Period } from '../agreement/period';
+import { Agreement, AgreementLine } from '../agreement/types';
+import { Cents } from '../money/money';
+/** A sales line, followed through its changes: the agreement and the series it belongs to. */
+export interface SalesLineRef {
+    agreementId: string;
+    seriesId: string;
+}
+/**
+ * A subscription at a supplier: the shape of a sales agreement line, plus where it came from and
+ * whom it is for. Its `price` is the snapshot taken when it was made — an offer that gets dearer
+ * later changes nothing here; a new price is a successor line from a date.
+ */
+export interface PurchaseAgreementLine extends AgreementLine {
+    /** Provenance only: the offer it was bought on. The price is `price`, not the offer's. */
+    offerId?: string;
+    /** Their subscription id (Pax8, Microsoft). */
+    externalRef?: string;
+    /** What the supplier handed back when it was made (a tenant id, an account id). */
+    fulfillment?: Record<string, string>;
+    /** Where it landed when that is not the supplier, so an end takes it off there first. */
+    deliveredTo?: {
+        app: string;
+        externalRef?: string;
+    };
+    customerCompanyId?: string;
+    /** The sales line that passes this on, followed by series. */
+    salesLine?: SalesLineRef;
+    /**
+     * `variable`: no price, the invoice decides the amount (transit minutes). Nothing is expected;
+     * only a jump against the last three months is work. A varying *count* (seats) is `quantity:
+     * manual|meter` with a fixed price instead — never this.
+     */
+    expected?: "variable";
+    /** Days from each term's start in which the supplier still takes a change (NCE: 7). */
+    changeWindowDays?: number;
+    /** The order line it came from, so a second receipt updates instead of adding. */
+    sourceKey?: string;
+    /** What supplier invoices said per period (fase 7): the history a variable line is judged on. */
+    invoiced?: {
+        from: number;
+        cents: Cents;
+    }[];
+}
+/** A supplier contract: `companyId` is the supplier; one contract holds many subscriptions. */
+export interface PurchaseAgreement extends Omit<Agreement, "lines"> {
+    lines: PurchaseAgreementLine[];
+}
+export interface ExpectedLine {
+    lineId: string;
+    kind: "fixed" | "count" | "variable";
+    /** Fixed lines only; a count waits for the count, a variable line expects nothing. */
+    cents?: Cents;
+}
+/**
+ * What the supplier should invoice over `window`, per line: a fixed count at the agreed price over
+ * the days it ran (the same `lineNet` the sales run bills with), or "count" / "variable" where the
+ * amount is not ours to know in advance.
+ */
+export declare function expectedFor(agreement: Pick<PurchaseAgreement, "startsAt" | "endsAt" | "lines">, window: Period): ExpectedLine[];
+/**
+ * A variable amount that moved more than `threshold` against the average of the (up to) three
+ * periods before: that is work for a person, not a number to wave through.
+ */
+export declare function variableJump(previous: readonly Cents[], current: Cents, threshold?: number): boolean;
+/** A sales line as sales reports it now, by series. */
+export interface SalesLineState extends SalesLineRef {
+    /** Fixed count now; `null` for a count from a meter or entered per period. */
+    quantity: number | null;
+    /** When it really ends if the customer gives notice today. */
+    effectiveEndAt: number;
+    /** Windows due now without an invoice line (`agreementLineId` + `servicePeriod`). */
+    unbilled: Period[];
+    /** The sales line has ended or its agreement is not active. */
+    ended?: boolean;
+}
+export type ContractSignal = {
+    kind: "not_covered";
+    contractId: string;
+    lineId: string;
+    reason: "no_sales_line" | "quantity" | "sales_ended";
+} | {
+    kind: "not_billed";
+    contractId: string;
+    lineId: string;
+    windows: Period[];
+} | {
+    kind: "term_mismatch";
+    contractId: string;
+    lineId: string;
+    purchaseEnd: number;
+    salesEnd: number;
+} | {
+    kind: "notice_due";
+    contractId: string;
+    lineId: string;
+    deadline: number;
+} | {
+    kind: "change_window";
+    contractId: string;
+    lineId: string;
+    closesAt: number;
+} | {
+    kind: "variable_jump";
+    contractId: string;
+    lineId: string;
+    cents: Cents;
+};
+export interface SignalOptions {
+    /** A notice deadline this close is a reminder. */
+    noticeDays?: number;
+    /** A change window closing this soon is a reminder. */
+    windowDays?: number;
+}
+/**
+ * Everything about a supplier contract a person should look at, apart:
+ * - **not covered**: bought for a customer, but no sales line passes it on, or another count;
+ * - **not billed**: the sales line exists but a period that is due has no invoice line — a sales
+ *   line that exists proves nothing, so this reads what sales actually invoiced;
+ * - **term mismatch**: we are bound longer than the customer is;
+ * - **notice due / change window**: reminders before the dates that decide the next term;
+ * - **variable jump**: a variable amount moved more than 30%.
+ */
+export declare function contractSignals(contracts: readonly PurchaseAgreement[], sales: readonly SalesLineState[], now: number, options?: SignalOptions): ContractSignal[];

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 {};