KeiroLabs JavaScript SDK

Official JavaScript/TypeScript SDK for KeiroLabs API - AI-powered search, research, and web crawling capabilities.

Table of Contents

• Installation
• Quick Start
• TypeScript Support
• Configuration
• API Methods
  • search
  • searchPro
  • searchEngine
  • answer
  • research
  • researchPro
  • webCrawler
  • healthCheck
  • validateApiKey
• Error Handling
• Advanced Usage
• Examples
• API Reference
• Support

Installation

npm install keirolabs

Requirements:

• Node.js >= 14.0.0
• npm or yarn

Quick Start

const { Keiro } = require('keirolabs');

const client = new Keiro(process.env.KEIRO_API_KEY);

async function main() {
  const result = await client.search("machine learning trends 2024");
  console.log(result.data);
  console.log(`Credits remaining: ${result.creditsRemaining}`);
}

main();

Get your API key: https://www.keirolabs.cloud/

TypeScript Support

Full TypeScript support with type definitions included:

import { Keiro, SearchResult, KeiroAuthError } from 'keirolabs';

const client = new Keiro(process.env.KEIRO_API_KEY!);

const result: SearchResult = await client.search("TypeScript best practices");

Configuration

Simple Initialization

Production server is used by default:

const client = new Keiro("your-api-key");

With Options

const client = new Keiro({
  apiKey: "your-api-key",
  timeout: 60000,  // 60 seconds
  baseUrl: "http://localhost:8000/api"  // For local development only
});

Environment Variables

require('dotenv').config();

const client = new Keiro(process.env.KEIRO_API_KEY);

Create .env file:

KEIRO_API_KEY=your-api-key-here

API Methods

search

Perform a neural search query.

Signature:

search(query: string, options?: SearchOptions): Promise<SearchResult>

Parameters:

• query (string, required) - Search query
• options (object, optional) - Additional search parameters

Returns:

• data (array) - Search results
• creditsRemaining (number) - Remaining API credits

Credits: 1 per request

Example:

const result = await client.search("Python best practices");

console.log(`Found ${result.data.length} results`);
console.log(`Credits: ${result.creditsRemaining}`);

result.data.forEach(item => {
  console.log(item.title);
  console.log(item.url);
});

searchPro

Advanced search with enhanced capabilities and deeper results.

Signature:

searchPro(query: string, options?: SearchOptions): Promise<SearchResult>

Credits: Variable

Example:

const result = await client.searchPro("advanced AI architectures");

searchEngine

Access search engine functionality for broader web search.

Signature:

searchEngine(query: string, options?: SearchOptions): Promise<SearchResult>

Credits: Variable

Example:

const results = await client.searchEngine("latest AI papers 2024");

answer

Generate detailed AI-powered answers to questions.

Signature:

answer(query: string, options?: SearchOptions): Promise<AnswerResult>

Parameters:

• query (string, required) - Question to answer
• options (object, optional) - Additional parameters

Returns:

• data (string|object) - Generated answer
• creditsRemaining (number) - Remaining API credits

Credits: 5 per request

Example:

const answer = await client.answer("What is reinforcement learning?");

console.log(answer.data);
console.log(`Credits: ${answer.creditsRemaining}`);

research

Conduct comprehensive research on any topic.

Signature:

research(query: string, options?: SearchOptions): Promise<ResearchResult>

Parameters:

• query (string, required) - Research topic
• options (object, optional) - Research parameters

Returns:

• data (object) - Research results with sources
• creditsRemaining (number) - Remaining API credits

Credits: Variable

Example:

const research = await client.research("climate change solutions");

console.log(research.data);

researchPro

Advanced research with deeper analysis and more comprehensive results.

Signature:

researchPro(query: string, options?: SearchOptions): Promise<ResearchResult>

Credits: Variable

Example:

const research = await client.researchPro("blockchain consensus mechanisms");

webCrawler

Extract structured data from any URL.

Signature:

webCrawler(url: string, options?: SearchOptions): Promise<WebCrawlerResult>

Parameters:

• url (string, required) - Website URL to crawl
• options (object, optional) - Crawler options

Returns:

• data (object) - Extracted content
• creditsRemaining (number) - Remaining API credits

Credits: Variable

Example:

const data = await client.webCrawler("https://example.com/article");

console.log(data.data.content);
console.log(data.data.title);

healthCheck

Check API server status and connectivity.

Signature:

healthCheck(): Promise<HealthCheckResult>

Returns:

• status (string) - Server status
• environment (string) - Environment name
• database (string) - Database status
• service (string) - Service name

Credits: Free

Example:

const health = await client.healthCheck();

console.log(`Status: ${health.status}`);
console.log(`Environment: ${health.environment}`);

validateApiKey

Validate your API key before making requests.

Signature:

validateApiKey(): Promise<ValidateApiKeyResult>

Returns:

• valid (boolean) - Whether the API key is valid
• message (string) - Validation message
• server_status (string) - Server status
• environment (string) - Environment name

Credits: Free

Example:

const validation = await client.validateApiKey();

if (validation.valid) {
  console.log("API key is valid!");
} else {
  console.log(`Invalid: ${validation.message}`);
}

Error Handling

The SDK provides specific exception types for different error scenarios.

Exception Types

| Exception | Description | Common Causes | |-----------|-------------|---------------| | KeiroError | Base exception class | General errors | | KeiroAuthError | Authentication failed | Invalid API key | | KeiroRateLimitError | Rate limit exceeded | Out of credits | | KeiroValidationError | Invalid parameters | Malformed request | | KeiroConnectionError | Network issues | Server unreachable | | KeiroAPIError | API request failed | Server error |

