@opencxh/domain 1.302.0 → 1.304.0

package/dist/platform/bookkeeping.d.ts

@@ -1,6 +1,7 @@
 import { LedgerMappingRule } from '../entities/bookkeeping/types';
 import { Cents } from '../entities/money/money';
 import { TaxRateKind } from '../entities/money/tax';
+import { LineDimensions } from '../entities/transaction/types';
 export declare const BOOKABLE_SOURCE_PROVIDER_GROUP = "bookable-source";
 export declare const BOOKKEEPING_PROVIDER_GROUP = "bookkeeping";
 /** Routes under `/provider`. Constants, so caller and provider cannot drift apart. */
@@ -39,6 +40,8 @@ export interface BookingDocument {
     number?: string;
     counterparty: {
         companyId?: string;
+        /** Its role number at this administration (debtor or creditor number), as it went out. */
+        number?: string;
         name: string;
         vatNumber?: string;
         kvkNumber?: string;
@@ -53,7 +56,7 @@ export interface BookingDocument {
     };
     /** `"2026-09-24"`. Dates are days, not instants. */
     issueDate: string;
-    /** Delivery date or end of the service period: decides the VAT period. */
+    /** When the VAT is due, if not on `issueDate`. A sales invoice leaves it out (D2). */
     taxPointDate?: string;
     dueDate?: string;
     currency: string;
@@ -95,11 +98,8 @@ export interface BookingLine {
      */
     accountKey?: string;
     productId?: string;
-    /**
-     * Open map: `projectId`, `costCenterId`, `customerCompanyId` (whose cost or revenue this is),
-     * and whatever a later country needs. All of it reaches the journal line.
-     */
-    dimensions?: Record<string, string>;
+    /** KETEN-STAND B1: each reaches the journal line as its own column. */
+    dimensions?: LineDimensions;
     /** The cost of what this line sold (quantity × cost price): carried for margin, not booked yet. */
     costCents?: Cents;
     /**
@@ -126,8 +126,8 @@ export interface IssuedDocumentRef {
 export interface BookingAnnouncement {
     sourceApp: string;
     documentId: string;
-    /** Empty = the default administration; finance resolves it, a row never carries "". */
-    businessEntityId?: string;
+    /** Always the document's own administration (review 5a-4); `""` is refused, not "the default". */
+    businessEntityId: string;
     documentKind: BookingDocument["kind"];
     documentNumber?: string;
     issuedAt: number;

package/dist/platform/provisioning.d.ts

@@ -1,24 +1,62 @@
-/**
- * `provisioning-source`: an app that can order at a supplier through its API (Eylo: a customer
- * account, numbers). Purchase submits a request per order line and follows it; the provider says
- * what it needs and what it made.
- */
+import { Commitment, LineRhythm } from '../entities/agreement/types';
 export declare const PROVISIONING_SOURCE_GROUP = "provisioning-source";
 export declare const PROVISIONING_ROUTES: {
     readonly describe: "/provisioning/describe";
     readonly submit: "/provisioning/submit";
     readonly status: "/provisioning/status";
+    readonly subscriptions: "/provisioning/subscriptions";
+    /** Optional, for account offers that declare `accounts`: every customer account it knows (047 step 9). */
+    readonly accounts: "/provisioning/accounts";
+    /** Optional, for providers that declare `catalog`: the assortment as price-list rows (045 D N-1). */
+    readonly catalog: "/provisioning/catalog";
+    /**
+     * A dry run of `submit` (plan 053): the next questions, what is still unmet and the cost — of a
+     * purchase, a change or an end. Every provider answers it; without a handler of its own, its
+     * declared `params` do.
+     */
+    readonly prepare: "/provisioning/prepare";
+};
+/**
+ * One vocabulary for the act, on the wire and on a `ProvisioningRequest` (plan 047 v2): `convert`
+ * swaps the product (Microsoft Transition, Pax8 ChangeProduct), `renew` starts a next term.
+ */
+export type ProvisioningAction = "purchase" | "change" | "convert" | "suspend" | "resume" | "cancel" | "renew";
+/** What one provider hands another, normalised (047 v2 §7): a few concrete kinds, no mapping language. */
+export type ProvidedResource = {
+    kind: "phone_number";
+    value: string;
+} | {
+    kind: "device";
+    value: string;
+} | {
+    kind: "tenant";
+    value: string;
+} | {
+    kind: "account";
+    value: string;
 };
-export type ProvisioningAction = "purchase" | "change" | "suspend" | "resume" | "cancel";
+export type ResourceKind = ProvidedResource["kind"];
+/** A role an offer needs another item in, and for which acts that item must be active. */
+export interface RoleNeed {
+    role: string;
+    kind: ResourceKind;
+    min: number;
+    max: number;
+    for: ProvisioningAction[];
+}
+/** How an unknown outcome is recovered, per act (047 v2 §2.3). */
+export type ProvisioningRecovery = "idempotent" | "lookup_by_ref" | "lookup_by_listing";
 /**
- * A field the supplier needs. `ordering` is filled on the order line before it goes (the tenant's
- * domain, the number's region); `fulfillment` is what the supplier hands back (the account id).
+ * A field the supplier needs. `qualify` is asked on the quote line already (the site, for a
+ * delivery check); `ordering` is filled before it goes (the tenant's domain, the number's region);
+ * `fulfillment` is what the supplier hands back (the account id). An `address` is a crm
+ * `CompanyAddress.id`, never a copy: the provider reads the address itself.
  */
 export interface ProvisioningParam {
     key: string;
     label: string;
-    phase: "ordering" | "fulfillment";
-    type?: "text" | "email" | "select";
+    phase: "qualify" | "ordering" | "fulfillment";
+    type?: "text" | "email" | "select" | "address";
     required?: boolean;
     options?: {
         value: string;
@@ -39,17 +77,126 @@ export interface ProvisionableOffer {
     actions: ProvisioningAction[];
     /** The account it makes is a usage source: approved links it to the customer's agreement. */
     usageAccount?: boolean;
+    /** What a successful purchase hands back to others (047 v2 §7). */
+    provides?: {
+        kind: ResourceKind;
+    }[];
+    /** What it needs from other items, per role (047 v2 §10.1). */
+    needs?: RoleNeed[];
+    /** Per act, how an unknown outcome is recovered. Absent = ask a person. */
+    recovery?: Partial<Record<ProvisioningAction, ProvisioningRecovery>>;
+    /** The provider lists what runs under an account (`subscriptions`): polled into `reported`. */
+    listing?: boolean;
+    /**
+     * An account offer whose accounts the provider lists (`POST /provisioning/accounts`): where
+     * fulfilment looks for what already runs when an existing business moves over (047 step 9).
+     */
+    accounts?: boolean;
+    /** The questions it starts with (plan 053); `prepare` answers the rest. */
+    requirements?: RequirementSpec[];
+}
+/**
+ * What one act costs at the supplier, per part: each part is a line on the purchase order, once
+ * or per month. Cost, internal — never shown to a customer.
+ */
+export interface ProviderQuote {
+    parts: {
+        label: string;
+        cents: number;
+        recurring?: "month";
+    }[];
+    warnings?: string[];
+}
+/** One subscription as the supplier lists it under an account (Pax8, Microsoft, 047 v2 §2.1). */
+export interface ReportedSubscription {
+    externalRef: string;
+    offer: string;
+    quantity: number;
+    status: "active" | "suspended" | "ended";
+    /** Our `requestId`, where the supplier keeps a reference (Ion `referenceId`). */
+    requestRef?: string;
+    termEndsAt?: number;
+    autoRenew?: boolean;
+    /** Microsoft NCE: every add-on has its own window; a decrease only within these. */
+    refundable?: {
+        quantity: number;
+        until: number;
+    }[];
+    scheduled?: {
+        quantity?: number;
+        productId?: string;
+        at: number;
+    };
+    /** The account it runs under at this provider (its `externalRef`), when listed flat. */
+    under?: string;
+    /** What it uses of other items (a number routed from elsewhere): bound to `requires` on adopt. */
+    uses?: ProvidedResource[];
+}
+/** One customer account a provider knows (`accounts`): matched to a crm company on adopt. */
+export interface ProviderAccount {
+    externalRef: string;
+    /** The account offer it is an instance of. */
+    offer: string;
+    name: string;
+    kvkNumber?: string;
+    domain?: string;
+    fulfillment?: Record<string, string>;
+    since?: number;
+}
+/** `subscriptions`: what runs under one account, optionally of one offer. */
+export interface SubscriptionsQuery {
+    account: {
+        externalRef?: string;
+        fulfillment?: Record<string, string>;
+    };
+    offer?: string;
 }
 export interface ProvisioningDescription {
     offers: ProvisionableOffer[];
+    /**
+     * The provider lists its assortment (`POST /provisioning/catalog { account }`), per connection:
+     * a price list with source `api` reads it instead of a file (045 D N-1).
+     */
+    catalog?: {
+        accounts: {
+            id: string;
+            name: string;
+        }[];
+    };
+}
+/** One product of a provider's assortment, as a price-list line reads it. */
+export interface ProviderCatalogRow {
+    vendorSku: string;
+    description: string;
+    brand?: string;
+    group?: string;
+    /** The provider's offer it is ordered through (`ProvisionableOffer.key`). */
+    offer: string;
+    /** Absent: priced per order (`pricedBy: "quote"`). */
+    costCents?: number;
+    currency?: string;
 }
-export interface ProvisioningRequest {
-    /** `lineKey` of the order line: the provider's idempotency key — the same request twice is one. */
+export interface ProvisioningCommand {
+    /** The provider's idempotency key: the same request twice is one. */
     requestId: string;
     offer: string;
     action: ProvisioningAction;
     quantity: number;
+    /** `convert`: the product it becomes. */
+    toProductId?: string;
+    /**
+     * What it is bought as at the supplier, from the PO line's offer: their product
+     * (`SupplierOffer.vendorSku`, a Nextpertise carrier product) and its term in months.
+     */
+    vendorSku?: string;
+    termMonths?: number;
     params: Record<string, string>;
+    /** What it uses from other items, bound by role (047 v2 §10.1): the number it routes. */
+    inputs?: {
+        role: string;
+        itemId: string;
+        resource: ProvidedResource;
+    }[];
     /** The subscription this changes or ends. */
     externalRef?: string;
     /** What the account level handed back (its id), for an item inside it. */
@@ -57,11 +204,6 @@ export interface ProvisioningRequest {
         externalRef?: string;
         fulfillment?: Record<string, string>;
     };
-    /** Bought elsewhere and landing here: what the purchase handed back (the numbers). */
-    predecessor?: {
-        externalRef?: string;
-        fulfillment?: Record<string, string>;
-    };
     customer?: {
         companyId: string;
         name?: string;
@@ -70,6 +212,13 @@ export interface ProvisioningRequest {
     effectiveAt?: number;
 }
 export type ProvisioningState = "pending" | "approved" | "failed" | "inquiring";
+/** What the supplier ships itself for a service (the SIM, the router), followed by its tracking. */
+export interface ProviderShipment {
+    carrier?: string;
+    trackingNumber?: string;
+    serials?: string[];
+    at?: number;
+}
 export interface ProvisioningResult {
     state: ProvisioningState;
     externalRef?: string;
@@ -85,4 +234,130 @@ export interface ProvisioningResult {
         app: string;
         accountRef: string;
     };
+    /** Partly done: how many of the target succeeded (Microsoft reports per part). */
+    quantity?: number;
+    /** What it now provides to others, normalised (047 v2 §7). */
+    resources?: ProvidedResource[];
+    /** Shipped by the supplier, for this request (plan 053 G3). */
+    deliveries?: ProviderShipment[];
+}
+/** What is bought, at whom: the provider's offer and, where one offer covers many, their product. */
+export interface OfferRef {
+    app: string;
+    offer: string;
+    sku?: string;
+}
+/** `app:offer`, plus `:sku` when there is one: the one way to key an offer. */
+export declare function offerKey(ref: OfferRef): string;
+/** The same offer; a ref without a sku matches every product of that offer. */
+export declare function sameOffer(a: OfferRef, b: OfferRef): boolean;
+/** Every answer by requirement key; a quantity or a yes/no is a string too. */
+export type ProvisioningAnswers = Record<string, string>;
+/** By when it must be met: before the quote is accepted, or before the order goes out. */
+export type RequirementGate = "quote" | "order";
+export type AnswerType = "text" | "email" | "address" | "select" | "boolean" | "quantity";
+/** One choice, live from the supplier. A `sku` makes it a product; its cost is internal. */
+export interface RequirementOption {
+    key: string;
+    label: string;
+    sku?: string;
+    costCents?: number;
+    recurring?: "month";
+    /**
+     * What this choice binds us to at the supplier (NCE monthly vs yearly, plan 053 G1): the same
+     * `Commitment` as an agreement, as far as the supplier says it (Nextpertise names only the term).
+     * How often they invoice is no commitment: `billedEvery`.
+     */
+    commitment?: Partial<Commitment>;
+    billedEvery?: LineRhythm;
+}
+interface RequirementBase {
+    key: string;
+    label: string;
+    before: RequirementGate;
+}
+/**
+ * Something we fill in. `line` says it is sold: `main` picks the supplier's product of the line
+ * (the network, the bundle), `addon` becomes a sub-line of its own (an EVC, premium SLA).
+ * `perUnit`: every unit of an exclusive item has its own (the number to port, per SIM).
+ */
+export interface AnswerSpec extends RequirementBase {
+    kind: "answer";
+    type: AnswerType;
+    required?: boolean;
+    options?: RequirementOption[];
+    line?: "main" | "addon";
+    /** A `boolean` or `quantity` add-on's own product and cost, per unit. */
+    sku?: string;
+    costCents?: number;
+    recurring?: "month";
+    min?: number;
+    max?: number;
+    perUnit?: boolean;
+    /**
+     * An offer may fix it (`SupplierOffer.provider.answers`): the article as a filter — "Glasvezel
+     * 1 Gbit" fixes technology and speed. Never asked in the flow; declared in `describe`.
+     */
+    preset?: boolean;
+}
+/** Something the provider judges; `who` resolves it when it is not met. */
+export interface ConditionSpec extends RequirementBase {
+    kind: "condition";
+    who: "colleague" | "customer" | "provider";
 }
+/** Declared in `describe`: the questions an offer starts with, so a search knows who to ask. */
+export type RequirementSpec = AnswerSpec | ConditionSpec;
+/** What to do to meet a condition: send the link, set the record. */
+export interface RequirementInstructions {
+    text: string;
+    link?: string;
+    record?: {
+        type: string;
+        name: string;
+        value: string;
+    };
+}
+export interface RequirementState {
+    met: boolean;
+    reason?: string;
+    /** An answer the provider proposes (from crm, or its only option). */
+    value?: string;
+    instructions?: RequirementInstructions;
+}
+export type Requirement = RequirementSpec & RequirementState;
+/**
+ * `prepare`: the same act as `submit`, not sent. `answers` are everything filled in so far, the
+ * offer's own fixed ones included (`SupplierOffer.provider.answers`: the article as a filter).
+ */
+export interface PrepareCommand {
+    ref: OfferRef;
+    action?: ProvisioningAction;
+    quantity: number;
+    answers: ProvisioningAnswers;
+    commitment?: Partial<Commitment>;
+    billedEvery?: LineRhythm;
+    externalRef?: string;
+    parent?: {
+        externalRef?: string;
+        fulfillment?: Record<string, string>;
+    };
+    customer?: {
+        companyId: string;
+        name?: string;
+    };
+    effectiveAt?: number;
+}
+/** The provider's answer: the next state of the questions, and what it costs. Internal. */
+export interface Preparation {
+    requirements: Requirement[];
+    cost?: ProviderQuote;
+    /** Until when it holds: a deliverability check does not last. */
+    expiresAt?: number;
+}
+/**
+ * The questions of an offer that computes nothing: its declared `params`, met when answered
+ * (`qualify` before the quote, `ordering` before the order; what the supplier hands back is no
+ * question). What `prepare` answers for a provider that does not implement it.
+ */
+export declare function preparationFromParams(params: ProvisioningParam[], answers: ProvisioningAnswers): Preparation;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.302.0",
+  "version": "1.304.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",