@opencxh/domain 1.182.0 → 1.183.0

package/dist/entities/onboarding/index.d.ts

@@ -0,0 +1,2 @@
+export * from './source';
+export * from './types';

package/dist/entities/onboarding/source.d.ts

@@ -0,0 +1,147 @@
+import { LocaleBundle } from '../analytics/dashboard';
+/**
+ * Role group of an app that declares its own setup steps.
+ *
+ * A constant and not a literal at both ends: `Bridge.providers.list` answers an unknown group
+ * with an empty list, so a typo would read as "no app has setup steps". Same reason
+ * `SYNC_SOURCE_PROVIDER_GROUP` is a constant.
+ */
+export declare const ONBOARDING_SOURCE_PROVIDER_GROUP = "onboarding-source";
+/**
+ * Text the hub renders without knowing what it says: an i18n key from the declaring app's own
+ * bundle, plus values for `{name}` placeholders.
+ *
+ * Not a plain string, because a describe is cached across users and the source cannot know the
+ * reader's language. Not a bare key either: half of these lines carry data ("1.284 contacts
+ * imported") and a key per count does not exist.
+ */
+export interface OnboardingText {
+    key: string;
+    vars?: Record<string, string | number>;
+}
+/**
+ * How urgent this step is. Three values, because the board has three kinds of urgency and two
+ * cannot express the middle one.
+ *
+ * - `live` — the organisation cannot help a customer until this is done. Counts in the live gate,
+ *   and the only tier that carries "needed to go live".
+ * - `soon` — real setup work, but nothing is blocked by it: seed the knowledge base, confirm what
+ *   the assistant may do. Sits with the rest of your work, outside the gate.
+ * - `improve` — polish that may sit for months (per-topic routing rules, SSO, own greetings).
+ *   Lands under "later, no hurry" on its own, without the admin having to push it there.
+ *
+ * App-declared, because only the owning app knows that an inbox without an enabled channel is not
+ * a working inbox. Nothing caps how many `live` items an app may claim — worth re-reading whenever
+ * a new source is added, because the gate stops meaning anything at thirty of them.
+ */
+export type OnboardingTier = "live" | "soon" | "improve";
+/**
+ * What the declaring app can know by itself. Three values, not five.
+ *
+ * `waiting` means the app is waiting on a third party (a number port, DNS propagation, a vendor
+ * approval) and the admin must do nothing. The two hub-owned states — delegated and pushed to
+ * later — are absent on purpose: an app cannot know you handed its step to a colleague, and the
+ * hub cannot know a port request is pending.
+ */
+export type OnboardingItemState = "done" | "todo" | "waiting";
+/** Where an action takes you. Two shapes, because the shell has exactly two surfaces. */
+export type OnboardingLink = 
+/**
+ * An app route, app-relative (`/callflows/abc`). Followed with `sdk.router.navigate`.
+ *
+ * `app` only when the target is *another* app — the declaring app is the default, so an item
+ * pointing into its own screens cannot name the wrong one.
+ */
+{
+    kind: "route";
+    path: string;
+    app?: string;
+}
+/**
+ * A settings page. Panels have no URL, so this is the registry key rather than a path.
+ *
+ * `<app>:<page>` (`communication:channels`); a bare `channels` is read as this app's own page.
+ */
+ | {
+    kind: "settings";
+    pageId: string;
+};
+/**
+ * - `apply` — "set it up this way": the hub posts to the owner's `/provider/onboarding/apply`
+ * - `open` — follow `link` into the app that owns the step
+ * - `review` — same mechanics as `open`, different copy and weight ("check the drafts")
+ * - `delegate` — the hub's own panel; the declaring app knows nothing about it
+ * - `status` — read-only, for `waiting`: a line, not a button
+ */
+export interface OnboardingAction {
+    kind: "apply" | "open" | "review" | "delegate" | "status";
+    /** Required for `open` and `review`. */
+    link?: OnboardingLink;
+    /** Overrides the hub's house copy for this verb. Usually absent. */
+    label?: OnboardingText;
+}
+export interface OnboardingItem {
+    /**
+     * App-namespaced and stable: `communication.servicedesk-inbox`, `eylo-voip.dialplan`.
+     *
+     * A stored reference — hub state and delegated tasks key on it — so renaming an id orphans a
+     * delegation. The prefix is convention for readability, never routing: `apply` is dispatched to
+     * the provider whose describe declared the id.
+     */
+    id: string;
+    tier: OnboardingTier;
+    state: OnboardingItemState;
+    title: OnboardingText;
+    /**
+     * The card's body, and therefore the proposal itself. There is no preview endpoint: the describe
+     * already computed what would happen, which is what makes the card readable.
+     */
+    description?: OnboardingText;
+    /** The line under the app label: "needed to go live". */
+    reason?: OnboardingText;
+    /** Minutes, not a rendered string — a later guided flow sums them into "about 20 min to go". */
+    estimateMinutes?: number;
+    actions: OnboardingAction[];
+    /** The small-caps chip (TELEPHONY, KNOWLEDGE BASE). Absent = the app's display name. */
+    group?: OnboardingText;
+    /** Absent = true. `false` for a step nobody else could take over. */
+    delegatable?: boolean;
+    /**
+     * Can this app observe completion by itself?
+     *
+     * `true` — "a team exists", "three colleagues can reply": the next describe returns `done` on
+     * its own, and a finished task proves nothing extra.
+     * `false` — no server state to read (DNS records at a registrar we have no credentials for, a
+     * vendor authorisation without an API). Only then does a completed delegation count as done.
+     *
+     * This boolean is the seam between "the app knows" and "someone said so". Declaring it per item
+     * keeps the trust window per step instead of making it global policy.
+     */
+    verifiable: boolean;
+    /** Sort hint within a tier. Ties break on app name, then id, so the order stays stable. */
+    order?: number;
+}
+/**
+ * Payload of `GET /provider/onboarding/describe`.
+ *
+ * Bare, not wrapped in `ResponseFactory` — that is how the fan-out reads it, same as
+ * `analytics-source` and `memory-source`.
+ */
+export interface OnboardingSourceDescribe {
+    /** The declaring app (== manifest name == `req.source.app`). */
+    source: string;
+    items: OnboardingItem[];
+    /** Texts for every key above, in every language this app ships. `flattenLocales()` helps. */
+    locales?: LocaleBundle;
+}
+/** Body of `POST /provider/onboarding/apply`. The only thing that crosses the app boundary. */
+export interface OnboardingApplyRequest {
+    itemId: string;
+}
+/** Result of an apply, wrapped in `ResponseFactory` by the provider. */
+export interface OnboardingApplyResult {
+    /** What was created, in the app's own words. Shown as a toast. */
+    message?: OnboardingText;
+    /** Where to look at the result, when there is something to look at. */
+    link?: OnboardingLink;
+}

