@elevasis/sdk 0.1.0 → 0.3.1

package/dist/index.d.ts

@@ -1,79 +1,5 @@
 import { z } from 'zod';
 
-/**
- * Error categories for observability grouping and classification.
- * Used to categorize errors in the execution_errors table metadata.
- */
-type ExecutionErrorCategory = 'llm' | 'tool' | 'workflow' | 'agent' | 'validation' | 'system';
-/**
- * Abstract base class for all execution engine errors.
- * Enforces contract for execution_errors table insertion with explicit type,
- * severity, category, and context properties.
- *
- * All execution engine errors MUST extend this class to ensure proper error
- * tracking and observability in the execution_errors table.
- *
- * @example
- * ```typescript
- * export class MyExecutionError extends ExecutionError {
- *   readonly type = 'my_execution_error' as const
- *   readonly severity = 'warning' as const
- *   readonly category = 'workflow' as const
- *
- *   constructor(message: string, context?: Record<string, unknown>) {
- *     super(message, context)
- *   }
- * }
- * ```
- */
-declare abstract class ExecutionError extends Error {
-    /**
-     * Error type identifier for execution_errors table.
-     * Should be a unique, snake_case string that identifies this specific error class.
-     * Used for filtering, aggregation, and error-specific handling in observability systems.
-     */
-    abstract readonly type: string;
-    /**
-     * Error severity level for execution_errors table.
-     * - critical: System failures, auth issues, resource exhaustion - execution cannot continue
-     * - warning: Transient failures, configuration errors - execution may retry or requires user correction
-     * - info: Validation failures, expected user errors - user/developer action needed
-     */
-    abstract readonly severity: 'critical' | 'warning' | 'info';
-    /**
-     * Error category for observability grouping.
-     * Used to categorize errors in dashboards and analytics.
-     */
-    abstract readonly category: ExecutionErrorCategory;
-    /**
-     * Additional context/metadata for the error.
-     * Stored in execution_errors.metadata JSONB column.
-     */
-    readonly context?: Record<string, unknown>;
-    /**
-     * @param message - Human-readable error message
-     * @param context - Additional context/metadata for observability
-     */
-    constructor(message: string, context?: Record<string, unknown>);
-    /**
-     * Indicates whether this error type is retryable.
-     * Default: false (safe default - only retry when explicitly safe to do so)
-     *
-     * Subclasses should override to return true for retryable scenarios:
-     * - Network/infrastructure errors (exponential backoff)
-     * - Rate limiting (linear backoff)
-     * - Service availability (exponential backoff)
-     * - Circuit breaker (circuit breaker's own delay)
-     *
-     * DO NOT retry:
-     * - Authentication/authorization errors
-     * - Validation errors
-     * - Configuration errors
-     * - Resource exhaustion errors
-     */
-    isRetryable(): boolean;
-}
-
 /**
  * Workflow-specific logging types
  */
@@ -363,6 +289,232 @@ interface FormSchema {
     layout?: 'vertical' | 'horizontal' | 'grid';
 }
 
