@relayplane/sdk/dist/errors.d.ts

RelayPlane SDK - Local-first AI workflow engine for building multi-step AI workflows

/**
 * RelayPlane SDK Error System
 *
 * Provides structured, agent-friendly errors with actionable information.
 * All errors include:
 * - code: Machine-readable error code
 * - message: Human-readable summary
 * - why: Explanation of what went wrong
 * - fix: Exact code snippet to fix it
 * - repro_cmd: Command to reproduce/verify fix
 * - trace_id: Unique ID for debugging
 *
 * @packageDocumentation
 */
/**
 * Error codes for RelayPlane SDK.
 * Standardized codes for machine-readable error handling.
 */
export declare enum RelayPlaneErrorCode {
    PROVIDER_NOT_CONFIGURED = "PROVIDER_NOT_CONFIGURED",
    INVALID_API_KEY = "INVALID_API_KEY",
    MISSING_CONFIG = "MISSING_CONFIG",
    INVALID_CONFIG = "INVALID_CONFIG",
    POLICY_NOT_FOUND = "POLICY_NOT_FOUND",
    POLICY_INVALID = "POLICY_INVALID",
    COST_CAP_EXCEEDED = "COST_CAP_EXCEEDED",
    TOKEN_CAP_EXCEEDED = "TOKEN_CAP_EXCEEDED",
    WORKFLOW_INVALID = "WORKFLOW_INVALID",
    CIRCULAR_DEPENDENCY = "CIRCULAR_DEPENDENCY",
    MISSING_DEPENDENCY = "MISSING_DEPENDENCY",
    DUPLICATE_STEP = "DUPLICATE_STEP",
    STEP_FAILED = "STEP_FAILED",
    TIMEOUT = "TIMEOUT",
    PROVIDER_ERROR = "PROVIDER_ERROR",
    RATE_LIMITED = "RATE_LIMITED",
    FALLBACK_EXHAUSTED = "FALLBACK_EXHAUSTED",
    TEMPLATE_ERROR = "TEMPLATE_ERROR",
    VARIABLE_NOT_FOUND = "VARIABLE_NOT_FOUND",
    MCP_SERVER_NOT_FOUND = "MCP_SERVER_NOT_FOUND",
    MCP_TOOL_ERROR = "MCP_TOOL_ERROR",
    UNKNOWN_ERROR = "UNKNOWN_ERROR",
    INTERNAL_ERROR = "INTERNAL_ERROR"
}
/**
 * Structured error payload for JSON serialization.
 */
export interface RelayPlaneErrorPayload {
    /** Machine-readable error code */
    code: RelayPlaneErrorCode | string;
    /** Human-readable error summary */
    message: string;
    /** Explanation of what went wrong */
    why: string;
    /** Exact code snippet or action to fix the error */
    fix: string;
    /** Command to reproduce or verify the fix */
    repro_cmd?: string;
    /** Unique trace ID for debugging */
    trace_id: string;
    /** Optional link to relevant documentation */
    docs?: string;
    /** Optional additional context */
    context?: Record<string, unknown>;
}
/**
 * RelayPlane SDK error with structured, agent-friendly information.
 *
 * Extends Error with additional fields for debugging and self-correction:
 * - code: Machine-readable error code
 * - why: Explanation of what went wrong
 * - fix: Exact code snippet to fix it
 * - repro_cmd: Command to reproduce/verify fix
 * - trace_id: Unique ID for debugging
 *
 * @example
 * ```typescript
 * throw new RelayPlaneError({
 *   code: RelayPlaneErrorCode.PROVIDER_NOT_CONFIGURED,
 *   message: 'OpenAI provider is not configured',
 *   why: 'You tried to use "openai:gpt-4o" but no OpenAI API key was provided',
 *   fix: `relay.configure({
 *   providers: {
 *     openai: { apiKey: process.env.OPENAI_API_KEY }
 *   }
 * })`,
 *   repro_cmd: 'relay check --provider openai',
 *   docs: 'https://relayplane.com/docs/configuration#providers'
 * });
 * ```
 */
export declare class RelayPlaneError extends Error {
    /** Machine-readable error code */
    readonly code: RelayPlaneErrorCode | string;
    /** Explanation of what went wrong */
    readonly why: string;
    /** Exact code snippet or action to fix the error */
    readonly fix: string;
    /** Command to reproduce or verify the fix */
    readonly repro_cmd?: string;
    /** Unique trace ID for debugging */
    readonly trace_id: string;
    /** Optional link to relevant documentation */
    readonly docs?: string;
    /** Optional additional context */
    readonly context?: Record<string, unknown>;
    /** Original error that caused this error */
    readonly cause?: Error;
    constructor(payload: RelayPlaneErrorPayload, cause?: Error);
    /**
     * Converts the error to a JSON-serializable object.
     * Useful for logging and API responses.
     */
    toJSON(): RelayPlaneErrorPayload;
    /**
     * Returns a formatted string representation for logging.
     */
    toString(): string;
}
/**
 * Type guard to check if an error is a RelayPlaneError.
 */
export declare function isRelayPlaneError(error: unknown): error is RelayPlaneError;
/**
 * Creates an error for unconfigured provider.
 */
export declare function providerNotConfiguredError(provider: string, model: string, traceId?: string): RelayPlaneError;
/**
 * Creates an error for policy not found.
 */
export declare function policyNotFoundError(policyId: string, availablePolicies: string[], traceId?: string): RelayPlaneError;
/**
 * Creates an error for cost cap exceeded.
 */
export declare function costCapExceededError(policyId: string, actualCost: number, maxCost: number, traceId?: string): RelayPlaneError;
/**
 * Creates an error for circular dependency.
 */
export declare function circularDependencyError(workflowName: string, cycle: string[], traceId?: string): RelayPlaneError;
/**
 * Creates an error for step execution failure.
 */
export declare function stepFailedError(stepName: string, workflowName: string, errorMessage: string, attempts: number, traceId?: string): RelayPlaneError;
/**
 * Creates an error for timeout.
 */
export declare function timeoutError(context: string, timeoutMs: number, traceId?: string): RelayPlaneError;
/**
 * Creates a generic error from an unknown error.
 */
export declare function fromUnknownError(error: unknown, traceId?: string): RelayPlaneError;
//# sourceMappingURL=errors.d.ts.map