@tollara/service-sdk 0.0.1 → 0.0.2

package/dist/index.mjs

@@ -3,10 +3,15 @@ var TollaraHeaders = {
   SIGNATURE: "X-Tollara-Signature",
   TIMESTAMP: "X-Tollara-Timestamp",
   USER_ID: "X-Tollara-User-ID",
+  /** @deprecated v1/v2 only; v3 uses SERVICE_PRODUCT_ID */
   PLAN: "X-Tollara-Plan",
+  SERVICE_PRODUCT_ID: "X-Tollara-Service-Product-ID",
   ROLES: "X-Tollara-Roles",
+  /** @deprecated v1 only */
   QUOTA_REMAINING: "X-Tollara-Quota-Remaining",
+  /** @deprecated v1/v2 only; v3 uses SUBSCRIPTION_STATUS */
   SUBSCRIPTION_ACTIVE: "X-Tollara-Subscription-Active",
+  SUBSCRIPTION_STATUS: "X-Tollara-Subscription-Status",
   BILLING_MODEL: "X-Tollara-Billing-Model",
   MEASUREMENT_TYPE: "X-Tollara-Measurement-Type",
   UNIT_LABEL: "X-Tollara-Unit-Label",
@@ -47,6 +52,13 @@ function validateHmacSignature(signature, payloadString, key) {
   }
 }
 