+/**
+ * Command View Types
+ *
+ * Unified type definitions for the Command View graph visualization.
+ * These types are used by both backend serialization and frontend rendering.
+ *
+ * Command View shows the resource graph: agents, workflows, triggers, integrations,
+ * external resources, and human checkpoints with their relationships.
+ */
+
+/**
+ * Extended agent metadata for Command View
+ * Includes model and capability information for graph display
+ */
+interface CommandViewAgent extends ResourceDefinition {
+    type: 'agent';
+    modelProvider: string;
+    modelId: string;
+    toolCount: number;
+    hasKnowledgeMap: boolean;
+    hasMemory: boolean;
+    sessionCapable: boolean;
+}
+/**
+ * Extended workflow metadata for Command View
+ * Includes step information for graph display
+ */
+interface CommandViewWorkflow extends ResourceDefinition {
+    type: 'workflow';
+    stepCount: number;
+    entryPoint: string;
+}
+/**
+ * Relationship types between resources
+ *
+ * - triggers: Resource initiates/starts another resource (orange)
+ * - uses: Resource uses an integration (teal)
+ * - approval: Resource requires human approval (yellow)
+ */
+type RelationshipType = 'triggers' | 'uses' | 'approval';
+/**
+ * Command View edge (relationship between resources)
+ */
+interface CommandViewEdge {
+    id: string;
+    source: string;
+    target: string;
+    relationship: RelationshipType;
+    label?: string;
+}
+/**
+ * Command View data structure
+ * Complete graph data for visualization
+ *
+ * Backend serializes this once at startup and serves it via /command-view endpoint.
+ * Frontend consumes this directly for graph rendering.
+ */
+interface CommandViewData {
+    workflows: CommandViewWorkflow[];
+    agents: CommandViewAgent[];
+    triggers: TriggerDefinition[];
+    integrations: IntegrationDefinition[];
+    externalResources: ExternalResourceDefinition[];
+    humanCheckpoints: HumanCheckpointDefinition[];
+    edges: CommandViewEdge[];
+    domainDefinitions?: DomainDefinition[];
+}
+
+/**
+ * Serialized Registry Types
+ *
+ * Pre-computed JSON-safe types for API responses and Command View.
+ * Serialization happens once at API startup, enabling instant response times.
+ */
+
+/**
+ * Serialized form field for API responses
+ */
+interface SerializedFormField {
+    name: string;
+    label: string;
+    type: FormFieldType;
+    defaultValue?: unknown;
+    required?: boolean;
+    placeholder?: string;
+    description?: string;
+    options?: Array<{
+        label: string;
+        value: string | number;
+    }>;
+    min?: number;
+    max?: number;
+}
+/**
+ * Serialized form schema for API responses
+ */
+interface SerializedFormSchema {
+    title?: string;
+    description?: string;
+    fields: SerializedFormField[];
+    layout?: 'vertical' | 'horizontal' | 'grid';
+}
+/**
+ * Serialized execution form schema for API responses
+ */
+interface SerializedExecutionFormSchema extends SerializedFormSchema {
+    fieldMappings?: Record<string, string>;
+    submitButton?: {
+        label?: string;
+        loadingLabel?: string;
+        confirmMessage?: string;
+    };
+}
+/**
+ * Serialized schedule config for API responses
+ */
+interface SerializedScheduleConfig {
+    enabled: boolean;
+    defaultSchedule?: string;
+    allowedPatterns?: string[];
+}
+/**
+ * Serialized webhook config for API responses
+ */
+interface SerializedWebhookConfig {
+    enabled: boolean;
+    payloadSchema?: unknown;
+}
+/**
+ * Serialized execution interface for API responses
+ */
+interface SerializedExecutionInterface {
+    form: SerializedExecutionFormSchema;
+    schedule?: SerializedScheduleConfig;
+    webhook?: SerializedWebhookConfig;
+}
+/**
+ * Serialized agent definition (JSON-safe)
+ * Result of serializeDefinition(AgentDefinition)
+ */
+interface SerializedAgentDefinition {
+    config: {
+        resourceId: string;
+        name: string;
+        description: string;
+        version: string;
+        type: 'agent';
+        status: 'dev' | 'prod';
+        systemPrompt: string;
+        constraints?: {
+            maxIterations?: number;
+            timeout?: number;
+            maxSessionMemoryKeys?: number;
+            maxMemoryTokens?: number;
+        };
+        sessionCapable?: boolean;
+        memoryPreferences?: string;
+    };
+    modelConfig: {
+        provider: string;
+        model: string;
+        apiKey: string;
+        temperature: number;
+        maxTokens: number;
+        topP?: number;
+        modelOptions?: Record<string, unknown>;
+    };
+    contract: {
+        inputSchema: object;
+        outputSchema?: object;
+    };
+    tools: Array<{
+        name: string;
+        description: string;
+        inputSchema?: object;
+        outputSchema?: object;
+    }>;
+    knowledgeMap?: {
+        nodeCount: number;
+        nodes: Array<{
+            id: string;
+            description: string;
+            loaded: boolean;
+            hasPrompt: boolean;
+        }>;
+    };
+    metricsConfig?: object;
+    interface?: SerializedExecutionInterface;
+}
+/**
+ * Serialized workflow definition (JSON-safe)
+ * Result of serializeDefinition(WorkflowDefinition)
+ */
+interface SerializedWorkflowDefinition {
+    config: {
+        resourceId: string;
+        name: string;
+        description: string;
+        version: string;
+        type: 'workflow';
+        status: 'dev' | 'prod';
+    };
+    entryPoint: string;
+    steps: Array<{
+        id: string;
+        name: string;
+        description: string;
+        inputSchema?: object;
+        outputSchema?: object;
+        next: {
+            type: 'linear' | 'conditional';
+            target?: string;
+            routes?: Array<{
+                target: string;
+            }>;
+            default?: string;
+        } | null;
+    }>;
+    contract: {
+        inputSchema: object;
+        outputSchema?: object;
+    };
+    metricsConfig?: object;
+    interface?: SerializedExecutionInterface;
+}
+
 /**
  * Model Configuration
  * Centralized model information, configuration, options, constraints, and validation
@@ -525,16 +677,16 @@ interface WorkflowStepDefinition {
     description: string;
 }
 type StepHandler = (input: unknown, context: ExecutionContext) => Promise<unknown>;
-declare enum StepType {
+declare enum StepType$1 {
     LINEAR = "linear",
     CONDITIONAL = "conditional"
 }
 interface LinearNext {
-    type: StepType.LINEAR;
+    type: StepType$1.LINEAR;
     target: string;
 }
 interface ConditionalNext {
-    type: StepType.CONDITIONAL;
+    type: StepType$1.CONDITIONAL;
     routes: Array<{
         condition: (data: unknown) => boolean;
         target: string;
@@ -924,6 +1076,157 @@ interface OrganizationResources {
     /** Human checkpoint definitions - human decision points in automation */
     humanCheckpoints?: HumanCheckpointDefinition[];
 }
