@elevasis/sdk 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -289,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
@@ -850,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,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 */
@@ -1433,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.
@@ -1471,5 +1873,5 @@ declare class ToolingError extends ExecutionError {
     constructor(errorType: string, message: string, details?: unknown);
 }
 
-export { ExecutionError, StepType, ToolingError };
+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 };