@agentuity/core 2.0.1 → 2.0.2

package/src/services/workflow/api-reference.ts

@@ -0,0 +1,350 @@
+import type { Service } from '../api-reference.ts';
+import {
+	CreateWorkflowRequestSchema,
+	UpdateWorkflowRequestSchema,
+	UpdateWorkflowGraphRequestSchema,
+	TestWorkflowRequestSchema,
+	WorkflowListResultSchema,
+	WorkflowGetResultSchema,
+	WorkflowCreateResultSchema,
+	WorkflowUpdateResultSchema,
+	WorkflowActivitySchema,
+	WorkflowExecutionSchema,
+	WorkflowDeliverySchema,
+	TestWorkflowResultSchema,
+} from './types.ts';
+import { z } from 'zod';
+
+const service: Service = {
+	name: 'Workflows',
+	slug: 'workflows',
+	description: 'Create and manage workflows that route events from sources to destinations',
+	endpoints: [
+		{
+			id: 'list-workflows',
+			title: 'List Workflows',
+			sectionTitle: 'Workflow Management',
+			method: 'GET',
+			path: '/workflow/list',
+			description: 'List all workflows with optional filtering and pagination.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Maximum number of workflows to return',
+					required: false,
+				},
+				{
+					name: 'offset',
+					type: 'number',
+					description: 'Pagination offset',
+					required: false,
+				},
+				{
+					name: 'status',
+					type: 'string',
+					description: 'Filter by status (enabled or disabled)',
+					required: false,
+				},
+				{
+					name: 'source_type',
+					type: 'string',
+					description: 'Filter by source type (email, queue, webhook, or schedule)',
+					required: false,
+				},
+				{
+					name: 'filter',
+					type: 'string',
+					description: 'Filter workflows by name',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Returns paginated list of workflows.',
+			responseFields: { schema: WorkflowListResultSchema },
+			statuses: [
+				{ code: 200, description: 'Workflows returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/workflow/list',
+		},
+		{
+			id: 'get-workflow',
+			title: 'Get Workflow',
+			sectionTitle: 'Workflow Management',
+			method: 'GET',
+			path: '/workflow/{workflowId}',
+			description: 'Get a specific workflow by ID.',
+			pathParams: [
+				{
+					name: 'workflowId',
+					type: 'string',
+					description: 'Workflow ID (wf_ prefix)',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns the workflow object.',
+			responseFields: { schema: WorkflowGetResultSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Workflow returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Workflow not found' },
+			],
+			examplePath: '/workflow/wf_abc123',
+		},
+		{
+			id: 'create-workflow',
+			title: 'Create Workflow',
+			sectionTitle: 'Workflow Management',
+			method: 'POST',
+			path: '/workflow/create',
+			description: 'Create a new workflow with a source type and reference.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Workflow creation payload.',
+				fields: { schema: CreateWorkflowRequestSchema },
+			},
+			responseDescription: 'Returns the created workflow.',
+			responseFields: { schema: WorkflowCreateResultSchema },
+			statuses: [
+				{ code: 201, description: 'Workflow created' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/workflow/create',
+			exampleBody: {
+				name: 'GitHub to Slack',
+				source_type: 'webhook',
+				source_ref_id: 'wh_abc123',
+			},
+		},
+		{
+			id: 'update-workflow',
+			title: 'Update Workflow',
+			sectionTitle: 'Workflow Management',
+			method: 'PATCH',
+			path: '/workflow/{workflowId}',
+			description: "Update a workflow's name, description, or status.",
+			pathParams: [
+				{
+					name: 'workflowId',
+					type: 'string',
+					description: 'Workflow ID',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: {
+				description: 'Fields to update.',
+				fields: { schema: UpdateWorkflowRequestSchema },
+			},
+			responseDescription: 'Returns the updated workflow.',
+			responseFields: { schema: WorkflowUpdateResultSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Workflow updated' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Workflow not found' },
+			],
+			examplePath: '/workflow/wf_abc123',
+			exampleBody: { name: 'Renamed Workflow', status: 'disabled' },
+		},
+		{
+			id: 'update-workflow-graph',
+			title: 'Update Workflow Graph',
+			sectionTitle: 'Workflow Management',
+			method: 'PUT',
+			path: '/workflow/{workflowId}/graph',
+			description: 'Update the workflow graph definition (nodes and edges).',
+			pathParams: [
+				{
+					name: 'workflowId',
+					type: 'string',
+					description: 'Workflow ID',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: {
+				description: 'Graph definition with nodes and edges.',
+				fields: { schema: UpdateWorkflowGraphRequestSchema },
+			},
+			responseDescription: 'Returns the updated workflow.',
+			responseFields: { schema: WorkflowUpdateResultSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Workflow graph updated' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Workflow not found' },
+			],
+			examplePath: '/workflow/wf_abc123/graph',
+			exampleBody: {
+				nodes: [
+					{ id: 'n1', type: 'filter' },
+					{ id: 'n2', type: 'action' },
+				],
+				edges: [{ id: 'e1', source: 'n1', target: 'n2' }],
+			},
+		},
+		{
+			id: 'delete-workflow',
+			title: 'Delete Workflow',
+			sectionTitle: 'Workflow Management',
+			method: 'DELETE',
+			path: '/workflow/{workflowId}',
+			description: 'Delete a workflow and all associated executions and deliveries.',
+			pathParams: [
+				{
+					name: 'workflowId',
+					type: 'string',
+					description: 'Workflow ID',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'Workflow deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Workflow not found' },
+			],
+			examplePath: '/workflow/wf_abc123',
+		},
+		{
+			id: 'test-workflow',
+			title: 'Test Workflow',
+			sectionTitle: 'Testing',
+			method: 'POST',
+			path: '/workflow/{workflowId}/test',
+			description: 'Test a workflow with a sample payload.',
+			pathParams: [
+				{
+					name: 'workflowId',
+					type: 'string',
+					description: 'Workflow ID',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: {
+				description: 'Test payload to send through the workflow.',
+				fields: { schema: TestWorkflowRequestSchema },
+			},
+			responseDescription: 'Returns the test execution result.',
+			responseFields: { schema: TestWorkflowResultSchema },
+			statuses: [
+				{ code: 200, description: 'Test completed' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Workflow not found' },
+			],
+			examplePath: '/workflow/wf_abc123/test',
+			exampleBody: { payload: { event: 'test', data: { key: 'value' } } },
+		},
+		{
+			id: 'workflow-activity',
+			title: 'Get Workflow Activity',
+			sectionTitle: 'Analytics',
+			method: 'GET',
+			path: '/workflow/activity',
+			description: 'Get workflow activity statistics for the organization.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'days',
+					type: 'number',
+					description: 'Number of days to look back',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Returns aggregate workflow activity statistics.',
+			responseFields: { schema: WorkflowActivitySchema },
+			statuses: [
+				{ code: 200, description: 'Activity returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/workflow/activity',
+		},
+		{
+			id: 'list-workflow-executions',
+			title: 'List Workflow Executions',
+			sectionTitle: 'Executions',
+			method: 'GET',
+			path: '/workflow/{workflowId}/executions',
+			description: 'List execution records for a specific workflow.',
+			pathParams: [
+				{
+					name: 'workflowId',
+					type: 'string',
+					description: 'Workflow ID',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns list of executions.',
+			responseFields: { schema: z.array(WorkflowExecutionSchema) },
+			statuses: [
+				{ code: 200, description: 'Executions returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Workflow not found' },
+			],
+			examplePath: '/workflow/wf_abc123/executions',
+		},
+		{
+			id: 'list-workflow-deliveries',
+			title: 'List Workflow Deliveries',
+			sectionTitle: 'Deliveries',
+			method: 'GET',
+			path: '/workflow/executions/{executionId}/deliveries',
+			description: 'List delivery records for a specific execution.',
+			pathParams: [
+				{
+					name: 'executionId',
+					type: 'string',
+					description: 'Execution ID',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns list of deliveries.',
+			responseFields: { schema: z.array(WorkflowDeliverySchema) },
+			statuses: [
+				{ code: 200, description: 'Deliveries returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Execution not found' },
+			],
+			examplePath: '/workflow/executions/exec_abc123/deliveries',
+		},
+		{
+			id: 'get-recent-payload',
+			title: 'Get Recent Payload',
+			sectionTitle: 'Analytics',
+			method: 'GET',
+			path: '/workflow/{workflowId}/recent-payload',
+			description: 'Get the most recent payload received by a workflow.',
+			pathParams: [
+				{
+					name: 'workflowId',
+					type: 'string',
+					description: 'Workflow ID',
+					required: true,
+				},
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Returns the most recent payload data.',
+			statuses: [
+				{ code: 200, description: 'Payload returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Workflow not found or no recent payload' },
+			],
+			examplePath: '/workflow/wf_abc123/recent-payload',
+		},
+	],
+};
+
+export default service;

package/src/services/workflow/index.ts

@@ -0,0 +1,2 @@
+export * from './service.ts';
+export * from './types.ts';