@opencxh/domain 1.300.0 → 1.301.0

package/dist/entities/business-entity/types.d.ts

@@ -67,6 +67,12 @@ export interface BusinessEntity {
     vatCadence?: "quarter" | "month" | "year";
     /** Kleineondernemersregeling: no VAT charged or deducted, so no return. */
     vatKor?: boolean;
+    /**
+     * The first debtor and creditor number crm hands out here (plan 050); absent = 10001 and 40001.
+     * A change counts for new numbers only: one handed out keeps its number.
+     */
+    firstDebtorNumber?: number;
+    firstCreditorNumber?: number;
     /** The one a new document lands on. Exactly one row carries it. */
     isDefault?: boolean;
     /** Archived, never deleted: an issued quote names the entity it went out as. */

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

@@ -132,3 +132,21 @@ export declare function ratedLineAmount(group: RatedGroup, rate: Rate | undefine
     unitKey: string;
     unitPriceCents: Cents;
 };
+/**
+ * What a rated line counted, in the meter's display unit (372 min), for a line billed as
+ * 1 piece × its total — `null` for every other line, whose own quantity already says it.
+ * The allowance is off: the reader sees what was billed.
+ */
+export declare function ratedQuantity(line: {
+    unitKey: string;
+    usage?: {
+        rateId?: string;
+        measured: number;
+        included?: number;
+        per: number;
+        unit: string;
+    };
+}): {
+    amount: number;
+    unit: string;
+} | null;

package/dist/entities/company/address.d.ts

@@ -0,0 +1,30 @@
+import { PostalAddress } from '../organization/types';
+/** What an address is for. One address can be several: billing and visiting at one door. */
+export type CompanyAddressKind = "billing" | "delivery" | "site" | "visit";
+export declare const COMPANY_ADDRESS_KINDS: readonly CompanyAddressKind[];
+/** The kinds a document takes by default when nobody picks. */
+export type PrimaryAddressKind = "billing" | "delivery";
+/**
+ * One address of a company, with an id to point at (plan 050): a qualification, a delivery to a
+ * site, a portal order. Archived, never deleted — whatever points at it keeps pointing. A sent
+ * document freezes the address on its paper; it never reads the row again.
+ */
+export interface CompanyAddress {
+    id: string;
+    organizationId: string;
+    companyId: string;
+    kinds: CompanyAddressKind[];
+    /** "Vestiging Utrecht"; absent = the street says enough. */
+    label?: string;
+    address: PostalAddress;
+    primaryFor?: PrimaryAddressKind[];
+    archived?: boolean;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * The address a document takes for `kind`: the primary one, else the first live one of that
+ * kind. A delivery falls back to billing — most small companies have one address for both.
+ */
+export declare function primaryAddress(addresses: readonly CompanyAddress[], kind: PrimaryAddressKind): CompanyAddress | undefined;

package/dist/entities/company/address.test.d.ts

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

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

@@ -1,2 +1,4 @@
+export * from './address';
 export * from './identifiers';
+export * from './role';
 export * from './types';

package/dist/entities/company/role.d.ts

@@ -0,0 +1,33 @@
+/** Which side of the table a company sits on, for one administration. */
+export type CompanyRoleKind = "customer" | "supplier";
+export declare const COMPANY_ROLE_KINDS: readonly CompanyRoleKind[];
+/**
+ * A company in one role for one administration (plan 050): customer 10023 at BV A, supplier 40017
+ * in USD at BV B. One per `(companyId, businessEntityId, role)`; crm hands out the numbers, per
+ * administration and role, so an organisation without sales still gets creditor numbers.
+ */
+export interface CompanyRole {
+    id: string;
+    organizationId: string;
+    companyId: string;
+    businessEntityId: string;
+    role: CompanyRoleKind;
+    /** Debtor or creditor number; unique per administration and role. */
+    number?: string;
+    /** An organization `PaymentTerm.code`, in the direction of the role. */
+    paymentTermKey?: string;
+    /** Empty = the administration's currency. */
+    currency?: string;
+    /** Nothing new in this role: no quote to a blocked customer, no PO to a blocked supplier. */
+    blocked?: boolean;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/** "Make sure this company is our supplier at BV B": idempotent, the existing role if there is one. */
+export interface EnsureCompanyRoleRequest {
+    companyId: string;
+    businessEntityId: string;
+    role: CompanyRoleKind;
+}
+/** The payment-term direction a role pays in: a customer pays us, we pay a supplier. */
+export declare const roleDirection: (role: CompanyRoleKind) => "sales" | "purchase";

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

@@ -1,5 +1,4 @@
 import { LifecycleStage } from '../contact/lifecycle';
-import { PostalAddress } from '../organization/types';
 import { OwnerScope } from '../scope/types';
 /** Same meaning as {@link ContactOrigin}: `shadow` is a lazily cached hit, a landed row is `own`. */
 export type CompanyOrigin = "own" | "shadow";
@@ -48,19 +47,6 @@ export interface Company {
     lifecycleStage?: LifecycleStage;
     /** The group this company belongs to. One level up per row; a cycle is refused on write. */
     parentCompanyId?: string;
-    /**
-     * Where the company sits. Needed by anything that puts this company on paper — a quote's
-     * recipient block is the first, and the issue gate refuses a document with a hole in it.
-     */
-    address?: PostalAddress;
-    /**
-     * This customer's default payment condition, as a code `apps/sales` owns.
-     *
-     * An opaque key, exactly like {@link Company.locale} is an opaque language: crm stores it and
-     * never interprets it. It is a default and not a rule — a document copies the condition when it
-     * is created and keeps it from then on, so changing this never rewrites what already went out.
-     */
-    paymentTermCode?: string;
     /** Normalised: upper case, no spaces (`NL123456789B01`). */
     vatNumber?: string;
     kvkNumber?: string;
@@ -68,14 +54,6 @@ export interface Company {
     ibans?: string[];
     /** `<scheme>:<id>` (`0106:12345678`), for Peppol e-invoicing. */
     peppolId?: string;
-    debtorNumber?: string;
-    creditorNumber?: string;
-    /** We buy from them. Loose fields on the company, as in Exact — not a supplier entity. */
-    isSupplier?: boolean;
-    /** Their payment condition towards us; {@link Company.paymentTermCode} is ours towards them. */
-    supplierPaymentTermKey?: string;
-    /** The currency they invoice us in; empty = the administration's. */
-    supplierCurrency?: string;
     /** Raw, human-readable phone/website as entered, for display. */
     phone?: string;
     website?: string;

package/dist/entities/contact/segment.d.ts

@@ -6,7 +6,7 @@ import { SavedView, SavedViewSort } from '../saved-view/types';
  */
 export type SegmentKind = "contact" | "company";
 /** Multi-value filters: empty or absent = no filter on that axis. */
-export declare const SEGMENT_LIST_FILTERS: readonly ["stages", "leadStatuses", "sources", "scopes", "cities", "parentCompanyIds"];
+export declare const SEGMENT_LIST_FILTERS: readonly ["stages", "leadStatuses", "sources", "scopes", "cities", "parentCompanyIds", "roles"];
 export type SegmentListFilter = (typeof SEGMENT_LIST_FILTERS)[number];
 /** Yes/no filters that need another store to answer: open deals in work, people at a company. */
 export declare const SEGMENT_PRESENCE_FILTERS: readonly ["openDeal", "hasContacts"];

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/types.d.ts

@@ -55,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 {
@@ -115,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. */