@seanhogg/builderforce-sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,21 +1,131 @@
-declare const AI_USE_CASES: readonly ["ide.chat", "ide.code_complete", "training.dataset_generate", "training.dataset_evaluate", "agent.inference", "coder.code", "coder.review", "coder.test", "coder.debug", "coder.refactor", "coder.document", "coder.architect", "coach.chat", "coach.insight", "coach.classify", "studio.compose", "studio.script", "studio.brief", "pitch_deck.generate", "investor.update", "ask.general", "tool.classify_email", "tool.categorize_expense", "tool.contract_analyze", "tool.competitor_scan", "tool.feature_score", "tool.market_research", "tool.health_score", "tool.journey_insight", "vision.describe", "ocr.extract", "embed.text", "match", "match_tailor", "match_insights", "resume_roast", "skill_extract", "job_parser", "autofill", "article_writer", "studio_script", "studio_edit_script", "studio_misc", "linkedin_post", "interview_questions", "interview_analyze", "chat", "career", "discovery", "dashboard_summary"];
-type AIUseCase = (typeof AI_USE_CASES)[number];
-declare function isAIUseCase(value: string): value is AIUseCase;
-
 type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
+interface TextContentPart {
+    type: 'text';
+    text: string;
+}
+interface ImageUrlContentPart {
+    type: 'image_url';
+    image_url: {
+        /** Either an `https://...` URL or a `data:image/...;base64,...` data URI. */
+        url: string;
+        /** Image detail hint — `'low' | 'high' | 'auto'`. Vendor-specific behaviour. */
+        detail?: 'low' | 'high' | 'auto';
+    };
+}
+type ContentPart = TextContentPart | ImageUrlContentPart;
+interface FunctionDefinition {
+    name: string;
+    description?: string;
+    /** JSON-Schema describing the function's argument shape. */
+    parameters?: Record<string, unknown>;
+}
+interface ToolSpec {
+    type: 'function';
+    function: FunctionDefinition;
+}
+interface ToolCallFunction {
+    name: string;
+    /** JSON-encoded argument string. Caller is responsible for `JSON.parse`. */
+    arguments: string;
+}
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: ToolCallFunction;
+}
+type ToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+/** Streaming-mode tool-call delta. Each chunk carries an `index` so callers
+ *  can stitch fragments together by call slot. */
+interface ToolCallDelta {
+    index: number;
+    id?: string;
+    type?: 'function';
+    function?: {
+        name?: string;
+        /** Partial JSON-encoded arguments — concatenate across deltas to reassemble. */
+        arguments?: string;
+    };
+}
+interface JsonSchemaSpec {
+    name: string;
+    description?: string;
+    /** JSON-Schema document. Use `strict: true` for vendor-side conformance retry. */
+    schema: Record<string, unknown>;
+    strict?: boolean;
+}
+type ResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    json_schema: JsonSchemaSpec;
+};
 interface ChatMessage {
     role: ChatRole;
-    content: string;
+    /** String for plain text. `ContentPart[]` for vision (text + image_url). `null`
+     *  is allowed on assistant turns that only carry `tool_calls`. */
+    content: string | ContentPart[] | null;
     name?: string;
+    /** Assistant-turn tool calls. Caller executes each and replies with a `tool` message
+     *  whose `tool_call_id` matches `tool_calls[i].id`. */
+    tool_calls?: ToolCall[];
+    /** Required on `role: 'tool'` messages — the id of the assistant tool call this
+     *  message is responding to. */
+    tool_call_id?: string;
+}
+interface PerCallOptions {
+    /** Override the client-level timeout for just this call. Useful when use
+     *  cases have a wide latency spread (autofill ~2s vs `career_360` ~30s). */
+    timeoutMs?: number;
+    /** Caller-supplied AbortSignal for user-cancellable generation. Fires alongside
+     *  the SDK's internal timeout signal — whichever fires first wins. */
+    signal?: AbortSignal;
+    /** Sent as `Idempotency-Key` header — gateway dedupes retries within its TTL. */
+    idempotencyKey?: string;
 }
