@classytic/arc-approval 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,137 @@
+import { ApprovalChain, DecisionInput } from "@classytic/primitives/approval";
+import { PermissionCheck } from "@classytic/arc/permissions";
+import { ActionDefinition, RequestWithExtras } from "@classytic/arc/types";
+
+//#region src/index.d.ts
+/** Minimum surface every approval-bearing subject doc exposes (P7). */
+interface ApprovableDoc {
+  readonly _id: unknown;
+  readonly approvals?: ApprovalChain | null;
+}
+/**
+ * Structural repository port — satisfied by any kit repository. The preset
+ * only reads one doc and patches one doc; it takes no dependency on how.
+ * `organizationId` is absent when the preset runs with `tenancy: 'off'`
+ * (single-tenant hosts) — kits without a tenant plugin simply ignore it.
+ */
+interface ApprovalSubjectRepository<TDoc extends ApprovableDoc> {
+  getById(id: string, options: {
+    organizationId?: string;
+    throwOnNotFound: false;
+    lean: true;
+  }): Promise<TDoc | null>;
+  update(id: string, patch: Record<string, unknown>, options: {
+    organizationId?: string;
+    lean: true;
+  }): Promise<TDoc | null>;
+}
+/**
+ * Context the policy resolver matches against — host-extensible.
+ * `branchId` is the tenant dimension when the host is multi-tenant; optional
+ * so single-tenant hosts (`tenancy: 'off'`) can resolve policies without one.
+ * (Name kept for API stability with existing consumers; the generic rename
+ * ships with the preset's extraction to its own package.)
+ */
+interface ApprovalEvaluationContext {
+  readonly branchId?: string;
+  readonly amount?: number;
+  readonly category?: string;
+  readonly [extra: string]: unknown;
+}
+/** A chain resolved from an approval-policy matrix, with provenance. */
+interface ResolvedApprovalChain {
+  readonly chain: ApprovalChain;
+  readonly policyId: string | null;
+  readonly policyVersion: number | null;
+}
+interface PersistContext {
+  /** Absent under `tenancy: 'off'` (single-tenant hosts). */
+  readonly organizationId?: string;
+  readonly actorId: string | null;
+  readonly requestId: string | undefined;
+}
+interface WithApprovalChainConfig<TDoc extends ApprovableDoc, TSubject extends string = string> {
+  /** Stable subject identifier — must match the host's ApprovalPolicy.subjectType. */
+  readonly subjectType: TSubject;
+  readonly repository: ApprovalSubjectRepository<TDoc>;
+  /** Statuses in which `submit_for_approval` is accepted. Omit → any state. */
+  readonly allowedSubmitStatus?: readonly string[];
+  /** Reads the lifecycle status off the doc. Default reads `status`. */
+  readonly getStatus?: (doc: TDoc) => string | undefined;
+  readonly permissions: {
+    readonly submit: PermissionCheck;
+    readonly decide: PermissionCheck;
+  };
+  /**
+   * Delegation / identity-mapping hook for `decide`.
+   *
+   * By default a decision is recorded as the AUTHENTICATED actor:
+   * `approverId` defaults to the actor id, and a caller-supplied
+   * `approverId` that differs from it is rejected with 403
+   * `approval.approver_mismatch` — otherwise anyone holding the broad
+   * `decide` permission could spoof `{ approverId: 'boss' }` and decide as
+   * any approver listed in the chain.
+   *
+   * Provide this hook to authorize the mismatch explicitly: delegation
+   * ("decide on behalf of"), or hosts whose chain approver ids are NOT auth
+   * user ids (employee-profile ids, role ids) and need an identity mapping.
+   * Return `true` to allow `actorId` to decide as `approverId`.
+   */
+  readonly canActAsApprover?: (actorId: string | null, approverId: string, req: RequestWithExtras) => boolean | Promise<boolean>;
+  /**
+   * Tenancy mode. `'required'` (default) rejects requests without an org
+   * context with 400 `approval.no_organization_context` and threads
+   * `organizationId` into every repository call. `'off'` skips the org
+   * requirement entirely — for single-tenant hosts.
+   */
+  readonly tenancy?: "required" | "off";
+  /**
+   * Policy-provenance persistence. `'persist'` (default) writes
+   * `approvalPolicyId` / `approvalPolicyVersion` onto the subject patch;
+   * subjects whose schema omits those fields rely on the storage kit's
+   * unknown-field policy (Mongoose strict mode DROPS them; a kit that throws
+   * on unknown fields must use `'omit'`). `'omit'` never writes them.
+   */
+  readonly provenance?: "persist" | "omit";
+  /** Required for `useMatrix: true` — builds the policy evaluation context. */
+  readonly toEvaluationContext?: (doc: TDoc) => ApprovalEvaluationContext;
+  /** Pluggable matrix resolver (host policy). Absent → literal chains only. */
+  readonly resolveChain?: (subjectType: TSubject, evalCtx: ApprovalEvaluationContext) => Promise<ResolvedApprovalChain | null>;
+  /** Coarse-status side effects — return a doc to make it the response. */
+  readonly onSubmitted?: (doc: TDoc, ctx: PersistContext) => Promise<TDoc | void>;
+  readonly onApproved?: (doc: TDoc, ctx: PersistContext) => Promise<TDoc | void>;
+  readonly onRejected?: (doc: TDoc, input: DecisionInput, ctx: PersistContext) => Promise<TDoc | void>;
+}
+/**
+ * Build the `{ submit_for_approval, decide }` slice of a resource's
+ * `actions:` map. Spread into the resource's actions block:
+ *
+ * ```ts
+ * actions: {
+ *   ...withApprovalChain({ subjectType: 'budget', repository, permissions, … }),
+ *   post: { … },   // subject-specific verbs stay here
+ * }
+ * ```
+ */
+declare function withApprovalChain<TDoc extends ApprovableDoc, TSubject extends string = string>(config: WithApprovalChainConfig<TDoc, TSubject>): Record<"submit_for_approval" | "decide", ActionDefinition>;
+/** Standalone name for the `canActAsApprover` hook shape. */
+type CanActAsApprover = (actorId: string | null, approverId: string, req: RequestWithExtras) => boolean | Promise<boolean>;
+/**
+ * `canActAsApprover` policy: callers holding one of the given PLATFORM roles
+ * (`req.user.role`, string or array) may decide as any chain approver.
+ *
+ * The operational escape hatch for role-expanded matrix chains — upstreamed
+ * from be-prod's `platformAdminMayDelegate` shim. The audit trail still
+ * records the real actor (`PersistContext.actorId`); this only authorizes the
+ * decision to be RECORDED against the named approver:
+ *
+ * ```ts
+ * withApprovalChain({
+ *   // …
+ *   canActAsApprover: delegateForRoles(["admin", "superadmin"]),
+ * });
+ * ```
+ */
+declare function delegateForRoles(roles: readonly string[]): CanActAsApprover;
+//#endregion
+export { ApprovableDoc, ApprovalEvaluationContext, ApprovalSubjectRepository, CanActAsApprover, PersistContext, ResolvedApprovalChain, WithApprovalChainConfig, delegateForRoles, withApprovalChain };

