@usagetap/sdk 0.10.0 → 1.1.0

package/dist/index.cjs

@@ -115,9 +115,500 @@ async function runWithRetry(operation, options, shouldRetry, onSchedule, signal)
   throw lastError instanceof Error ? lastError : new Error(String(lastError));
 }
 
+// src/prompt-compression.ts
+var DEFAULT_TTC_ENDPOINT = "https://api.thetokencompany.com/v1/compress";
+var DEFAULT_TTC_MODEL = "bear-2";
+var DEFAULT_TTC_AGGRESSIVENESS = 0.2;
+var PROTECTED_TEXT_PATTERN = /<ttc_safe>[\s\S]*?<\/ttc_safe>|<usagetap_safe>[\s\S]*?<\/usagetap_safe>/g;
+function protectPromptText(text) {
+  return `<ttc_safe>${text}</ttc_safe>`;
+}
+var protect = protectPromptText;
+async function compressPrompt(options) {
+  try {
+    if (options.provider === "thetokencompany" || options.tokenCompanyApiKey) {
+      return await compressWithTheTokenCompany(options);
+    }
+    if (options.provider === "toon") {
+      return compressPromptToon(options.input);
+    }
+    return compressPromptHeuristic(options.input);
+  } catch (error) {
+    if (options.failOpen === false) {
+      throw error;
+    }
+    return createPromptCompressionFallback(
+      options.input,
+      options.provider ?? (options.tokenCompanyApiKey ? "thetokencompany" : "heuristic"),
+      error
+    );
+  }
+}
+function compressPromptHeuristic(input) {
+  const original = stableStringifyInput(input);
+  const techniques = /* @__PURE__ */ new Set();
+  const compressedInput = compressValue(input, techniques, { allowToonString: false });
+  const compressed = stableStringifyInput(compressedInput);
+  const chosenInput = compressed.length <= original.length ? compressedInput : input;
+  const chosen = compressed.length <= original.length ? compressed : original;
+  if (!techniques.size) {
+    techniques.add("no-op");
+  }
+  return buildResult(
+    input,
+    chosenInput,
+    "heuristic",
+    original,
+    chosen,
+    Array.from(techniques)
+  );
+}
+function compressPromptToon(input) {
+  const original = stableStringifyInput(input);
+  const compressedInput = typeof input === "string" ? compressText(input, /* @__PURE__ */ new Set(), { allowToonString: true }) : encodeToon(input);
+  const compressed = stableStringifyInput(compressedInput);
+  return buildResult(input, compressedInput, "toon", original, compressed, [
+    "toon",
+    "json-minify"
+  ]);
+}
+async function compressWithTheTokenCompany(options) {
+  if (!options.tokenCompanyApiKey) {
+    throw new Error(
+      "tokenCompanyApiKey is required when provider is thetokencompany"
+    );
+  }
+  const fetchCandidate = options.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchCandidate !== "function") {
+    throw new Error(
+      "A fetch implementation is required for The Token Company compression"
+    );
+  }
+  const original = stableStringifyInput(options.input);
+  const heuristic = compressPromptHeuristic(options.input);
+  const input = typeof heuristic.compressedInput === "string" ? heuristic.compressedInput : stableStringifyInput(heuristic.compressedInput);
+  const model = options.tokenCompanyModel ?? DEFAULT_TTC_MODEL;
+  const aggressiveness = options.tokenCompanyAggressiveness ?? DEFAULT_TTC_AGGRESSIVENESS;
+  if (typeof aggressiveness !== "number" || !Number.isFinite(aggressiveness) || aggressiveness < 0 || aggressiveness > 1) {
+    throw new Error("tokenCompanyAggressiveness must be between 0.0 and 1.0");
+  }
+  const response = await fetchCandidate(
+    options.tokenCompanyEndpoint ?? DEFAULT_TTC_ENDPOINT,
+    {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${options.tokenCompanyApiKey}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        model,
+        input,
+        compression_settings: { aggressiveness },
+        ...options.tokenCompanyAppId ? { app_id: options.tokenCompanyAppId } : {}
+      }),
+      signal: options.signal
+    }
+  );
+  if (!response.ok) {
+    throw new Error(
+      `The Token Company compression failed with HTTP ${response.status}`
+    );
+  }
+  const payload = await response.json();
+  const tokenCompanyResult = normalizeTheTokenCompanyCompressResponse(payload);
+  const compressedInput = payload.compressedInput ?? payload.compressed ?? tokenCompanyResult?.output ?? payload.output ?? payload.text;
+  if (compressedInput === void 0) {
+    throw new Error("The Token Company response did not include compressed content");
+  }
+  const compressed = stableStringifyInput(compressedInput);
+  const tokenCounts = tokenCompanyResult ? {
+    originalTokens: tokenCompanyResult.input_tokens,
+    compressedTokens: tokenCompanyResult.output_tokens,
+    savedTokens: tokenCompanyResult.tokens_saved
+  } : void 0;
+  return buildResult(
+    options.input,
+    compressedInput,
+    "thetokencompany",
+    original,
+    compressed,
+    [...heuristic.techniques, "thetokencompany"],
+    tokenCounts
+  );
+}
+function normalizeTheTokenCompanyCompressResponse(data) {
+  if (typeof data.output !== "string" || typeof data.output_tokens !== "number") {
+    return void 0;
+  }
+  const inputTokens = typeof data.input_tokens === "number" ? data.input_tokens : data.original_input_tokens;
+  if (typeof inputTokens !== "number") {
+    return void 0;
+  }
+  const tokensSaved = typeof data.tokens_saved === "number" ? data.tokens_saved : inputTokens - data.output_tokens;
+  const compressionRatio = typeof data.compression_ratio === "number" ? data.compression_ratio : data.output_tokens === 0 ? 0 : inputTokens / data.output_tokens;
+  return {
+    output: data.output,
+    output_tokens: data.output_tokens,
+    input_tokens: inputTokens,
+    tokens_saved: tokensSaved,
+    compression_ratio: compressionRatio
+  };
+}
+function createPromptCompressionFallback(input, provider = "heuristic", error) {
+  const original = stableStringifyInput(input);
+  const techniques = ["fallback-original"];
+  if (error) {
+    techniques.push("compression-error");
+  }
+  return buildResult(input, input, provider, original, original, techniques);
+}
+function buildResult(input, compressedInput, provider, original, compressed, techniques, tokenCounts) {
+  const originalCharacters = original.length;
+  const compressedCharacters = compressed.length;
+  const savedCharacters = Math.max(
+    0,
+    originalCharacters - compressedCharacters
+  );
+  const originalTokens = tokenCounts?.originalTokens ?? estimatePromptTokens(original);
+  const compressedTokens = tokenCounts?.compressedTokens ?? estimatePromptTokens(compressed);
+  const savedTokens = Math.max(
+    0,
+    tokenCounts?.savedTokens ?? originalTokens - compressedTokens
+  );
+  return {
+    input,
+    compressedInput,
+    provider,
+    originalCharacters,
+    compressedCharacters,
+    savedCharacters,
+    originalTokens,
+    compressedTokens,
+    savedTokens,
+    tokenSavingsRatio: originalTokens > 0 ? savedTokens / originalTokens : 0,
+    savingsRatio: originalCharacters > 0 ? savedCharacters / originalCharacters : 0,
+    techniques
+  };
+}
+function estimatePromptTokens(input) {
+  const text = typeof input === "string" ? input : stableStringifyInput(input);
+  return text.match(/[\p{L}\p{N}]+|[^\s]/gu)?.length ?? 0;
+}
+function compressValue(value, techniques, options) {
+  if (typeof value === "string") return compressText(value, techniques, options);
+  if (Array.isArray(value)) {
+    techniques.add("json-minify");
+    return value.map((item) => compressValue(item, techniques, options));
+  }
+  if (value && typeof value === "object") {
+    techniques.add("json-minify");
+    return Object.keys(value).reduce((acc, key) => {
+      const child = value[key];
+      if (child !== void 0) {
+        acc[key] = compressValue(child, techniques, options);
+      }
+      return acc;
+    }, {});
+  }
+  return value;
+}
+function compressText(value, techniques, options) {
+  const protectedSpans = [];
+  const text = value.replace(PROTECTED_TEXT_PATTERN, (match) => {
+    const placeholder = `__USAGETAP_PROTECTED_${protectedSpans.length}__`;
+    protectedSpans.push(match);
+    techniques.add("protected-text");
+    return placeholder;
+  });
+  const compressed = compressTextWithoutProtection(text, techniques, options);
+  return protectedSpans.reduce(
+    (output, span, index) => output.replace(`__USAGETAP_PROTECTED_${index}__`, span),
+    compressed
+  );
+}
+function compressTextWithoutProtection(value, techniques, options) {
+  const fencePattern = /```([\w-]+)?\n([\s\S]*?)```/g;
+  const parts = [];
+  let cursor = 0;
+  let match;
+  while ((match = fencePattern.exec(value)) !== null) {
+    const before = value.slice(cursor, match.index);
+    const compressedBefore = compressPlainTextAndEmbeddedJson(
+      before,
+      techniques,
+      options
+    );
+    if (compressedBefore) parts.push(compressedBefore);
+    const lang = match[1]?.toLowerCase();
+    const code = cleanCodeBlock(match[2] ?? "");
+    const compressedCode = lang === "json" ? compressJsonText(code, techniques, options) : void 0;
+    if (compressedCode?.format === "toon") {
+      parts.push(`\`\`\`toon
+${compressedCode.text}
+\`\`\``);
+    } else if (compressedCode?.format === "json") {
+      parts.push(`\`\`\`json
+${compressedCode.text}
+\`\`\``);
+    } else {
+      if (code !== match[2]) {
+        techniques.add("code-whitespace");
+      }
+      parts.push(lang ? `\`\`\`${lang}
+${code}
+\`\`\`` : `\`\`\`
+${code}
+\`\`\``);
+    }
+    cursor = match.index + match[0].length;
+  }
+  const after = compressPlainTextAndEmbeddedJson(value.slice(cursor), techniques, options);
+  if (after) parts.push(after);
+  return parts.join("\n").trim();
+}
+function compressPlainText(value, techniques) {
+  const compressed = value.split("\n").map((line) => line.trim()).filter((line) => line).join("\n").replace(/[ \t]{2,}/g, " ").trim();
+  if (compressed !== value.trim()) {
+    techniques.add("text-whitespace");
+  }
+  return compressed;
+}
+function compressPlainTextAndEmbeddedJson(value, techniques, options) {
+  const normalized = compressPlainText(value, techniques);
+  return compressEmbeddedJson(normalized, techniques, options);
+}
+function cleanCodeBlock(code) {
+  const lines = code.replace(/\r\n/g, "\n").split("\n");
+  while (lines.length && lines[0].trim() === "") lines.shift();
+  while (lines.length && lines[lines.length - 1].trim() === "") lines.pop();
+  const commonIndent = lines.filter((line) => line.trim()).reduce((min, line) => {
+    const indent = /^[ \t]*/.exec(line)?.[0].length ?? 0;
+    return min === void 0 ? indent : Math.min(min, indent);
+  }, void 0);
+  return lines.map((line) => commonIndent ? line.slice(commonIndent) : line).join("\n").replace(/[ \t]+$/gm, "");
+}
+function stableStringifyInput(input) {
+  if (typeof input === "string") return input;
+  return JSON.stringify(input) ?? String(input);
+}
+function compressJsonText(text, techniques, options) {
+  const parsed = safeParseJson(text);
+  if (parsed === void 0) {
+    return void 0;
+  }
+  const compactJson = JSON.stringify(parsed);
+  const candidates = [
+    { format: "json", text: compactJson }
+  ];
+  if (options.allowToonString || shouldUseToonForJson(parsed)) {
+    candidates.push({ format: "toon", text: encodeToon(parsed) });
+  }
+  const originalLength = text.trim().length;
+  const best = candidates.reduce(
+    (winner, candidate) => candidate.text.length < winner.text.length ? candidate : winner
+  );
+  if (best.text.length >= originalLength) {
+    return void 0;
+  }
+  techniques.add(best.format === "toon" ? "embedded-json-toon" : "embedded-json-minify");
+  return best;
+}
+function compressEmbeddedJson(text, techniques, options) {
+  let result = "";
+  let cursor = 0;
+  while (cursor < text.length) {
+    const start = findNextJsonStart(text, cursor);
+    if (start < 0) {
+      result += text.slice(cursor);
+      break;
+    }
+    result += text.slice(cursor, start);
+    const span = findBalancedJsonSpan(text, start);
+    if (!span) {
+      result += text[start];
+      cursor = start + 1;
+      continue;
+    }
+    const candidate = compressJsonText(span.text, techniques, options);
+    if (candidate) {
+      result += candidate.text;
+    } else {
+      result += span.text;
+    }
+    cursor = span.end;
+  }
+  return result;
+}
+function findNextJsonStart(text, from) {
+  const objectStart = text.indexOf("{", from);
+  const arrayStart = text.indexOf("[", from);
+  if (objectStart < 0) return arrayStart;
+  if (arrayStart < 0) return objectStart;
+  return Math.min(objectStart, arrayStart);
+}
+function findBalancedJsonSpan(text, start) {
+  const opener = text[start];
+  const closer = opener === "{" ? "}" : opener === "[" ? "]" : void 0;
+  if (!closer) return void 0;
+  const stack = [closer];
+  let inString = false;
+  let escaped = false;
+  for (let index = start + 1; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{" || char === "[") {
+      stack.push(char === "{" ? "}" : "]");
+      continue;
+    }
+    if (char === stack[stack.length - 1]) {
+      stack.pop();
+      if (!stack.length) {
+        const end = index + 1;
+        return { text: text.slice(start, end), end };
+      }
+    }
+  }
+  return void 0;
+}
+function safeParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function shouldUseToonForJson(value) {
+  if (Array.isArray(value)) {
+    return isUniformObjectArray(value) || value.some(shouldUseToonForJson);
+  }
+  if (isPlainObject(value)) {
+    return Object.values(value).some(shouldUseToonForJson);
+  }
+  return false;
+}
+function encodeToon(value, indent = 0) {
+  if (isPrimitive(value)) {
+    return scalarToToon(value);
+  }
+  if (Array.isArray(value)) {
+    return encodeArrayToon(value, indent);
+  }
+  if (isPlainObject(value)) {
+    const lines = [];
+    for (const [key, child] of Object.entries(value)) {
+      lines.push(...encodePropertyToon(key, child, indent));
+    }
+    return lines.join("\n");
+  }
+  return scalarToToon(String(value));
+}
+function encodePropertyToon(key, value, indent) {
+  const prefix = " ".repeat(indent);
+  const toonKey = keyToToon(key);
+  if (isPrimitive(value)) {
+    return [`${prefix}${toonKey}: ${scalarToToon(value)}`];
+  }
+  if (Array.isArray(value)) {
+    if (value.every(isPrimitive)) {
+      return [`${prefix}${toonKey}[${value.length}]: ${value.map(scalarToToon).join(",")}`];
+    }
+    if (isUniformObjectArray(value)) {
+      const fields = Object.keys(value[0]);
+      const header = `${prefix}${toonKey}[${value.length}]{${fields.map(keyToToon).join(",")}}:`;
+      const rows = value.map(
+        (item) => `${" ".repeat(indent + 2)}${fields.map(
+          (field) => scalarToToon(item[field])
+        ).join(",")}`
+      );
+      return [header, ...rows];
+    }
+    return [
+      `${prefix}${toonKey}[${value.length}]:`,
+      ...value.flatMap((item, index) => {
+        if (isPrimitive(item)) {
+          return [`${" ".repeat(indent + 2)}- ${scalarToToon(item)}`];
+        }
+        return [
+          `${" ".repeat(indent + 2)}- item${index}:`,
+          ...encodeToon(item, indent + 4).split("\n")
+        ];
+      })
+    ];
+  }
+  return [`${prefix}${toonKey}:`, ...encodeToon(value, indent + 2).split("\n")];
+}
+function encodeArrayToon(value, indent) {
+  if (value.every(isPrimitive)) {
+    return `[${value.length}]: ${value.map(scalarToToon).join(",")}`;
+  }
+  if (isUniformObjectArray(value)) {
+    const fields = Object.keys(value[0]);
+    return [
+      `[${value.length}]{${fields.map(keyToToon).join(",")}}:`,
+      ...value.map(
+        (item) => `${" ".repeat(indent + 2)}${fields.map(
+          (field) => scalarToToon(item[field])
+        ).join(",")}`
+      )
+    ].join("\n");
+  }
+  return value.flatMap((item, index) => [
+    `${" ".repeat(indent)}- item${index}:`,
+    ...encodeToon(item, indent + 2).split("\n")
+  ]).join("\n");
+}
+function isUniformObjectArray(value) {
+  if (!value.length || !value.every(isPlainObject)) {
+    return false;
+  }
+  const fields = Object.keys(value[0]);
+  if (!fields.length) {
+    return false;
+  }
+  return value.every((item) => {
+    const record = item;
+    const itemFields = Object.keys(record);
+    return itemFields.length === fields.length && fields.every((field) => itemFields.includes(field) && isPrimitive(record[field]));
+  });
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPrimitive(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function keyToToon(key) {
+  return /^[A-Za-z_][A-Za-z0-9_-]*$/.test(key) ? key : JSON.stringify(key);
+}
+function scalarToToon(value) {
+  if (value === null) return "null";
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  const text = String(value);
+  if (text && !/^(true|false|null|-?\d+(?:\.\d+)?)$/i.test(text) && /^[A-Za-z0-9_./@-]+(?: [A-Za-z0-9_./@-]+)*$/.test(text)) {
+    return text;
+  }
+  return JSON.stringify(text);
+}
+
 // src/client.ts
 var CALL_BEGIN_PATH = "call_begin";
 var CALL_END_PATH = "call_end";
+var COMPRESS_PROMPT_PATH = "compress_prompt";
 var CHECK_USAGE_PATH = "customers/{customerId}/usage";
 var CREATE_CUSTOMER_PATH = "customers";
 var CHANGE_PLAN_PATH = "customers/{customerId}/change_plan";
@@ -129,7 +620,7 @@ var IDEMPOTENCY_HEADER = "idempotency-key";
 var SDK_HEADER = "x-usage-sdk";
 var USER_AGENT = "UsageTapClient";
 var CANONICAL_MEDIA_TYPE = "application/vnd.usagetap.v1+json";
-var SDK_VERSION = "0.10.0" ;
+var SDK_VERSION = "1.1.0" ;
 var HAS_WINDOW = typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
 var UsageTapClient = class {
   apiKey;
@@ -144,6 +635,11 @@ var UsageTapClient = class {
   metricFn;
   authHeader;
   autoIdempotency;
+  tokenCompanyApiKey;
+  tokenCompanyEndpoint;
+  tokenCompanyModel;
+  tokenCompanyAggressiveness;
+  tokenCompanyAppId;
   constructor(options) {
     if (!options) {
       throw new UsageTapError(
@@ -189,6 +685,11 @@ var UsageTapClient = class {
     this.metricFn = options.onUsageMetric;
     this.authHeader = options.useApiKeyHeader ? API_KEY_HEADER : AUTH_HEADER;
     this.autoIdempotency = options.autoIdempotency ?? true;
+    this.tokenCompanyApiKey = options.tokenCompanyApiKey;
+    this.tokenCompanyEndpoint = options.tokenCompanyEndpoint;
+    this.tokenCompanyModel = options.tokenCompanyModel;
+    this.tokenCompanyAggressiveness = options.tokenCompanyAggressiveness;
+    this.tokenCompanyAppId = options.tokenCompanyAppId;
   }
   async beginCall(request, options = {}) {
     const idempotencyKey = request.idempotencyKey ?? request.idempotency ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
@@ -211,6 +712,70 @@ var UsageTapClient = class {
     );
     return response;
   }
+  async promptCompress(request, options = {}) {
+    if (!request?.callId) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "promptCompress requires callId"
+      );
+    }
+    const result = await this.compressPromptInput(request.input, {
+      provider: request.provider,
+      tokenCompanyModel: request.tokenCompanyModel,
+      tokenCompanyAggressiveness: request.tokenCompanyAggressiveness,
+      tokenCompanyAppId: request.tokenCompanyAppId,
+      signal: options.signal
+    });
+    try {
+      await this.recordPromptCompression(
+        {
+          callId: request.callId,
+          promptCompression: this.toPromptCompressionTelemetry(result)
+        },
+        options
+      );
+      return { ...result, callId: request.callId };
+    } catch (error) {
+      return {
+        ...createPromptCompressionFallback(
+          request.input,
+          request.provider ?? result.provider,
+          error
+        ),
+        callId: request.callId
+      };
+    }
+  }
+  async compressPromptInput(input, options = {}) {
+    return compressPrompt({
+      input,
+      provider: options.provider,
+      tokenCompanyApiKey: this.tokenCompanyApiKey,
+      tokenCompanyEndpoint: this.tokenCompanyEndpoint,
+      tokenCompanyModel: options.tokenCompanyModel ?? this.tokenCompanyModel,
+      tokenCompanyAggressiveness: options.tokenCompanyAggressiveness ?? this.tokenCompanyAggressiveness,
+      tokenCompanyAppId: options.tokenCompanyAppId ?? this.tokenCompanyAppId,
+      fetchImpl: this.fetchImpl,
+      signal: options.signal,
+      failOpen: options.failOpen
+    });
+  }
+  async recordPromptCompression(request, options = {}) {
+    if (!request?.callId) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "recordPromptCompression requires callId"
+      );
+    }
+    return this.request(
+      COMPRESS_PROMPT_PATH,
+      {
+        callId: request.callId,
+        promptCompression: request.promptCompression
+      },
+      options
+    );
+  }
   async endCall(request, options = {}) {
     if (!request?.callId) {
       throw new UsageTapError(
@@ -435,6 +1000,20 @@ var UsageTapClient = class {
     }
     return handlerResult;
   }
+  toPromptCompressionTelemetry(result) {
+    return {
+      provider: result.provider,
+      originalCharacters: result.originalCharacters,
+      compressedCharacters: result.compressedCharacters,
+      savedCharacters: result.savedCharacters,
+      originalTokens: result.originalTokens,
+      compressedTokens: result.compressedTokens,
+      savedTokens: result.savedTokens,
+      tokenSavingsRatio: result.tokenSavingsRatio,
+      savingsRatio: result.savingsRatio,
+      techniques: result.techniques
+    };
+  }
   async request(path, payload, options) {
     const url = new URL(path, this.baseUrl).toString();
     const body = payload !== void 0 ? JSON.stringify(payload) : void 0;
@@ -1024,8 +1603,14 @@ async function finalizeCall(callState, usageTap, error, usage) {
 
 exports.UsageTapClient = UsageTapClient;
 exports.UsageTapError = UsageTapError;
+exports.compressPrompt = compressPrompt;
+exports.compressPromptHeuristic = compressPromptHeuristic;
+exports.compressPromptToon = compressPromptToon;
 exports.createIdempotencyKey = createIdempotencyKey;
+exports.estimatePromptTokens = estimatePromptTokens;
 exports.isUsageTapError = isUsageTapError;
+exports.protect = protect;
+exports.protectPromptText = protectPromptText;
 exports.wrapFetch = wrapFetch;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map