@agentuity/core 2.0.0 → 2.0.2

package/src/services/auth/types.ts

@@ -0,0 +1,223 @@
+/**
+ * Core authentication types for Agentuity.
+ *
+ * These types are defined in @agentuity/core to avoid circular dependencies
+ * and allow packages like @agentuity/runtime to use auth types without
+ * pulling in heavy dependencies like drizzle-orm.
+ *
+ * @module services/auth/types
+ */
+
+// =============================================================================
+// Canonical User/Session Types
+// =============================================================================
+
+/**
+ * Canonical authenticated user type for Agentuity Auth.
+ *
+ * Common fields include:
+ * - `id` – Stable user identifier
+ * - `email` – Primary email address
+ * - `name` – Display name
+ * - `image` – Avatar URL (if configured)
+ * - `createdAt` / `updatedAt` – Timestamps
+ */
+export interface AuthUser {
+	id: string;
+	email: string;
+	name?: string | null;
+	image?: string | null;
+	createdAt?: Date | string;
+	updatedAt?: Date | string;
+}
+
+/**
+ * Auth session type with organization plugin fields.
+ */
+export interface AuthSession {
+	id: string;
+	userId: string;
+	expiresAt: Date | string;
+	/** Active organization ID from the organization plugin */
+	activeOrganizationId?: string;
+	ipAddress?: string | null;
+	userAgent?: string | null;
+	createdAt?: Date | string;
+	updatedAt?: Date | string;
+}
+
+/**
+ * Auth context containing user, session, and org data.
+ * This is the full auth context available on AgentContext.auth and c.var.auth.
+ * Session may be null for API key authentication.
+ */
+export interface AuthContext<TUser = AuthUser, TSession = AuthSession | null> {
+	user: TUser;
+	session: TSession;
+	org: AuthOrgContext | null;
+}
+
+/**
+ * Organization context from the organization plugin.
+ */
+export interface AuthOrgContext {
+	/** Organization ID */
+	id: string;
+	/** Organization slug (URL-friendly identifier) */
+	slug?: string | null;
+	/** Organization display name */
+	name?: string | null;
+	/** Member's role in this organization (e.g., 'owner', 'admin', 'member') */
+	role?: string | null;
+	/** Member ID for this user in this organization */
+	memberId?: string | null;
+	/** Organization metadata (if enabled) */
+	metadata?: unknown;
+}
+
+// =============================================================================
+// API Key Types
+// =============================================================================
+
+/**
+ * API key permissions format.
+ * Maps resource names to arrays of allowed actions.
+ *
+ * @example
+ * ```typescript
+ * const permissions: AuthApiKeyPermissions = {
+ *   project: ['read', 'write'],
+ *   user: ['read'],
+ *   admin: ['*'], // wildcard - all actions
+ * };
+ * ```
+ */
+export interface AuthApiKeyPermissions {
+	[key: string]: string[];
+}
+
+/**
+ * API key context when request is authenticated via API key.
+ */
+export interface AuthApiKeyContext {
+	/** API key ID */
+	id: string;
+	/** Display name of the API key */
+	name?: string | null;
+	/** Permissions associated with this API key */
+	permissions: AuthApiKeyPermissions;
+	/** User ID the API key belongs to */
+	userId?: string | null;
+}
+
+/**
+ * Authentication method used for the current request.
+ */
+export type AuthMethod = 'session' | 'api-key' | 'bearer';
+
+// =============================================================================
+// Auth Interface
+// =============================================================================
+
+/**
+ * Generic authentication interface exposed on Hono context.
+ *
+ * This type is intentionally provider-agnostic.
+ *
+ * @typeParam TUser - Domain user type (defaults to unknown for flexibility).
+ * @typeParam TRaw - Underlying auth context (defaults to unknown for flexibility).
+ */
+export interface AgentuityAuth<TUser = unknown, TRaw = unknown> {
+	/** Get the authenticated user, throws if not authenticated */
+	getUser(): Promise<TUser>;
+
+	/** Get the raw JWT token */
+	getToken(): Promise<string | null>;
+
+	/** Raw provider-specific auth object or auth context */
+	raw: TRaw;
+}
+
+/**
+ * Organization helpers available on the auth context.
+ */
+export interface AuthOrgHelpers {
+	/** Active organization context if available, null otherwise */
+	org: AuthOrgContext | null;
+
+	/** Returns active org or null (never throws) */
+	getOrg(): Promise<AuthOrgContext | null>;
+
+	/** Convenience accessor for the member's role on the active org */
+	getOrgRole(): Promise<string | null>;
+
+	/** True if the current member's role is one of the provided roles */
+	hasOrgRole(...roles: string[]): Promise<boolean>;
+}
+
+/**
+ * API key helpers available on the auth context.
+ */
+export interface AuthApiKeyHelpers {
+	/** How this request was authenticated */
+	authMethod: AuthMethod;
+
+	/** API key context when request is authenticated via API key, null otherwise */
+	apiKey: AuthApiKeyContext | null;
+
+	/**
+	 * Check if the API key has the required permissions.
+	 * All specified actions must be present for the resource.
+	 * Supports '*' wildcard which matches any action.
+	 *
+	 * @param resource - The resource to check (e.g., 'project', 'user')
+	 * @param actions - Actions required (e.g., 'read', 'write')
+	 * @returns true if all actions are permitted, false otherwise
+	 *
+	 * @example
+	 * ```typescript
+	 * // Check for specific permission
+	 * if (c.var.auth.hasPermission('project', 'write')) { ... }
+	 *
+	 * // Check for multiple permissions (all required)
+	 * if (c.var.auth.hasPermission('project', 'read', 'write')) { ... }
+	 * ```
+	 */
+	hasPermission(resource: string, ...actions: string[]): boolean;
+}
+
+/**
+ * Full authentication interface available on `c.var.auth` and `ctx.auth`.
+ *
+ * This is the primary interface you'll use to access authentication data
+ * in your route handlers and agents. It provides:
+ *
+ * - User data via `getUser()`
+ * - Organization helpers via `getOrg()`, `getOrgRole()`, `hasOrgRole()`
+ * - API key helpers via `apiKey`, `hasPermission()`
+ * - Token access via `getToken()`
+ *
+ * @example Route handler
+ * ```typescript
+ * app.get('/api/profile', async (c) => {
+ *   const user = await c.var.auth.getUser();
+ *   const org = await c.var.auth.getOrg();
+ *   return c.json({ user, org });
+ * });
+ * ```
+ *
+ * @example Agent handler
+ * ```typescript
+ * handler: async (ctx, input) => {
+ *   if (!ctx.auth) return { error: 'Unauthorized' };
+ *   const user = await ctx.auth.getUser();
+ *   return { message: `Hello, ${user.email}!` };
+ * }
+ * ```
+ *
+ * @typeParam TUser - User type (extends AuthUser, defaults to AuthUser)
+ */
+export interface AuthInterface<TUser extends AuthUser = AuthUser>
+	extends AgentuityAuth<TUser, AuthContext<TUser>>,
+		AuthOrgHelpers,
+		AuthApiKeyHelpers {}

