@opencxh/domain 1.260.0 → 1.262.0

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

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

package/dist/entities/approval/policy.d.ts

@@ -0,0 +1,39 @@
+import { ApprovalDecision, ApprovalFacts, ApprovalPolicy, ApprovalRequest, ApproverSet } from './types';
+/** What a policy is matched against: the resource's kind, the act, and the reported facts. */
+export interface ApprovalMatchInput extends ApprovalFacts {
+    scopeKind: string;
+    act: string;
+}
+/**
+ * The rule that guards this act, or nothing.
+ *
+ * **Specificity decides, not an order column.** A rule with a threshold beats one without, and
+ * among several thresholds the highest one that still fits wins — so the Ramp/Spendesk ladder
+ * ("above 1.000 the manager, above 10.000 finance") reads correctly at 12.000 without anybody
+ * keeping a priority number in sync. Ties break on id so two equal rules never swap between reads.
+ *
+ * A rule with a threshold never matches a caller that reported no amount: the caller is the only
+ * one who knows whether its row has a value, and guessing "0" would let every quote through.
+ */
+export declare function matchApprovalPolicy(policies: readonly ApprovalPolicy[], input: ApprovalMatchInput): ApprovalPolicy | undefined;
+/**
+ * Who still has to sign: the named people plus the named teams' members, minus the requester.
+ *
+ * Flattened here and stored on the row, because the store cannot join and "what waits on me" has
+ * to be one indexed read. Team membership is resolved by the caller — this layer never fetches.
+ */
+export declare function pendingApprovers(approvers: ApproverSet, teamMembers: Readonly<Record<string, readonly string[]>>, requestedBy: string, allowSelfApproval?: boolean): string[];
+/**
+ * One verdict folded into a request.
+ *
+ * Three rules, and the order is the point:
+ *
+ * 1. A settled request stays settled — a late job or a double click writes nothing.
+ * 2. A second vote from the same person counts once; the first one stands.
+ * 3. **A rejection always wins.** With `rule: "all"` a single no ends it; with `"any"` a yes ends
+ *    it. So the two rules differ only in what it takes to say yes, never in what it takes to say no.
+ *
+ * Pure: the caller decides whether this person may vote at all (the route gates on
+ * `pendingUserIds`) and writes the result.
+ */
+export declare function applyApprovalDecision(request: ApprovalRequest, decision: ApprovalDecision): ApprovalRequest;

package/dist/entities/approval/policy.test.d.ts

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

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

