feat: improve Automation API type safety, add triggerFlow schemas, enhance tests

- Fix IAutomationService contract: replace `unknown` return types with `FlowParsed` and `ExecutionLog`
- Add TriggerFlowRequestSchema/TriggerFlowResponseSchema with input/output for triggerFlow contract
- Add typed contract tests for getFlow, listRuns, getRun, toggleFlow
- Add triggerFlow API schema tests
- Add contract completeness test (all endpoints have input/output)
- Update ROADMAP to reflect type safety improvements

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

ROADMAP.md

@@ -147,14 +147,14 @@ Multi-stage triggers, action pipelines, execution logs, and cron scheduling stan
 | Action pipeline (webhook, email, CRUD, notification) | ✅ | `automation/flow.zod.ts` (HTTP, CRUD, script nodes) |
 | State machine & approval processes | ✅ | `automation/state-machine.zod.ts`, `automation/workflow.zod.ts` |
 | Retry policies with exponential backoff | ✅ | `automation/webhook.zod.ts` |
-| `IAutomationService` contract | ✅ | `contracts/automation-service.ts` (getFlow, toggleFlow, listRuns, getRun) |
+| `IAutomationService` contract | ✅ | `contracts/automation-service.ts` (typed: `FlowParsed`, `ExecutionLog`) |
 | `service-automation` DAG engine (MVP) | ✅ | `@objectstack/service-automation` (42 tests) |
 | Execution log/history storage protocol | ✅ | `automation/execution.zod.ts` → `ExecutionLogSchema`, `ExecutionStepLogSchema` |
 | Execution error tracking & diagnostics | ✅ | `automation/execution.zod.ts` → `ExecutionErrorSchema`, `ExecutionErrorSeverity` |
 | Conflict resolution for concurrent executions | ✅ | `automation/execution.zod.ts` → `ConcurrencyPolicySchema` |
 | Checkpointing/resume for interrupted flows | ✅ | `automation/execution.zod.ts` → `CheckpointSchema` |
 | Scheduled execution persistence (next-run, pause/resume) | ✅ | `automation/execution.zod.ts` → `ScheduleStateSchema` |
-| Automation API protocol (REST CRUD schemas) | ✅ | `api/automation-api.zod.ts` → 9 endpoints, `AutomationApiContracts` |
+| Automation API protocol (REST CRUD schemas) | ✅ | `api/automation-api.zod.ts` → 9 endpoints, all with `input`/`output` schemas |
 | Automation HTTP route handler (9 routes) | ✅ | `runtime/http-dispatcher.ts` → `handleAutomation()` CRUD + toggle + runs |
 | Client SDK `automation` namespace (10 methods) | ✅ | `client/src/index.ts` → `list`, `get`, `create`, `update`, `delete`, `toggle`, `runs.*` |
 
@@ -717,7 +717,7 @@ Final polish and advanced features.
 | 16 | Search Service | `ISearchService` | ❌ | `@objectstack/service-search` (planned) | Spec only |
 | 17 | Notification Service | `INotificationService` | ❌ | `@objectstack/service-notification` (planned) | Spec only |
 | 18 | AI Service | `IAIService` | ❌ | `@objectstack/service-ai` (planned) | Spec only |
-| 19 | Automation Service | `IAutomationService` | ✅ | `@objectstack/service-automation` | DAG engine + HTTP API CRUD + Client SDK (42 tests) |
+| 19 | Automation Service | `IAutomationService` | ✅ | `@objectstack/service-automation` | DAG engine + HTTP API CRUD + Client SDK + typed returns (42 tests) |
 | 20 | Workflow Service | `IWorkflowService` | ❌ | `@objectstack/service-workflow` (planned) | Spec only |
 | 21 | GraphQL Service | `IGraphQLService` | ❌ | `@objectstack/service-graphql` (planned) | Spec only |
 | 22 | i18n Service | `II18nService` | ✅ | `@objectstack/service-i18n` | File-based locale loading |

