JavaScript / TypeScript SDK

Package @tollara/service-sdk — verify inbound gateway HMAC, validate service keys, usage pre-flight (service-key and JWT paths), gateway invoke (sync/async), report usage, progress and completion, and poll async job status. Full contract and examples live in the SDK repo README (sdk-js).

Install

npm install @tollara/service-sdk

Published package: npm — @tollara/service-sdk. Contract E2E and install docs pin version 0.0.1; bump the pin in Install by language when you ship a new release.

Configuration

By default the client targets the production tollara.ai API origin. Override for staging, tests, or private deployments with the apiUrl option on TollaraClient, or set the environment variable TOLLARA_API_URL.

TollaraClient uses optional TOLLARA_SERVICE_ID, required TOLLARA_SERVICE_SECRET (unless passed as serviceSecret), and optional TOLLARA_API_URL. Progress and completion calls always use the full progressUrl / callbackUrl strings from the platform.

API highlights

  • Inbound HMAC — defaults to signing version v2; verifySignatureFromHeadersAndGetUserContext, verifySignatureFromHeaders, getUserContext
  • Core (service key) — validateServiceKey, estimateUsage (response HMAC verified when headers are present); successful validate can include serviceKeyId
  • JWT usage estimate — estimateUsageWithJwt (unsigned Core response)
  • Gateway — invokeService; getRequestStatus, getRequestResult
  • Usage service — reportUsage; reportProgress, reportCompletionWithResult with CompletionStatus (API expects uppercase COMPLETED / FAILED)
  • Usage report signing — JSON body uses an ISO-8601 timestamp; X-Tollara-Timestamp is Unix epoch seconds for HMAC

See also