+// src/grantAccess.ts
+var ACCESS_STATUSES = /* @__PURE__ */ new Set(["ACTIVE", "TRIAL", "CANCELLING", "CANCELLING_PENDING"]);
+function grantAccess(subscriptionStatus) {
+  if (subscriptionStatus == null || subscriptionStatus === "") return false;
+  return ACCESS_STATUSES.has(subscriptionStatus.trim().toUpperCase());
+}
+
 // src/verifier.ts
 function headerGet(headers, canonicalName) {
   const target = canonicalName.toLowerCase();
@@ -84,42 +96,69 @@ function buildGatewayUserContextStringV2(userId, plan, roles, subscriptionActive
   const ul = unitLabel ?? "";
   return "2" + u + p + r + sub + b + m + ul;
 }
-function verifySignature(serviceSecret, input) {
+function buildGatewayUserContextStringV3(userId, serviceProductId, roles, subscriptionStatus, billingModelType, measurementType, unitLabel) {
+  const u = userId ?? "";
+  const sp = serviceProductId ?? "";
+  const r = roles?.length ? roles.join(",") : "";
+  const st = subscriptionStatus ?? "";
+  const b = billingModelType ?? "";
+  const m = measurementType ?? "";
+  const ul = unitLabel ?? "";
+  return "3" + u + sp + r + st + b + m + ul;
+}
+function buildUserContextString(input) {
   const {
-    signature,
-    timestamp,
-    payload,
     userId,
+    serviceProductId,
     plan,
     roles,
     quotaRemaining,
+    subscriptionStatus,
     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(
+  if (signingVersion === "3") {
+    return buildGatewayUserContextStringV3(
       userId,
-      plan,
+      serviceProductId ?? null,
       roles ?? [],
-      subscriptionActive,
+      subscriptionStatus ?? null,
       billingModelType ?? null,
       measurementType ?? null,
       unitLabel ?? null
-    ) : buildGatewayUserContextString(
+    );
+  }
+  if (signingVersion === "2") {
+    return buildGatewayUserContextStringV2(
       userId,
-      plan,
+      plan ?? null,
       roles ?? [],
-      quotaRemaining,
-      subscriptionActive,
+      subscriptionActive ?? false,
       billingModelType ?? null,
       measurementType ?? null,
       unitLabel ?? null
     );
+  }
+  return buildGatewayUserContextString(
+    userId,
+    plan ?? null,
+    roles ?? [],
+    quotaRemaining ?? null,
+    subscriptionActive ?? false,
+    billingModelType ?? null,
+    measurementType ?? null,
+    unitLabel ?? null
+  );
+}
+function verifySignature(serviceSecret, input) {
+  const { signature, timestamp, payload } = input;
+  if (!signature || !timestamp || !serviceSecret) return false;
+  try {
+    const payloadString = payload == null ? "" : typeof payload === "string" ? payload : JSON.stringify(payload);
+    const userContextString = buildUserContextString(input);
     const dataToSign = payloadString + timestamp + userContextString;
     const expectedSignature = calculateHmac(dataToSign, serviceSecret);
     return constantTimeEquals(expectedSignature, signature);
@@ -134,9 +173,11 @@ function verifyInboundHmac(serviceSecret, request) {
     timestamp: request.timestamp,
     payload: request.payload,
     userId: s.userId,
+    serviceProductId: s.serviceProductId,
     plan: s.plan,
     roles: s.roles ?? [],
     quotaRemaining: s.quotaRemaining,
+    subscriptionStatus: s.subscriptionStatus,
     subscriptionActive: s.subscriptionActive,
     billingModelType: s.billingModelType,
     measurementType: s.measurementType,
@@ -144,10 +185,7 @@ function verifyInboundHmac(serviceSecret, request) {
     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;
+function parseSignedUserContextFromHeaders(headers) {
   const rolesHeader = headerGet(headers, TollaraHeaders.ROLES);
   const roles = rolesHeader ? rolesHeader.split(",").map((x) => x.trim()).filter(Boolean) : [];
   let quotaRemaining = headerGet(headers, TollaraHeaders.QUOTA_REMAINING);
@@ -162,16 +200,24 @@ function verifySignatureFromHeaders(serviceSecret, headers, payload) {
   const billing = headerGet(headers, TollaraHeaders.BILLING_MODEL);
   const measurement = headerGet(headers, TollaraHeaders.MEASUREMENT_TYPE);
   const unit = headerGet(headers, TollaraHeaders.UNIT_LABEL);
-  const signedUserContext = {
+  return {
     userId: headerGet(headers, TollaraHeaders.USER_ID),
+    serviceProductId: headerGet(headers, TollaraHeaders.SERVICE_PRODUCT_ID),
     plan: headerGet(headers, TollaraHeaders.PLAN),
     roles,
     quotaRemaining,
+    subscriptionStatus: headerGet(headers, TollaraHeaders.SUBSCRIPTION_STATUS),
     subscriptionActive,
     billingModelType: billing && billing !== "" ? billing : null,
     measurementType: measurement && measurement !== "" ? measurement : null,
     unitLabel: unit && unit !== "" ? unit : null
   };
+}
+function verifySignatureFromHeaders(serviceSecret, headers, payload) {
+  const signature = headerGet(headers, TollaraHeaders.SIGNATURE);
+  const timestamp = headerGet(headers, TollaraHeaders.TIMESTAMP);
+  if (!signature || !timestamp) return false;
+  const signedUserContext = parseSignedUserContextFromHeaders(headers);
   const signingVersion = headerGet(headers, TollaraHeaders.SIGNING_VERSION);
   return verifyInboundHmac(serviceSecret, {
     signature,
@@ -186,28 +232,42 @@ function verifySignatureFromHeadersAndGetUserContext(serviceSecret, headers, pay
   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);
+  const s = parseSignedUserContextFromHeaders(headers);
   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
+    userId: s.userId,
+    serviceProductId: s.serviceProductId ?? null,
+    plan: s.plan ?? null,
+    roles: s.roles ?? [],
+    quotaRemaining: typeof s.quotaRemaining === "number" ? s.quotaRemaining : s.quotaRemaining != null && s.quotaRemaining !== "" ? Number(s.quotaRemaining) : null,
+    subscriptionStatus: s.subscriptionStatus ?? null,
+    subscriptionActive: s.subscriptionActive ?? false,
+    billingModelType: s.billingModelType ?? null,
+    measurementType: s.measurementType ?? null,
+    unitLabel: s.unitLabel ?? null
+  };
+}
+
+// src/usageBreakdown.ts
+function parseUsageBreakdown(raw) {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const o = raw;
+  const num = (k) => typeof o[k] === "number" ? o[k] : void 0;
+  const bool = (k) => typeof o[k] === "boolean" ? o[k] : void 0;
+  return {
+    unitsUsed: num("unitsUsed"),
+    baseUnitsUsed: num("baseUnitsUsed"),
+    overageUnits: num("overageUnits"),
+    chargeableOverageUnits: num("chargeableOverageUnits"),
+    surplusOverageUnits: num("surplusOverageUnits"),
+    overageCost: num("overageCost"),
+    totalOverageCost: num("totalOverageCost"),
+    unitsRemaining: num("unitsRemaining"),
+    remainingCredits: num("remainingCredits"),
+    remainingSpendingCap: num("remainingSpendingCap"),
+    totalUnitsUsedThisCycle: num("totalUnitsUsedThisCycle"),
+    isOverLimit: bool("isOverLimit"),
+    isOverage: bool("isOverage"),
+    isOverageAllowed: bool("isOverageAllowed")
   };
 }
 
@@ -216,6 +276,9 @@ 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";
+var ECS_CORE_PATH_PREFIX = "/core/api/v1";
+var ECS_GATEWAY_PATH_PREFIX = "/gateway/api/v1";
+var ECS_USAGE_PATH_PREFIX = "/usage/api/v1";
 
 // src/urls.ts
 function trimTrailingSlashes(s) {
@@ -234,13 +297,88 @@ function resolveBaseUrl(override, fallback) {
   return trimTrailingSlashes(t || fallback);
 }
 
+// src/pathPrefixes.ts
+function isHostedTollaraApiOrigin(origin) {
+  try {
+    const host = new URL(origin).hostname.toLowerCase();
+    if (host === "api.tollara.ai" || host.endsWith(".api.tollara.ai")) {
+      return true;
+    }
+    if (host === "api.ppe.tollara.ai" || host.endsWith(".api.ppe.tollara.ai")) {
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function resolveGatewayPathPrefix(baseUrl, override) {
+  const explicit = override?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const origin = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
+  return isHostedTollaraApiOrigin(origin) ? ECS_GATEWAY_PATH_PREFIX : DEFAULT_GATEWAY_PATH_PREFIX;
+}
+function resolveCorePathPrefix(baseUrl, override) {
+  const explicit = override?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const origin = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
+  return isHostedTollaraApiOrigin(origin) ? ECS_CORE_PATH_PREFIX : DEFAULT_CORE_PATH_PREFIX;
+}
+function resolveUsagePathPrefix(baseUrl, override) {
+  const explicit = override?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const origin = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
+  return isHostedTollaraApiOrigin(origin) ? ECS_USAGE_PATH_PREFIX : DEFAULT_USAGE_PATH_PREFIX;
+}
+
 // src/validationClient.ts
-var CACHE_TTL_MS = 6e4;
-async function validateServiceKey(params) {
+function invalidKeyFromUnsignedErrorBody(responseText, httpStatus) {
+  if (httpStatus !== 401 && httpStatus !== 403) {
+    return null;
+  }
+  try {
+    const data = JSON.parse(responseText);
+    if (data.valid === false) {
+      return {
+        ok: false,
+        code: "INVALID_KEY",
+        message: typeof data.error === "string" ? data.error : void 0,
+        httpStatus
+      };
+    }
+  } catch {
+  }
+  return null;
+}
+function parseValidationResult(data, serviceId) {
+  const subscriptionStatus = typeof data.subscriptionStatus === "string" ? data.subscriptionStatus : null;
+  return {
+    userId: data.userId ?? null,
+    serviceId: data.serviceId ?? serviceId ?? null,
+    serviceKeyId: typeof data.serviceKeyId === "string" && data.serviceKeyId.length > 0 ? data.serviceKeyId : null,
+    serviceProductId: typeof data.serviceProductId === "string" ? data.serviceProductId : null,
+    roles: Array.isArray(data.roles) ? data.roles : [],
+    subscriptionStatus,
+    validationSchemaVersion: typeof data.validationSchemaVersion === "number" ? data.validationSchemaVersion : 0,
+    billingModelType: data.billingModelType ?? null,
+    measurementType: data.measurementType ?? null,
+    unitLabel: data.unitLabel ?? null,
+    grantAccess: grantAccess(subscriptionStatus)
+  };
+}
+async function validateServiceKeyWithOutcome(params) {
   const { baseUrl, serviceKey, serviceId, serviceSecret, fetch: fetchFn = fetch } = params;
-  if (!serviceKey?.trim()) return null;
+  if (!serviceKey?.trim()) {
+    return { ok: false, code: "MISSING_KEY" };
+  }
   const origin = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
-  const url = `${joinUrl(origin, DEFAULT_CORE_PATH_PREFIX)}/service-keys/validate`;
+  const url = `${joinUrl(origin, resolveCorePathPrefix(baseUrl))}/service-keys/validate`;
   const body = JSON.stringify({ serviceKey, serviceId, serviceSecret });
   let res;
   try {
@@ -249,35 +387,61 @@ async function validateServiceKey(params) {
       headers: { "Content-Type": "application/json" },
       body
     });
-  } catch (e) {
-    return null;
+  } catch {
+    return { ok: false, code: "NETWORK" };
   }
-  if (!res.ok) return null;
+  const httpStatus = res.status;
   const responseText = await res.text();
+  if (!res.ok) {
+    const unsignedInvalid = invalidKeyFromUnsignedErrorBody(responseText, httpStatus);
+    if (unsignedInvalid) {
+      return unsignedInvalid;
+    }
+    return { ok: false, code: "HTTP_ERROR", httpStatus };
+  }
   const signature = res.headers.get(TollaraHeaders.SIGNATURE);
   const timestamp = res.headers.get(TollaraHeaders.TIMESTAMP);
-  if (!signature || !timestamp) return null;
+  if (!signature || !timestamp) {
+    return { ok: false, code: "MISSING_SIGNATURE_HEADERS", httpStatus };
+  }
   const dataToVerify = responseText + timestamp;
   const expectedSig = calculateHmac(dataToVerify, serviceSecret);
-  if (!constantTimeEquals(expectedSig, signature)) return null;
+  if (!constantTimeEquals(expectedSig, signature)) {
+    return { ok: false, code: "HMAC_MISMATCH", httpStatus };
+  }
   let data;
   try {
     data = JSON.parse(responseText);
   } catch {
-    return null;
+    return { ok: false, code: "PARSE_ERROR", httpStatus };
   }
-  if (!data.valid) return null;
+  if (!data.valid) {
+    return {
+      ok: false,
+      code: "INVALID_KEY",
+      message: typeof data.error === "string" ? data.error : void 0,
+      httpStatus
+    };
+  }
+  return { ok: true, result: parseValidationResult(data, serviceId) };
+}
+async function validateServiceKey(params) {
+  const outcome = await validateServiceKeyWithOutcome(params);
+  return outcome.ok ? outcome.result : null;
+}
+function parseEstimateResult(data, httpStatus) {
   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
+    sufficientCredits: Boolean(data.sufficientCredits),
+    wouldExceedCap: Boolean(data.wouldExceedCap),
+    wouldAllow: Boolean(data.wouldAllow),
+    estimatedCost: typeof data.estimatedCost === "number" ? data.estimatedCost : 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: parseUsageBreakdown(data.breakdown),
+    estimateSchemaVersion: typeof data.estimateSchemaVersion === "number" ? data.estimateSchemaVersion : 0,
+    timestamp: typeof data.timestamp === "number" ? data.timestamp : 0,
+    httpStatus
   };
 }
 async function estimateUsage(params) {
@@ -285,7 +449,7 @@ async function estimateUsage(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 url = `${joinUrl(origin, resolveCorePathPrefix(baseUrl))}/service-keys/estimate-usage`;
   const body = JSON.stringify({ serviceKey, serviceId, serviceSecret, estimatedUnits });
   let res;
   try {
@@ -311,23 +475,7 @@ async function estimateUsage(params) {
   } 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
-  };
+  return parseEstimateResult(data, code);
 }
 async function estimateUsageWithJwt(params) {
   const {
@@ -342,7 +490,7 @@ async function estimateUsageWithJwt(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 prefix = resolveCorePathPrefix(baseUrl, corePathPrefix);
   const url = `${joinUrl(origin, prefix)}/billing/usage/estimate`;
   const body = JSON.stringify({ userId, serviceId, estimatedUnits });
   let res;
@@ -368,24 +516,9 @@ async function estimateUsageWithJwt(params) {
   } 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
-  };
+  return parseEstimateResult(data, code);
 }
+var CACHE_TTL_MS = 6e4;
 function createValidationCache() {
   const cache = /* @__PURE__ */ new Map();
   return {
@@ -427,12 +560,15 @@ function usageReportInstantAndEpochSeconds(timestamp) {
 }
 function buildUsageReportUrl(baseUrl) {
   const base = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
-  let p = DEFAULT_USAGE_PATH_PREFIX.trim();
+  let p = resolveUsagePathPrefix(baseUrl).trim();
   if (!p.startsWith("/")) p = `/${p}`;
   p = p.replace(/\/$/, "");
   return `${base}${p}/report`;
 }
 function parseUrlParams(url) {
+  if (url == null || typeof url !== "string") {
+    return { baseUrl: "", signature: null, timestamp: null };
+  }
   let baseUrl = url;
   let signature = null;
   let timestamp = null;
@@ -445,17 +581,16 @@ function parseUrlParams(url) {
   }
   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);
+async function postSignedUsageCallback(urlWithQuery, bodyString, serviceSecret, fetchFn) {
+  const { baseUrl, timestamp } = parseUrlParams(urlWithQuery);
+  if (!timestamp) {
+    return {
+      success: false,
+      httpStatus: 0,
+      httpStatusText: urlWithQuery ? "Missing timestamp query parameter in URL" : "Missing or invalid callback/progress URL",
+      requestUrl: baseUrl
+    };
+  }
   const signature = calculateHmacWithTimestamp(bodyString, timestamp, serviceSecret);
   try {
     const res = await fetchFn(baseUrl, {
@@ -467,21 +602,37 @@ async function reportProgress(params) {
       },
       body: bodyString
     });
-    return res.ok;
-  } catch {
-    return false;
+    const responseBody = await res.text();
+    return {
+      success: res.ok,
+      httpStatus: res.status,
+      httpStatusText: res.statusText,
+      requestUrl: baseUrl,
+      responseBody: responseBody || void 0
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      httpStatus: 0,
+      httpStatusText: "Network error",
+      requestUrl: baseUrl,
+      networkError: message
+    };
   }
 }
-async function reportCompletion(params) {
-  return reportCompletionFull({ ...params, units: params.units ?? 0 });
-}
-async function reportCompletionWithResult(params) {
-  return reportCompletionFull({ ...params, units: params.units ?? 0 });
+async function reportProgress(params) {
+  const { progressUrl, stage, percentageComplete, errorMessage, serviceSecret, fetch: fetchFn = fetch } = params;
+  const body = {
+    stage,
+    percentageComplete,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (errorMessage != null) body.errorMessage = errorMessage;
+  return postSignedUsageCallback(progressUrl, JSON.stringify(body), serviceSecret, fetchFn);
 }
-async function reportCompletionFull(params) {
+async function reportCompletion(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(),
@@ -490,22 +641,7 @@ async function reportCompletionFull(params) {
   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;
-  }
+  return postSignedUsageCallback(callbackUrl, JSON.stringify(body), serviceSecret, fetchFn);
 }
 async function reportUsage(params) {
   const {
@@ -534,7 +670,18 @@ async function reportUsage(params) {
   if (!res.ok) {
     throw new Error(`Usage report failed: ${res.status} ${res.statusText}`);
   }
-  return await res.json();
+  const json = await res.json();
+  return {
+    reportSchemaVersion: typeof json.reportSchemaVersion === "number" ? json.reportSchemaVersion : void 0,
+    status: typeof json.status === "string" ? json.status : void 0,
+    warning: typeof json.warning === "string" ? json.warning : json.warning === null ? null : void 0,
+    userId: typeof json.userId === "string" ? json.userId : void 0,
+    serviceId: typeof json.serviceId === "string" ? json.serviceId : void 0,
+    billingModelType: typeof json.billingModelType === "string" ? json.billingModelType : null,
+    measurementType: typeof json.measurementType === "string" ? json.measurementType : null,
+    unitLabel: typeof json.unitLabel === "string" ? json.unitLabel : null,
+    breakdown: parseUsageBreakdown(json.breakdown)
+  };
 }
 
 // src/gatewayClient.ts
@@ -549,7 +696,11 @@ function buildUrl(origin, 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`);
+  const url = buildUrl(
+    baseUrl ?? DEFAULT_API_URL,
+    resolveGatewayPathPrefix(baseUrl),
+    `/requests/${requestId}/status`
+  );
   try {
     const res = await fetchFn(url, {
       method: "GET",
@@ -563,7 +714,11 @@ async function getRequestStatus(params) {
 }
 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`);
+  const url = buildUrl(
+    baseUrl ?? DEFAULT_API_URL,
+    resolveGatewayPathPrefix(baseUrl),
+    `/requests/${requestId}/result`
+  );
   try {
     const res = await fetchFn(url, {
       method: "GET",
@@ -595,7 +750,7 @@ async function invokeService(params) {
     fetch: fetchFn = fetch
   } = params;
   const origin = resolveBaseUrl(baseUrl, DEFAULT_API_URL);
-  const prefix = normalizePrefix2((gatewayPathPrefix ?? DEFAULT_GATEWAY_PATH_PREFIX).trim());
+  const prefix = normalizePrefix2(resolveGatewayPathPrefix(baseUrl, gatewayPathPrefix));
   const path = `${prefix}/service/${serviceId}/endpoint/${endpointId}/invoke${isAsync ? "/async" : ""}`;
   const url = `${origin}${path}`;
   const m = method.toUpperCase();
@@ -672,6 +827,15 @@ var TollaraClient = class {
       fetch: this.fetchFn
     });
   }
+  async validateServiceKeyWithOutcome(serviceKey) {
+    return validateServiceKeyWithOutcome({
+      baseUrl: this.apiOrigin,
+      serviceKey,
+      serviceId: this.serviceId,
+      serviceSecret: this.serviceSecret,
+      fetch: this.fetchFn
+    });
+  }
   async estimateUsage(serviceKey, estimatedUnits) {
     return estimateUsage({
       baseUrl: this.apiOrigin,
@@ -733,23 +897,13 @@ var TollaraClient = class {
   }
   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,
+      result,
+      resultUrl,
+      contentType,
       units,
       serviceSecret: this.serviceSecret,
       fetch: this.fetchFn
@@ -785,6 +939,9 @@ export {
   DEFAULT_CORE_PATH_PREFIX,
   DEFAULT_GATEWAY_PATH_PREFIX,
   DEFAULT_USAGE_PATH_PREFIX,
+  ECS_CORE_PATH_PREFIX,
+  ECS_GATEWAY_PATH_PREFIX,
+  ECS_USAGE_PATH_PREFIX,
   ENV_API_URL,
   ENV_SERVICE_ID,
   ENV_SERVICE_SECRET,
@@ -792,6 +949,7 @@ export {
   TollaraHeaders,
   buildGatewayUserContextString,
   buildGatewayUserContextStringV2,
+  buildGatewayUserContextStringV3,
   buildUsageReportUrl,
   calculateHmac,
   calculateHmacWithTimestamp,
@@ -802,14 +960,19 @@ export {
   getRequestResult,
   getRequestStatus,
   getUserContext,
+  grantAccess,
   invokeService,
+  isHostedTollaraApiOrigin,
+  parseUsageBreakdown,
   reportCompletion,
-  reportCompletionFull,
-  reportCompletionWithResult,
   reportProgress,
   reportUsage,
+  resolveCorePathPrefix,
+  resolveGatewayPathPrefix,
+  resolveUsagePathPrefix,
   validateHmacSignature,
   validateServiceKey,
+  validateServiceKeyWithOutcome,
   verifyInboundHmac,
   verifySignature,
   verifySignatureFromHeaders,