packages/spec/src/api/automation-api.test.ts

@@ -13,6 +13,8 @@ import {
   UpdateFlowResponseSchema,
   DeleteFlowRequestSchema,
   DeleteFlowResponseSchema,
+  TriggerFlowRequestSchema,
+  TriggerFlowResponseSchema,
   ToggleFlowRequestSchema,
   ToggleFlowResponseSchema,
   ListRunsRequestSchema,
@@ -259,6 +261,60 @@ describe('DeleteFlowResponseSchema', () => {
   });
 });
 
+// ==========================================
+// Trigger Flow
+// ==========================================
+
+describe('TriggerFlowRequestSchema', () => {
+  it('should accept minimal trigger request', () => {
+    const result = TriggerFlowRequestSchema.parse({ name: 'my_flow' });
+    expect(result.name).toBe('my_flow');
+    expect(result.record).toBeUndefined();
+  });
+
+  it('should accept full trigger request', () => {
+    const result = TriggerFlowRequestSchema.parse({
+      name: 'approval_flow',
+      record: { id: 'rec-1', amount: 50000 },
+      object: 'opportunity',
+      event: 'on_create',
+      userId: 'user_123',
+      params: { priority: 'high' },
+    });
+    expect(result.name).toBe('approval_flow');
+    expect(result.object).toBe('opportunity');
+    expect(result.event).toBe('on_create');
+  });
+});
+
+describe('TriggerFlowResponseSchema', () => {
+  it('should accept a successful trigger response', () => {
+    const result = TriggerFlowResponseSchema.parse({
+      success: true,
+      data: {
+        success: true,
+        output: { status: 'approved' },
+        durationMs: 42,
+      },
+    });
+    expect(result.data.success).toBe(true);
+    expect(result.data.durationMs).toBe(42);
+  });
+
+  it('should accept a failed trigger response', () => {
+    const result = TriggerFlowResponseSchema.parse({
+      success: true,
+      data: {
+        success: false,
+        error: 'Flow step 3 failed: timeout',
+        durationMs: 5000,
+      },
+    });
+    expect(result.data.success).toBe(false);
+    expect(result.data.error).toContain('timeout');
+  });
+});
+
 // ==========================================
 // Toggle Flow
 // ==========================================
@@ -437,4 +493,11 @@ describe('AutomationApiContracts', () => {
     expect(AutomationApiContracts.listRuns.path).toBe('/api/automation/:name/runs');
     expect(AutomationApiContracts.getRun.path).toBe('/api/automation/:name/runs/:runId');
   });
+
+  it('should have input and output schemas for all endpoints', () => {
+    for (const [key, contract] of Object.entries(AutomationApiContracts)) {
+      expect(contract.input, `${key} should have input schema`).toBeDefined();
+      expect(contract.output, `${key} should have output schema`).toBeDefined();
+    }
+  });
 });

packages/spec/src/api/automation-api.zod.ts