package/dist/entities/onboarding/types.d.ts

@@ -0,0 +1,82 @@
+import { LocaleBundle } from '../analytics/dashboard';
+import { OrganizationProfile } from '../organization/profile';
+import { OnboardingApplyResult, OnboardingItem } from './source';
+/**
+ * The five groups from the design, grouped by who has to act. Composed by the hub; no app and no
+ * table stores it.
+ *
+ * | value          | owner | source                                                       |
+ * |----------------|-------|--------------------------------------------------------------|
+ * | done           | app   | state `done`, or a finished task on a `verifiable: false` item |
+ * | with-you       | app   | state `todo` with no hub overlay                             |
+ * | with-colleague | hub   | an open delegation row                                       |
+ * | waiting-on-us  | app   | state `waiting`                                              |
+ * | later          | hub   | the admin pushed it down                                     |
+ */
+export type OnboardingStatus = "done" | "with-you" | "with-colleague" | "waiting-on-us" | "later";
+export interface OnboardingDelegation {
+    taskId: string;
+    assigneeId: string;
+    /** Resolved by the hub. Absent means draw no name and no avatar rather than an id. */
+    assigneeName?: string;
+    delegatedAt: number;
+}
+/** An item as the page receives it: the app's declaration plus the hub's overlay. */
+export interface OnboardingViewItem extends OnboardingItem {
+    /** Stamped from `OnboardingSourceDescribe.source`, never read off the item itself. */
+    app: string;
+    status: OnboardingStatus;
+    delegation?: OnboardingDelegation;
+}
+/** The live gate ("3 of 4"). Derived from the composed items, never stored. */
+export interface OnboardingLiveGate {
+    /** Every `tier: "live"` item, in order — these are the checklist lines. */
+    itemIds: string[];
+    total: number;
+    done: number;
+    /** Set only when exactly one live item is left, so the band can name it. */
+    nextItemId?: string;
+}
+export interface OnboardingCounts {
+    all: number;
+    withYou: number;
+    withColleagues: number;
+    waitingOnUs: number;
+    later: number;
+    done: number;
+}
+/** An installable app this organisation does not use yet. */
+export interface OnboardingSuggestedApp {
+    name: string;
+    displayName: string;
+    shortDescription?: string;
+    icon?: string;
+}
+/**
+ * Payload of `POST organization/onboarding/apply`.
+ *
+ * The recomputed board travels with the result, and that is a contract rather than a convenience:
+ * applying one step can flip the live gate, move an item between groups and change every count, so
+ * a response carrying only the changed step would leave the page showing numbers that no longer
+ * hold — and a follow-up GET would show them for the length of a round trip.
+ */
+export interface OnboardingApplyResponse {
+    result: OnboardingApplyResult;
+    view: OnboardingView;
+}
+/** Payload of `GET organization/onboarding/`. */
+export interface OnboardingView {
+    items: OnboardingViewItem[];
+    gate: OnboardingLiveGate;
+    counts: OnboardingCounts;
+    /** Merged from every source's describe; handed straight to `registerBundle`. */
+    locales: LocaleBundle;
+    suggestedApps: OnboardingSuggestedApp[];
+    /**
+     * Apps whose describe did not answer, so the page can say what is missing instead of lying by
+     * omission. Always present — `[]` when every source answered — so the client never has to tell
+     * "all fine" apart from "this field is old".
+     */
+    degradedApps: string[];
+    profile?: OrganizationProfile;
+}

