@ema.co/mcp-toolkit 0.2.0

package/dist/sdk/config.js

@@ -0,0 +1,136 @@
+/**
+ * Environment Configuration
+ *
+ * Defines Ema API environments and service settings.
+ * Used by both MCP server and CLI/service modes.
+ */
+import fs from "node:fs";
+import yaml from "js-yaml";
+import { z } from "zod";
+// ─────────────────────────────────────────────────────────────────────────────
+// Schema
+// ─────────────────────────────────────────────────────────────────────────────
+const EnvironmentSchema = z.object({
+    name: z.string().min(1),
+    baseUrl: z.string().url(),
+    bearerTokenEnv: z.string().min(1),
+    isMaster: z.boolean().optional().default(false),
+    // Deprecated but accepted for backward compatibility
+    userId: z.string().optional(),
+    templateIdMap: z.record(z.string()).optional(),
+});
+const SchedulerSchema = z.object({
+    intervalSeconds: z.number().int().positive().optional(),
+    cron: z.string().min(1).optional(),
+}).strict().refine((v) => v.cron || v.intervalSeconds, { message: "scheduler must set either intervalSeconds or cron" });
+const ServiceSchema = z.object({
+    stateDbPath: z.string().min(1).optional().default("./ema-state.sqlite3"),
+    scheduler: SchedulerSchema.optional(),
+}).strict();
+// Legacy schema for backward compatibility
+const LegacyRouteRuleSchema = z.object({
+    personaIds: z.array(z.string()).default([]),
+    targetEnvs: z.array(z.string()).default([]),
+    nameGlobs: z.array(z.string()).optional().default([]),
+    nameRegexes: z.array(z.string()).optional().default([]),
+    namePrefixes: z.array(z.string()).optional().default([]),
+}).passthrough();
+const AppConfigSchema = z.object({
+    environments: z.array(EnvironmentSchema).min(1),
+    service: ServiceSchema.optional(),
+    dryRun: z.boolean().optional().default(false),
+    verbose: z.boolean().optional().default(false),
+    // Legacy fields (kept for backward compatibility)
+    routing: z.array(LegacyRouteRuleSchema).optional(),
+    scheduler: SchedulerSchema.optional(),
+    stateDbPath: z.string().optional(),
+    eventSharedSecretEnv: z.string().optional(),
+}).refine((cfg) => {
+    // Validate at most one master
+    const masters = cfg.environments.filter((e) => e.isMaster);
+    return masters.length <= 1;
+}, { message: "At most one environment can be isMaster: true" });
+// ─────────────────────────────────────────────────────────────────────────────
+// Loading functions
+// ─────────────────────────────────────────────────────────────────────────────
+export function loadConfig(path) {
+    const raw = fs.readFileSync(path, "utf8");
+    const parsed = yaml.load(raw);
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("Invalid config YAML");
+    }
+    const res = AppConfigSchema.safeParse(parsed);
+    if (!res.success) {
+        const errors = res.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
+        throw new Error(`Invalid config: ${errors.join("; ")}`);
+    }
+    return res.data;
+}
+export function loadConfigOptional(path) {
+    try {
+        return loadConfig(path);
+    }
+    catch (e) {
+        if (e && typeof e === "object" && "code" in e && e.code === "ENOENT") {
+            return null;
+        }
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes("ENOENT"))
+            return null;
+        throw e;
+    }
+}
+export function loadConfigFromJsonEnv() {
+    const raw = process.env.EMA_CONFIG_JSON ?? process.env.EMA_AGENT_SYNC_CONFIG_JSON;
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("EMA_CONFIG_JSON is not valid JSON");
+    }
+    const res = validateConfig(parsed);
+    if (!res.ok) {
+        throw new Error(`Invalid EMA_CONFIG_JSON: ${res.errors.join("; ")}`);
+    }
+    return res.config;
+}
+export function validateConfig(input) {
+    const res = AppConfigSchema.safeParse(input);
+    if (!res.success) {
+        return { ok: false, errors: res.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`) };
+    }
+    return { ok: true, config: res.data };
+}
+export function configToYaml(cfg) {
+    return yaml.dump(cfg, { noRefs: true, sortKeys: true });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+export function resolveBearerToken(envVarName) {
+    const v = process.env[envVarName];
+    if (!v)
+        throw new Error(`Missing bearer token env var: ${envVarName}`);
+    // Strip "Bearer " prefix if user included it
+    const trimmed = v.trim();
+    if (trimmed.toLowerCase().startsWith("bearer ")) {
+        return trimmed.slice(7).trim();
+    }
+    return trimmed;
+}
+export function assertEnvVarsPresent(cfg) {
+    for (const e of cfg.environments) {
+        if (!process.env[e.bearerTokenEnv]) {
+            throw new Error(`Missing required env var for ${e.name}: ${e.bearerTokenEnv}`);
+        }
+    }
+}
+export function getMasterEnv(cfg) {
+    return cfg.environments.find((e) => e.isMaster);
+}
+export function getEnvByName(cfg, name) {
+    return cfg.environments.find((e) => e.name === name);
+}

package/dist/sdk/contracts.js

@@ -0,0 +1,429 @@
+/**
+ * API Contract Validation using Zod
+ *
+ * This module defines comprehensive Zod schemas for validating API responses at runtime.
+ * These schemas should match the OpenAPI spec (auto-generated from Pydantic).
+ *
+ * IMPORTANT: Keep these schemas in sync with the backend Pydantic models.
+ * Run `npm run check:contracts` to detect drift.
+ *
+ * Benefits:
+ * - Runtime type validation (catch malformed API responses)
+ * - Better error messages than TypeScript alone
+ * - Can generate TypeScript types with z.infer<>
+ *
+ * Usage:
+ *   import { PersonaDTOSchema, validateResponse } from "./contracts";
+ *
+ *   const result = validateResponse(PersonaDTOSchema, apiResponse);
+ *   // result is typed as PersonaDTO
+ */
+import { z } from "zod";
+// ─────────────────────────────────────────────────────────────────────────────
+// Base Types & Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+/** UUID string format - validates format but not actual UUID validity */
+export const UUIDSchema = z.string().min(1);
+/** ISO 8601 datetime string */
+export const DateTimeSchema = z.string().refine((val) => !isNaN(Date.parse(val)), { message: "Invalid datetime format" });
+/** Nullable wrapper for optional fields that can be explicitly null */
+export const nullable = (schema) => schema.nullable().optional();
+// ─────────────────────────────────────────────────────────────────────────────
+// Enums (match backend PersonaTriggerTypeEnum, PersonaStateEnum, etc.)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Persona trigger types - how the AI Employee is activated */
+export const PersonaTriggerTypeSchema = z.enum([
+    "TRIGGER_TYPE_CHATBOT",
+    "TRIGGER_TYPE_WEBAPP",
+    "TRIGGER_TYPE_GCHAT",
+    "TRIGGER_TYPE_SLACK",
+    "TRIGGER_TYPE_MSTEAMS",
+    "TRIGGER_TYPE_EMAIL",
+    "TRIGGER_TYPE_VOICE",
+    "TRIGGER_TYPE_DOCUMENT",
+    "TRIGGER_TYPE_DASHBOARD",
+    "TRIGGER_TYPE_ORCHESTRATION",
+    "TRIGGER_TYPE_API",
+]);
+/** Persona state - current operational status */
+export const PersonaStateSchema = z.enum([
+    "DISABLED_BY_USER",
+    "DISABLED_BY_SYSTEM",
+    "READY",
+    "DRAFT",
+]);
+/** Persona access level - who can use the AI Employee */
+export const PersonaAccessLevelSchema = z.enum([
+    "PERSONA_ACCESS_LEVEL_PRIVATE",
+    "PERSONA_ACCESS_LEVEL_TEAM",
+    "PERSONA_ACCESS_LEVEL_PUBLIC",
+]);
+/** Conversation source - where the conversation originated */
+export const ConversationSourceSchema = z.enum([
+    "webapp",
+    "chatbot",
+    "gchat",
+    "msteams",
+    "slack",
+    "email",
+    "voice",
+]);
+/** Message sentiment for feedback */
+export const SentimentSchema = z.enum(["positive", "negative", "neutral"]);
+/** Processing result status */
+export const ProcessingResultSchema = z.enum([
+    "success",
+    "warning",
+    "error",
+    "in_progress",
+    "indexing",
+]);
+// ─────────────────────────────────────────────────────────────────────────────
+// Welcome Messages
+// ─────────────────────────────────────────────────────────────────────────────
+export const WelcomeMessageSingleSchema = z.object({
+    display_text: z.string().optional(),
+    actual_prompt: z.string().optional(),
+}).passthrough();
+export const WelcomeMessageSectionSchema = z.object({
+    title: z.string().optional(),
+    messages: z.array(WelcomeMessageSingleSchema).optional(),
+}).passthrough();
+export const WelcomeMessageSchema = z.object({
+    sections: z.array(WelcomeMessageSectionSchema).optional(),
+    is_default: z.boolean().optional(),
+}).passthrough();
+// ─────────────────────────────────────────────────────────────────────────────
+// Persona (AI Employee)
+// ─────────────────────────────────────────────────────────────────────────────
+/** AI Employee (Persona) data transfer object */
+export const PersonaDTOSchema = z.object({
+    /** Unique identifier for the AI Employee */
+    id: z.string(),
+    /** ID of the template this persona was created from */
+    template_id: z.string().optional().nullable(),
+    templateId: z.string().optional().nullable(), // Legacy camelCase variant
+    /** ID of the workflow powering this AI Employee */
+    workflow_id: z.string().optional().nullable(),
+    /** Complete workflow definition */
+    workflow_def: z.record(z.unknown()).optional().nullable(),
+    /** Workflow interface defining inputs and outputs */
+    workflow_interface: z.record(z.unknown()).optional().nullable(),
+    /** Display name of the AI Employee */
+    name: z.string().optional(),
+    display_name: z.string().optional(),
+    /** Human-readable description */
+    description: z.string().optional().nullable(),
+    /** Protocol buffer configuration */
+    proto_config: z.record(z.unknown()).optional().nullable(),
+    /** Current state (READY, DRAFT, DISABLED_BY_USER, DISABLED_BY_SYSTEM) */
+    status: z.string().optional(),
+    computed_state: PersonaStateSchema.optional(),
+    /** Log of status changes and metadata */
+    status_log: z.record(z.unknown()).optional().nullable(),
+    /** Welcome messages displayed when starting a conversation */
+    welcome_messages: WelcomeMessageSchema.optional().nullable(),
+    /** Whether this persona supports projects */
+    has_project_template: z.boolean().optional(),
+    /** Access level controlling who can use this AI Employee */
+    access_level: z.string().optional(),
+    /** How this AI Employee is triggered */
+    trigger_type: z.string().optional(),
+    /** ID of the associated workflow dashboard */
+    workflow_dashboard_id: z.string().optional().nullable(),
+    /** Type of interaction supported */
+    persona_interaction_type: z.string().optional(),
+    /** Whether this AI Employee can be embedded */
+    embedding_enabled: z.boolean().optional(),
+    /** Whether user has enabled this persona */
+    enabled_by_user: z.boolean().optional(),
+    /** Creation timestamp */
+    created_at: DateTimeSchema.optional().nullable(),
+    /** Last update timestamp */
+    updated_at: DateTimeSchema.optional().nullable(),
+}).passthrough();
+/** Response from list personas endpoint */
+export const GetPersonasForTenantResponseSchema = z.object({
+    personas: z.array(PersonaDTOSchema).optional(),
+    configs: z.array(PersonaDTOSchema).optional(), // Legacy field
+}).passthrough();
+/** Request to create an AI Employee */
+export const CreatePersonaRequestSchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    template_id: z.string().optional(),
+    source_persona_id: z.string().optional(),
+    proto_config: z.record(z.unknown()).optional(),
+    welcome_messages: WelcomeMessageSchema.optional(),
+    trigger_type: z.string().optional(),
+});
+/** Response from create persona endpoint */
+export const CreatePersonaResponseSchema = z.object({
+    persona_id: z.string().optional(),
+    id: z.string().optional(),
+    status: z.string().optional(),
+}).passthrough();
+/** Request to update an AI Employee */
+export const UpdatePersonaRequestSchema = z.object({
+    persona_id: z.string(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    proto_config: z.record(z.unknown()).optional(),
+    welcome_messages: WelcomeMessageSchema.optional(),
+    workflow: z.record(z.unknown()).optional(),
+    embedding_enabled: z.boolean().optional(),
+    enabled_by_user: z.boolean().optional(),
+    status_log: z.record(z.unknown()).optional(),
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Actions (Agents in UI)
+// ─────────────────────────────────────────────────────────────────────────────
+export const ActionParameterTypeSchema = z.object({
+    well_known_type: z.number().optional(),
+    wellKnownType: z.number().optional(),
+    is_list: z.boolean().optional(),
+    isList: z.boolean().optional(),
+}).passthrough();
+export const ActionParameterSchema = z.object({
+    name: z.string().optional(),
+    description: z.string().optional(),
+    type: ActionParameterTypeSchema.optional(),
+    required: z.boolean().optional(),
+    default_value: z.unknown().optional(),
+}).passthrough();
+export const ActionDTOSchema = z.object({
+    /** Unique identifier for the action */
+    id: z.string(),
+    /** Display name of the action (shown as "Agent" in UI) */
+    name: z.string().optional(),
+    /** Description of what the action does */
+    description: z.string().optional(),
+    /** Category or type of the action */
+    category: z.string().optional(),
+    /** Input parameters for the action */
+    inputs: z.array(ActionParameterSchema).optional(),
+    /** Output parameters from the action */
+    outputs: z.array(ActionParameterSchema).optional(),
+    /** Whether the action is enabled */
+    enabled: z.boolean().optional(),
+    /** Whether the action is deprecated */
+    deprecated: z.boolean().optional(),
+    /** Version of the action */
+    version: z.string().optional(),
+    /** Icon URL or identifier */
+    icon: z.string().optional(),
+    /** Tags for categorization */
+    tags: z.array(z.string()).optional(),
+    /** The workflow this action belongs to */
+    workflow_id: z.string().optional(),
+    /** Creation timestamp */
+    created_at: DateTimeSchema.optional(),
+    /** Last update timestamp */
+    updated_at: DateTimeSchema.optional(),
+}).passthrough();
+export const ListActionsResponseSchema = z.object({
+    actions: z.array(ActionDTOSchema).optional(),
+}).passthrough();
+// ─────────────────────────────────────────────────────────────────────────────
+// Conversations
+// ─────────────────────────────────────────────────────────────────────────────
+export const ConversationDTOSchema = z.object({
+    id: z.string(),
+    display_name: z.string().optional().nullable(),
+    created_at: DateTimeSchema.optional().nullable(),
+    updated_at: DateTimeSchema.optional().nullable(),
+    is_blocked: z.boolean().optional().nullable(),
+    is_deleted: z.boolean().optional().nullable(),
+    persona_id: z.string().optional().nullable(),
+    persona_display_name: z.string().optional().nullable(),
+    persona_project_id: z.string().optional().nullable(),
+    persona_project_display_name: z.string().optional().nullable(),
+    status: z.string().optional().nullable(),
+    status_desc: z.string().optional().nullable(),
+}).passthrough();
+// ─────────────────────────────────────────────────────────────────────────────
+// Messages
+// ─────────────────────────────────────────────────────────────────────────────
+export const SnippetDTOSchema = z.object({
+    id: z.string().optional(),
+    type: z.string().optional(),
+    content: z.record(z.unknown()).optional(),
+    context: z.string().optional(),
+}).passthrough();
+export const MessageDTOSchema = z.object({
+    id: z.string(),
+    content_payload: z.record(z.string()).optional().nullable(),
+    sender_id: z.string().optional().nullable(),
+    created_at: DateTimeSchema.optional().nullable(),
+    updated_at: DateTimeSchema.optional().nullable(),
+    sentiment: SentimentSchema.optional().nullable(),
+    feedback_content: z.string().optional().nullable(),
+    snippets: z.array(SnippetDTOSchema).optional().nullable(),
+    processing_status: z.string().optional().nullable(),
+}).passthrough();
+// ─────────────────────────────────────────────────────────────────────────────
+// Pagination
+// ─────────────────────────────────────────────────────────────────────────────
+export const PaginationMetaSchema = z.object({
+    total: z.number(),
+    next_token: z.string().optional().nullable(),
+    prev_token: z.string().optional().nullable(),
+});
+export const PaginatedConversationsSchema = z.object({
+    conversations: z.array(ConversationDTOSchema),
+    meta: PaginationMetaSchema,
+});
+export const PaginatedMessagesSchema = z.object({
+    messages: z.array(MessageDTOSchema),
+    meta: PaginationMetaSchema,
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Projects
+// ─────────────────────────────────────────────────────────────────────────────
+export const ProjectDTOSchema = z.object({
+    id: z.string(),
+    persona_id: z.string().optional(),
+    display_name: z.string().optional(),
+    description: z.string().optional().nullable(),
+    state: z.string().optional(),
+    created_at: DateTimeSchema.optional().nullable(),
+    updated_at: DateTimeSchema.optional().nullable(),
+    settings: z.record(z.unknown()).optional().nullable(),
+}).passthrough();
+// ─────────────────────────────────────────────────────────────────────────────
+// Templates
+// ─────────────────────────────────────────────────────────────────────────────
+export const PersonaTemplateDTOSchema = z.object({
+    id: z.string(),
+    name: z.string().optional(),
+    description: z.string().optional().nullable(),
+    category: z.string().optional().nullable(),
+    agent_name: z.string().optional().nullable(),
+    trigger_type: z.string().optional().nullable(),
+    proto_config: z.record(z.unknown()).optional().nullable(),
+    workflow_def: z.record(z.unknown()).optional().nullable(),
+    has_project_template: z.boolean().optional(),
+    about_template: z.string().optional().nullable(),
+    is_system_template: z.boolean().optional().nullable(),
+}).passthrough();
+export const GetPersonaTemplatesResponseSchema = z.object({
+    templates: z.array(PersonaTemplateDTOSchema),
+    category_options: z.array(z.object({
+        value: z.string(),
+        name: z.string(),
+    })).optional(),
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Chat / Chatbot
+// ─────────────────────────────────────────────────────────────────────────────
+export const ChatbotMessageSchema = z.object({
+    message_id: z.string().optional(),
+    message_type: z.number().optional(),
+    content: z.string().optional(),
+    role: z.string().optional(),
+}).passthrough();
+export const ChatbotResponseSchema = z.object({
+    conversation_id: z.string().optional(),
+    message: ChatbotMessageSchema.optional(),
+    success: z.boolean().optional(),
+}).passthrough();
+export const ChatbotSDKConfigResponseSchema = z.object({
+    persona_id: z.string().optional(),
+    theme: z.record(z.unknown()).optional(),
+    header: z.record(z.unknown()).optional(),
+    welcome_message: z.record(z.unknown()).optional(),
+}).passthrough();
+// ─────────────────────────────────────────────────────────────────────────────
+// Error Responses
+// ─────────────────────────────────────────────────────────────────────────────
+export const ErrorDetailSchema = z.object({
+    field: z.string().optional().nullable(),
+    message: z.string(),
+    code: z.string().optional().nullable(),
+});
+export const ErrorResponseSchema = z.object({
+    error: z.string(),
+    message: z.string(),
+    details: z.array(ErrorDetailSchema).optional().nullable(),
+    request_id: z.string().optional().nullable(),
+    timestamp: DateTimeSchema.optional(),
+    path: z.string().optional().nullable(),
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Sync Metadata (MCP Toolkit internal)
+// ─────────────────────────────────────────────────────────────────────────────
+export const SyncMetadataSchema = z.object({
+    master_env: z.string(),
+    master_id: z.string(),
+    synced_at: z.string(),
+    master_fingerprint: z.string().optional(),
+    sync_run_id: z.string().optional(),
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Validate an API response against a schema.
+ * Returns the parsed data if valid, throws ZodError if invalid.
+ *
+ * @example
+ * const persona = validateResponse(PersonaDTOSchema, apiResponse);
+ */
+export function validateResponse(schema, data) {
+    return schema.parse(data);
+}
+/**
+ * Safely validate an API response.
+ * Returns { success: true, data } or { success: false, error }.
+ *
+ * @example
+ * const result = safeValidateResponse(PersonaDTOSchema, apiResponse);
+ * if (result.success) {
+ *   console.log(result.data.name);
+ * } else {
+ *   console.error(result.error.issues);
+ * }
+ */
+export function safeValidateResponse(schema, data) {
+    return schema.safeParse(data);
+}
+/**
+ * Validate a list of items, returning only the valid ones.
+ * Invalid items are logged as warnings but don't cause the entire validation to fail.
+ *
+ * @example
+ * const personas = validateList(PersonaDTOSchema, apiResponse.personas, "personas");
+ */
+export function validateList(schema, items, context) {
+    const valid = [];
+    for (let i = 0; i < items.length; i++) {
+        const result = schema.safeParse(items[i]);
+        if (result.success) {
+            valid.push(result.data);
+        }
+        else {
+            console.warn(`[contracts] Invalid item at index ${i}${context ? ` in ${context}` : ""}:`, result.error.issues.map(issue => `${issue.path.join(".")}: ${issue.message}`).join(", "));
+        }
+    }
+    return valid;
+}
+/**
+ * Type guard to check if a value matches a schema.
+ *
+ * @example
+ * if (isValid(PersonaDTOSchema, data)) {
+ *   // data is typed as PersonaDTO here
+ * }
+ */
+export function isValid(schema, data) {
+    return schema.safeParse(data).success;
+}
+/**
+ * Extract validation errors in a user-friendly format.
+ */
+export function formatValidationErrors(error) {
+    return error.issues.map(issue => {
+        const path = issue.path.join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    });
+}