cvx-kit 0.0.1

package/src/components/approvals/decisions.ts

@@ -0,0 +1,376 @@
+import { WorkflowManager, type WorkflowId } from '@convex-dev/workflow'
+import { zodToConvex } from 'convex-helpers/server/zod4'
+import { v } from 'convex/values'
+
+import { components, internal } from './_generated/api'
+import {
+	internalMutation,
+	internalQuery,
+	mutation,
+	query,
+	type QueryCtx,
+} from './_generated/server'
+import { logApprovalTransition } from './audit'
+import {
+	APPROVAL_DECISIONS,
+	APPROVAL_RUN_STATES,
+	type ApprovalRunState,
+} from './constants'
+import { canTransitionApprovalRun, classifyPendingRunAt } from './functions'
+import { approvalActor, approvalDecision, approvalReason } from './validators'
+import {
+	approvalDecisionEventName,
+	evaluateDecisionOutcome,
+} from './workflow_steps'
+
+export const decide = mutation({
+	args: {
+		runId: v.id('approvalRuns'),
+		decision: zodToConvex(approvalDecision),
+		reason: v.optional(zodToConvex(approvalReason)),
+		actor: zodToConvex(approvalActor),
+		compatibilityKey: v.string(),
+	},
+	returns: v.object({
+		state: v.union(
+			v.literal(APPROVAL_RUN_STATES[0]),
+			v.literal(APPROVAL_RUN_STATES[1]),
+			v.literal(APPROVAL_RUN_STATES[2]),
+			v.literal(APPROVAL_RUN_STATES[3]),
+			v.literal(APPROVAL_RUN_STATES[4]),
+		),
+	}),
+	handler: async (ctx, input) => {
+		const run = await ctx.db.get(input.runId)
+		if (!run) throw new Error('Approval request not found')
+		assertCompatible(run.workflow.compatibilityKey, input.compatibilityKey)
+		const step = run.workflow.steps.find(
+			(candidate) =>
+				candidate.kind === 'decision' && candidate.key === run.currentStepKey,
+		)
+		if (!step || step.kind !== 'decision')
+			throw new Error('Approval request is not waiting for a decision')
+
+		const prior = await ctx.db
+			.query('approvalDecisions')
+			.withIndex('by_runId_and_stepKey_and_actor_actorRef', (query) =>
+				query
+					.eq('runId', run._id)
+					.eq('stepKey', step.key)
+					.eq('actor.actorRef', input.actor.actorRef),
+			)
+			.unique()
+		if (prior) {
+			if (prior.decision !== input.decision)
+				throw new Error('Actor already submitted a contradictory decision')
+			return {
+				state: run.state as 'pending' | 'approved' | 'rejected' | 'expired',
+			}
+		}
+		if (run.state !== 'pending')
+			throw new Error(`Approval request is already ${run.state}`)
+		if (
+			run.expiresAt !== undefined &&
+			classifyPendingRunAt(Date.now(), run.expiresAt) === 'expired'
+		)
+			return claimExpiry(ctx, run, step.key)
+		if (!step.decisions.includes(input.decision))
+			throw new Error('Decision is not allowed by this workflow step')
+		if (step.makerChecker && input.actor.actorRef === run.requester.actorRef)
+			throw new Error('Requester cannot decide this approval step')
+
+		const decidedAt = Date.now()
+		await ctx.db.insert('approvalDecisions', {
+			runId: run._id,
+			stepKey: step.key,
+			actor: input.actor,
+			decision: input.decision,
+			...(input.reason === undefined ? {} : { reason: input.reason }),
+			decidedAt,
+		})
+		const evidence = await ctx.db
+			.query('approvalDecisions')
+			.withIndex('by_runId_and_stepKey_and_decidedAt', (query) =>
+				query.eq('runId', run._id).eq('stepKey', step.key),
+			)
+			.collect()
+		const outcome = evaluateDecisionOutcome(
+			evidence.map((item) => ({
+				actorRef: item.actor.actorRef,
+				decision: item.decision,
+			})),
+			step.quorum.approvals,
+		)
+		await logApprovalTransition(ctx, {
+			action: `approval.decision.${input.decision}`,
+			actorRef: input.actor.actorRef,
+			runId: run._id,
+			resourceType: run.resourceType,
+			resourceRef: run.resourceRef,
+			transition: `${step.key}:${input.actor.actorRef}:${input.decision}`,
+		})
+		if (!outcome) return { state: 'pending' as const }
+		const terminal = isTerminalDecision(run, step.key, outcome)
+		await finishDecision(ctx, run, step.key, outcome, terminal, {
+			actorRef: input.actor.actorRef,
+			decision: input.decision,
+			...(input.reason === undefined ? {} : { reason: input.reason }),
+			decidedAt,
+		})
+		return terminal ? { state: outcome } : { state: 'pending' as const }
+	},
+})
+
+export const list = query({
+	args: { runId: v.id('approvalRuns') },
+	returns: v.array(
+		v.object({
+			stepKey: v.string(),
+			actorRef: v.string(),
+			decision: zodToConvex(approvalDecision),
+			reason: v.optional(zodToConvex(approvalReason)),
+			decidedAt: v.number(),
+		}),
+	),
+	handler: (ctx, input) => listDecisionEvidence(ctx, input.runId),
+})
+
+export const listForWorkflow = internalQuery({
+	args: { runId: v.id('approvalRuns'), stepKey: v.string() },
+	returns: v.array(
+		v.object({
+			stepKey: v.string(),
+			actorRef: v.string(),
+			decision: zodToConvex(approvalDecision),
+			reason: v.optional(zodToConvex(approvalReason)),
+			decidedAt: v.number(),
+		}),
+	),
+	handler: (ctx, input) =>
+		listDecisionEvidenceForStep(ctx, input.runId, input.stepKey),
+})
+
+export const enter = internalMutation({
+	args: {
+		runId: v.id('approvalRuns'),
+		stepKey: v.string(),
+		workflowId: v.string(),
+		expiresAfterMs: v.optional(v.number()),
+	},
+	returns: v.object({
+		state: v.union(
+			v.literal(APPROVAL_RUN_STATES[0]),
+			v.literal(APPROVAL_RUN_STATES[1]),
+			v.literal(APPROVAL_RUN_STATES[2]),
+			v.literal(APPROVAL_RUN_STATES[3]),
+			v.literal(APPROVAL_RUN_STATES[4]),
+		),
+		expiresAt: v.optional(v.number()),
+	}),
+	handler: async (ctx, input) => {
+		const run = await ctx.db.get(input.runId)
+		if (!run) throw new Error('Approval request not found')
+		if (run.workflowId !== input.workflowId)
+			throw new Error('Approval workflow linkage is incomplete')
+		if (run.state !== 'pending')
+			return {
+				state: run.state as ApprovalRunState,
+				expiresAt: run.expiresAt,
+			}
+		const configuredExpiresAt = Number(run.metadata?.approvalExpiresAt)
+		const expiresAt = Number.isFinite(configuredExpiresAt)
+			? configuredExpiresAt
+			: input.expiresAfterMs === undefined
+				? undefined
+				: Date.now() + input.expiresAfterMs
+		await ctx.db.patch(run._id, {
+			currentStepKey: input.stepKey,
+			expiresAt,
+			updatedAt: Date.now(),
+		})
+		await logApprovalTransition(ctx, {
+			action: 'approval.waiting',
+			runId: run._id,
+			resourceType: run.resourceType,
+			resourceRef: run.resourceRef,
+			transition: `${input.stepKey}:waiting`,
+		})
+		if (expiresAt !== undefined)
+			await ctx.scheduler.runAt(expiresAt, internal.decisions.expire, {
+				runId: run._id,
+				stepKey: input.stepKey,
+			})
+		return {
+			state: 'pending' as const,
+			...(expiresAt === undefined ? {} : { expiresAt }),
+		}
+	},
+})
+
+export const expire = internalMutation({
+	args: { runId: v.id('approvalRuns'), stepKey: v.string() },
+	returns: v.object({
+		state: v.union(
+			v.literal('missing'),
+			v.literal(APPROVAL_RUN_STATES[0]),
+			v.literal(APPROVAL_RUN_STATES[1]),
+			v.literal(APPROVAL_RUN_STATES[2]),
+			v.literal(APPROVAL_RUN_STATES[3]),
+			v.literal(APPROVAL_RUN_STATES[4]),
+		),
+	}),
+	handler: async (ctx, input) => {
+		const run = await ctx.db.get(input.runId)
+		if (!run) return { state: 'missing' as const }
+		if (
+			run.state !== 'pending' ||
+			run.currentStepKey !== input.stepKey ||
+			run.expiresAt === undefined ||
+			classifyPendingRunAt(Date.now(), run.expiresAt) === 'pending'
+		)
+			return { state: run.state as ApprovalRunState }
+		return claimExpiry(ctx, run, input.stepKey)
+	},
+})
+
+const approvalWorkflow = new WorkflowManager(components.workflow)
+
+async function claimExpiry(
+	ctx: import('./_generated/server').MutationCtx,
+	run: import('./_generated/dataModel').Doc<'approvalRuns'>,
+	stepKey: string,
+): Promise<{ state: 'expired' }> {
+	if (!canTransitionApprovalRun(run.state, 'expired'))
+		throw new Error(`Approval request cannot transition from ${run.state}`)
+	const now = Date.now()
+	await ctx.db.patch(run._id, {
+		state: 'expired',
+		expiresAt: undefined,
+		updatedAt: now,
+		terminalAt: now,
+	})
+	await logApprovalTransition(ctx, {
+		action: 'approval.expired',
+		runId: run._id,
+		resourceType: run.resourceType,
+		resourceRef: run.resourceRef,
+		transition: `${stepKey}:expired`,
+	})
+	if (!run.workflowId) throw new Error('Approval workflow is not linked')
+	await approvalWorkflow.sendEvent(ctx, {
+		workflowId: run.workflowId as WorkflowId,
+		name: approvalDecisionEventName(run._id, stepKey),
+		validator: v.object({ outcome: v.literal(APPROVAL_RUN_STATES[3]) }),
+		value: { outcome: 'expired' },
+	})
+	return { state: 'expired' }
+}
+
+async function finishDecision(
+	ctx: import('./_generated/server').MutationCtx,
+	run: import('./_generated/dataModel').Doc<'approvalRuns'>,
+	stepKey: string,
+	outcome: 'approved' | 'rejected',
+	terminal: boolean,
+	terminalEvidence: {
+		actorRef: string
+		decision: 'approved' | 'rejected'
+		reason?: string
+		decidedAt: number
+	},
+): Promise<void> {
+	if (terminal) {
+		if (!canTransitionApprovalRun(run.state, outcome))
+			throw new Error(`Approval request cannot transition from ${run.state}`)
+		const now = Date.now()
+		await ctx.db.patch(run._id, {
+			state: outcome,
+			expiresAt: undefined,
+			updatedAt: now,
+			terminalAt: now,
+		})
+		await logApprovalTransition(ctx, {
+			action: `approval.${outcome}`,
+			runId: run._id,
+			resourceType: run.resourceType,
+			resourceRef: run.resourceRef,
+			transition: `${stepKey}:terminal:${outcome}`,
+		})
+	}
+	if (!run.workflowId) throw new Error('Approval workflow is not linked')
+	await approvalWorkflow.sendEvent(ctx, {
+		workflowId: run.workflowId as WorkflowId,
+		name: approvalDecisionEventName(run._id, stepKey),
+		validator: v.object({
+			outcome: v.union(
+				v.literal(APPROVAL_DECISIONS[0]),
+				v.literal(APPROVAL_DECISIONS[1]),
+			),
+			terminalEvidence: v.object({
+				actorRef: v.string(),
+				decision: zodToConvex(approvalDecision),
+				reason: v.optional(zodToConvex(approvalReason)),
+				decidedAt: v.number(),
+			}),
+		}),
+		value: { outcome, terminalEvidence },
+	})
+}
+
+function assertCompatible(actual: string, expected: string): void {
+	if (actual !== expected)
+		throw new Error(
+			`Approval workflow compatibility mismatch: expected ${expected}, received ${actual}`,
+		)
+}
+
+async function listDecisionEvidence(
+	ctx: QueryCtx,
+	runId: import('./_generated/dataModel').Id<'approvalRuns'>,
+) {
+	const decisions = await ctx.db
+		.query('approvalDecisions')
+		.withIndex('by_runId_and_decidedAt', (query) => query.eq('runId', runId))
+		.collect()
+	return decisions.map((decision) => ({
+		stepKey: decision.stepKey,
+		actorRef: decision.actor.actorRef,
+		decision: decision.decision,
+		...(decision.reason === undefined ? {} : { reason: decision.reason }),
+		decidedAt: decision.decidedAt,
+	}))
+}
+
+async function listDecisionEvidenceForStep(
+	ctx: QueryCtx,
+	runId: import('./_generated/dataModel').Id<'approvalRuns'>,
+	stepKey: string,
+) {
+	const decisions = await ctx.db
+		.query('approvalDecisions')
+		.withIndex('by_runId_and_stepKey_and_decidedAt', (query) =>
+			query.eq('runId', runId).eq('stepKey', stepKey),
+		)
+		.collect()
+	return decisions.map((decision) => ({
+		stepKey: decision.stepKey,
+		actorRef: decision.actor.actorRef,
+		decision: decision.decision,
+		...(decision.reason === undefined ? {} : { reason: decision.reason }),
+		decidedAt: decision.decidedAt,
+	}))
+}
+
+function isTerminalDecision(
+	run: import('./_generated/dataModel').Doc<'approvalRuns'>,
+	stepKey: string,
+	outcome: 'approved' | 'rejected',
+): boolean {
+	if (outcome === 'rejected') return true
+	const currentIndex = run.workflow.steps.findIndex(
+		(step) => step.kind === 'decision' && step.key === stepKey,
+	)
+	return !run.workflow.steps
+		.slice(currentIndex + 1)
+		.some((step) => step.kind === 'decision')
+}