package/dist/entities/organization/index.d.ts

@@ -1,2 +1,3 @@
 export * from './billing';
+export * from './profile';
 export * from './types';

package/dist/entities/organization/profile.d.ts

@@ -0,0 +1,57 @@
+import { ChannelKind } from '../../platform/communication';
+/** Keys and not free text: an app has to be able to branch on this. */
+export type WorkArea = "support" | "billing" | "availability" | "sales" | "onboarding";
+/** A tool the organisation runs today, and whether it stays or gets replaced. */
+export interface ProfileTool {
+    /** Lowercased vendor name: "outlook", "zendesk", "hubspot". */
+    name: string;
+    disposition: "keep" | "replace";
+}
+/**
+ * One window, because that is the intake answer ("Mon-Fri 08:30-17:30"). Per-day windows and
+ * holidays belong to the dialplan that enforces them, not here.
+ */
+export interface ProfileOpeningHours {
+    /** ISO weekdays, 1 = Monday. */
+    days: number[];
+    /** "08:30", local to the organisation. */
+    from: string;
+    to: string;
+}
+/**
+ * What the company said about itself. Input to every app's setup proposal, and the reason the
+ * setup centre can promise that changing this changes the proposals.
+ *
+ * Flat and small on purpose: a form has to fill it in one sitting and an app has to branch on it
+ * with an `includes`. Anything richer (which team, which number, which mailbox) is real
+ * configuration and belongs to the app that owns it.
+ */
+export interface OrganizationProfile {
+    workAreas?: WorkArea[];
+    channels?: ChannelKind[];
+    /** Intended headcount. A proposal needs the target, not today's count. */
+    teamSize?: number;
+    toolsInUse?: ProfileTool[];
+    /** "Within 4 hours on business days". */
+    responseTime?: {
+        hours: number;
+        businessHoursOnly: boolean;
+    };
+    openingHours?: ProfileOpeningHours;
+    tone?: {
+        formality: "informal" | "formal";
+        length: "short" | "normal";
+        /** ISO codes, primary first. */
+        languages: string[];
+    };
+    /** `posture` shares its vocabulary with playbook autonomy deliberately. */
+    ai?: {
+        posture: "off" | "suggest" | "auto";
+        region?: "eu" | "us";
+        ownKey?: boolean;
+    };
+    /** Epoch ms of the last intake edit. */
+    updatedAt?: number;
+}
+export declare const WORK_AREAS: WorkArea[];
+export declare const PROFILE_TOOL_DISPOSITIONS: ProfileTool["disposition"][];

package/dist/entities/organization/types.d.ts

@@ -1,3 +1,4 @@
+import { OrganizationProfile } from './profile';
 export interface OrganizationAddress {
     street?: string;
     houseNumber?: string;
@@ -34,6 +35,11 @@ export interface Organization {
     description?: string;
     address?: OrganizationAddress;
     billing?: OrganizationBilling;
+    /**
+     * What this organisation does, from the setup intake. Read by every onboarding source to decide
+     * which steps apply and what to propose. See `profile.ts`.
+     */
+    profile?: OrganizationProfile;
     /** Small company logo stored inline as a base64 data-URI. */
     logo?: string;
     /**