SDK

npm install openai

// client.ts
import OpenAI from "openai";

export const lobstack = new OpenAI({
  apiKey: process.env.LOBSTACK_API_KEY,       // lsk_live_…
  baseURL: "https://www.lobstack.ai/api/gateway/v1",
});

const completion = await lobstack.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Summarise this changelog in one line." }],
  max_tokens: 256,
});

console.log(completion.choices[0].message.content);
// The model that actually served it, which may differ from what you asked for.
console.log(completion.model);

const { data, response } = await lobstack.chat.completions
  .create({
    model: "claude-opus-5",
    messages: [{ role: "user", content: "hey, you there?" }],
  })
  .withResponse();

console.log(data.choices[0].message.content);
console.log({
  served:     response.headers.get("x-lobstack-model"),
  tier:       response.headers.get("x-lobstack-tier"),
  complexity: response.headers.get("x-lobstack-complexity"),
  routed:     response.headers.get("x-lobstack-routed"),
  costUsd:    response.headers.get("x-lobstack-cost-usd"),
  savingsUsd: response.headers.get("x-lobstack-savings-usd"),
  // ALWAYS read this next to savingsUsd. "named" means the saving is against
  // the model you asked for. "plan_ceiling" means you sent "auto" and it is
  // against the priciest model your plan allows — which you did not request.
  baselineReason: response.headers.get("x-lobstack-baseline-reason"),
  baselineModel:  response.headers.get("x-lobstack-baseline-model"),
  requestId:  response.headers.get("x-lobstack-request-id"),
});

const stream = await lobstack.chat.completions.create({
  model: "auto",
  stream: true,
  messages: [{ role: "user", content: "List three causes of a rollback." }],
});

for await (const chunk of stream) {
  // The last data chunk has an empty choices array and carries usage.
  if (chunk.usage) {
    console.log("\ntokens:", chunk.usage.total_tokens);
    continue;
  }
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

export interface LobstackReceipt {
  requestId: string | null;
  model: string | null;
  tier: string | null;
  complexity: number | null;
  routed: boolean;
  costUsd: number | null;      // null when the model is unpriced
  savingsUsd: number | null;   // null when there is no baseline at all
  // What savingsUsd was measured against, and why. Never render the saving
  // without the reason: "plan_ceiling" is a comparison against a model the
  // caller did not choose.
  baselineModel: string | null;
  baselineReason: "named" | "plan_ceiling" | null;
  droppedParams: string | null;
}

export interface LobstackResult<T> {
  data: T;
  receipt: LobstackReceipt;
}

const BASE = "https://www.lobstack.ai/api/gateway/v1";

/** Headers carry empty strings where the honest answer is "no number". */
function num(h: Headers, k: string): number | null {
  const v = h.get(k);
  return v === null || v === "" ? null : Number(v);
}

export async function chat<T = unknown>(
  apiKey: string,
  body: Record<string, unknown>,
): Promise<LobstackResult<T>> {
  const res = await fetch(`${BASE}/chat/completions`, {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  const json = await res.json();
  if (!res.ok) {
    const e = json?.error ?? {};
    throw Object.assign(new Error(e.message ?? `gateway error ${res.status}`), {
      status: res.status,
      class: e.type ?? null,
      requestId: e.request_id ?? res.headers.get("x-lobstack-request-id"),
    });
  }

  const h = res.headers;
  return {
    data: json as T,
    receipt: {
      requestId: h.get("x-lobstack-request-id"),
      model: h.get("x-lobstack-model"),
      tier: h.get("x-lobstack-tier"),
      complexity: num(h, "x-lobstack-complexity"),
      routed: h.get("x-lobstack-routed") === "true",
      costUsd: num(h, "x-lobstack-cost-usd"),
      savingsUsd: num(h, "x-lobstack-savings-usd"),
      baselineModel: h.get("x-lobstack-baseline-model"),
      baselineReason: h.get("x-lobstack-baseline-reason") as "named" | "plan_ceiling" | null,
      droppedParams: h.get("x-lobstack-dropped-params"),
    },
  };
}

const models = await lobstack.models.list();
for (const m of models.data) {
  console.log(m.id, m.owned_by);
}