fugu-sdk 1.0.2

package/README.md

@@ -0,0 +1,127 @@
+# fugu-sdk
+
+TypeScript SDK for the FUGU routed RAG API. Class-based, zero runtime
+dependencies (uses the platform `fetch`), works in Node 18+ and browsers.
+
+## Install
+
+```bash
+npm install fugu-sdk
+```
+
+## Quick start
+
+```ts
+import { FuguClient } from 'fugu-sdk';
+
+const client = new FuguClient({ apiKey: 'fugu_sk_...' });
+
+const result = await client.query.execute('what does FUGU combine to answer questions');
+console.log(result.answer);
+```
+
+Pass `baseUrl` to point at a non-default deployment:
+
+```ts
+new FuguClient({ apiKey: '...', baseUrl: 'https://api.example.com/api' });
+```
+
+## Resources
+
+The client exposes three resource groups:
+
+- `client.query` — run queries (`execute`, `stream`)
+- `client.documents` — manage documents (`list`, `get`, `upload`, `delete`, `retry`)
+- `client.credentials` — manage the org's BYOK LLM credential (`get`, `listModels`, `save`, `remove`)
+
+### Queries
+
+```ts
+const result = await client.query.execute('my question', {
+  strategy: 'hybrid', // 'vector_only' | 'graph_only' | 'hybrid' | 'auto'
+  top_k: 10,
+});
+```
+
+Streaming (async generator of SSE events):
+
+```ts
+for await (const event of client.query.stream('my question')) {
+  switch (event.type) {
+    case 'meta':
+      console.log('sources:', event.results);
+      break;
+    case 'delta':
+      process.stdout.write(event.text);
+      break;
+    case 'done':
+      console.log('\ncitations:', event.citations);
+      break;
+    case 'error':
+      console.error('stream error:', event.message);
+      break;
+  }
+}
+```
+
+### Documents
+
+```ts
+const { document_id } = await client.documents.upload({
+  filename: 'report.pdf',
+  data: fs.readFileSync('report.pdf'), // Buffer, Uint8Array, or Blob
+});
+
+const docs = await client.documents.list({ limit: 20, offset: 0 });
+const doc = await client.documents.get(document_id);
+await client.documents.retry(document_id);
+await client.documents.delete(document_id);
+```
+
+### Credentials (BYOK)
+
+```ts
+const models = await client.credentials.listModels('openrouter');
+
+await client.credentials.save({
+  provider: 'openrouter',
+  model: models.find((m) => m.free)?.id ?? models[0].id,
+  apiKey: 'sk-or-...',
+});
+
+const credential = await client.credentials.get(); // { provider, model, keyLastFour, lastVerifiedAt } | null
+await client.credentials.remove();
+```
+
+## Errors
+
+All non-2xx responses throw `FuguApiError` (with `status` and `code`).
+Two conditions get typed subclasses so you can branch without string-matching:
+
+```ts
+import { FuguApiError, BYOKRequiredError, QuotaExceededError } from 'fugu-sdk';
+
+try {
+  await client.query.execute('...');
+} catch (err) {
+  if (err instanceof BYOKRequiredError) {
+    // org has no LLM credential configured (HTTP 409)
+  } else if (err instanceof QuotaExceededError) {
+    // monthly query quota exceeded (HTTP 429)
+  } else if (err instanceof FuguApiError) {
+    console.error(err.status, err.code, err.message);
+  }
+}
+```
+
+## Example
+
+See [examples/basic-query.ts](examples/basic-query.ts). Run with:
+
+```bash
+npm install
+npm run build
+FUGU_API_KEY=fugu_sk_... node -r ts-node/register examples/basic-query.ts
+# or, after building:
+FUGU_API_KEY=fugu_sk_... node -e "require('./dist/index')" # see examples for a full script
+```

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import { QueryResource } from './resources/query';
+import { DocumentsResource } from './resources/documents';
+import { CredentialsResource } from './resources/credentials';
+export interface FuguClientOptions {
+    /** API key issued from the FUGU dashboard, of the form `fugu_sk_...`. */
+    apiKey: string;
+    /** Base API URL. Defaults to `http://localhost:3001/api` for local dev. */
+    baseUrl?: string;
+    /** Custom `fetch` implementation (useful for testing or non-standard runtimes). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Entry point for the FUGU SDK.
+ *
+ * ```ts
+ * const client = new FuguClient({ apiKey: 'fugu_sk_...' });
+ * const result = await client.query.execute('what does FUGU combine to answer questions');
+ * for await (const event of client.query.stream('...')) { ... }
+ * await client.documents.upload({ filename: 'doc.pdf', data: buffer });
+ * const credential = await client.credentials.get();
+ * ```
+ */
+export declare class FuguClient {
+    readonly query: QueryResource;
+    readonly documents: DocumentsResource;
+    readonly credentials: CredentialsResource;
+    constructor(options: FuguClientOptions);
+}

package/dist/client.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FuguClient = void 0;
+const http_1 = require("./http");
+const query_1 = require("./resources/query");
+const documents_1 = require("./resources/documents");
+const credentials_1 = require("./resources/credentials");
+/**
+ * Entry point for the FUGU SDK.
+ *
+ * ```ts
+ * const client = new FuguClient({ apiKey: 'fugu_sk_...' });
+ * const result = await client.query.execute('what does FUGU combine to answer questions');
+ * for await (const event of client.query.stream('...')) { ... }
+ * await client.documents.upload({ filename: 'doc.pdf', data: buffer });
+ * const credential = await client.credentials.get();
+ * ```
+ */
+class FuguClient {
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error('FuguClient requires an apiKey');
+        const http = new http_1.HttpClient({
+            apiKey: options.apiKey,
+            baseUrl: (options.baseUrl ?? 'http://localhost:3001/api').replace(/\/+$/, ''),
+            fetchImpl: options.fetchImpl ?? fetch,
+        });
+        this.query = new query_1.QueryResource(http);
+        this.documents = new documents_1.DocumentsResource(http);
+        this.credentials = new credentials_1.CredentialsResource(http);
+    }
+}
+exports.FuguClient = FuguClient;

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+export interface ApiErrorBody {
+    error?: {
+        message?: string;
+        code?: string;
+    };
+}
+/** Base error for any non-2xx response from the FUGU API. */
+export declare class FuguApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+/**
+ * Thrown when a query is rejected because the organization has no active
+ * LLM credential configured (BYOK). Distinct subclass so callers can branch
+ * on `instanceof BYOKRequiredError` instead of string-matching `code`.
+ */
+export declare class BYOKRequiredError extends FuguApiError {
+    constructor(message: string, status: number);
+}
+/** Thrown when the organization's monthly query quota has been exceeded. */
+export declare class QuotaExceededError extends FuguApiError {
+    constructor(message: string, status: number);
+}
+/** Builds the right error subclass from a parsed error-response body. */
+export declare function errorFromResponse(status: number, body: ApiErrorBody | null): FuguApiError;