+/**
+ * Organization Registry type
+ */
+type OrganizationRegistry = Record<string, OrganizationResources>;
+declare class ResourceRegistry {
+    private registry;
+    /**
+     * Pre-serialized organization data cache
+     * Computed once at construction, never invalidated (static registry)
+     */
+    private serializedCache;
+    constructor(registry: OrganizationRegistry);
+    /**
+     * Validates registry on construction
+     * - Checks for duplicate resourceIds within organizations
+     * - Validates model configurations against constraints
+     * - Validates ExecutionInterface matches inputSchema
+     * @throws Error if validation fails
+     */
+    private validateRegistry;
+    /**
+     * Validates relationship declarations reference valid resources
+     * Runs at API server startup - fails fast in development
+     * @throws Error if validation fails
+     */
+    private validateRelationships;
+    /**
+     * Get a resource definition by ID
+     * Returns full definition (WorkflowDefinition or AgentDefinition)
+     * Check definition.config.type to determine if it's a workflow or agent
+     */
+    getResourceDefinition(organizationName: string, resourceId: string): WorkflowDefinition | AgentDefinition | null;
+    /**
+     * List all resources for an organization
+     * Returns ResourceDefinition metadata (not full definitions)
+     *
+     * Environment filtering (automatic):
+     * - Development: Returns all resources (dev + prod)
+     * - Production: Returns only prod resources (filters out dev)
+     */
+    listResourcesForOrganization(organizationName: string, environment?: ResourceStatus): ResourceList;
+    /**
+     * List all resources from all organizations
+     * NOTE: For debugging only - returns raw registry data
+     */
+    listAllResources(): OrganizationRegistry;
+    /**
+     * Get triggers for an organization
+     * @param organizationName - Organization name
+     * @returns Array of trigger definitions (empty if none defined)
+     */
+    getTriggers(organizationName: string): TriggerDefinition[];
+    /**
+     * Get integrations for an organization
+     * @param organizationName - Organization name
+     * @returns Array of integration definitions (empty if none defined)
+     */
+    getIntegrations(organizationName: string): IntegrationDefinition[];
+    /**
+     * Get resource relationships for an organization
+     * @param organizationName - Organization name
+     * @returns Resource relationships map (undefined if none defined)
+     */
+    getRelationships(organizationName: string): ResourceRelationships | undefined;
+    /**
+     * Get a specific trigger by ID
+     * @param organizationName - Organization name
+     * @param triggerId - Trigger ID
+     * @returns Trigger definition or null if not found
+     */
+    getTrigger(organizationName: string, triggerId: string): TriggerDefinition | null;
+    /**
+     * Get a specific integration by ID
+     * @param organizationName - Organization name
+     * @param integrationId - Integration ID
+     * @returns Integration definition or null if not found
+     */
+    getIntegration(organizationName: string, integrationId: string): IntegrationDefinition | null;
+    /**
+     * Get external resources for an organization
+     * @param organizationName - Organization name
+     * @returns Array of external resource definitions (empty if none defined)
+     */
+    getExternalResources(organizationName: string): ExternalResourceDefinition[];
+    /**
+     * Get a specific external resource by ID
+     * @param organizationName - Organization name
+     * @param externalId - External resource ID
+     * @returns External resource definition or null if not found
+     */
+    getExternalResource(organizationName: string, externalId: string): ExternalResourceDefinition | null;
+    /**
+     * Get human checkpoints for an organization
+     * @param organizationName - Organization name
+     * @returns Array of human checkpoint definitions (empty if none defined)
+     */
+    getHumanCheckpoints(organizationName: string): HumanCheckpointDefinition[];
+    /**
+     * Get a specific human checkpoint by ID
+     * @param organizationName - Organization name
+     * @param humanCheckpointId - Human checkpoint ID
+     * @returns Human checkpoint definition or null if not found
+     */
+    getHumanCheckpoint(organizationName: string, humanCheckpointId: string): HumanCheckpointDefinition | null;
+    /**
+     * Get serialized resource definition (instant lookup)
+     * Use for API responses - returns pre-computed JSON-safe structure
+     *
+     * @param organizationName - Organization name
+     * @param resourceId - Resource ID
+     * @returns Serialized definition or null if not found
+     */
+    getSerializedDefinition(organizationName: string, resourceId: string): SerializedAgentDefinition | SerializedWorkflowDefinition | null;
+    /**
+     * Get resource list for organization (instant lookup)
+     * Use for /resources endpoint - returns pre-computed ResourceDefinition array
+     *
+     * @param organizationName - Organization name
+     * @returns Resource list with workflows, agents, and total count
+     */
+    getResourceList(organizationName: string): {
+        workflows: ResourceDefinition[];
+        agents: ResourceDefinition[];
+        total: number;
+    };
+    /**
+     * Get Command View data for organization (instant lookup)
+     * Use for /command-view endpoint - returns complete graph data
+     *
+     * @param organizationName - Organization name
+     * @returns Command View data with nodes and edges
+     */
+    getCommandViewData(organizationName: string): CommandViewData;
+    /**
+     * List resources that have UI interfaces configured
+     * Used by Execution Runner Catalog UI
+     *
+     * @param organizationName - Organization name
+     * @param environment - Optional environment filter ('dev' or 'prod')
+     * @returns Array of resources with interfaces
+     */
+    listExecutable(organizationName: string, environment?: 'dev' | 'prod'): Array<{
+        resourceId: string;
+        resourceName: string;
+        resourceType: 'workflow' | 'agent';
+        description?: string;
+        status: 'dev' | 'prod';
+        version: string;
+        interface: SerializedExecutionInterface;
+    }>;
+}
 
 /**
  * MetricsCollector
@@ -1162,44 +1465,6 @@ interface Tool {
  * Used across platform tools and integration tools
  */
 type ToolingErrorType = 'service_unavailable' | 'permission_denied' | 'adapter_not_found' | 'method_not_found' | 'tool_not_found' | 'credentials_missing' | 'credentials_invalid' | 'rate_limit_exceeded' | 'server_unavailable' | 'auth_error' | 'api_error' | 'validation_error' | 'network_error' | 'timeout_error' | 'unknown_error';
