@opencxh/domain 1.297.0 → 1.301.0

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

@@ -0,0 +1,132 @@
+import { Cents } from '../money/money';
+import { OfferAvailability, SupplierOffer } from './types';
+/**
+ * A supplier's price and stock list as a file (plan 045 C): uploaded, mailed, or picked up from a
+ * storage folder. It only updates offers we already have; a line we do not know is listed, never
+ * turned into a product or an offer by itself.
+ */
+/** The columns a feed can fill. `vendorSku` or `gtin` is the key; the rest is optional. */
+export type FeedColumn = "vendorSku" | "gtin" | "description" | "cost" | "list" | "currency" | "stock" | "leadDays";
+export declare const FEED_COLUMNS: readonly FeedColumn[];
+/** Per column, the header it is read from. Set once (the AI proposes, a person approves). */
+export type FeedMapping = Partial<Record<FeedColumn, string>>;
+export type FeedSource = "upload" | "mail" | "storage";
+/** How often a new file is expected; it decides how long a stock figure counts as fresh. */
+export type FeedEvery = "day" | "week" | "month";
+export declare const FEED_EVERY_MS: Record<FeedEvery, number>;
+/** A price jump above this share is still applied, but said out loud. */
+export declare const DEFAULT_JUMP_PERCENT = 10;
+export interface SupplierFeed {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    supplierCompanyId: string;
+    name?: string;
+    source: FeedSource;
+    /** For `storage`: the folder it reads the newest csv from (a dated file each time is fine). */
+    storage?: {
+        mountId: string;
+        path: string;
+    };
+    /** The file the last storage run read, and how new it was: the same file is not read twice. */
+    lastFile?: {
+        id: string;
+        at: number;
+    };
+    mapping: FeedMapping;
+    /** When the file has no currency column. Absent = the administration's. */
+    currency?: string;
+    every: FeedEvery;
+    jumpPercent?: number;
+    lastRunAt?: number;
+    lastRunId?: string;
+    archived?: boolean;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/** One line of the file, read. */
+export interface FeedRow {
+    /** 1-based, the header included: what a person sees in the file. */
+    line: number;
+    vendorSku?: string;
+    gtin?: string;
+    description?: string;
+    costCents?: Cents;
+    listCents?: Cents;
+    currency?: string;
+    /** `null`: the file says nothing about stock, or "on request". */
+    stock?: number | null;
+    leadDays?: number;
+}
+export interface FeedReadResult {
+    rows: FeedRow[];
+    errors: {
+        line: number;
+        message: string;
+    }[];
+    /** A mapped header that is not in the file: the supplier changed the layout. */
+    missingHeaders: string[];
+}
+/** The file's cells, read through the mapping. Deterministic: the AI only proposed the mapping. */
+export declare function readFeed(table: readonly string[][], mapping: FeedMapping): FeedReadResult;
+/** Just enough of an article to match a feed line on its barcode. */
+export interface FeedProduct {
+    id: string;
+    gtin?: string;
+    barcodes?: string[];
+}
+export type FeedMatch = {
+    row: FeedRow;
+    offer: SupplierOffer;
+} | {
+    row: FeedRow;
+    product: FeedProduct;
+} | {
+    row: FeedRow;
+};
+/**
+ * Each line to an offer of this supplier (their article number first, then the barcode of the
+ * article it is for), else to an article without an offer yet, else to nothing.
+ * `offers` are this supplier's in this administration.
+ */
+export declare function matchFeed(rows: readonly FeedRow[], offers: readonly SupplierOffer[], products: readonly FeedProduct[]): FeedMatch[];
+export interface OfferChange {
+    offerId: string;
+    set: Partial<Pick<SupplierOffer, "costCents" | "listCents" | "currency" | "vendorSku">> & {
+        availability: OfferAvailability;
+    };
+    /** A price moved more than the feed's threshold; applied, and said. */
+    jump?: {
+        fromCents: Cents;
+        toCents: Cents;
+        percent: number;
+    };
+}
+export interface FeedUnmatched {
+    line: number;
+    vendorSku?: string;
+    gtin?: string;
+    description?: string;
+    costCents?: Cents;
+    /** An article we have, with no offer from this supplier yet: "make an offer" is one click. */
+    productId?: string;
+}
+export interface FeedOutcome {
+    changes: OfferChange[];
+    /** Offers whose price and stock stayed as they were (only the freshness moved). */
+    unchanged: number;
+    /** Offers this feed filled before and no longer lists: stock 0, nothing deleted. */
+    gone: string[];
+    unmatched: FeedUnmatched[];
+}
+/**
+ * What the run writes. Every matched offer gets a fresh stock stamp — the freshness is the
+ * point of a feed; price, advice price and currency only when the file has them.
+ */
+export declare function feedOutcome(matches: readonly FeedMatch[], offers: readonly SupplierOffer[], now: number, jumpPercent?: number): FeedOutcome;
+/**
+ * A first mapping from the header alone: an exact word, then a header that starts with one.
+ * No AI, no guessing beyond the list — what it leaves open, the AI or a person fills.
+ */
+export declare function guessFeedMapping(header: readonly string[]): FeedMapping;

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

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

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

@@ -1,5 +1,6 @@
 export * from './contract';
 export * from './demand';
+export * from './feed';
 export * from './kinds';
 export * from './logic';
 export * from './match';

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;
@@ -51,11 +55,25 @@ export interface SupplierOffer {
         app: string;
         offer: string;
     };
+    /** The supplier's advised price (the Microsoft ERP price), from a feed (plan 045 G). */
+    listCents?: Cents;
+    /** The last known stock; only the latest, no history (plan 045 B.1). */
+    availability?: OfferAvailability;
     isDefault: boolean;
     createdBy: string;
     createdAt?: number;
     updatedAt?: number;
 }
