cvx-kit 0.0.2 → 0.0.4

package/src/components/approvals/audit.ts

@@ -1,148 +0,0 @@
-import { AuditLog, type AuditEventInput } from 'convex-audit-log'
-import { v } from 'convex/values'
-
-import { components } from './_generated/api'
-import { mutation, query, type MutationCtx } from './_generated/server'
-import {
-	APPROVAL_AUDIT_RETENTION_CATEGORY,
-	MAX_APPROVAL_AUDIT_CLEANUP_BATCH_SIZE,
-	MAX_APPROVAL_AUDIT_RETENTION_DAYS,
-	MIN_APPROVAL_AUDIT_RETENTION_DAYS,
-} from './constants'
-
-export type ApprovalAuditTransition = Readonly<{
-	action: string
-	actorRef?: string
-	runId: string
-	resourceType: string
-	resourceRef: string
-	transition: string
-	severity?: AuditEventInput['severity']
-}>
-
-export type ApprovalAuditProjection = Readonly<{
-	action: string
-	actorRef?: string
-	correlationKey: string
-	transition: string
-}>
-
-export const approvalAudit = new AuditLog(components.auditLog, {
-	samplingEnabled: false,
-})
-
-export const history = query({
-	args: {
-		resourceType: v.string(),
-		resourceRef: v.string(),
-		limit: v.optional(v.number()),
-	},
-	returns: v.array(
-		v.object({
-			action: v.string(),
-			actorRef: v.optional(v.string()),
-			correlationKey: v.string(),
-			transition: v.string(),
-		}),
-	),
-	handler: async (ctx, input) => {
-		const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 100), 100))
-		const events = await approvalAudit.queryByResource(ctx, {
-			resourceType: input.resourceType,
-			resourceId: input.resourceRef,
-			limit,
-		})
-		const unique = new Map<string, ApprovalAuditProjection>()
-		for (const event of events) {
-			const projection = auditProjection(event)
-			if (projection) unique.set(projection.correlationKey, projection)
-		}
-		return [...unique.values()]
-	},
-})
-
-export const cleanup = mutation({
-	args: {
-		olderThanDays: v.number(),
-		batchSize: v.number(),
-	},
-	returns: v.number(),
-	handler: (ctx, input) => {
-		const olderThanDays = boundedInteger(
-			input.olderThanDays,
-			MIN_APPROVAL_AUDIT_RETENTION_DAYS,
-			MAX_APPROVAL_AUDIT_RETENTION_DAYS,
-			'olderThanDays',
-		)
-		const batchSize = boundedInteger(
-			input.batchSize,
-			1,
-			MAX_APPROVAL_AUDIT_CLEANUP_BATCH_SIZE,
-			'batchSize',
-		)
-		return approvalAudit.cleanup(ctx, {
-			olderThanDays,
-			batchSize,
-			retentionCategory: APPROVAL_AUDIT_RETENTION_CATEGORY,
-		})
-	},
-})
-
-export function approvalAuditEvent(
-	input: ApprovalAuditTransition,
-): AuditEventInput {
-	return {
-		action: input.action,
-		...(input.actorRef === undefined ? {} : { actorId: input.actorRef }),
-		resourceType: input.resourceType,
-		resourceId: input.resourceRef,
-		severity: input.severity ?? 'info',
-		tags: ['approvals'],
-		retentionCategory: APPROVAL_AUDIT_RETENTION_CATEGORY,
-		metadata: {
-			correlationKey: `${input.runId}:${input.transition}`,
-			runId: input.runId,
-			transition: input.transition,
-		},
-	}
-}
-
-export async function logApprovalTransition(
-	ctx: MutationCtx,
-	input: ApprovalAuditTransition,
-): Promise<void> {
-	await approvalAudit.log(ctx, approvalAuditEvent(input))
-}
-
-function boundedInteger(
-	value: number,
-	minimum: number,
-	maximum: number,
-	name: string,
-): number {
-	if (!Number.isInteger(value) || value < minimum || value > maximum)
-		throw new Error(
-			`${name} must be an integer between ${minimum} and ${maximum}`,
-		)
-	return value
-}
-
-function auditProjection(event: unknown): ApprovalAuditProjection | null {
-	if (!event || typeof event !== 'object') return null
-	const value = event as Record<string, unknown>
-	const metadata = value.metadata
-	if (!metadata || typeof metadata !== 'object') return null
-	const details = metadata as Record<string, unknown>
-	if (
-		typeof value.action !== 'string' ||
-		typeof details.correlationKey !== 'string' ||
-		typeof details.transition !== 'string'
-	)
-		return null
-	return {
-		action: value.action,
-		...(typeof value.actorId === 'string' ? { actorRef: value.actorId } : {}),
-		correlationKey: details.correlationKey,
-		transition: details.transition,
-	}
-}

