@rainfall-devkit/sdk 0.2.2 → 0.2.3

package/dist/daemon/index.js

@@ -37,6 +37,164 @@ var init_cjs_shims = __esm({
   }
 });
 
+// src/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  AuthenticationError: () => AuthenticationError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  RainfallError: () => RainfallError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  TimeoutError: () => TimeoutError,
+  ToolNotFoundError: () => ToolNotFoundError,
+  ValidationError: () => ValidationError,
+  parseErrorResponse: () => parseErrorResponse
+});
+function parseErrorResponse(response, data) {
+  const statusCode = response.status;
+  if (statusCode === 429) {
+    const retryAfter = parseInt(response.headers.get("retry-after") || "60", 10);
+    const limit = parseInt(response.headers.get("x-ratelimit-limit") || "0", 10);
+    const remaining = parseInt(response.headers.get("x-ratelimit-remaining") || "0", 10);
+    const resetHeader = response.headers.get("x-ratelimit-reset");
+    const resetAt = resetHeader ? new Date(parseInt(resetHeader, 10) * 1e3) : void 0;
+    return new RateLimitError(
+      typeof data === "object" && data && "message" in data ? String(data.message) : "Rate limit exceeded",
+      retryAfter,
+      limit,
+      remaining,
+      resetAt
+    );
+  }
+  switch (statusCode) {
+    case 401:
+      return new AuthenticationError(
+        typeof data === "object" && data && "message" in data ? String(data.message) : "Invalid API key"
+      );
+    case 404:
+      return new NotFoundError(
+        typeof data === "object" && data && "resource" in data ? String(data.resource) : "Resource",
+        typeof data === "object" && data && "identifier" in data ? String(data.identifier) : void 0
+      );
+    case 400:
+      return new ValidationError(
+        typeof data === "object" && data && "message" in data ? String(data.message) : "Invalid request",
+        typeof data === "object" && data && "details" in data ? data.details : void 0
+      );
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+      return new ServerError(
+        typeof data === "object" && data && "message" in data ? String(data.message) : "Server error",
+        statusCode
+      );
+    default:
+      return new RainfallError(
+        typeof data === "object" && data && "message" in data ? String(data.message) : `HTTP ${statusCode}`,
+        "UNKNOWN_ERROR",
+        statusCode,
+        typeof data === "object" ? data : void 0
+      );
+  }
+}
+var RainfallError, AuthenticationError, RateLimitError, ValidationError, NotFoundError, ServerError, TimeoutError, NetworkError, ToolNotFoundError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    "use strict";
+    init_cjs_shims();
+    RainfallError = class _RainfallError extends Error {
+      constructor(message, code, statusCode, details) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = "RainfallError";
+        Object.setPrototypeOf(this, _RainfallError.prototype);
+      }
+      toJSON() {
+        return {
+          name: this.name,
+          code: this.code,
+          message: this.message,
+          statusCode: this.statusCode,
+          details: this.details
+        };
+      }
+    };
+    AuthenticationError = class _AuthenticationError extends RainfallError {
+      constructor(message = "Invalid API key", details) {
+        super(message, "AUTHENTICATION_ERROR", 401, details);
+        this.name = "AuthenticationError";
+        Object.setPrototypeOf(this, _AuthenticationError.prototype);
+      }
+    };
+    RateLimitError = class _RateLimitError extends RainfallError {
+      retryAfter;
+      limit;
+      remaining;
+      resetAt;
+      constructor(message = "Rate limit exceeded", retryAfter = 60, limit = 0, remaining = 0, resetAt) {
+        super(message, "RATE_LIMIT_ERROR", 429, { retryAfter, limit, remaining });
+        this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
+        this.limit = limit;
+        this.remaining = remaining;
+        this.resetAt = resetAt || new Date(Date.now() + retryAfter * 1e3);
+        Object.setPrototypeOf(this, _RateLimitError.prototype);
+      }
+    };
+    ValidationError = class _ValidationError extends RainfallError {
+      constructor(message, details) {
+        super(message, "VALIDATION_ERROR", 400, details);
+        this.name = "ValidationError";
+        Object.setPrototypeOf(this, _ValidationError.prototype);
+      }
+    };
+    NotFoundError = class _NotFoundError extends RainfallError {
+      constructor(resource, identifier) {
+        super(
+          `${resource}${identifier ? ` '${identifier}'` : ""} not found`,
+          "NOT_FOUND_ERROR",
+          404,
+          { resource, identifier }
+        );
+        this.name = "NotFoundError";
+        Object.setPrototypeOf(this, _NotFoundError.prototype);
+      }
+    };
+    ServerError = class _ServerError extends RainfallError {
+      constructor(message = "Internal server error", statusCode = 500) {
+        super(message, "SERVER_ERROR", statusCode);
+        this.name = "ServerError";
+        Object.setPrototypeOf(this, _ServerError.prototype);
+      }
+    };
+    TimeoutError = class _TimeoutError extends RainfallError {
+      constructor(timeoutMs) {
+        super(`Request timed out after ${timeoutMs}ms`, "TIMEOUT_ERROR", 408);
+        this.name = "TimeoutError";
+        Object.setPrototypeOf(this, _TimeoutError.prototype);
+      }
+    };
+    NetworkError = class _NetworkError extends RainfallError {
+      constructor(message = "Network error", details) {
+        super(message, "NETWORK_ERROR", void 0, details);
+        this.name = "NetworkError";
+        Object.setPrototypeOf(this, _NetworkError.prototype);
+      }
+    };
+    ToolNotFoundError = class _ToolNotFoundError extends RainfallError {
+      constructor(toolId) {
+        super(`Tool '${toolId}' not found`, "TOOL_NOT_FOUND", 404, { toolId });
+        this.name = "ToolNotFoundError";
+        Object.setPrototypeOf(this, _ToolNotFoundError.prototype);
+      }
+    };
+  }
+});
+
 // src/cli/config.ts
 var config_exports = {};
 __export(config_exports, {
@@ -154,137 +312,166 @@ init_cjs_shims();
 
 // src/client.ts
 init_cjs_shims();
+init_errors();
 
-// src/errors.ts
+// src/validation.ts
 init_cjs_shims();
-var RainfallError = class _RainfallError extends Error {
-  constructor(message, code, statusCode, details) {
-    super(message);
-    this.code = code;
-    this.statusCode = statusCode;
-    this.details = details;
-    this.name = "RainfallError";
-    Object.setPrototypeOf(this, _RainfallError.prototype);
-  }
-  toJSON() {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      statusCode: this.statusCode,
-      details: this.details
-    };
-  }
-};
-var AuthenticationError = class _AuthenticationError extends RainfallError {
-  constructor(message = "Invalid API key", details) {
-    super(message, "AUTHENTICATION_ERROR", 401, details);
-    this.name = "AuthenticationError";
-    Object.setPrototypeOf(this, _AuthenticationError.prototype);
-  }
-};
-var RateLimitError = class _RateLimitError extends RainfallError {
-  retryAfter;
-  limit;
-  remaining;
-  resetAt;
-  constructor(message = "Rate limit exceeded", retryAfter = 60, limit = 0, remaining = 0, resetAt) {
-    super(message, "RATE_LIMIT_ERROR", 429, { retryAfter, limit, remaining });
-    this.name = "RateLimitError";
-    this.retryAfter = retryAfter;
-    this.limit = limit;
-    this.remaining = remaining;
-    this.resetAt = resetAt || new Date(Date.now() + retryAfter * 1e3);
-    Object.setPrototypeOf(this, _RateLimitError.prototype);
-  }
-};
-var ValidationError = class _ValidationError extends RainfallError {
-  constructor(message, details) {
-    super(message, "VALIDATION_ERROR", 400, details);
-    this.name = "ValidationError";
-    Object.setPrototypeOf(this, _ValidationError.prototype);
-  }
-};
-var NotFoundError = class _NotFoundError extends RainfallError {
-  constructor(resource, identifier) {
-    super(
-      `${resource}${identifier ? ` '${identifier}'` : ""} not found`,
-      "NOT_FOUND_ERROR",
-      404,
-      { resource, identifier }
-    );
-    this.name = "NotFoundError";
-    Object.setPrototypeOf(this, _NotFoundError.prototype);
-  }
-};
-var ServerError = class _ServerError extends RainfallError {
-  constructor(message = "Internal server error", statusCode = 500) {
-    super(message, "SERVER_ERROR", statusCode);
-    this.name = "ServerError";
-    Object.setPrototypeOf(this, _ServerError.prototype);
-  }
-};
-var TimeoutError = class _TimeoutError extends RainfallError {
-  constructor(timeoutMs) {
-    super(`Request timed out after ${timeoutMs}ms`, "TIMEOUT_ERROR", 408);
-    this.name = "TimeoutError";
-    Object.setPrototypeOf(this, _TimeoutError.prototype);
+init_errors();
+var schemaCache = /* @__PURE__ */ new Map();
+var CACHE_TTL_MS = 5 * 60 * 1e3;
+async function fetchToolSchema(client, toolId) {
+  const cached = schemaCache.get(toolId);
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+    return cached.schema;
+  }
+  const response = await client.request(
+    `/olympic/subscribers/me/nodes/${toolId}/params`
+  );
+  if (!response.success || !response.params) {
+    throw new ValidationError(`Failed to fetch schema for tool '${toolId}'`);
+  }
+  schemaCache.set(toolId, { schema: response.params, timestamp: Date.now() });
+  return response.params;
+}
+function validateParams(schema, params, toolId) {
+  const errors = [];
+  const parameters = schema.parameters || {};
+  for (const [key, paramSchema] of Object.entries(parameters)) {
+    if (paramSchema.optional !== true && !(key in (params || {}))) {
+      errors.push({
+        path: key,
+        message: `Missing required parameter '${key}'`,
+        expected: paramSchema.type
+      });
+    }
   }
-};
-var NetworkError = class _NetworkError extends RainfallError {
-  constructor(message = "Network error", details) {
-    super(message, "NETWORK_ERROR", void 0, details);
-    this.name = "NetworkError";
-    Object.setPrototypeOf(this, _NetworkError.prototype);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      const paramSchema = parameters[key];
+      if (!paramSchema) {
+        errors.push({
+          path: key,
+          message: `Unknown parameter '${key}'`,
+          received: value
+        });
+        continue;
+      }
+      const typeError = validateType(key, value, paramSchema);
+      if (typeError) {
+        errors.push(typeError);
+      }
+    }
   }
-};
-function parseErrorResponse(response, data) {
-  const statusCode = response.status;
-  if (statusCode === 429) {
-    const retryAfter = parseInt(response.headers.get("retry-after") || "60", 10);
-    const limit = parseInt(response.headers.get("x-ratelimit-limit") || "0", 10);
-    const remaining = parseInt(response.headers.get("x-ratelimit-remaining") || "0", 10);
-    const resetHeader = response.headers.get("x-ratelimit-reset");
-    const resetAt = resetHeader ? new Date(parseInt(resetHeader, 10) * 1e3) : void 0;
-    return new RateLimitError(
-      typeof data === "object" && data && "message" in data ? String(data.message) : "Rate limit exceeded",
-      retryAfter,
-      limit,
-      remaining,
-      resetAt
-    );
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function validateType(path, value, schema) {
+  if (value === null || value === void 0) {
+    if (schema.optional === true) {
+      return null;
+    }
+    return {
+      path,
+      message: `Parameter '${path}' is required but received ${value}`,
+      received: value,
+      expected: schema.type
+    };
   }
-  switch (statusCode) {
-    case 401:
-      return new AuthenticationError(
-        typeof data === "object" && data && "message" in data ? String(data.message) : "Invalid API key"
-      );
-    case 404:
-      return new NotFoundError(
-        typeof data === "object" && data && "resource" in data ? String(data.resource) : "Resource",
-        typeof data === "object" && data && "identifier" in data ? String(data.identifier) : void 0
-      );
-    case 400:
-      return new ValidationError(
-        typeof data === "object" && data && "message" in data ? String(data.message) : "Invalid request",
-        typeof data === "object" && data && "details" in data ? data.details : void 0
-      );
-    case 500:
-    case 502:
-    case 503:
-    case 504:
-      return new ServerError(
-        typeof data === "object" && data && "message" in data ? String(data.message) : "Server error",
-        statusCode
-      );
+  const expectedType = schema.type;
+  const actualType = getJsType(value);
+  switch (expectedType) {
+    case "string":
+      if (typeof value !== "string") {
+        return {
+          path,
+          message: `Parameter '${path}' must be a string, received ${actualType}`,
+          received: value,
+          expected: "string"
+        };
+      }
+      break;
+    case "number":
+      if (typeof value !== "number" || isNaN(value)) {
+        return {
+          path,
+          message: `Parameter '${path}' must be a number, received ${actualType}`,
+          received: value,
+          expected: "number"
+        };
+      }
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return {
+          path,
+          message: `Parameter '${path}' must be a boolean, received ${actualType}`,
+          received: value,
+          expected: "boolean"
+        };
+      }
+      break;
+    case "array":
+      if (!Array.isArray(value)) {
+        return {
+          path,
+          message: `Parameter '${path}' must be an array, received ${actualType}`,
+          received: value,
+          expected: "array"
+        };
+      }
+      if (schema.items) {
+        for (let i = 0; i < value.length; i++) {
+          const itemError = validateType(`${path}[${i}]`, value[i], schema.items);
+          if (itemError) {
+            return itemError;
+          }
+        }
+      }
+      break;
+    case "object":
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {
+          path,
+          message: `Parameter '${path}' must be an object, received ${actualType}`,
+          received: value,
+          expected: "object"
+        };
+      }
+      if (schema.properties) {
+        const objValue = value;
+        for (const [propKey, propSchema] of Object.entries(schema.properties)) {
+          if (objValue[propKey] !== void 0) {
+            const propError = validateType(`${path}.${propKey}`, objValue[propKey], propSchema);
+            if (propError) {
+              return propError;
+            }
+          }
+        }
+      }
+      break;
     default:
-      return new RainfallError(
-        typeof data === "object" && data && "message" in data ? String(data.message) : `HTTP ${statusCode}`,
-        "UNKNOWN_ERROR",
-        statusCode,
-        typeof data === "object" ? data : void 0
-      );
+      break;
   }
+  return null;
+}
+function getJsType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function formatValidationErrors(result) {
+  if (result.valid) return "No validation errors";
+  const lines = result.errors.map((err) => {
+    let line = `  - ${err.message}`;
+    if (err.received !== void 0) {
+      line += ` (received: ${JSON.stringify(err.received).slice(0, 50)})`;
+    }
+    return line;
+  });
+  return `Validation failed with ${result.errors.length} error(s):
+${lines.join("\n")}`;
 }
 
 // src/client.ts
@@ -298,6 +485,7 @@ var RainfallClient = class {
   defaultTimeout;
   defaultRetries;
   defaultRetryDelay;
+  disableValidation;
   lastRateLimitInfo;
   subscriberId;
   constructor(config) {
@@ -306,6 +494,7 @@ var RainfallClient = class {
     this.defaultTimeout = config.timeout || DEFAULT_TIMEOUT;
     this.defaultRetries = config.retries ?? DEFAULT_RETRIES;
     this.defaultRetryDelay = config.retryDelay || DEFAULT_RETRY_DELAY;
+    this.disableValidation = config.disableValidation ?? false;
   }
   /**
    * Get the last rate limit info from the API
@@ -388,15 +577,68 @@ var RainfallClient = class {
   }
   /**
    * Execute a tool/node by ID
+   * 
+   * @param toolId - The ID of the tool/node to execute
+   * @param params - Parameters to pass to the tool
+   * @param options - Request options including skipValidation to bypass param validation
    */
   async executeTool(toolId, params, options) {
+    if (!this.disableValidation && !options?.skipValidation) {
+      const validation = await this.validateToolParams(toolId, params);
+      if (!validation.valid) {
+        const { ValidationError: ValidationError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+        throw new ValidationError2(
+          `Parameter validation failed for tool '${toolId}': ${formatValidationErrors(validation)}`,
+          { toolId, errors: validation.errors }
+        );
+      }
+    }
     const subscriberId = await this.ensureSubscriberId();
     const response = await this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}`, {
       method: "POST",
       body: params || {}
     }, options);
+    if (response.success === false) {
+      const errorMessage = typeof response.error === "string" ? response.error : JSON.stringify(response.error);
+      throw new RainfallError(
+        `Tool execution failed: ${errorMessage}`,
+        "TOOL_EXECUTION_ERROR",
+        400,
+        { toolId, error: response.error }
+      );
+    }
     return response.result;
   }
+  /**
+   * Validate parameters for a tool without executing it
+   * Fetches the tool schema and validates the provided params
+   * 
+   * @param toolId - The ID of the tool to validate params for
+   * @param params - Parameters to validate
+   * @returns Validation result with detailed error information
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.validateToolParams('finviz-quotes', { tickers: ['AAPL'] });
+   * if (!result.valid) {
+   *   console.log('Validation errors:', result.errors);
+   * }
+   * ```
+   */
+  async validateToolParams(toolId, params) {
+    try {
+      const schema = await fetchToolSchema(this, toolId);
+      return validateParams(schema, params, toolId);
+    } catch (error) {
+      if (error instanceof RainfallError && error.statusCode === 404) {
+        return {
+          valid: false,
+          errors: [{ path: toolId, message: `Tool '${toolId}' not found` }]
+        };
+      }
+      return { valid: true, errors: [] };
+    }
+  }
   /**
    * List all available tools
    */
@@ -419,11 +661,20 @@ var RainfallClient = class {
   }
   /**
    * Get tool schema/parameters
+   * 
+   * @param toolId - The ID of the tool to get schema for
+   * @returns Tool schema including parameters and output definitions
    */
   async getToolSchema(toolId) {
-    const subscriberId = await this.ensureSubscriberId();
-    const response = await this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}/params`);
-    return response.params;
+    const schema = await fetchToolSchema(this, toolId);
+    return {
+      name: schema.name,
+      description: schema.description,
+      category: schema.category,
+      parameters: schema.parameters,
+      output: schema.output,
+      metadata: schema.metadata || {}
+    };
   }
   /**
    * Get subscriber info
@@ -950,9 +1201,40 @@ var Rainfall = class {
   }
   /**
    * Execute any tool by ID (low-level access)
+   * 
+   * @param toolId - The ID of the tool to execute
+   * @param params - Parameters to pass to the tool
+   * @param options - Execution options including skipValidation to bypass param validation
+   * 
+   * @example
+   * ```typescript
+   * // Execute with validation (default)
+   * const result = await rainfall.executeTool('finviz-quotes', { tickers: ['AAPL'] });
+   * 
+   * // Execute without validation
+   * const result = await rainfall.executeTool('finviz-quotes', { tickers: ['AAPL'] }, { skipValidation: true });
+   * ```
    */
-  async executeTool(toolId, params) {
-    return this.client.executeTool(toolId, params);
+  async executeTool(toolId, params, options) {
+    return this.client.executeTool(toolId, params, options);
+  }
+  /**
+   * Validate parameters for a tool without executing it
+   * 
+   * @param toolId - The ID of the tool to validate params for
+   * @param params - Parameters to validate
+   * @returns Validation result with detailed error information
+   * 
+   * @example
+   * ```typescript
+   * const result = await rainfall.validateToolParams('finviz-quotes', { tickers: ['AAPL'] });
+   * if (!result.valid) {
+   *   console.log('Validation errors:', result.errors);
+   * }
+   * ```
+   */
+  async validateToolParams(toolId, params) {
+    return this.client.validateToolParams(toolId, params);
   }
   /**
    * Get current subscriber info and usage

package/dist/daemon/index.mjs

@@ -5,7 +5,8 @@ import {
 } from "../chunk-7MRE4ZVI.mjs";
 import {
   Rainfall
-} from "../chunk-VDPKDC3R.mjs";
+} from "../chunk-CQ5TV7CQ.mjs";
+import "../chunk-LJQEO3CY.mjs";
 
 // src/daemon/index.ts
 import { WebSocketServer } from "ws";

package/dist/display-KKJPO6UA.mjs

@@ -0,0 +1,14 @@
+import {
+  detectImageData,
+  detectImageSupport,
+  displayImage,
+  formatAsTable,
+  formatResult
+} from "./chunk-XHPFY5MH.mjs";
+export {
+  detectImageData,
+  detectImageSupport,
+  displayImage,
+  formatAsTable,
+  formatResult
+};

package/dist/errors-CY6HW2I5.mjs

@@ -0,0 +1,24 @@
+import {
+  AuthenticationError,
+  NetworkError,
+  NotFoundError,
+  RainfallError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  ToolNotFoundError,
+  ValidationError,
+  parseErrorResponse
+} from "./chunk-LJQEO3CY.mjs";
+export {
+  AuthenticationError,
+  NetworkError,
+  NotFoundError,
+  RainfallError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  ToolNotFoundError,
+  ValidationError,
+  parseErrorResponse
+};