@bigiforg/bigif 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @bigiforg/bigif
 
-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.
+```sh
+npm install @bigiforg/bigif
+```
+
+The official TypeScript and JavaScript SDK for the [Big If True API](https://bigif.org/developers/): Big, Disco and
+Ticker with streaming, function calling, images and typed errors. No dependencies; Node 18+, Deno, Bun and browsers.
+
+```ts
+import { BigIfTrue } from "@bigiforg/bigif";
+
+const client = new BigIfTrue({ apiKey: process.env.BIGIF_API_KEY });
+console.log(await client.ask("Hello!", { model: "big" }));
+```
+
+Full guide: https://bigif.org/developers/sdks/#typescript

package/dist/index.d.ts

@@ -0,0 +1,266 @@
+export declare const VERSION = "1.0.0";
+export declare const DEFAULT_BASE_URL = "https://bigif.org/api/openai/v1";
+export type Model = "big" | "big-think" | "disco" | "disco-think" | "ticker" | "ticker-think" | (string & {});
+export type Role = "system" | "developer" | "user" | "assistant" | "tool";
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+};
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ChatMessage {
+    role: Role;
+    content: string | ContentPart[] | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+export interface Tool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+        strict?: boolean;
+    };
+}
+export interface GenerationParams {
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    min_p?: number;
+    top_a?: number;
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    repetition_penalty?: number;
+    seed?: number;
+    logit_bias?: Record<string, number>;
+    max_tokens?: number;
+    max_completion_tokens?: number;
+    stop?: string | string[];
+    reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    logprobs?: boolean;
+    top_logprobs?: number;
+    user?: string;
+    stream_options?: {
+        include_usage?: boolean;
+    };
+}
+export interface ChatCompletionParams extends GenerationParams {
+    model: Model;
+    messages: ChatMessage[];
+    tools?: Tool[];
+    tool_choice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    parallel_tool_calls?: boolean;
+    response_format?: {
+        type: "text" | "json_object" | "json_schema";
+        json_schema?: Record<string, unknown>;
+    };
+    stream?: boolean;
+}
+export interface CompletionParams extends GenerationParams {
+    model: Model;
+    prompt: string;
+    stream?: boolean;
+}
+export interface BillingInfo {
+    credits?: number;
+    credits_final?: boolean;
+    request_id?: string;
+    log_id?: string;
+}
+export interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    bigif?: BillingInfo;
+}
+export interface ChatCompletion {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: {
+        index: number;
+        finish_reason: string;
+        logprobs: unknown;
+        message: {
+            role: "assistant";
+            content: string | null;
+            reasoning_content?: string;
+            tool_calls?: ToolCall[];
+        };
+    }[];
+    usage: Usage;
+    bigif?: BillingInfo;
+}
+export interface ChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    usage?: Usage;
+    choices: {
+        index: number;
+        finish_reason: string | null;
+        logprobs?: unknown;
+        delta: {
+            role?: string;
+            content?: string;
+            reasoning_content?: string;
+            tool_calls?: {
+                index: number;
+                id?: string;
+                type?: "function";
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }[];
+        };
+    }[];
+}
+export interface TextCompletion {
+    id: string;
+    object: "text_completion";
+    created: number;
+    model: string;
+    choices: {
+        text: string;
+        index: number;
+        finish_reason: string | null;
+    }[];
+    usage?: Usage;
+    bigif?: BillingInfo;
+}
+export interface ModelInfo {
+    id: string;
+    object: "model";
+    created: number;
+    owned_by: string;
+    name?: string;
+    description?: string;
+}
+export interface ImageParams {
+    prompt: string;
+    model?: Model;
+    size?: string;
+    quality?: "standard" | "hd" | "high" | "max";
+    n?: 1;
+}
+export interface ImageResponse {
+    created: number;
+    data: {
+        b64_json?: string;
+        url?: string;
+        revised_prompt?: string;
+    }[];
+}
+export interface ClientOptions {
+    apiKey?: string;
+    baseURL?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    appName?: string;
+    fetch?: typeof fetch;
+}
+/** An error from the API, in OpenAI's shape (status 0 for a network failure). */
+export declare class BigIfTrueError extends Error {
+    status: number;
+    type: string;
+    code: string | null;
+    param: string | null;
+    requestId: string;
+    body: unknown;
+    constructor(message: string, init?: {
+        status?: number;
+        type?: string;
+        code?: string | null;
+        param?: string | null;
+        requestId?: string;
+        body?: unknown;
+    });
+}
+/** A streamed completion: `for await (const chunk of stream)`. `text` and `usage` fill in as it goes. */
+export declare class Stream<T> implements AsyncIterable<T> {
+    private response;
+    readonly controller: AbortController;
+    private onDone;
+    text: string;
+    usage: Usage | undefined;
+    readonly requestId: string;
+    constructor(response: Response, controller: AbortController, onDone?: () => void);
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /** Read to the end and return the whole text. */
+    finalText(): Promise<string>;
+    abort(): void;
+}
+export declare class BigIfTrue {
+    readonly apiKey: string;
+    readonly baseURL: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly appName?: string;
+    private fetcher;
+    constructor(options?: ClientOptions);
+    /** Low-level request: JSON in, JSON (or a Stream) out, with retries for busy or failing servers. */
+    request<T>(method: string, path: string, body?: unknown, stream?: boolean): Promise<T>;
+    readonly models: {
+        list: () => Promise<{
+            object: "list";
+            data: ModelInfo[];
+        }>;
+        retrieve: (model: Model) => Promise<ModelInfo>;
+    };
+    readonly chat: {
+        completions: {
+            create: {
+                (params: ChatCompletionParams & {
+                    stream: true;
+                }): Promise<Stream<ChatCompletionChunk>>;
+                (params: ChatCompletionParams & {
+                    stream?: false;
+                }): Promise<ChatCompletion>;
+                (params: ChatCompletionParams): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
+            };
+        };
+    };
+    readonly completions: {
+        create: {
+            (params: CompletionParams & {
+                stream: true;
+            }): Promise<Stream<TextCompletion>>;
+            (params: CompletionParams & {
+                stream?: false;
+            }): Promise<TextCompletion>;
+        };
+    };
+    readonly images: {
+        generate: (params: ImageParams) => Promise<ImageResponse>;
+    };
+    /** One question, one answer: the reply's text. */
+    ask(prompt: string, options?: Omit<ChatCompletionParams, "messages" | "model" | "stream"> & {
+        model?: Model;
+        system?: string;
+    }): Promise<string>;
+    /** The API's OpenAPI description. */
+    openapi(): Promise<Record<string, unknown>>;
+}
+export default BigIfTrue;

