@tollara/service-sdk 0.0.1 → 0.0.2

package/README.md

@@ -1,6 +1,6 @@
 # Tollara SDK (JavaScript/TypeScript)
 
-**Package:** `@tollara/service-sdk` (version **0.0.1** in this repo)
+**Package:** `@tollara/service-sdk` (version **0.0.2** in this repo)
 
 Verify inbound HMAC, validate **service keys**, run usage pre-flight (service-key **and** JWT paths), **gateway invoke** (sync/async), report usage, progress, completion, and poll async job status.
 
@@ -41,13 +41,13 @@ if (estimate) {
 
 ### Verify signature and user context together
 
-Verification defaults to signing version **v2** (newer user-context suffix, no quota segment in the signed material). `verifySignatureFromHeaders` also reads `X-Tollara-Signing-Version` when present.
+Verification uses HMAC user-context **v3** when `X-Tollara-Signing-Version` is `"3"` (`serviceProductId`, `subscriptionStatus`); **v2** when `"2"`; legacy v1 when the header is absent.
 
 ```ts
-import { verifySignatureFromHeadersAndGetUserContext } from '@tollara/service-sdk';
+import { grantAccess, verifySignatureFromHeadersAndGetUserContext } from '@tollara/service-sdk';
 
 const ctx = verifySignatureFromHeadersAndGetUserContext(serviceSecret, headers, rawBody);
-if (ctx) { /* trusted */ }
+if (ctx && grantAccess(ctx.subscriptionStatus)) { /* trusted + invoke-eligible */ }
 ```
 
 ## Install
@@ -58,9 +58,10 @@ npm install @tollara/service-sdk
 
 ## API highlights
 
-- `TollaraHeaders` — canonical `X-Tollara-*` names (including signing-version for gateway HMAC v2)
-- `buildGatewayUserContextString` / `buildGatewayUserContextStringV2` — inbound suffix helpers
-- `verifyInboundHmac` / `verifySignatureFromHeaders` — inbound gateway HMAC
+- `TollaraHeaders` — canonical `X-Tollara-*` names (including signing-version for gateway HMAC v3)
+- `buildGatewayUserContextStringV3` — inbound suffix helper for production gateway forwards
+- `grantAccess` — invoke eligibility from `subscriptionStatus` (validate/gateway v3)
+- `verifyInboundHmac` / `verifySignatureFromHeaders` — inbound gateway HMAC (v3 when `X-Tollara-Signing-Version` is `"3"`)
 - `getUserContext` — parses headers (case-insensitive keys)
 - `TollaraClient` — validate key, estimates, invoke, usage reporting, gateway polling
 - `validateServiceKey` / `estimateUsage` — Core **service-key** paths; response HMAC verified when headers present
@@ -130,16 +131,20 @@ await reportUsage({
 URLs come from the platform (`progress_url`, `callback_url`).
 
 ```ts
-import { CompletionStatus, reportProgress, reportCompletionWithResult } from '@tollara/service-sdk';
+import { CompletionStatus, reportProgress, reportCompletion } from '@tollara/service-sdk';
 
-await reportProgress({
+const progress = await reportProgress({
   progressUrl,
   requestId,
   stage: 'processing',
   percentageComplete: 50,
   serviceSecret,
 });
-await reportCompletionWithResult({
+if (!progress.success) {
+  console.error(progress.httpStatus, progress.responseBody);
+}
+
+const complete = await reportCompletion({
   callbackUrl,
   requestId,
   status: CompletionStatus.Completed,

package/dist/index.d.mts

@@ -3,10 +3,15 @@ declare const TollaraHeaders: {
     readonly SIGNATURE: "X-Tollara-Signature";
     readonly TIMESTAMP: "X-Tollara-Timestamp";
     readonly USER_ID: "X-Tollara-User-ID";
+    /** @deprecated v1/v2 only; v3 uses SERVICE_PRODUCT_ID */
     readonly PLAN: "X-Tollara-Plan";
+    readonly SERVICE_PRODUCT_ID: "X-Tollara-Service-Product-ID";
     readonly ROLES: "X-Tollara-Roles";
+    /** @deprecated v1 only */
     readonly QUOTA_REMAINING: "X-Tollara-Quota-Remaining";
+    /** @deprecated v1/v2 only; v3 uses SUBSCRIPTION_STATUS */
     readonly SUBSCRIPTION_ACTIVE: "X-Tollara-Subscription-Active";
+    readonly SUBSCRIPTION_STATUS: "X-Tollara-Subscription-Status";
     readonly BILLING_MODEL: "X-Tollara-Billing-Model";
     readonly MEASUREMENT_TYPE: "X-Tollara-Measurement-Type";
     readonly UNIT_LABEL: "X-Tollara-Unit-Label";
@@ -32,11 +37,21 @@ declare function constantTimeEquals(a: string, b: string): boolean;
  */
 declare function validateHmacSignature(signature: string, payloadString: string, key: string): boolean;
 
+/** Whether subscriptionStatus grants invoke access (validation/gateway v3). */
+declare function grantAccess(subscriptionStatus: string | null | undefined): boolean;
+
 interface UserContext {
     userId: string | null;
+    /** v3: service product id; v1/v2 legacy: plan name in {@link plan}. */
+    serviceProductId: string | null;
+    /** @deprecated v1/v2 only */
     plan: string | null;
     roles: string[];
+    /** @deprecated v1 only */
     quotaRemaining: number | null;
+    /** v3: uppercase subscription status. */
+    subscriptionStatus: string | null;
+    /** @deprecated v1/v2 only */
     subscriptionActive: boolean;
     billingModelType: string | null;
     measurementType: string | null;
@@ -47,24 +62,32 @@ interface VerifySignatureInput {
     timestamp: string;
     payload: string | object | null;
     userId: string | null;
-    plan: string | null;
+    /** v3 */
+    serviceProductId?: string | null;
+    /** v1/v2 */
+    plan?: string | null;
     roles: string[];
-    quotaRemaining: number | string | null;
-    /** Must match X-Tollara-Subscription-Active for verification. */
-    subscriptionActive: boolean;
+    /** v1 only */
+    quotaRemaining?: number | string | null;
+    /** v3 */
+    subscriptionStatus?: string | null;
+    /** v1/v2 */
+    subscriptionActive?: boolean;
     billingModelType?: string | null;
     measurementType?: string | null;
     unitLabel?: string | null;
-    /** When `2`, uses HMAC user-context v2 (see TollaraHeaders.SIGNING_VERSION). */
+    /** `3` = v3; `2` = v2; absent = v1 */
     signingVersion?: string | null;
 }
-/** User fields that participate in inbound HMAC userContextString (docs/hmac-spec.md). */
+/** User fields that participate in inbound HMAC userContextString. */
 interface SignedUserContext {
     userId: string | null;
-    plan: string | null;
+    serviceProductId?: string | null;
+    plan?: string | null;
     roles: string[];
-    quotaRemaining: number | string | null;
-    subscriptionActive: boolean;
+    quotaRemaining?: number | string | null;
+    subscriptionStatus?: string | null;
+    subscriptionActive?: boolean;
     billingModelType?: string | null;
     measurementType?: string | null;
     unitLabel?: string | null;
@@ -79,14 +102,16 @@ interface InboundHmacRequest {
 /** Loose header map (e.g. Node/Express lowercases keys). */
 type HeaderBag = Record<string, string | string[] | undefined | null>;
 /**
- * Gateway inbound HMAC suffix: userId + plan + rolesCsv + quota + subscriptionActive + billing + measurement + unit.
+ * Gateway inbound HMAC suffix v1: userId + plan + rolesCsv + quota + subscriptionActive + billing fields.
  */
 declare function buildGatewayUserContextString(userId: string | null, plan: string | null, roles: string[], quotaRemaining: number | string | null, subscriptionActive: boolean, billingModelType: string | null, measurementType: string | null, unitLabel: string | null): string;
 /** Gateway HMAC user-context v2: leading `2`, then userId, plan, roles, subscription, billing fields (no quota). */
 declare function buildGatewayUserContextStringV2(userId: string | null, plan: string | null, roles: string[], subscriptionActive: boolean, billingModelType: string | null, measurementType: string | null, unitLabel: string | null): string;
+/** Gateway HMAC user-context v3: leading `3`, serviceProductId, subscriptionStatus (see MAIN-SDK-API-SPEC §4). */
+declare function buildGatewayUserContextStringV3(userId: string | null, serviceProductId: string | null, roles: string[], subscriptionStatus: string | null, billingModelType: string | null, measurementType: string | null, unitLabel: string | null): string;
 /**
  * Verifies HMAC on an inbound gateway request.
- * Canonical string: payload + timestamp + userContextString (see docs/hmac-spec.md).
+ * Canonical string: payload + timestamp + userContextString (see docs-sdk/MAIN-SDK-API-SPEC.md §4).
  */
 declare function verifySignature(serviceSecret: string, input: VerifySignatureInput): boolean;
 /**
@@ -99,46 +124,84 @@ declare function verifyInboundHmac(serviceSecret: string, request: InboundHmacRe
 declare function verifySignatureFromHeaders(serviceSecret: string, headers: HeaderBag, payload: string | object | null): boolean;
 /**
  * Verifies inbound HMAC; if valid returns user context, else `null` (do not trust headers).
- * Parses `X-Tollara-*` headers into {@link UserContext} (case-insensitive header names).
  */
 declare function verifySignatureFromHeadersAndGetUserContext(serviceSecret: string, headers: HeaderBag, payload: string | object | null): UserContext | null;
 declare function getUserContext(headers: HeaderBag): UserContext;
 
+/** Shared usage breakdown for estimate and report responses (MAIN-SDK-API-SPEC). */
+interface UsageBreakdown {
+    unitsUsed?: number;
+    baseUnitsUsed?: number;
+    overageUnits?: number;
+    chargeableOverageUnits?: number;
+    surplusOverageUnits?: number;
+    overageCost?: number;
+    totalOverageCost?: number;
+    unitsRemaining?: number;
+    /** PREPAID: credit balance after this chunk. */
+    remainingCredits?: number;
+    remainingSpendingCap?: number;
+    totalUnitsUsedThisCycle?: number;
+    isOverLimit?: boolean;
+    isOverage?: boolean;
+    isOverageAllowed?: boolean;
+}
+declare function parseUsageBreakdown(raw: unknown): UsageBreakdown | null;
+
 interface ServiceKeyValidationResult {
     userId: string | null;
     serviceId: string | null;
     /** Core service-key row id when present in the validate JSON body. */
     serviceKeyId: string | null;
-    plan: string | null;
+    serviceProductId: string | null;
     roles: string[];
-    quotaRemaining: number | null;
-    subscriptionActive: boolean;
+    subscriptionStatus: string | null;
+    validationSchemaVersion: number;
     billingModelType: string | null;
     measurementType: string | null;
     unitLabel: string | null;
+    /** Whether {@link subscriptionStatus} grants invoke access. */
+    grantAccess: boolean;
 }
 interface UsageEstimateResult {
     sufficientCredits: boolean;
     wouldExceedCap: boolean;
     wouldAllow: boolean;
     estimatedCost: number | null;
-    remainingCredits: number | null;
-    remainingSpendingCap: number | null;
     billingModelType: string | null;
     measurementType: string | null;
     unitLabel: string | null;
-    breakdown: Record<string, unknown> | null;
+    breakdown: UsageBreakdown | null;
     estimateSchemaVersion: number;
     timestamp: number;
     httpStatus: number;
 }
+/** Canonical failure codes for validateServiceKeyWithOutcome (see docs-sdk §2.1.1). */
+type ValidationFailureCode = 'MISSING_KEY' | 'NETWORK' | 'HTTP_ERROR' | 'MISSING_SIGNATURE_HEADERS' | 'HMAC_MISMATCH' | 'INVALID_KEY' | 'PARSE_ERROR';
+type ServiceKeyValidationOutcome = {
+    ok: true;
+    result: ServiceKeyValidationResult;
+} | {
+    ok: false;
+    code: ValidationFailureCode;
+    message?: string;
+    httpStatus?: number;
+};
+/**
+ * Validates a service key via the Tollara API and verifies response HMAC.
+ * Returns a discriminated outcome with canonical failure codes (§2.1.1).
+ */
+declare function validateServiceKeyWithOutcome(params: {
+    baseUrl?: string | null;
+    serviceKey: string;
+    serviceId: string | null;
+    serviceSecret: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<ServiceKeyValidationOutcome>;
 /**
  * Validates a service key via the Tollara API and verifies response HMAC.
- * Uses `baseUrl` (default production API origin) + `/api/v1/service-keys/validate`.
- * Optional in-memory cache with 60s TTL via {@link createValidationCache}.
  */
 declare function validateServiceKey(params: {
-    /** API origin; defaults to `https://api.tollara.ai`. */
     baseUrl?: string | null;
     serviceKey: string;
     serviceId: string | null;
@@ -146,8 +209,7 @@ declare function validateServiceKey(params: {
     fetch?: typeof globalThis.fetch;
 }): Promise<ServiceKeyValidationResult | null>;
 /**
- * Usage pre-flight for a service key (Core). Same trust model as {@link validateServiceKey}: JSON body, response HMAC.
- * Verifies signatures on 200 / 403 / 429 when `X-Tollara-Signature` and `X-Tollara-Timestamp` are present.
+ * Usage pre-flight for a service key (Core). Same trust model as {@link validateServiceKey}.
  */
 declare function estimateUsage(params: {
     baseUrl?: string | null;
@@ -157,9 +219,7 @@ declare function estimateUsage(params: {
     estimatedUnits: number;
     fetch?: typeof globalThis.fetch;
 }): Promise<UsageEstimateResult | null>;
-/**
- * Core JWT usage estimate (`POST …/billing/usage/estimate`). Not HMAC-signed (spec §2.2).
- */
+/** Core JWT usage estimate (`POST …/billing/usage/estimate`). Not HMAC-signed (spec §2.2). */
 declare function estimateUsageWithJwt(params: {
     baseUrl?: string | null;
     corePathPrefix?: string | null;
@@ -169,9 +229,7 @@ declare function estimateUsageWithJwt(params: {
     estimatedUnits: number;
     fetch?: typeof globalThis.fetch;
 }): Promise<UsageEstimateResult | null>;
-/**
- * Simple cache for validateServiceKey (optional).
- */
+/** Simple cache for validateServiceKey (optional). */
 declare function createValidationCache(): {
     get(serviceKey: string): ServiceKeyValidationResult | null;
     set(serviceKey: string, result: ServiceKeyValidationResult): void;
@@ -188,13 +246,25 @@ declare enum CompletionStatus {
 
 /** Default Tollara API origin (production). */
 declare const DEFAULT_API_URL = "https://api.tollara.ai";
-/** Path segments joined to `baseUrl` for each service (not part of the public URL API). */
+/** Path segments joined to `baseUrl` for each service (Docker/local default). */
 declare const DEFAULT_CORE_PATH_PREFIX = "/api/v1";
 declare const DEFAULT_GATEWAY_PATH_PREFIX = "/api";
 declare const DEFAULT_USAGE_PATH_PREFIX = "/api/usage";
+/** ECS / hosted api.tollara.ai path prefixes (see MAIN-SDK-API-SPEC.md). */
+declare const ECS_CORE_PATH_PREFIX = "/core/api/v1";
+declare const ECS_GATEWAY_PATH_PREFIX = "/gateway/api/v1";
+declare const ECS_USAGE_PATH_PREFIX = "/usage/api/v1";
 
-/** Builds `{baseUrl}/api/usage/report` using the default usage path. */
+/** Builds usage report URL for the given API origin (Docker or hosted ECS). */
 declare function buildUsageReportUrl(baseUrl: string): string;
+type UsageCallbackResult = {
+    success: boolean;
+    httpStatus: number;
+    httpStatusText: string;
+    requestUrl: string;
+    responseBody?: string;
+    networkError?: string;
+};
 type ReportProgressParams = {
     progressUrl: string;
     requestId: string;
@@ -205,10 +275,8 @@ type ReportProgressParams = {
     serviceSecret: string;
     fetch?: typeof globalThis.fetch;
 };
-/**
- * POST to progressUrl with signed body (optional errorMessage).
- */
-declare function reportProgress(params: ReportProgressParams): Promise<boolean>;
+/** POST to progressUrl with signed body (optional errorMessage). */
+declare function reportProgress(params: ReportProgressParams): Promise<UsageCallbackResult>;
 type ReportCompletionParams = {
     callbackUrl: string;
     requestId: string;
@@ -220,28 +288,18 @@ type ReportCompletionParams = {
     serviceSecret: string;
     fetch?: typeof globalThis.fetch;
 };
-/**
- * POST completion with status and optional units (defaults to 0).
- */
-declare function reportCompletion(params: Pick<ReportCompletionParams, 'callbackUrl' | 'requestId' | 'status' | 'serviceSecret' | 'fetch'> & {
-    units?: number | null;
-}): Promise<boolean>;
-/**
- * POST completion with inline result text.
- */
-declare function reportCompletionWithResult(params: Pick<ReportCompletionParams, 'callbackUrl' | 'requestId' | 'status' | 'result' | 'units' | 'serviceSecret' | 'fetch'>): Promise<boolean>;
-/**
- * POST to callbackUrl with signed body (all optional fields).
- */
-declare function reportCompletionFull(params: ReportCompletionParams): Promise<boolean>;
+/** POST to callbackUrl with signed completion body. */
+declare function reportCompletion(params: ReportCompletionParams): Promise<UsageCallbackResult>;
 interface UsageReportResponse {
+    reportSchemaVersion?: number;
     status?: string;
-    warning?: string;
-    isOverLimit?: boolean;
-    remainingRequestsPerPeriod?: number;
-    remainingTimeUnitsPerPeriod?: number;
-    remainingSpendingCap?: number;
-    overageRate?: number;
+    warning?: string | null;
+    userId?: string;
+    serviceId?: string;
+    billingModelType?: string | null;
+    measurementType?: string | null;
+    unitLabel?: string | null;
+    breakdown?: UsageBreakdown | null;
 }
 /**
  * POST usage report with signed body (`{baseUrl}/api/usage/report`).
@@ -346,6 +404,7 @@ declare class TollaraClient {
     private readonly fetchFn;
     constructor(options?: TollaraClientOptions);
     validateServiceKey(serviceKey: string): Promise<ServiceKeyValidationResult | null>;
+    validateServiceKeyWithOutcome(serviceKey: string): Promise<ServiceKeyValidationOutcome>;
     estimateUsage(serviceKey: string, estimatedUnits: number): Promise<UsageEstimateResult | null>;
     /**
      * Core JWT usage estimate (`POST …/billing/usage/estimate`). Response is not HMAC-signed.
@@ -359,14 +418,20 @@ declare class TollaraClient {
         async?: boolean;
     }): Promise<GatewayInvokeResult | null>;
     reportUsage(userId: string, serviceId: string, unitsUsed: number): Promise<UsageReportResponse>;
-    sendProgressUpdate(progressUrl: string, requestId: string, stage: string, percentageComplete: number, errorMessage?: string | null): Promise<boolean>;
+    sendProgressUpdate(progressUrl: string, requestId: string, stage: string, percentageComplete: number, errorMessage?: string | null): Promise<UsageCallbackResult>;
     sendCompletion(callbackUrl: string, requestId: string, status: CompletionStatus, units: number, options?: {
         result?: string | null;
         resultUrl?: string | null;
         contentType?: string | null;
-    }): Promise<boolean>;
+    }): Promise<UsageCallbackResult>;
     getRequestStatus(requestId: string, serviceKey: string): Promise<GatewayPollResult>;
     getRequestResult(requestId: string, serviceKey: string): Promise<GatewayPollResult>;
 }
 
-export { 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, type GatewayHttpMethod, type GatewayInvokeAsyncEnvelope, type GatewayInvokeResult, type GatewayPollResult, type HeaderBag, type InboundHmacRequest, type ReportCompletionParams, type ReportProgressParams, type ServiceKeyValidationResult, type SignedUserContext, TollaraClient, type TollaraClientOptions, type TollaraHeaderName, TollaraHeaders, type UsageEstimateResult, type UsageReportResponse, type UserContext, type VerifySignatureInput, buildGatewayUserContextString, buildGatewayUserContextStringV2, buildUsageReportUrl, calculateHmac, calculateHmacWithTimestamp, constantTimeEquals, createValidationCache, estimateUsage, estimateUsageWithJwt, getRequestResult, getRequestStatus, getUserContext, invokeService, reportCompletion, reportCompletionFull, reportCompletionWithResult, reportProgress, reportUsage, validateHmacSignature, validateServiceKey, verifyInboundHmac, verifySignature, verifySignatureFromHeaders, verifySignatureFromHeadersAndGetUserContext };
+/** True for hosted Tollara API hosts (prod/PPE/branded *.api.tollara.ai). */
+declare function isHostedTollaraApiOrigin(origin: string): boolean;
+declare function resolveGatewayPathPrefix(baseUrl?: string | null, override?: string | null): string;
+declare function resolveCorePathPrefix(baseUrl?: string | null, override?: string | null): string;
+declare function resolveUsagePathPrefix(baseUrl?: string | null, override?: string | null): string;
+
+export { CompletionStatus, DEFAULT_API_URL, 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, type GatewayHttpMethod, type GatewayInvokeAsyncEnvelope, type GatewayInvokeResult, type GatewayPollResult, type HeaderBag, type InboundHmacRequest, type ReportCompletionParams, type ReportProgressParams, type ServiceKeyValidationOutcome, type ServiceKeyValidationResult, type SignedUserContext, TollaraClient, type TollaraClientOptions, type TollaraHeaderName, TollaraHeaders, type UsageBreakdown, type UsageCallbackResult, type UsageEstimateResult, type UsageReportResponse, type UserContext, type ValidationFailureCode, type VerifySignatureInput, buildGatewayUserContextString, buildGatewayUserContextStringV2, buildGatewayUserContextStringV3, buildUsageReportUrl, calculateHmac, calculateHmacWithTimestamp, constantTimeEquals, createValidationCache, estimateUsage, estimateUsageWithJwt, getRequestResult, getRequestStatus, getUserContext, grantAccess, invokeService, isHostedTollaraApiOrigin, parseUsageBreakdown, reportCompletion, reportProgress, reportUsage, resolveCorePathPrefix, resolveGatewayPathPrefix, resolveUsagePathPrefix, validateHmacSignature, validateServiceKey, validateServiceKeyWithOutcome, verifyInboundHmac, verifySignature, verifySignatureFromHeaders, verifySignatureFromHeadersAndGetUserContext };