hereco 0.2.0

package/index.d.ts

@@ -0,0 +1,48 @@
+declare module 'hereco' {
+  export interface HerecoOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+  }
+
+  export interface ChatOptions {
+    message: string;
+    model?: string;
+    system?: string;
+    temperature?: number;
+    maxTokens?: number;
+  }
+
+  export interface ChatResponse {
+    outputText: string;
+    model: string;
+    usage: Record<string, number>;
+    toString(): string;
+  }
+
+  export interface KeyValidation {
+    valid: boolean;
+    keyId?: string;
+    permissions?: string[];
+    credits?: { balance: number; balanceFormatted: string };
+    rateLimit?: { limit: number; remaining: number };
+    error?: string;
+  }
+
+  export class Chat {
+    create(options: string | ChatOptions): Promise<ChatResponse>;
+  }
+
+  export class Hereco {
+    constructor(options?: HerecoOptions);
+    chat: Chat;
+    testKey(): Promise<KeyValidation>;
+    ask(message: string, options?: Omit<ChatOptions, 'message'>): Promise<string>;
+  }
+
+  export class HerecoBotError extends Error {
+    status: number;
+  }
+
+  export default Hereco;
+}

package/index.js

@@ -0,0 +1,149 @@
+/**
+ * Hereco AI SDK for JavaScript/Node.js
+ * @module hereco
+ */
+
+class Hereco {
+  /**
+   * Create a Hereco client
+   * @param {Object} options
+   * @param {string} options.apiKey - Your Hereco API key
+   * @param {string} [options.baseUrl] - API base URL (default: https://hereco.xyz)
+   * @param {number} [options.timeout] - Request timeout in ms (default: 30000)
+   */
+  constructor(options = {}) {
+    this.apiKey = options.apiKey || process.env.HERECO_API_KEY;
+    this.baseUrl = (options.baseUrl || process.env.HERECO_API_BASE || 'https://hereco.xyz').replace(/\/$/, '');
+    this.timeout = options.timeout || 30000;
+
+    if (!this.apiKey) {
+      throw new Error('API key is required. Set HERECO_API_KEY or pass apiKey option.');
+    }
+
+    this.chat = new Chat(this);
+  }
+
+  async _request(endpoint, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+          ...options.headers,
+        },
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new HerecoBotError(error.error || `HTTP ${response.status}`, response.status);
+      }
+
+      return response.json();
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err.name === 'AbortError') {
+        throw new HerecoBotError('Request timeout', 408);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Test if API key is valid
+   * @returns {Promise<Object>} Validation result
+   */
+  async testKey() {
+    try {
+      const result = await this._request('/api/v1/validate');
+      return {
+        valid: true,
+        keyId: result.keyId,
+        permissions: result.permissions,
+        credits: result.credits,
+        rateLimit: result.rateLimit,
+      };
+    } catch (err) {
+      return {
+        valid: false,
+        error: err.message,
+      };
+    }
+  }
+
+  /**
+   * Simple one-liner to ask a question
+   * @param {string} message - Question to ask
+   * @param {Object} [options] - Additional options
+   * @returns {Promise<string>} Response text
+   */
+  async ask(message, options = {}) {
+    const response = await this.chat.create({ message, ...options });
+    return response.outputText;
+  }
+}
+
+class Chat {
+  constructor(client) {
+    this._client = client;
+  }
+
+  /**
+   * Create a chat completion
+   * @param {Object} options
+   * @param {string} options.message - User message
+   * @param {string} [options.model] - Model name (default: 'default')
+   * @param {string} [options.system] - System prompt
+   * @param {number} [options.temperature] - Temperature (0-1)
+   * @param {number} [options.maxTokens] - Max tokens
+   * @returns {Promise<ChatResponse>}
+   */
+  async create(options) {
+    const { message, model = 'default', system, temperature = 0.7, maxTokens = 512 } = 
+      typeof options === 'string' ? { message: options } : options;
+
+    const result = await this._client._request('/api/v1/chat', {
+      method: 'POST',
+      body: JSON.stringify({
+        message,
+        model,
+        system,
+        temperature,
+        max_tokens: maxTokens,
+      }),
+    });
+
+    return new ChatResponse(result);
+  }
+}
+
+class ChatResponse {
+  constructor(data) {
+    this.outputText = data.output_text || data.response || '';
+    this.model = data.model || 'default';
+    this.usage = data.usage || {};
+  }
+
+  toString() {
+    return this.outputText;
+  }
+}
+
+class HerecoBotError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = 'HerecoBotError';
+    this.status = status;
+  }
+}
+
+// CommonJS export
+module.exports = { Hereco, HerecoBotError, ChatResponse };
+module.exports.default = Hereco;

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "hereco",
+  "version": "0.2.0",
+  "description": "Official Hereco AI SDK for JavaScript/Node.js",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": ["hereco", "ai", "chatbot", "sdk", "api"],
+  "author": "Hereco",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hereco/hereco-node"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}