-interface ChatCompletionCreateParams {
+interface ChatCompletionCreateParams extends PerCallOptions {
+    /**
+     * Model **hint** (not a hard pin). When set, the gateway puts this id at the
+     * head of its candidate chain so it's tried first — but the gateway retains
+     * the right to substitute on cooldown, vendor outage, or plan-tier mismatch.
+     * The actual model used is reported via `_builderforce.resolvedModel`; check
+     * it if you need to detect substitution.
+     *
+     * Vendor prefixes (`openrouter/<id>`, `cerebras/<id>`, `ollama/<id>`) route
+     * to the named vendor when that model is selected. Bare ids fall back to
+     * catalog lookup.
+     *
+     * When unset, the gateway picks from the tenant-plan model pool with
+     * shape-based reordering (tools / response_format / vision content blocks).
+     */
     model?: string;
     messages: ChatMessage[];
     stream?: boolean;
-    useCase?: AIUseCase;
     temperature?: number;
     max_tokens?: number;
     top_p?: number;
+    /** Tool / function-calling spec. */
+    tools?: ToolSpec[];
+    tool_choice?: ToolChoice;
+    /** Structured-output mode. `'json_object'` is loose JSON; `'json_schema'` requests
+     *  gateway-side schema validation with retry across the failover chain. */
+    response_format?: ResponseFormat;
+    /**
+     * Opaque telemetry slug. The gateway treats this as a free-form string —
+     * persisted to `llm_usage_log.use_case` and echoed back in `_builderforce.useCase`
+     * for confirmation, but **never used for routing**. The taxonomy is yours.
+     */
+    useCase?: string;
+    /** Free-form key/value pairs persisted to `llm_usage_log.metadata` for billing
+     *  trace-back ({ toolRunId, sessionId, userId, featureKey, … }). Echoed back
+     *  in `_builderforce.metadata`. Not forwarded to vendors. */
+    metadata?: Record<string, string>;
     [key: string]: unknown;
 }
 interface ChatCompletionChunk {
@@ -27,7 +137,8 @@ interface ChatCompletionChunk {
         index?: number;
         delta?: {
             role?: ChatRole;
-            content?: string;
+            content?: string | null;
+            tool_calls?: ToolCallDelta[];
         };
         finish_reason?: string | null;
     }>;
@@ -46,8 +157,10 @@ interface ChatCompletionResponse {
         index?: number;
         message?: {
             role?: ChatRole;
-            content?: string;
+            content?: string | null;
+            tool_calls?: ToolCall[];
         };
+        /** `'stop' | 'length' | 'tool_calls' | 'content_filter' | …` */
         finish_reason?: string | null;
     }>;
     usage?: {
@@ -56,11 +169,21 @@ interface ChatCompletionResponse {
         total_tokens?: number;
     };
     _builderforce?: {
+        /** The model the gateway dispatched against. Equals `request.model` when caller pinned. */
         resolvedModel?: string;
+        /** How many vendor retries happened inside the failover chain. */
         retries?: number;
         pool?: number;
         product?: string;
         effectivePlan?: string;
+        /** Number of vendor retries the gateway performed for json_schema conformance. */
+        schemaRetries?: number;
+        /** Echo of `request.useCase` (opaque telemetry slug). */
+        useCase?: string;
+        /** Echo of `request.metadata` for caller-side billing trace-back. */
+        metadata?: Record<string, string>;
+        /** Mirror of the `x-request-id` response header. */
+        requestId?: string;
     };
     [key: string]: unknown;
 }
@@ -124,6 +247,36 @@ interface UsageResponse {
 interface UsageGetParams {
     days?: number;
 }
+interface EmbeddingsCreateParams extends PerCallOptions {
+    model?: string;
+    /** Single string or array of strings to embed. */
+    input: string | string[];
+    /** Opaque telemetry slug — same semantics as chat. */
+    useCase?: string;
+    /** Free-form attribution metadata (same semantics as chat). */
+    metadata?: Record<string, string>;
+    [key: string]: unknown;
+}
+interface EmbeddingObject {
+    object: 'embedding';
+    index: number;
+    embedding: number[];
+}
+interface EmbeddingsResponse {
+    object: 'list';
+    data: EmbeddingObject[];
+    model: string;
+    usage?: {
+        prompt_tokens?: number;
+        total_tokens?: number;
+    };
+    _builderforce?: {
+        resolvedModel?: string;
+        retries?: number;
+        product?: string;
+    };
+    [key: string]: unknown;
+}
 
 declare class BuilderforceApiError extends Error {
     readonly status: number;
@@ -136,18 +289,34 @@ interface HttpClientOptions {
     apiKey: string;
     baseUrl: string;
     fetchFn?: typeof fetch;
+    /** Default per-request timeout in ms. Overridable per call. */
+    timeoutMs?: number;
+}
+/** Per-request overrides — passed by the API layer, not by SDK consumers directly. */
+interface RequestOptions {
+    /** Override the client default timeout for just this request. */
     timeoutMs?: number;
+    /** Caller-provided AbortSignal. Linked together with the SDK's internal timeout
+     *  signal — whichever fires first aborts the request. */
+    signal?: AbortSignal;
+    /** Extra headers to merge in (e.g. `Idempotency-Key`). */
+    headers?: Record<string, string>;
 }
 declare class HttpClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly fetchFn;
-    private readonly timeoutMs;
+    private readonly defaultTimeoutMs;
     constructor(options: HttpClientOptions);
-    getJson<T>(path: string): Promise<T>;
-    postJson<T>(path: string, body: unknown): Promise<T>;
-    postRaw(path: string, body: unknown): Promise<Response>;
-    private authHeaders;
+    getJson<T>(path: string, options?: RequestOptions): Promise<T>;
+    postJson<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    postRaw(path: string, body: unknown, options?: RequestOptions): Promise<Response>;
+    private mergeHeaders;
+    /**
+     * Wrap a fetch in a combined abort signal: an internal timeout AND any
+     * caller-provided signal. Either firing aborts the request. Single source of
+     * abort plumbing — every method routes through here (DRY).
+     */
     private fetchWithTimeout;
     private parseJsonResponse;
     private toApiError;
@@ -170,6 +339,19 @@ declare class ChatCompletionsApi {
     }): Promise<ChatCompletionResponse>;
 }
 
+declare class EmbeddingsApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create one or more text embeddings.
+     *
+     * NOTE: As of v0.3.0 the gateway accepts the request shape but the underlying
+     * vendor wiring is still being rolled out — calls may currently 503 with
+     * `code: 'embeddings_not_wired'`. Track gateway PRD §6.7.
+     */
+    create(params: EmbeddingsCreateParams): Promise<EmbeddingsResponse>;
+}
+
 declare class ModelsApi {
     private readonly http;
     constructor(http: HttpClient);
@@ -186,15 +368,18 @@ interface BuilderforceClientOptions {
     apiKey: string;
     baseUrl?: string;
     fetch?: typeof fetch;
+    /** Default request timeout in ms (default 60_000). Per-call override available
+     *  via `chat.completions.create({ timeoutMs })` and `embeddings.create({ timeoutMs })`. */
     timeoutMs?: number;
 }
 declare class BuilderforceClient {
     readonly chat: {
         completions: ChatCompletionsApi;
     };
+    readonly embeddings: EmbeddingsApi;
     readonly models: ModelsApi;
     readonly usage: UsageApi;
     constructor(options: BuilderforceClientOptions);
 }
 
-export { type AIUseCase, AI_USE_CASES, BuilderforceApiError, BuilderforceClient, type BuilderforceClientOptions, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatCompletionResponse, ChatCompletionStream, type ChatMessage, type ChatRole, type ModelsListResponse, type UsageByDay, type UsageByModel, type UsageByUser, type UsageGetParams, type UsageResponse, isAIUseCase };
+export { BuilderforceApiError, BuilderforceClient, type BuilderforceClientOptions, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatCompletionResponse, ChatCompletionStream, type ChatMessage, type ChatRole, type ContentPart, type EmbeddingObject, EmbeddingsApi, type EmbeddingsCreateParams, type EmbeddingsResponse, type FunctionDefinition, type ImageUrlContentPart, type JsonSchemaSpec, type ModelsListResponse, type PerCallOptions, type ResponseFormat, type TextContentPart, type ToolCall, type ToolCallDelta, type ToolCallFunction, type ToolChoice, type ToolSpec, type UsageByDay, type UsageByModel, type UsageByUser, type UsageGetParams, type UsageResponse };

package/dist/index.mjs

@@ -42,20 +42,66 @@ var ChatCompletionStream = class {
     return full;
   }
 };
+function splitTransportOptions(params) {
+  const { timeoutMs, signal, idempotencyKey, ...rest } = params;
+  const headers = {};
+  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+  return {
+    body: rest,
+    request: {
+      timeoutMs,
+      signal,
+      ...Object.keys(headers).length > 0 ? { headers } : {}
+    }
+  };
+}
 var ChatCompletionsApi = class {
   http;
   constructor(http) {
     this.http = http;
   }
   async create(params) {
+    const { body, request } = splitTransportOptions(params);
     if (params.stream) {
-      const response = await this.http.postRaw("/llm/v1/chat/completions", params);
+      const response = await this.http.postRaw("/llm/v1/chat/completions", body, request);
       if (!response.body) {
         throw new Error("Streaming response body is missing");
       }
       return new ChatCompletionStream(response.body);
     }
-    return this.http.postJson("/llm/v1/chat/completions", params);
+    return this.http.postJson("/llm/v1/chat/completions", body, request);
+  }
+};
+
+// src/application/EmbeddingsApi.ts
+function splitTransportOptions2(params) {
+  const { timeoutMs, signal, idempotencyKey, ...rest } = params;
+  const headers = {};
+  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+  return {
+    body: rest,
+    request: {
+      timeoutMs,
+      signal,
+      ...Object.keys(headers).length > 0 ? { headers } : {}
+    }
+  };
+}
+var EmbeddingsApi = class {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create one or more text embeddings.
+   *
+   * NOTE: As of v0.3.0 the gateway accepts the request shape but the underlying
+   * vendor wiring is still being rolled out — calls may currently 503 with
+   * `code: 'embeddings_not_wired'`. Track gateway PRD §6.7.
+   */
+  create(params) {
+    const { body, request } = splitTransportOptions2(params);
+    return this.http.postJson("/llm/v1/embeddings", body, request);
   }
 };
 
@@ -101,62 +147,68 @@ var HttpClient = class {
   apiKey;
   baseUrl;
   fetchFn;
-  timeoutMs;
+  defaultTimeoutMs;
   constructor(options) {
     this.apiKey = options.apiKey;
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
     this.fetchFn = options.fetchFn ?? fetch;
-    this.timeoutMs = options.timeoutMs ?? 6e4;
+    this.defaultTimeoutMs = options.timeoutMs ?? 6e4;
   }
-  async getJson(path) {
+  async getJson(path, options) {
     const res = await this.fetchWithTimeout(`${this.baseUrl}${path}`, {
       method: "GET",
-      headers: this.authHeaders()
-    });
+      headers: this.mergeHeaders(options)
+    }, options);
     return this.parseJsonResponse(res);
   }
-  async postJson(path, body) {
+  async postJson(path, body, options) {
     const res = await this.fetchWithTimeout(`${this.baseUrl}${path}`, {
       method: "POST",
-      headers: {
-        ...this.authHeaders(),
-        "Content-Type": "application/json"
-      },
+      headers: this.mergeHeaders(options, { "Content-Type": "application/json" }),
       body: JSON.stringify(body)
-    });
+    }, options);
     return this.parseJsonResponse(res);
   }
