@tollara/service-sdk 0.0.1

package/dist/index.d.ts

@@ -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 };