Basic Error Handling

const { Keiro, KeiroAuthError, KeiroRateLimitError } = require('keirolabs');

const client = new Keiro(process.env.KEIRO_API_KEY);

try {
  const result = await client.search("query");
} catch (error) {
  if (error instanceof KeiroAuthError) {
    console.log("Invalid API key");
  } else if (error instanceof KeiroRateLimitError) {
    console.log("Out of credits -  please purchase more");
  } else {
    console.log(`Error: ${error.message}`);
  }
}

Comprehensive Error Handling

const {
  Keiro,
  KeiroAuthError,
  KeiroRateLimitError,
  KeiroValidationError,
  KeiroConnectionError,
  KeiroAPIError
} = require('keirolabs');

async function safeSearch(query) {
  const client = new Keiro(process.env.KEIRO_API_KEY);
  
  try {
    return await client.search(query);
  } catch (error) {
    if (error instanceof KeiroAuthError) {
      console.error("Authentication failed - check your API key");
    } else if (error instanceof KeiroRateLimitError) {
      console.error("Rate limit exceeded - out of credits");
    } else if (error instanceof KeiroValidationError) {
      console.error(`Invalid parameters: ${error.message}`);
    } else if (error instanceof KeiroConnectionError) {
      console.error("Network error - check your connection");
    } else if (error instanceof KeiroAPIError) {
      console.error(`API error: ${error.message}`);
    } else {
      console.error(`Unexpected error: ${error.message}`);
    }
    throw error;
  }
}

Advanced Usage

Custom Timeout

Set custom timeout for long-running requests:

const client = new Keiro({
  apiKey: process.env.KEIRO_API_KEY,
  timeout: 120000  // 2 minutes
});

Local Development

For testing against a local server:

const client = new Keiro({
  apiKey: process.env.KEIRO_API_KEY,
  baseUrl: "http://localhost:8000/api"
});

Dynamic Base URL

Change the base URL after initialization:

const client = new Keiro(process.env.KEIRO_API_KEY);

client.setBaseUrl("https://staging-api.keiro.com/api");

Examples

Example 1: Basic Search

const { Keiro } = require('keirolabs');

async function basicSearch() {
  const client = new Keiro(process.env.KEIRO_API_KEY);
  
  const result = await client.search("JavaScript async patterns");
  
  console.log(`Found: ${result.data.length} results`);
  console.log(`Credits: ${result.creditsRemaining}`);
  
  result.data.forEach((item, index) => {
    console.log(`\n${index + 1}. ${item.title}`);
    console.log(`   URL: ${item.url}`);
  });
}

basicSearch();

Example 2: Research with Answer

async function researchAndAnswer() {
  const client = new Keiro(process.env.KEIRO_API_KEY);
  
  const topic = "quantum computing applications";
  const research = await client.research(topic);
  
  console.log("Research Results:");
  console.log(research.data);
  
  const answer = await client.answer(`Summarize: ${topic}`);
  console.log("\nAI Summary:");
  console.log(answer.data);
}

Example 3: Batch Processing

async function batchSearch() {
  const client = new Keiro(process.env.KEIRO_API_KEY);
  
  const queries = [
    "Python best practices",
    "JavaScript frameworks",
    "TypeScript migration"
  ];
  
  const results = await Promise.all(
    queries.map(query => client.search(query))
  );
  
  results.forEach((result, index) => {
    console.log(`Query: ${queries[index]}`);
    console.log(`Results: ${result.data.length}`);
    console.log(`Credits: ${result.creditsRemaining}\n`);
  });
}

Example 4: Error Handling with Retry

async function searchWithRetry(query, maxRetries = 3) {
  const client = new Keiro(process.env.KEIRO_API_KEY);
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await client.search(query);
    } catch (error) {
      if (error instanceof KeiroRateLimitError) {
        throw error;  // Don't retry on rate limit
      }
      
      if (attempt === maxRetries) throw error;
      
      console.log(`Attempt ${attempt} failed, retrying...`);
      await new Promise(r => setTimeout(r, 1000 * attempt));
    }
  }
}

API Reference

Types

SearchResult

interface SearchResult {
  data: any;
  creditsRemaining: number;
}

AnswerResult

interface AnswerResult {
  data: any;
  creditsRemaining: number;
}

ResearchResult

interface ResearchResult {
  data: any;
  creditsRemaining: number;
}

WebCrawlerResult

interface WebCrawlerResult {
  data: any;
  creditsRemaining: number;
}

HealthCheckResult

interface HealthCheckResult {
  status: string;
  environment: string;
  database?: string;
  service?: string;
}

ValidateApiKeyResult

interface ValidateApiKeyResult {
  valid: boolean;
  message: string;
  server_status: string;
  environment: string;
}

Credits System

| Operation | Credits | Description | |-----------|---------|-------------| | search() | 1 | Basic search query | | searchPro() | Variable | Advanced search | | searchEngine() | Variable | Search engine access | | answer() | 5 | AI answer generation | | research() | Variable | Topic research | | researchPro() | Variable | Advanced research | | webCrawler() | Variable | Web page extraction | | healthCheck() | Free | Server status | | validateApiKey() | Free | API key validation |

Links

• npm Package: https://www.npmjs.com/package/keirolabs
• Homepage: https://www.keirolabs.cloud/
• API Dashboard: https://www.keirolabs.cloud/
• Support: [email protected]
• Python SDK: https://pypi.org/project/keirolabs

License

MIT License - see LICENSE file for details.

Version 0.1.2

Made by KeiroLabs Team