-  async postRaw(path, body) {
+  async postRaw(path, body, options) {
     const res = await this.fetchWithTimeout(`${this.baseUrl}${path}`, {
       method: "POST",
-      headers: {
-        ...this.authHeaders(),
-        "Content-Type": "application/json"
-      },
+      headers: this.mergeHeaders(options, { "Content-Type": "application/json" }),
       body: JSON.stringify(body)
-    });
+    }, options);
     if (!res.ok) {
       throw await this.toApiError(res);
     }
     return res;
   }
-  authHeaders() {
+  mergeHeaders(options, base) {
     return {
-      Authorization: `Bearer ${this.apiKey}`
+      Authorization: `Bearer ${this.apiKey}`,
+      ...base ?? {},
+      ...options?.headers ?? {}
     };
   }
-  async fetchWithTimeout(input, init) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+  /**
+   * Wrap a fetch in a combined abort signal: an internal timeout AND any
+   * caller-provided signal. Either firing aborts the request. Single source of
+   * abort plumbing — every method routes through here (DRY).
+   */
+  async fetchWithTimeout(input, init, options) {
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const timeoutCtl = new AbortController();
+    const timer = setTimeout(() => timeoutCtl.abort(), timeoutMs);
+    const signal = combineSignals(timeoutCtl.signal, options?.signal);
     try {
-      return await this.fetchFn(input, { ...init, signal: controller.signal });
+      return await this.fetchFn(input, { ...init, signal });
     } catch (error) {
-      if (controller.signal.aborted) {
-        throw new BuilderforceApiError(`Request timed out after ${this.timeoutMs}ms`, 408, "timeout");
+      if (timeoutCtl.signal.aborted) {
+        throw new BuilderforceApiError(`Request timed out after ${timeoutMs}ms`, 408, "timeout");
+      }
+      if (options?.signal?.aborted) {
+        throw new BuilderforceApiError("Request aborted by caller", 499, "aborted");
       }
       throw error;
     } finally {
-      clearTimeout(timeout);
+      clearTimeout(timer);
     }
   }
   async parseJsonResponse(res) {
@@ -177,10 +229,28 @@ var HttpClient = class {
     }
   }
 };
+function combineSignals(...signals) {
+  const live = signals.filter((s) => s !== void 0);
+  if (live.length === 1) return live[0];
+  const anyImpl = AbortSignal.any;
+  if (typeof anyImpl === "function") {
+    return anyImpl(live);
+  }
+  const ctl = new AbortController();
+  for (const s of live) {
+    if (s.aborted) {
+      ctl.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => ctl.abort(s.reason), { once: true });
+  }
+  return ctl.signal;
+}
 
 // src/BuilderforceClient.ts
 var BuilderforceClient = class {
   chat;
+  embeddings;
   models;
   usage;
   constructor(options) {
@@ -201,72 +271,15 @@ var BuilderforceClient = class {
     this.chat = {
       completions: new ChatCompletionsApi(http)
     };
+    this.embeddings = new EmbeddingsApi(http);
     this.models = new ModelsApi(http);
     this.usage = new UsageApi(http);
   }
 };
-
-// src/domain/aiUseCases.ts
-var AI_USE_CASES = [
-  "ide.chat",
-  "ide.code_complete",
-  "training.dataset_generate",
-  "training.dataset_evaluate",
-  "agent.inference",
-  "coder.code",
-  "coder.review",
-  "coder.test",
-  "coder.debug",
-  "coder.refactor",
-  "coder.document",
-  "coder.architect",
-  "coach.chat",
-  "coach.insight",
-  "coach.classify",
-  "studio.compose",
-  "studio.script",
-  "studio.brief",
-  "pitch_deck.generate",
-  "investor.update",
-  "ask.general",
-  "tool.classify_email",
-  "tool.categorize_expense",
-  "tool.contract_analyze",
-  "tool.competitor_scan",
-  "tool.feature_score",
-  "tool.market_research",
-  "tool.health_score",
-  "tool.journey_insight",
-  "vision.describe",
-  "ocr.extract",
-  "embed.text",
-  "match",
-  "match_tailor",
-  "match_insights",
-  "resume_roast",
-  "skill_extract",
-  "job_parser",
-  "autofill",
-  "article_writer",
-  "studio_script",
-  "studio_edit_script",
-  "studio_misc",
-  "linkedin_post",
-  "interview_questions",
-  "interview_analyze",
-  "chat",
-  "career",
-  "discovery",
-  "dashboard_summary"
-];
-function isAIUseCase(value) {
-  return AI_USE_CASES.includes(value);
-}
 export {
-  AI_USE_CASES,
   BuilderforceApiError,
   BuilderforceClient,
   ChatCompletionStream,
-  isAIUseCase
+  EmbeddingsApi
 };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/infrastructure/sse.ts","../src/application/ChatCompletionsApi.ts","../src/application/ModelsApi.ts","../src/application/UsageApi.ts","../src/infrastructure/httpClient.ts","../src/BuilderforceClient.ts","../src/domain/aiUseCases.ts"],"sourcesContent":["export async function* parseSseJson<T>(\r\n  stream: ReadableStream<Uint8Array>,\r\n): AsyncGenerator<T, void, unknown> {\r\n  const reader = stream.getReader();\r\n  const decoder = new TextDecoder();\r\n  let buffer = '';\r\n\r\n  while (true) {\r\n    const { done, value } = await reader.read();\r\n    if (done) break;\r\n\r\n    buffer += decoder.decode(value, { stream: true });\r\n    const lines = buffer.split('\\n');\r\n    buffer = lines.pop() ?? '';\r\n\r\n    for (const line of lines) {\r\n      const trimmed = line.trim();\r\n      if (!trimmed.startsWith('data: ')) continue;\r\n\r\n      const data = trimmed.slice(6).trim();\r\n      if (data === '[DONE]') return;\r\n\r\n      try {\r\n        yield JSON.parse(data) as T;\r\n      } catch {\r\n        // Skip malformed chunks instead of breaking the stream.\r\n      }\r\n    }\r\n  }\r\n}\r\n","import type { ChatCompletionChunk, ChatCompletionCreateParams, ChatCompletionResponse } from '../domain/types';\r\nimport { HttpClient } from '../infrastructure/httpClient';\r\nimport { parseSseJson } from '../infrastructure/sse';\r\n\r\nexport class ChatCompletionStream implements AsyncIterable<ChatCompletionChunk> {\r\n  private readonly stream: ReadableStream<Uint8Array>;\r\n\r\n  constructor(stream: ReadableStream<Uint8Array>) {\r\n    this.stream = stream;\r\n  }\r\n\r\n  [Symbol.asyncIterator](): AsyncIterator<ChatCompletionChunk, void, unknown> {\r\n    return parseSseJson<ChatCompletionChunk>(this.stream);\r\n  }\r\n\r\n  async toText(): Promise<string> {\r\n    let full = '';\r\n    for await (const chunk of this) {\r\n      const delta = chunk.choices?.[0]?.delta?.content;\r\n      if (typeof delta === 'string') {\r\n        full += delta;\r\n      }\r\n    }\r\n    return full;\r\n  }\r\n}\r\n\r\nexport class ChatCompletionsApi {\r\n  private readonly http: HttpClient;\r\n\r\n  constructor(http: HttpClient) {\r\n    this.http = http;\r\n  }\r\n\r\n  async create(params: ChatCompletionCreateParams & { stream: true }): Promise<ChatCompletionStream>;\r\n  async create(params: ChatCompletionCreateParams & { stream?: false | undefined }): Promise<ChatCompletionResponse>;\r\n  async create(\r\n    params: ChatCompletionCreateParams,\r\n  ): Promise<ChatCompletionResponse | ChatCompletionStream> {\r\n    if (params.stream) {\r\n      const response = await this.http.postRaw('/llm/v1/chat/completions', params);\r\n      if (!response.body) {\r\n        throw new Error('Streaming response body is missing');\r\n      }\r\n      return new ChatCompletionStream(response.body);\r\n    }\r\n\r\n    return this.http.postJson<ChatCompletionResponse>('/llm/v1/chat/completions', params);\r\n  }\r\n}\r\n","import type { ModelsListResponse } from '../domain/types';\r\nimport { HttpClient } from '../infrastructure/httpClient';\r\n\r\nexport class ModelsApi {\r\n  private readonly http: HttpClient;\r\n\r\n  constructor(http: HttpClient) {\r\n    this.http = http;\r\n  }\r\n\r\n  list(): Promise<ModelsListResponse> {\r\n    return this.http.getJson<ModelsListResponse>('/llm/v1/models');\r\n  }\r\n}\r\n","import type { UsageGetParams, UsageResponse } from '../domain/types';\r\nimport { HttpClient } from '../infrastructure/httpClient';\r\n\r\nexport class UsageApi {\r\n  private readonly http: HttpClient;\r\n\r\n  constructor(http: HttpClient) {\r\n    this.http = http;\r\n  }\r\n\r\n  get(params: UsageGetParams = {}): Promise<UsageResponse> {\r\n    const query = typeof params.days === 'number' ? `?days=${encodeURIComponent(String(params.days))}` : '';\r\n    return this.http.getJson<UsageResponse>(`/llm/v1/usage${query}`);\r\n  }\r\n}\r\n","export class BuilderforceApiError extends Error {\r\n  public readonly status: number;\r\n  public readonly code?: string;\r\n  public readonly details?: unknown;\r\n  public readonly requestId?: string;\r\n\r\n  constructor(message: string, status: number, code?: string, details?: unknown, requestId?: string) {\r\n    super(message);\r\n    this.name = 'BuilderforceApiError';\r\n    this.status = status;\r\n    this.code = code;\r\n    this.details = details;\r\n    this.requestId = requestId;\r\n  }\r\n}\r\n\r\nexport interface HttpClientOptions {\r\n  apiKey: string;\r\n  baseUrl: string;\r\n  fetchFn?: typeof fetch;\r\n  timeoutMs?: number;\r\n}\r\n\r\nexport class HttpClient {\r\n  private readonly apiKey: string;\r\n  private readonly baseUrl: string;\r\n  private readonly fetchFn: typeof fetch;\r\n  private readonly timeoutMs: number;\r\n\r\n  constructor(options: HttpClientOptions) {\r\n    this.apiKey = options.apiKey;\r\n    this.baseUrl = options.baseUrl.replace(/\\/$/, '');\r\n    this.fetchFn = options.fetchFn ?? fetch;\r\n    this.timeoutMs = options.timeoutMs ?? 60_000;\r\n  }\r\n\r\n  async getJson<T>(path: string): Promise<T> {\r\n    const res = await this.fetchWithTimeout(`${this.baseUrl}${path}`, {\r\n      method: 'GET',\r\n      headers: this.authHeaders(),\r\n    });\r\n    return this.parseJsonResponse<T>(res);\r\n  }\r\n\r\n  async postJson<T>(path: string, body: unknown): Promise<T> {\r\n    const res = await this.fetchWithTimeout(`${this.baseUrl}${path}`, {\r\n      method: 'POST',\r\n      headers: {\r\n        ...this.authHeaders(),\r\n        'Content-Type': 'application/json',\r\n      },\r\n      body: JSON.stringify(body),\r\n    });\r\n    return this.parseJsonResponse<T>(res);\r\n  }\r\n\r\n  async postRaw(path: string, body: unknown): Promise<Response> {\r\n    const res = await this.fetchWithTimeout(`${this.baseUrl}${path}`, {\r\n      method: 'POST',\r\n      headers: {\r\n        ...this.authHeaders(),\r\n        'Content-Type': 'application/json',\r\n      },\r\n      body: JSON.stringify(body),\r\n    });\r\n    if (!res.ok) {\r\n      throw await this.toApiError(res);\r\n    }\r\n    return res;\r\n  }\r\n\r\n  private authHeaders(): Record<string, string> {\r\n    return {\r\n      Authorization: `Bearer ${this.apiKey}`,\r\n    };\r\n  }\r\n\r\n  private async fetchWithTimeout(input: RequestInfo | URL, init: RequestInit): Promise<Response> {\r\n    const controller = new AbortController();\r\n    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);\r\n    try {\r\n      return await this.fetchFn(input, { ...init, signal: controller.signal });\r\n    } catch (error) {\r\n      if (controller.signal.aborted) {\r\n        throw new BuilderforceApiError(`Request timed out after ${this.timeoutMs}ms`, 408, 'timeout');\r\n      }\r\n      throw error;\r\n    } finally {\r\n      clearTimeout(timeout);\r\n    }\r\n  }\r\n\r\n  private async parseJsonResponse<T>(res: Response): Promise<T> {\r\n    if (!res.ok) {\r\n      throw await this.toApiError(res);\r\n    }\r\n    return res.json() as Promise<T>;\r\n  }\r\n\r\n  private async toApiError(res: Response): Promise<BuilderforceApiError> {\r\n    const fallback = `Request failed (${res.status})`;\r\n    const requestId = res.headers.get('x-request-id') ?? undefined;\r\n    try {\r\n      const payload = await res.json() as { error?: string; code?: string; details?: unknown };\r\n      return new BuilderforceApiError(payload.error ?? fallback, res.status, payload.code, payload.details, requestId);\r\n    } catch {\r\n      const text = await res.text().catch(() => '');\r\n      return new BuilderforceApiError(text || fallback, res.status, undefined, undefined, requestId);\r\n    }\r\n  }\r\n}\r\n","import { ChatCompletionsApi } from './application/ChatCompletionsApi';\r\nimport { ModelsApi } from './application/ModelsApi';\r\nimport { UsageApi } from './application/UsageApi';\r\nimport { BuilderforceApiError, HttpClient } from './infrastructure/httpClient';\r\n\r\nexport interface BuilderforceClientOptions {\r\n  apiKey: string;\r\n  baseUrl?: string;\r\n  fetch?: typeof fetch;\r\n  timeoutMs?: number;\r\n}\r\n\r\nexport class BuilderforceClient {\r\n  public readonly chat: {\r\n    completions: ChatCompletionsApi;\r\n  };\r\n  public readonly models: ModelsApi;\r\n  public readonly usage: UsageApi;\r\n\r\n  constructor(options: BuilderforceClientOptions) {\r\n    const apiKey = options.apiKey?.trim();\r\n    if (!apiKey) {\r\n      throw new BuilderforceApiError(\r\n        'BuilderforceClient requires a non-empty apiKey',\r\n        400,\r\n        'missing_api_key',\r\n      );\r\n    }\r\n\r\n    const http = new HttpClient({\r\n      apiKey,\r\n      baseUrl: options.baseUrl ?? 'https://api.builderforce.ai',\r\n      fetchFn: options.fetch,\r\n      timeoutMs: options.timeoutMs,\r\n    });\r\n\r\n    this.chat = {\r\n      completions: new ChatCompletionsApi(http),\r\n    };\r\n    this.models = new ModelsApi(http);\r\n    this.usage = new UsageApi(http);\r\n  }\r\n}\r\n","// Keep this list aligned with api/src/application/llm/aiUseCases.ts.\r\nexport const AI_USE_CASES = [\r\n  'ide.chat',\r\n  'ide.code_complete',\r\n  'training.dataset_generate',\r\n  'training.dataset_evaluate',\r\n  'agent.inference',\r\n  'coder.code',\r\n  'coder.review',\r\n  'coder.test',\r\n  'coder.debug',\r\n  'coder.refactor',\r\n  'coder.document',\r\n  'coder.architect',\r\n  'coach.chat',\r\n  'coach.insight',\r\n  'coach.classify',\r\n  'studio.compose',\r\n  'studio.script',\r\n  'studio.brief',\r\n  'pitch_deck.generate',\r\n  'investor.update',\r\n  'ask.general',\r\n  'tool.classify_email',\r\n  'tool.categorize_expense',\r\n  'tool.contract_analyze',\r\n  'tool.competitor_scan',\r\n  'tool.feature_score',\r\n  'tool.market_research',\r\n  'tool.health_score',\r\n  'tool.journey_insight',\r\n  'vision.describe',\r\n  'ocr.extract',\r\n  'embed.text',\r\n  'match',\r\n  'match_tailor',\r\n  'match_insights',\r\n  'resume_roast',\r\n  'skill_extract',\r\n  'job_parser',\r\n  'autofill',\r\n  'article_writer',\r\n  'studio_script',\r\n  'studio_edit_script',\r\n  'studio_misc',\r\n  'linkedin_post',\r\n  'interview_questions',\r\n  'interview_analyze',\r\n  'chat',\r\n  'career',\r\n  'discovery',\r\n  'dashboard_summary',\r\n] as const;\r\n\r\nexport type AIUseCase = (typeof AI_USE_CASES)[number];\r\n\r\nexport function isAIUseCase(value: string): value is AIUseCase {\r\n  return (AI_USE_CASES as readonly string[]).includes(value);\r\n}\r\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/infrastructure/sse.ts","../src/application/ChatCompletionsApi.ts","../src/application/EmbeddingsApi.ts","../src/application/ModelsApi.ts","../src/application/UsageApi.ts","../src/infrastructure/httpClient.ts","../src/BuilderforceClient.ts"],"sourcesContent":["export async function* parseSseJson<T>(\n  stream: ReadableStream<Uint8Array>,\n): AsyncGenerator<T, void, unknown> {\n  const reader = stream.getReader();\n  const decoder = new TextDecoder();\n  let buffer = '';\n\n  while (true) {\n    const { done, value } = await reader.read();\n    if (done) break;\n\n    buffer += decoder.decode(value, { stream: true });\n    const lines = buffer.split('\\n');\n    buffer = lines.pop() ?? '';\n\n    for (const line of lines) {\n      const trimmed = line.trim();\n      if (!trimmed.startsWith('data: ')) continue;\n\n      const data = trimmed.slice(6).trim();\n      if (data === '[DONE]') return;\n\n      try {\n        yield JSON.parse(data) as T;\n      } catch {\n        // Skip malformed chunks instead of breaking the stream.\n      }\n    }\n  }\n}\n","import type { ChatCompletionChunk, ChatCompletionCreateParams, ChatCompletionResponse } from '../domain/types';\nimport { HttpClient, type RequestOptions } from '../infrastructure/httpClient';\nimport { parseSseJson } from '../infrastructure/sse';\n\nexport class ChatCompletionStream implements AsyncIterable<ChatCompletionChunk> {\n  private readonly stream: ReadableStream<Uint8Array>;\n\n  constructor(stream: ReadableStream<Uint8Array>) {\n    this.stream = stream;\n  }\n\n  [Symbol.asyncIterator](): AsyncIterator<ChatCompletionChunk, void, unknown> {\n    return parseSseJson<ChatCompletionChunk>(this.stream);\n  }\n\n  async toText(): Promise<string> {\n    let full = '';\n    for await (const chunk of this) {\n      const delta = chunk.choices?.[0]?.delta?.content;\n      if (typeof delta === 'string') {\n        full += delta;\n      }\n    }\n    return full;\n  }\n}\n\n/**\n * Pull SDK-level transport options (timeout, signal, idempotency key) out of\n * the params object so they don't get JSON-serialized into the request body.\n * Returns the request options AND the cleaned-up body.\n */\nfunction splitTransportOptions(params: ChatCompletionCreateParams): {\n  body: Record<string, unknown>;\n  request: RequestOptions;\n} {\n  const { timeoutMs, signal, idempotencyKey, ...rest } = params;\n  const headers: Record<string, string> = {};\n  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;\n  return {\n    body: rest as unknown as Record<string, unknown>,\n    request: {\n      timeoutMs,\n      signal,\n      ...(Object.keys(headers).length > 0 ? { headers } : {}),\n    },\n  };\n}\n\nexport class ChatCompletionsApi {\n  private readonly http: HttpClient;\n\n  constructor(http: HttpClient) {\n    this.http = http;\n  }\n\n  async create(params: ChatCompletionCreateParams & { stream: true }): Promise<ChatCompletionStream>;\n  async create(params: ChatCompletionCreateParams & { stream?: false | undefined }): Promise<ChatCompletionResponse>;\n  async create(\n    params: ChatCompletionCreateParams,\n  ): Promise<ChatCompletionResponse | ChatCompletionStream> {\n    const { body, request } = splitTransportOptions(params);\n\n    if (params.stream) {\n      const response = await this.http.postRaw('/llm/v1/chat/completions', body, request);\n      if (!response.body) {\n        throw new Error('Streaming response body is missing');\n      }\n      return new ChatCompletionStream(response.body);\n    }\n\n    return this.http.postJson<ChatCompletionResponse>('/llm/v1/chat/completions', body, request);\n  }\n}\n","import type { EmbeddingsCreateParams, EmbeddingsResponse } from '../domain/types';\nimport { HttpClient, type RequestOptions } from '../infrastructure/httpClient';\n\n/**\n * Pull SDK-level transport options out of the params so they don't ride\n * along inside the JSON body. Same shape as ChatCompletionsApi (DRY pattern).\n */\nfunction splitTransportOptions(params: EmbeddingsCreateParams): {\n  body: Record<string, unknown>;\n  request: RequestOptions;\n} {\n  const { timeoutMs, signal, idempotencyKey, ...rest } = params;\n  const headers: Record<string, string> = {};\n  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;\n  return {\n    body: rest as unknown as Record<string, unknown>,\n    request: {\n      timeoutMs,\n      signal,\n      ...(Object.keys(headers).length > 0 ? { headers } : {}),\n    },\n  };\n}\n\nexport class EmbeddingsApi {\n  private readonly http: HttpClient;\n\n  constructor(http: HttpClient) {\n    this.http = http;\n  }\n\n  /**\n   * Create one or more text embeddings.\n   *\n   * NOTE: As of v0.3.0 the gateway accepts the request shape but the underlying\n   * vendor wiring is still being rolled out — calls may currently 503 with\n   * `code: 'embeddings_not_wired'`. Track gateway PRD §6.7.\n   */\n  create(params: EmbeddingsCreateParams): Promise<EmbeddingsResponse> {\n    const { body, request } = splitTransportOptions(params);\n    return this.http.postJson<EmbeddingsResponse>('/llm/v1/embeddings', body, request);\n  }\n}\n","import type { ModelsListResponse } from '../domain/types';\nimport { HttpClient } from '../infrastructure/httpClient';\n\nexport class ModelsApi {\n  private readonly http: HttpClient;\n\n  constructor(http: HttpClient) {\n    this.http = http;\n  }\n\n  list(): Promise<ModelsListResponse> {\n    return this.http.getJson<ModelsListResponse>('/llm/v1/models');\n  }\n}\n","import type { UsageGetParams, UsageResponse } from '../domain/types';\nimport { HttpClient } from '../infrastructure/httpClient';\n\nexport class UsageApi {\n  private readonly http: HttpClient;\n\n  constructor(http: HttpClient) {\n    this.http = http;\n  }\n\n  get(params: UsageGetParams = {}): Promise<UsageResponse> {\n    const query = typeof params.days === 'number' ? `?days=${encodeURIComponent(String(params.days))}` : '';\n    return this.http.getJson<UsageResponse>(`/llm/v1/usage${query}`);\n  }\n}\n","export class BuilderforceApiError extends Error {\n  public readonly status: number;\n  public readonly code?: string;\n  public readonly details?: unknown;\n  public readonly requestId?: string;\n\n  constructor(message: string, status: number, code?: string, details?: unknown, requestId?: string) {\n    super(message);\n    this.name = 'BuilderforceApiError';\n    this.status = status;\n    this.code = code;\n    this.details = details;\n    this.requestId = requestId;\n  }\n}\n\nexport interface HttpClientOptions {\n  apiKey: string;\n  baseUrl: string;\n  fetchFn?: typeof fetch;\n  /** Default per-request timeout in ms. Overridable per call. */\n  timeoutMs?: number;\n}\n\n/** Per-request overrides — passed by the API layer, not by SDK consumers directly. */\nexport interface RequestOptions {\n  /** Override the client default timeout for just this request. */\n  timeoutMs?: number;\n  /** Caller-provided AbortSignal. Linked together with the SDK's internal timeout\n   *  signal — whichever fires first aborts the request. */\n  signal?: AbortSignal;\n  /** Extra headers to merge in (e.g. `Idempotency-Key`). */\n  headers?: Record<string, string>;\n}\n\nexport class HttpClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly fetchFn: typeof fetch;\n  private readonly defaultTimeoutMs: number;\n\n  constructor(options: HttpClientOptions) {\n    this.apiKey = options.apiKey;\n    this.baseUrl = options.baseUrl.replace(/\\/$/, '');\n    this.fetchFn = options.fetchFn ?? fetch;\n    this.defaultTimeoutMs = options.timeoutMs ?? 60_000;\n  }\n\n  async getJson<T>(path: string, options?: RequestOptions): Promise<T> {\n    const res = await this.fetchWithTimeout(`${this.baseUrl}${path}`, {\n      method: 'GET',\n      headers: this.mergeHeaders(options),\n    }, options);\n    return this.parseJsonResponse<T>(res);\n  }\n\n  async postJson<T>(path: string, body: unknown, options?: RequestOptions): Promise<T> {\n    const res = await this.fetchWithTimeout(`${this.baseUrl}${path}`, {\n      method: 'POST',\n      headers: this.mergeHeaders(options, { 'Content-Type': 'application/json' }),\n      body: JSON.stringify(body),\n    }, options);\n    return this.parseJsonResponse<T>(res);\n  }\n\n  async postRaw(path: string, body: unknown, options?: RequestOptions): Promise<Response> {\n    const res = await this.fetchWithTimeout(`${this.baseUrl}${path}`, {\n      method: 'POST',\n      headers: this.mergeHeaders(options, { 'Content-Type': 'application/json' }),\n      body: JSON.stringify(body),\n    }, options);\n    if (!res.ok) {\n      throw await this.toApiError(res);\n    }\n    return res;\n  }\n\n  private mergeHeaders(options?: RequestOptions, base?: Record<string, string>): Record<string, string> {\n    return {\n      Authorization: `Bearer ${this.apiKey}`,\n      ...(base ?? {}),\n      ...(options?.headers ?? {}),\n    };\n  }\n\n  /**\n   * Wrap a fetch in a combined abort signal: an internal timeout AND any\n   * caller-provided signal. Either firing aborts the request. Single source of\n   * abort plumbing — every method routes through here (DRY).\n   */\n  private async fetchWithTimeout(\n    input: RequestInfo | URL,\n    init: RequestInit,\n    options?: RequestOptions,\n  ): Promise<Response> {\n    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;\n    const timeoutCtl = new AbortController();\n    const timer = setTimeout(() => timeoutCtl.abort(), timeoutMs);\n\n    // Combine internal timeout signal + caller signal. Native AbortSignal.any\n    // (Node 20+ / modern Workers) is preferred; fall back to manual linking.\n    const signal = combineSignals(timeoutCtl.signal, options?.signal);\n\n    try {\n      return await this.fetchFn(input, { ...init, signal });\n    } catch (error) {\n      if (timeoutCtl.signal.aborted) {\n        throw new BuilderforceApiError(`Request timed out after ${timeoutMs}ms`, 408, 'timeout');\n      }\n      if (options?.signal?.aborted) {\n        throw new BuilderforceApiError('Request aborted by caller', 499, 'aborted');\n      }\n      throw error;\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n\n  private async parseJsonResponse<T>(res: Response): Promise<T> {\n    if (!res.ok) {\n      throw await this.toApiError(res);\n    }\n    return res.json() as Promise<T>;\n  }\n\n  private async toApiError(res: Response): Promise<BuilderforceApiError> {\n    const fallback = `Request failed (${res.status})`;\n    const requestId = res.headers.get('x-request-id') ?? undefined;\n    try {\n      const payload = await res.json() as { error?: string; code?: string; details?: unknown };\n      return new BuilderforceApiError(payload.error ?? fallback, res.status, payload.code, payload.details, requestId);\n    } catch {\n      const text = await res.text().catch(() => '');\n      return new BuilderforceApiError(text || fallback, res.status, undefined, undefined, requestId);\n    }\n  }\n}\n\n/**\n * Combine multiple AbortSignals into one. Uses native `AbortSignal.any` when\n * available (Node 20+, modern Workers); falls back to manual event linking.\n */\nfunction combineSignals(...signals: Array<AbortSignal | undefined>): AbortSignal {\n  const live = signals.filter((s): s is AbortSignal => s !== undefined);\n  if (live.length === 1) return live[0]!;\n\n  const anyImpl = (AbortSignal as unknown as { any?: (signals: AbortSignal[]) => AbortSignal }).any;\n  if (typeof anyImpl === 'function') {\n    return anyImpl(live);\n  }\n\n  const ctl = new AbortController();\n  for (const s of live) {\n    if (s.aborted) { ctl.abort(s.reason); break; }\n    s.addEventListener('abort', () => ctl.abort(s.reason), { once: true });\n  }\n  return ctl.signal;\n}\n","import { ChatCompletionsApi } from './application/ChatCompletionsApi';\nimport { EmbeddingsApi } from './application/EmbeddingsApi';\nimport { ModelsApi } from './application/ModelsApi';\nimport { UsageApi } from './application/UsageApi';\nimport { BuilderforceApiError, HttpClient } from './infrastructure/httpClient';\n\nexport interface BuilderforceClientOptions {\n  apiKey: string;\n  baseUrl?: string;\n  fetch?: typeof fetch;\n  /** Default request timeout in ms (default 60_000). Per-call override available\n   *  via `chat.completions.create({ timeoutMs })` and `embeddings.create({ timeoutMs })`. */\n  timeoutMs?: number;\n}\n\nexport class BuilderforceClient {\n  public readonly chat: {\n    completions: ChatCompletionsApi;\n  };\n  public readonly embeddings: EmbeddingsApi;\n  public readonly models: ModelsApi;\n  public readonly usage: UsageApi;\n\n  constructor(options: BuilderforceClientOptions) {\n    const apiKey = options.apiKey?.trim();\n    if (!apiKey) {\n      throw new BuilderforceApiError(\n        'BuilderforceClient requires a non-empty apiKey',\n        400,\n        'missing_api_key',\n      );\n    }\n\n    const http = new HttpClient({\n      apiKey,\n      baseUrl: options.baseUrl ?? 'https://api.builderforce.ai',\n      fetchFn: options.fetch,\n      timeoutMs: options.timeoutMs,\n    });\n\n    this.chat = {\n      completions: new ChatCompletionsApi(http),\n    };\n    this.embeddings = new EmbeddingsApi(http);\n    this.models = new ModelsApi(http);\n    this.usage = new UsageApi(http);\n  }\n}\n"],"mappings":"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","names":["splitTransportOptions"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seanhogg/builderforce-sdk",
-  "version": "0.2.0",
-  "description": "Typed SDK for the Builderforce.ai LLM gateway — chat completions, models, and usage analytics over an OpenAI-compatible surface.",
+  "version": "0.3.0",
+  "description": "Typed SDK for the Builderforce.ai LLM gateway — chat completions with tool-calling and structured output, embeddings, models, and usage analytics over an OpenAI-compatible surface.",
   "license": "MIT",
   "author": "Sean Hogg",
   "homepage": "https://github.com/SeanHogg/Builderforce.ai/tree/main/sdk#readme",
@@ -43,11 +43,11 @@
     "access": "public"
   },
   "scripts": {
-    "check:usecases": "node scripts/check-usecases-sync.mjs",
     "build": "tsup --config tsup.config.ts",
     "type-check": "tsc --noEmit",
-    "test": "npm run check:usecases && vitest run",
-    "prepublishOnly": "npm run build"
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "publish:if-new": "node scripts/publish-if-new.mjs"
   },
   "engines": {
     "node": ">=18"