@usagetap/sdk 1.0.0 → 1.2.0

package/dist/index.cjs

@@ -117,21 +117,34 @@ async function runWithRetry(operation, options, shouldRetry, onSchedule, signal)
 
 // 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 DEFAULT_USAGETAP_COMPRESSION_ENDPOINT = "https://compress.usagetap.com/v1/compress";
+var DEFAULT_USAGETAP_MESSAGES_COMPRESSION_ENDPOINT = "https://compress.usagetap.com/v1/messages/compress";
+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) {
+  const input = resolvePromptCompressionInput(options);
   try {
+    if (options.provider === "usagetap") {
+      return await compressWithUsageTap(options);
+    }
     if (options.provider === "thetokencompany" || options.tokenCompanyApiKey) {
       return await compressWithTheTokenCompany(options);
     }
     if (options.provider === "toon") {
-      return compressPromptToon(options.input);
+      return compressPromptToon(input);
     }
-    return compressPromptHeuristic(options.input);
+    return compressPromptHeuristic(input);
   } catch (error) {
     if (options.failOpen === false) {
       throw error;
     }
     return createPromptCompressionFallback(
-      options.input,
+      input,
       options.provider ?? (options.tokenCompanyApiKey ? "thetokencompany" : "heuristic"),
       error
     );
@@ -165,6 +178,20 @@ function compressPromptToon(input) {
     "json-minify"
   ]);
 }
+async function compressPromptMessages(options) {
+  try {
+    return await compressMessagesWithUsageTap(options);
+  } catch (error) {
+    if (options.failOpen === false) {
+      throw error;
+    }
+    return createPromptCompressionFallback(
+      options.input,
+      options.provider ?? "usagetap",
+      error
+    );
+  }
+}
 async function compressWithTheTokenCompany(options) {
   if (!options.tokenCompanyApiKey) {
     throw new Error(
@@ -177,30 +204,131 @@ async function compressWithTheTokenCompany(options) {
       "A fetch implementation is required for The Token Company compression"
     );
   }
+  return compressWithCompatibleRemoteProvider({
+    options,
+    provider: "thetokencompany",
+    endpoint: options.tokenCompanyEndpoint ?? DEFAULT_TTC_ENDPOINT,
+    model: options.model ?? options.tokenCompanyModel ?? DEFAULT_TTC_MODEL,
+    aggressiveness: options.aggressiveness ?? options.tokenCompanyAggressiveness ?? DEFAULT_TTC_AGGRESSIVENESS,
+    apiKey: options.tokenCompanyApiKey,
+    appId: options.tokenCompanyAppId,
+    providerLabel: "The Token Company"
+  });
+}
+async function compressWithUsageTap(options) {
+  const fetchCandidate = options.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchCandidate !== "function") {
+    throw new Error(
+      "A fetch implementation is required for UsageTap prompt compression"
+    );
+  }
+  return compressWithCompatibleRemoteProvider({
+    options,
+    provider: "usagetap",
+    endpoint: options.usageTapCompressionEndpoint ?? DEFAULT_USAGETAP_COMPRESSION_ENDPOINT,
+    model: options.model ?? options.usageTapCompressionModel ?? options.tokenCompanyModel ?? DEFAULT_TTC_MODEL,
+    aggressiveness: options.aggressiveness ?? options.usageTapCompressionAggressiveness ?? options.tokenCompanyAggressiveness ?? DEFAULT_TTC_AGGRESSIVENESS,
+    apiKey: options.usageTapCompressionApiKey,
+    appId: options.tokenCompanyAppId,
+    providerLabel: "UsageTap prompt compression"
+  });
+}
+async function compressMessagesWithUsageTap(options) {
+  const fetchCandidate = options.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchCandidate !== "function") {
+    throw new Error(
+      "A fetch implementation is required for UsageTap prompt message compression"
+    );
+  }
+  const aggressiveness = options.aggressiveness ?? options.usageTapCompressionAggressiveness ?? DEFAULT_TTC_AGGRESSIVENESS;
+  validateAggressiveness(
+    aggressiveness,
+    "UsageTap prompt message compression"
+  );
   const original = stableStringifyInput(options.input);
