benchgecko 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BenchGecko
+
+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,99 @@
+# BenchGecko JavaScript SDK
+
+Official JavaScript/TypeScript client for the [BenchGecko](https://benchgecko.ai) API. Query AI model data, benchmark scores, and run side-by-side comparisons from Node.js or any JavaScript runtime.
+
+BenchGecko tracks every major AI model, benchmark, and provider. This SDK wraps the public REST API so you can integrate AI model intelligence into your applications, dashboards, and developer tools.
+
+## Installation
+
+```bash
+npm install benchgecko
+```
+
+Works with Node.js 14+ and any runtime that supports the Fetch API.
+
+## Quick Start
+
+```javascript
+const { BenchGecko } = require('benchgecko');
+
+const client = new BenchGecko();
+
+// List all tracked AI models
+const models = await client.models();
+console.log(`Tracking ${models.length} models`);
+
+// List all benchmarks
+const benchmarks = await client.benchmarks();
+benchmarks.forEach(b => console.log(b.name));
+
+// Compare two models head-to-head
+const comparison = await client.compare(['gpt-4o', 'claude-opus-4']);
+comparison.models.forEach(m => {
+  console.log(m.name, m.scores);
+});
+```
+
+## TypeScript Support
+
+Full TypeScript definitions are included out of the box:
+
+```typescript
+import { BenchGecko, Model, Benchmark, ComparisonResult } from 'benchgecko';
+
+const client = new BenchGecko();
+const models: Model[] = await client.models();
+const result: ComparisonResult = await client.compare(['gpt-4o', 'claude-opus-4']);
+```
+
+## API Reference
+
+### `new BenchGecko(options?)`
+
+Create a client instance.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | string | `https://benchgecko.ai` | API base URL |
+| `timeout` | number | `30000` | Request timeout in ms |
+
+### `client.models()`
+
+Fetch all AI models tracked by BenchGecko. Returns an array of model objects containing name, provider, parameter count, pricing tiers, and benchmark scores.
+
+### `client.benchmarks()`
+
+Fetch all benchmarks tracked by BenchGecko. Returns an array of benchmark objects with name, category, and description.
+
+### `client.compare(models)`
+
+Compare two or more models side by side. Pass an array of model slugs. Returns a structured comparison with per-model scores, pricing, and capability breakdowns.
+
+## Error Handling
+
+```javascript
+const { BenchGecko, BenchGeckoError } = require('benchgecko');
+
+const client = new BenchGecko();
+try {
+  const models = await client.models();
+} catch (error) {
+  if (error instanceof BenchGeckoError) {
+    console.error(`API error: ${error.message} (status: ${error.statusCode})`);
+  }
+}
+```
+
+## Data Attribution
+
+Data provided by [BenchGecko](https://benchgecko.ai). Benchmark scores sourced from official evaluation suites. Pricing data updated daily from provider APIs.
+
+## Links
+
+- [BenchGecko](https://benchgecko.ai) - AI model benchmarks, pricing, and rankings
+- [API Documentation](https://benchgecko.ai/api-docs)
+- [GitHub Repository](https://github.com/BenchGecko/benchgecko-js)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "benchgecko",
+  "version": "1.0.0",
+  "description": "Official JavaScript/TypeScript SDK for the BenchGecko API. Compare AI models, benchmarks, and pricing.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "benchmarks",
+    "llm",
+    "models",
+    "pricing",
+    "machine-learning",
+    "gpt",
+    "claude",
+    "gemini",
+    "api-client"
+  ],
+  "author": "BenchGecko <hello@benchgecko.ai>",
+  "license": "MIT",
+  "homepage": "https://benchgecko.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BenchGecko/benchgecko-js"
+  },
+  "bugs": {
+    "url": "https://github.com/BenchGecko/benchgecko-js/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * BenchGecko - Official TypeScript SDK for the BenchGecko API.
+ */
+
+export interface BenchGeckoOptions {
+  /** API base URL. Defaults to https://benchgecko.ai */
+  baseUrl?: string;
+  /** Request timeout in milliseconds. Defaults to 30000. */
+  timeout?: number;
+}
+
+export interface Model {
+  id: string;
+  name: string;
+  slug: string;
+  provider: string;
+  parameters?: number;
+  context_window?: number;
+  pricing?: {
+    input_per_million?: number;
+    output_per_million?: number;
+  };
+  scores?: Record<string, number>;
+  [key: string]: unknown;
+}
+
+export interface Benchmark {
+  id: string;
+  name: string;
+  slug: string;
+  category: string;
+  description?: string;
+  [key: string]: unknown;
+}
+
+export interface ComparisonResult {
+  models: Array<{
+    name: string;
+    slug: string;
+    provider: string;
+    scores: Record<string, number>;
+    pricing?: {
+      input_per_million?: number;
+      output_per_million?: number;
+    };
+    [key: string]: unknown;
+  }>;
+  [key: string]: unknown;
+}
+
+export class BenchGeckoError extends Error {
+  statusCode: number | null;
+  constructor(message: string, statusCode?: number);
+}
+
+export class BenchGecko {
+  constructor(options?: BenchGeckoOptions);
+
+  /** List all AI models tracked by BenchGecko. */
+  models(): Promise<Model[]>;
+
+  /** List all benchmarks tracked by BenchGecko. */
+  benchmarks(): Promise<Benchmark[]>;
+
+  /** Compare two or more AI models side by side. */
+  compare(models: string[]): Promise<ComparisonResult>;
+}

package/src/index.js

@@ -0,0 +1,124 @@
+/**
+ * BenchGecko - Official JavaScript SDK for the BenchGecko API.
+ *
+ * Compare AI models, benchmarks, and pricing programmatically.
+ *
+ * @example
+ * const { BenchGecko } = require('benchgecko');
+ * const client = new BenchGecko();
+ * const models = await client.models();
+ */
+
+class BenchGeckoError extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = 'BenchGeckoError';
+    this.statusCode = statusCode || null;
+  }
+}
+
+class BenchGecko {
+  /**
+   * Create a BenchGecko API client.
+   *
+   * @param {Object} [options]
+   * @param {string} [options.baseUrl='https://benchgecko.ai'] - API base URL.
+   * @param {number} [options.timeout=30000] - Request timeout in milliseconds.
+   */
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl || 'https://benchgecko.ai').replace(/\/+$/, '');
+    this.timeout = options.timeout || 30000;
+  }
+
+  /**
+   * Send a request to the BenchGecko API.
+   * @private
+   */
+  async _request(path, params = {}) {
+    const url = new URL(path, this.baseUrl);
+    Object.entries(params).forEach(([key, value]) => {
+      url.searchParams.set(key, value);
+    });
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+          'User-Agent': 'benchgecko-js/1.0.0',
+          'Accept': 'application/json',
+        },
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new BenchGeckoError(
+          `API request failed with status ${response.status}: ${response.statusText}`,
+          response.status
+        );
+      }
+
+      return await response.json();
+    } catch (error) {
+      if (error instanceof BenchGeckoError) throw error;
+      if (error.name === 'AbortError') {
+        throw new BenchGeckoError(`Request timed out after ${this.timeout}ms`);
+      }
+      throw new BenchGeckoError(`Request failed: ${error.message}`);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * List all AI models tracked by BenchGecko.
+   *
+   * @returns {Promise<Array<Object>>} Array of model objects with metadata,
+   *   benchmark scores, and pricing information.
+   *
+   * @example
+   * const models = await client.models();
+   * console.log(`Tracking ${models.length} models`);
+   */
+  async models() {
+    return this._request('/api/v1/models');
+  }
+
+  /**
+   * List all benchmarks tracked by BenchGecko.
+   *
+   * @returns {Promise<Array<Object>>} Array of benchmark objects with name,
+   *   category, and description.
+   *
+   * @example
+   * const benchmarks = await client.benchmarks();
+   * benchmarks.forEach(b => console.log(b.name));
+   */
+  async benchmarks() {
+    return this._request('/api/v1/benchmarks');
+  }
+
+  /**
+   * Compare two or more AI models side by side.
+   *
+   * @param {string[]} models - Array of model slugs to compare.
+   * @returns {Promise<Object>} Comparison result with per-model scores and pricing.
+   * @throws {Error} If fewer than 2 models are provided.
+   *
+   * @example
+   * const result = await client.compare(['gpt-4o', 'claude-opus-4']);
+   * result.models.forEach(m => console.log(m.name, m.scores));
+   */
+  async compare(models) {
+    if (!Array.isArray(models) || models.length < 2) {
+      throw new Error('At least 2 models are required for comparison.');
+    }
+    return this._request('/api/v1/compare', {
+      models: models.join(','),
+    });
+  }
+}
+
+module.exports = { BenchGecko, BenchGeckoError };