@usagetap/sdk 1.1.0 → 1.3.1

package/dist/index.cjs

@@ -119,26 +119,32 @@ async function runWithRetry(operation, options, shouldRetry, onSchedule, signal)
 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
     );
@@ -172,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(
@@ -184,41 +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.usageTapCompressionMessagesEndpoint ?? DEFAULT_USAGETAP_MESSAGES_COMPRESSION_ENDPOINT,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        ...cloneInputRecord(options.input),
+        compression_settings: { aggressiveness }
+      }),
+      signal: options.signal
+    }
+  );
+  if (!response.ok) {
+    throw new Error(
+      `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);
-  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");
+  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(
-    options.tokenCompanyEndpoint ?? DEFAULT_TTC_ENDPOINT,
+    endpoint,
     {
       method: "POST",
-      headers: {
-        authorization: `Bearer ${options.tokenCompanyApiKey}`,
-        "content-type": "application/json"
-      },
+      headers,
       body: JSON.stringify({
         model,
         input,
+        ...provider === "usagetap" ? { text: input } : {},
         compression_settings: { aggressiveness },
-        ...options.tokenCompanyAppId ? { app_id: options.tokenCompanyAppId } : {}
+        ...appId ? { app_id: appId } : {}
       }),
       signal: options.signal
     }
   );
   if (!response.ok) {
     throw new Error(
-      `The Token Company compression failed with HTTP ${response.status}`
+      `${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 ? {
@@ -227,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;
@@ -620,7 +770,8 @@ 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.1.0" ;
+var DEFAULT_BASE_URL = "https://api.usagetap.com";
+var SDK_VERSION = "1.3.1" ;
 var HAS_WINDOW = typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
 var UsageTapClient = class {
   apiKey;
@@ -637,26 +788,23 @@ var UsageTapClient = class {
   autoIdempotency;
   tokenCompanyApiKey;
   tokenCompanyEndpoint;
+  model;
   tokenCompanyModel;
+  aggressiveness;
   tokenCompanyAggressiveness;
   tokenCompanyAppId;
-  constructor(options) {
-    if (!options) {
-      throw new UsageTapError(
-        "USAGETAP_BAD_REQUEST",
-        "UsageTapClient options are required"
-      );
-    }
-    if (!options.apiKey) {
-      throw new UsageTapError(
-        "USAGETAP_BAD_REQUEST",
-        "UsageTapClient requires an apiKey"
-      );
-    }
-    if (!options.baseUrl) {
+  usageTapCompressionApiKey;
+  usageTapCompressionEndpoint;
+  usageTapCompressionMessagesEndpoint;
+  usageTapCompressionModel;
+  usageTapCompressionAggressiveness;
+  constructor(options = {}) {
+    const apiKey = options.apiKey?.trim() || readEnvironmentVariable("USAGETAP_API_KEY");
+    const baseUrl = options.baseUrl?.trim() || readEnvironmentVariable("USAGETAP_BASE_URL") || DEFAULT_BASE_URL;
+    if (!apiKey) {
       throw new UsageTapError(
         "USAGETAP_BAD_REQUEST",
-        "UsageTapClient requires a baseUrl"
+        "UsageTapClient requires an apiKey or the USAGETAP_API_KEY environment variable"
       );
     }
     if (HAS_WINDOW && !options.allowBrowser) {
@@ -672,9 +820,9 @@ var UsageTapClient = class {
         "A global fetch implementation was not found. Pass fetchImpl in UsageTapClientOptions."
       );
     }
-    const normalizedBaseUrl = normalizeBaseUrl(options.baseUrl);
+    const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
     this.baseUrl = new URL(normalizedBaseUrl);
-    this.apiKey = options.apiKey;
+    this.apiKey = apiKey;
     this.fetchImpl = wrapFetchImplementation(fetchCandidate, !options.fetchImpl);
     this.defaultFeature = options.defaultFeature;
     this.defaultTags = options.defaultTags?.length ? dedupeStrings(options.defaultTags) : void 0;
@@ -687,9 +835,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 ?? 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);
@@ -719,11 +874,22 @@ var UsageTapClient = class {
         "promptCompress requires callId"
       );
     }
-    const result = await this.compressPromptInput(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,
+      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 {
@@ -738,7 +904,7 @@ var UsageTapClient = class {
     } catch (error) {
       return {
         ...createPromptCompressionFallback(
-          request.input,
+          requestInput,
           request.provider ?? result.provider,
           error
         ),
@@ -752,9 +918,52 @@ var UsageTapClient = class {
       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
+    });
+  }
+  /**
+   * Compress text with UsageTap's hosted compression service.
+   *
+   * This is the short, standalone path. It does not create a metered call and
+   * fails open to the original text unless failOpen is explicitly disabled.
+   */
+  async compress(text, options = {}) {
+    if (typeof text !== "string") {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "compress requires text"
+      );
+    }
+    const result = await this.compressPromptInput(text, {
+      ...options,
+      provider: "usagetap"
+    });
+    const output = typeof result.compressedInput === "string" ? result.compressedInput : text;
+    return {
+      ...result,
+      compressedInput: output,
+      output
+    };
+  }
+  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
@@ -1000,6 +1209,14 @@ var UsageTapClient = class {
     }
     return handlerResult;
   }
+  /**
+   * Meter one operation. Pass only a customer ID for the common path, or the
+   * existing begin-call request object when feature, tags, or entitlements are needed.
+   */
+  async meter(request, handler, options = {}) {
+    const beginRequest = typeof request === "string" ? { customerId: request } : request;
+    return this.withUsage(beginRequest, handler, options);
+  }
   toPromptCompressionTelemetry(result) {
     return {
       provider: result.provider,
@@ -1312,6 +1529,11 @@ function sanitizeDetails(payload) {
   if (payload.error) details.error = payload.error;
   return Object.keys(details).length ? details : void 0;
 }
+function readEnvironmentVariable(name) {
+  const runtime = globalThis;
+  const value = runtime.process?.env?.[name]?.trim();
+  return value || void 0;
+}
 function normalizeBaseUrl(baseUrl) {
   const trimmed = baseUrl.trim();
   if (!trimmed) return trimmed;
@@ -1601,10 +1823,12 @@ async function finalizeCall(callState, usageTap, error, usage) {
   }
 }
 
+exports.UsageTap = UsageTapClient;
 exports.UsageTapClient = UsageTapClient;
 exports.UsageTapError = UsageTapError;
 exports.compressPrompt = compressPrompt;
 exports.compressPromptHeuristic = compressPromptHeuristic;
+exports.compressPromptMessages = compressPromptMessages;
 exports.compressPromptToon = compressPromptToon;
 exports.createIdempotencyKey = createIdempotencyKey;
 exports.estimatePromptTokens = estimatePromptTokens;