@opencxh/domain 1.293.0 → 1.295.0

package/dist/platform/bookkeeping.d.ts

@@ -27,8 +27,14 @@ export declare const BOOKKEEPING_ROUTES: {
 export interface BookingDocument {
     sourceApp: string;
     documentId: string;
-    direction: "sale" | "purchase";
-    kind: "invoice" | "credit_note" | "receipt";
+    /** `none` for a journal: a memorial entry has no buyer or seller side. */
+    direction: "sale" | "purchase" | "none";
+    /**
+     * `journal`: a memorial entry from another app (a payroll journal from HRM or Nmbrs): signed
+     * lines on categories, no VAT, `counterparty.name` names it ("Loonjournaal september 2026").
+     * Only books that declare the `journal` capability take one; the rest refuse it visibly.
+     */
+    kind: "invoice" | "credit_note" | "receipt" | "journal";
     businessEntityId: string;
     /** Empty for a receipt without a number, and for an invoice the books will number themselves. */
     number?: string;
@@ -66,9 +72,16 @@ export interface BookingDocument {
         fileId: string;
     };
     externalIds?: string[];
+    /**
+     * The source's own page for this document, as a shell path (`/apps/sales/<administration>/
+     * invoices/<id>`): the books link back to it ("Naar de factuur") without knowing the source.
+     */
+    path?: string;
 }
 export interface BookingLine {
     description: string;
+    /** A journal's line: signed, debit positive. `netCents` and `taxCents` are 0 there. */
+    amountCents?: Cents;
     netCents: Cents;
     taxCents: Cents;
     /** `TaxCode.key`. The books map it onto their own box and account. */
@@ -83,8 +96,21 @@ export interface BookingLine {
      */
     accountKey?: string;
     productId?: string;
-    /** Open map: cost centre, project, and whatever a later country needs. */
+    /**
+     * 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>;
+    /** The cost of what this line sold (quantity × cost price): carried for margin, not booked yet. */
+    costCents?: Cents;
+    /**
+     * The service period it is for, `YYYY-MM-DD`, `to` inclusive. Own books spread a line over more
+     * than one calendar month through the balance (prepaid costs, revenue invoiced ahead).
+     */
+    period?: {
+        from: string;
+        to: string;
+    };
 }
 /** One row of the sweeper's safety net: an issued document the books may not have heard of. */
 export interface IssuedDocumentRef {

package/dist/platform/manifest.d.ts

@@ -1,13 +1,12 @@
 import { IconDefinition } from './common';
 import { Translations } from './localization';
-import { MenuItem } from './menu';
+import { NavContribution, ScopeDefinition } from './navigation';
 import { RouteDefinition } from './routing';
 export interface ActionDefinition {
     displayName: string;
     description: string;
 }
 export interface Modules {
-    sidebar?: ModuleDefinition;
     tools?: ModuleDefinition[];
     assets?: ModuleDefinition[];
     services?: ModuleDefinition[];
@@ -37,23 +36,6 @@ export type ResourceDefinition<T = any> = T;
  * It defines the app's identity, its components, its UI contributions,
  * and most importantly, its security sandbox via the permissions block.
  */
-/** The two groups of the app switcher: the product itself, and what extends it. */
-export type AppSwitcherGroup = "core" | "apps";
-/**
- * Where an app sits in the shell's app switcher. Declaring this — not having an
- * `icon` — is what puts an app in the switcher; settings-only and provider apps
- * leave it out and stay reachable through settings, panels and docks.
- */
-export interface AppSwitcherPlacement {
-    /** `core` is reserved for first-party product apps; everything else is `apps`. */
-    group: AppSwitcherGroup;
-    /** Position within `core` — a fixed reading order, not alphabetical. Ignored for `apps`. */
-    order?: number;
-    /** Also offer the app in the mobile tab bar. Core apps are there by default. */
-    mobile?: boolean;
-    /** Permissions the reader needs before the app is listed at all (`"<app>.<resource>.<action>"`). */
-    permissions?: string[];
-}
 export interface AppManifest<_TSDK = any> {
     /**
      * The namespace of the application.
@@ -79,13 +61,8 @@ export interface AppManifest<_TSDK = any> {
      * A brief description of what the application does.
      */
     description?: string;
-    /**
-     * Optional icon for the application. Shown wherever the app is listed; on its own
-     * it does not place the app in the switcher — see `switcher`.
-     */
+    /** Optional icon for the application, shown wherever the app is listed. */
     icon?: IconDefinition;
-    /** Placement in the app switcher and the mobile tab bar. Absent = not listed. */
-    switcher?: AppSwitcherPlacement;
     /**
      * Optional default route for the application.
      */
@@ -166,8 +143,10 @@ export interface AppManifest<_TSDK = any> {
      * status page is a URL customers see and link to.
      */
     publicBasePath?: string;
-    /** An array of menu items provided by this application. */
-    menu?: MenuItem[];
+    /** Where this app's entries hang in the workspaces (plan 048). */
+    nav?: NavContribution[];
+    /** Choices this app owns that decide what pages show, kept on the URL by the shell. */
+    scopes?: ScopeDefinition[];
     /** An array of translations provided by this application. */
     translations?: Translations;
     /**

package/dist/platform/navigation.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Navigation by workspace (plan 048). An app owns data and routes; a workspace is a switcher row
+ * for a role that shows entries from any app. URL: `/<workspace>/<app>/<path>`.
+ */
+/** The default workspaces. An organization can add its own; those carry a free `string` key. */
+export type WorkspaceKey = "home" | "inbox" | "work" | "files" | "customers" | "sales" | "purchase" | "finance" | "knowledge" | "reports";
+/**
+ * Workspaces the shell owns rather than `domain` or an organization: `apps` is every app's own
+ * workspace (`/apps/<app>/…`), `settings` has the settings categories as its sections.
+ */
+export type ReservedWorkspace = "apps" | "settings";
+/** First path segments that are never a workspace key. Every `publicBasePath` joins these. */
+export declare const RESERVED_SEGMENTS: readonly string[];
+/** The administration's scope parameter; organization declares it, `everywhere`. */
+export declare const BUSINESS_ENTITY_PARAM = "businessEntityId";
+export interface ScopeOption {
+    id: string;
+    /** Display text: options are data (an account name). */
+    label: string;
+}
+/**
+ * A choice that decides what an app's pages show — the administration, a PBX account, a knowledge
+ * base — kept as a query parameter by the shell (plan 048). The shell reads it from the URL, else
+ * the last choice, else the first option; writes it onto a page that lacks it; keeps it on every
+ * navigation; and hands it to apps as `sdk.router.scope$(param)`. With one option there is no
+ * parameter, but the option is still the value.
+ */
+export interface ScopeDefinition {
+    /**
+     * The query parameter, unique across apps, and the prop a page receives it as (`accountId`,
+     * `kbId`): the shell hands every page the scopes that hold on it, beside its route params.
+     */
+    param: string;
+    /** i18n key, owner's namespace: what the picker is called. */
+    label: string;
+    /** In the owner's preferred order: the first is the default. */
+    options: () => Subscribable<ScopeOption[]>;
+    /**
+     * On every URL, and picked in the profile menu (the administration). Otherwise only on the
+     * owner's own pages, picked in their header.
+     */
+    everywhere?: boolean;
+    /**
+     * The owner's resource to show instead of its pages while there is no option at all ("make your
+     * first knowledge base"). Without it the page renders with the prop undefined.
+     */
+    empty?: string;
+}
+export interface WorkspaceDefinition {
+    key: string;
+    /**
+     * The app the workspace needs: without it the workspace does not exist, and links to it open
+     * here by default (its canonical workspace).
+     */
+    owner: string;
+    icon: string;
+    order: number;
+    /**
+     * Section keys, top to bottom. Stable ids (organization config points at them), not i18n
+     * keys: the shell shows `section_<key>`, like `workspace_<key>` for the workspace itself.
+     */
+    sections: string[];
+}
+/** Structural, so domain stays free of rxjs; an Observable fits. */
+export interface Subscribable<T> {
+    subscribe(next: (value: T) => void): {
+        unsubscribe(): void;
+    };
+}
+export interface NavChild {
+    id: string;
+    /** Display text, not an i18n key: children are data (a project name). */
+    label: string;
+    /** App-relative. */
+    path: string;
+    /** Nested levels, e.g. kb sub-collections. */
+    children?: NavChild[];
+}
+export interface NavEntry {
+    /** Unique within the app; an organization refers to it as `{ app, entry: id }`. */
+    id: string;
+    /** i18n key, app namespace. */
+    label: string;
+    /** A Lucide name. Leave it out for rows that hang off their section's rail without a mark. */
+    icon?: string;
+    /** App-relative, like `RouteDefinition.path`. */
+    path: string;
+    /**
+     * Live children: kb collections, work projects, storage mounts. A function because the app's
+     * stores exist only after `initialize`; the shell calls it when the column shows.
+     */
+    children?: () => Subscribable<NavChild[]>;
+    permissions?: string[];
+}
+/**
+ * An app hangs entries in one section of a workspace; it lands only where the workspace exists
+ * (its owner is there). An app that lands nowhere gets its own, as with `"apps"`.
+ */
+export interface NavContribution {
+    workspace: WorkspaceKey | "apps";
+    /**
+     * In a shared workspace a key from its `sections`: an app never invents a heading there. In
+     * `"apps"` the app is alone, so its keys are free and labelled `<app>:section_<key>`, in
+     * manifest order. Absent = the first section.
+     */
+    section?: string;
+    entries: NavEntry[];
+}
+export interface NavEntryRef {
+    app: string;
+    entry: string;
+}
+/**
+ * What an organization changes on top of the defaults, one document per workspace in
+ * apps/organization. A difference, not a copy: whatever it leaves out comes from the default.
+ */
+export interface OrgWorkspaceConfig {
+    /** A default key (override) or a new one (the organization's own workspace). */
+    key: string;
+    /** Own workspaces carry text, not an i18n key. */
+    label?: string;
+    icon?: string;
+    order?: number;
+    /** Omitted = visible. */
+    visibleByDefault?: boolean;
+    /** Omitted = everyone. */
+    audience?: {
+        teamIds: string[];
+    };
+    /**
+     * Omitted = the default layout; a section without `entries` keeps its default entries. On a
+     * default workspace every entry not placed here and not `excluded` still lands at the bottom of
+     * its own section, so an app installed later shows up. An own workspace is exactly this list.
+     */
+    sections?: {
+        key: string;
+        label?: string;
+        entries?: NavEntryRef[];
+    }[];
+    /** Default entries the organization took out of a default workspace. */
+    excluded?: NavEntryRef[];
+}
+/** What one user changes: which workspaces they see. Never the contents. */
+export interface UserWorkspacePrefs {
+    /** Turned on although hidden by default. */
+    shown: string[];
+    /** Turned off although visible by default. */
+    hidden: string[];
+}
+/** Where to go, never a URL: a page of an app, or a record (`"product:p-1042"`). */
+export type Destination = {
+    app: string;
+    path: string;
+} | {
+    ref: string;
+};
+/** The part of the nav model the resolution rule reads. Built by the shell. */
+export interface WorkspaceIndex {
+    /** Visible workspaces for this user, in switcher order. */
+    visible: readonly string[];
+    /**
+     * Per app, the visible workspaces it contributes to, the one it owns first; `"apps"` when it
+     * contributes to its own. First = canonical.
+     */
+    byApp: Readonly<Record<string, readonly string[]>>;
+}
+export interface ResolveInput {
+    app: string;
+    /**
+     * Workspace segment of the URL, if any. Valid when it is visible and either the app contributes
+     * to it or the page is a `kind` page (a record opened from there keeps its column on refresh).
+     */
+    requested?: string;
+    /** Workspace on screen now. */
+    current?: string;
+    /** The route declares `kind`: a page of one thing opens where you are. */
+    isRecord: boolean;
+    index: WorkspaceIndex;
+}
+/**
+ * Which workspace shows this page: the one in the URL, else the one on screen, else the app's
+ * canonical one, else its own (`"apps"`). A `kind` page may stay in any visible shared workspace;
+ * never in `"apps"`, which is one app's own. A result other than `requested` means: correct the URL.
+ */
+export declare function resolveWorkspace({ app, requested, current, isRecord, index, }: ResolveInput): string;
+/** The default layout, in switcher order. Icons are the owner app's own mark. */
+export declare const DEFAULT_WORKSPACES: readonly WorkspaceDefinition[];
+/** A shell URL taken apart: `/<workspace>/<app>/<path>`. */
+export interface WorkspacePath {
+    workspace: string;
+    /** Absent on a bare workspace URL (`/sales`): the shell opens its first entry. */
+    app?: string;
+    /** App-relative, with query and hash; `"/"` when there is nothing after the app. */
+    path: string;
+}
+/**
+ * Reads a shell URL, or null when the first segment is no workspace (a public page, `/wake`).
+ * `isWorkspace` comes from the nav model: organization keys are data, so domain cannot list them.
+ */
+export declare function parseWorkspacePath(url: string, isWorkspace: (key: string) => boolean): WorkspacePath | null;
+/** The other way round. `path` is app-relative; a missing leading slash is added. */
+export declare function workspacePath({ workspace, app, path }: WorkspacePath): string;

package/dist/platform/navigation.test.d.ts

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

package/dist/platform/provider.d.ts

@@ -169,4 +169,11 @@ export interface DownloadAttachmentPayload {
     id?: string;
     /** Conversation id (Teams chatId) — needed to proxy chat hostedContent. */
     conversationId?: string;
+    /**
+     * RFC-822 Message-ID plus the attachment's name/size: lets a provider whose
+     * `id`/`attachmentId` change on a folder move (Outlook) find the file again.
+     */
+    rfcMessageId?: string;
+    filename?: string;
+    size?: number;
 }

package/dist/platform/provisioning.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `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.
+ */
+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";
+};
+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).
+ */
+export interface ProvisioningParam {
+    key: string;
+    label: string;
+    phase: "ordering" | "fulfillment";
+    type?: "text" | "email" | "select";
+    required?: boolean;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+export interface ProvisionableOffer {
+    /** The provider's own key, matched by `SupplierOffer.provider.offer`. */
+    key: string;
+    label: string;
+    /**
+     * `account`: the customer's place at the supplier (a tenant, an Eylo account), made once and
+     * first. `item`: something inside it (licences, numbers), which `requires` an account.
+     */
+    level: "account" | "item";
+    requires?: string;
+    params: ProvisioningParam[];
+    actions: ProvisioningAction[];
+    /** The account it makes is a usage source: approved links it to the customer's agreement. */
+    usageAccount?: boolean;
+}
+export interface ProvisioningDescription {
+    offers: ProvisionableOffer[];
+}
+export interface ProvisioningRequest {
+    /** `lineKey` of the order line: the provider's idempotency key — the same request twice is one. */
+    requestId: string;
+    offer: string;
+    action: ProvisioningAction;
+    quantity: number;
+    params: Record<string, string>;
+    /** The subscription this changes or ends. */
+    externalRef?: string;
+    /** What the account level handed back (its id), for an item inside it. */
+    parent?: {
+        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;
+    };
+    /** When a change or cancellation takes effect (epoch ms); absent = now. */
+    effectiveAt?: number;
+}
+export type ProvisioningState = "pending" | "approved" | "failed" | "inquiring";
+export interface ProvisioningResult {
+    state: ProvisioningState;
+    externalRef?: string;
+    fulfillment?: Record<string, string>;
+    /** `inquiring`: which ordering fields are missing or wrong. */
+    missing?: {
+        key: string;
+        reason: string;
+    }[];
+    error?: string;
+    /** The account is a usage source: the agreement reads usage from it from now on. */
+    usageAccount?: {
+        app: string;
+        accountRef: string;
+    };
+}

package/dist/platform/resource.d.ts

@@ -17,6 +17,25 @@ export interface ResourceRef {
 }
 /** The key shape `authorizeScope` and the file keys use. */
 export declare function refKey(ref: ResourceRef): string;
+/** One line inside a resource: invoice line, receipt line, agreement line. */
+export interface LineRef extends ResourceRef {
+    lineId: string;
+}
+/**
+ * `"invoice:412#l3"` — a line, anywhere. Kind names are unique across apps, so the key alone says
+ * whose line it is. Never an array index: a line removed above it would shift every key below.
+ */
+export declare function lineKey(ref: LineRef): string;
+export declare function parseLineKey(key: string): LineRef | null;
+/**
+ * Gives every line without an id its own (`l<n>`, above the highest in use), keeping the ids that
+ * are there: a line keeps its id for life, so what points at it keeps pointing.
+ */
+export declare function withLineIds<T extends {
+    id?: string;
+}>(lines: readonly T[]): (T & {
+    id: string;
+})[];
 /**
  * The kind comms owns, and the only one the engine knows something extra about: on an interaction
  * you can wait for a reply and put a line in the timeline. Other kinds cannot, and that is not an

package/dist/platform/resource.test.d.ts

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

package/dist/platform/routing.d.ts

@@ -37,6 +37,16 @@ export interface RouteDefinition {
      * which hands the page to somebody else's brand entirely.
      */
     chrome?: "none";
+    /**
+     * The scope kind this route shows one of (`"order"` on `/order/:id`). Such a page opens in the
+     * workspace on screen; a list page only in workspaces the app contributes to.
+     */
+    kind?: string;
+    /**
+     * The page works without its app's own scopes (plan 048): the shell neither waits for them nor
+     * shows the scope's `empty` page — the one that creates the first knowledge base, say.
+     */
+    unscoped?: boolean;
 }
 export interface NamespacedRouteDefinition extends RouteDefinition {
     appName: string;
@@ -56,18 +66,6 @@ export declare const AUTH_APP_NAME = "auth";
  * thrown TypeError takes the subscription down without a word.
  */
 export declare function appNameFromPath(path: string | null | undefined): string | null;
-/**
- * Does this landing path say where the user wanted to go?
- *
- * Asked at startup by everything that would otherwise send the user somewhere
- * of its own choosing. It has to be one shared answer: the shell and the module
- * loader both used to decide this, and the loader's "go to the default app"
- * simply ran last and overwrote whatever URL you had opened.
- *
- * `/wake` counts — the service worker lands there with a provider in the query
- * and `WakeRoute` routes onward itself.
- */
-export declare function isDeepLink(path: string | null | undefined): boolean;
 /**
  * The shell's settings route. Not an app: it frames the pages every app registers,
  * so it lives beside `/apps/…` rather than under it.
@@ -82,12 +80,9 @@ export declare function settingsPath(pageId?: string | null): string;
  * True for the bare root and for the login screen — you are sent there, you do
  * not go there. Everything else is a request, whether or not it names an app.
  *
- * This is **not** the complement of {@link isDeepLink}. That one answers "does
- * this path name an app other than auth", so a public help page — which names
- * no app at all — comes back false. Callers that read that false as "the user
- * wanted nothing" sent readers of `/help/…` to the organisation's default app.
- * Between the two lies the set of paths that might be public, and the only way
- * to know is to wait for the app manifests.
+ * Its old counterpart `isDeepLink` ("names an app other than auth") read a
+ * public help page and every workspace URL as "wanted nothing"; the shell now
+ * treats everything that is not a landing path as a destination.
  */
 export declare function isLandingPath(path: string | null | undefined): boolean;
 /** Turn a route pattern with `:param` segments into an exact-match regex. */

package/package.json

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

package/dist/platform/menu.d.ts

@@ -1,26 +0,0 @@
-import { IconDefinition } from './common';
-export interface MenuItem {
-    /** The label of the menu item. */
-    label: string;
-    /** The description of the menu item. */
-    description?: string;
-    /** The path of the menu item. */
-    path: string;
-    /** The icon of the menu item. */
-    icon?: IconDefinition;
-    /** The group of the menu item. */
-    group?: string;
-    /** The required capabilities of the menu item. */
-    requiredCapabilities?: string[];
-    /**
-     * Permissions (`"<app>.<resource>.<action>"`) the reader needs to see this item. All must hold.
-     * Absent = visible to everyone. Read `docs/ROLES.md` for the vocabulary.
-     */
-    permissions?: string[];
-}
-export interface NamespacedMenuItem extends MenuItem {
-    /** The namespace of the menu item. */
-    namespace: string;
-    /** The absolute path of the menu item. */
-    absolutePath: string;
-}