@tollara/service-sdk 0.0.1

package/dist/index.js

@@ -0,0 +1,877 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CompletionStatus: () => CompletionStatus,
+  DEFAULT_API_URL: () => DEFAULT_API_URL,
+  DEFAULT_CORE_PATH_PREFIX: () => DEFAULT_CORE_PATH_PREFIX,
+  DEFAULT_GATEWAY_PATH_PREFIX: () => DEFAULT_GATEWAY_PATH_PREFIX,
+  DEFAULT_USAGE_PATH_PREFIX: () => DEFAULT_USAGE_PATH_PREFIX,
+  ENV_API_URL: () => ENV_API_URL,
+  ENV_SERVICE_ID: () => ENV_SERVICE_ID,
+  ENV_SERVICE_SECRET: () => ENV_SERVICE_SECRET,
+  TollaraClient: () => TollaraClient,
+  TollaraHeaders: () => TollaraHeaders,
+  buildGatewayUserContextString: () => buildGatewayUserContextString,
+  buildGatewayUserContextStringV2: () => buildGatewayUserContextStringV2,
+  buildUsageReportUrl: () => buildUsageReportUrl,
+  calculateHmac: () => calculateHmac,
+  calculateHmacWithTimestamp: () => calculateHmacWithTimestamp,
+  constantTimeEquals: () => constantTimeEquals,
+  createValidationCache: () => createValidationCache,
+  estimateUsage: () => estimateUsage,
+  estimateUsageWithJwt: () => estimateUsageWithJwt,
+  getRequestResult: () => getRequestResult,
+  getRequestStatus: () => getRequestStatus,
+  getUserContext: () => getUserContext,
+  invokeService: () => invokeService,
+  reportCompletion: () => reportCompletion,
+  reportCompletionFull: () => reportCompletionFull,
+  reportCompletionWithResult: () => reportCompletionWithResult,
+  reportProgress: () => reportProgress,
+  reportUsage: () => reportUsage,
+  validateHmacSignature: () => validateHmacSignature,
+  validateServiceKey: () => validateServiceKey,
+  verifyInboundHmac: () => verifyInboundHmac,
+  verifySignature: () => verifySignature,
+  verifySignatureFromHeaders: () => verifySignatureFromHeaders,
+  verifySignatureFromHeadersAndGetUserContext: () => verifySignatureFromHeadersAndGetUserContext
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/tollaraHeaders.ts
+var TollaraHeaders = {
+  SIGNATURE: "X-Tollara-Signature",
+  TIMESTAMP: "X-Tollara-Timestamp",
+  USER_ID: "X-Tollara-User-ID",
+  PLAN: "X-Tollara-Plan",
+  ROLES: "X-Tollara-Roles",
+  QUOTA_REMAINING: "X-Tollara-Quota-Remaining",
+  SUBSCRIPTION_ACTIVE: "X-Tollara-Subscription-Active",
+  BILLING_MODEL: "X-Tollara-Billing-Model",
+  MEASUREMENT_TYPE: "X-Tollara-Measurement-Type",
+  UNIT_LABEL: "X-Tollara-Unit-Label",
+  /** Gateway HMAC user-context schema: `2` = v2 suffix (leading `2`, no quota segment). */
+  SIGNING_VERSION: "X-Tollara-Signing-Version"
+};
+
+// src/hmac.ts
+var import_crypto = require("crypto");
+function calculateHmac(data, key) {
+  const hmac = (0, import_crypto.createHmac)("sha256", key);
+  hmac.update(data, "utf8");
+  return hmac.digest("base64");
+}
+function calculateHmacWithTimestamp(bodyString, timestamp, key) {
+  const ts = typeof timestamp === "number" ? String(timestamp) : timestamp;
+  return calculateHmac(bodyString + ts, key);
+}
+function constantTimeEquals(a, b) {
+  if (a == null || b == null) return a === b;
+  if (a.length !== b.length) return false;
+  try {
+    const bufA = Buffer.from(a, "utf8");
+    const bufB = Buffer.from(b, "utf8");
+    if (bufA.length !== bufB.length) return false;
+    return (0, import_crypto.timingSafeEqual)(bufA, bufB);
+  } catch {
+    return false;
+  }
+}
+function validateHmacSignature(signature, payloadString, key) {
+  if (!signature || !key) return false;
+  try {
+    const expected = calculateHmac(payloadString, key);
+    return constantTimeEquals(expected, signature);
+  } catch {
+    return false;
+  }
+}
+
+// src/verifier.ts
+function headerGet(headers, canonicalName) {
+  const target = canonicalName.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === target) {
+      if (v == null) return null;
+      return Array.isArray(v) ? v[0] ?? null : String(v);
+    }
+  }
+  return null;
+}
+function parseSubscriptionActive(raw) {
+  if (raw == null || raw === "") return false;
+  const t = raw.trim();
+  return t === "true" || t === "1";
+}
+function buildGatewayUserContextString(userId, plan, roles, quotaRemaining, subscriptionActive, billingModelType, measurementType, unitLabel) {
+  const u = userId ?? "";
+  const p = plan ?? "";
+  const r = roles?.length ? roles.join(",") : "";
+  const q = quotaRemaining != null && quotaRemaining !== "" ? String(quotaRemaining) : "";
+  const sub = subscriptionActive ? "true" : "false";
+  const b = billingModelType ?? "";
+  const m = measurementType ?? "";
+  const ul = unitLabel ?? "";
+  return u + p + r + q + sub + b + m + ul;
+}
+function buildGatewayUserContextStringV2(userId, plan, roles, subscriptionActive, billingModelType, measurementType, unitLabel) {
+  const u = userId ?? "";
+  const p = plan ?? "";
+  const r = roles?.length ? roles.join(",") : "";
+  const sub = subscriptionActive ? "true" : "false";
+  const b = billingModelType ?? "";
+  const m = measurementType ?? "";
+  const ul = unitLabel ?? "";
+  return "2" + u + p + r + sub + b + m + ul;
+}
+function verifySignature(serviceSecret, input) {
+  const {
+    signature,
+    timestamp,
+    payload,
+    userId,
+    plan,
+    roles,
+    quotaRemaining,
+    subscriptionActive,
+    billingModelType,
+    measurementType,
+    unitLabel,
+    signingVersion
+  } = input;
+  if (!signature || !timestamp || !serviceSecret) return false;
+  try {
+    const payloadString = payload == null ? "" : typeof payload === "string" ? payload : JSON.stringify(payload);
+    const userContextString = signingVersion === "2" ? buildGatewayUserContextStringV2(
+      userId,
+      plan,
+      roles ?? [],
+      subscriptionActive,
+      billingModelType ?? null,
+      measurementType ?? null,
+      unitLabel ?? null
+    ) : buildGatewayUserContextString(
+      userId,
+      plan,
+      roles ?? [],
+      quotaRemaining,
+      subscriptionActive,
+      billingModelType ?? null,
+      measurementType ?? null,
+      unitLabel ?? null
+    );
+    const dataToSign = payloadString + timestamp + userContextString;
+    const expectedSignature = calculateHmac(dataToSign, serviceSecret);
+    return constantTimeEquals(expectedSignature, signature);
+  } catch {
+    return false;
+  }
+}
+function verifyInboundHmac(serviceSecret, request) {
+  const s = request.signedUserContext;
+  return verifySignature(serviceSecret, {
+    signature: request.signature,
+    timestamp: request.timestamp,
+    payload: request.payload,
+    userId: s.userId,
+    plan: s.plan,
+    roles: s.roles ?? [],
+    quotaRemaining: s.quotaRemaining,
+    subscriptionActive: s.subscriptionActive,
+    billingModelType: s.billingModelType,
+    measurementType: s.measurementType,
+    unitLabel: s.unitLabel,
+    signingVersion: request.signingVersion
+  });
+}
+function verifySignatureFromHeaders(serviceSecret, headers, payload) {
+  const signature = headerGet(headers, TollaraHeaders.SIGNATURE);
+  const timestamp = headerGet(headers, TollaraHeaders.TIMESTAMP);
+  if (!signature || !timestamp) return false;
+  const rolesHeader = headerGet(headers, TollaraHeaders.ROLES);
+  const roles = rolesHeader ? rolesHeader.split(",").map((x) => x.trim()).filter(Boolean) : [];
+  let quotaRemaining = headerGet(headers, TollaraHeaders.QUOTA_REMAINING);
+  if (quotaRemaining != null && quotaRemaining !== "") {
+    const n = Number(quotaRemaining);
+    if (!Number.isNaN(n)) quotaRemaining = n;
+  } else {
+    quotaRemaining = null;
+  }
+  const subRaw = headerGet(headers, TollaraHeaders.SUBSCRIPTION_ACTIVE);
+  const subscriptionActive = parseSubscriptionActive(subRaw);
+  const billing = headerGet(headers, TollaraHeaders.BILLING_MODEL);
+  const measurement = headerGet(headers, TollaraHeaders.MEASUREMENT_TYPE);
+  const unit = headerGet(headers, TollaraHeaders.UNIT_LABEL);
+  const signedUserContext = {
+    userId: headerGet(headers, TollaraHeaders.USER_ID),
+    plan: headerGet(headers, TollaraHeaders.PLAN),
+    roles,
+    quotaRemaining,
+    subscriptionActive,
+    billingModelType: billing && billing !== "" ? billing : null,
+    measurementType: measurement && measurement !== "" ? measurement : null,
+    unitLabel: unit && unit !== "" ? unit : null
+  };
+  const signingVersion = headerGet(headers, TollaraHeaders.SIGNING_VERSION);
+  return verifyInboundHmac(serviceSecret, {
+    signature,
+    timestamp,
+    payload,
+    signedUserContext,
+    signingVersion: signingVersion && signingVersion !== "" ? signingVersion : null
+  });
+}
+function verifySignatureFromHeadersAndGetUserContext(serviceSecret, headers, payload) {
+  if (!verifySignatureFromHeaders(serviceSecret, headers, payload)) return null;
+  return getUserContext(headers);
+}
+function getUserContext(headers) {
+  const rolesHeader = headerGet(headers, TollaraHeaders.ROLES);
+  const roles = rolesHeader ? rolesHeader.split(",").map((s) => s.trim()).filter(Boolean) : [];
+  let quotaRemaining = null;
+  const q = headerGet(headers, TollaraHeaders.QUOTA_REMAINING);
+  if (q != null && q !== "") {
+    const n = Number(q);
+    if (!Number.isNaN(n)) quotaRemaining = n;
+  }
+  const sub = headerGet(headers, TollaraHeaders.SUBSCRIPTION_ACTIVE);
+  const subscriptionActive = parseSubscriptionActive(sub);
+  const bm = headerGet(headers, TollaraHeaders.BILLING_MODEL);
+  const mt = headerGet(headers, TollaraHeaders.MEASUREMENT_TYPE);
+  const ul = headerGet(headers, TollaraHeaders.UNIT_LABEL);
+  return {
+    userId: headerGet(headers, TollaraHeaders.USER_ID),
+    plan: headerGet(headers, TollaraHeaders.PLAN),
+    roles,
+    quotaRemaining,
+    subscriptionActive,
+    billingModelType: bm && bm !== "" ? bm : null,
+    measurementType: mt && mt !== "" ? mt : null,
+    unitLabel: ul && ul !== "" ? ul : null
+  };
+}
+
+// src/constants.ts
+var DEFAULT_API_URL = "https://api.tollara.ai";
+var DEFAULT_CORE_PATH_PREFIX = "/api/v1";
+var DEFAULT_GATEWAY_PATH_PREFIX = "/api";
+var DEFAULT_USAGE_PATH_PREFIX = "/api/usage";
+
+// src/urls.ts
+function trimTrailingSlashes(s) {
+  let t = s.trim();
+  while (t.endsWith("/")) t = t.slice(0, -1);
+  return t;
+}
+function joinUrl(base, path) {
+  const b = trimTrailingSlashes(base);
+  if (path == null || path === "") return b;
+  const p = path.startsWith("/") ? path : `/${path}`;
+  return b + p;
+}
+function resolveBaseUrl(override, fallback) {
+  const t = (override ?? "").trim();
+  return trimTrailingSlashes(t || fallback);
+}
+
+// src/validationClient.ts
+var CACHE_TTL_MS = 6e4;
+async function validateServiceKey(params) {
+  const { baseUrl, serviceKey, serviceId, serviceSecret, fetch: fetchFn = fetch } = params;
+  if (!serviceKey?.trim()) return null;
+  const origin = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
+  const url = `${joinUrl(origin, DEFAULT_CORE_PATH_PREFIX)}/service-keys/validate`;
+  const body = JSON.stringify({ serviceKey, serviceId, serviceSecret });
+  let res;
+  try {
+    res = await fetchFn(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body
+    });
+  } catch (e) {
+    return null;
+  }
+  if (!res.ok) return null;
+  const responseText = await res.text();
+  const signature = res.headers.get(TollaraHeaders.SIGNATURE);
+  const timestamp = res.headers.get(TollaraHeaders.TIMESTAMP);
+  if (!signature || !timestamp) return null;
+  const dataToVerify = responseText + timestamp;
+  const expectedSig = calculateHmac(dataToVerify, serviceSecret);
+  if (!constantTimeEquals(expectedSig, signature)) return null;
+  let data;
+  try {
+    data = JSON.parse(responseText);
+  } catch {
+    return null;
+  }
+  if (!data.valid) return null;
+  return {
+    userId: data.userId ?? null,
+    serviceId: data.serviceId ?? serviceId ?? null,
+    serviceKeyId: typeof data.serviceKeyId === "string" && data.serviceKeyId.length > 0 ? data.serviceKeyId : null,
+    plan: data.plan ?? null,
+    roles: Array.isArray(data.roles) ? data.roles : [],
+    quotaRemaining: typeof data.quotaRemaining === "number" ? data.quotaRemaining : null,
+    subscriptionActive: Boolean(data.subscriptionActive),
+    billingModelType: data.billingModelType ?? null,
+    measurementType: data.measurementType ?? null,
+    unitLabel: data.unitLabel ?? null
+  };
+}
+async function estimateUsage(params) {
+  const { baseUrl, serviceKey, serviceId, serviceSecret, estimatedUnits, fetch: fetchFn = fetch } = params;
+  if (!serviceKey?.trim()) return null;
+  if (estimatedUnits == null || !Number.isFinite(estimatedUnits) || estimatedUnits <= 0) return null;
+  const origin = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
+  const url = `${joinUrl(origin, DEFAULT_CORE_PATH_PREFIX)}/service-keys/estimate-usage`;
+  const body = JSON.stringify({ serviceKey, serviceId, serviceSecret, estimatedUnits });
+  let res;
+  try {
+    res = await fetchFn(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body
+    });
+  } catch {
+    return null;
+  }
+  const code = res.status;
+  if (code !== 200 && code !== 403 && code !== 429) return null;
+  const responseText = await res.text();
+  if (!responseText.trim()) return null;
+  const signature = res.headers.get(TollaraHeaders.SIGNATURE);
+  const timestamp = res.headers.get(TollaraHeaders.TIMESTAMP);
+  if (!signature || !timestamp) return null;
+  if (!validateHmacSignature(signature, responseText + timestamp, serviceSecret)) return null;
+  let data;
+  try {
+    data = JSON.parse(responseText);
+  } catch {
+    return null;
+  }
+  const br = data.breakdown;
+  const breakdown = br != null && typeof br === "object" && !Array.isArray(br) ? br : null;
+  return {
+    sufficientCredits: Boolean(data.sufficientCredits),
+    wouldExceedCap: Boolean(data.wouldExceedCap),
+    wouldAllow: Boolean(data.wouldAllow),
+    estimatedCost: typeof data.estimatedCost === "number" ? data.estimatedCost : null,
+    remainingCredits: typeof data.remainingCredits === "number" ? data.remainingCredits : null,
+    remainingSpendingCap: typeof data.remainingSpendingCap === "number" ? data.remainingSpendingCap : null,
+    billingModelType: typeof data.billingModelType === "string" ? data.billingModelType : null,
+    measurementType: typeof data.measurementType === "string" ? data.measurementType : null,
+    unitLabel: typeof data.unitLabel === "string" ? data.unitLabel : null,
+    breakdown,
+    estimateSchemaVersion: typeof data.estimateSchemaVersion === "number" ? data.estimateSchemaVersion : 0,
+    timestamp: typeof data.timestamp === "number" ? data.timestamp : 0,
+    httpStatus: code
+  };
+}
+async function estimateUsageWithJwt(params) {
+  const {
+    baseUrl,
+    corePathPrefix,
+    bearerToken,
+    userId,
+    serviceId,
+    estimatedUnits,
+    fetch: fetchFn = fetch
+  } = params;
+  if (!bearerToken?.trim() || !userId?.trim() || !serviceId?.trim()) return null;
+  if (estimatedUnits == null || !Number.isFinite(estimatedUnits) || estimatedUnits <= 0) return null;
+  const origin = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
+  const prefix = (corePathPrefix ?? DEFAULT_CORE_PATH_PREFIX).trim();
+  const url = `${joinUrl(origin, prefix)}/billing/usage/estimate`;
+  const body = JSON.stringify({ userId, serviceId, estimatedUnits });
+  let res;
+  try {
+    res = await fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${bearerToken.trim()}`
+      },
+      body
+    });
+  } catch {
+    return null;
+  }
+  const code = res.status;
+  if (code !== 200 && code !== 403 && code !== 429) return null;
+  const responseText = await res.text();
+  if (!responseText.trim()) return null;
+  let data;
+  try {
+    data = JSON.parse(responseText);
+  } catch {
+    return null;
+  }
+  const br = data.breakdown;
+  const breakdown = br != null && typeof br === "object" && !Array.isArray(br) ? br : null;
+  return {
+    sufficientCredits: Boolean(data.sufficientCredits),
+    wouldExceedCap: Boolean(data.wouldExceedCap),
+    wouldAllow: Boolean(data.wouldAllow),
+    estimatedCost: typeof data.estimatedCost === "number" ? data.estimatedCost : null,
+    remainingCredits: typeof data.remainingCredits === "number" ? data.remainingCredits : null,
+    remainingSpendingCap: typeof data.remainingSpendingCap === "number" ? data.remainingSpendingCap : null,
+    billingModelType: typeof data.billingModelType === "string" ? data.billingModelType : null,
+    measurementType: typeof data.measurementType === "string" ? data.measurementType : null,
+    unitLabel: typeof data.unitLabel === "string" ? data.unitLabel : null,
+    breakdown,
+    estimateSchemaVersion: typeof data.estimateSchemaVersion === "number" ? data.estimateSchemaVersion : 0,
+    timestamp: typeof data.timestamp === "number" ? data.timestamp : 0,
+    httpStatus: code
+  };
+}
+function createValidationCache() {
+  const cache = /* @__PURE__ */ new Map();
+  return {
+    get(serviceKey) {
+      const entry = cache.get(serviceKey);
+      if (!entry || Date.now() - entry.ts > CACHE_TTL_MS) return null;
+      return entry.result;
+    },
+    set(serviceKey, result) {
+      cache.set(serviceKey, { result, ts: Date.now() });
+    },
+    clear() {
+      cache.clear();
+    }
+  };
+}
+
+// src/completionStatus.ts
+var CompletionStatus = /* @__PURE__ */ ((CompletionStatus2) => {
+  CompletionStatus2["Completed"] = "COMPLETED";
+  CompletionStatus2["Failed"] = "FAILED";
+  return CompletionStatus2;
+})(CompletionStatus || {});
+
+// src/usageClient.ts
+function usageReportInstantAndEpochSeconds(timestamp) {
+  let ms;
+  if (timestamp == null) {
+    ms = Date.now();
+  } else if (timestamp instanceof Date) {
+    ms = timestamp.getTime();
+  } else if (typeof timestamp === "number") {
+    ms = timestamp < 1e11 ? Math.round(timestamp * 1e3) : timestamp;
+  } else {
+    ms = Date.now();
+  }
+  const sec = Math.floor(ms / 1e3);
+  return { iso: new Date(ms).toISOString(), epochSec: String(sec) };
+}
+function buildUsageReportUrl(baseUrl) {
+  const base = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
+  let p = DEFAULT_USAGE_PATH_PREFIX.trim();
+  if (!p.startsWith("/")) p = `/${p}`;
+  p = p.replace(/\/$/, "");
+  return `${base}${p}/report`;
+}
+function parseUrlParams(url) {
+  let baseUrl = url;
+  let signature = null;
+  let timestamp = null;
+  const q = url.indexOf("?");
+  if (q >= 0) {
+    baseUrl = url.slice(0, q);
+    const search = new URLSearchParams(url.slice(q + 1));
+    signature = search.get("signature");
+    timestamp = search.get("timestamp");
+  }
+  return { baseUrl, signature, timestamp };
+}
+async function reportProgress(params) {
+  const { progressUrl, requestId, stage, percentageComplete, errorMessage, serviceSecret, fetch: fetchFn = fetch } = params;
+  const { baseUrl, timestamp } = parseUrlParams(progressUrl);
+  if (!timestamp) return false;
+  const body = {
+    stage,
+    percentageComplete,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (errorMessage != null) body.errorMessage = errorMessage;
+  const bodyString = JSON.stringify(body);
+  const signature = calculateHmacWithTimestamp(bodyString, timestamp, serviceSecret);
+  try {
+    const res = await fetchFn(baseUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        [TollaraHeaders.SIGNATURE]: signature,
+        [TollaraHeaders.TIMESTAMP]: timestamp
+      },
+      body: bodyString
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+async function reportCompletion(params) {
+  return reportCompletionFull({ ...params, units: params.units ?? 0 });
+}
+async function reportCompletionWithResult(params) {
+  return reportCompletionFull({ ...params, units: params.units ?? 0 });
+}
+async function reportCompletionFull(params) {
+  const { callbackUrl, status, result, resultUrl, contentType, units, serviceSecret, fetch: fetchFn = fetch } = params;
+  const { baseUrl, timestamp } = parseUrlParams(callbackUrl);
+  if (!timestamp) return false;
+  const body = {
+    status,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    units: units ?? 0
+  };
+  if (result != null) body.result = result;
+  if (resultUrl != null) body.resultUrl = resultUrl;
+  if (contentType != null) body.contentType = contentType;
+  const bodyString = JSON.stringify(body);
+  const signature = calculateHmacWithTimestamp(bodyString, timestamp, serviceSecret);
+  try {
+    const res = await fetchFn(baseUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        [TollaraHeaders.SIGNATURE]: signature,
+        [TollaraHeaders.TIMESTAMP]: timestamp
+      },
+      body: bodyString
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+async function reportUsage(params) {
+  const {
+    baseUrl,
+    userId,
+    serviceId,
+    unitsUsed,
+    timestamp,
+    serviceSecret,
+    fetch: fetchFn = fetch
+  } = params;
+  const { iso, epochSec } = usageReportInstantAndEpochSeconds(timestamp ?? null);
+  const body = { userId, serviceId, unitsUsed, timestamp: iso };
+  const bodyString = JSON.stringify(body);
+  const signature = calculateHmacWithTimestamp(bodyString, epochSec, serviceSecret);
+  const url = buildUsageReportUrl(baseUrl ?? DEFAULT_API_URL);
+  const res = await fetchFn(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      [TollaraHeaders.SIGNATURE]: signature,
+      [TollaraHeaders.TIMESTAMP]: epochSec
+    },
+    body: bodyString
+  });
+  if (!res.ok) {
+    throw new Error(`Usage report failed: ${res.status} ${res.statusText}`);
+  }
+  return await res.json();
+}
+
+// src/gatewayClient.ts
+function normalizePrefix(prefix) {
+  if (!prefix) return "";
+  const p = prefix.startsWith("/") ? prefix : `/${prefix}`;
+  return p.replace(/\/$/, "");
+}
+function buildUrl(origin, gatewayPathPrefix, suffix) {
+  const base = resolveBaseUrl(origin, DEFAULT_API_URL);
+  return `${base}${normalizePrefix(gatewayPathPrefix)}${suffix}`;
+}
+async function getRequestStatus(params) {
+  const { baseUrl, requestId, serviceKey, fetch: fetchFn = fetch } = params;
+  const url = buildUrl(baseUrl ?? DEFAULT_API_URL, DEFAULT_GATEWAY_PATH_PREFIX, `/requests/${requestId}/status`);
+  try {
+    const res = await fetchFn(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${serviceKey}` }
+    });
+    const body = await res.text();
+    return { ok: res.ok, status: res.status, body };
+  } catch {
+    return { ok: false, status: 0, body: "" };
+  }
+}
+async function getRequestResult(params) {
+  const { baseUrl, requestId, serviceKey, fetch: fetchFn = fetch } = params;
+  const url = buildUrl(baseUrl ?? DEFAULT_API_URL, DEFAULT_GATEWAY_PATH_PREFIX, `/requests/${requestId}/result`);
+  try {
+    const res = await fetchFn(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${serviceKey}` }
+    });
+    const body = await res.text();
+    return { ok: res.ok, status: res.status, body };
+  } catch {
+    return { ok: false, status: 0, body: "" };
+  }
+}
+
+// src/gatewayInvoke.ts
+function normalizePrefix2(prefix) {
+  if (!prefix) return "";
+  const p = prefix.startsWith("/") ? prefix : `/${prefix}`;
+  return p.replace(/\/$/, "");
+}
+async function invokeService(params) {
+  const {
+    baseUrl,
+    gatewayPathPrefix,
+    method,
+    serviceId,
+    endpointId,
+    serviceKey,
+    body,
+    async: isAsync,
+    fetch: fetchFn = fetch
+  } = params;
+  const origin = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
+  const prefix = normalizePrefix2((gatewayPathPrefix ?? DEFAULT_GATEWAY_PATH_PREFIX).trim());
+  const path = `${prefix}/service/${serviceId}/endpoint/${endpointId}/invoke${isAsync ? "/async" : ""}`;
+  const url = `${origin}${path}`;
+  const m = method.toUpperCase();
+  const payload = body ?? "";
+  const headers = { Authorization: `Bearer ${serviceKey}` };
+  const hasBody = payload.length > 0 && (m === "POST" || m === "PUT");
+  if (hasBody) {
+    headers["Content-Type"] = "application/json";
+  }
+  try {
+    const res = await fetchFn(url, {
+      method: m,
+      headers,
+      body: m === "GET" || m === "DELETE" ? void 0 : hasBody ? payload : void 0
+    });
+    const text = await res.text();
+    let asyncEnvelope;
+    if (res.status === 202 && text.trim()) {
+      try {
+        const j = JSON.parse(text);
+        if (typeof j.requestId === "string") {
+          asyncEnvelope = {
+            requestId: j.requestId,
+            callbackUrl: typeof j.callbackUrl === "string" ? j.callbackUrl : "",
+            progressUrl: typeof j.progressUrl === "string" ? j.progressUrl : ""
+          };
+        }
+      } catch {
+      }
+    }
+    return { statusCode: res.status, body: text, asyncEnvelope };
+  } catch {
+    return null;
+  }
+}
+
+// src/tollaraClient.ts
+var ENV_API_URL = "TOLLARA_API_URL";
+var ENV_SERVICE_ID = "TOLLARA_SERVICE_ID";
+var ENV_SERVICE_SECRET = "TOLLARA_SERVICE_SECRET";
+function envGet(name) {
+  if (typeof process !== "undefined" && process.env && typeof process.env[name] === "string") {
+    return process.env[name];
+  }
+  return void 0;
+}
+function firstNonBlank(a, b) {
+  const t = (a ?? "").trim();
+  if (t) return t;
+  return (b ?? "").trim();
+}
+var TollaraClient = class {
+  constructor(options = {}) {
+    const resolved = resolveBaseUrl(firstNonBlank(options.apiUrl, envGet(ENV_API_URL)), DEFAULT_API_URL);
+    const secret = firstNonBlank(options.serviceSecret, envGet(ENV_SERVICE_SECRET));
+    if (!secret) {
+      throw new Error(
+        `Service secret is required: set serviceSecret or environment variable ${ENV_SERVICE_SECRET}`
+      );
+    }
+    const sidRaw = firstNonBlank(options.serviceId, envGet(ENV_SERVICE_ID));
+    const sid = sidRaw === "" ? null : sidRaw || null;
+    this.apiOrigin = resolved;
+    this.serviceId = sid;
+    this.serviceSecret = secret;
+    this.fetchFn = options.fetch ?? fetch;
+  }
+  async validateServiceKey(serviceKey) {
+    return validateServiceKey({
+      baseUrl: this.apiOrigin,
+      serviceKey,
+      serviceId: this.serviceId,
+      serviceSecret: this.serviceSecret,
+      fetch: this.fetchFn
+    });
+  }
+  async estimateUsage(serviceKey, estimatedUnits) {
+    return estimateUsage({
+      baseUrl: this.apiOrigin,
+      serviceKey,
+      serviceId: this.serviceId,
+      serviceSecret: this.serviceSecret,
+      estimatedUnits,
+      fetch: this.fetchFn
+    });
+  }
+  /**
+   * Core JWT usage estimate (`POST …/billing/usage/estimate`). Response is not HMAC-signed.
+   */
+  async estimateUsageWithJwt(bearerToken, userId, serviceId, estimatedUnits) {
+    return estimateUsageWithJwt({
+      baseUrl: this.apiOrigin,
+      bearerToken,
+      userId,
+      serviceId,
+      estimatedUnits,
+      fetch: this.fetchFn
+    });
+  }
+  /**
+   * Gateway service invoke (sync or async). See platform spec §1.1–1.2.
+   */
+  async invokeService(method, serviceId, endpointId, serviceKey, options) {
+    return invokeService({
+      baseUrl: this.apiOrigin,
+      method,
+      serviceId,
+      endpointId,
+      serviceKey,
+      body: options?.body ?? null,
+      async: options?.async ?? false,
+      fetch: this.fetchFn
+    });
+  }
+  async reportUsage(userId, serviceId, unitsUsed) {
+    return reportUsage({
+      baseUrl: this.apiOrigin,
+      userId,
+      serviceId,
+      unitsUsed,
+      serviceSecret: this.serviceSecret,
+      fetch: this.fetchFn
+    });
+  }
+  async sendProgressUpdate(progressUrl, requestId, stage, percentageComplete, errorMessage) {
+    return reportProgress({
+      progressUrl,
+      requestId,
+      stage,
+      percentageComplete,
+      errorMessage,
+      serviceSecret: this.serviceSecret,
+      fetch: this.fetchFn
+    });
+  }
+  async sendCompletion(callbackUrl, requestId, status, units, options) {
+    const { result, resultUrl, contentType } = options ?? {};
+    if (result != null || resultUrl != null || contentType != null) {
+      return reportCompletionFull({
+        callbackUrl,
+        requestId,
+        status,
+        result,
+        resultUrl,
+        contentType,
+        units,
+        serviceSecret: this.serviceSecret,
+        fetch: this.fetchFn
+      });
+    }
+    return reportCompletion({
+      callbackUrl,
+      requestId,
+      status,
+      units,
+      serviceSecret: this.serviceSecret,
+      fetch: this.fetchFn
+    });
+  }
+  async getRequestStatus(requestId, serviceKey) {
+    return getRequestStatus({
+      baseUrl: this.apiOrigin,
+      requestId,
+      serviceKey,
+      fetch: this.fetchFn
+    });
+  }
+  async getRequestResult(requestId, serviceKey) {
+    return getRequestResult({
+      baseUrl: this.apiOrigin,
+      requestId,
+      serviceKey,
+      fetch: this.fetchFn
+    });
+  }
+};
+TollaraClient.ENV_API_URL = ENV_API_URL;
+TollaraClient.ENV_SERVICE_ID = ENV_SERVICE_ID;
+TollaraClient.ENV_SERVICE_SECRET = ENV_SERVICE_SECRET;
+TollaraClient.DEFAULT_API_URL = DEFAULT_API_URL;
+TollaraClient.DEFAULT_CORE_PATH_PREFIX = DEFAULT_CORE_PATH_PREFIX;
+TollaraClient.DEFAULT_GATEWAY_PATH_PREFIX = DEFAULT_GATEWAY_PATH_PREFIX;
+TollaraClient.DEFAULT_USAGE_PATH_PREFIX = DEFAULT_USAGE_PATH_PREFIX;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CompletionStatus,
+  DEFAULT_API_URL,
+  DEFAULT_CORE_PATH_PREFIX,
+  DEFAULT_GATEWAY_PATH_PREFIX,
+  DEFAULT_USAGE_PATH_PREFIX,
+  ENV_API_URL,
+  ENV_SERVICE_ID,
+  ENV_SERVICE_SECRET,
+  TollaraClient,
+  TollaraHeaders,
+  buildGatewayUserContextString,
+  buildGatewayUserContextStringV2,
+  buildUsageReportUrl,
+  calculateHmac,
+  calculateHmacWithTimestamp,
+  constantTimeEquals,
+  createValidationCache,
+  estimateUsage,
+  estimateUsageWithJwt,
+  getRequestResult,
+  getRequestStatus,
+  getUserContext,
+  invokeService,
+  reportCompletion,
+  reportCompletionFull,
+  reportCompletionWithResult,
+  reportProgress,
+  reportUsage,
+  validateHmacSignature,
+  validateServiceKey,
+  verifyInboundHmac,
+  verifySignature,
+  verifySignatureFromHeaders,
+  verifySignatureFromHeadersAndGetUserContext
+});