@punktechnologies/sdk 0.1.2 → 0.2.0

package/dist/index.js

@@ -2,8 +2,11 @@
 var PUNK_CHORUS_MODEL = "punk/chorus";
 var PUNK_MODEL = PUNK_CHORUS_MODEL;
 var DEFAULT_BASE_URL = "http://localhost:4100";
+var DEFAULT_APP = "default-app";
 var MAX_TOOL_CACHE_TTL_SECONDS = 24 * 60 * 60;
 var MAX_TOOL_CACHE_DIMENSION_CHARS = 120;
+var DEFAULT_WAIT_POLL_INTERVAL_MS = 250;
+var DEFAULT_WAIT_TIMEOUT_MS = 30000;
 function stringifyToolArguments(value) {
   if (typeof value === "string")
     return value;
@@ -467,6 +470,16 @@ function cleanPathId(label, value) {
   }
   return trimmed;
 }
+function readEnv(name) {
+  const env = globalThis?.process?.env;
+  if (!env || typeof env !== "object")
+    return;
+  const value = env[name];
+  return typeof value === "string" ? value : undefined;
+}
+function optionOrEnv(opts, key, envName) {
+  return Object.prototype.hasOwnProperty.call(opts, key) ? opts[key] : readEnv(envName);
+}
 function normalizeBaseUrl(value) {
   const trimmed = typeof value === "string" ? value.trim() : "";
   return (trimmed || DEFAULT_BASE_URL).replace(/\/+$/, "");
@@ -513,6 +526,170 @@ function chatMessageText(message) {
   }
   return chatMessageContentToString(message?.content);
 }
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function normalizeOpenAIUsage(raw) {
+  if (!isRecord(raw?.usage))
+    return;
+  const usage = raw.usage;
+  const normalized = { raw: raw.usage };
+  const inputTokens = finiteNumber(usage.prompt_tokens ?? usage.input_tokens);
+  const outputTokens = finiteNumber(usage.completion_tokens ?? usage.output_tokens);
+  const totalTokens = finiteNumber(usage.total_tokens);
+  if (inputTokens !== undefined)
+    normalized.inputTokens = inputTokens;
+  if (outputTokens !== undefined)
+    normalized.outputTokens = outputTokens;
+  if (totalTokens !== undefined)
+    normalized.totalTokens = totalTokens;
+  if (normalized.totalTokens === undefined && inputTokens !== undefined && outputTokens !== undefined) {
+    normalized.totalTokens = inputTokens + outputTokens;
+  }
+  return normalized;
+}
+function normalizeAnthropicUsage(raw) {
+  if (!isRecord(raw?.usage))
+    return;
+  const usage = raw.usage;
+  const normalized = { raw: raw.usage };
+  const inputTokens = finiteNumber(usage.input_tokens);
+  const outputTokens = finiteNumber(usage.output_tokens);
+  if (inputTokens !== undefined)
+    normalized.inputTokens = inputTokens;
+  if (outputTokens !== undefined)
+    normalized.outputTokens = outputTokens;
+  if (inputTokens !== undefined && outputTokens !== undefined)
+    normalized.totalTokens = inputTokens + outputTokens;
+  return normalized;
+}
+function normalizeModel(raw) {
+  return typeof raw?.model === "string" && raw.model.length > 0 ? raw.model : undefined;
+}
+function normalizeProvider(raw) {
+  for (const key of ["provider", "providerName", "provider_name"]) {
+    if (typeof raw?.[key] === "string" && raw[key].length > 0)
+      return raw[key];
+  }
+  return;
+}
+function anthropicTextFromContent(value, method, path) {
+  if (typeof value === "string")
+    return value;
+  if (!Array.isArray(value)) {
+    throw malformedApiResponse(method, path, "content must be a string or content block array");
+  }
+  return value.map((part) => {
+    if (typeof part === "string")
+      return part;
+    if (part?.type === "text" && typeof part.text === "string")
+      return part.text;
+    return "";
+  }).join("");
+}
+function anthropicMessageText(raw, method, path) {
+  if (!isRecord(raw))
+    throw malformedApiResponse(method, path, "missing response object");
+  if (!Object.prototype.hasOwnProperty.call(raw, "content")) {
+    throw malformedApiResponse(method, path, "missing content");
+  }
+  return anthropicTextFromContent(raw.content, method, path);
+}
+function anthropicContentBlocks(raw, method, path) {
+  if (!isRecord(raw))
+    throw malformedApiResponse(method, path, "missing response object");
+  const content = raw.content;
+  if (typeof content === "string")
+    return [{ type: "text", text: content }];
+  if (!Array.isArray(content))
+    throw malformedApiResponse(method, path, "content must be a string or content block array");
+  return content.filter(isRecord);
+}
+function parseSseFrame(frame) {
+  const data = [];
+  let event;
+  for (const line of frame.split(/\r?\n/)) {
+    if (line.length === 0 || line.startsWith(":"))
+      continue;
+    if (line.startsWith("event:")) {
+      event = line.slice("event:".length).trim();
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      const value = line.slice("data:".length);
+      data.push(value.startsWith(" ") ? value.slice(1) : value);
+    }
+  }
+  if (data.length === 0)
+    return null;
+  return { event, data: data.join(`
+`) };
+}
+async function* sseFrames(res, method, path) {
+  if (!res.body) {
+    throw new Error(`Punk API ${method} ${path} returned an empty stream`);
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done });
+      let boundary = buffer.search(/\r?\n\r?\n/);
+      while (boundary >= 0) {
+        const frameText = buffer.slice(0, boundary);
+        const match = buffer.slice(boundary).match(/^\r?\n\r?\n/);
+        buffer = buffer.slice(boundary + (match?.[0].length ?? 2));
+        const frame = parseSseFrame(frameText);
+        if (frame)
+          yield frame;
+        boundary = buffer.search(/\r?\n\r?\n/);
+      }
+      if (done)
+        break;
+    }
+    const tail = parseSseFrame(buffer.trim());
+    if (tail)
+      yield tail;
+  } finally {
+    reader.releaseLock();
+  }
+}
+function parseSseJson(frame, method, path) {
+  try {
+    return JSON.parse(frame.data);
+  } catch {
+    throw malformedApiResponse(method, path, "stream data was not JSON");
+  }
+}
+function streamDeltaText(value) {
+  if (value === undefined || value === null)
+    return "";
+  if (typeof value === "string")
+    return value;
+  if (Array.isArray(value)) {
+    return value.map((part) => typeof part?.text === "string" ? part.text : "").join("");
+  }
+  return "";
+}
+function isTerminalRunStatus(status) {
+  return status === "completed" || status === "failed" || status === "blocked";
+}
+function checkedDelay(ms, signal) {
+  if (signal?.aborted)
+    return Promise.reject(new Error("Punk wait aborted"));
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(resolve, ms);
+    const onAbort = () => {
+      clearTimeout(timeout);
+      reject(new Error("Punk wait aborted"));
+    };
+    if (signal) {
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
 var TOOL_LEVEL_4 = new Set([
   "delete",
   "remove",
@@ -687,12 +864,107 @@ class Punk {
   agent;
   subject;
   apiKey;
+  runStack = [];
   constructor(opts = {}) {
-    this.baseUrl = normalizeBaseUrl(opts.baseUrl);
-    this.apiKey = cleanIdentityValue(opts.apiKey);
-    this.app = cleanIdentityValue(opts.app) ?? "default-app";
-    this.agent = cleanIdentityValue(opts.agent);
-    this.subject = cleanIdentityValue(opts.subject);
+    this.baseUrl = normalizeBaseUrl(optionOrEnv(opts, "baseUrl", "PUNK_BASE_URL"));
+    this.apiKey = cleanIdentityValue(optionOrEnv(opts, "apiKey", "PUNK_API_KEY"));
+    this.app = cleanIdentityValue(optionOrEnv(opts, "app", "PUNK_APP")) ?? DEFAULT_APP;
+    this.agent = cleanIdentityValue(optionOrEnv(opts, "agent", "PUNK_AGENT"));
+    this.subject = cleanIdentityValue(optionOrEnv(opts, "subject", "PUNK_SUBJECT"));
+  }
+  gateway = {
+    chat: (params) => this.chat(params),
+    streamChat: (params) => this.streamChat(params),
+    stream: (params) => this.chatStream(params)
+  };
+  openai = {
+    chat: (params) => this.chat(params),
+    streamChat: (params) => this.streamChat(params),
+    stream: (params) => this.chatStream(params),
+    config: (opts) => this.openAIConfig(opts)
+  };
+  anthropic = {
+    messages: (params) => this.messages(params),
+    streamMessages: (params) => this.streamMessages(params),
+    stream: (params) => this.messagesStream(params),
+    config: (opts) => this.anthropicConfig(opts)
+  };
+  identityHeaders(opts = {}) {
+    const includeAuthorization = opts.includeAuthorization !== false;
+    const headers = {};
+    if (opts.includeContentType === true)
+      headers["Content-Type"] = "application/json";
+    if (includeAuthorization && this.apiKey)
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    const app = cleanIdentityValue(opts.app) ?? this.app;
+    const agent = cleanIdentityValue(opts.agent) ?? this.agent;
+    const subject = cleanIdentityValue(opts.subject) ?? this.subject;
+    headers["X-Punk-App"] = app;
+    if (agent)
+      headers["X-Punk-Agent"] = agent;
+    if (subject)
+      headers["X-Punk-Subject"] = subject;
+    if (opts.headers) {
+      for (const [key, value] of Object.entries(opts.headers)) {
+        if (typeof value === "string" && value.trim().length > 0)
+          headers[key] = value;
+      }
+    }
+    return headers;
+  }
+  openAIConfig(opts = {}) {
+    const baseUrl = normalizeBaseUrl(opts.baseUrl ?? this.baseUrl);
+    const apiKey = cleanIdentityValue(opts.apiKey) ?? this.apiKey ?? "punk-local";
+    return {
+      baseURL: `${baseUrl}/v1`,
+      apiKey,
+      defaultHeaders: this.identityHeaders({ ...opts, includeAuthorization: false })
+    };
+  }
+  anthropicConfig(opts = {}) {
+    const baseUrl = normalizeBaseUrl(opts.baseUrl ?? this.baseUrl);
+    const authToken = cleanIdentityValue(opts.apiKey) ?? this.apiKey ?? "punk-local";
+    return {
+      baseURL: baseUrl,
+      authToken,
+      defaultHeaders: this.identityHeaders({ ...opts, includeAuthorization: true })
+    };
+  }
+  vercelAIConfig(opts = {}) {
+    return this.vercelOpenAICompatibleConfig(opts);
+  }
+  vercelOpenAICompatibleConfig(opts = {}) {
+    const baseUrl = normalizeBaseUrl(opts.baseUrl ?? this.baseUrl);
+    return {
+      name: cleanIdentityValue(opts.name) ?? "punk",
+      baseURL: `${baseUrl}/v1`,
+      apiKey: cleanIdentityValue(opts.apiKey) ?? this.apiKey ?? "punk-local",
+      headers: this.identityHeaders({ ...opts, includeAuthorization: false }),
+      includeUsage: opts.includeUsage ?? true
+    };
+  }
+  langChainConfig(opts = {}) {
+    const baseUrl = normalizeBaseUrl(opts.baseUrl ?? this.baseUrl);
+    return {
+      apiKey: cleanIdentityValue(opts.apiKey) ?? this.apiKey ?? "punk-local",
+      configuration: {
+        baseURL: `${baseUrl}/v1`,
+        defaultHeaders: this.identityHeaders({ ...opts, includeAuthorization: false })
+      }
+    };
+  }
+  currentRunId() {
+    return this.runStack.at(-1);
+  }
+  async withRun(run, fn) {
+    const rawRunId = typeof run === "string" ? run : run.runId;
+    const id = cleanPathId("run id", rawRunId ?? "");
+    this.runStack.push(id);
+    try {
+      return await fn();
+    } finally {
+      this.runStack.pop();
+    }
   }
   async chat(params) {
     let res;
@@ -719,16 +991,163 @@ class Punk {
       toolCalls,
       runId: res.headers.get("x-punk-run-id") ?? "",
       route: res.headers.get("x-punk-route") ?? "unknown",
-      raw
+      raw,
+      usage: normalizeOpenAIUsage(raw),
+      model: normalizeModel(raw),
+      provider: normalizeProvider(raw)
+    };
+  }
+  streamChat(params) {
+    return this.chatStream(params);
+  }
+  async* chatStream(params) {
+    const method = "POST";
+    const path = "/v1/chat/completions";
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers({
+          "X-Punk-App": this.app,
+          "X-Punk-Agent": this.agent,
+          "X-Punk-Subject": this.subject
+        }),
+        body: JSON.stringify({ ...params, stream: true })
+      });
+    } catch (err) {
+      throw this.toTransportError(method, path, err);
+    }
+    if (!res.ok)
+      throw this.toError(method, path, res, await res.text());
+    const runId = res.headers.get("x-punk-run-id") ?? "";
+    const route = res.headers.get("x-punk-route") ?? "unknown";
+    for await (const frame of sseFrames(res, method, path)) {
+      if (frame.data === "[DONE]") {
+        yield { type: "done", content: "", toolCalls: [], runId, route };
+        return;
+      }
+      const raw = parseSseJson(frame, method, path);
+      const choice = Array.isArray(raw?.choices) ? raw.choices[0] : undefined;
+      const delta = isRecord(choice?.delta) ? choice.delta : {};
+      yield {
+        type: "delta",
+        content: streamDeltaText(delta.content),
+        toolCalls: normalizeChatToolCalls(delta.tool_calls),
+        runId,
+        route,
+        raw,
+        usage: normalizeOpenAIUsage(raw),
+        model: normalizeModel(raw),
+        provider: normalizeProvider(raw)
+      };
+    }
+    yield { type: "done", content: "", toolCalls: [], runId, route };
+  }
+  async messages(params) {
+    const method = "POST";
+    const path = "/v1/messages";
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers({
+          "anthropic-version": "2023-06-01",
+          "X-Punk-App": this.app,
+          "X-Punk-Agent": this.agent,
+          "X-Punk-Subject": this.subject
+        }),
+        body: JSON.stringify({ ...params, stream: false })
+      });
+    } catch (err) {
+      throw this.toTransportError(method, path, err);
+    }
+    const raw = await this.parseJsonResponse(method, path, res);
+    return {
+      content: anthropicMessageText(raw, method, path),
+      contentBlocks: anthropicContentBlocks(raw, method, path),
+      runId: res.headers.get("x-punk-run-id") ?? "",
+      route: res.headers.get("x-punk-route") ?? "unknown",
+      raw,
+      usage: normalizeAnthropicUsage(raw),
+      model: normalizeModel(raw),
+      provider: normalizeProvider(raw),
+      stopReason: typeof raw?.stop_reason === "string" ? raw.stop_reason : undefined
     };
   }