package/src/components/approvals/client.ts

@@ -1,321 +0,0 @@
-import type {
-	FunctionArgs,
-	FunctionReference,
-	FunctionReturnType,
-	GenericDataModel,
-	GenericMutationCtx,
-	GenericQueryCtx,
-} from 'convex/server'
-
-import type { ComponentApi } from './_generated/component'
-import type { ApprovalDecision } from './constants'
-import type {
-	ApprovalActor,
-	ApprovalMetadata,
-	ApprovalWorkflowDescriptor,
-} from './validators'
-import {
-	compileApprovalDescriptor,
-	type ApprovalActionStep,
-	type ApprovalBranchStep,
-	type ApprovalDecisionStep,
-	type ApprovalDefinition,
-	type ApprovalMutationStep,
-	type ApprovalNotifyStep,
-	type ApprovalWorkflowStep,
-	type ApprovalCallbackInput,
-	type CreateApprovalHandle,
-} from './workflow_steps'
-
-export type ApprovalsOptions = Readonly<{
-	createHandle?: CreateApprovalHandle
-}>
-
-export type ApprovalStartInput = Readonly<{
-	scopeRef: string
-	resourceType: string
-	resourceRef: string
-	requester: ApprovalActor
-	metadata?: ApprovalMetadata
-}>
-
-export type ApprovalDecisionInput = Readonly<{
-	runId: string
-	decision: ApprovalDecision
-	reason?: string
-}>
-
-export type ApprovalEvidenceItem = Readonly<{
-	stepKey: string
-	actorRef: string
-	decision: ApprovalDecision
-	reason?: string
-	decidedAt: number
-}>
-
-export type ApprovalAuditHistoryInput = Readonly<{
-	resourceType: string
-	resourceRef: string
-	limit?: number
-}>
-
-export type ApprovalAuditCleanupInput = Readonly<{
-	olderThanDays: number
-	batchSize: number
-}>
-
-export type ApprovalStatus = FunctionReturnType<
-	ComponentApi['requests']['status']
->
-
-export class Approvals<Component extends ComponentApi = ComponentApi> {
-	private readonly component: Component
-	private readonly createHandle: CreateApprovalHandle | undefined
-
-	constructor(component: Component, options: ApprovalsOptions = {}) {
-		this.component = component
-		this.createHandle = options.createHandle
-	}
-
-	cleanupAudit<DataModel extends GenericDataModel>(
-		ctx: GenericMutationCtx<DataModel>,
-		input: ApprovalAuditCleanupInput,
-	): Promise<FunctionReturnType<Component['audit']['cleanup']>> {
-		return ctx.runMutation(this.component.audit.cleanup, input)
-	}
-
-	mutation(
-		key: string,
-		options: Readonly<{
-			handler: FunctionReference<
-				'mutation',
-				'internal',
-				ApprovalCallbackInput,
-				unknown
-			>
-			retry?: boolean
-		}>,
-	): ApprovalMutationStep {
-		return Object.freeze({
-			kind: 'mutation',
-			key,
-			handler: options.handler,
-			retry: options.retry ?? false,
-		})
-	}
-
-	action(
-		key: string,
-		options: Readonly<{
-			handler: FunctionReference<
-				'action',
-				'internal',
-				ApprovalCallbackInput,
-				unknown
-			>
-			retry?: boolean
-		}>,
-	): ApprovalActionStep {
-		return Object.freeze({
-			kind: 'action',
-			key,
-			handler: options.handler,
-			retry: options.retry ?? false,
-		})
-	}
-
-	notify(
-		key: string,
-		options: Readonly<{
-			handler: FunctionReference<
-				'action',
-				'internal',
-				ApprovalCallbackInput,
-				unknown
-			>
-			retry?: boolean
-		}>,
-	): ApprovalNotifyStep {
-		return Object.freeze({
-			kind: 'notify',
-			key,
-			handler: options.handler,
-			retry: options.retry ?? false,
-		})
-	}
-
-	decision(
-		key: string,
-		options: Readonly<{
-			decisions: readonly ApprovalDecision[]
-			quorum: Readonly<{ kind: 'count'; approvals: number }>
-			makerChecker?: boolean
-			expiresAfterMs?: number
-		}>,
-	): ApprovalDecisionStep {
-		return Object.freeze({
-			kind: 'decision',
-			key,
-			decisions: Object.freeze([...options.decisions]),
-			quorum: Object.freeze({ ...options.quorum }),
-			makerChecker: options.makerChecker ?? false,
-			...(options.expiresAfterMs === undefined
-				? {}
-				: { expiresAfterMs: options.expiresAfterMs }),
-		})
-	}
-
-	branch(
-		key: string,
-		options: Readonly<{
-			approvedStepKey: string
-			rejectedStepKey: string
-		}>,
-	): ApprovalBranchStep {
-		return Object.freeze({ kind: 'branch', key, ...options })
-	}
-
-	define(
-		input: Readonly<{
-			name: string
-			compatibilityKey?: string
-			steps: readonly ApprovalWorkflowStep[]
-		}>,
-	): ConfiguredApprovalWorkflow<Component> {
-		const definition = freezeDefinition({
-			name: input.name,
-			compatibilityKey: input.compatibilityKey ?? input.name,
-			steps: input.steps,
-		})
-		return new ConfiguredApprovalWorkflow(
-			this.component,
-			definition,
-			this.createHandle,
-		)
-	}
-}
-
-export class ConfiguredApprovalWorkflow<
-	Component extends ComponentApi = ComponentApi,
-> {
-	readonly name: string
-	readonly compatibilityKey: string
-	readonly steps: readonly ApprovalWorkflowStep[]
-
-	private readonly component: Component
-	private readonly definition: ApprovalDefinition
-	private readonly createHandle: CreateApprovalHandle | undefined
-
-	constructor(
-		component: Component,
-		definition: ApprovalDefinition,
-		createHandle?: CreateApprovalHandle,
-	) {
-		this.component = component
-		this.definition = definition
-		this.name = definition.name
-		this.compatibilityKey = definition.compatibilityKey
-		this.steps = definition.steps
-		this.createHandle = createHandle
-		Object.freeze(this)
-	}
-
-	descriptor(): Promise<Readonly<ApprovalWorkflowDescriptor>> {
-		return compileApprovalDescriptor(this.definition, this.createHandle)
-	}
-
-	async start<DataModel extends GenericDataModel>(
-		ctx: GenericMutationCtx<DataModel>,
-		input: ApprovalStartInput,
-	): Promise<FunctionReturnType<Component['requests']['start']>> {
-		return ctx.runMutation(this.component.requests.start, {
-			...input,
-			workflow: await this.descriptor(),
-		})
-	}
-
-	decide<DataModel extends GenericDataModel>(
-		ctx: GenericMutationCtx<DataModel>,
-		input: ApprovalDecisionInput,
-		actor: ApprovalActor,
-	): Promise<FunctionReturnType<Component['decisions']['decide']>> {
-		return ctx.runMutation(this.component.decisions.decide, {
-			...input,
-			actor,
-			compatibilityKey: this.compatibilityKey,
-		})
-	}
-
-	evidence<DataModel extends GenericDataModel>(
-		ctx: GenericQueryCtx<DataModel>,
-		runId: string,
-	): Promise<FunctionReturnType<Component['decisions']['list']>> {
-		return ctx.runQuery(this.component.decisions.list, { runId })
-	}
-
-	auditHistory<DataModel extends GenericDataModel>(
-		ctx: GenericQueryCtx<DataModel>,
-		input: ApprovalAuditHistoryInput,
-	): Promise<FunctionReturnType<Component['audit']['history']>> {
-		return ctx.runQuery(this.component.audit.history, input)
-	}
-
-	cancel<DataModel extends GenericDataModel>(
-		ctx: GenericMutationCtx<DataModel>,
-		runId: string,
-		actor: ApprovalActor,
-	): Promise<FunctionReturnType<Component['requests']['cancel']>> {
-		return ctx.runMutation(this.component.requests.cancel, {
-			runId,
-			actor,
-			compatibilityKey: this.compatibilityKey,
-		})
-	}
-
-	status<DataModel extends GenericDataModel>(
-		ctx: GenericQueryCtx<DataModel>,
-		runId: string,
-	): Promise<ApprovalStatus | null> {
-		return ctx.runQuery(this.component.requests.status, {
-			runId,
-			compatibilityKey: this.compatibilityKey,
-		})
-	}
-
-	list<DataModel extends GenericDataModel>(
-		ctx: GenericQueryCtx<DataModel>,
-		input: FunctionArgs<Component['requests']['list']>,
-	): Promise<FunctionReturnType<Component['requests']['list']>> {
-		return ctx.runQuery(this.component.requests.list, input)
-	}
-
-	restart<DataModel extends GenericDataModel>(
-		ctx: GenericMutationCtx<DataModel>,
-		runId: string,
-	): Promise<FunctionReturnType<Component['requests']['restart']>> {
-		return ctx.runMutation(this.component.requests.restart, {
-			runId,
-			compatibilityKey: this.compatibilityKey,
-		})
-	}
-}
-
-function freezeDefinition(definition: ApprovalDefinition): ApprovalDefinition {
-	return Object.freeze({
-		...definition,
-		steps: Object.freeze(
-			definition.steps.map((step) => {
-				if (step.kind === 'decision')
-					return Object.freeze({
-						...step,
-						decisions: Object.freeze([...step.decisions]),
-						quorum: Object.freeze({ ...step.quorum }),
-					})
-				return Object.freeze({ ...step })
-			}),
-		),
-	})
-}
-
-// Component definition as default export: `import approvals from "cvx-kit/components/approvals"` → app.use(approvals)
-export { default } from "./convex.config"

