chapybara 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anderson L Polo A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# Chapybara NodeJS SDK
+
+The official NodeJS SDK for the Chapybara Domain & IP Intelligence API.
+
+## Features
+
+- **Fluent, Promise-based API**: Modern and easy to use with `async/await`.
+- **Automatic Retries**: Automatically retries failed requests on server errors (5xx) with exponential backoff.
+- **Configurable Caching**: Built-in LRU caching to reduce latency and save on API quotas.
+- **TypeScript Support**: Ships with detailed type definitions for a superior developer experience.
+- **Custom Error Handling**: Throws specific error types for robust error management.
+
+## Installation
+
+```bash
+npm install chapybara
+```
+
+## Usage
+
+First, import and instantiate the client with your API key.
+
+```javascript
+import { ChapybaraClient } from "chapybara";
+
+const chapybara = new ChapybaraClient({
+  apiKey: "ck_your_api_key_here",
+});
+```
+
+### Get Domain Intelligence
+
+```javascript
+async function getDomainInfo() {
+  try {
+    const data = await chapybara.domain.getIntelligence("google.com");
+    console.log(data.domain_identity);
+    console.log(data.security_analysis);
+  } catch (error) {
+    console.error(`Error fetching domain data: ${error.message}`);
+  }
+}
+
+getDomainInfo();
+```
+
+### Get IP Intelligence
+
+```javascript
+async function getIpInfo() {
+  try {
+    const data = await chapybara.ip.getIntelligence("8.8.8.8");
+    console.log(data.location.country.name);
+    console.log(data.network.organization);
+  } catch (error) {
+    console.error(`Error fetching IP data: ${error.message}`);
+  }
+}
+
+getIpInfo();
+```
+
+### Get Web Tech Data
+
+```javascript
+async function getWebTechInfo() {
+  try {
+    const data = await chapybara.webtech.getScanner("github.com");
+    console.log(data.title);
+    console.log(data.technologies);
+  } catch (error) {
+    console.error(`Error fetching web tech data: ${error.message}`);
+  }
+}
+
+getWebTechInfo();
+```
+
+### Get Account Information
+
+```javascript
+async function getAccountDetails() {
+  try {
+    const data = await chapybara.account.getInfo();
+    console.log("Domain quota remaining:", data.quotas.domain.remaining);
+  } catch (error) {
+    console.error(`Error fetching account info: ${error.message}`);
+  }
+}
+
+getAccountDetails();
+```
+
+## Configuration
+
+You can pass a configuration object to the `ChapybaraClient` constructor:
+
+```javascript
+const chapybara = new ChapybaraClient({
+  apiKey: "ck_your_api_key_here",
+  baseUrl: "https://api.chapyapi.com/api/v1", // Optional: override base URL
+  retries: 2, // Optional: number of retries on server errors (default: 2)
+  timeout: 15000, // Optional: request timeout in ms (default: 20000)
+  cacheOptions: {
+    // Optional: LRU cache options
+    max: 500, // Max number of items in cache
+    ttl: 1000 * 60 * 5, // Cache TTL in ms (5 minutes)
+  },
+});
+```
+
+## Error Handling
+
+The SDK throws custom errors for different API responses, allowing you to handle them gracefully. All errors extend `ChapybaraError`.
+
+- `AuthenticationError`: Invalid or missing API key (401, 403).
+- `RateLimitError`: Rate limit exceeded (429).
+- `NotFoundError`: Resource not found (404).
+- `BadRequestError`: Invalid input (400, 402).
+- `ServerError`: An error occurred on the Chapybara servers (5xx).
+- `APIError`: A generic API error.
+
+```javascript
+import { RateLimitError, AuthenticationError } from "chapybara";
+
+async function handleErrors() {
+  try {
+    await chapybara.domain.getIntelligence("invalid-domain");
+  } catch (error) {
+    if (error instanceof RateLimitError) {
+      console.log("Rate limit hit. Please wait before trying again.");
+    } else if (error instanceof AuthenticationError) {
+      console.log("Authentication failed. Please check your API key.");
+    } else {
+      console.log(`An API error occurred: ${error.message}`);
+      console.log(`Request ID: ${error.requestId}`);
+    }
+  }
+}
+```

package/index.d.ts

@@ -0,0 +1,100 @@
+import type { LRUCache } from "lru-cache";
+
+declare module "chapybara" {
+  interface ChapybaraClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    retries?: number;
+    timeout?: number;
+    cacheOptions?: LRUCache.Options<string, any, unknown>;
+  }
+
+  // API Response Types
+  interface DomainIntelligenceResponse {
+    domain_identity: any;
+    classification: any;
+    dns_records: any;
+    dns_analysis: any;
+    tls_certificate: any;
+    network_details: any;
+    security_analysis: any;
+    metadata: any;
+  }
+
+  interface IPIntelligenceResponse {
+    ip: string;
+    hostnames: string[];
+    location: any;
+    network: any;
+    time_zone: string | null;
+    security: any;
+    ads: any;
+    metadata: any;
+  }
+
+  interface WebTechResponse {
+    domain: string;
+    final_url: string;
+    status_code: number;
+    title: string | null;
+    meta: any;
+    headers: Record<string, string | string[]>;
+    security_headers: Record<string, string | string[]>;
+    cookies: string[];
+    links: any;
+    structure: any;
+    technologies: string[];
+    redirect_chain: any[];
+    metadata: any;
+  }
+
+  interface AccountInfoResponse {
+    quotas: {
+      domain: { limit: number; used: number; remaining: number };
+      ip: { limit: number; used: number; remaining: number };
+      webtech: { limit: number; used: number; remaining: number };
+      reset_date: string;
+    };
+    api_key: {
+      name: string;
+      requests_made: number;
+      allowed_endpoints: string[];
+    };
+    metadata: any;
+  }
+
+  // Error Types
+  export class ChapybaraError extends Error {}
+  export class APIError extends ChapybaraError {
+    status: number;
+    code?: string;
+    requestId?: string;
+  }
+  export class AuthenticationError extends APIError {}
+  export class RateLimitError extends APIError {}
+  export class NotFoundError extends APIError {}
+  export class ServerError extends APIError {}
+  export class BadRequestError extends APIError {}
+
+  export class ChapybaraClient {
+    constructor(options: ChapybaraClientOptions);
+
+    domain: {
+      getIntelligence: (
+        domain: string,
+      ) => Promise<DomainIntelligenceResponse>;
+    };
+
+    ip: {
+      getIntelligence: (ip: string) => Promise<IPIntelligenceResponse>;
+    };
+
+    webtech: {
+      getScanner: (domain: string) => Promise<WebTechResponse>;
+    };
+
+    account: {
+      getInfo: () => Promise<AccountInfoResponse>;
+    };
+  }
+}