package/dist/index.mjs

@@ -0,0 +1,249 @@
+import { getOrgId, getUserId } from "@classytic/arc/scope";
+import { NotFoundError, ValidationError, createDomainError } from "@classytic/arc/utils";
+import { ApprovalError, applyDecision, createChain, isApproved, isRejected } from "@classytic/primitives/approval";
+//#region src/index.ts
+const STATUS_BY_CODE = {
+	EMPTY_STEPS: 400,
+	DUPLICATE_STEP_ID: 400,
+	EMPTY_APPROVERS: 400,
+	DUPLICATE_APPROVER_ID: 400,
+	INVALID_QUORUM: 400,
+	UNKNOWN_STEP: 422,
+	UNAUTHORIZED_APPROVER: 403,
+	STEP_NOT_ACTIVE: 422,
+	STEP_ALREADY_DECIDED_BY_APPROVER: 409
+};
+function rethrowApprovalError(fn) {
+	try {
+		return fn();
+	} catch (err) {
+		if (err instanceof ApprovalError) {
+			const status = STATUS_BY_CODE[err.code] ?? 422;
+			throw createDomainError(`approval.${err.code.toLowerCase()}`, err.message, status);
+		}
+		throw err;
+	}
+}
+/**
+* Build the `{ submit_for_approval, decide }` slice of a resource's
+* `actions:` map. Spread into the resource's actions block:
+*
+* ```ts
+* actions: {
+*   ...withApprovalChain({ subjectType: 'budget', repository, permissions, … }),
+*   post: { … },   // subject-specific verbs stay here
+* }
+* ```
+*/
+function withApprovalChain(config) {
+	return {
+		submit_for_approval: {
+			handler: async (id, data, req) => submitHandler(config, id, data, req),
+			permissions: config.permissions.submit,
+			description: `Attach an approval chain to a ${config.subjectType}. Pass either a literal \`chain\` or \`useMatrix: true\` to resolve from policy.`,
+			schema: {
+				type: "object",
+				properties: {
+					useMatrix: {
+						type: "boolean",
+						description: "Resolve chain from ApprovalPolicy matrix."
+					},
+					chain: {
+						type: "object",
+						properties: {
+							order: {
+								type: "string",
+								enum: ["sequential", "parallel"]
+							},
+							steps: {
+								type: "array",
+								minItems: 1,
+								items: {
+									type: "object",
+									required: ["id", "approvers"],
+									properties: {
+										id: {
+											type: "string",
+											minLength: 1
+										},
+										name: { type: "string" },
+										requiredApprovals: {
+											type: "integer",
+											minimum: 1
+										},
+										approvers: {
+											type: "array",
+											minItems: 1,
+											items: {
+												type: "object",
+												required: ["id"],
+												properties: {
+													id: {
+														type: "string",
+														minLength: 1
+													},
+													name: { type: "string" },
+													role: { type: "string" }
+												}
+											}
+										}
+									}
+								}
+							}
+						}
+					}
+				},
+				additionalProperties: false
+			}
+		},
+		decide: {
+			handler: async (id, data, req) => decideHandler(config, id, data, req),
+			permissions: config.permissions.decide,
+			description: `Apply a single approver decision to the ${config.subjectType}'s active chain step.`,
+			schema: {
+				type: "object",
+				required: ["stepId", "decision"],
+				properties: {
+					stepId: {
+						type: "string",
+						minLength: 1
+					},
+					approverId: {
+						type: "string",
+						minLength: 1,
+						description: "Defaults to the authenticated actor. A different id requires the host's canActAsApprover hook to authorize it (403 otherwise)."
+					},
+					decision: {
+						type: "string",
+						enum: ["approved", "rejected"]
+					},
+					note: {
+						type: "string",
+						maxLength: 1e3
+					}
+				},
+				additionalProperties: false
+			}
+		}
+	};
+}
+async function submitHandler(config, id, body, req) {
+	const ctx = persistContext(req, config.tenancy ?? "required");
+	const doc = await loadSubject(config, id, ctx);
+	if (config.allowedSubmitStatus) {
+		const current = readStatus(config, doc);
+		if (!current || !config.allowedSubmitStatus.includes(current)) throw createDomainError("approval.invalid_status_for_submit", `Cannot submit ${config.subjectType} for approval in status '${current ?? "unknown"}'. Must be ${config.allowedSubmitStatus.join(" or ")}.`, 422);
+	}
+	const existingChain = doc.approvals;
+	if (existingChain && existingChain.status !== "rejected") throw createDomainError("approval.chain_already_attached", `Approval chain is already attached and ${existingChain.status}. Cancel or wait for the current workflow first.`, 409);
+	let chain;
+	let policyId = null;
+	let policyVersion = null;
+	if (body.useMatrix) {
+		if (!config.resolveChain || !config.toEvaluationContext) throw createDomainError("approval.matrix_unavailable", `Matrix-driven submit not configured for ${config.subjectType}. Provide a literal 'chain' instead.`, 422);
+		const resolved = await config.resolveChain(config.subjectType, config.toEvaluationContext(doc));
+		if (!resolved) throw createDomainError("approval.no_matching_policy", `No approval policy matched for ${config.subjectType}. Configure one or pass a literal 'chain'.`, 422);
+		chain = resolved.chain;
+		policyId = resolved.policyId;
+		policyVersion = resolved.policyVersion;
+	} else {
+		const literal = body.chain;
+		if (!literal || typeof literal !== "object") throw new ValidationError("Either `chain` (literal) or `useMatrix: true` is required.");
+		chain = rethrowApprovalError(() => createChain(literal));
+	}
+	const patch = { approvals: chain };
+	if (config.provenance !== "omit") {
+		if (policyId) patch.approvalPolicyId = policyId;
+		if (policyVersion !== null) patch.approvalPolicyVersion = policyVersion;
+	}
+	const updated = await config.repository.update(id, patch, {
+		...ctx.organizationId ? { organizationId: ctx.organizationId } : {},
+		lean: true
+	});
+	if (!updated) throw new NotFoundError(config.subjectType);
+	if (config.onSubmitted) {
+		const refined = await config.onSubmitted(updated, ctx);
+		if (refined) return refined;
+	}
+	return updated;
+}
+async function decideHandler(config, id, body, req) {
+	const ctx = persistContext(req, config.tenancy ?? "required");
+	if (!body.stepId || !body.decision) throw new ValidationError("stepId and decision are required.");
+	const approverId = body.approverId ?? ctx.actorId;
+	if (!approverId) throw new ValidationError("approverId is required when the request has no authenticated actor.");
+	if (approverId !== ctx.actorId) {
+		if (!(config.canActAsApprover ? await config.canActAsApprover(ctx.actorId, approverId, req) : false)) throw createDomainError("approval.approver_mismatch", `Cannot decide as approver '${approverId}': decisions are recorded as the authenticated actor unless canActAsApprover authorizes the delegation.`, 403);
+	}
+	const existing = (await loadSubject(config, id, ctx)).approvals;
+	if (!existing) throw createDomainError("approval.no_chain_attached", `No approval chain attached to this ${config.subjectType}. Submit one first.`, 422);
+	const decisionInput = {
+		stepId: body.stepId,
+		approverId,
+		decision: body.decision,
+		...body.note !== void 0 ? { note: body.note } : {}
+	};
+	const updatedChain = rethrowApprovalError(() => applyDecision(existing, decisionInput));
+	const updated = await config.repository.update(id, { approvals: updatedChain }, {
+		...ctx.organizationId ? { organizationId: ctx.organizationId } : {},
+		lean: true
+	});
+	if (!updated) throw new NotFoundError(config.subjectType);
+	if (isApproved(updatedChain) && !isApproved(existing) && config.onApproved) {
+		const refined = await config.onApproved(updated, ctx);
+		if (refined) return refined;
+	} else if (isRejected(updatedChain) && !isRejected(existing) && config.onRejected) {
+		const refined = await config.onRejected(updated, decisionInput, ctx);
+		if (refined) return refined;
+	}
+	return updated;
+}
+function persistContext(req, tenancy) {
+	const organizationId = getOrgId(req.scope) ?? "";
+	if (!organizationId && tenancy === "required") throw createDomainError("approval.no_organization_context", "Organization context is required for this action.", 400);
+	const actorId = getUserId(req.scope) ?? req.user?._id ?? req.user?.id ?? null;
+	return {
+		...organizationId ? { organizationId } : {},
+		actorId,
+		requestId: req.id
+	};
+}
+function readStatus(config, doc) {
+	if (config.getStatus) return config.getStatus(doc);
+	const maybe = doc.status;
+	return typeof maybe === "string" ? maybe : void 0;
+}
+async function loadSubject(config, id, ctx) {
+	const doc = await config.repository.getById(id, {
+		...ctx.organizationId ? { organizationId: ctx.organizationId } : {},
+		throwOnNotFound: false,
+		lean: true
+	});
+	if (!doc) throw new NotFoundError(`${config.subjectType} not found`);
+	return doc;
+}
+/**
+* `canActAsApprover` policy: callers holding one of the given PLATFORM roles
+* (`req.user.role`, string or array) may decide as any chain approver.
+*
+* The operational escape hatch for role-expanded matrix chains — upstreamed
+* from be-prod's `platformAdminMayDelegate` shim. The audit trail still
+* records the real actor (`PersistContext.actorId`); this only authorizes the
+* decision to be RECORDED against the named approver:
+*
+* ```ts
+* withApprovalChain({
+*   // …
+*   canActAsApprover: delegateForRoles(["admin", "superadmin"]),
+* });
+* ```
+*/
+function delegateForRoles(roles) {
+	const allowed = new Set(roles);
+	return (_actorId, _approverId, req) => {
+		const raw = req.user?.role;
+		return (Array.isArray(raw) ? raw : typeof raw === "string" ? [raw] : []).some((role) => typeof role === "string" && allowed.has(role));
+	};
+}
+//#endregion
+export { delegateForRoles, withApprovalChain };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@classytic/arc-approval",
+  "version": "0.1.0",
+  "description": "Approval-chain action preset for @classytic/arc — submit_for_approval + decide with policy-matrix resolution, actor-derived decision identity, and delegation hooks",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
+  },
+  "peerDependencies": {
+    "@classytic/arc": ">=2.20.0",
+    "@classytic/primitives": ">=0.9.0"
+  },
+  "keywords": [
+    "arc",
+    "fastify",
+    "approval",
+    "approval-chain",
+    "workflow",
+    "classytic"
+  ],
+  "license": "MIT",
+  "author": "Classytic",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/classytic/arc-ecosystem.git",
+    "directory": "packages/arc-approval"
+  }
+}