@tollara/service-sdk 0.0.1

package/README.md

@@ -0,0 +1,190 @@
+# Tollara SDK (JavaScript/TypeScript)
+
+**Package:** `@tollara/service-sdk` (version **0.0.1** 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.
+
+This README covers the public SDK contract and usage examples.
+
+## API origin
+
+By default, the SDK uses the production Tollara API origin. Override when needed (non-production or private deployments):
+
+- **`TollaraClient`:** pass `apiUrl`, or set **`TOLLARA_API_URL`**
+
+## Tollara client (recommended)
+
+`TollaraClient` uses optional **`TOLLARA_SERVICE_ID`** (service UUID), required **`TOLLARA_SERVICE_SECRET`** (unless passed as `serviceSecret`), and optional **`TOLLARA_API_URL`**.
+
+```ts
+import { TollaraClient } from '@tollara/service-sdk';
+
+const client = new TollaraClient({
+  serviceId: 'service-uuid',
+  serviceSecret: 'secret',
+});
+await client.getRequestStatus(requestId, serviceKey);
+await client.reportUsage(userId, serviceId, 1);
+await client.validateServiceKey(serviceKey);
+const estimate = await client.estimateUsage(serviceKey, 1);
+if (estimate) {
+  const allowed = estimate.wouldAllow;
+  const status = estimate.httpStatus;
+}
+
+// JWT usage estimate (unsigned Core response): internal Core user id + service id + units
+// await client.estimateUsageWithJwt(bearerJwt, coreUserId, serviceId, 1);
+
+// Gateway invoke (Bearer = service key): method, serviceId, endpointId, serviceKey, optional body + async flag
+// await client.invokeService('POST', serviceId, endpointId, serviceKey, { body: '{}', async: false });
+```
+
+### 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.
+
+```ts
+import { verifySignatureFromHeadersAndGetUserContext } from '@tollara/service-sdk';
+
+const ctx = verifySignatureFromHeadersAndGetUserContext(serviceSecret, headers, rawBody);
+if (ctx) { /* trusted */ }
+```
+
+## Install
+
+```bash
+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
+- `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
+- `estimateUsageWithJwt` — Core `POST …/billing/usage/estimate` with Bearer JWT (unsigned response)
+- `invokeService` — gateway `…/service/{serviceId}/endpoint/…/invoke` and `…/invoke/async`
+- `reportUsage`, `reportProgress`, `reportCompletion` — usage service (**report** body uses ISO `timestamp`; `X-Tollara-Timestamp` = epoch **seconds** for HMAC)
+- `getRequestStatus`, `getRequestResult` — async job polling
+
+## Examples
+
+### Verify HMAC (backend)
+
+```ts
+import { verifySignatureFromHeaders, getUserContext } from '@tollara/service-sdk';
+
+const serviceSecret = 'your-service-shared-secret';
+const valid = verifySignatureFromHeaders(serviceSecret, req.headers, rawBodyString);
+if (valid) {
+  const ctx = getUserContext(req.headers);
+}
+```
+
+### Validate service key (caller)
+
+```ts
+import { validateServiceKey } from '@tollara/service-sdk';
+
+const result = await validateServiceKey({
+  serviceKey: 'bearer-token',
+  serviceId: 'service-id',
+  serviceSecret: 'service-secret',
+});
+```
+
+Optional `baseUrl` when not using the default production origin. Successful validate results include **`serviceKeyId`** when Core returns it (§2.1).
+
+### Usage estimate (caller)
+
+Same trust model as validate: JSON body with the service key (no separate bearer on Core). Response HMAC is verified for success and typical denial statuses when signature headers are present.
+
+```ts
+import { estimateUsage } from '@tollara/service-sdk';
+
+const est = await estimateUsage({
+  serviceKey: 'bearer-token',
+  serviceId: 'service-id',
+  serviceSecret: 'service-secret',
+  estimatedUnits: 1,
+});
+```
+
+### Report usage
+
+```ts
+import { reportUsage } from '@tollara/service-sdk';
+
+await reportUsage({
+  userId: 'u1',
+  serviceId: 'a1',
+  unitsUsed: 1,
+  serviceSecret: 'secret',
+});
+```
+
+### Progress and completion (async)
+
+URLs come from the platform (`progress_url`, `callback_url`).
+
+```ts
+import { CompletionStatus, reportProgress, reportCompletionWithResult } from '@tollara/service-sdk';
+
+await reportProgress({
+  progressUrl,
+  requestId,
+  stage: 'processing',
+  percentageComplete: 50,
+  serviceSecret,
+});
+await reportCompletionWithResult({
+  callbackUrl,
+  requestId,
+  status: CompletionStatus.Completed,
+  result: 'done',
+  serviceSecret,
+  units: 1,
+});
+```
+
+### Job status / result (caller)
+
+```ts
+import { getRequestStatus, getRequestResult } from '@tollara/service-sdk';
+
+const st = await getRequestStatus({ requestId, serviceKey });
+const res = await getRequestResult({ requestId, serviceKey });
+```
+
+Optional `baseUrl` on each call when not using the default origin.
+
+## Build & test
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+## Release (npm)
+
+Package name: **`@tollara/service-sdk`** ([npm scoped packages](https://docs.npmjs.com/about-scopes-and-packages)).
+
+1. **Version** — Bump `"version"` in [`package.json`](package.json) (SemVer). npm will not let you publish the same version twice.
+2. **Verify** — `npm ci`, `npm test`, and `npm run build` (or rely on `prepublishOnly`, which runs `build` on `npm publish`).
+3. **Login** — `npm login` on the machine that will publish, or use an **automation token** / `NPM_TOKEN` in CI (see [access tokens](https://docs.npmjs.com/about-access-tokens) and [CI workflows](https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow)).
+4. **Publish** — From `sdk-js`:
+
+   ```bash
+   npm publish --access public
+   ```
+
+   The first publish of a **scoped** package to the public registry must use `--access public` (subsequent publishes can omit it if the package is already public).
+
+5. **Tag** — Tag the Git commit that matches the published version.
+
+Optional: `npm publish --dry-run` to inspect the tarball without uploading. `repository`, `files` (`dist`, `README.md`), and `prepublishOnly` are already set in `package.json`.
+
+Contract reference: this README and the package API surface.

package/dist/index.d.mts

@@ -0,0 +1,372 @@
+/** Canonical Tollara HTTP header names (gateway-signed requests and signed responses). */
+declare const TollaraHeaders: {
+    readonly SIGNATURE: "X-Tollara-Signature";
+    readonly TIMESTAMP: "X-Tollara-Timestamp";
+    readonly USER_ID: "X-Tollara-User-ID";
+    readonly PLAN: "X-Tollara-Plan";
+    readonly ROLES: "X-Tollara-Roles";
+    readonly QUOTA_REMAINING: "X-Tollara-Quota-Remaining";
+    readonly SUBSCRIPTION_ACTIVE: "X-Tollara-Subscription-Active";
+    readonly BILLING_MODEL: "X-Tollara-Billing-Model";
+    readonly MEASUREMENT_TYPE: "X-Tollara-Measurement-Type";
+    readonly UNIT_LABEL: "X-Tollara-Unit-Label";
+    /** Gateway HMAC user-context schema: `2` = v2 suffix (leading `2`, no quota segment). */
+    readonly SIGNING_VERSION: "X-Tollara-Signing-Version";
+};
+type TollaraHeaderName = (typeof TollaraHeaders)[keyof typeof TollaraHeaders];
+
+/**
+ * HMAC-SHA256 with UTF-8 key/message and Base64 output (per docs/hmac-spec.md).
+ */
+declare function calculateHmac(data: string, key: string): string;
+/**
+ * Outbound signing: canonical string = bodyString + timestamp.
+ */
+declare function calculateHmacWithTimestamp(bodyString: string, timestamp: string | number, key: string): string;
+/**
+ * Constant-time string comparison to avoid timing attacks.
+ */
+declare function constantTimeEquals(a: string, b: string): boolean;
+/**
+ * Validate that signature matches HMAC(payloadString, key).
+ */
+declare function validateHmacSignature(signature: string, payloadString: string, key: string): boolean;
+
+interface UserContext {
+    userId: string | null;
+    plan: string | null;
+    roles: string[];
+    quotaRemaining: number | null;
+    subscriptionActive: boolean;
+    billingModelType: string | null;
+    measurementType: string | null;
+    unitLabel: string | null;
+}
+interface VerifySignatureInput {
+    signature: string;
+    timestamp: string;
+    payload: string | object | null;
+    userId: string | null;
+    plan: string | null;
+    roles: string[];
+    quotaRemaining: number | string | null;
+    /** Must match X-Tollara-Subscription-Active for verification. */
+    subscriptionActive: boolean;
+    billingModelType?: string | null;
+    measurementType?: string | null;
+    unitLabel?: string | null;
+    /** When `2`, uses HMAC user-context v2 (see TollaraHeaders.SIGNING_VERSION). */
+    signingVersion?: string | null;
+}
+/** User fields that participate in inbound HMAC userContextString (docs/hmac-spec.md). */
+interface SignedUserContext {
+    userId: string | null;
+    plan: string | null;
+    roles: string[];
+    quotaRemaining: number | string | null;
+    subscriptionActive: boolean;
+    billingModelType?: string | null;
+    measurementType?: string | null;
+    unitLabel?: string | null;
+}
+interface InboundHmacRequest {
+    signature: string;
+    timestamp: string;
+    payload: string | object | null;
+    signedUserContext: SignedUserContext;
+    signingVersion?: string | null;
+}
+/** 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.
+ */
+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;
+/**
+ * Verifies HMAC on an inbound gateway request.
+ * Canonical string: payload + timestamp + userContextString (see docs/hmac-spec.md).
+ */
+declare function verifySignature(serviceSecret: string, input: VerifySignatureInput): boolean;
+/**
+ * Verifies inbound HMAC using {@link InboundHmacRequest} (preferred typed entry point).
+ */
+declare function verifyInboundHmac(serviceSecret: string, request: InboundHmacRequest): boolean;
+/**
+ * Verifies inbound HMAC from a case-insensitive header bag and payload.
+ */
+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;
+
+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;
+    roles: string[];
+    quotaRemaining: number | null;
+    subscriptionActive: boolean;
+    billingModelType: string | null;
+    measurementType: string | null;
+    unitLabel: string | null;
+}
+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;
+    estimateSchemaVersion: number;
+    timestamp: number;
+    httpStatus: number;
+}
+/**
+ * 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;
+    serviceSecret: string;
+    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.
+ */
+declare function estimateUsage(params: {
+    baseUrl?: string | null;
+    serviceKey: string;
+    serviceId: string | null;
+    serviceSecret: string;
+    estimatedUnits: number;
+    fetch?: typeof globalThis.fetch;
+}): Promise<UsageEstimateResult | null>;
+/**
+ * Core JWT usage estimate (`POST …/billing/usage/estimate`). Not HMAC-signed (spec §2.2).
+ */
+declare function estimateUsageWithJwt(params: {
+    baseUrl?: string | null;
+    corePathPrefix?: string | null;
+    bearerToken: string;
+    userId: string;
+    serviceId: string;
+    estimatedUnits: number;
+    fetch?: typeof globalThis.fetch;
+}): Promise<UsageEstimateResult | null>;
+/**
+ * Simple cache for validateServiceKey (optional).
+ */
+declare function createValidationCache(): {
+    get(serviceKey: string): ServiceKeyValidationResult | null;
+    set(serviceKey: string, result: ServiceKeyValidationResult): void;
+    clear(): void;
+};
+
+/**
+ * Completion status for usage service async completion (docs/sdk-api-spec.md §3.3).
+ */
+declare enum CompletionStatus {
+    Completed = "COMPLETED",
+    Failed = "FAILED"
+}
+
+/** 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). */
+declare const DEFAULT_CORE_PATH_PREFIX = "/api/v1";
+declare const DEFAULT_GATEWAY_PATH_PREFIX = "/api";
+declare const DEFAULT_USAGE_PATH_PREFIX = "/api/usage";
+
+/** Builds `{baseUrl}/api/usage/report` using the default usage path. */
+declare function buildUsageReportUrl(baseUrl: string): string;
+type ReportProgressParams = {
+    progressUrl: string;
+    requestId: string;
+    stage: string;
+    percentageComplete: number;
+    /** Omit or leave unset when there is no error (avoids passing null). */
+    errorMessage?: string | null;
+    serviceSecret: string;
+    fetch?: typeof globalThis.fetch;
+};
+/**
+ * POST to progressUrl with signed body (optional errorMessage).
+ */
+declare function reportProgress(params: ReportProgressParams): Promise<boolean>;
+type ReportCompletionParams = {
+    callbackUrl: string;
+    requestId: string;
+    status: CompletionStatus;
+    result?: string | null;
+    resultUrl?: string | null;
+    contentType?: string | null;
+    units?: number | null;
+    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>;
+interface UsageReportResponse {
+    status?: string;
+    warning?: string;
+    isOverLimit?: boolean;
+    remainingRequestsPerPeriod?: number;
+    remainingTimeUnitsPerPeriod?: number;
+    remainingSpendingCap?: number;
+    overageRate?: number;
+}
+/**
+ * POST usage report with signed body (`{baseUrl}/api/usage/report`).
+ */
+declare function reportUsage(params: {
+    /** API origin; defaults to `https://api.tollara.ai`. */
+    baseUrl?: string | null;
+    userId: string;
+    serviceId: string;
+    unitsUsed: number;
+    timestamp?: number | Date | null;
+    serviceSecret: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<UsageReportResponse>;
+
+/**
+ * Caller-side gateway polling for async jobs.
+ */
+interface GatewayPollResult {
+    ok: boolean;
+    status: number;
+    body: string;
+}
+/**
+ * GET .../requests/{requestId}/status with Bearer service key.
+ */
+declare function getRequestStatus(params: {
+    /** API origin; defaults to `https://api.tollara.ai`. */
+    baseUrl?: string | null;
+    requestId: string;
+    serviceKey: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<GatewayPollResult>;
+/**
+ * GET .../requests/{requestId}/result with Bearer service key.
+ */
+declare function getRequestResult(params: {
+    /** API origin; defaults to `https://api.tollara.ai`. */
+    baseUrl?: string | null;
+    requestId: string;
+    serviceKey: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<GatewayPollResult>;
+
+type GatewayHttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type GatewayInvokeAsyncEnvelope = {
+    requestId: string;
+    callbackUrl: string;
+    progressUrl: string;
+};
+type GatewayInvokeResult = {
+    statusCode: number;
+    body: string;
+    asyncEnvelope?: GatewayInvokeAsyncEnvelope;
+};
+/**
+ * Gateway service invoke (sync or async). See `docs-sdk/MAIN-SDK-API-SPEC.md` §1.1–1.2.
+ */
+declare function invokeService(params: {
+    baseUrl?: string | null;
+    gatewayPathPrefix?: string | null;
+    method: GatewayHttpMethod;
+    serviceId: string;
+    endpointId: string;
+    serviceKey: string;
+    body?: string | null;
+    async?: boolean;
+    fetch?: typeof globalThis.fetch;
+}): Promise<GatewayInvokeResult | null>;
+
+declare const ENV_API_URL = "TOLLARA_API_URL";
+declare const ENV_SERVICE_ID = "TOLLARA_SERVICE_ID";
+declare const ENV_SERVICE_SECRET = "TOLLARA_SERVICE_SECRET";
+
+type TollaraClientOptions = {
+    /**
+     * API origin (scheme + host). Defaults to `https://api.tollara.ai` or `TOLLARA_API_URL`.
+     * All service calls use this origin with fixed paths (validate, usage, gateway polling).
+     */
+    apiUrl?: string | null;
+    /** Service UUID; falls back to `TOLLARA_SERVICE_ID`. */
+    serviceId?: string | null;
+    /** Shared secret; falls back to `TOLLARA_SERVICE_SECRET`. */
+    serviceSecret?: string | null;
+    fetch?: typeof globalThis.fetch;
+};
+/**
+ * Unified client: validate service key, report usage/progress/complete, poll gateway for async jobs.
+ * Omitted options fall back to `TOLLARA_*` environment variables (when `process.env` exists).
+ */
+declare class TollaraClient {
+    static readonly ENV_API_URL = "TOLLARA_API_URL";
+    static readonly ENV_SERVICE_ID = "TOLLARA_SERVICE_ID";
+    static readonly ENV_SERVICE_SECRET = "TOLLARA_SERVICE_SECRET";
+    static readonly DEFAULT_API_URL = "https://api.tollara.ai";
+    static readonly DEFAULT_CORE_PATH_PREFIX = "/api/v1";
+    static readonly DEFAULT_GATEWAY_PATH_PREFIX = "/api";
+    static readonly DEFAULT_USAGE_PATH_PREFIX = "/api/usage";
+    private readonly apiOrigin;
+    private readonly serviceId;
+    private readonly serviceSecret;
+    private readonly fetchFn;
+    constructor(options?: TollaraClientOptions);
+    validateServiceKey(serviceKey: string): Promise<ServiceKeyValidationResult | null>;
+    estimateUsage(serviceKey: string, estimatedUnits: number): Promise<UsageEstimateResult | null>;
+    /**
+     * Core JWT usage estimate (`POST …/billing/usage/estimate`). Response is not HMAC-signed.
+     */
+    estimateUsageWithJwt(bearerToken: string, userId: string, serviceId: string, estimatedUnits: number): Promise<UsageEstimateResult | null>;
+    /**
+     * Gateway service invoke (sync or async). See platform spec §1.1–1.2.
+     */
+    invokeService(method: GatewayHttpMethod, serviceId: string, endpointId: string, serviceKey: string, options?: {
+        body?: string | null;
+        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>;
+    sendCompletion(callbackUrl: string, requestId: string, status: CompletionStatus, units: number, options?: {
+        result?: string | null;
+        resultUrl?: string | null;
+        contentType?: string | null;
+    }): Promise<boolean>;
+    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 };