package/index.js

@@ -0,0 +1,116 @@
+import fetch from "node-fetch";
+import { LRUCache } from "lru-cache";
+import { APIError, AuthenticationError, BadRequestError, NotFoundError, RateLimitError, ServerError } from "./lib/errors.js";
+
+const DEFAULT_BASE_URL = "https://chapyapi.com/api/v1";
+const DEFAULT_RETRIES = 2;
+const DEFAULT_TIMEOUT = 20000;
+
+export class ChapybaraClient {
+  constructor(options) {
+    if (!options || !options.apiKey) {
+      throw new Error("API key is required.");
+    }
+
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+    this.retries = options.retries ?? DEFAULT_RETRIES;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+
+    if (options.cacheOptions) {
+      this.cache = new LRUCache(options.cacheOptions);
+    }
+
+    this.domain = {
+      getIntelligence: (domain) => this._request(`/domain/${domain}`),
+    };
+
+    this.ip = {
+      getIntelligence: (ip) => this._request(`/ip/${ip}`),
+    };
+
+    this.webtech = {
+      getScanner: (domain) => this._request(`/webtech/${domain}`),
+    };
+
+    this.account = {
+      getInfo: () => this._request("/account"),
+    };
+  }
+
+  async _request(endpoint, attempt = 1) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const cacheKey = endpoint;
+
+    if (this.cache?.has(cacheKey)) {
+      return this.cache.get(cacheKey);
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "X-API-Key": this.apiKey,
+          "Content-Type": "application/json",
+          "User-Agent": "Chapybara-NodeJS-SDK/1.0.0",
+        },
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        if (response.status >= 500 && attempt <= this.retries) {
+          const delay = 2 ** attempt * 100;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          return this._request(endpoint, attempt + 1);
+        }
+        await this._handleError(response);
+      }
+
+      const data = await response.json();
+
+      if (this.cache) {
+        this.cache.set(cacheKey, data);
+      }
+
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        throw new Error("Request timed out");
+      }
+      throw error;
+    }
+  }
+
+  async _handleError(response) {
+    let errorData;
+    try {
+      errorData = await response.json();
+    } catch (e) {
+      errorData = { error: `HTTP ${response.status} Error` };
+    }
+
+    switch (response.status) {
+      case 401:
+      case 403:
+        throw new AuthenticationError(response.status, errorData);
+      case 404:
+        throw new NotFoundError(response.status, errorData);
+      case 429:
+        throw new RateLimitError(response.status, errorData);
+      case 400:
+      case 402:
+        throw new BadRequestError(response.status, errorData);
+      default:
+        if (response.status >= 500) {
+          throw new ServerError(response.status, errorData);
+        }
+        throw new APIError(response.status, errorData);
+    }
+  }
+}

package/lib/errors.js

@@ -0,0 +1,51 @@
+export class ChapybaraError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ChapybaraError";
+  }
+}
+
+export class APIError extends ChapybaraError {
+  constructor(status, error) {
+    super(error?.error || `Request failed with status code ${status}`);
+    this.name = "APIError";
+    this.status = status;
+    this.code = error?.code;
+    this.requestId = error?.requestId;
+  }
+}
+
+export class AuthenticationError extends APIError {
+  constructor(status, error) {
+    super(status, error);
+    this.name = "AuthenticationError";
+  }
+}
+
+export class RateLimitError extends APIError {
+  constructor(status, error) {
+    super(status, error);
+    this.name = "RateLimitError";
+  }
+}
+
+export class NotFoundError extends APIError {
+  constructor(status, error) {
+    super(status, error);
+    this.name = "NotFoundError";
+  }
+}
+
+export class ServerError extends APIError {
+  constructor(status, error) {
+    super(status, error);
+    this.name = "ServerError";
+  }
+}
+
+export class BadRequestError extends APIError {
+  constructor(status, error) {
+    super(status, error);
+    this.name = "BadRequestError";
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "chapybara",
+  "version": "0.1.0",
+  "description": "Official NodeJS SDK for the Chapybara Domain & IP Intelligence API.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "chapybara",
+    "api",
+    "sdk",
+    "domain",
+    "ip",
+    "intelligence",
+    "security"
+  ],
+  "author": "Alpha System",
+  "license": "MIT",
+  "dependencies": {
+    "lru-cache": "^11.2.0",
+    "node-fetch": "^3.3.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}