@opencxh/domain 1.128.0 → 1.131.0

package/dist/platform/ai-tools.d.ts

@@ -19,6 +19,25 @@ export interface AiTool {
     description: string;
     parameters: AiToolParameterSchema;
 }
+/**
+ * One entry in the tool catalog: what is available in this organisation right now.
+ *
+ * Lives in domain because three places already had their own copy (the AI server's
+ * registry and two of its client hooks) and the contact-source register needs a fourth —
+ * the catalog is what an organisation picks an external contact source from.
+ */
+export interface ToolCatalogEntry {
+    name: string;
+    description: string;
+    /** "mcp" for external MCP tools, otherwise the owning app name. */
+    source: string;
+    /** JSON-Schema of the tool's arguments — drives the playbook builder's param form. */
+    parameters: AiToolParameterSchema;
+    /** read | write as the tool declares it; absent = unknown. */
+    access?: "read" | "write";
+    /** internal | outward as the tool declares it; absent = outward. */
+    effect?: "internal" | "outward";
+}
 /** A model's request to call a tool. */
 export interface AiToolCall {
     id: string;

package/dist/platform/communication.d.ts

@@ -44,6 +44,12 @@ export interface CommsAccount<T = any> {
     userId: string;
     config: T;
     status: 'registered' | 'unregistered' | 'error';
+    /**
+     * The channel this registration serves. Set by the transport provider from
+     * its registration config; this is what binds an outgoing intent on a
+     * channel to the right account when several are registered at once.
+     */
+    channelId?: string;
 }
 export interface ITransportProvider {
     readonly id: string;
@@ -79,19 +85,19 @@ export declare enum CommunicationScheme {
     CALENDAR = "calendar"
 }
 /**
- * Account selector for `transport: session` intents. Tells the frontend
- * which `CommsAccount` should service this intent on this channel.
- *  - `protocol` only: pick the first registered account with this protocol
- *    (acceptable when there is one UA per provider per tenant)
- *  - `accountId` set: pin to a specific account (multi-trunk / multi-tenant)
- *  - `matcherId` set: defer to a client-registered matcher fn that picks the
- *    account based on dynamic context (channel, accounts). Lookup by string
- *    keeps the wire format JSON; fn lives in the runtime registry.
+ * Account selector for `transport: session` intents. Narrows the registered
+ * `CommsAccount`s down to the one that should service this intent.
+ *
+ * `protocol` is the filter axis rather than a provider id because the two id
+ * spaces don't line up: `channel.providerId` is the *server* provider (e.g.
+ * eylo-voip) while `account.providerId` is the *transport* provider (e.g.
+ * sip-provider). Which of the remaining candidates is picked is decided by the
+ * binding on the account itself (`CommsAccount.channelId`) — `accountId` is
+ * only a static pin for providers that have no per-channel binding.
  */
 export interface AccountSelector {
     protocol: string;
     accountId?: string;
-    matcherId?: string;
 }
 /**
  * Routing-hint voor de frontend en de comm-server: hoe wordt deze intent

package/dist/platform/scope.d.ts

@@ -21,6 +21,31 @@ export interface ScopeAuth {
      * onbekend, en dat wordt daar als "versmallen" gelezen: de veilige kant.
      */
     ownerScope?: OwnerScope;
+    /**
+     * De **dossiersleutels** waaronder deze resource valt: de canonieke sleutels waarmee andere
+     * apps hem in één geïndexeerde `$in` terugvinden.
+     *
+     * Dit is de ene conventie waarmee verbanden in dit platform worden uitgedrukt. Deze
+     * datastore kan niet joinen en niet recursief traverseren, dus een edge-*tabel* zou van
+     * elke vraag een keten van `$in`-hops met een groeiende idlijst maken. In plaats daarvan
+     * draagt elke contextdragende rij zijn eigen sleutels, platgeslagen op **schrijfmoment**:
+     * `Interaction.partyKeys` doet dat al, `Contact.keys`/`Company.keys` ook, en de
+     * geheugenlaag stempelt ze via dit veld op zijn items (`MemoryItem.keys`).
+     *
+     * Het vocabulaire is dat van `endpointKey`: `mailto:`, `tel:`, `domain:`, plus de
+     * vastgelegde `contact:<id>` / `company:<id>` / `interaction:<id>`. Twee rollen, één
+     * vorm — *identiteit* ("dit ben ik", `Contact.keys`) en *verwijzing* ("hier hoor ik bij",
+     * `partyKeys`).
+     *
+     * **Klein houden.** Dit is de set van de rij zelf, niet zijn hele omgeving: een company
+     * geeft zijn eigen sleutels en domeinen, níet die van tweehonderd medewerkers. Die
+     * fan-out hoort bij een expliciete zoekvraag (`keySetForCompany`), niet bij elke
+     * autorisatie — deze call zit op het hete pad van elke geheugen-schrijfactie.
+     *
+     * Afwezig = onbekend, en dat wordt gelezen als "alleen het subject zelf": minder
+     * vindbaar, nooit ruimer. Dezelfde richting als {@link ScopeAuth.ownerScope}.
+     */
+    keys?: string[];
 }
 /** GET /provider/scope/describe response: the scopeKey prefixes an app owns. */
 export interface ScopeDescribe {

package/dist/platform/services.d.ts

@@ -36,7 +36,24 @@ export type ServiceHandlerMetadata<P = any, T = any, R = any> = {
     appId: string;
     fn: ServiceHandlerFn<P, T, R>;
 };
-export type ServiceCallOptions<P, T> = {
+/**
+ * `T` defaults to `unknown` because most handlers only care about `params`.
+ * Spelling it `never` instead makes the handler unassignable to
+ * {@link ServiceHandlerFn} (whose `payload` is `any`), which is a confusing error
+ * for a service that simply takes no payload.
+ */
+export type ServiceCallOptions<P, T = unknown> = {
     params?: P;
     payload?: T;
+    /**
+     * Restrict this call to these provider apps.
+     *
+     * Without it the only participation filter is "is the app installed for this org",
+     * which is all-or-nothing and the same switch that controls the app's routes and
+     * settings pages. A caller that has a per-source preference (which address books may
+     * be searched) needs to narrow one call without uninstalling anything.
+     *
+     * Absent means every enabled handler, which is the previous behaviour.
+     */
+    appIds?: string[];
 };

package/dist/text/endpoint.d.ts

@@ -0,0 +1,104 @@
+/**
+ * One normalisation for communication endpoints — phone numbers, e-mail addresses
+ * and the lookup keys built from them.
+ *
+ * Before this module there were five copies of `resource.replace(/[\s()-]/g, "")`
+ * spread over eylo-voip, microsoft and three comms services, plus a sixth variant
+ * with `+31` hardcoded. None of them turned a national number into an international
+ * one, so `0882112121` never matched `+31882112121`. Every lookup key in the platform
+ * has to be produced here, or the write side and the read side drift apart and the
+ * index is worthless.
+ *
+ * Deliberately dependency-free: `libphonenumber-js` is ~145 kB for a rule we express
+ * in a table. The honest cost is that we cannot validate per-country number *plans*,
+ * only plausible lengths — so we reject implausible input instead of forcing it, and
+ * callers keep the raw value for display.
+ */
+/** A dialling plan entry: enough to normalise, not enough to validate a number plan. */
+export interface PhoneRegion {
+    /** E.164 country calling code, without `+`. */
+    callingCode: string;
+    /** Prefix used when dialling domestically (dropped when going international). */
+    trunkPrefix?: string;
+    /** Plausible length of the national significant number, excluding the trunk prefix. */
+    nsnMin: number;
+    nsnMax: number;
+}
+/**
+ * The regions we serve. Adding one is a table entry, not code — but do add it: a
+ * missing region means every national number from that country resolves to `null`.
+ */
+export declare const PHONE_REGIONS: Record<string, PhoneRegion>;
+/** Fallback when no organisation region is configured. */
+export declare const DEFAULT_PHONE_REGION = "NL";
+/**
+ * True when a value looks like an e-mail address rather than a SIP-style phone URI.
+ *
+ * Both contain an `@`, so presence of one proves nothing: `0653928801@demo1.eylo.tel` is a
+ * phone number. The local part decides — digits and phone punctuation mean a number.
+ */
+export declare function looksLikeEmail(value: string | undefined | null): boolean;
+/**
+ * Turn any written form of a phone number into `+<callingCode><nsn>`, or `null` when
+ * it cannot be resolved without guessing.
+ *
+ * | input | output |
+ * |---|---|
+ * | `+31 88 211 2121` | `+31882112121` |
+ * | `0031882112121` | `+31882112121` |
+ * | `088 211 2121` (region NL) | `+31882112121` |
+ * | `882112121` | `null` — ambiguous, we do not guess |
+ *
+ * Resolution order for the region: an explicit `+` or `00` wins, then `defaultRegion`
+ * (the organisation setting, or the region of the channel the call came in on).
+ */
+export declare function toE164(raw: string | undefined | null, defaultRegion?: string): string | null;
+/**
+ * The last 8-9 digits of a number, notation-independent: `+31882112121`,
+ * `0882112121` and `088 211 2121` all share `882112121`.
+ *
+ * Use it to ORDER candidates for a human. Never to link automatically — short
+ * suffixes collide across borders and direct-dial ranges make it worse.
+ */
+export declare function phoneSuffix(raw: string | undefined | null, length?: number): string | null;
+/**
+ * Lowercase, trim and drop a `+tag` sub-address, so `Naam+factuur@Bedrijf.NL`
+ * matches `naam@bedrijf.nl`.
+ */
+export declare function normalizeEmail(raw: string | undefined | null): string | null;
+/** The domain part of an e-mail address, already normalised. */
+export declare function emailDomain(raw: string | undefined | null): string | null;
+/**
+ * The registrable part of a host: `mail.bedrijf.nl` → `bedrijf.nl`,
+ * `mail.bedrijf.co.uk` → `bedrijf.co.uk`. A subdomain belongs to the same company.
+ *
+ * This is a short list, not the public suffix list — a dependency-free approximation
+ * that is right for the regions we serve and degrades to "one label too many", never
+ * to a public suffix on its own.
+ */
+export declare function registrableDomain(host: string | undefined | null): string | null;
+/**
+ * Free-mail and consumer domains. A company row with `gmail.com` in `domains` would
+ * map EVERY private customer onto itself — not an edge case but the first time
+ * somebody saves a Gmail address on a company.
+ */
+export declare const PUBLIC_EMAIL_DOMAINS: Set<string>;
+/** True when a domain is consumer mail and must never identify a company. */
+export declare function isPublicEmailDomain(domain: string | undefined | null): boolean;
+/**
+ * Does normalising this scheme need a phone region?
+ *
+ * Worth asking before resolving one: the region lives on the organisation, so fetching it
+ * is a cross-app round trip, while an e-mail address has no region at all. A mail-only
+ * lookup that resolves the region anyway pays for four internal RPCs it never uses.
+ */
+export declare function needsPhoneRegion(scheme: string | undefined | null): boolean;
+/**
+ * The canonical, indexable lookup key for an endpoint: `tel:+31882112121`,
+ * `mailto:naam@bedrijf.nl`. Returns `null` when the resource cannot be normalised —
+ * an un-normalisable value must never reach a key array, or the index lies.
+ *
+ * `scheme` is the lowercase `CommunicationScheme` value; this module deliberately does
+ * not import that enum so it stays usable from the write path of any app.
+ */
+export declare function endpointKey(scheme: string | undefined | null, resource: string | undefined | null, defaultRegion?: string): string | null;

package/dist/text/endpoint.test.d.ts

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

package/dist/text/region.test.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.128.0",
+  "version": "1.131.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -10,14 +10,18 @@
   ],
   "scripts": {
     "build": "vite build",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:watch": "vitest --watch"
   },
   "peerDependencies": {
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "typescript": "^5.2.2",
+    "typescript": "6.0.3",
     "vite": "7.1.7",
-    "vite-plugin-dts": "^4.5.4"
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.0.18"
   }
 }