-  const heuristic = compressPromptHeuristic(options.input);
+  const headers = {
+    "content-type": "application/json"
+  };
+  if (options.usageTapCompressionApiKey) {
+    headers.authorization = `Bearer ${options.usageTapCompressionApiKey}`;
+  }
   const response = await fetchCandidate(
-    options.tokenCompanyEndpoint ?? DEFAULT_TTC_ENDPOINT,
+    options.usageTapCompressionMessagesEndpoint ?? DEFAULT_USAGETAP_MESSAGES_COMPRESSION_ENDPOINT,
     {
       method: "POST",
-      headers: {
-        authorization: `Bearer ${options.tokenCompanyApiKey}`,
-        "content-type": "application/json"
-      },
-      body: JSON.stringify({ input: heuristic.compressedInput }),
+      headers,
+      body: JSON.stringify({
+        ...cloneInputRecord(options.input),
+        compression_settings: { aggressiveness }
+      }),
       signal: options.signal
     }
   );
   if (!response.ok) {
     throw new Error(
-      `The Token Company compression failed with HTTP ${response.status}`
+      `UsageTap prompt message compression failed with HTTP ${response.status}`
+    );
+  }
+  const payload = await response.json();
+  const compressedInput = payload.compressed_request ?? payload.compressedInput ?? payload.compressed ?? (payload.messages !== void 0 ? { ...cloneInputRecord(options.input), messages: payload.messages } : void 0);
+  if (compressedInput === void 0) {
+    throw new Error(
+      "UsageTap prompt message compression response did not include compressed content"
+    );
+  }
+  const compressed = stableStringifyInput(compressedInput);
+  const tokenCounts = normalizeCompatibleTokenCounts(payload);
+  return buildResult(
+    options.input,
+    compressedInput,
+    "usagetap",
+    original,
+    compressed,
+    ["usagetap", "messages-endpoint"],
+    tokenCounts
+  );
+}
+async function compressWithCompatibleRemoteProvider(args) {
+  const { options, provider, endpoint, model, aggressiveness, apiKey, appId, providerLabel } = args;
+  const fetchCandidate = options.fetchImpl ?? globalThis.fetch;
+  const sourceInput = resolvePromptCompressionInput(options);
+  const original = stableStringifyInput(sourceInput);
+  const heuristic = compressPromptHeuristic(sourceInput);
+  const input = typeof heuristic.compressedInput === "string" ? heuristic.compressedInput : stableStringifyInput(heuristic.compressedInput);
+  if (!isValidAggressiveness(aggressiveness)) {
+    throw new Error(`${providerLabel} aggressiveness must be between 0.0 and 1.0`);
+  }
+  const headers = {
+    "content-type": "application/json"
+  };
+  if (apiKey) {
+    headers.authorization = `Bearer ${apiKey}`;
+  }
+  const response = await fetchCandidate(
+    endpoint,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        model,
+        input,
+        ...provider === "usagetap" ? { text: input } : {},
+        compression_settings: { aggressiveness },
+        ...appId ? { app_id: appId } : {}
+      }),
+      signal: options.signal
+    }
+  );
+  if (!response.ok) {
+    throw new Error(
+      `${providerLabel} 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");
+    throw new Error(`${providerLabel} response did not include compressed content`);
   }
   const compressed = stableStringifyInput(compressedInput);
   const tokenCounts = tokenCompanyResult ? {
@@ -209,15 +337,55 @@ async function compressWithTheTokenCompany(options) {
     savedTokens: tokenCompanyResult.tokens_saved
   } : void 0;
   return buildResult(
-    options.input,
+    sourceInput,
     compressedInput,
-    "thetokencompany",
+    provider,
     original,
     compressed,
-    [...heuristic.techniques, "thetokencompany"],
+    [...heuristic.techniques, provider],
     tokenCounts
   );
 }
+function resolvePromptCompressionInput(options) {
+  if (options.input !== void 0) {
+    return options.input;
+  }
+  if (options.text !== void 0) {
+    return options.text;
+  }
+  throw new Error("Prompt compression requires input or text");
+}
+function validateAggressiveness(value, label) {
+  if (typeof value === "number") {
+    if (!isValidAggressiveness(value)) {
+      throw new Error(`${label} aggressiveness must be between 0.0 and 1.0`);
+    }
+    return;
+  }
+  for (const aggressiveness of Object.values(value)) {
+    if (aggressiveness !== void 0 && !isValidAggressiveness(aggressiveness)) {
+      throw new Error(`${label} aggressiveness must be between 0.0 and 1.0`);
+    }
+  }
+}
+function isValidAggressiveness(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+function cloneInputRecord(input) {
+  return input && typeof input === "object" && !Array.isArray(input) ? { ...input } : { input };
+}
+function normalizeCompatibleTokenCounts(data) {
+  const inputTokens = typeof data.input_tokens === "number" ? data.input_tokens : data.original_input_tokens;
+  const outputTokens = data.output_tokens;
+  if (typeof inputTokens !== "number" || typeof outputTokens !== "number") {
+    return void 0;
+  }
+  return {
+    originalTokens: inputTokens,
+    compressedTokens: outputTokens,
+    savedTokens: typeof data.tokens_saved === "number" ? data.tokens_saved : inputTokens - outputTokens
+  };
+}
 function normalizeTheTokenCompanyCompressResponse(data) {
   if (typeof data.output !== "string" || typeof data.output_tokens !== "number") {
     return void 0;
@@ -295,6 +463,20 @@ function compressValue(value, techniques, options) {
   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;
@@ -588,7 +770,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 = "1.0.0" ;
+var SDK_VERSION = "1.2.0" ;
 var HAS_WINDOW = typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
 var UsageTapClient = class {
   apiKey;
@@ -605,6 +787,16 @@ var UsageTapClient = class {
   autoIdempotency;
   tokenCompanyApiKey;
   tokenCompanyEndpoint;
+  model;
+  tokenCompanyModel;
+  aggressiveness;
+  tokenCompanyAggressiveness;
+  tokenCompanyAppId;
+  usageTapCompressionApiKey;
+  usageTapCompressionEndpoint;
+  usageTapCompressionMessagesEndpoint;
+  usageTapCompressionModel;
+  usageTapCompressionAggressiveness;
   constructor(options) {
     if (!options) {
       throw new UsageTapError(
@@ -652,6 +844,16 @@ var UsageTapClient = class {
     this.autoIdempotency = options.autoIdempotency ?? true;
     this.tokenCompanyApiKey = options.tokenCompanyApiKey;
     this.tokenCompanyEndpoint = options.tokenCompanyEndpoint;
+    this.model = options.model;
+    this.tokenCompanyModel = options.tokenCompanyModel;
+    this.aggressiveness = options.aggressiveness;
+    this.tokenCompanyAggressiveness = options.tokenCompanyAggressiveness;
+    this.tokenCompanyAppId = options.tokenCompanyAppId;
+    this.usageTapCompressionApiKey = options.usageTapCompressionApiKey ?? options.apiKey;
+    this.usageTapCompressionEndpoint = options.usageTapCompressionEndpoint;
+    this.usageTapCompressionMessagesEndpoint = options.usageTapCompressionMessagesEndpoint;
+    this.usageTapCompressionModel = options.usageTapCompressionModel;
+    this.usageTapCompressionAggressiveness = options.usageTapCompressionAggressiveness;
   }
   async beginCall(request, options = {}) {
     const idempotencyKey = request.idempotencyKey ?? request.idempotency ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
@@ -681,17 +883,26 @@ var UsageTapClient = class {
         "promptCompress requires callId"
       );
     }
-    const result = await compressPrompt({
-      input: request.input,
+    const requestInput = request.input ?? request.text;
+    if (requestInput === void 0) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "promptCompress requires input or text"
+      );
+    }
+    const result = await this.compressPromptInput(requestInput, {
       provider: request.provider,
-      tokenCompanyApiKey: this.tokenCompanyApiKey,
-      tokenCompanyEndpoint: this.tokenCompanyEndpoint,
-      fetchImpl: this.fetchImpl,
+      model: request.model,
+      tokenCompanyModel: request.tokenCompanyModel,
+      aggressiveness: request.aggressiveness,
+      tokenCompanyAggressiveness: request.tokenCompanyAggressiveness,
+      tokenCompanyAppId: request.tokenCompanyAppId,
+      usageTapCompressionModel: request.usageTapCompressionModel,
+      usageTapCompressionAggressiveness: request.usageTapCompressionAggressiveness,
       signal: options.signal
     });
     try {
-      await this.request(
-        COMPRESS_PROMPT_PATH,
+      await this.recordPromptCompression(
         {
           callId: request.callId,
           promptCompression: this.toPromptCompressionTelemetry(result)
@@ -702,7 +913,7 @@ var UsageTapClient = class {
     } catch (error) {
       return {
         ...createPromptCompressionFallback(
-          request.input,
+          requestInput,
           request.provider ?? result.provider,
           error
         ),
@@ -710,6 +921,55 @@ var UsageTapClient = class {
       };
     }
   }
+  async compressPromptInput(input, options = {}) {
+    return compressPrompt({
+      input,
+      provider: options.provider,
+      tokenCompanyApiKey: this.tokenCompanyApiKey,
+      tokenCompanyEndpoint: this.tokenCompanyEndpoint,
+      model: options.model ?? this.model,
+      tokenCompanyModel: options.tokenCompanyModel ?? this.tokenCompanyModel,
+      aggressiveness: options.aggressiveness ?? this.aggressiveness,
+      tokenCompanyAggressiveness: options.tokenCompanyAggressiveness ?? this.tokenCompanyAggressiveness,
+      tokenCompanyAppId: options.tokenCompanyAppId ?? this.tokenCompanyAppId,
+      usageTapCompressionApiKey: this.usageTapCompressionApiKey,
+      usageTapCompressionEndpoint: this.usageTapCompressionEndpoint,
+      usageTapCompressionModel: options.usageTapCompressionModel ?? this.usageTapCompressionModel,
+      usageTapCompressionAggressiveness: options.usageTapCompressionAggressiveness ?? this.usageTapCompressionAggressiveness,
+      fetchImpl: this.fetchImpl,
+      signal: options.signal,
+      failOpen: options.failOpen
+    });
+  }
+  async compressPromptMessages(input, options = {}) {
+    return compressPromptMessages({
+      input,
+      provider: options.provider ?? "usagetap",
+      usageTapCompressionApiKey: this.usageTapCompressionApiKey,
+      usageTapCompressionMessagesEndpoint: this.usageTapCompressionMessagesEndpoint,
+      aggressiveness: options.aggressiveness ?? this.aggressiveness,
+      usageTapCompressionAggressiveness: options.usageTapCompressionAggressiveness ?? this.usageTapCompressionAggressiveness,
+      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(
@@ -1539,10 +1799,13 @@ exports.UsageTapClient = UsageTapClient;
 exports.UsageTapError = UsageTapError;
 exports.compressPrompt = compressPrompt;
 exports.compressPromptHeuristic = compressPromptHeuristic;
+exports.compressPromptMessages = compressPromptMessages;
 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