package/src/services/index.ts

@@ -1,4 +1,5 @@
 export * from './adapter.ts';
+export * from './auth/index.ts';
 export * from './email/index.ts';
 export * from './exception.ts';
 export * from './keyvalue/index.ts';
@@ -30,5 +31,6 @@ export * from './stream/index.ts';
 export * from './thread/index.ts';
 export * from './user/index.ts';
 export * from './webhook/index.ts';
+export * from './workflow/index.ts';
 
 export { buildUrl, fromResponse, toPayload, toServiceException } from './_util.ts';

package/src/services/queue/destinations.ts

@@ -78,7 +78,7 @@ export async function createDestination(
 				undefined,
 				buildQueueHeaders(options?.orgId)
 			),
-		{ queueName, destinationUrl: params.config?.url }
+		{ queueName, destinationUrl: params.config?.url as string | undefined }
 	);
 
 	if (resp.success) {

package/src/services/queue/types.ts

@@ -319,9 +319,11 @@ export const MessageSchema = z
 export type Message = z.infer<typeof MessageSchema>;
 
 /**
- * Destination type schema. Currently only HTTP webhooks are supported.
+ * Destination type schema. Supports webhook, queue, sandbox, and email destinations.
  */
-export const DestinationTypeSchema = z.enum(['http']).describe('Destination type schema');
+export const DestinationTypeSchema = z
+	.enum(['http', 'url', 'webhook', 'queue', 'sandbox', 'email'])
+	.describe('Destination type schema');
 
 /**
  * Destination type.
@@ -591,6 +593,7 @@ export const CreateQueueRequestSchema = z
 		name: z.string().optional().describe('Optional queue name (auto-generated if not provided).'),
 		description: z.string().optional().describe("Optional description of the queue's purpose."),
 		queue_type: QueueTypeSchema.describe('Type of queue to create.'),
+		internal: z.boolean().optional().describe('Whether the queue is system-managed.'),
 		settings: QueueSettingsSchemaBase.partial()
 			.optional()
 			.describe(
@@ -747,7 +750,9 @@ export const CreateDestinationRequestSchema = z
 		name: z.string().describe('Human-readable name for the destination.'),
 		description: z.string().optional().describe('Optional description of the destination.'),
 		destination_type: DestinationTypeSchema.describe('Type of destination to create.'),
-		config: HttpDestinationConfigSchema.describe('HTTP configuration for the destination.'),
+		config: z
+			.record(z.string(), z.unknown())
+			.describe('Configuration for the destination (type-specific).'),
 		enabled: z
 			.boolean()
 			.default(true)
@@ -769,9 +774,10 @@ export const UpdateDestinationRequestSchema = z
 			.nullable()
 			.optional()
 			.describe('Updated description of the destination.'),
-		config: HttpDestinationConfigSchema.partial()
+		config: z
+			.record(z.string(), z.unknown())
 			.optional()
-			.describe('HTTP configuration updates (partial update supported).'),
+			.describe('Configuration updates (partial update supported).'),
 		enabled: z.boolean().optional().describe('Enable or disable the destination.'),
 	})
 	.describe('Update destination request schema');

package/src/services/webhook/types.ts

@@ -213,6 +213,7 @@ export const CreateWebhookRequestSchema = z
 	.object({
 		name: z.string().describe('Human-readable name for the webhook'),
 		description: z.string().optional().describe("Optional description of the webhook's purpose"),
+		internal: z.boolean().optional().describe('Whether the webhook is system-managed.'),
 	})
 	.describe('Request for creating a new webhook');
 

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';