Skip to content

JavaScript SDK reference

This page is the reference for developers using the JavaScript SDK: every option and export. It lists the configuration options and exports of the JavaScript SDK (@sidub-inc/licensing-client), for React and Node. It needs Node.js 20 or later ("engines": { "node": ">=20" }): the client uses crypto.subtle as a global, which Node 18 exposes only behind a flag. Browsers are not affected.

Field Required or optional Meaning
licenseServiceUri Required The licensing API URL to call.
encodedCredential Required, unless using the manual parts below The encoded credential (SIDUB_LIC_...) that authenticates the client. It is decoded into seatId, serviceKeyId, serviceKeyPublicMember and runtimeToken.
runtimeToken Required if not using encodedCredential The seat-scoped runtime token. Opaque: never decode, parse or display it. Normally arrives inside encodedCredential rather than being set directly.
seatId Required if not using encodedCredential The seat ID component of the manual credential.
serviceKeyId Required if not using encodedCredential The service key ID component of the manual credential.
serviceKeyPublicMember Required if not using encodedCredential The service key public member component of the manual credential.
consumptionServiceUri Optional The consumption API URL to call. performOperation counts a use with or without it; the address decides only whether the use is reported.
timeout Optional The request timeout, in milliseconds, for calls to the licensing service. Default 30000 (30 seconds).
validateSignatures Optional Whether to validate response signatures.
cacheEnabled Optional Whether to cache authorization results.
cacheMaxSize Optional The maximum size of the authorization cache.
cacheFreshTtlMs Optional How long, in milliseconds, a cached authorization is served before the client revalidates it against the licensing service. Default 24 hours (also the cap); an authorization with no expiry defaults to 1 hour. Revocation latency is min(cacheFreshTtlMs, remaining seat window); tighten it for faster revocation pickup at the cost of more calls; 0 revalidates on every read.
staleGraceMs Optional How long, in milliseconds, an expired cached authorization may still be served (flagged stale) when the licensing service is transiently unreachable. Default 24 hours, capped at 7 days; 0 disables stale-serve. The Node analogue of .NET’s AuthorizationStaleGraceMinutes.
contextProvider Optional A custom context provider for multi-tenant credential resolution: an object whose resolveContext() returns the credential parts for the current caller, in place of the fixed credential above.
billableResourceId Optional The billable resource ID to report consumption against.
issuerClientId Set it Your account’s client id. Every runtime call declares the seller, and a credential another seller issued is refused, so a credential bought for someone else’s product cannot unlock yours because the feature keys match.
productId Set it This product’s id. With it a credential of another product is refused, your own other products included.
Export Kind Meaning
LicensingClient Client The client class, configured as shown above.
LicensingProvider React Context provider that makes a LicensingClient available to a React tree.
useLicensingContext React hook Returns the LicensingClient provided by LicensingProvider.
useLicensingContextValue React hook Returns the provider’s client, isSignatureValidationEnabled and configuredSeatId together.
ServiceAccessAssertion Assertion Asserts that the license has access to the service.
FeatureExistsAssertion Assertion Asserts that a given feature exists on the license.
RateLimitAssertion Assertion Asserts that a rate-limited feature has not exceeded its limit.
QuotaAssertion Assertion Asserts that an allowance still has uses left in the current billing period.
LimitAssertion Assertion Asserts that a count your application holds is within a limit. See Limits.
CompositeAssertion Assertion Combines multiple assertions into one.
NotAssertion Assertion Inverts another assertion.
PurchaseClient Client The in-app purchase client: listOfferings, getOffering, createCheckout, getResult and pollResult. It takes the buyer’s token through getAccessToken and no key of yours. See In-app purchase.
LicensingError Error The base error the client throws. It carries the server’s code and correlationId, and on a 403 AuthorizationDenied its denialReason (type AuthorizationDenialReason) names why: Expired, LicenseSuspended, LicenseCancelled, SeatRetired or ProductMismatch (the credential is for another seller or product than issuerClientId/productId declare). denialReason is undefined for every other error.
LicensingConfigurationException Error Thrown when the client configuration is invalid or incomplete.
CryptoError Error Thrown when signature verification fails.
RateLimitError Error Thrown when a rate-limited operation exceeds its limit.
AllowanceExhaustedError Error Thrown when an allowance does not cover a use: featureKey, allowance and periodEndUtc, when the period resets.
encodeCredential, decodeCredential, tryDecodeCredential Helper Convert between the credential parts and the encoded SIDUB_LIC_... string.
hasValidCryptoConfig Helper Reports whether a decoded credential carries both serviceKeyId and serviceKeyPublicMember, the pair signature verification needs.
LicensingCredential Type The decoded credential: seatId, serviceKeyId, serviceKeyPublicMember and runtimeToken, all required. License codes are version 2 only; decodeCredential refuses a version 1 payload (which named the seat licenseId) rather than reinterpreting it.
licensingContextFromEncodedString, licensingContextToEncodedString Helper Convert a licensing context to and from its encoded form.
RateLimitFeatureState Type The state carried through rate-limited operations.
QuotaLicenseFeature, QuotaFeatureState Type An allowance feature (allowance per billing period; 0 is no cap) and the period state the client keeps for it. See Consumption and metering.
LimitLicenseFeature, LimitReading Type A limit feature (limit, a number your application holds to; null is unlimited) and the reading getLimit returns: featureKey, limit and isUnlimited.