-/**
- * Tooling error class
- * Provides structured error information for tool failures across all tool types
- *
- * Severity mapping:
- * - critical: credentials_missing, credentials_invalid, permission_denied, auth_error,
- *            adapter_not_found, method_not_found, tool_not_found
- * - info: validation_error
- * - warning: All other types (retryable transient errors)
- *
- * Category: tool (tool execution errors)
- */
-declare class ToolingError extends ExecutionError {
-    readonly errorType: ToolingErrorType;
-    readonly details?: unknown | undefined;
-    readonly type: "tooling_error";
-    readonly category: "tool";
-    constructor(errorType: ToolingErrorType, message: string, details?: unknown | undefined);
-    /**
-     * Derive severity based on error type
-     */
-    get severity(): 'critical' | 'warning' | 'info';
-    /**
-     * Check if error is retryable
-     */
-    isRetryable(): boolean;
-    /**
-     * Convert to JSON for logging
-     */
-    toJSON(): {
-        name: string;
-        type: ToolingErrorType;
-        message: string;
-        severity: "critical" | "warning" | "info";
-        category: "tool";
-        details: unknown;
-    };
-}
 
 /**
  * Supported integration types
@@ -1274,6 +1539,17 @@ interface DomainDefinition {
     /** Optional Tabler icon name (e.g., 'IconHeadset') */
     icon?: string;
 }
