@froredion/codebase-indexer-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# Codebase Indexer SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Search the code and documents indexed on your [Codebase Indexer](https://codebaseindexer.com) account from your own app:
+ranked passages with their file, line range and heading trail, ready to put in a prompt. No dependencies, so it runs
+anywhere `fetch` works: Node 18+, serverless, and edge runtimes.
+
+```bash
+npm install @froredion/codebase-indexer-sdk
+```
+
+```ts
+import { CodebaseIndexer, formatContext } from '@froredion/codebase-indexer-sdk';
+
+const cbi = new CodebaseIndexer({ apiKey: process.env.CODEBASE_INDEXER_API_KEY });
+
+const results = await cbi.search('What is our refund policy?', { limit: 5 });
+const context = formatContext(results);
+// [1] handbook/policies/refunds.md:6-8 — Refund policy › Who approves refunds
+// Support leads approve refunds up to $500; anything larger goes to the finance team.
+// …
+
+// e.g. with any LLM:
+// system: "Answer from the context and cite sources by number.\n\n" + context
+```
+
+## API key
+
+Create one under **API keys** in the [dashboard](https://codebaseindexer.com/api-keys). Keep it on your server, never in
+a browser bundle. Without `apiKey`, the SDK reads `CODEBASE_INDEXER_API_KEY`.
+
+## Getting content in
+
+The SDK searches; it doesn't upload. Files are read and chunked where they live, with the CLI. Run it from CI to keep a
+docs folder or repo up to date (only changed files are re-embedded):
+
+```bash
+CODEBASE_INDEXER_TOKEN=<api key> npx @froredion/codebase-indexer index ./docs
+```
+
+Markdown/MDX, plain text, reStructuredText and code in 30+ languages are indexed.
+
+## Options
+
+```ts
+cbi.search(query, {
+  scope: 'account',          // default: everything on the account; or 'codebase' with codebaseId
+  codebaseId: '…',
+  limit: 10,                 // 1–50
+  languages: ['markdown'],
+  contentTypes: ['markdown'], // 'code' | 'text' | 'markdown' | 'markdown_code' | 'markdown_table' | 'frontmatter'
+  pathPrefix: 'policies/',
+  signal,                    // AbortSignal
+});
+```
+
+Each result has `codebaseName`, `filePath`, `startLine`, `endLine`, `headingPath`, `content`, `score`, `language`,
+`contentType`, `codebaseId` and `workspaceId`.
+
+Errors are `CodebaseIndexerError` with the HTTP `status` and an API `code`, for example `unauthorized`,
+`payment_required` (billing needs attention; the message says what to do), or `spending_limit_reached`. Network errors,
+`429` and `5xx` are retried twice, and a retried search is billed once.
+
+Usage is billed to the account the key belongs to: pay per use, with prices at
+[codebaseindexer.com](https://codebaseindexer.com/#pricing).

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Codebase Indexer SDK: search the code and documents indexed on your account from your own app,
+ * e.g. as the retrieval step of a RAG pipeline. No dependencies; runs anywhere `fetch` does (Node 18+,
+ * serverless, edge runtimes). Indexing stays with the CLI (`npx @froredion/codebase-indexer index`),
+ * because files are read and chunked where they live.
+ *
+ *   const cbi = new CodebaseIndexer({ apiKey: process.env.CODEBASE_INDEXER_API_KEY });
+ *   const results = await cbi.search('What is our refund policy?', { limit: 5 });
+ *   const context = formatContext(results); // numbered passages with their sources, for a prompt
+ */
+export declare const DEFAULT_BASE_URL = "https://api.codebaseindexer.com";
+export type ContentType = 'code' | 'text' | 'markdown' | 'markdown_code' | 'markdown_table' | 'frontmatter';
+export interface CodebaseIndexerOptions {
+    /** A key from the dashboard (or a machine token). Defaults to CODEBASE_INDEXER_API_KEY, then CODEBASE_INDEXER_TOKEN. */
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /** Retries for network errors, 429 and 5xx (default 2). A retried search is never billed twice. */
+    maxRetries?: number;
+}
+export interface SearchOptions {
+    /** `account` (default): everything indexed on the account. `codebase`: one codebase, by `codebaseId`. */
+    scope?: 'account' | 'codebase';
+    codebaseId?: string;
+    /** 1–50, default 10. */
+    limit?: number;
+    /** Only these languages, e.g. ['markdown'] or ['typescript', 'python']. */
+    languages?: string[];
+    /** Only these chunk kinds, e.g. ['markdown'] for prose. */
+    contentTypes?: ContentType[];
+    /** Only files under this path, e.g. 'policies/'. */
+    pathPrefix?: string;
+    signal?: AbortSignal;
+}
+export interface SearchResult {
+    codebaseId: string;
+    codebaseName: string;
+    workspaceId: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    language: string;
+    contentType: ContentType;
+    /** Markdown heading trail, e.g. ['Refund policy', 'Who approves refunds']. */
+    headingPath: string[];
+    content: string;
+    /** Cosine similarity, higher is closer. */
+    score: number;
+}
+export declare class CodebaseIndexerError extends Error {
+    /** HTTP status; 0 when the API couldn't be reached. */
+    readonly status: number;
+    /** API error code, e.g. 'unauthorized', 'payment_required', 'spending_limit_reached'. */
+    readonly code: string;
+    constructor(message: string, 
+    /** HTTP status; 0 when the API couldn't be reached. */
+    status: number, 
+    /** API error code, e.g. 'unauthorized', 'payment_required', 'spending_limit_reached'. */
+    code: string);
+}
+export declare class CodebaseIndexer {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetcher;
+    private readonly maxRetries;
+    constructor(options?: CodebaseIndexerOptions);
+    /** Semantic search over the account's indexed code and documents, best match first. */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    private request;
+}
+/**
+ * Renders results as numbered passages with their sources, ready to put in a prompt. Stops before
+ * `maxChars` (default 12,000) so the context stays within budget.
+ */
+export declare function formatContext(results: SearchResult[], options?: {
+    maxChars?: number;
+}): string;

package/dist/index.js

@@ -0,0 +1,126 @@
+/**
+ * Codebase Indexer SDK: search the code and documents indexed on your account from your own app,
+ * e.g. as the retrieval step of a RAG pipeline. No dependencies; runs anywhere `fetch` does (Node 18+,
+ * serverless, edge runtimes). Indexing stays with the CLI (`npx @froredion/codebase-indexer index`),
+ * because files are read and chunked where they live.
+ *
+ *   const cbi = new CodebaseIndexer({ apiKey: process.env.CODEBASE_INDEXER_API_KEY });
+ *   const results = await cbi.search('What is our refund policy?', { limit: 5 });
+ *   const context = formatContext(results); // numbered passages with their sources, for a prompt
+ */
+export const DEFAULT_BASE_URL = 'https://api.codebaseindexer.com';
+const SDK_VERSION = '0.1.0';
+export class CodebaseIndexerError extends Error {
+    status;
+    code;
+    constructor(message, 
+    /** HTTP status; 0 when the API couldn't be reached. */
+    status, 
+    /** API error code, e.g. 'unauthorized', 'payment_required', 'spending_limit_reached'. */
+    code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'CodebaseIndexerError';
+    }
+}
+function envVar(name) {
+    const env = globalThis.process?.env;
+    return env?.[name] || undefined;
+}
+export class CodebaseIndexer {
+    apiKey;
+    baseUrl;
+    fetcher;
+    maxRetries;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? envVar('CODEBASE_INDEXER_API_KEY') ?? envVar('CODEBASE_INDEXER_TOKEN');
+        if (!apiKey)
+            throw new CodebaseIndexerError('No API key: pass `apiKey` or set CODEBASE_INDEXER_API_KEY.', 0, 'unauthorized');
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+        this.maxRetries = options.maxRetries ?? 2;
+    }
+    /** Semantic search over the account's indexed code and documents, best match first. */
+    async search(query, options = {}) {
+        const scope = options.scope ?? (options.codebaseId ? 'codebase' : 'account');
+        if (scope === 'codebase' && !options.codebaseId)
+            throw new CodebaseIndexerError('scope "codebase" needs codebaseId', 400, 'validation_error');
+        const body = {
+            query,
+            scope,
+            codebase_id: options.codebaseId,
+            limit: options.limit ?? 10,
+            filters: { languages: options.languages, content_types: options.contentTypes, path_prefix: options.pathPrefix },
+        };
+        const response = await this.request('/v1/search', body, options.signal);
+        return response.results.map((r) => ({
+            codebaseId: r.codebase_id,
+            codebaseName: r.codebase_name,
+            workspaceId: r.workspace_id,
+            filePath: r.file_path,
+            startLine: r.start_line,
+            endLine: r.end_line,
+            language: r.language,
+            contentType: r.content_type,
+            headingPath: r.heading_path,
+            content: r.content,
+            score: r.score,
+        }));
+    }
+    async request(path, body, signal) {
+        // One key per logical call: the API bills a retried request once.
+        const idempotencyKey = crypto.randomUUID();
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            if (attempt > 0)
+                await new Promise((r) => setTimeout(r, 400 * 2 ** (attempt - 1)));
+            let response;
+            try {
+                response = await this.fetcher(`${this.baseUrl}${path}`, {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${this.apiKey}`,
+                        'content-type': 'application/json',
+                        'idempotency-key': idempotencyKey,
+                        'x-codebase-indexer-client': `sdk/${SDK_VERSION}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal,
+                });
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                lastError = new CodebaseIndexerError(`Could not reach Codebase Indexer: ${error instanceof Error ? error.message : String(error)}`, 0, 'network_error');
+                continue;
+            }
+            const json = (await response.json().catch(() => undefined));
+            if (response.ok && json)
+                return json;
+            lastError = new CodebaseIndexerError(json?.error?.message ?? `HTTP ${response.status}`, response.status, json?.error?.code ?? 'internal_error');
+            if (response.status < 500 && response.status !== 429)
+                break;
+        }
+        throw lastError;
+    }
+}
+/**
+ * Renders results as numbered passages with their sources, ready to put in a prompt. Stops before
+ * `maxChars` (default 12,000) so the context stays within budget.
+ */
+export function formatContext(results, options = {}) {
+    const maxChars = options.maxChars ?? 12_000;
+    const parts = [];
+    let used = 0;
+    for (const [i, r] of results.entries()) {
+        const heading = r.headingPath.length ? ` — ${r.headingPath.join(' › ')}` : '';
+        const part = `[${i + 1}] ${r.codebaseName}/${r.filePath}:${r.startLine}-${r.endLine}${heading}\n${r.content.trim()}`;
+        if (used + part.length > maxChars && parts.length > 0)
+            break;
+        parts.push(part);
+        used += part.length + 2;
+    }
+    return parts.join('\n\n');
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@froredion/codebase-indexer-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Search your Codebase Indexer code and documents from your own app: ranked passages with sources, ready for a RAG prompt.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "homepage": "https://codebaseindexer.com",
+  "keywords": ["rag", "retrieval", "semantic-search", "embeddings", "documentation", "code-search", "llm"],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist/index.js", "dist/index.d.ts", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@codebase-indexer/shared": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}