A credential carries one authority: the runtime token for the seat it names. The client calls {licenseServiceUri}/runtime and {consumptionServiceUri}/runtime, and presents the token as Authorization: Bearer. The /runtime suffix is derived by the client, so the configured URIs are the plain addresses. No dub-apiKey and no Ocp-Apim-Subscription-Key is sent on those calls: a runtime credential carries no account authority.

LicensingContextType, the licensing-context shape, carries a required runtimeToken alongside the seat and service-key parts, and no account key.

Checkout is the one place the seller’s account API key appears, and it is always an explicit argument rather than client configuration: createCheckoutSession(request, apiKey), getCheckoutResult(checkoutId, apiKey) and pollCheckoutResult(checkoutId, { apiKey, signal?, maxAttempts? }). It is a server-side secret; never put it in a browser bundle.

CheckoutSession carries a claimUrl field. It is present only when a free offering was bought against a typed email address: nothing is provisioned until the buyer confirms on that page, so redirect them to it at once (the email carrying the same link is only a fallback). With a returnUrl set they come back with request_id added, the requestId of your request: look up the checkoutId you saved under it, and one getCheckoutResult read is enough; without one, poll. A paid checkout ends on successUrl with request_id added the same way.

performOperation records a use of an allowance. A use the allowance does not cover is neither counted nor reported, and performOperation throws AllowanceExhaustedError, which carries when the period resets. performOperation throws LicensingError when the client needs the platform and cannot reach it.

await client.assertAllowance(featureKey) checks before the work that the use it will record fits. It records nothing, and returns true, throws AllowanceExhaustedError, or returns false when the license does not carry the allowance. The optional amount, default 1, is how many uses the work will record. client.assertLicense(QuotaAssertion.create(featureKey), authorization) asserts the last use: true, or AllowanceExhaustedError once a use is refused, until a use is covered again. It asks the platform nothing. Every refusal also logs a console.warn.

getState().allowances carries one entry for each allowance feature: featureKey, allowance, used, reserved, remaining, periodEndUtc and asOfUtc. getState() reads the figures from the platform when it holds none for the period or those it holds are more than a minute old; the read uses none of the allowance. The figures are unknown while periodEndUtc is null. After the platform refuses a use because the period is spent, remaining is 0 and periodEndUtc is when the period resets. Showing what is left lists each case.

The client keeps the count by reserving units from the platform at {licenseServiceUri}/runtime/AcquireAllowanceGrant and returning them at {licenseServiceUri}/runtime/ReleaseAllowanceGrant, and reads the figures at {licenseServiceUri}/runtime/ReadAllowance; allow all three paths wherever you list the runtime paths. You never call them.

When the application stops, the client settles with the platform by itself:

  • Browser. Automatic, on pagehide.
  • React. Automatic: LicensingProvider does it when it unmounts.
  • Node. Automatic when the process ends on its own, including a process whose signal handler closes its servers and lets the event loop drain. Only code that calls process.exit() awaits client.disposeAsync() first.

client.dispose() releases a client that is no longer needed while the process keeps running. It returns nothing and does not wait.

Every runtime call states the newest signature layout the client reads (SignatureLayout: 1), and the platform names the layout it signed the answer in, beside the signature. An answer in a layout this client does not read fails with a CryptoError (VERIFICATION_FAILED) that names the update it needs. A 429 LedgerBusy or 503 StoreUnavailable answer is retried under the same RequestId, honouring Retry-After, so a lost ledger race never costs units.

Enforcing an allowance covers the behaviour.

A limit is a number your application holds to, such as 10 projects or 90 days of history. The platform never counts it: your application counts its own data and asserts the count it would hold after the action. client.assertLicense(LimitAssertion.create(featureKey, count), authorization) returns true when count is within the limit, and false when it is past it or the license does not carry the feature as a limit; it never throws for a count past the limit. With a limit of 3, creating the fourth project asserts 4 and returns false. A limit of null is unlimited.

client.getLimit(featureKey, authorization) reads the limit without asserting, to show “7 of 10” or size a control: { featureKey, limit, isUnlimited }, or undefined when the license does not carry the feature as a limit. getState().limits lists every limit the same way. Neither asks the platform anything, and nothing is reported for a limit.

A limit is read by SDK 2.4.0 or later.