+  streamMessages(params) {
+    return this.messagesStream(params);
+  }
+  async* messagesStream(params) {
+    const method = "POST";
+    const path = "/v1/messages";
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers({
+          "anthropic-version": "2023-06-01",
+          "X-Punk-App": this.app,
+          "X-Punk-Agent": this.agent,
+          "X-Punk-Subject": this.subject
+        }),
+        body: JSON.stringify({ ...params, stream: true })
+      });
+    } catch (err) {
+      throw this.toTransportError(method, path, err);
+    }
+    if (!res.ok)
+      throw this.toError(method, path, res, await res.text());
+    const runId = res.headers.get("x-punk-run-id") ?? "";
+    const route = res.headers.get("x-punk-route") ?? "unknown";
+    let model;
+    let usage;
+    for await (const frame of sseFrames(res, method, path)) {
+      const raw = parseSseJson(frame, method, path);
+      if (typeof raw?.message?.model === "string")
+        model = raw.message.model;
+      const messageUsage = normalizeAnthropicUsage(raw.message);
+      if (messageUsage)
+        usage = messageUsage;
+      if (isRecord(raw?.usage)) {
+        usage = normalizeAnthropicUsage({ usage: { ...usage?.raw, ...raw.usage } });
+      }
+      if (raw?.type === "content_block_delta") {
+        yield {
+          type: "delta",
+          content: typeof raw?.delta?.text === "string" ? raw.delta.text : "",
+          runId,
+          route,
+          event: frame.event,
+          raw,
+          usage,
+          model,
+          provider: normalizeProvider(raw)
+        };
+      }
+      if (raw?.type === "message_stop") {
+        yield {
+          type: "done",
+          content: "",
+          runId,
+          route,
+          event: frame.event,
+          raw,
+          usage,
+          model,
+          provider: normalizeProvider(raw)
+        };
+        return;
+      }
+    }
+    yield { type: "done", content: "", runId, route, usage, model };
+  }
   traceTool(def) {
     const toolName = requireCleanToolName(def.name);
     const level = classifySdkToolSideEffect(toolName, def.sideEffectLevel);
     const ttlSeconds = normalizeTtlSeconds(def.ttlSeconds);
     const schemaFp = cleanOptionalCacheDimension("schemaFp", def.schemaFp);
     return async (args, ctx) => {
-      const runId = cleanIdentityValue(ctx?.runId);
+      const runId = cleanIdentityValue(ctx?.runId) ?? this.currentRunId();
       const cacheable = level <= 1 && ttlSeconds !== undefined && runId !== undefined && this.subject !== undefined;
       if (runId) {
         const decision = await this.tryTraceDecision(runId, "tool.called", {
@@ -906,6 +1325,51 @@ class Punk {
     const path = `/api/v1/runs/${encodeURIComponent(cleanPathId("run id", id))}`;
     return requireRunDetailResult(await this.request("GET", path), "GET", path);
   }
+  async explain(runId) {
+    return this.runDetail(runId).then((detail) => detail.run.routeExplanation ?? null);
+  }
+  async savingsForRun(runId) {
+    const detail = await this.runDetail(runId);
+    return {
+      runId: detail.run.id,
+      route: detail.run.route,
+      status: detail.run.status,
+      costUsd: detail.run.costUsd,
+      savedUsd: detail.run.savedUsd,
+      ghostSavedUsd: detail.run.ghostSavedUsd ?? 0,
+      latencyMs: detail.run.latencyMs,
+      inputTokens: detail.run.inputTokens,
+      outputTokens: detail.run.outputTokens
+    };
+  }
+  async sideEffectsForRun(runId) {
+    return this.runDetail(runId).then((detail) => detail.sideEffects);
+  }
+  async waitForRun(runId, opts = {}) {
+    for await (const detail of this.watchRun(runId, opts)) {
+      if (isTerminalRunStatus(detail.run.status))
+        return detail;
+    }
+    throw new Error(`Punk waitForRun(${cleanPathId("run id", runId)}) ended before the run reached a terminal status`);
+  }
+  async* watchRun(runId, opts = {}) {
+    const id = cleanPathId("run id", runId);
+    const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_WAIT_POLL_INTERVAL_MS;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const startedAt = Date.now();
+    while (true) {
+      if (opts.signal?.aborted)
+        throw new Error("Punk watchRun aborted");
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`Punk watchRun(${id}) timed out after ${timeoutMs}ms`);
+      }
+      const detail = await this.runDetail(id);
+      yield detail;
+      if (isTerminalRunStatus(detail.run.status))
+        return;
+      await checkedDelay(pollIntervalMs, opts.signal);
+    }
+  }
   async receipt(id) {
     const path = `/api/v1/receipts/${encodeURIComponent(cleanPathId("receipt id", id))}`;
     return requireReceiptResult(await this.request("GET", path), "GET", path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punktechnologies/sdk",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Gateway Agnostic AI runtime SDK for OpenAI, Anthropic, OpenRouter, and more, with agent tracing, tool caching, governance, observability, and cost optimization.",
   "license": "Apache-2.0",
   "type": "module",