@opencxh/domain 1.303.0 → 1.304.0

package/dist/platform/provisioning.d.ts

@@ -1,22 +1,20 @@
-/**
- * `provisioning-source`: an app that can order at a supplier through its API (Eylo: a customer
- * account, numbers). Fulfilment submits a request per act 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 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";
+    /**
+     * 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`
@@ -89,65 +87,16 @@ export interface ProvisionableOffer {
     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;
+    /** The questions it starts with (plan 053); `prepare` answers the rest. */
+    requirements?: RequirementSpec[];
 }
 /**
- * `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
+ * 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 {
@@ -263,6 +212,13 @@ export interface ProvisioningCommand {
     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;
@@ -282,4 +238,126 @@ export interface ProvisioningResult {
     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.303.0",
+  "version": "1.304.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",