package/dist/errors.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotaExceededError = exports.BYOKRequiredError = exports.FuguApiError = void 0;
+exports.errorFromResponse = errorFromResponse;
+/** Base error for any non-2xx response from the FUGU API. */
+class FuguApiError extends Error {
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'FuguApiError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.FuguApiError = FuguApiError;
+/**
+ * Thrown when a query is rejected because the organization has no active
+ * LLM credential configured (BYOK). Distinct subclass so callers can branch
+ * on `instanceof BYOKRequiredError` instead of string-matching `code`.
+ */
+class BYOKRequiredError extends FuguApiError {
+    constructor(message, status) {
+        super(message, status, 'BYOK_REQUIRED');
+        this.name = 'BYOKRequiredError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.BYOKRequiredError = BYOKRequiredError;
+/** Thrown when the organization's monthly query quota has been exceeded. */
+class QuotaExceededError extends FuguApiError {
+    constructor(message, status) {
+        super(message, status, 'QUOTA_EXCEEDED');
+        this.name = 'QuotaExceededError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.QuotaExceededError = QuotaExceededError;
+/** Builds the right error subclass from a parsed error-response body. */
+function errorFromResponse(status, body) {
+    const message = body?.error?.message ?? `Request failed with status ${status}`;
+    const code = body?.error?.code;
+    if (code === 'BYOK_REQUIRED')
+        return new BYOKRequiredError(message, status);
+    if (code === 'QUOTA_EXCEEDED')
+        return new QuotaExceededError(message, status);
+    return new FuguApiError(message, status, code);
+}

package/dist/http.d.ts

@@ -0,0 +1,37 @@
+export interface HttpClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    fetchImpl: typeof fetch;
+}
+/**
+ * Thin wrapper around `fetch` shared by all resource sub-clients. Handles
+ * auth header injection, base URL joining, JSON (de)serialization, and
+ * translating non-2xx responses into typed `FuguApiError`s.
+ */
+export declare class HttpClient {
+    private readonly opts;
+    constructor(opts: HttpClientOptions);
+    private url;
+    private authHeaders;
+    requestJson<T>(path: string, init: {
+        method: string;
+        body?: unknown;
+        query?: Record<string, string | number | undefined>;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    requestForm<T>(path: string, init: {
+        method: string;
+        form: FormData;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    requestVoid(path: string, init: {
+        method: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Raw streaming request used by the SSE query stream. Returns the fetch Response. */
+    requestStream(path: string, init: {
+        method: string;
+        body?: unknown;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+}

package/dist/http.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const errors_1 = require("./errors");
+/**
+ * Thin wrapper around `fetch` shared by all resource sub-clients. Handles
+ * auth header injection, base URL joining, JSON (de)serialization, and
+ * translating non-2xx responses into typed `FuguApiError`s.
+ */
+class HttpClient {
+    constructor(opts) {
+        this.opts = opts;
+    }
+    url(path) {
+        return `${this.opts.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+    }
+    authHeaders(extra) {
+        return {
+            Authorization: `Bearer ${this.opts.apiKey}`,
+            ...extra,
+        };
+    }
+    async requestJson(path, init) {
+        let finalUrl = this.url(path);
+        if (init.query) {
+            const params = new URLSearchParams();
+            for (const [k, v] of Object.entries(init.query)) {
+                if (v !== undefined)
+                    params.set(k, String(v));
+            }
+            const qs = params.toString();
+            if (qs)
+                finalUrl += `?${qs}`;
+        }
+        const res = await this.opts.fetchImpl(finalUrl, {
+            method: init.method,
+            headers: this.authHeaders(init.body !== undefined ? { 'Content-Type': 'application/json' } : undefined),
+            body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+            signal: init.signal,
+        });
+        if (res.status === 204) {
+            return undefined;
+        }
+        const body = await res.json().catch(() => null);
+        if (!res.ok) {
+            throw (0, errors_1.errorFromResponse)(res.status, body);
+        }
+        return body;
+    }
+    async requestForm(path, init) {
+        const res = await this.opts.fetchImpl(this.url(path), {
+            method: init.method,
+            headers: this.authHeaders(),
+            body: init.form,
+            signal: init.signal,
+        });
+        const body = await res.json().catch(() => null);
+        if (!res.ok) {
+            throw (0, errors_1.errorFromResponse)(res.status, body);
+        }
+        return body;
+    }
+    async requestVoid(path, init) {
+        const res = await this.opts.fetchImpl(this.url(path), {
+            method: init.method,
+            headers: this.authHeaders(),
+            signal: init.signal,
+        });
+        if (res.status === 204 || res.ok)
+            return;
+        const body = await res.json().catch(() => null);
+        throw (0, errors_1.errorFromResponse)(res.status, body);
+    }
+    /** Raw streaming request used by the SSE query stream. Returns the fetch Response. */
+    async requestStream(path, init) {
+        return this.opts.fetchImpl(this.url(path), {
+            method: init.method,
+            headers: this.authHeaders(init.body !== undefined ? { 'Content-Type': 'application/json' } : undefined),
+            body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+            signal: init.signal,
+        });
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { FuguClient, type FuguClientOptions } from './client';
+export { QueryResource } from './resources/query';
+export { DocumentsResource, type UploadFileInput } from './resources/documents';
+export { CredentialsResource } from './resources/credentials';
+export { FuguApiError, BYOKRequiredError, QuotaExceededError } from './errors';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotaExceededError = exports.BYOKRequiredError = exports.FuguApiError = exports.CredentialsResource = exports.DocumentsResource = exports.QueryResource = exports.FuguClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "FuguClient", { enumerable: true, get: function () { return client_1.FuguClient; } });
+var query_1 = require("./resources/query");
+Object.defineProperty(exports, "QueryResource", { enumerable: true, get: function () { return query_1.QueryResource; } });
+var documents_1 = require("./resources/documents");
+Object.defineProperty(exports, "DocumentsResource", { enumerable: true, get: function () { return documents_1.DocumentsResource; } });
+var credentials_1 = require("./resources/credentials");
+Object.defineProperty(exports, "CredentialsResource", { enumerable: true, get: function () { return credentials_1.CredentialsResource; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "FuguApiError", { enumerable: true, get: function () { return errors_1.FuguApiError; } });
+Object.defineProperty(exports, "BYOKRequiredError", { enumerable: true, get: function () { return errors_1.BYOKRequiredError; } });
+Object.defineProperty(exports, "QuotaExceededError", { enumerable: true, get: function () { return errors_1.QuotaExceededError; } });
+__exportStar(require("./types"), exports);

package/dist/resources/credentials.d.ts

@@ -0,0 +1,13 @@
+import { HttpClient } from '../http';
+import type { CredentialDisplay, CredentialModel, LLMCredentialProvider, SaveCredentialInput } from '../types';
+export declare class CredentialsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Returns the organization's configured BYOK credential, or `null` if none is set. */
+    get(signal?: AbortSignal): Promise<CredentialDisplay | null>;
+    /** Lists available models for a provider, including free-tier availability. */
+    listModels(provider: LLMCredentialProvider, signal?: AbortSignal): Promise<CredentialModel[]>;
+    /** Saves (creates or replaces) the organization's BYOK credential. Validates the key with a real test call server-side. */
+    save(input: SaveCredentialInput, signal?: AbortSignal): Promise<CredentialDisplay>;
+    remove(signal?: AbortSignal): Promise<void>;
+}

package/dist/resources/credentials.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialsResource = void 0;
+class CredentialsResource {
+    constructor(http) {
+        this.http = http;
+    }
+    /** Returns the organization's configured BYOK credential, or `null` if none is set. */
+    async get(signal) {
+        const res = await this.http.requestJson('/organization/llm-credential', {
+            method: 'GET',
+            signal,
+        });
+        return res.credential;
+    }
+    /** Lists available models for a provider, including free-tier availability. */
+    async listModels(provider, signal) {
+        const res = await this.http.requestJson('/organization/llm-credential/models', {
+            method: 'GET',
+            query: { provider },
+            signal,
+        });
+        return res.models;
+    }
+    /** Saves (creates or replaces) the organization's BYOK credential. Validates the key with a real test call server-side. */
+    async save(input, signal) {
+        const res = await this.http.requestJson('/organization/llm-credential', {
+            method: 'PUT',
+            body: input,
+            signal,
+        });
+        return res.credential;
+    }
+    async remove(signal) {
+        await this.http.requestVoid('/organization/llm-credential', { method: 'DELETE', signal });
+    }
+}
+exports.CredentialsResource = CredentialsResource;

package/dist/resources/documents.d.ts

@@ -0,0 +1,23 @@
+import { HttpClient } from '../http';
+import type { DocumentUploadResponse, FuguDocument, ListDocumentsOptions } from '../types';
+export interface UploadFileInput {
+    /** File name including extension, used for type detection server-side. */
+    filename: string;
+    /** File contents. Accepts a Blob/File (browser) or a Buffer/Uint8Array (Node). */
+    data: Blob | Buffer | Uint8Array;
+    /** Optional MIME type; inferred by the platform's Blob implementation if omitted. */
+    contentType?: string;
+}
+export declare class DocumentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: ListDocumentsOptions): Promise<FuguDocument[]>;
+    get(id: string, signal?: AbortSignal): Promise<FuguDocument>;
+    /** Uploads a document (multipart/form-data, field name `file`). 50MB limit. */
+    upload(file: UploadFileInput, signal?: AbortSignal): Promise<DocumentUploadResponse>;
+    delete(id: string, signal?: AbortSignal): Promise<void>;
+    /** Re-queues a failed or pending document for ingestion. */
+    retry(id: string, signal?: AbortSignal): Promise<{
+        status: 'pending';
+    }>;
+}

package/dist/resources/documents.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentsResource = void 0;
+class DocumentsResource {
+    constructor(http) {
+        this.http = http;
+    }
+    async list(options = {}) {
+        const res = await this.http.requestJson('/documents', {
+            method: 'GET',
+            query: { limit: options.limit, offset: options.offset },
+            signal: options.signal,
+        });
+        return res.documents;
+    }
+    async get(id, signal) {
+        const res = await this.http.requestJson(`/documents/${encodeURIComponent(id)}`, {
+            method: 'GET',
+            signal,
+        });
+        return res.document;
+    }
+    /** Uploads a document (multipart/form-data, field name `file`). 50MB limit. */
+    async upload(file, signal) {
+        const form = new FormData();
+        const blob = file.data instanceof Blob ? file.data : new Blob([new Uint8Array(file.data)], { type: file.contentType });
+        form.append('file', blob, file.filename);
+        return this.http.requestForm('/documents', {
+            method: 'POST',
+            form,
+            signal,
+        });
+    }
+    async delete(id, signal) {
+        await this.http.requestVoid(`/documents/${encodeURIComponent(id)}`, { method: 'DELETE', signal });
+    }
+    /** Re-queues a failed or pending document for ingestion. */
+    async retry(id, signal) {
+        return this.http.requestJson(`/documents/${encodeURIComponent(id)}/retry`, {
+            method: 'POST',
+            signal,
+        });
+    }
+}
+exports.DocumentsResource = DocumentsResource;

package/dist/resources/query.d.ts

@@ -0,0 +1,19 @@
+import { HttpClient } from '../http';
+import type { QueryOptions, QueryResponse, QueryStreamEvent } from '../types';
+export declare class QueryResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Runs a query and waits for the full (non-streaming) answer. */
+    execute(query: string, options?: QueryOptions): Promise<QueryResponse>;
+    /**
+     * Runs a query and streams the answer token-by-token via Server-Sent
+     * Events. Yields `QueryStreamEvent`s as they arrive:
+     *
+     * ```ts
+     * for await (const event of client.query.stream('...')) {
+     *   if (event.type === 'delta') process.stdout.write(event.text);
+     * }
+     * ```
+     */
+    stream(query: string, options?: QueryOptions): AsyncGenerator<QueryStreamEvent, void, void>;
+}

package/dist/resources/query.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryResource = void 0;
+const errors_1 = require("../errors");
+class QueryResource {
+    constructor(http) {
+        this.http = http;
+    }
+    /** Runs a query and waits for the full (non-streaming) answer. */
+    async execute(query, options = {}) {
+        return this.http.requestJson('/queries/v1/query', {
+            method: 'POST',
+            body: { query, strategy: options.strategy, top_k: options.top_k },
+            signal: options.signal,
+        });
+    }
+    /**
+     * Runs a query and streams the answer token-by-token via Server-Sent
+     * Events. Yields `QueryStreamEvent`s as they arrive:
+     *
+     * ```ts
+     * for await (const event of client.query.stream('...')) {
+     *   if (event.type === 'delta') process.stdout.write(event.text);
+     * }
+     * ```
+     */
+    async *stream(query, options = {}) {
+        const res = await this.http.requestStream('/queries/stream', {
+            method: 'POST',
+            body: { query, strategy: options.strategy, top_k: options.top_k },
+            signal: options.signal,
+        });
+        if (!res.ok || !res.body) {
+            const body = await res.json().catch(() => null);
+            throw (0, errors_1.errorFromResponse)(res.status, body);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let sep;
+                while ((sep = buffer.indexOf('\n\n')) !== -1) {
+                    const frame = buffer.slice(0, sep);
+                    buffer = buffer.slice(sep + 2);
+                    const line = frame.split('\n').find((l) => l.startsWith('data:'));
+                    if (!line)
+                        continue;
+                    const event = JSON.parse(line.slice(5).trim());
+                    yield event;
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}
+exports.QueryResource = QueryResource;

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+export type QueryStrategy = 'vector_only' | 'graph_only' | 'hybrid' | 'auto';
+export interface QuerySource {
+    content: string;
+    source: 'vector' | 'graph';
+    score: number;
+    document_id?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface QuotaInfo {
+    used: number;
+    limit: number;
+    percent: number;
+    warn: boolean;
+}
+export interface QueryResponse {
+    answer: string;
+    citations: string[];
+    answer_degraded: boolean;
+    results: QuerySource[];
+    explain: Record<string, unknown>;
+    quota: QuotaInfo;
+}
+export interface QueryOptions {
+    strategy?: QueryStrategy;
+    top_k?: number;
+    signal?: AbortSignal;
+}
+/** Server-Sent Events emitted by `POST /api/queries/stream`. */
+export type QueryStreamEvent = {
+    type: 'meta';
+    results: QuerySource[];
+    explain: Record<string, unknown>;
+    quota: QuotaInfo;
+} | {
+    type: 'delta';
+    text: string;
+} | {
+    type: 'done';
+    citations: string[];
+    answer_degraded: boolean;
+} | {
+    type: 'error';
+    message: string;
+};
+export type DocumentStatus = 'pending' | 'processing' | 'ready' | 'failed';
+export interface FuguDocument {
+    id: string;
+    name: string;
+    file_type: string;
+    file_size: number;
+    status: DocumentStatus;
+    created_at: string;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+export interface DocumentUploadResponse {
+    document_id: string;
+    status: 'pending';
+}
+export interface ListDocumentsOptions {
+    limit?: number;
+    offset?: number;
+    signal?: AbortSignal;
+}
+export type LLMCredentialProvider = 'anthropic' | 'openai' | 'gemini' | 'openrouter';
+export interface CredentialDisplay {
+    provider: LLMCredentialProvider;
+    model: string;
+    keyLastFour: string;
+    lastVerifiedAt: string | null;
+}
+export interface CredentialModel {
+    id: string;
+    label: string;
+    free: boolean;
+}
+export interface SaveCredentialInput {
+    provider: LLMCredentialProvider;
+    model: string;
+    apiKey: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/examples/basic-query.ts

@@ -0,0 +1,52 @@
+import { FuguClient, BYOKRequiredError, QuotaExceededError } from '../src/index';
+
+async function main() {
+  const apiKey = process.env.FUGU_API_KEY;
+  if (!apiKey) {
+    throw new Error('Set FUGU_API_KEY env var to a valid fugu_sk_... key');
+  }
+
+  const client = new FuguClient({
+    apiKey,
+    baseUrl: process.env.FUGU_BASE_URL ?? 'http://localhost:3001/api',
+  });
+
+  // 1. Non-streaming query
+  try {
+    const result = await client.query.execute('what does FUGU combine to answer questions');
+    console.log('Answer:', result.answer);
+    console.log('Strategy used:', result.explain.strategy_final);
+    console.log('Sources:', result.results.length);
+  } catch (err) {
+    if (err instanceof BYOKRequiredError) {
+      console.error('No LLM credential configured for this org. Set one via client.credentials.save().');
+      return;
+    }
+    if (err instanceof QuotaExceededError) {
+      console.error('Monthly query quota exceeded.');
+      return;
+    }
+    throw err;
+  }
+
+  // 2. Streaming query
+  console.log('\nStreaming:');
+  for await (const event of client.query.stream('what does FUGU combine to answer questions')) {
+    if (event.type === 'delta') process.stdout.write(event.text);
+    if (event.type === 'done') console.log('\n[done]', event.citations);
+    if (event.type === 'error') console.error('\n[stream error]', event.message);
+  }
+
+  // 3. Documents
+  const docs = await client.documents.list({ limit: 5 });
+  console.log('\nDocuments:', docs.length);
+
+  // 4. Credentials
+  const credential = await client.credentials.get();
+  console.log('Credential:', credential);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "fugu-sdk",
+  "version": "1.0.2",
+  "description": "TypeScript SDK for the FUGU routed RAG API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogukandemirci-software-engineer/fugu-ragrouting",
+    "directory": "sdk-typescript"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "keywords": ["fugu", "rag", "sdk"],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^22.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,44 @@
+import { HttpClient } from './http';
+import { QueryResource } from './resources/query';
+import { DocumentsResource } from './resources/documents';
+import { CredentialsResource } from './resources/credentials';
+
+export interface FuguClientOptions {
+  /** API key issued from the FUGU dashboard, of the form `fugu_sk_...`. */
+  apiKey: string;
+  /** Base API URL. Defaults to `http://localhost:3001/api` for local dev. */
+  baseUrl?: string;
+  /** Custom `fetch` implementation (useful for testing or non-standard runtimes). */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Entry point for the FUGU SDK.
+ *
+ * ```ts
+ * const client = new FuguClient({ apiKey: 'fugu_sk_...' });
+ * const result = await client.query.execute('what does FUGU combine to answer questions');
+ * for await (const event of client.query.stream('...')) { ... }
+ * await client.documents.upload({ filename: 'doc.pdf', data: buffer });
+ * const credential = await client.credentials.get();
+ * ```
+ */
+export class FuguClient {
+  readonly query: QueryResource;
+  readonly documents: DocumentsResource;
+  readonly credentials: CredentialsResource;
+
+  constructor(options: FuguClientOptions) {
+    if (!options.apiKey) throw new Error('FuguClient requires an apiKey');
+
+    const http = new HttpClient({
+      apiKey: options.apiKey,
+      baseUrl: (options.baseUrl ?? 'http://localhost:3001/api').replace(/\/+$/, ''),
+      fetchImpl: options.fetchImpl ?? fetch,
+    });
+
+    this.query = new QueryResource(http);
+    this.documents = new DocumentsResource(http);
+    this.credentials = new CredentialsResource(http);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,51 @@
+export interface ApiErrorBody {
+  error?: {
+    message?: string;
+    code?: string;
+  };
+}
+
+/** Base error for any non-2xx response from the FUGU API. */
+export class FuguApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly code?: string
+  ) {
+    super(message);
+    this.name = 'FuguApiError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when a query is rejected because the organization has no active
+ * LLM credential configured (BYOK). Distinct subclass so callers can branch
+ * on `instanceof BYOKRequiredError` instead of string-matching `code`.
+ */
+export class BYOKRequiredError extends FuguApiError {
+  constructor(message: string, status: number) {
+    super(message, status, 'BYOK_REQUIRED');
+    this.name = 'BYOKRequiredError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/** Thrown when the organization's monthly query quota has been exceeded. */
+export class QuotaExceededError extends FuguApiError {
+  constructor(message: string, status: number) {
+    super(message, status, 'QUOTA_EXCEEDED');
+    this.name = 'QuotaExceededError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/** Builds the right error subclass from a parsed error-response body. */
+export function errorFromResponse(status: number, body: ApiErrorBody | null): FuguApiError {
+  const message = body?.error?.message ?? `Request failed with status ${status}`;
+  const code = body?.error?.code;
+
+  if (code === 'BYOK_REQUIRED') return new BYOKRequiredError(message, status);
+  if (code === 'QUOTA_EXCEEDED') return new QuotaExceededError(message, status);
+  return new FuguApiError(message, status, code);
+}

package/src/http.ts

@@ -0,0 +1,107 @@
+import { errorFromResponse, type ApiErrorBody } from './errors';
+
+export interface HttpClientOptions {
+  apiKey: string;
+  baseUrl: string;
+  fetchImpl: typeof fetch;
+}
+
+/**
+ * Thin wrapper around `fetch` shared by all resource sub-clients. Handles
+ * auth header injection, base URL joining, JSON (de)serialization, and
+ * translating non-2xx responses into typed `FuguApiError`s.
+ */
+export class HttpClient {
+  constructor(private readonly opts: HttpClientOptions) {}
+
+  private url(path: string): string {
+    return `${this.opts.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+  }
+
+  private authHeaders(extra?: Record<string, string>): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.opts.apiKey}`,
+      ...extra,
+    };
+  }
+
+  async requestJson<T>(
+    path: string,
+    init: { method: string; body?: unknown; query?: Record<string, string | number | undefined>; signal?: AbortSignal }
+  ): Promise<T> {
+    let finalUrl = this.url(path);
+    if (init.query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(init.query)) {
+        if (v !== undefined) params.set(k, String(v));
+      }
+      const qs = params.toString();
+      if (qs) finalUrl += `?${qs}`;
+    }
+
+    const res = await this.opts.fetchImpl(finalUrl, {
+      method: init.method,
+      headers: this.authHeaders(init.body !== undefined ? { 'Content-Type': 'application/json' } : undefined),
+      body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+      signal: init.signal,
+    });
+
+    if (res.status === 204) {
+      return undefined as T;
+    }
+
+    const body = await res.json().catch(() => null);
+
+    if (!res.ok) {
+      throw errorFromResponse(res.status, body as ApiErrorBody | null);
+    }
+
+    return body as T;
+  }
+
+  async requestForm<T>(
+    path: string,
+    init: { method: string; form: FormData; signal?: AbortSignal }
+  ): Promise<T> {
+    const res = await this.opts.fetchImpl(this.url(path), {
+      method: init.method,
+      headers: this.authHeaders(),
+      body: init.form,
+      signal: init.signal,
+    });
+
+    const body = await res.json().catch(() => null);
+
+    if (!res.ok) {
+      throw errorFromResponse(res.status, body as ApiErrorBody | null);
+    }
+
+    return body as T;
+  }
+
+  async requestVoid(path: string, init: { method: string; signal?: AbortSignal }): Promise<void> {
+    const res = await this.opts.fetchImpl(this.url(path), {
+      method: init.method,
+      headers: this.authHeaders(),
+      signal: init.signal,
+    });
+
+    if (res.status === 204 || res.ok) return;
+
+    const body = await res.json().catch(() => null);
+    throw errorFromResponse(res.status, body as ApiErrorBody | null);
+  }
+
+  /** Raw streaming request used by the SSE query stream. Returns the fetch Response. */
+  async requestStream(
+    path: string,
+    init: { method: string; body?: unknown; signal?: AbortSignal }
+  ): Promise<Response> {
+    return this.opts.fetchImpl(this.url(path), {
+      method: init.method,
+      headers: this.authHeaders(init.body !== undefined ? { 'Content-Type': 'application/json' } : undefined),
+      body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+      signal: init.signal,
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { FuguClient, type FuguClientOptions } from './client';
+export { QueryResource } from './resources/query';
+export { DocumentsResource, type UploadFileInput } from './resources/documents';
+export { CredentialsResource } from './resources/credentials';
+export { FuguApiError, BYOKRequiredError, QuotaExceededError } from './errors';
+export * from './types';

package/src/resources/credentials.ts

@@ -0,0 +1,39 @@
+import { HttpClient } from '../http';
+import type { CredentialDisplay, CredentialModel, LLMCredentialProvider, SaveCredentialInput } from '../types';
+
+export class CredentialsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Returns the organization's configured BYOK credential, or `null` if none is set. */
+  async get(signal?: AbortSignal): Promise<CredentialDisplay | null> {
+    const res = await this.http.requestJson<{ credential: CredentialDisplay | null }>('/organization/llm-credential', {
+      method: 'GET',
+      signal,
+    });
+    return res.credential;
+  }
+
+  /** Lists available models for a provider, including free-tier availability. */
+  async listModels(provider: LLMCredentialProvider, signal?: AbortSignal): Promise<CredentialModel[]> {
+    const res = await this.http.requestJson<{ models: CredentialModel[] }>('/organization/llm-credential/models', {
+      method: 'GET',
+      query: { provider },
+      signal,
+    });
+    return res.models;
+  }
+
+  /** Saves (creates or replaces) the organization's BYOK credential. Validates the key with a real test call server-side. */
+  async save(input: SaveCredentialInput, signal?: AbortSignal): Promise<CredentialDisplay> {
+    const res = await this.http.requestJson<{ credential: CredentialDisplay }>('/organization/llm-credential', {
+      method: 'PUT',
+      body: input,
+      signal,
+    });
+    return res.credential;
+  }
+
+  async remove(signal?: AbortSignal): Promise<void> {
+    await this.http.requestVoid('/organization/llm-credential', { method: 'DELETE', signal });
+  }
+}

package/src/resources/documents.ts

@@ -0,0 +1,58 @@
+import { HttpClient } from '../http';
+import type { DocumentUploadResponse, FuguDocument, ListDocumentsOptions } from '../types';
+
+export interface UploadFileInput {
+  /** File name including extension, used for type detection server-side. */
+  filename: string;
+  /** File contents. Accepts a Blob/File (browser) or a Buffer/Uint8Array (Node). */
+  data: Blob | Buffer | Uint8Array;
+  /** Optional MIME type; inferred by the platform's Blob implementation if omitted. */
+  contentType?: string;
+}
+
+export class DocumentsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(options: ListDocumentsOptions = {}): Promise<FuguDocument[]> {
+    const res = await this.http.requestJson<{ documents: FuguDocument[] }>('/documents', {
+      method: 'GET',
+      query: { limit: options.limit, offset: options.offset },
+      signal: options.signal,
+    });
+    return res.documents;
+  }
+
+  async get(id: string, signal?: AbortSignal): Promise<FuguDocument> {
+    const res = await this.http.requestJson<{ document: FuguDocument }>(`/documents/${encodeURIComponent(id)}`, {
+      method: 'GET',
+      signal,
+    });
+    return res.document;
+  }
+
+  /** Uploads a document (multipart/form-data, field name `file`). 50MB limit. */
+  async upload(file: UploadFileInput, signal?: AbortSignal): Promise<DocumentUploadResponse> {
+    const form = new FormData();
+    const blob =
+      file.data instanceof Blob ? file.data : new Blob([new Uint8Array(file.data)], { type: file.contentType });
+    form.append('file', blob, file.filename);
+
+    return this.http.requestForm<DocumentUploadResponse>('/documents', {
+      method: 'POST',
+      form,
+      signal,
+    });
+  }
+
+  async delete(id: string, signal?: AbortSignal): Promise<void> {
+    await this.http.requestVoid(`/documents/${encodeURIComponent(id)}`, { method: 'DELETE', signal });
+  }
+
+  /** Re-queues a failed or pending document for ingestion. */
+  async retry(id: string, signal?: AbortSignal): Promise<{ status: 'pending' }> {
+    return this.http.requestJson<{ status: 'pending' }>(`/documents/${encodeURIComponent(id)}/retry`, {
+      method: 'POST',
+      signal,
+    });
+  }
+}

package/src/resources/query.ts

@@ -0,0 +1,63 @@
+import { HttpClient } from '../http';
+import { errorFromResponse, type ApiErrorBody } from '../errors';
+import type { QueryOptions, QueryResponse, QueryStreamEvent } from '../types';
+
+export class QueryResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Runs a query and waits for the full (non-streaming) answer. */
+  async execute(query: string, options: QueryOptions = {}): Promise<QueryResponse> {
+    return this.http.requestJson<QueryResponse>('/queries/v1/query', {
+      method: 'POST',
+      body: { query, strategy: options.strategy, top_k: options.top_k },
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Runs a query and streams the answer token-by-token via Server-Sent
+   * Events. Yields `QueryStreamEvent`s as they arrive:
+   *
+   * ```ts
+   * for await (const event of client.query.stream('...')) {
+   *   if (event.type === 'delta') process.stdout.write(event.text);
+   * }
+   * ```
+   */
+  async *stream(query: string, options: QueryOptions = {}): AsyncGenerator<QueryStreamEvent, void, void> {
+    const res = await this.http.requestStream('/queries/stream', {
+      method: 'POST',
+      body: { query, strategy: options.strategy, top_k: options.top_k },
+      signal: options.signal,
+    });
+
+    if (!res.ok || !res.body) {
+      const body = await res.json().catch(() => null);
+      throw errorFromResponse(res.status, body as ApiErrorBody | null);
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+
+        let sep: number;
+        while ((sep = buffer.indexOf('\n\n')) !== -1) {
+          const frame = buffer.slice(0, sep);
+          buffer = buffer.slice(sep + 2);
+          const line = frame.split('\n').find((l) => l.startsWith('data:'));
+          if (!line) continue;
+          const event = JSON.parse(line.slice(5).trim()) as QueryStreamEvent;
+          yield event;
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+export type QueryStrategy = 'vector_only' | 'graph_only' | 'hybrid' | 'auto';
+
+export interface QuerySource {
+  content: string;
+  source: 'vector' | 'graph';
+  score: number;
+  document_id?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface QuotaInfo {
+  used: number;
+  limit: number;
+  percent: number;
+  warn: boolean;
+}
+
+export interface QueryResponse {
+  answer: string;
+  citations: string[];
+  answer_degraded: boolean;
+  results: QuerySource[];
+  explain: Record<string, unknown>;
+  quota: QuotaInfo;
+}
+
+export interface QueryOptions {
+  strategy?: QueryStrategy;
+  top_k?: number;
+  signal?: AbortSignal;
+}
+
+/** Server-Sent Events emitted by `POST /api/queries/stream`. */
+export type QueryStreamEvent =
+  | { type: 'meta'; results: QuerySource[]; explain: Record<string, unknown>; quota: QuotaInfo }
+  | { type: 'delta'; text: string }
+  | { type: 'done'; citations: string[]; answer_degraded: boolean }
+  | { type: 'error'; message: string };
+
+export type DocumentStatus = 'pending' | 'processing' | 'ready' | 'failed';
+
+export interface FuguDocument {
+  id: string;
+  name: string;
+  file_type: string;
+  file_size: number;
+  status: DocumentStatus;
+  created_at: string;
+  updated_at?: string;
+  [key: string]: unknown;
+}
+
+export interface DocumentUploadResponse {
+  document_id: string;
+  status: 'pending';
+}
+
+export interface ListDocumentsOptions {
+  limit?: number;
+  offset?: number;
+  signal?: AbortSignal;
+}
+
+export type LLMCredentialProvider = 'anthropic' | 'openai' | 'gemini' | 'openrouter';
+
+export interface CredentialDisplay {
+  provider: LLMCredentialProvider;
+  model: string;
+  keyLastFour: string;
+  lastVerifiedAt: string | null;
+}
+
+export interface CredentialModel {
+  id: string;
+  label: string;
+  free: boolean;
+}
+
+export interface SaveCredentialInput {
+  provider: LLMCredentialProvider;
+  model: string;
+  apiKey: string;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM"],
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}