@rainfall-devkit/sdk 0.1.7 → 0.1.8

package/dist/chunk-RA3HDYF4.mjs

@@ -0,0 +1,778 @@
+// src/errors.ts
+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);
+  }
+};
+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);
+  }
+};
+var 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);
+  }
+};
+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
+      );
+  }
+}
+
+// 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;
+  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;
+  }
+  /**
+   * 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
+   */
+  async executeTool(toolId, params, options) {
+    const subscriberId = await this.ensureSubscriberId();
+    const response = await this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}`, {
+      method: "POST",
+      body: params || {}
+    }, options);
+    return response.result;
+  }
+  /**
+   * 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
+   */
+  async getToolSchema(toolId) {
+    const subscriberId = await this.ensureSubscriberId();
+    const response = await this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}/params`);
+    return response.params;
+  }
+  /**
+   * 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));
+  }
+};
+
+// 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)
+  };
+}
+
+// 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)
+   */
+  async executeTool(toolId, params) {
+    return this.client.executeTool(toolId, params);
+  }
+  /**
+   * Get current subscriber info and usage
+   */
+  async getMe() {
+    return this.client.getMe();
+  }
+  /**
+   * Get current rate limit info
+   */
+  getRateLimitInfo() {
+    return this.client.getRateLimitInfo();
+  }
+};
+
+export {
+  RainfallError,
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+  ServerError,
+  TimeoutError,
+  NetworkError,
+  ToolNotFoundError,
+  parseErrorResponse,
+  RainfallClient,
+  Rainfall
+};

package/dist/cli/index.js

@@ -1,5 +1,27 @@
 #!/usr/bin/env node
 "use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 
 // src/cli/index.ts
 var import_fs = require("fs");
@@ -241,10 +263,11 @@ var RainfallClient = class {
    */
   async executeTool(toolId, params, options) {
     const subscriberId = await this.ensureSubscriberId();
-    return this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}`, {
+    const response = await this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}`, {
       method: "POST",
-      body: params
+      body: params || {}
     }, options);