@@ -178,7 +178,44 @@ export const DeleteFlowResponseSchema = BaseResponseSchema.extend({
 export type DeleteFlowResponse = z.infer<typeof DeleteFlowResponseSchema>;
 
 // ==========================================
-// 7. Toggle Flow (POST /api/automation/:name/toggle)
+// 7. Trigger Flow (POST /api/automation/:name/trigger)
+// ==========================================
+
+/**
+ * Request body for triggering a flow execution.
+ *
+ * @example POST /api/automation/approval_flow/trigger
+ * { record: { id: 'rec-1' }, object: 'account', event: 'on_create' }
+ */
+export const TriggerFlowRequestSchema = AutomationFlowPathParamsSchema.extend({
+  record: z.record(z.string(), z.unknown()).optional()
+    .describe('Record that triggered the automation'),
+  object: z.string().optional()
+    .describe('Object name the record belongs to'),
+  event: z.string().optional()
+    .describe('Trigger event type'),
+  userId: z.string().optional()
+    .describe('User who triggered the automation'),
+  params: z.record(z.string(), z.unknown()).optional()
+    .describe('Additional contextual data'),
+});
+export type TriggerFlowRequest = z.infer<typeof TriggerFlowRequestSchema>;
+
+/**
+ * Response after triggering a flow execution.
+ */
+export const TriggerFlowResponseSchema = BaseResponseSchema.extend({
+  data: z.object({
+    success: z.boolean().describe('Whether the automation completed successfully'),
+    output: z.unknown().optional().describe('Output data from the automation'),
+    error: z.string().optional().describe('Error message if execution failed'),
+    durationMs: z.number().optional().describe('Execution duration in milliseconds'),
+  }),
+});
+export type TriggerFlowResponse = z.infer<typeof TriggerFlowResponseSchema>;
+
+// ==========================================
+// 8. Toggle Flow (POST /api/automation/:name/toggle)
 // ==========================================
 
 /**
@@ -204,7 +241,7 @@ export const ToggleFlowResponseSchema = BaseResponseSchema.extend({
 export type ToggleFlowResponse = z.infer<typeof ToggleFlowResponseSchema>;
 
 // ==========================================
-// 8. List Runs (GET /api/automation/:name/runs)
+// 9. List Runs (GET /api/automation/:name/runs)
 // ==========================================
 
 /**
@@ -236,7 +273,7 @@ export const ListRunsResponseSchema = BaseResponseSchema.extend({
 export type ListRunsResponse = z.infer<typeof ListRunsResponseSchema>;
 
 // ==========================================
-// 9. Get Run (GET /api/automation/:name/runs/:runId)
+// 10. Get Run (GET /api/automation/:name/runs/:runId)
 // ==========================================
 
 /**
@@ -254,7 +291,7 @@ export const GetRunResponseSchema = BaseResponseSchema.extend({
 export type GetRunResponse = z.infer<typeof GetRunResponseSchema>;
 
 // ==========================================
-// 10. Automation API Error Codes
+// 11. Automation API Error Codes
 // ==========================================
 
 /**
@@ -274,7 +311,7 @@ export const AutomationApiErrorCode = z.enum([
 export type AutomationApiErrorCode = z.infer<typeof AutomationApiErrorCode>;
 
 // ==========================================
-// 11. Automation API Contract Registry
+// 12. Automation API Contract Registry
 // ==========================================
 
 /**
@@ -315,6 +352,8 @@ export const AutomationApiContracts = {
   triggerFlow: {
     method: 'POST' as const,
     path: '/api/automation/:name/trigger',
+    input: TriggerFlowRequestSchema,
+    output: TriggerFlowResponseSchema,
   },
   toggleFlow: {
     method: 'POST' as const,

packages/spec/src/contracts/automation-service.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import type { IAutomationService, AutomationResult } from './automation-service';
+import type { FlowParsed } from '../automation/flow.zod';
+import type { ExecutionLog } from '../automation/execution.zod';
 
 describe('Automation Service Contract', () => {
   it('should allow a minimal IAutomationService implementation with required methods', () => {
@@ -79,4 +81,90 @@ describe('Automation Service Contract', () => {
     expect(flows).toHaveLength(3);
     expect(flows).toContain('approval_flow');
   });
+
+  it('should return typed FlowParsed from getFlow', async () => {
+    const mockFlow: FlowParsed = {
+      name: 'approval_flow',
+      label: 'Approval Flow',
+      type: 'autolaunched',
+      status: 'draft',
+      version: 1,
+      enabled: true,
+      nodes: [
+        { id: 'start', type: 'start', label: 'Start' },
+        { id: 'end', type: 'end', label: 'End' },
+      ],
+      edges: [{ id: 'e1', source: 'start', target: 'end' }],
+    };
+
+    const service: IAutomationService = {
+      execute: async () => ({ success: true }),
+      listFlows: async () => ['approval_flow'],
+      getFlow: async (name) => name === 'approval_flow' ? mockFlow : null,
+    };
+
+    const flow = await service.getFlow!('approval_flow');
+    expect(flow).not.toBeNull();
+    expect(flow!.name).toBe('approval_flow');
+    expect(flow!.nodes).toHaveLength(2);
+
+    const missing = await service.getFlow!('nonexistent');
+    expect(missing).toBeNull();
+  });
+
+  it('should return typed ExecutionLog from listRuns and getRun', async () => {
+    const mockRun: ExecutionLog = {
+      id: 'exec_001',
+      flowName: 'approval_flow',
+      status: 'completed',
+      trigger: { type: 'api' },
+      steps: [{
+        nodeId: 'start',
+        nodeType: 'start',
+        status: 'success',
+        startedAt: '2026-02-01T10:00:00Z',
+        durationMs: 1,
+      }],
+      startedAt: '2026-02-01T10:00:00Z',
+      completedAt: '2026-02-01T10:00:01Z',
+      durationMs: 1000,
+    };
+
+    const service: IAutomationService = {
+      execute: async () => ({ success: true }),
+      listFlows: async () => ['approval_flow'],
+      listRuns: async (_flowName, _options?) => [mockRun],
+      getRun: async (runId) => runId === 'exec_001' ? mockRun : null,
+    };
+
+    const runs = await service.listRuns!('approval_flow');
+    expect(runs).toHaveLength(1);
+    expect(runs[0].id).toBe('exec_001');
+    expect(runs[0].status).toBe('completed');
+    expect(runs[0].steps).toHaveLength(1);
+
+    const run = await service.getRun!('exec_001');
+    expect(run).not.toBeNull();
+    expect(run!.flowName).toBe('approval_flow');
+    expect(run!.durationMs).toBe(1000);
+
+    const missingRun = await service.getRun!('nonexistent');
+    expect(missingRun).toBeNull();
+  });
+
+  it('should support toggleFlow to enable/disable flows', async () => {
+    let flowEnabled = true;
+
+    const service: IAutomationService = {
+      execute: async () => ({ success: true }),
+      listFlows: async () => ['test_flow'],
+      toggleFlow: async (_name, enabled) => { flowEnabled = enabled; },
+    };
+
+    await service.toggleFlow!('test_flow', false);
+    expect(flowEnabled).toBe(false);
+
+    await service.toggleFlow!('test_flow', true);
+    expect(flowEnabled).toBe(true);
+  });
 });

packages/spec/src/contracts/automation-service.ts

@@ -13,6 +13,9 @@
  * Aligned with CoreServiceName 'automation' in core-services.zod.ts.
  */
 
+import type { FlowParsed } from '../automation/flow.zod';
+import type { ExecutionLog } from '../automation/execution.zod';
+
 /**
  * Context passed to a flow/script execution
  */
@@ -76,7 +79,7 @@ export interface IAutomationService {
      * @param name - Flow name (snake_case)
      * @returns Flow definition or null if not found
      */
-    getFlow?(name: string): Promise<unknown | null>;
+    getFlow?(name: string): Promise<FlowParsed | null>;
 
     /**
      * Enable or disable a flow
@@ -91,12 +94,12 @@ export interface IAutomationService {
      * @param options - Pagination options
      * @returns Array of execution logs
      */
-    listRuns?(flowName: string, options?: { limit?: number; cursor?: string }): Promise<unknown[]>;
+    listRuns?(flowName: string, options?: { limit?: number; cursor?: string }): Promise<ExecutionLog[]>;
 
     /**
      * Get a single execution run by ID
      * @param runId - Execution run ID
      * @returns Execution log or null if not found
      */
-    getRun?(runId: string): Promise<unknown | null>;
+    getRun?(runId: string): Promise<ExecutionLog | null>;
 }