package/src/components/approvals/functions.ts

@@ -0,0 +1,27 @@
+import type { ApprovalRunState } from './constants'
+
+export function canTransitionApprovalRun(
+	from: ApprovalRunState,
+	to: ApprovalRunState,
+): boolean {
+	return (
+		LEGAL_APPROVAL_RUN_TRANSITIONS[from] as readonly ApprovalRunState[]
+	).includes(to)
+}
+
+export function classifyPendingRunAt(
+	now: number,
+	expiresAt: number,
+): 'pending' | 'expired' {
+	return now >= expiresAt ? 'expired' : 'pending'
+}
+
+const LEGAL_APPROVAL_RUN_TRANSITIONS = {
+	pending: ['approved', 'rejected', 'expired', 'canceled'],
+	approved: [],
+	rejected: [],
+	expired: [],
+	canceled: [],
+} as const satisfies Readonly<
+	Record<ApprovalRunState, readonly ApprovalRunState[]>
+>

package/src/components/approvals/requests.ts

@@ -0,0 +1,240 @@
+import { WorkflowManager, type WorkflowId } from '@convex-dev/workflow'
+import { zodToConvex } from 'convex-helpers/server/zod4'
+import {
+	paginationOptsValidator,
+	paginationResultValidator,
+} from 'convex/server'
+import { v } from 'convex/values'
+
+import { components, internal } from './_generated/api'
+import {
+	internalMutation,
+	internalQuery,
+	mutation,
+	query,
+} from './_generated/server'
+import { logApprovalTransition } from './audit'
+import { APPROVAL_EXECUTION_STATES, APPROVAL_RUN_STATES } from './constants'
+import { canTransitionApprovalRun } from './functions'
+import {
+	approvalActor,
+	approvalMetadata,
+	approvalName,
+	approvalReference,
+	approvalRunDocument,
+	approvalRunState,
+	approvalWorkflowDescriptor,
+} from './validators'
+
+export const start = mutation({
+	args: {
+		scopeRef: zodToConvex(approvalReference),
+		resourceType: zodToConvex(approvalReference),
+		resourceRef: zodToConvex(approvalReference),
+		requester: zodToConvex(approvalActor),
+		metadata: v.optional(zodToConvex(approvalMetadata)),
+		workflow: zodToConvex(approvalWorkflowDescriptor),
+	},
+	returns: v.object({ runId: v.id('approvalRuns') }),
+	handler: async (ctx, input) => {
+		const now = Date.now()
+		const runId = await ctx.db.insert('approvalRuns', {
+			...input,
+			state: 'pending',
+			createdAt: now,
+			updatedAt: now,
+		})
+		const workflowId: WorkflowId = await approvalWorkflow.start(
+			ctx,
+			internal.workflow.run,
+			{ runId },
+			{ startAsync: true },
+		)
+		await ctx.db.patch(runId, { workflowId, updatedAt: Date.now() })
+		await logApprovalTransition(ctx, {
+			action: 'approval.requested',
+			actorRef: input.requester.actorRef,
+			runId,
+			resourceType: input.resourceType,
+			resourceRef: input.resourceRef,
+			transition: 'requested',
+		})
+		return { runId }
+	},
+})
+
+export const cancel = mutation({
+	args: {
+		runId: v.id('approvalRuns'),
+		actor: zodToConvex(approvalActor),
+		compatibilityKey: v.string(),
+	},
+	returns: v.object({ state: v.literal(APPROVAL_RUN_STATES[4]) }),
+	handler: async (ctx, input) => {
+		const run = await ctx.db.get(input.runId)
+		if (!run) throw new Error('Approval request not found')
+		assertCompatible(run.workflow.compatibilityKey, input.compatibilityKey)
+		if (run.state !== 'pending') {
+			if (run.state === 'canceled') return { state: 'canceled' as const }
+			throw new Error(`Approval request is already ${run.state}`)
+		}
+		if (!run.workflowId) throw new Error('Approval workflow is not linked')
+		await approvalWorkflow.cancel(ctx, run.workflowId as WorkflowId)
+		if (!canTransitionApprovalRun(run.state, 'canceled'))
+			throw new Error(`Approval request cannot transition from ${run.state}`)
+		const now = Date.now()
+		await ctx.db.patch(run._id, {
+			state: 'canceled',
+			expiresAt: undefined,
+			updatedAt: now,
+			terminalAt: now,
+		})
+		await logApprovalTransition(ctx, {
+			action: 'approval.canceled',
+			actorRef: input.actor.actorRef,
+			runId: run._id,
+			resourceType: run.resourceType,
+			resourceRef: run.resourceRef,
+			transition: 'canceled',
+		})
+		return { state: 'canceled' as const }
+	},
+})
+
+export const restart = mutation({
+	args: { runId: v.id('approvalRuns'), compatibilityKey: v.string() },
+	returns: v.null(),
+	handler: async (ctx, input) => {
+		const run = await ctx.db.get(input.runId)
+		if (!run) throw new Error('Approval request not found')
+		assertCompatible(run.workflow.compatibilityKey, input.compatibilityKey)
+		if (!run.workflowId) throw new Error('Approval workflow is not linked')
+		if (!run.executionFailedStepKey)
+			throw new Error('Approval workflow has no failed step to restart')
+		await approvalWorkflow.restart(ctx, run.workflowId as WorkflowId, {
+			from: run.executionFailedStepKey,
+			startAsync: true,
+		})
+		return null
+	},
+})
+
+export const status = query({
+	args: { runId: v.id('approvalRuns'), compatibilityKey: v.string() },
+	returns: v.union(v.null(), approvalStatusValidator()),
+	handler: async (ctx, input) => {
+		const run = await ctx.db.get(input.runId)
+		if (!run) return null
+		assertCompatible(run.workflow.compatibilityKey, input.compatibilityKey)
+		const workflowStatus = run.workflowId
+			? await approvalWorkflow.status(ctx, run.workflowId as WorkflowId)
+			: null
+		const execution = normalizeWorkflowStatus(workflowStatus)
+		return { run, execution }
+	},
+})
+
+export const list = query({
+	args: {
+		scopeRef: zodToConvex(approvalReference),
+		state: v.optional(zodToConvex(approvalRunState)),
+		paginationOpts: paginationOptsValidator,
+	},
+	returns: paginationResultValidator(approvalRunValidator()),
+	handler: (ctx, input) =>
+		ctx.db
+			.query('approvalRuns')
+			.withIndex('by_scopeRef_and_state', (query) =>
+				input.state === undefined
+					? query.eq('scopeRef', input.scopeRef)
+					: query.eq('scopeRef', input.scopeRef).eq('state', input.state),
+			)
+			.order('desc')
+			.paginate(input.paginationOpts),
+})
+
+export const getForWorkflow = internalQuery({
+	args: { runId: v.id('approvalRuns') },
+	returns: v.union(v.null(), approvalRunValidator()),
+	handler: (ctx, input) => ctx.db.get(input.runId),
+})
+
+export const recordExecutionTerminal = internalMutation({
+	args: {
+		runId: v.id('approvalRuns'),
+		outcome: v.union(
+			v.literal(APPROVAL_EXECUTION_STATES[1]),
+			v.literal(APPROVAL_EXECUTION_STATES[3]),
+		),
+		failedStepKey: v.optional(zodToConvex(approvalName)),
+	},
+	returns: v.null(),
+	handler: async (ctx, input) => {
+		const run = await ctx.db.get(input.runId)
+		if (!run) throw new Error('Approval request not found')
+		await ctx.db.patch(run._id, {
+			executionFailedStepKey:
+				input.outcome === 'failed' ? input.failedStepKey : undefined,
+			updatedAt: Date.now(),
+		})
+		await logApprovalTransition(ctx, {
+			action: `approval.execution.${input.outcome}`,
+			runId: run._id,
+			resourceType: run.resourceType,
+			resourceRef: run.resourceRef,
+			transition: `execution:${input.outcome}`,
+			severity: input.outcome === 'failed' ? 'error' : 'info',
+		})
+		return null
+	},
+})
+
+const approvalWorkflow = new WorkflowManager(components.workflow)
+
+function normalizeWorkflowStatus(
+	status: Awaited<ReturnType<typeof approvalWorkflow.status>> | null,
+) {
+	if (!status) return null
+	switch (status.type) {
+		case 'failed':
+			return { type: 'failed' as const, error: status.error }
+		case 'inProgress':
+		case 'completed':
+		case 'canceled':
+			return { type: status.type }
+	}
+}
+
+function approvalRunValidator() {
+	return v.object({
+		_id: v.id('approvalRuns'),
+		_creationTime: v.number(),
+		...zodToConvex(approvalRunDocument).fields,
+	})
+}
+
+function workflowStatusValidator() {
+	return v.union(
+		v.object({ type: v.literal(APPROVAL_EXECUTION_STATES[0]) }),
+		v.object({ type: v.literal(APPROVAL_EXECUTION_STATES[1]) }),
+		v.object({ type: v.literal(APPROVAL_EXECUTION_STATES[2]) }),
+		v.object({
+			type: v.literal(APPROVAL_EXECUTION_STATES[3]),
+			error: v.string(),
+		}),
+	)
+}
+
+function approvalStatusValidator() {
+	return v.object({
+		run: approvalRunValidator(),
+		execution: v.union(v.null(), workflowStatusValidator()),
+	})
+}
+
+function assertCompatible(actual: string, expected: string): void {
+	if (actual !== expected)
+		throw new Error(
+			`Approval workflow compatibility mismatch: expected ${expected}, received ${actual}`,
+		)
+}

package/src/components/approvals/schema.ts

@@ -0,0 +1,23 @@
+import { zodToConvex } from 'convex-helpers/server/zod4'
+import { defineSchema, defineTable } from 'convex/server'
+
+import { approvalDecisionDocument, approvalRunDocument } from './validators'
+
+export default defineSchema({
+	approvalRuns: defineTable(zodToConvex(approvalRunDocument))
+		.index('by_resourceType_and_resourceRef', ['resourceType', 'resourceRef'])
+		.index('by_scopeRef_and_state', ['scopeRef', 'state'])
+		.index('by_state_and_expiresAt', ['state', 'expiresAt']),
+	approvalDecisions: defineTable(zodToConvex(approvalDecisionDocument))
+		.index('by_runId_and_stepKey_and_actor_actorRef', [
+			'runId',
+			'stepKey',
+			'actor.actorRef',
+		])
+		.index('by_runId_and_stepKey_and_decidedAt', [
+			'runId',
+			'stepKey',
+			'decidedAt',
+		])
+		.index('by_runId_and_decidedAt', ['runId', 'decidedAt']),
+})