@@ -0,0 +1,104 @@
+import { OrgTeamScope } from '../scope/types';
+/**
+ * Who may decide. People and teams, never a role: `docs/ROLES.md` §7 says every session still
+ * gets `{"*":["*"]}`, so a rule naming a role would point at everybody.
+ */
+export interface ApproverSet {
+    userIds: string[];
+    teamIds: string[];
+}
+/** `any` = one sign-off is enough, `all` = everybody named. No chains; see the plan. */
+export type ApprovalRule = "any" | "all";
+export type ApprovalStatus = "pending" | "approved" | "rejected" | "withdrawn";
+export type ApprovalVerdict = "approved" | "rejected";
+export interface ApprovalDecision {
+    userId: string;
+    decision: ApprovalVerdict;
+    at: number;
+    note?: string;
+}
+/**
+ * One request for sign-off on one act, on any resource in the platform.
+ *
+ * Addressed by `scopeKey` like {@link Pin} and `SlaClock`: this layer knows nothing about quotes
+ * or work items, and the app that owns the kind stays the one that authorizes access to it.
+ */
+export interface ApprovalRequest {
+    id: string;
+    organizationId: string;
+    /** `<kind>:<ref>` — the vocabulary `assertScopeAccess` already speaks. */
+    scopeKey: string;
+    /**
+     * What is being asked for: `"issue"`, `"status:published"`. A free string the owning app owns;
+     * this layer only compares it. The act's parameters live *inside* it, which is why there is no
+     * opaque payload column. A act with real arguments earns a `payload` field then, not now.
+     */
+    act: string;
+    requestedBy: string;
+    requestedAt: number;
+    approvers: ApproverSet;
+    /**
+     * Teams flattened to people at write time, minus the requester unless the rule allows self
+     * approval. The only column "what waits on me" queries — the store cannot join, and an array
+     * column needs `anyOf` to match at all.
+     */
+    pendingUserIds: string[];
+    rule: ApprovalRule;
+    status: ApprovalStatus;
+    decisions: ApprovalDecision[];
+    /** Federated card of the source app, `"sales:ApprovalCard"`. Absent = text plus a link. */
+    resource?: string;
+    /**
+     * What the thing is called, snapshotted by the app that asked. Used **cold**: a notification is
+     * read long after it was written and the queue lists requests across apps, so neither has the
+     * resource at hand. Same doctrine as `Pin.label` — whoever renders it with the live row in
+     * reach lets the live value win. Absent = the reader falls back to the key.
+     */
+    title?: string;
+    /** What the requester wrote when submitting. */
+    note?: string;
+    policyId?: string;
+    settledAt?: number;
+}
+/**
+ * A rule: for this kind of resource and this act, above this amount, these people sign.
+ *
+ * Same shape as `SlaProfile` — org/team owned configuration, a small matching surface, and no
+ * `order` column: the match is decided by specificity (see {@link matchApprovalPolicy}), not by
+ * a number somebody has to keep in sync.
+ */
+export interface ApprovalPolicy {
+    id: string;
+    organizationId: string;
+    ownerScope: OrgTeamScope;
+    name: string;
+    enabled: boolean;
+    /** The scopeKey prefix this rule guards: `"quote"`, `"work_item"`. */
+    scopeKind: string;
+    /** The act it guards: `"issue"`, `"status:published"`. */
+    act: string;
+    /**
+     * Below this the act passes unguarded. Absent = always guarded. In cents, like all money here:
+     * a threshold in euros would round differently than the totals it is compared against.
+     */
+    minAmountCents?: number;
+    approvers: ApproverSet;
+    rule: ApprovalRule;
+    /** Default false: four eyes does not mean your own two, twice. */
+    allowSelfApproval?: boolean;
+}
+/** Facts the caller reports about its own row, for a rule to match on. Never a judgement. */
+export interface ApprovalFacts {
+    amountCents?: number;
+}
+/** What the gate answers. `not_required` is the common case and costs the caller nothing. */
+export type ApprovalGateState = "not_required" | "pending" | "approved";
+/**
+ * *Why* the gate answered that, for the two cases where "nothing happened" is a surprise.
+ *
+ * Only `no_approvers` needs saying out loud: a rule whose only approver is the person acting
+ * lets the act through, which is the right call (a request nobody can decide is a deadlock with
+ * no screen to fix it from) and the wrong silence — somebody configured a gate and watched it
+ * not gate. The other reasons exist so a log line can name one.
+ */
+export type ApprovalGateReason = "no_rule" | "no_approvers" | "already_approved" | "already_pending" | "unreachable";

package/dist/entities/work/ladder.d.ts

@@ -95,3 +95,12 @@ export interface StatusLadderProblem {
  * finished immediately, and a ladder without `done` makes finishing impossible.
  */
 export declare function validateStatuses(statuses: readonly WorkStatus[]): StatusLadderProblem[];
+/**
+ * Does entering this status need a signature?
+ *
+ * Here and not at the call site because two places ask it — the server gate and the screen that
+ * labels the button — and an unknown key must read as "no". An item pointing at a deleted status
+ * is already handled by {@link categoryOf}'s fallback; adding a gate on top of that would block a
+ * move nobody can unblock.
+ */
+export declare function statusRequiresApproval(statusKey: string, ladder: readonly WorkStatus[]): boolean;

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

@@ -44,6 +44,19 @@ export interface WorkStatus {
     order: number;
     /** Optional accent colour for the dots in the list and the admin screen. */
     color?: string;
+    /**
+     * Entering this status needs a colleague's sign-off.
+     *
+     * One flag and no second ladder: a campaign template already ships a status called "Review"
+     * that does nothing, and this is what turns it into a gate. *Which* colleague is not here —
+     * that is an approval rule in `apps/context`, keyed on `work_item` + `status:<key>`, so the
+     * same person can change who signs without touching a project's workflow.
+     *
+     * Only entering is guarded. Leaving a guarded status is not a second approval: the item is
+     * already past the gate, and asking twice is how a workflow becomes something people route
+     * around.
+     */
+    requiresApproval?: boolean;
 }
 /**
  * A resolution: *how* something ended, apart from where it sits.