feat: Add approval and feature flag schemas with validation logic

Author: hotlong

packages/spec/src/automation/approval.zod.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
+
+/**
+ * Approval Step Approver Type
+ */
+export const ApproverType = z.enum([
+  'user',           // Specific user(s)
+  'role',           // Users with specific role
+  'manager',        // Submitter's manager
+  'field',          // User ID defined in a record field
+  'queue'           // Data ownership queue
+]);
+
+/**
+ * Approval Action Type
+ * Actions to execute on transition
+ */
+export const ApprovalActionType = z.enum([
+  'field_update',
+  'email_alert',
+  'webhook',
+  'script'
+]);
+
+/**
+ * definition of an action to perform
+ */
+export const ApprovalActionSchema = z.object({
+  type: ApprovalActionType,
+  name: z.string().describe('Action name'),
+  config: z.record(z.any()).describe('Action configuration')
+});
+
+/**
+ * Approval Process Step
+ */
+export const ApprovalStepSchema = z.object({
+  name: SnakeCaseIdentifierSchema.describe('Step machine name'),
+  label: z.string().describe('Step display label'),
+  description: z.string().optional(),
+  
+  /** Entry criteria for this step */
+  entryCriteria: z.string().optional().describe('Formula expression to enter this step'),
+  
+  /** Who can approve */
+  approvers: z.array(z.object({
+    type: ApproverType,
+    value: z.string().describe('User ID, Role Name, or Field Name')
+  })).min(1).describe('List of allowed approvers'),
+  
+  /** Approval Logic */
+  behavior: z.enum(['first_response', 'unanimous']).default('first_response')
+    .describe('How to handle multiple approvers'),
+    
+  /** Rejection behavior */
+  rejectionBehavior: z.enum(['reject_process', 'back_to_previous'])
+    .default('reject_process').describe('What happens if rejected'),
+
+  /** Actions */
+  onApprove: z.array(ApprovalActionSchema).optional().describe('Actions on step approval'),
+  onReject: z.array(ApprovalActionSchema).optional().describe('Actions on step rejection'),
+});
+
+/**
+ * Approval Process Protocol
+ * 
+ * Defines a complex review and approval cycle for a record.
+ * Manages state locking, notifications, and transition logic.
+ */
+export const ApprovalProcessSchema = z.object({
+  name: SnakeCaseIdentifierSchema.describe('Unique process name'),
+  label: z.string().describe('Human readable label'),
+  object: z.string().describe('Target Object Name'),
+  
+  active: z.boolean().default(false),
+  description: z.string().optional(),
+  
+  /** Entry Criteria for the entire process */
+  entryCriteria: z.string().optional().describe('Formula to allow submission'),
+  
+  /** Record Locking */
+  lockRecord: z.boolean().default(true).describe('Lock record from editing during approval'),
+  
+  /** Steps */
+  steps: z.array(ApprovalStepSchema).min(1).describe('Sequence of approval steps'),
+  
+  /** Global Actions */
+  onSubmit: z.array(ApprovalActionSchema).optional().describe('Actions on initial submission'),
+  onFinalApprove: z.array(ApprovalActionSchema).optional().describe('Actions on final approval'),
+  onFinalReject: z.array(ApprovalActionSchema).optional().describe('Actions on final rejection'),
+  onRecall: z.array(ApprovalActionSchema).optional().describe('Actions on recall'),
+});
+
+export const ApprovalProcess = Object.assign(ApprovalProcessSchema, {
+  create: <T extends z.input<typeof ApprovalProcessSchema>>(config: T) => config,
+});
+
+export type ApprovalProcess = z.infer<typeof ApprovalProcessSchema>;
+export type ApprovalStep = z.infer<typeof ApprovalStepSchema>;

packages/spec/src/automation/index.ts

@@ -2,3 +2,4 @@
 export * from './workflow.zod';
 export * from './flow.zod';
 export * from './webhook.zod';
+export * from './approval.zod';

packages/spec/src/system/feature.zod.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
+
+/**
+ * Feature Rollout Strategy
+ */
+export const FeatureStrategy = z.enum([
+  'boolean',        // Simple On/Off
+  'percentage',     // Gradual rollout (0-100%)
+  'user_list',      // Specific users
+  'group',          // Specific groups/roles
+  'custom'          // Custom constraint/script
+]);
+
+/**
+ * Feature Flag Protocol
+ * 
+ * Manages feature toggles and gradual rollouts.
+ * Used for CI/CD, A/B Testing, and Trunk-Based Development.
+ */
+export const FeatureFlagSchema = z.object({
+  name: SnakeCaseIdentifierSchema.describe('Feature key (snake_case)'),
+  label: z.string().optional().describe('Display label'),
+  description: z.string().optional(),
+  
+  /** Default state */
+  enabled: z.boolean().default(false).describe('Is globally enabled'),
+  
+  /** Rollout Strategy */
+  strategy: FeatureStrategy.default('boolean'),
+  
+  /** Strategy Configuration */
+  conditions: z.object({
+    percentage: z.number().min(0).max(100).optional(),
+    users: z.array(z.string()).optional(),
+    groups: z.array(z.string()).optional(),
+    expression: z.string().optional().describe('Custom formula expression')
+  }).optional(),
+  
+  /** Integration */
+  environment: z.enum(['dev', 'staging', 'prod', 'all']).default('all')
+    .describe('Environment validity'),
+    
+  /** Expiration */
+  expiresAt: z.string().datetime().optional().describe('Feature flag expiration date'),
+});
+
+export const FeatureFlag = Object.assign(FeatureFlagSchema, {
+  create: <T extends z.input<typeof FeatureFlagSchema>>(config: T) => config,
+});
+
+export type FeatureFlag = z.infer<typeof FeatureFlagSchema>;

packages/spec/src/system/index.ts

@@ -11,6 +11,7 @@ export * from './audit.zod';
 export * from './translation.zod';
 export * from './events.zod';
 export * from './job.zod';
+export * from './feature.zod';
 export * from './types';
 
 // Re-export Core System Definitions