+/**
+ * What the supplier has, as last heard. `qty: null` = "can deliver, number unknown". `at` says
+ * how old it is: a stand older than the feed's rhythm counts as unknown in the choice.
+ */
+export interface OfferAvailability {
+    qty: number | null;
+    at: number;
+    source: "feed" | "api" | "manual";
+    leadDays?: 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 {
@@ -111,6 +129,9 @@ export interface LineProvisioning {
 export interface DeliverTo {
     kind: "own" | "customer" | "site";
     companyId?: string;
+    /** A crm `CompanyAddress` (plan 050); absent = the company's primary delivery address. */
+    addressId?: string;
+    /** Frozen when the order is sent: what the supplier was told, whatever crm says later. */
     address?: PostalAddress;
 }
 /** A purchase order: a `Transaction` of kind `purchase_order`; `companyId` is the supplier. */

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

@@ -11,4 +11,4 @@ export declare function isBookable(tx: Pick<Transaction, "kindKey" | "issuedAt">
  * Headings and options carry no amount, so they are not lines here. A reverse charge or
  * exemption ticked on the document replaces every line's code, as it did when it was priced.
  */
-export declare function bookingDocumentOf(tx: Transaction, company: Pick<Company, "id" | "name" | "vatNumber" | "kvkNumber" | "address"> | null, sourceApp?: string): BookingDocument;
+export declare function bookingDocumentOf(tx: Transaction, company: Pick<Company, "id" | "name" | "vatNumber" | "kvkNumber"> | null, sourceApp?: string): BookingDocument;

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

@@ -22,12 +22,12 @@ export declare function awaitsNumber(tx: Pick<Transaction, "issuedAt" | "kindKey
  * What a save may set on a draft. `status` is not here: it moves through `issue` and the status
  * route, which check the transition and announce it.
  */
-export declare const DRAFT_FIELDS: readonly ["companyId", "contactId", "dealItemId", "title", "reference", "currency", "taxOverrideKey", "introText", "termsText", "expiresAt", "deliveredAt", "periodFrom", "periodTo", "paymentTerm", "lines"];
+export declare const DRAFT_FIELDS: readonly ["companyId", "contactId", "dealItemId", "title", "reference", "currency", "taxOverrideKey", "introText", "termsText", "expiresAt", "deliveredAt", "periodFrom", "periodTo", "paymentTerm", "billingAddressId", "lines"];
 /**
  * The draft fields a save may empty, named in `clear`. A list and not `null` in the body:
  * `invoke` strips `null`, so "empty this" never reaches the server any other way.
  */
-export declare const CLEARABLE_FIELDS: readonly ["contactId", "dealItemId", "title", "reference", "taxOverrideKey", "introText", "termsText", "expiresAt", "deliveredAt", "periodFrom", "periodTo"];
+export declare const CLEARABLE_FIELDS: readonly ["contactId", "dealItemId", "title", "reference", "taxOverrideKey", "introText", "termsText", "expiresAt", "deliveredAt", "periodFrom", "periodTo", "billingAddressId"];
 export type ClearableField = (typeof CLEARABLE_FIELDS)[number];
 /** The fields a draft carries over; the server owns id, organisation and author. */
 export type TransactionDraft = Omit<Transaction, "id" | "organizationId" | "createdBy" | "createdAt" | "updatedAt">;

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

@@ -59,6 +59,8 @@ export interface SlotLabels {
     unitPrice: string;
     /** After a period price: "222,00 per jaar". */
     per: Record<PricePer, string>;
+    /** A meter's display unit after a rated quantity: `minute` → "min". Unknown = the key. */
+    units: Record<string, string>;
     net: string;
     tax: string;
     gross: string;

package/dist/entities/transaction/payment-term.d.ts

@@ -28,7 +28,9 @@ export interface PaymentTerm {
     method: PaymentTermMethod;
     /** Days after issue until it falls due. `0` is payable immediately. */
     dueDays: number;
-    /** The one a new document starts with when neither the request nor the customer says. */
+    /** Who pays under it (plan 050): our customer (`sales`), or we a supplier. Absent = both. */
+    direction?: PaymentTermDirection;
+    /** The one a new document starts with when neither the request nor the role says. */
     isDefault?: boolean;
     archived?: boolean;
     order?: number;
@@ -36,6 +38,18 @@ export interface PaymentTerm {
     createdAt?: number;
     updatedAt?: number;
 }
+export type PaymentTermDirection = "sales" | "purchase";
+/** Whether a term may be picked for a document in `direction`. */
+export declare const termApplies: (term: Pick<PaymentTerm, "direction">, direction: PaymentTermDirection) => boolean;
+/**
+ * The term a new document takes: the one asked for, else the role's, else the default in that
+ * direction (a direction's own default beats a shared one). Archived or wrong-way codes are
+ * skipped, never an error — the next rung answers. `null` = the organisation has no terms.
+ */
+export declare function pickPaymentTerm(terms: readonly PaymentTerm[], direction: PaymentTermDirection, wanted?: {
+    explicit?: string;
+    role?: string;
+}): PaymentTerm | null;
 /**
  * The due date of a document issued at `issuedAt` under a term of `dueDays`.
  *

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

@@ -5,6 +5,7 @@ import { DocumentSender } from '../document-template/types';
 import { Cents } from '../money/money';
 import { PricePer } from '../money/period-price';
 import { TaxRateKind } from '../money/tax';
+import { PostalAddress } from '../organization/types';
 import { OwnerScope } from '../scope/types';
 import { TransactionPaymentTerm } from './payment-term';
 /**
@@ -83,6 +84,11 @@ export interface Transaction {
      * ride along because the due date is computed at issue, and by then the row may be gone.
      */
     paymentTerm?: TransactionPaymentTerm;
+    /**
+     * The customer's crm address this document goes to (plan 050); absent = its primary billing
+     * address. Read while it is a draft, frozen as `issuedPaper.billingAddress` when it goes out.
+     */
+    billingAddressId?: string;
     /**
      * When it falls due. Computed at issue from the condition, and only for a numbered kind: a quote
      * does not fall due, it expires — that is `expiresAt`.
@@ -170,6 +176,8 @@ export interface IssuedPaper {
     sender: DocumentSender;
     templateId?: string;
     customerName?: string;
+    /** The billing address as it went out (plan 050); the books take this one, not crm's today. */
+    billingAddress?: PostalAddress;
 }
 export interface TransactionLine {
     /** Stable within the transaction, so a version diff can follow a line. */
@@ -181,7 +189,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 +207,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;