@opencxh/domain 1.301.0 → 1.303.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,6 +1,6 @@
 /**
  * `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
+ * account, numbers). Fulfilment submits a request per act and follows it; the provider says
  * what it needs and what it made.
  */
 export declare const PROVISIONING_SOURCE_GROUP = "provisioning-source";
@@ -8,17 +8,57 @@ export declare const PROVISIONING_ROUTES: {
     readonly describe: "/provisioning/describe";
     readonly submit: "/provisioning/submit";
     readonly status: "/provisioning/status";
+    readonly subscriptions: "/provisioning/subscriptions";
+    /** Optional, for offers that declare `qualify`: deliverable here, before the promise (047 step 8). */
+    readonly qualify: "/provisioning/qualify";
+    /** 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";
+    /** Optional, for offers that declare `quote`: what one order costs, per part (045 D N-2). */
+    readonly quote: "/provisioning/quote";
 };
-export type ProvisioningAction = "purchase" | "change" | "suspend" | "resume" | "cancel";
 /**
- * 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).
+ * 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 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. `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 +79,175 @@ 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;
+    /** Answers `POST /provisioning/qualify` with its `qualify` params (047 step 8). */
+    qualify?: boolean;
+    /** Priced per order: answers `POST /provisioning/quote` (045 D N-2). */
+    quote?: 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;
+    /**
+     * Internal only: a federated resource (`"nextpertise:SiteCheck"`) for a check a form cannot do.
+     * Runs with a colleague's rights, so an offer checkable only this way is never self-service.
+     */
+    resource?: string;
+}
+/**
+ * `qualify`: the offer, the supplier's product (`SupplierOffer.vendorSku`: one Nextpertise offer
+ * covers every carrier product) and its `qualify` answers (an address as a crm address id).
+ */
+export interface QualifyCommand {
+    offer: string;
+    vendorSku?: string;
+    params: Record<string, string>;
+}
+/**
+ * A provider's answer, per supplier option, with its cost: internal, never shown to a customer.
+ * An option's `key` is one of the provider's own offer keys, so fulfilment can name it as ours.
+ */
+export interface ProviderQualification {
+    available: boolean;
+    reason?: string;
+    options?: {
+        key: string;
+        label: string;
+        costCents?: number;
+        termMonths?: number;
+    }[];
+    expiresAt: number;
+}
+/**
+ * `quote`: what an act costs. A purchase (no `action`): the offer, the supplier's product
+ * (`SupplierOffer.vendorSku`), its commitment (`SupplierOffer.termMonths`) and the request's
+ * answers. A cancel: the running subscription, the account it runs under and the day it ends.
+ */
+export interface QuoteCommand {
+    offer: string;
+    action?: ProvisioningAction;
+    vendorSku?: string;
+    termMonths?: number;
+    params: Record<string, string>;
+    externalRef?: string;
+    parent?: {
+        externalRef?: string;
+        fulfillment?: Record<string, string>;
+    };
+    effectiveAt?: number;
+}
+/**
+ * What one order 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;
+        }[];
+    };
 }
-export interface ProvisioningRequest {
-    /** `lineKey` of the order line: the provider's idempotency key — the same request twice is one. */
+/** 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 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 +255,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;
@@ -85,4 +278,8 @@ 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[];
 }

package/package.json

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