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.
LicensingClient config
Section titled “LicensingClient config”| 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. |
Exports
Section titled “Exports”| 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. |
Credential posture
Section titled “Credential posture”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.
Allowances
Section titled “Allowances”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:
LicensingProviderdoes 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()awaitsclient.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.
Limits
Section titled “Limits”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.