+/**
+ * Resource list for organization
+ * Returns ResourceDefinition metadata (not full definitions)
+ */
+interface ResourceList {
+    workflows: ResourceDefinition[];
+    agents: ResourceDefinition[];
+    total: number;
+    organizationName: string;
+    environment?: 'dev' | 'prod';
+}
 /** Webhook provider identifiers */
 type WebhookProviderType = 'cal-com' | 'fillout' | 'stripe' | 'signature-api' | 'instantly' | 'test';
 /** Webhook trigger configuration */
@@ -1545,6 +1821,20 @@ declare const DOMAINS: {
  */
 type ResourceDomain = (typeof DOMAINS)[keyof typeof DOMAINS];
 
+/**
+ * Registry Validation Utilities
+ *
+ * Centralized validation logic for ResourceRegistry.
+ * All validation runs at API startup - fails fast in development.
+ */
+
+declare class RegistryValidationError extends Error {
+    readonly orgName: string;
+    readonly resourceId: string | null;
+    readonly field: string | null;
+    constructor(orgName: string, resourceId: string | null, field: string | null, message: string);
+}
+
 /**
  * Project configuration for an external developer project.
  * Defined in elevas.config.ts at the project root.
@@ -1557,5 +1847,31 @@ interface ElevasConfig {
     };
 }
 
-export { ExecutionError, StepType, ToolingError };
+/**
+ * Runtime values for SDK developers.
+ *
+ * These are standalone definitions (not re-exported from @repo/core)
+ * to avoid pulling in the entire execution engine dependency tree (~3.5MB).
+ * Values are identical to their @repo/core counterparts.
+ */
+/** Step connection type for multi-step workflows */
+declare enum StepType {
+    LINEAR = "linear",
+    CONDITIONAL = "conditional"
+}
+/** Base error class for execution errors */
+declare class ExecutionError extends Error {
+    readonly type: string;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, context?: Record<string, unknown>);
+    isRetryable(): boolean;
+}
+/** Error thrown from tool execution handlers */
+declare class ToolingError extends ExecutionError {
+    readonly errorType: string;
+    readonly details?: unknown;
+    constructor(errorType: string, message: string, details?: unknown);
+}
+
+export { ExecutionError, RegistryValidationError, ResourceRegistry, StepType, ToolingError };
 export type { AgentConfig, AgentConstraints, AgentDefinition, ConditionalNext, Contract, DomainDefinition, ElevasConfig, EventTriggerConfig, ExecutionContext, ExecutionInterface, ExecutionMetadata, FormField, FormFieldType, FormSchema, IntegrationDefinition, LLMModel, LinearNext, ModelConfig, NextConfig, OrganizationResources, ResourceDefinition, ResourceDomain, ResourceMetricsConfig, ResourceStatus, ResourceType, ScheduleTriggerConfig, StepHandler, Tool, ToolExecutionOptions, ToolingErrorType, TriggerConfig, TriggerDefinition, WebhookProviderType, WebhookTriggerConfig, WorkflowConfig, WorkflowDefinition, WorkflowStep };