meebly-onboarding-mcp-server 0.0.1

package/dist/src/utils/validation.js

@@ -0,0 +1,724 @@
+import { z } from 'zod';
+import { ApiError } from './errorUtils.js';
+import { HTTP_STATUS } from '../constants/index.js';
+export function requireString(obj, fieldName, customMessage) {
+    const value = obj?.[fieldName];
+    if (!value || typeof value !== 'string' || value.trim().length === 0) {
+        throw new ApiError(customMessage ||
+            `${fieldName} is required and must be a non-empty string`, HTTP_STATUS.BAD_REQUEST);
+    }
+    return value.trim();
+}
+export function optionalString(obj, fieldName, customMessage) {
+    const value = obj?.[fieldName];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new ApiError(customMessage || `${fieldName} must be a non-empty string when provided`, HTTP_STATUS.BAD_REQUEST);
+    }
+    return value.trim();
+}
+export function optionalBoolean(obj, fieldName, customMessage) {
+    const value = obj?.[fieldName];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean') {
+        throw new ApiError(customMessage || `${fieldName} must be a boolean when provided`, HTTP_STATUS.BAD_REQUEST);
+    }
+    return value;
+}
+export function requireArray(obj, fieldName, customMessage) {
+    const value = obj?.[fieldName];
+    if (!Array.isArray(value)) {
+        throw new ApiError(customMessage || `${fieldName} must be an array`, HTTP_STATUS.BAD_REQUEST);
+    }
+    return value;
+}
+export function requireMessageArray(obj, fieldName = 'messages') {
+    const messages = requireArray(obj, fieldName);
+    if (messages.some((m) => !m || typeof m.content !== 'string')) {
+        throw new ApiError(`${fieldName} must be an array of objects with content property`, HTTP_STATUS.BAD_REQUEST);
+    }
+    return messages;
+}
+export function requireEnum(obj, fieldName, allowedValues, customMessage) {
+    const value = requireString(obj, fieldName);
+    if (!allowedValues.includes(value)) {
+        throw new ApiError(customMessage ||
+            `${fieldName} must be one of: ${allowedValues.join(', ')}`, HTTP_STATUS.BAD_REQUEST);
+    }
+    return value;
+}
+export function optionalEnum(obj, fieldName, allowedValues, customMessage) {
+    const value = obj?.[fieldName];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !allowedValues.includes(value)) {
+        throw new ApiError(customMessage ||
+            `${fieldName} must be one of: ${allowedValues.join(', ')} when provided`, HTTP_STATUS.BAD_REQUEST);
+    }
+    return value;
+}
+export function validateRequiredParams(params, requiredParams) {
+    const missing = requiredParams.filter((p) => params?.[p] === undefined || params?.[p] === null || params?.[p] === '');
+    if (missing.length > 0) {
+        throw new ApiError(`Missing required parameters: ${missing.join(', ')}`, HTTP_STATUS.BAD_REQUEST);
+    }
+}
+export function validateUrl(url, paramName = 'url') {
+    try {
+        new URL(url);
+    }
+    catch {
+        throw new ApiError(`Invalid ${paramName} format`, HTTP_STATUS.BAD_REQUEST);
+    }
+}
+export function validateEmail(email) {
+    try {
+        z.string().email().parse(email);
+    }
+    catch {
+        throw new ApiError('Invalid email format', HTTP_STATUS.BAD_REQUEST);
+    }
+}
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const OBJECT_ID_REGEX = /^[0-9a-fA-F]{24}$/;
+export function validateId(value, { fieldName = 'id', kind = 'string', } = {}) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new ApiError(`${fieldName} is required and must be a string`, HTTP_STATUS.BAD_REQUEST);
+    }
+    const v = value.trim();
+    if (kind === 'uuid' && !UUID_REGEX.test(v)) {
+        throw new ApiError(`Invalid ${fieldName} format. Expected UUID.`, HTTP_STATUS.BAD_REQUEST);
+    }
+    if (kind === 'objectId' && !OBJECT_ID_REGEX.test(v)) {
+        throw new ApiError(`Invalid ${fieldName} format. Expected 24-char hex ObjectId.`, HTTP_STATUS.BAD_REQUEST);
+    }
+    return v;
+}
+export function validateBody(data, schema) {
+    try {
+        return schema.parse(data);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const errorMessage = error.issues
+                .map((err) => `${err.path.join('.')}: ${err.message}`)
+                .join(', ');
+            throw new ApiError(`Validation error: ${errorMessage}`, HTTP_STATUS.BAD_REQUEST, error.issues);
+        }
+        throw error;
+    }
+}
+export const HttpMethodEnum = z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
+export const InviteStatusEnum = z.enum([
+    'pending',
+    'accepted',
+    'expired',
+    'revoked',
+]);
+export const OrganizationRoleEnum = z.enum(['Owner', 'Member', 'Admin']);
+/* ------------------------------------ */
+/* Field Validation Schemas             */
+/* ------------------------------------ */
+/** Supported field types */
+export const FieldTypeSchema = z.enum([
+    'string',
+    'number',
+    'integer',
+    'boolean',
+    'array',
+    'object',
+    'date',
+    'datetime',
+    'uuid',
+    'email',
+    'url',
+    'file',
+]);
+/** Field configuration (recursive for nested properties) */
+export const FieldSchema = z.lazy(() => z.object({
+    type: FieldTypeSchema,
+    requiredByBackend: z.boolean().optional().default(false),
+    fieldInstructions: z.string().optional(),
+    format: z.string().optional(),
+    items: FieldSchema.optional(),
+    example: z.any().optional(),
+    location: z.enum(['query', 'path', 'body']).optional(),
+    properties: z.record(z.string(), FieldSchema).optional(),
+}));
+/** Field collection - supports both simple and complex formats */
+export const FieldsSchema = z.record(z.string(), FieldSchema);
+export const SimpleFieldsSchema = z.record(z.string(), FieldTypeSchema);
+export const FlexibleFieldsSchema = z.union([SimpleFieldsSchema, FieldsSchema]);
+/* ------------------------------------ */
+/* Chat Validation Schemas              */
+/* ------------------------------------ */
+/** Uploaded file metadata */
+export const UploadedFileSchema = z.object({
+    url: z.string().min(1, 'File url is required'),
+    name: z.string().min(1, 'name is required'),
+    type: z.string().min(1, 'MIME type is required'),
+});
+/** Uploaded files collection */
+export const UploadedFilesSchema = z
+    .record(z.string(), UploadedFileSchema)
+    .optional();
+/** Chat message structure */
+export const ChatMessageSchema = z.object({
+    agentId: z.string().min(1, 'agentId is required'),
+    apiKey: z.string().min(1, 'apiKey is required'),
+    environmentId: z.string().min(1, 'environmentId is required'),
+    messages: z
+        .array(z.object({
+        content: z.string().min(1, 'Message content is required'),
+    }))
+        .min(1, 'At least one message is required'),
+    customerId: z.string().optional(),
+    customInstructions: z.string().optional(),
+    logChannelId: z.string().optional(),
+    logToolScore: z.boolean().optional().default(false),
+    threadId: z.string().optional(),
+    uploadedFiles: UploadedFilesSchema.optional(),
+});
+export const EphemeralChatMessageSchema = z.object({
+    apiKey: z.string().min(1, 'apiKey is required'),
+    environmentId: z.string().min(1, 'environmentId is required'),
+    messages: z
+        .array(z.object({
+        content: z.string().min(1, 'Message content is required'),
+    }))
+        .min(1, 'At least one message is required'),
+    authToken: z.string().optional(),
+    customInstructions: z.string().optional(),
+    endpointDefinition: z.any().optional(),
+    endpointId: z.string().optional(),
+    logChannelId: z.string().optional(),
+    threadId: z.string().optional(),
+    uploadedFiles: UploadedFilesSchema.optional(),
+    mcpToolId: z.string().optional(),
+});
+/** Screen state schema for context from host app */
+export const ScreenStateSchema = z.object({
+    route: z.string().min(1, 'route is required'),
+    routeName: z.string().optional(),
+    entities: z.record(z.string(), z.any()).optional(),
+    observedElements: z
+        .array(z.object({
+        selector: z.string(),
+        text: z.string().optional(),
+        attributes: z.record(z.string(), z.string()).optional(),
+    }))
+        .optional(),
+    timestamp: z.string(),
+    viewportSize: z
+        .object({
+        width: z.number(),
+        height: z.number(),
+    })
+        .optional(),
+});
+export const EmbedChatMessageSchema = z.object({
+    embedToken: z.string().min(1, 'embedToken is required').optional(),
+    messages: z
+        .array(z.object({
+        content: z.string().min(1, 'Message content is required'),
+    }))
+        .min(1, 'At least one message is required'),
+    customerId: z.string().optional(),
+    customInstructions: z.string().optional(),
+    encryptedBackendToken: z.string().optional(),
+    threadId: z.string().optional(),
+    uploadedFiles: UploadedFilesSchema.optional(),
+    parentDomain: z.string().optional(),
+    screenState: ScreenStateSchema.optional(),
+});
+const ToolExecutionFilePartSchema = z.object({
+    name: z.string().nullable().optional(),
+    type: z.string().nullable().optional(),
+    size: z.number().nullable().optional(),
+    base64: z.string().nullable().optional(),
+});
+const ToolExecutionPayloadSchema = z.union([
+    z.object({
+        type: z.literal('none'),
+    }),
+    z.object({
+        type: z.literal('json'),
+        body: z.any().optional(),
+    }),
+    z.object({
+        type: z.literal('form-data'),
+        fields: z.record(z.string(), z.any()).optional().default({}),
+        files: z
+            .record(z.string(), z.union([
+            ToolExecutionFilePartSchema,
+            z.array(ToolExecutionFilePartSchema),
+        ]))
+            .optional()
+            .default({}),
+    }),
+]);
+export const PingMateManualRunSchema = z.object({
+    apiKey: z.string().min(1, 'apiKey is required'),
+    environmentId: z.string().min(1, 'environmentId is required'),
+    method: HttpMethodEnum,
+    url: z.string().min(1, 'url is required'),
+    headers: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean()]).nullable())
+        .optional(),
+    payload: ToolExecutionPayloadSchema.optional(),
+    logChannelId: z.string().optional(),
+    authToken: z.string().optional(),
+});
+/** HITL tool approval payload - supports both direct API key auth and embed token auth */
+export const HitlToolApprovalSchema = z
+    .object({
+    runId: z.string().min(1, 'runId is required'),
+    // For authenticated agent sandbox users
+    apiKey: z.string().optional(),
+    environmentId: z.string().optional(),
+    // For embedded iframe users
+    embedToken: z.string().optional(),
+})
+    .refine((data) => {
+    // Either embedToken OR (apiKey + environmentId) must be provided
+    const hasEmbedToken = !!data.embedToken;
+    const hasApiKeyAuth = !!(data.apiKey && data.environmentId);
+    return hasEmbedToken || hasApiKeyAuth;
+}, {
+    message: 'Either embedToken or both apiKey and environmentId must be provided',
+});
+/* ------------------------------------ */
+/* Log Validation Schemas               */
+/* ------------------------------------ */
+/** Log levels */
+export const LogLevelSchema = z.enum(['info', 'debug', 'warn', 'error']);
+/** Log data (flexible structure) */
+export const LogDataSchema = z
+    .union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.record(z.string(), z.any()),
+    z.array(z.any()),
+])
+    .optional();
+/** Complete log entry */
+export const LogEntrySchema = z.object({
+    level: LogLevelSchema,
+    message: z.string().min(1, 'Log message is required'),
+    data: LogDataSchema,
+    scope: z.enum(['request', 'tool', 'system']).optional(),
+    userFacing: z.literal(true),
+    timestamp: z.string().datetime('Invalid timestamp format'),
+    text: z.string().optional(),
+    correlationId: z.string().uuid('Invalid correlation ID').optional(),
+});
+/** App create/update payload */
+export const AppDataSchema = z.object({
+    name: z.string().min(1, 'name is required'),
+    environments: z
+        .array(z.object({
+        name: z.string().min(1, 'Environment name is required'),
+        backendUrl: z
+            .string()
+            .min(1, 'backendUrl is required')
+            .refine((u) => {
+            try {
+                new URL(u);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }, 'backendUrl must be a valid URL'),
+    }))
+        .min(1, 'At least one environment is required'),
+});
+/** Environment create payload */
+export const EnvironmentCreateDataSchema = z.object({
+    name: z.string().min(1, 'name is required').max(255, 'Name too long'),
+    description: z.string().optional(),
+    organizationId: z.string().uuid('Invalid organization ID'),
+    backendUrl: z
+        .string()
+        .min(1, 'backendUrl is required')
+        .refine((u) => {
+        try {
+            new URL(u);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, 'backendUrl must be a valid URL'),
+});
+/** Environment update payload */
+export const EnvironmentUpdateDataSchema = z.object({
+    name: z.string().min(1).max(255).optional(),
+    description: z.string().optional(),
+    backendUrl: z
+        .string()
+        .min(1)
+        .refine((u) => {
+        try {
+            new URL(u);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, 'backendUrl must be a valid URL')
+        .optional(),
+    isActive: z.boolean().optional(),
+});
+/** Quick action object for chat interfaces */
+export const QuickActionSchema = z.object({
+    label: z.string().min(1, 'label is required'),
+    text: z.string().min(1, 'text is required'),
+});
+/** AI model for agents */
+export const AgentModelSchema = z.object({
+    name: z.string().min(1, 'name is required'),
+    provider: z.string().min(1, 'provider is required'),
+    apiKey: z.string().min(1, 'apiKey is required'),
+});
+/** Endpoint create/update payload */
+export const EndpointDataSchema = z.object({
+    operationName: z.string().min(1, 'operationName is required'),
+    method: HttpMethodEnum,
+    path: z.string().min(1, 'path is required'),
+    authType: z.string().nullable(),
+    // Optional content type
+    contentType: z.string().nullable().optional(),
+    // Optional for additional instructions
+    systemInstructions: z.string().nullable().optional(),
+    // Optional override for backend URL (for external endpoints)
+    backendUrlOverride: z
+        .string()
+        .min(1, 'backendUrlOverride cannot be empty when provided')
+        .refine((u) => {
+        try {
+            new URL(u);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, 'backendUrlOverride must be a valid URL')
+        .nullable()
+        .optional(),
+    // Optional success URL to return after successful tool execution
+    // No validation - accepts any string or null.
+    // The reason is that customers might want to use something like '#tab' in order to redirect to a specific section of their app, not necessarily a full URL.
+    successUrl: z.string().nullable().optional(),
+    // Optional, but when provided must match your flexible schema
+    inputFields: FlexibleFieldsSchema.optional(),
+    // Optional payload examples to guide AI agents
+    payloadExamples: z
+        .object({
+        required: z.any().optional(),
+        full: z.any().optional(),
+        custom: z.any().optional(),
+    })
+        .nullable()
+        .optional(),
+    // Whether to request human confirmation before executing this tool (HITL)
+    requestConfirmation: z.boolean().optional(),
+});
+/** Endpoint create payload */
+export const EndpointCreateDataSchema = z.object({
+    name: z.string().min(1, 'name is required').max(255, 'Name too long'),
+    description: z.string().optional(),
+    environmentId: z.string().uuid('Invalid environment ID'),
+    agentId: z.string().uuid('Invalid agent ID'),
+    endpointData: EndpointDataSchema,
+});
+/** Endpoint update payload */
+export const EndpointUpdateDataSchema = z.object({
+    name: z.string().min(1).max(255).optional(),
+    description: z.string().optional(),
+    endpointData: EndpointDataSchema.optional(),
+    isActive: z.boolean().optional(),
+});
+/** Endpoint execute payload */
+export const EndpointExecuteDataSchema = z.object({
+    inputData: z.any(),
+    parameters: z.record(z.string(), z.any()).optional(),
+});
+/** MCP Tool create payload */
+export const McpToolDataSchema = z.object({
+    name: z.string().min(1, 'name is required'),
+    description: z.string().min(1, 'description is required'),
+    type: z.string().min(1, 'type is required'),
+    serverData: z.any(),
+    icon: z.string().optional(),
+});
+/** MCP Tool update payload */
+export const McpToolUpdateDataSchema = McpToolDataSchema.partial();
+/** Agent create/update payload */
+/** Agent type enumeration */
+export const AgentTypeSchema = z.enum(['conversational', 'functional']);
+export const AgentDataSchema = z.object({
+    name: z.string().min(1, 'name is required'),
+    instructions: z.string().min(1, 'instructions is required'),
+    roleName: z.string().optional().default('assistant'),
+    toolIds: z.array(z.string()),
+    environmentId: z.string(),
+    quickActions: z.array(QuickActionSchema).optional(),
+    models: z.array(AgentModelSchema).optional(),
+    agentType: AgentTypeSchema.optional(),
+    outputSchema: z.any().optional(),
+    temperature: z.number().min(0).max(1).optional(),
+    enableToolSearch: z.boolean().optional(),
+    mcpToolIds: z.array(z.string()),
+});
+export const AgentRAGCreateDataSchema = z.object({
+    environmentId: z.string().min(1, 'environmentId is required'),
+    uploadedFile: UploadedFileSchema,
+});
+export const AgentRAGDeleteDataSchema = z.object({
+    environmentId: z.string().min(1, 'environmentId is required'),
+    fileName: z.string().min(1, 'fileName is required'),
+});
+/** WorkflowStep create/update payload */
+export const WorkflowStepDataSchema = z.object({
+    name: z.string().min(1, 'name is required'),
+    description: z.string().optional(),
+    stepType: z.enum(['agent', 'code', 'tool']),
+    inputSchema: z.any(), // JSON Schema object
+    outputSchema: z.any(), // JSON Schema object
+    config: z.any(), // Step-specific configuration
+    retries: z.number().int().min(0, 'retries must be non-negative').optional(),
+    environmentId: z.string().min(1, 'environmentId is required'),
+});
+export const WorkflowStepUpdateDataSchema = WorkflowStepDataSchema.partial().omit({ environmentId: true });
+/** Workflow step reference schema */
+export const WorkflowStepReferenceSchema = z.object({
+    stepId: z.string().uuid('Invalid step ID'),
+    stepKey: z
+        .string()
+        .min(1, 'stepKey is required')
+        .regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'stepKey must be a valid identifier'),
+    stepOrder: z
+        .number()
+        .int('stepOrder must be an integer')
+        .min(0, 'stepOrder must be non-negative'),
+    branchGroup: z
+        .number()
+        .int('branchGroup must be an integer')
+        .positive('branchGroup must be positive')
+        .nullable()
+        .optional(),
+    branchCondition: z
+        .string()
+        .min(1, 'branchCondition cannot be empty when provided')
+        .nullable()
+        .optional(),
+    isDefaultBranch: z.boolean().optional(),
+    dataMapping: z.record(z.string(), z.string()).nullable().optional(),
+    loopType: z.enum(['foreach', 'dowhile', 'dountil']).nullable().optional(),
+    loopConfig: z
+        .object({
+        collectionPath: z.string().optional(),
+        concurrency: z.number().int().min(1).max(20).optional(),
+        condition: z.string().optional(),
+        maxIterations: z.number().int().min(1).max(1000).optional(),
+    })
+        .nullable()
+        .optional(),
+});
+/** Workflow create/update payload */
+export const WorkflowDataSchema = z.object({
+    name: z.string().min(1, 'name is required'),
+    description: z.string().optional(),
+    environmentId: z.string().min(1, 'environmentId is required'),
+    steps: z
+        .array(WorkflowStepReferenceSchema)
+        .min(1, 'At least one step is required'),
+});
+export const WorkflowUpdateDataSchema = WorkflowDataSchema.partial().omit({
+    environmentId: true,
+});
+/** Organization create/update payload */
+export const CreateOrganizationDataSchema = z.object({
+    name: z.string().min(1, 'name is required'),
+    tier: z.enum(['Hobby', 'Professional', 'Scale', 'Enterprise']),
+});
+export const UpdateOrganizationDataSchema = CreateOrganizationDataSchema.partial();
+/** User↔Organization link payload */
+export const UserToOrgDataSchema = z.object({
+    userId: z.string().min(1, 'userId is required'),
+    organizationId: z.string().min(1, 'organizationId is required'),
+});
+/** Organization invite create payload */
+export const OrganizationInviteCreateDataSchema = z.object({
+    email: z.string().email('Invalid email'),
+    role: z.enum(['Owner', 'Member', 'Admin']).optional(),
+    expiresAt: z
+        .string()
+        .datetime({ message: 'expiresAt must be an ISO timestamp', offset: true })
+        .optional(),
+});
+/** Agent update payload (partial) */
+export const AgentUpdateDataSchema = AgentDataSchema.partial();
+/** Agent configuration patch payload (for Agent Sandbox editing) */
+export const AgentConfigurationPatchDataSchema = z.object({
+    instructions: z.string().min(1, 'instructions is required').optional(),
+    toolIds: z.array(z.string()).optional(),
+    quickActions: z.array(QuickActionSchema).optional(),
+});
+/** Embed Token create payload */
+export const EmbedTokenCreateDataSchema = z.object({
+    agentId: z.string().min(1, 'agentId is required'),
+    environmentId: z.string().min(1, 'environmentId is required'),
+    expiresInDays: z.number().min(1).max(365).optional().default(30),
+    allowedDomains: z.array(z.string()).optional(),
+});
+/** Thread query parameters */
+export const ThreadQuerySchema = z.object({
+    apiKey: z.string().min(1, 'apiKey is required'),
+    environmentId: z.string().min(1, 'environmentId is required'),
+    customerId: z.string().optional(),
+});
+/** Embed metadata query parameters */
+export const EmbedMetadataQuerySchema = z.object({
+    token: z.string().min(1, 'token is required'),
+});
+/** Agentic execution request payload */
+export const FunctionalAgentExecutionServiceRequestSchema = z.object({
+    apiKey: z.string().min(1, 'apiKey is required'),
+    environmentId: z.string().min(1, 'environmentId is required'),
+    userContext: z.string().optional(),
+    inputParameters: z.record(z.string(), z.any()).optional(),
+    backendJwtToken: z.string().optional(),
+    customerId: z.string().optional(),
+});
+/* V1 Public API Schemas */
+/** V1 Chat message structure (credentials in headers) */
+export const V1ChatMessageSchema = z.object({
+    agentId: z.string().min(1, 'agentId is required'),
+    environmentId: z.string().min(1, 'environmentId is required'),
+    messages: z
+        .array(z.object({
+        content: z.string().min(1, 'Message content is required'),
+    }))
+        .min(1, 'At least one message is required'),
+    customerId: z.string().optional(),
+    customInstructions: z.string().optional(),
+    logChannelId: z.string().optional(),
+    logToolScore: z.boolean().optional().default(false),
+    threadId: z.string().optional(),
+    uploadedFiles: UploadedFilesSchema.optional(),
+    screenState: ScreenStateSchema.optional(),
+});
+/** V1 HITL tool approval payload (credentials in headers) */
+export const V1HitlToolApprovalSchema = z.object({
+    runId: z.string().min(1, 'runId is required'),
+    environmentId: z.string().optional(),
+});
+/** V1 Agentic execution request payload (credentials in headers) */
+export const V1FunctionalAgentExecutionServiceRequestSchema = z.object({
+    agentId: z.string().min(1, 'agentId is required'),
+    environmentId: z.string().min(1, 'environmentId is required'),
+    userContext: z.string().optional(),
+    inputParameters: z.record(z.string(), z.any()).optional(),
+    customerId: z.string().optional(),
+});
+/** V1 Action data schema (credentials in headers) */
+export const V1ActionDataSchema = EndpointDataSchema.extend({
+    environmentId: z.string().min(1, 'environmentId is required'),
+});
+export const Validation = {
+    // primitives / helpers
+    requireString,
+    optionalString,
+    optionalBoolean,
+    requireArray,
+    requireMessageArray,
+    requireEnum,
+    optionalEnum,
+    validateRequiredParams,
+    validateEmail,
+    validateUrl,
+    // IDs
+    validateId, // pass kind: 'uuid' | 'objectId' | 'string'
+    validateUUID: (id, fieldName = 'id') => validateId(id, { fieldName, kind: 'uuid' }),
+    validateObjectId: (id, fieldName = 'id') => validateId(id, { fieldName, kind: 'objectId' }),
+    // Body parsing with Zod
+    validateBody,
+    // High-level parsers (return parsed, typed data)
+    parseAppData: (data) => validateBody(data, AppDataSchema),
+    // Environment parsers
+    parseEnvironmentCreateData: (data) => validateBody(data, EnvironmentCreateDataSchema),
+    parseEnvironmentUpdateData: (data) => validateBody(data, EnvironmentUpdateDataSchema),
+    // Endpoint parsers
+    parseEndpointData: (data) => validateBody(data, EndpointDataSchema),
+    parseEndpointCreateData: (data) => validateBody(data, EndpointCreateDataSchema),
+    parseEndpointUpdateData: (data) => validateBody(data, EndpointUpdateDataSchema),
+    parseEndpointExecuteData: (data) => validateBody(data, EndpointExecuteDataSchema),
+    // MCP Tool parser
+    parseMcpToolData: (data) => validateBody(data, McpToolDataSchema),
+    parseMcpToolUpdateData: (data) => validateBody(data, McpToolUpdateDataSchema),
+    // Agent parsers
+    parseAgentData: (data) => validateBody(data, AgentDataSchema),
+    parseAgentUpdateData: (data) => validateBody(data, AgentUpdateDataSchema),
+    parseAgentConfigurationPatchData: (data) => validateBody(data, AgentConfigurationPatchDataSchema),
+    parseAgentRAGCreateData: (data) => validateBody(data, AgentRAGCreateDataSchema),
+    parseAgentRAGDeleteData: (data) => validateBody(data, AgentRAGDeleteDataSchema),
+    // WorkflowStep parsers
+    parseWorkflowStepData: (data) => validateBody(data, WorkflowStepDataSchema),
+    parseWorkflowStepUpdateData: (data) => validateBody(data, WorkflowStepUpdateDataSchema),
+    // Workflow parsers
+    parseWorkflowData: (data) => validateBody(data, WorkflowDataSchema),
+    parseWorkflowUpdateData: (data) => validateBody(data, WorkflowUpdateDataSchema),
+    // Organization parsers
+    parseCreateOrganizationData: (data) => validateBody(data, CreateOrganizationDataSchema),
+    parseUpdateOrganizationData: (data) => validateBody(data, UpdateOrganizationDataSchema),
+    parseUserToOrgData: (data) => validateBody(data, UserToOrgDataSchema),
+    parseOrganizationInviteCreateData: (data) => validateBody(data, OrganizationInviteCreateDataSchema),
+    // Field parsers
+    parseFieldData: (data) => validateBody(data, FieldSchema),
+    parseFieldCollectionData: (data) => validateBody(data, FlexibleFieldsSchema),
+    // Chat parsers
+    parseChatMessageData: (data) => validateBody(data, ChatMessageSchema),
+    parseEphemeralChatMessageData: (data) => validateBody(data, EphemeralChatMessageSchema),
+    parseEmbedChatMessageData: (data) => validateBody(data, EmbedChatMessageSchema),
+    parsePingMateManualRunData: (data) => validateBody(data, PingMateManualRunSchema),
+    // HITL parsers
+    parseHitlToolApprovalData: (data) => validateBody(data, HitlToolApprovalSchema),
+    // Log parsers
+    parseLogEntryData: (data) => validateBody(data, LogEntrySchema),
+    parseLogData: (data) => validateBody(data, LogDataSchema),
+    // Enhanced endpoint parsers
+    parseEnhancedEndpointData: (data) => validateBody(data, EnhancedEndpointSchema),
+    // Other parsers
+    parseEmbedTokenCreateData: (data) => validateBody(data, EmbedTokenCreateDataSchema),
+    parseThreadQuery: (data) => validateBody(data, ThreadQuerySchema),
+    parseEmbedMetadataQuery: (data) => validateBody(data, EmbedMetadataQuerySchema),
+    parseFunctionalAgentExecutionServiceRequest: (data) => validateBody(data, FunctionalAgentExecutionServiceRequestSchema),
+    // V1 Public API parsers (header-based auth)
+    parseV1ChatMessageData: (data) => validateBody(data, V1ChatMessageSchema),
+    parseV1HitlToolApprovalData: (data) => validateBody(data, V1HitlToolApprovalSchema),
+    parseV1FunctionalAgentExecutionServiceRequest: (data) => validateBody(data, V1FunctionalAgentExecutionServiceRequestSchema),
+    parseV1ActionData: (data) => validateBody(data, V1ActionDataSchema),
+};
+/** Enhanced endpoint schema for auto-onboarding */
+export const EnhancedEndpointSchema = z.object({
+    systemInstructions: z
+        .string()
+        .describe('Clear, detailed instructions for what this endpoint does'),
+    inputFields: z
+        .record(z.string(), z.object({
+        type: FieldTypeSchema,
+        requiredByBackend: z.boolean(),
+        fieldInstructions: z
+            .string()
+            .describe('Specific instructions for this input field'),
+        format: z.string().optional(),
+        items: FieldSchema.optional(),
+        example: z.any().optional(),
+    }))
+        .describe('Enhanced input field definitions'),
+});