@rainfall-devkit/sdk 0.2.3 → 0.2.4

package/dist/chunk-2FYYTIJQ.mjs

@@ -0,0 +1,993 @@
+import {
+  NetworkError,
+  RainfallError,
+  TimeoutError,
+  ValidationError,
+  parseErrorResponse
+} from "./chunk-LJQEO3CY.mjs";
+
+// src/validation.ts
+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 clearSchemaCache() {
+  schemaCache.clear();
+}
+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
+      });
+    }
+  }
+  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);
+      }
+    }
+  }
+  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
+    };
+  }
+  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:
+      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
+var DEFAULT_BASE_URL = "https://olympic-api.pragma-digital.org/v1";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_RETRIES = 3;
+var DEFAULT_RETRY_DELAY = 1e3;
+var RainfallClient = class {
+  apiKey;
+  baseUrl;
+  defaultTimeout;
+  defaultRetries;
+  defaultRetryDelay;
+  disableValidation;
+  lastRateLimitInfo;
+  subscriberId;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+    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
+   */
+  getRateLimitInfo() {
+    return this.lastRateLimitInfo;
+  }
+  /**
+   * Make an authenticated request to the Rainfall API
+   */
+  async request(path, options = {}, requestOptions) {
+    const timeout = requestOptions?.timeout ?? this.defaultTimeout;
+    const maxRetries = requestOptions?.retries ?? this.defaultRetries;
+    const retryDelay = requestOptions?.retryDelay ?? this.defaultRetryDelay;
+    const url = `${this.baseUrl}${path}`;
+    const method = options.method || "GET";
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "x-api-key": this.apiKey,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "X-Rainfall-SDK-Version": "0.1.0",
+            ...options.headers
+          },
+          body: options.body ? JSON.stringify(options.body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        const limit = response.headers.get("x-ratelimit-limit");
+        const remaining = response.headers.get("x-ratelimit-remaining");
+        const reset = response.headers.get("x-ratelimit-reset");
+        if (limit && remaining && reset) {
+          this.lastRateLimitInfo = {
+            limit: parseInt(limit, 10),
+            remaining: parseInt(remaining, 10),
+            resetAt: new Date(parseInt(reset, 10) * 1e3)
+          };
+        }
+        let data;
+        const contentType = response.headers.get("content-type");
+        if (contentType?.includes("application/json")) {
+          data = await response.json();
+        } else {
+          data = await response.text();
+        }
+        if (!response.ok) {
+          throw parseErrorResponse(response, data);
+        }
+        return data;
+      } catch (error) {
+        if (error instanceof RainfallError) {
+          if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
+            throw error;
+          }
+          if (error.statusCode === 401) {
+            throw error;
+          }
+        }
+        if (error instanceof Error && error.name === "AbortError") {
+          lastError = new TimeoutError(timeout);
+        } else if (error instanceof TypeError) {
+          lastError = new NetworkError(error.message);
+        } else {
+          lastError = error instanceof Error ? error : new Error(String(error));
+        }
+        if (attempt >= maxRetries) {
+          break;
+        }
+        const delay = retryDelay * Math.pow(2, attempt) + Math.random() * 1e3;
+        await this.sleep(delay);
+      }
+    }
+    throw lastError || new RainfallError("Request failed", "REQUEST_FAILED");
+  }
+  /**
+   * 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 import("./errors-CY6HW2I5.mjs");
+        throw new ValidationError2(
+          `Parameter validation failed for tool '${toolId}': ${formatValidationErrors(validation)}`,
+          { toolId, errors: validation.errors }
+        );
+      }
+    }
+    const subscriberId = await this.ensureSubscriberId();
+    const body = params || {};
+    if (options?.targetEdge) {
+      body._targetEdge = options.targetEdge;
+    }
+    const response = await this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}`, {
+      method: "POST",
+      body
+    }, 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
+   */
+  async listTools() {
+    const subscriberId = await this.ensureSubscriberId();
+    const result = await this.request(`/olympic/subscribers/${subscriberId}/nodes/_utils/node-descriptions`);
+    if (result.success && result.nodes) {
+      return Object.values(result.nodes);
+    }
+    const legacyResult = await this.request(`/olympic/subscribers/${subscriberId}/nodes/_utils/node-list`);
+    if (legacyResult.keys && Array.isArray(legacyResult.keys)) {
+      return legacyResult.keys.map((key) => ({
+        id: key,
+        name: key,
+        description: "",
+        category: "general"
+      }));
+    }
+    return legacyResult.nodes || [];
+  }
+  /**
+   * 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 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
+   */
+  async getMe() {
+    const result = await this.request("/olympic/subscribers/me");
+    if (result.subscriber?.id) {
+      this.subscriberId = result.subscriber.id;
+    }
+    const subscriber = result.subscriber;
+    return {
+      id: subscriber.id,
+      name: subscriber.name,
+      email: subscriber.google_id,
+      billingStatus: subscriber.billing_status,
+      plan: subscriber.billing_status,
+      usage: {
+        callsThisMonth: subscriber.metadata?.usage?.callsThisMonth ?? 0,
+        callsLimit: subscriber.metadata?.usage?.callsLimit ?? 5e3
+      }
+    };
+  }
+  /**
+   * Ensure we have a subscriber ID, fetching it if necessary
+   */
+  async ensureSubscriberId() {
+    if (this.subscriberId) {
+      return this.subscriberId;
+    }
+    const me = await this.getMe();
+    if (!me.id) {
+      throw new RainfallError("Failed to get subscriber ID", "NO_SUBSCRIBER_ID");
+    }
+    return me.id;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * OpenAI-compatible chat completions with tool support
+   */
+  async chatCompletions(params) {
+    const { subscriber_id, ...body } = params;
+    if (body.stream) {
+      const url = `${this.baseUrl}/olympic/subscribers/${subscriber_id}/v1/chat/completions`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "x-api-key": this.apiKey,
+          "Content-Type": "application/json",
+          "Accept": "text/event-stream"
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        const error = await response.text();
+        throw new RainfallError(`Chat completions failed: ${error}`, "CHAT_ERROR");
+      }
+      if (!response.body) {
+        throw new RainfallError("No response body", "CHAT_ERROR");
+      }
+      return response.body;
+    }
+    return this.request(
+      `/olympic/subscribers/${subscriber_id}/v1/chat/completions`,
+      {
+        method: "POST",
+        body
+      }
+    );
+  }
+  /**
+   * List available models (OpenAI-compatible format)
+   */
+  async listModels(subscriberId) {
+    const sid = subscriberId || this.subscriberId || await this.ensureSubscriberId();
+    const result = await this.request(
+      `/olympic/subscribers/${sid}/v1/models`
+    );
+    return result.data || [];
+  }
+};
+
+// src/namespaces/integrations.ts
+function createIntegrations(client) {
+  return new IntegrationsNamespace(client);
+}
+var IntegrationsNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  get github() {
+    return {
+      issues: {
+        create: (params) => this.client.executeTool("github-create-issue", params),
+        list: (params) => this.client.executeTool("github-list-issues", params),
+        get: (params) => this.client.executeTool("github-get-issue", params),
+        update: (params) => this.client.executeTool("github-update-issue", params),
+        addComment: (params) => this.client.executeTool("github-add-issue-comment", params)
+      },
+      repos: {
+        get: (params) => this.client.executeTool("github-get-repository", params),
+        listBranches: (params) => this.client.executeTool("github-list-branches", params)
+      },
+      pullRequests: {
+        list: (params) => this.client.executeTool("github-list-pull-requests", params),
+        get: (params) => this.client.executeTool("github-get-pull-request", params)
+      }
+    };
+  }
+  get notion() {
+    return {
+      pages: {
+        create: (params) => this.client.executeTool("notion-pages-create", params),
+        retrieve: (params) => this.client.executeTool("notion-pages-retrieve", params),
+        update: (params) => this.client.executeTool("notion-pages-update", params)
+      },
+      databases: {
+        query: (params) => this.client.executeTool("notion-databases-query", params),
+        retrieve: (params) => this.client.executeTool("notion-databases-retrieve", params)
+      },
+      blocks: {
+        appendChildren: (params) => this.client.executeTool("notion-blocks-append-children", params),
+        retrieveChildren: (params) => this.client.executeTool("notion-blocks-retrieve-children", params)
+      }
+    };
+  }
+  get linear() {
+    return {
+      issues: {
+        create: (params) => this.client.executeTool("linear-core-issueCreate", params),
+        list: (params) => this.client.executeTool("linear-core-issues", params),
+        get: (params) => this.client.executeTool("linear-core-issue", params),
+        update: (params) => this.client.executeTool("linear-core-issueUpdate", params),
+        archive: (params) => this.client.executeTool("linear-core-issueArchive", params)
+      },
+      teams: {
+        list: () => this.client.executeTool("linear-core-teams", {})
+      }
+    };
+  }
+  get slack() {
+    return {
+      messages: {
+        send: (params) => this.client.executeTool("slack-core-postMessage", params),
+        list: (params) => this.client.executeTool("slack-core-listMessages", params)
+      },
+      channels: {
+        list: () => this.client.executeTool("slack-core-listChannels", {})
+      },
+      users: {
+        list: () => this.client.executeTool("slack-core-listUsers", {})
+      },
+      reactions: {
+        add: (params) => this.client.executeTool("slack-core-addReaction", params)
+      }
+    };
+  }
+  get figma() {
+    return {
+      files: {
+        get: (params) => this.client.executeTool("figma-files-getFile", { fileKey: params.fileKey }),
+        getNodes: (params) => this.client.executeTool("figma-files-getFileNodes", { fileKey: params.fileKey, nodeIds: params.nodeIds }),
+        getImages: (params) => this.client.executeTool("figma-files-getFileImage", { fileKey: params.fileKey, nodeIds: params.nodeIds, format: params.format }),
+        getComments: (params) => this.client.executeTool("figma-comments-getFileComments", { fileKey: params.fileKey }),
+        postComment: (params) => this.client.executeTool("figma-comments-postComment", { fileKey: params.fileKey, message: params.message, nodeId: params.nodeId })
+      },
+      projects: {
+        list: (params) => this.client.executeTool("figma-projects-getTeamProjects", { teamId: params.teamId }),
+        getFiles: (params) => this.client.executeTool("figma-projects-getProjectFiles", { projectId: params.projectId })
+      }
+    };
+  }
+  get stripe() {
+    return {
+      customers: {
+        create: (params) => this.client.executeTool("stripe-customers-create", params),
+        retrieve: (params) => this.client.executeTool("stripe-customers-retrieve", { customerId: params.customerId }),
+        update: (params) => this.client.executeTool("stripe-customers-update", params),
+        listPaymentMethods: (params) => this.client.executeTool("stripe-customers-list-payment-methods", { customerId: params.customerId })
+      },
+      paymentIntents: {
+        create: (params) => this.client.executeTool("stripe-payment-intents-create", params),
+        retrieve: (params) => this.client.executeTool("stripe-payment-intents-retrieve", { paymentIntentId: params.paymentIntentId }),
+        confirm: (params) => this.client.executeTool("stripe-payment-intents-confirm", { paymentIntentId: params.paymentIntentId })
+      },
+      subscriptions: {
+        create: (params) => this.client.executeTool("stripe-subscriptions-create", params),
+        retrieve: (params) => this.client.executeTool("stripe-subscriptions-retrieve", { subscriptionId: params.subscriptionId }),
+        cancel: (params) => this.client.executeTool("stripe-subscriptions-cancel", { subscriptionId: params.subscriptionId })
+      }
+    };
+  }
+};
+
+// src/namespaces/memory.ts
+function createMemory(client) {
+  return {
+    create: (params) => client.executeTool("memory-create", params),
+    get: (params) => client.executeTool("memory-get", { memoryId: params.memoryId }),
+    recall: (params) => client.executeTool("memory-recall", params),
+    list: (params) => client.executeTool("memory-list", params ?? {}),
+    update: (params) => client.executeTool("memory-update", params),
+    delete: (params) => client.executeTool("memory-delete", { memoryId: params.memoryId })
+  };
+}
+
+// src/namespaces/articles.ts
+function createArticles(client) {
+  return {
+    search: (params) => client.executeTool("article-search", params),
+    create: (params) => client.executeTool("article-create", params),
+    createFromUrl: (params) => client.executeTool("article-create-from-url", params),
+    fetch: (params) => client.executeTool("article-fetch", params),
+    recent: (params) => client.executeTool("article-recent", params ?? {}),
+    relevant: (params) => client.executeTool("article-relevant-news", params),
+    summarize: (params) => client.executeTool("article-summarize", params),
+    extractTopics: (params) => client.executeTool("article-topic-extractor", params)
+  };
+}
+
+// src/namespaces/web.ts
+function createWeb(client) {
+  return {
+    search: {
+      exa: (params) => client.executeTool("exa-web-search", params),
+      perplexity: (params) => client.executeTool("perplexity-search", params)
+    },
+    fetch: (params) => client.executeTool("web-fetch", params),
+    htmlToMarkdown: (params) => client.executeTool("html-to-markdown-converter", params),
+    extractHtml: (params) => client.executeTool("extract-html-selector", params)
+  };
+}
+
+// src/namespaces/ai.ts
+function createAI(client) {
+  return {
+    embeddings: {
+      document: (params) => client.executeTool("jina-document-embedding", params),
+      query: (params) => client.executeTool("jina-query-embedding", params),
+      image: (params) => client.executeTool("jina-image-embedding", { image: params.imageBase64 })
+    },
+    image: {
+      generate: (params) => client.executeTool("image-generation", params)
+    },
+    ocr: (params) => client.executeTool("ocr-text-extraction", { image: params.imageBase64 }),
+    vision: (params) => client.executeTool("llama-scout-vision", { image: params.imageBase64, prompt: params.prompt }),
+    chat: (params) => client.executeTool("xai-chat-completions", params),
+    complete: (params) => client.executeTool("fim", params),
+    classify: (params) => client.executeTool("jina-document-classifier", params),
+    segment: (params) => client.executeTool("jina-text-segmenter", params),
+    /**
+     * OpenAI-compatible chat completions with full tool support
+     * This is the recommended method for multi-turn conversations with tools
+     */
+    chatCompletions: (params) => client.chatCompletions(params)
+  };
+}
+
+// src/namespaces/data.ts
+function createData(client) {
+  return {
+    csv: {
+      query: (params) => client.executeTool("query-csv", params),
+      convert: (params) => client.executeTool("csv-convert", params)
+    },
+    scripts: {
+      create: (params) => client.executeTool("create-saved-script", params),
+      execute: (params) => client.executeTool("execute-saved-script", params),
+      list: () => client.executeTool("list-saved-scripts", {}),
+      update: (params) => client.executeTool("update-saved-script", params),
+      delete: (params) => client.executeTool("delete-saved-script", params)
+    },
+    similarity: {
+      search: (params) => client.executeTool("duck-db-similarity-search", params),
+      duckDbSearch: (params) => client.executeTool("duck-db-similarity-search", params)
+    }
+  };
+}
+
+// src/namespaces/utils.ts
+function createUtils(client) {
+  return {
+    mermaid: (params) => client.executeTool("mermaid-diagram-generator", { mermaid: params.diagram }),
+    documentConvert: (params) => client.executeTool("document-format-converter", {
+      base64: `data:${params.mimeType};base64,${Buffer.from(params.document).toString("base64")}`,
+      format: params.format
+    }),
+    regex: {
+      match: (params) => client.executeTool("regex-match", params),
+      replace: (params) => client.executeTool("regex-replace", params)
+    },
+    jsonExtract: (params) => client.executeTool("json-extract", params),
+    digest: (params) => client.executeTool("digest-generator", { text: params.data }),
+    monteCarlo: (params) => client.executeTool("monte-carlo-simulation", params)
+  };
+}
+
+// src/sdk.ts
+var Rainfall = class {
+  client;
+  _integrations;
+  _memory;
+  _articles;
+  _web;
+  _ai;
+  _data;
+  _utils;
+  constructor(config) {
+    this.client = new RainfallClient(config);
+  }
+  /**
+   * Integrations namespace - GitHub, Notion, Linear, Slack, Figma, Stripe
+   * 
+   * @example
+   * ```typescript
+   * // GitHub
+   * await rainfall.integrations.github.issues.create({
+   *   owner: 'facebook',
+   *   repo: 'react',
+   *   title: 'Bug report'
+   * });
+   * 
+   * // Slack
+   * await rainfall.integrations.slack.messages.send({
+   *   channelId: 'C123456',
+   *   text: 'Hello team!'
+   * });
+   * 
+   * // Linear
+   * const issues = await rainfall.integrations.linear.issues.list();
+   * ```
+   */
+  get integrations() {
+    if (!this._integrations) {
+      this._integrations = createIntegrations(this.client);
+    }
+    return this._integrations;
+  }
+  /**
+   * Memory namespace - Semantic memory storage and retrieval
+   * 
+   * @example
+   * ```typescript
+   * // Store a memory
+   * await rainfall.memory.create({
+   *   content: 'User prefers dark mode',
+   *   keywords: ['preference', 'ui']
+   * });
+   * 
+   * // Recall similar memories
+   * const memories = await rainfall.memory.recall({
+   *   query: 'user preferences',
+   *   topK: 5
+   * });
+   * ```
+   */
+  get memory() {
+    if (!this._memory) {
+      this._memory = createMemory(this.client);
+    }
+    return this._memory;
+  }
+  /**
+   * Articles namespace - News aggregation and article management
+   * 
+   * @example
+   * ```typescript
+   * // Search news
+   * const articles = await rainfall.articles.search({
+   *   query: 'artificial intelligence'
+   * });
+   * 
+   * // Create from URL
+   * const article = await rainfall.articles.createFromUrl({
+   *   url: 'https://example.com/article'
+   * });
+   * 
+   * // Summarize
+   * const summary = await rainfall.articles.summarize({
+   *   text: article.content
+   * });
+   * ```
+   */
+  get articles() {
+    if (!this._articles) {
+      this._articles = createArticles(this.client);
+    }
+    return this._articles;
+  }
+  /**
+   * Web namespace - Web search, scraping, and content extraction
+   * 
+   * @example
+   * ```typescript
+   * // Search with Exa
+   * const results = await rainfall.web.search.exa({
+   *   query: 'latest AI research'
+   * });
+   * 
+   * // Fetch and convert
+   * const html = await rainfall.web.fetch({ url: 'https://example.com' });
+   * const markdown = await rainfall.web.htmlToMarkdown({ html });
+   * 
+   * // Extract specific elements
+   * const links = await rainfall.web.extractHtml({
+   *   html,
+   *   selector: 'a[href]'
+   * });
+   * ```
+   */
+  get web() {
+    if (!this._web) {
+      this._web = createWeb(this.client);
+    }
+    return this._web;
+  }
+  /**
+   * AI namespace - Embeddings, image generation, OCR, vision, chat
+   * 
+   * @example
+   * ```typescript
+   * // Generate embeddings
+   * const embedding = await rainfall.ai.embeddings.document({
+   *   text: 'Hello world'
+   * });
+   * 
+   * // Generate image
+   * const image = await rainfall.ai.image.generate({
+   *   prompt: 'A serene mountain landscape'
+   * });
+   * 
+   * // OCR
+   * const text = await rainfall.ai.ocr({ imageBase64: '...' });
+   * 
+   * // Chat
+   * const response = await rainfall.ai.chat({
+   *   messages: [{ role: 'user', content: 'Hello!' }]
+   * });
+   * ```
+   */
+  get ai() {
+    if (!this._ai) {
+      this._ai = createAI(this.client);
+    }
+    return this._ai;
+  }
+  /**
+   * Data namespace - CSV processing, scripts, similarity search
+   * 
+   * @example
+   * ```typescript
+   * // Query CSV with SQL
+   * const results = await rainfall.data.csv.query({
+   *   sql: 'SELECT * FROM data WHERE value > 100'
+   * });
+   * 
+   * // Execute saved script
+   * const result = await rainfall.data.scripts.execute({
+   *   name: 'my-script',
+   *   params: { input: 'data' }
+   * });
+   * ```
+   */
+  get data() {
+    if (!this._data) {
+      this._data = createData(this.client);
+    }
+    return this._data;
+  }
+  /**
+   * Utils namespace - Mermaid diagrams, document conversion, regex, JSON extraction
+   * 
+   * @example
+   * ```typescript
+   * // Generate diagram
+   * const diagram = await rainfall.utils.mermaid({
+   *   diagram: 'graph TD; A-->B;'
+   * });
+   * 
+   * // Convert document
+   * const pdf = await rainfall.utils.documentConvert({
+   *   document: markdownContent,
+   *   mimeType: 'text/markdown',
+   *   format: 'pdf'
+   * });
+   * 
+   * // Extract JSON from text
+   * const json = await rainfall.utils.jsonExtract({
+   *   text: 'Here is some data: {"key": "value"}'
+   * });
+   * ```
+   */
+  get utils() {
+    if (!this._utils) {
+      this._utils = createUtils(this.client);
+    }
+    return this._utils;
+  }
+  /**
+   * Get the underlying HTTP client for advanced usage
+   */
+  getClient() {
+    return this.client;
+  }
+  /**
+   * List all available tools
+   */
+  async listTools() {
+    return this.client.listTools();
+  }
+  /**
+   * Get schema for a specific tool
+   */
+  async getToolSchema(toolId) {
+    return this.client.getToolSchema(toolId);
+  }
+  /**
+   * 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, 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
+   */
+  async getMe() {
+    return this.client.getMe();
+  }
+  /**
+   * Get current rate limit info
+   */
+  getRateLimitInfo() {
+    return this.client.getRateLimitInfo();
+  }
+  /**
+   * OpenAI-compatible chat completions with tool support
+   * 
+   * @example
+   * ```typescript
+   * // Simple chat
+   * const response = await rainfall.chatCompletions({
+   *   subscriber_id: 'my-subscriber',
+   *   messages: [{ role: 'user', content: 'Hello!' }],
+   *   model: 'llama-3.3-70b-versatile'
+   * });
+   * 
+   * // With tools
+   * const response = await rainfall.chatCompletions({
+   *   subscriber_id: 'my-subscriber',
+   *   messages: [{ role: 'user', content: 'Search for AI news' }],
+   *   tools: [{ type: 'function', function: { name: 'web-search' } }],
+   *   enable_stacked: true
+   * });
+   * 
+   * // Streaming
+   * const stream = await rainfall.chatCompletions({
+   *   subscriber_id: 'my-subscriber',
+   *   messages: [{ role: 'user', content: 'Tell me a story' }],
+   *   stream: true
+   * });
+   * ```
+   */
+  async chatCompletions(params) {
+    return this.client.chatCompletions(params);
+  }
+  /**
+   * List available models (OpenAI-compatible format)
+   * 
+   * @example
+   * ```typescript
+   * const models = await rainfall.listModels();
+   * console.log(models); // [{ id: 'llama-3.3-70b-versatile', ... }]
+   * ```
+   */
+  async listModels(subscriberId) {
+    return this.client.listModels(subscriberId);
+  }
+};
+
+export {
+  fetchToolSchema,
+  clearSchemaCache,
+  validateParams,
+  formatValidationErrors,
+  RainfallClient,
+  Rainfall
+};