package/src/components/approvals/constants.ts

@@ -1,51 +0,0 @@
-export const APPROVAL_RUN_STATES = [
-	'pending',
-	'approved',
-	'rejected',
-	'expired',
-	'canceled',
-] as const
-
-export const APPROVAL_DECISIONS = ['approved', 'rejected'] as const
-
-export const APPROVAL_EXECUTION_STATES = [
-	'inProgress',
-	'completed',
-	'canceled',
-	'failed',
-] as const
-
-export const APPROVAL_STEP_KINDS = [
-	'mutation',
-	'action',
-	'notify',
-	'decision',
-	'branch',
-] as const
-
-export const APPROVAL_QUORUM_KINDS = ['count'] as const
-
-export const APPROVAL_CALLBACK_KINDS = ['mutation', 'action'] as const
-
-export const APPROVAL_DESCRIPTOR_SCHEMA_VERSION = 1 as const
-
-export const APPROVAL_AUDIT_RETENTION_CATEGORY = 'approval-protocol'
-export const MIN_APPROVAL_AUDIT_RETENTION_DAYS = 1
-export const MAX_APPROVAL_AUDIT_RETENTION_DAYS = 3_650
-export const MAX_APPROVAL_AUDIT_CLEANUP_BATCH_SIZE = 100
-
-export const MAX_APPROVAL_REFERENCE_LENGTH = 256
-export const MAX_APPROVAL_NAME_LENGTH = 96
-export const MAX_APPROVAL_REASON_LENGTH = 500
-export const MAX_APPROVAL_CAPABILITIES = 32
-export const MAX_APPROVAL_METADATA_ENTRIES = 32
-export const MAX_APPROVAL_METADATA_KEY_LENGTH = 64
-export const MAX_APPROVAL_METADATA_VALUE_LENGTH = 512
-export const MAX_APPROVAL_WORKFLOW_STEPS = 32
-export const MAX_APPROVAL_DECISIONS_PER_STEP = 8
-
-export type ApprovalRunState = (typeof APPROVAL_RUN_STATES)[number]
-export type ApprovalDecision = (typeof APPROVAL_DECISIONS)[number]
-export type ApprovalExecutionState = (typeof APPROVAL_EXECUTION_STATES)[number]
-export type ApprovalStepKind = (typeof APPROVAL_STEP_KINDS)[number]
-export type ApprovalCallbackKind = (typeof APPROVAL_CALLBACK_KINDS)[number]

package/src/components/approvals/convex.config.ts

@@ -1,10 +0,0 @@
-import workflow from '@convex-dev/workflow/convex.config'
-import auditLog from 'convex-audit-log/convex.config.js'
-import { defineComponent } from 'convex/server'
-
-const approvals = defineComponent('approvals')
-
-approvals.use(workflow, { name: 'workflow' })
-approvals.use(auditLog, { name: 'auditLog' })
-
-export default approvals