shutro-erp 0.3.6 → 0.3.7

package/dist/permissions/approvals.d.ts

@@ -33,6 +33,8 @@ export interface ApprovalRequestInfo {
     readonly approverRole: string;
     /** The people who decide (empty: the role's holders). */
     readonly approvers: readonly number[];
+    /** Backups who may decide it too. */
+    readonly backups: readonly number[];
     /** How many approvals it needs, and how many it has. */
     readonly required: number;
     readonly approvals: number;
@@ -40,6 +42,9 @@ export interface ApprovalRequestInfo {
     /** When it should be decided by, and the role it was escalated to once late. */
     readonly dueAt: string | null;
     readonly escalatedTo: string | null;
+    /** When its turn came (null: earlier levels still decide), and how its approvers were found. */
+    readonly startedAt: string | null;
+    readonly explanation: string | null;
     readonly state: 'pending' | 'approved' | 'rejected' | 'sent_back' | 'cancelled';
     readonly requestedBy: number | null;
     readonly decidedBy: number | null;
@@ -47,10 +52,30 @@ export interface ApprovalRequestInfo {
     readonly comment: string | null;
 }
 /**
- * Creates the approval requests of `records` (a recordset: `env`, `modelName`, `ids`) from the matching policies
- * and levels; earlier pending requests of the records are cancelled (a resubmission starts a new round). Returns
- * the number of requests created.
+ * Which of the last `limit` records of the policy's model each of its levels would have asked about (RFC 0025 step
+ * 4: the editor's preview), as the system; the policy's own condition first.
  */
+export declare function previewPolicy(su: Env, policyId: number, limit?: number): Promise<{
+    records: number;
+    levels: {
+        id: number;
+        name: string;
+        matched: number[];
+    }[];
+    covers: {
+        all: boolean;
+        companies: string[];
+    };
+}>;
+/** The matrix log of a record's requests, when `env` may read the record. */
+export declare function eventsOf(env: Env, model: string, id: number): Promise<{
+    id: number;
+    request: number;
+    at: string;
+    user: number | null;
+    kind: string;
+    note: string | null;
+}[]>;
 export declare function requestApprovals(records: unknown): Promise<number>;
 /** `none` (no level applied), `pending`, `approved` or `rejected`, for the record's current round. */
 export declare function approvalState(env: Env, model: string, id: number): Promise<'none' | 'pending' | 'approved' | 'rejected' | 'sent_back'>;
@@ -87,6 +112,30 @@ export declare function decide(env: Env, requestId: number, decision: Decision,
  * transition runs. @throws {HttpProblem} 404 when nothing is pending, 403 when they did not ask
  */
 export declare function withdraw(env: Env, model: string, id: number): Promise<number>;
+/**
+ * Reassigns a pending request (RFC 0027 §2.6), for Approvals managers: its approvers replaced by `users`, or `users`
+ * added to them (a role's holders named first); never the requester; a reason required; logged, audited and
+ * announced (`approval.reassigned`, with the people added). @throws {HttpProblem} 403 / 404 / 409 / 422
+ */
+export declare function reassign(env: Env, requestId: number, users: readonly number[], mode: 'replace' | 'add', reason: string): Promise<ApprovalRequestInfo>;
+/**
+ * Tells a current request's backups that it waits (RFC 0027 §2.6): for Approvals managers and the request's
+ * approvers; logged and announced (`approval.backups`). @throws {HttpProblem} 403 / 404 / 409
+ */
+export declare function notifyBackups(env: Env, requestId: number): Promise<number>;
+/** The fields of a level that decide its approvers: a change to one is synced to its waiting requests. */
+export declare const APPROVER_KEYS: readonly string[];
+/**
+ * Keeps waiting requests in step with their levels (RFC 0027 §2.6), as the system: each pending request of these
+ * levels gets its approvers found again — added to the ones it has, or replacing them, as its policy says (`mode`
+ * overrides it, for "Sync now") — logged when they change. Returns what changed, with the people added to requests
+ * whose turn it is (to tell, when the policy says so).
+ */
+export declare function syncLevels(su: Env, levelIds: readonly number[], mode?: 'add' | 'replace'): Promise<{
+    request: ApprovalRequestInfo;
+    added: number[];
+    notify: boolean;
+}[]>;
 /** A request as the Approvals app shows it (RFC 0025 §3.1): the record, who asked, since when, every level. */
 export interface ApprovalCard {
     readonly id: number;
@@ -141,6 +190,49 @@ export declare function approvalStats(env: Env): Promise<{
     decidedThisMonth: number;
     medianHours: number | null;
 }>;
+/** The periods of the matrix dashboard, in days (`all`: no limit). */
+declare const MATRIX_DAYS: {
+    readonly '7d': 7;
+    readonly '30d': 30;
+    readonly '3m': 91;
+    readonly '6m': 182;
+    readonly '1y': 365;
+    readonly all: null;
+};
+export type MatrixPeriod = keyof typeof MATRIX_DAYS;
+export declare const MATRIX_PERIODS: readonly MatrixPeriod[];
+/** One card of the matrix: a policy's requests the user decides, by state. */
+export interface MatrixCard {
+    readonly policy: number | null;
+    readonly title: string;
+    readonly waiting: number;
+    readonly approved: number;
+    readonly rejected: number;
+    readonly total: number;
+}
+/**
+ * The matrix dashboard (RFC 0027 §2.7): the requests of the period the user decides — directly (named, or holding
+ * the role) or delegated (as a backup or for someone away) — a card per policy with what waits, what was approved
+ * and rejected; for Approvals managers also the hours each level takes to decide and the bottlenecks (who has the
+ * most requests late).
+ */
+export declare function approvalMatrix(env: Env, period: MatrixPeriod, mode: 'direct' | 'delegated'): Promise<{
+    cards: MatrixCard[];
+    direct: number;
+    delegated: number;
+    levels: {
+        policy: string;
+        level: string;
+        decided: number;
+        averageHours: number;
+    }[] | null;
+    bottlenecks: {
+        user: number;
+        name: string;
+        late: number;
+        waiting: number;
+    }[] | null;
+}>;
 /** The people who may decide `request` now: its approvers (or its role's holders), the escalation role's once late,
  * and whoever they delegated to today; never the requester. */
 export declare function decidersOf(su: Env, request: ApprovalRequestInfo, today: string): Promise<number[]>;
@@ -156,7 +248,7 @@ export declare function sweepDeadlines(su: Env, now?: Date): Promise<{
     request: ApprovalRequestInfo;
 }[]>;
 /** One-time links deciding `request` from an email, one per person who may decide it now (7 days). */
-export declare function issueLinks(su: Env, request: ApprovalRequestInfo, today: string, newToken: () => string, digestOf: (token: string) => string): Promise<{
+export declare function issueLinks(su: Env, request: ApprovalRequestInfo, today: string, newToken: () => string, digestOf: (token: string) => string, only?: readonly number[]): Promise<{
     user: number;
     token: string;
 }[]>;
@@ -176,3 +268,4 @@ export declare function inbox(env: Env): Promise<ApprovalRequestInfo[]>;
 export declare function requestsOf(env: Env, model: string, id: number): Promise<ApprovalRequestInfo[]>;
 /** Installs the default policies the modules declare (`approvals` in manifests) that do not exist yet, by name. */
 export declare function installApprovalPolicies(env: Env, modules: readonly KoshModule[]): Promise<number>;
+export {};