@opencxh/domain 1.232.0 → 1.233.1

package/dist/entities/planning/terms.d.ts

@@ -0,0 +1,42 @@
+/**
+ * How many hours somebody is available in a week.
+ *
+ * An employment fact, not a planning one — it changes because a contract changes, and it has
+ * readers outside planning waiting: overtime is booked time above these hours, utilisation is
+ * billable divided by them, and leave accrual is a function of them.
+ *
+ * **It lives in `apps/planning` on purpose, and temporarily.** Three things keep the eventual move
+ * to an HR app a hostname rather than a project: this type is in `domain` and not in the app; the
+ * app keeps it in one resource folder with no terms logic scattered elsewhere; and every reader
+ * reads it over HTTP, which is the only option anyway since apps share no store.
+ */
+export interface EmploymentTerms {
+    id: string;
+    organizationId: string;
+    userId: string;
+    /**
+     * Contract hours, as minutes per week.
+     *
+     * **Known limit:** a Dutch contract is often "36 hours averaged over 13 weeks". This field
+     * cannot say that. An averaging period is one field more the day somebody needs it; it is
+     * written down here so it is not a surprise.
+     */
+    weeklyMinutes: number;
+    /** From when this holds. A changed contract is a new row, never a patch on the old one. */
+    effectiveFrom?: number;
+    note?: string;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * The terms that applied to somebody on a given day.
+ *
+ * The most recent `effectiveFrom` that had already started wins, so the row that governed last
+ * quarter stays readable next to the weeks it governed.
+ *
+ * Deliberately no `fte`: that is `weeklyMinutes` divided by a full-time norm which differs per
+ * organisation — forty hours here, thirty-six elsewhere. Storing it would be a second truth;
+ * showing it can wait until there is a norm to divide by.
+ */
+export declare function termsFor(terms: readonly EmploymentTerms[], userId: string, day: number): EmploymentTerms | undefined;

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

@@ -0,0 +1,188 @@
+import { FilterClause } from '../analytics/report';
+import { OwnerScope } from '../scope/types';
+/**
+ * Where a planned row stands.
+ *
+ * `draft` is the whole reason this field exists: a planner builds next week over an afternoon,
+ * and half a roster must not read as coverage while they do. `requested`/`declined` only ever
+ * occur on an approvable kind (leave) — see {@link ScheduleKind.approvable}.
+ */
+export type ScheduleStatus = "draft" | "published" | "requested" | "approved" | "declined" | "cancelled";
+/** Who asked for this row, and why when a system did. */
+export interface ScheduleEntrySource {
+    initiator: "user" | "system";
+    /** Free reason on `system` ("copy_week", "playbook"). Same shape as WorkItemSource. */
+    reason?: string;
+}
+/**
+ * One person, one time span, one kind of time.
+ *
+ * Shift, break, training, leave request, project allocation and customer appointment are all
+ * this row with a different `kindKey`. They share the span, the person, the overlap rules, the
+ * grid, publication and the capacity arithmetic; what differs is whether the kind *makes*
+ * capacity, *spends* it or *takes it away*, and that is two flags on the kind — not three tables.
+ */
+export interface ScheduleEntry {
+    id: string;
+    organizationId: string;
+    /** Who. **Absent = an open shift** — planned work with no name on it, visible as a gap. */
+    userId?: string;
+    /** Only on an open shift: the role being looked for. A free string until skills exist. */
+    placeholderRole?: string;
+    /** Which kind of time. See `FIXED_KINDS`; an unknown key is treated as unproductive. */
+    kindKey: string;
+    /** Epoch ms, half-open `[start, end)` — the same convention as analytics' DateRange. */
+    start: number;
+    end: number;
+    status: ScheduleStatus;
+    /** Where this time goes on the demand side. Absent on a shift = unallocated capacity. */
+    workstreamId?: string;
+    /** Where it goes on the work side: `work_project:7`, `work_item:42`, `company:9`. */
+    scopeKey?: string;
+    /** Which team this time is worked for. Feeds `WorkMode.source = "roster"` later. */
+    teamId?: string;
+    /**
+     * Which `WorkType` the hours on this block will be booked under.
+     *
+     * The join with `apps/time`: planned and booked time land on the same key, so planned-versus-
+     * actual is one grouping instead of a mapping table. Absent = the workstream's default.
+     */
+    workTypeKey?: string;
+    note?: string;
+    /** Set once a published row reached the person's calendar. Absent = never pushed. */
+    calendarEventId?: string;
+    externalIds?: string[];
+    source: ScheduleEntrySource;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * How a workstream's demand is derived.
+ *
+ * Three shapes, one output: required person-seconds per interval. `metric` is the support case
+ * (history → forecast), `source` the delivery case (an app that knows what work is coming),
+ * `fixed` the back-office case (always two people on it).
+ *
+ * `source` is a provider role and not a list of app names on purpose: planning must not grow a
+ * branch per app that can generate work. `metric` needs no provider because analytics already
+ * federates every app's volume — a source only declares itself when its demand is not a
+ * countable stream with a handle time.
+ */
+export type WorkstreamDemand = {
+    kind: "metric";
+    /** An analytics metric id, e.g. "comms.conversations.created". */
+    metricId: string;
+    /** The mapping rule. There is no second rule engine — this *is* it. */
+    filters?: FilterClause[];
+    /** Average handle time per unit, in seconds. */
+    handleSeconds: number;
+    /** A duration metric to read AHT from instead of the fixed number. Not in v1. */
+    handleSecondsMetricId?: string;
+} | {
+    kind: "source";
+    /** The app answering `POST /provider/demand/query`. See {@link DemandSourceDescribe}. */
+    sourceApp: string;
+    /** Opaque to planning, validated by the source: `{ projectIds, cycleId }` for apps/work. */
+    params?: Record<string, unknown>;
+} | {
+    kind: "fixed";
+    headcount: number;
+    /** Local hours the fixed staffing applies to, e.g. `[8, 18]`. Absent = around the clock. */
+    weekdayHours?: [number, number];
+};
+/**
+ * How required work turns into required people.
+ *
+ * `queue` is for work that arrives and waits — you steer on how fast it gets picked up. `hours`
+ * is for work that is already known — you divide it by the clock. Named after the question a
+ * planner answers, not after the maths: `queue` runs Erlang C underneath (see `erlang.ts`), and
+ * a field called `erlang_c` asks every reader to know a 1917 formula before they can pick one.
+ *
+ * `unplannedLossPercent` — shrinkage, in the trade — defaults to 0 on purpose: most WFM tools
+ * assume 25-35% because breaks, training and meetings are not in their roster. Here they are, as
+ * rows that give no coverage. It is only for what you *cannot* roster (sick leave, ad hoc), and
+ * counting it twice is the classic error.
+ */
+export type StaffingPolicy = {
+    model: "hours";
+    unplannedLossPercent?: number;
+} | {
+    model: "queue";
+    /** e.g. 80 for "80% of contacts answered within `targetSeconds`". */
+    serviceLevelPercent: number;
+    targetSeconds: number;
+    /** Cap on how busy an agent may be, e.g. 85. Absent = no cap. */
+    maxOccupancyPercent?: number;
+    unplannedLossPercent?: number;
+};
+/** A bucket demand comes from: an inbox, a project, a process, a pipeline. */
+export interface Workstream {
+    id: string;
+    organizationId: string;
+    /** Org-unique slug — the same shape as `WorkType.key`. */
+    key: string;
+    name: string;
+    description?: string;
+    color?: string;
+    icon?: string;
+    /** Team or org, never personal: a workstream nobody but you can see plans nothing. */
+    ownerScope: OwnerScope;
+    demand: WorkstreamDemand;
+    staffing: StaffingPolicy;
+    /**
+     * The `WorkType` blocks on this workstream get when nobody picks one.
+     *
+     * Deliberately not a `billable` flag of its own. Billability already has a home —
+     * `WorkType.defaultBillable`, which every booked hour resolves through — and a second flag
+     * here would drift from it the first time somebody changes one of the two.
+     */
+    defaultWorkTypeKey?: string;
+    archived?: boolean;
+    order?: number;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * A human override on a forecast, and the only forecast row that is stored.
+ *
+ * The forecast itself is a pure function of history + these; recomputing it on read costs less
+ * than a job plus the "why is this number stale" question that a stored forecast creates.
+ */
+export interface ForecastAdjustment {
+    id: string;
+    organizationId: string;
+    workstreamId: string;
+    /** Epoch ms, half-open `[from, to)`. */
+    from: number;
+    to: number;
+    /** A multiplier (1.3 = campaign week). Ignored when `absoluteVolume` is set. */
+    factor?: number;
+    /** An absolute volume per interval. Wins over `factor`. */
+    absoluteVolume?: number;
+    note?: string;
+    createdBy: string;
+    createdAt?: number;
+}
+/**
+ * One interval of the coverage answer. Derived on read, never stored.
+ *
+ * Headcounts are FTE-equivalents (`seconds / intervalSeconds`) and may be fractional: somebody
+ * who works half the hour covers half of it. Rounding to whole people here would make a
+ * half-staffed interval look either fully covered or empty.
+ */
+export interface CoverageInterval {
+    /** "2026-09-17T09" — the same period key `MetricFact` uses. */
+    period: string;
+    forecastVolume?: number;
+    requiredSeconds: number;
+    requiredHeadcount: number;
+    scheduledSeconds: number;
+    scheduledHeadcount: number;
+    /** `scheduled - required`. Negative = short. */
+    netHeadcount: number;
+    /** All shift time, whether or not it is allocated to this workstream. */
+    capacitySeconds: number;
+    absentSeconds: number;
+}

package/dist/entities/strategy/levels.d.ts

@@ -60,6 +60,18 @@ export declare function levelOrder(levelKey: string, levels?: readonly StrategyL
  * key this platform does not recognise.
  */
 export declare function canParent(childLevelKey: string, parentLevelKey: string, levels?: readonly StrategyLevel[]): boolean;
+/**
+ * The rung a child of this row gets by default.
+ *
+ * What the inline "+" on a row creates: one step down the ladder, so a focus area yields a goal
+ * and a goal yields a key result. **The deepest rung yields itself** rather than nothing — a key
+ * result under a key result is unusual but legal (`canParent` allows equal rungs), and returning
+ * `undefined` would mean the affordance disappears exactly where a team is working deepest.
+ *
+ * An unknown level ranks last, so it also yields itself. That is the safe direction: a level a
+ * source invented gets a sibling, not a guess at what sits under it.
+ */
+export declare function nextLevelBelow(levelKey: string, levels?: readonly StrategyLevel[]): string;
 /**
  * Which of our own rungs a source's name means, or `null`.
  *

package/dist/entities/strategy/progress.d.ts

@@ -4,11 +4,19 @@ import { StrategyHealth, StrategyItem, StrategyMeasure, StrategyProgress } from
  *
  * Measured from `startValue`, not from zero: "from 5h30m down to 2h" is 0% on day one, while a
  * zero baseline would report that same goal as already two-thirds done before anyone did
- * anything. `direction` is what makes the falling case work at all.
+ * anything.
  *
- * When target and start are equal there is no distance to travel, so the ratio is the answer to
- * "are we there": 1 if the current value has reached the target in the intended direction,
- * otherwise 0. Dividing would be `Infinity` or `NaN`, and both render as a full bar.
+ * **`direction` and the bounds have to agree, and this is where they are checked.** The maths
+ * needs no `direction` at all — a falling goal is one whose target lies below its start, and the
+ * division handles that by itself. The field exists for the one case the bounds cannot express
+ * (holding a number steady, where start equals target) and for the label on the form. So when the
+ * two disagree — "lower is better" with a target *above* the start, which a form will happily
+ * accept — the bounds are not a scale at all, and this falls back to the only honest answer:
+ * "are we there, yes or no". Dividing anyway is what reported a goal as 100% done the moment its
+ * value went the wrong way.
+ *
+ * A value that cannot be a number is 0, never `NaN`: a `NaN` ratio renders as an empty bar with
+ * no width and reads as "not started".
  */
 export declare function measureRatio(measure: Pick<StrategyMeasure, "direction" | "startValue" | "targetValue">, currentValue: number): number;
 /**