+    return response.result;
   }
   /**
    * List all available tools
@@ -985,6 +1008,25 @@ async function runTool(args) {
     console.error("\nUsage: rainfall run <tool-id> [options]");
     process.exit(1);
   }
+  if (toolId === "--help" || toolId === "-h") {
+    console.log(`
+Usage: rainfall run <tool-id> [options]
+
+Execute a tool by ID.
+
+Options:
+  -p, --params <json>    Tool parameters as JSON string
+  -f, --file <path>      Read parameters from JSON file
+  --raw                  Output raw JSON (no formatting)
+
+Examples:
+  rainfall run figma-users-getMe
+  rainfall run exa-web-search -p '{"query": "AI news"}'
+  rainfall run github-create-issue -f ./issue.json
+  echo '{"query": "hello"}' | rainfall run exa-web-search
+`);
+    return;
+  }
   let params = {};
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
@@ -1016,16 +1058,37 @@ async function runTool(args) {
     }
   }
   if (!process.stdin.isTTY) {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-      chunks.push(chunk);
-    }
-    if (chunks.length > 0) {
-      try {
-        const piped = JSON.parse(Buffer.concat(chunks).toString());
-        params = { ...params, ...piped };
-      } catch {
+    process.stdin.pause();
+    const fs = await import("fs");
+    try {
+      const buffer = Buffer.alloc(1024);
+      const bytesRead = await new Promise((resolve) => {
+        const timeout = setTimeout(() => resolve(0), 50);
+        fs.read(process.stdin.fd, buffer, 0, 1024, null, (err, n) => {
+          clearTimeout(timeout);
+          resolve(err ? 0 : n);
+        });
+      });
+      if (bytesRead > 0) {
+        let data = buffer.toString("utf8", 0, bytesRead);
+        while (true) {
+          const more = await new Promise((resolve) => {
+            fs.read(process.stdin.fd, buffer, 0, 1024, null, (err, n) => {
+              resolve(err ? 0 : n);
+            });
+          });
+          if (more === 0) break;
+          data += buffer.toString("utf8", 0, more);
+        }
+        if (data.trim()) {
+          try {
+            const piped = JSON.parse(data);
+            params = { ...params, ...piped };
+          } catch {
+          }
+        }
       }
+    } catch {
     }
   }
   const rainfall = getRainfall();
@@ -1114,7 +1177,7 @@ async function main() {
       }
       break;
     case "run":
-      await runTool(rest);
+      await runTool(args.slice(1));
       break;
     case "me":
       await showMe();

package/dist/cli/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   Rainfall
-} from "../chunk-PNYIIMJS.mjs";
+} from "../chunk-RA3HDYF4.mjs";
 
 // src/cli/index.ts
 import { readFileSync, existsSync, writeFileSync, mkdirSync } from "fs";
@@ -229,6 +229,25 @@ async function runTool(args) {
     console.error("\nUsage: rainfall run <tool-id> [options]");
     process.exit(1);
   }
+  if (toolId === "--help" || toolId === "-h") {
+    console.log(`
+Usage: rainfall run <tool-id> [options]
+
+Execute a tool by ID.
+
+Options:
+  -p, --params <json>    Tool parameters as JSON string
+  -f, --file <path>      Read parameters from JSON file
+  --raw                  Output raw JSON (no formatting)
+
+Examples:
+  rainfall run figma-users-getMe
+  rainfall run exa-web-search -p '{"query": "AI news"}'
+  rainfall run github-create-issue -f ./issue.json
+  echo '{"query": "hello"}' | rainfall run exa-web-search
+`);
+    return;
+  }
   let params = {};
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
@@ -260,16 +279,37 @@ async function runTool(args) {
     }
   }
   if (!process.stdin.isTTY) {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-      chunks.push(chunk);
-    }
-    if (chunks.length > 0) {
-      try {
-        const piped = JSON.parse(Buffer.concat(chunks).toString());
-        params = { ...params, ...piped };
-      } catch {
+    process.stdin.pause();
+    const fs = await import("fs");
+    try {
+      const buffer = Buffer.alloc(1024);
+      const bytesRead = await new Promise((resolve) => {
+        const timeout = setTimeout(() => resolve(0), 50);
+        fs.read(process.stdin.fd, buffer, 0, 1024, null, (err, n) => {
+          clearTimeout(timeout);
+          resolve(err ? 0 : n);
+        });
+      });
+      if (bytesRead > 0) {
+        let data = buffer.toString("utf8", 0, bytesRead);
+        while (true) {
+          const more = await new Promise((resolve) => {
+            fs.read(process.stdin.fd, buffer, 0, 1024, null, (err, n) => {
+              resolve(err ? 0 : n);
+            });
+          });
+          if (more === 0) break;
+          data += buffer.toString("utf8", 0, more);
+        }
+        if (data.trim()) {
+          try {
+            const piped = JSON.parse(data);
+            params = { ...params, ...piped };
+          } catch {
+          }
+        }
       }
+    } catch {
     }
   }
   const rainfall = getRainfall();
@@ -358,7 +398,7 @@ async function main() {
       }
       break;
     case "run":
-      await runTool(rest);
+      await runTool(args.slice(1));
       break;
     case "me":
       await showMe();

package/dist/index.js

@@ -277,10 +277,11 @@ var RainfallClient = class {
    */
   async executeTool(toolId, params, options) {
     const subscriberId = await this.ensureSubscriberId();
-    return this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}`, {
+    const response = await this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}`, {
       method: "POST",
-      body: params
+      body: params || {}
     }, options);
+    return response.result;
   }
   /**
    * List all available tools

package/dist/index.mjs

@@ -10,7 +10,7 @@ import {
   TimeoutError,
   ToolNotFoundError,
   ValidationError
-} from "./chunk-PNYIIMJS.mjs";
+} from "./chunk-RA3HDYF4.mjs";
 
 // src/index.ts
 var VERSION = "0.1.0";

package/dist/mcp.js

@@ -277,10 +277,11 @@ var RainfallClient = class {
    */
   async executeTool(toolId, params, options) {
     const subscriberId = await this.ensureSubscriberId();
-    return this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}`, {
+    const response = await this.request(`/olympic/subscribers/${subscriberId}/nodes/${toolId}`, {
       method: "POST",
-      body: params
+      body: params || {}
     }, options);
+    return response.result;
   }
   /**
    * List all available tools

package/dist/mcp.mjs

@@ -10,7 +10,7 @@ import {
   ToolNotFoundError,
   ValidationError,
   parseErrorResponse
-} from "./chunk-PNYIIMJS.mjs";
+} from "./chunk-RA3HDYF4.mjs";
 
 // src/mcp.ts
 function createRainfallMCPServer(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainfall-devkit/sdk",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Official SDK for Rainfall API - 200+ tools for building AI-powered applications",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -67,6 +67,6 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@rainfall-devkit/sdk": "^0.1.5"
+    "@rainfall-devkit/sdk": "^0.1.7"
   }
 }