package/dist/index.js

@@ -0,0 +1,151 @@
+// The official TypeScript SDK for the Big If True API: Big, Disco and Ticker
+// through the OpenAI-compatible endpoints at https://bigif.org/api/openai/v1.
+export const VERSION = "1.0.0";
+export const DEFAULT_BASE_URL = "https://bigif.org/api/openai/v1";
+/** An error from the API, in OpenAI's shape (status 0 for a network failure). */
+export class BigIfTrueError extends Error {
+    constructor(message, init = {}) {
+        super(message);
+        this.name = "BigIfTrueError";
+        this.status = init.status ?? 0;
+        this.type = init.type ?? "";
+        this.code = init.code ?? null;
+        this.param = init.param ?? null;
+        this.requestId = init.requestId ?? "";
+        this.body = init.body;
+    }
+}
+/** A streamed completion: `for await (const chunk of stream)`. `text` and `usage` fill in as it goes. */
+export class Stream {
+    constructor(response, controller, onDone = () => { }) {
+        this.response = response;
+        this.controller = controller;
+        this.onDone = onDone;
+        this.text = "";
+        this.requestId = response.headers.get("x-request-id") ?? "";
+    }
+    async *[Symbol.asyncIterator]() {
+        const reader = this.response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    return;
+                buffer += decoder.decode(value, { stream: true });
+                let index;
+                while ((index = buffer.indexOf("\n\n")) >= 0) {
+                    const frame = buffer.slice(0, index);
+                    buffer = buffer.slice(index + 2);
+                    const data = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).join("");
+                    if (!data)
+                        continue;
+                    if (data === "[DONE]")
+                        return;
+                    const chunk = JSON.parse(data);
+                    if (chunk.error)
+                        throw new BigIfTrueError(chunk.error.message, { status: 200, type: chunk.error.type, code: chunk.error.code, body: chunk });
+                    if (chunk.usage)
+                        this.usage = chunk.usage;
+                    const choice = chunk.choices?.[0];
+                    this.text += choice?.delta?.content ?? choice?.text ?? "";
+                    yield chunk;
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+            this.onDone();
+        }
+    }
+    /** Read to the end and return the whole text. */
+    async finalText() { for await (const _ of this) { /* drain */ } return this.text; }
+    abort() { this.controller.abort(); }
+}
+const RETRY = new Set([408, 409, 429, 500, 502, 503, 504]);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class BigIfTrue {
+    constructor(options = {}) {
+        this.models = {
+            list: () => this.request("GET", "/models"),
+            retrieve: (model) => this.request("GET", `/models/${model}`),
+        };
+        this.chat = {
+            completions: {
+                create: ((params) => {
+                    const body = params.stream ? { stream_options: { include_usage: true }, ...params } : params;
+                    return this.request("POST", "/chat/completions", body, Boolean(params.stream));
+                }),
+            },
+        };
+        this.completions = {
+            create: ((params) => {
+                const body = params.stream ? { stream_options: { include_usage: true }, ...params } : params;
+                return this.request("POST", "/completions", body, Boolean(params.stream));
+            }),
+        };
+        this.images = {
+            generate: (params) => this.request("POST", "/images/generations", params),
+        };
+        // process.env where it exists (Node, Bun, Deno with compat); browsers pass apiKey.
+        const env = globalThis.process?.env ?? {};
+        this.apiKey = options.apiKey ?? env.BIGIF_API_KEY ?? "";
+        if (!this.apiKey)
+            throw new BigIfTrueError("No API key. Pass apiKey or set BIGIF_API_KEY. Create one at https://bigif.org/workspace/?view=api.");
+        this.baseURL = (options.baseURL ?? env.BIGIF_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? 600000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.appName = options.appName;
+        this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** Low-level request: JSON in, JSON (or a Stream) out, with retries for busy or failing servers. */
+    async request(method, path, body, stream = false) {
+        const headers = { Authorization: `Bearer ${this.apiKey}`, Accept: stream ? "text/event-stream" : "application/json" };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (this.appName)
+            headers["X-Title"] = this.appName;
+        for (let attempt = 0;; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            timer?.unref?.();
+            let response;
+            try {
+                response = await this.fetcher(`${this.baseURL}${path}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: controller.signal });
+            }
+            catch (error) {
+                clearTimeout(timer);
+                if (attempt < this.maxRetries) {
+                    await sleep(500 * 2 ** attempt);
+                    continue;
+                }
+                throw new BigIfTrueError(`Could not reach the Big If True API: ${error.message}`);
+            }
+            if (!stream)
+                clearTimeout(timer);
+            if (response.ok)
+                return (stream ? new Stream(response, controller, () => clearTimeout(timer)) : await response.json());
+            clearTimeout(timer);
+            const data = await response.json().catch(() => ({ error: { message: `HTTP ${response.status}` } }));
+            const error = data?.error ?? {};
+            if (RETRY.has(response.status) && attempt < this.maxRetries && error.type !== "insufficient_quota") {
+                const after = Number(response.headers.get("retry-after"));
+                await sleep(Number.isFinite(after) && after > 0 ? Math.min(after, 30) * 1000 : 500 * 2 ** attempt);
+                continue;
+            }
+            throw new BigIfTrueError(error.message ?? `HTTP ${response.status}`, { status: response.status, type: error.type, code: error.code, param: error.param,
+                requestId: response.headers.get("x-request-id") ?? "", body: data });
+        }
+    }
+    /** One question, one answer: the reply's text. */
+    async ask(prompt, options = {}) {
+        const { model = "big", system, ...params } = options;
+        const messages = [...(system ? [{ role: "system", content: system }] : []), { role: "user", content: prompt }];
+        const reply = await this.chat.completions.create({ ...params, model, messages, stream: false });
+        return reply.choices[0]?.message.content ?? "";
+    }
+    /** The API's OpenAPI description. */
+    openapi() { return this.request("GET", "/openapi.json"); }
+}
+export default BigIfTrue;

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@bigiforg/bigif",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "The official TypeScript and JavaScript SDK for the Big If True API (Big, Disco and Ticker, OpenAI-compatible).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "homepage": "https://bigif.org/developers/sdks/#typescript",
+  "scripts": { "build": "tsc", "test": "node --test test/client.test.js" },
+  "devDependencies": { "typescript": "5.6.3" }
+}