@sidub-inc/licensing-client 1.3.45 → 1.4.0

package/README.md

@@ -556,4 +556,5 @@ See [MIGRATION.md](docs/MIGRATION.md) for detailed upgrade instructions. Key cha
 
 ## License
 
-MIT © Sidub Inc.
+Proprietary licenses available at https://sidub.ca/
+© Sidub Inc.

package/dist/index.d.ts

@@ -1,16 +1,24 @@
 import React, { ReactNode } from 'react';
 
 /**
- * Error class for licensing-related errors
+ * Error class for licensing-related errors.
+ * Thrown when API requests fail, authorization is denied, or network errors occur.
  */
 declare class LicensingError extends Error {
     statusCode?: number | undefined;
     response?: unknown | undefined;
+    /**
+     * Creates a new licensing error.
+     * @param message A description of the error.
+     * @param statusCode The HTTP status code from the server response, if applicable.
+     * @param response The raw response body from the server, if available.
+     */
     constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
 }
 
 /**
- * License classification types
+ * License classification types defining the licensing model.
+ * Matches the .NET LicenseClassificationType enum.
  */
 declare enum LicenseClassificationType {
     /** Perpetual license with no expiration */
@@ -23,21 +31,32 @@ declare enum LicenseClassificationType {
 /**
  * Normalizes a license classification value from server integer or string to the TypeScript enum.
  * The .NET server serializes enums as integers (0=Trial, 1=Subscription, 2=Perpetual).
+ *
+ * @param value The raw value from the server response (integer, string, null, or undefined).
+ * @returns The normalized enum value, or undefined if the input cannot be mapped.
  */
 declare function normalizeLicenseClassificationType(value: number | string | null | undefined): LicenseClassificationType | undefined;
 /**
  * Billing interval units for subscription licenses.
- * Matches .NET BillingIntervalUnit enum with singular names.
+ * Matches the .NET BillingIntervalUnit enum with singular names.
  */
 declare enum BillingIntervalUnit {
+    /** Hourly billing interval. */
     Hour = "Hour",
+    /** Daily billing interval. */
     Day = "Day",
+    /** Weekly billing interval. */
     Week = "Week",
+    /** Monthly billing interval. */
     Month = "Month",
+    /** Yearly billing interval. */
     Year = "Year"
 }
 /**
  * Normalizes a billing interval unit value from server integer or string to the TypeScript enum.
+ *
+ * @param value The raw value from the server response (integer, string, null, or undefined).
+ * @returns The normalized enum value, or undefined if the input cannot be mapped.
  */
 declare function normalizeBillingIntervalUnit(value: number | string | null | undefined): BillingIntervalUnit | undefined;
 
@@ -377,25 +396,33 @@ declare abstract class LicenseAssertion<T extends ILicenseFeature = ILicenseFeat
 }
 
 /**
- * Service access level types
+ * Service access levels for feature authorization.
+ * Matches the .NET ServiceAccessLevel enum.
  */
 declare enum ServiceAccessLevel {
+    /** Access to the feature is denied. */
     Denied = "Denied",
+    /** Access to the feature is allowed. */
     Allowed = "Allowed"
 }
 /**
  * Normalizes a service access level value from server integer or string to the TypeScript enum.
  * The .NET server serializes enums as integers (0=Denied, 1=Allowed).
+ *
+ * @param value The raw value from the server response (integer, string, null, or undefined).
+ * @returns The normalized enum value, or undefined if the input cannot be mapped.
  */
 declare function normalizeServiceAccessLevel(value: number | string | null | undefined): ServiceAccessLevel | undefined;
 /**
- * Service access license feature with access control
+ * Service access license feature with binary access control.
+ * Extends the base feature with service type and access level metadata.
  */
 interface ServiceAccessLicenseFeature extends ILicenseFeature {
+    /** Unique identifier for the feature. */
     featureId: string;
-    /** Service type identifier */
+    /** Optional service type identifier for finer-grained access control. */
     serviceType?: string;
-    /** Access level for this feature */
+    /** The access level granted for this feature (Allowed or Denied). */
     serviceAccessLevel?: ServiceAccessLevel;
 }
 /**
@@ -442,23 +469,35 @@ declare class ServiceAccessAssertion extends LicenseAssertion<ServiceAccessLicen
 declare class RateLimitFeatureState {
     private metrics;
     private sampleSeconds;
+    /**
+     * Creates a new rate limit feature state tracker.
+     * @param sampleSeconds The sliding window duration in seconds for rate limit evaluation.
+     */
     constructor(sampleSeconds: number);
-    /** Records a consumption event with the current timestamp */
+    /**
+     * Records a consumption event with the current timestamp.
+     * @param amount The quantity consumed in this event.
+     */
     consumeRate(amount: number): void;
-    /** Returns total consumption within the sample window, pruning stale entries */
+    /**
+     * Returns total consumption within the sample window, pruning stale entries.
+     * @returns The sum of all consumption amounts within the sliding window.
+     */
     getConsumption(): number;
 }
 
 /**
- * Rate limit license feature with consumption tracking
+ * Rate limit license feature with consumption tracking.
+ * Extends the base feature with rate limiting metadata and usage counters.
  */
 interface RateLimitLicenseFeature extends ILicenseFeature {
+    /** Unique identifier for the feature. */
     featureId: string;
-    /** Sample period in seconds */
+    /** Sliding window duration in seconds for rate limit evaluation. */
     sampleSeconds?: number;
-    /** Rate limit (max requests per sample period) */
+    /** Maximum allowed consumption within the sample window. */
     rateLimit?: number;
-    /** Current consumption count */
+    /** Current server-reported consumption count within the sample window. */
     currentConsumption?: number;
 }
 /**
@@ -593,11 +632,15 @@ declare class NotAssertion extends LicenseAssertion {
 }
 
 /**
- * Parameters for generating a license authorization
+ * Parameters for generating a license authorization request.
+ * Sent to the server to retrieve a signed license authorization.
  */
 interface GenerateLicenseAuthorizationParameters {
+    /** Optional request identifier for tracking and idempotency. */
     RequestId?: string;
+    /** Optional license classification filter. */
     LicenseClassification?: LicenseClassificationType;
+    /** The unique identifier of the license to authorize. */
     LicenseId: string;
 }
 /**
@@ -669,28 +712,37 @@ declare class LicensingClient {
      */
     private normalizeSignature;
     /**
-     * Asserts whether a license condition is satisfied using the provided assertion.
-     * This evaluates the assertion against a license authorization.
+     * Evaluates a license assertion against a license authorization.
+     * Returns whether the assertion condition (feature access, rate limit, etc.) is satisfied.
      *
-     * @param assertion The license assertion to evaluate
-     * @param authorization The license authorization to check against (if not provided, you must call getAuthorization first)
-     * @returns True if the assertion is satisfied, false otherwise
-     *
-     * @example
-     * ```typescript
-     * const authorization = await client.getAuthorization('license-id');
-     * const assertion = ServiceAccessAssertion.create('premium-features');
-     * const hasAccess = client.assertLicense(assertion, authorization);
-     * ```
+     * @template T The type of license feature the assertion operates on.
+     * @param assertion The license assertion to evaluate.
+     * @param authorization The license authorization to check against.
+     * @returns True if the assertion is satisfied, false otherwise.
      */
     assertLicense<T extends ILicenseFeature = ILicenseFeature>(assertion: ILicenseAssertion<T>, authorization: LicenseAuthorization): boolean;
-    /** Clears all cached authorizations */
+    /**
+     * Clears all cached authorizations.
+     */
     clearCache(): void;
-    /** Invalidates all cached authorizations for a specific license */
+    /**
+     * Invalidates all cached authorizations for a specific license.
+     * @param licenseId The license identifier to invalidate.
+     */
     invalidateCache(licenseId: string): void;
-    /** Gets the local feature state for a license+feature combination */
+    /**
+     * Gets the local feature state for a license+feature combination.
+     * @param licenseId The license identifier.
+     * @param featureKey The feature key.
+     * @returns The rate limit feature state tracker, or undefined if no state exists.
+     */
     getFeatureState(licenseId: string, featureKey: string): RateLimitFeatureState | undefined;
-    /** Sets/replaces the local feature state for a license+feature combination */
+    /**
+     * Sets or replaces the local feature state for a license+feature combination.
+     * @param licenseId The license identifier.
+     * @param featureKey The feature key.
+     * @param state The rate limit feature state tracker to associate.
+     */
     setFeatureState(licenseId: string, featureKey: string, state: RateLimitFeatureState): void;
     /**
      * Reports license feature consumption/usage to the server.
@@ -757,12 +809,21 @@ declare class LicensingClient {
         maxAttempts?: number;
     }): Promise<CheckoutSessionResult>;
     /**
-     * Gets the current configuration
+     * Gets the current licensing configuration.
+     * @returns A read-only copy of the resolved configuration.
      */
     getConfig(): Readonly<LicensingConfig>;
 }
 
+/**
+ * Error thrown when the licensing client is misconfigured.
+ * Indicates missing or invalid configuration values such as a missing license ID or service URI.
+ */
 declare class LicensingConfigurationException extends LicensingError {
+    /**
+     * Creates a new configuration exception.
+     * @param message A description of the configuration error.
+     */
     constructor(message: string);
 }
 
@@ -786,6 +847,10 @@ interface CryptoConfig {
 declare class CryptoService {
     private publicKey;
     private readonly config;
+    /**
+     * Creates a new cryptography service instance.
+     * @param config The cryptography configuration containing the public key for verification.
+     */
     constructor(config: CryptoConfig);
     /**
      * Gets the service key ID
@@ -811,10 +876,16 @@ declare class CryptoService {
     private base64ToArrayBuffer;
 }
 /**
- * Error class for cryptography-related errors
+ * Error class for cryptography-related errors.
+ * Contains a machine-readable error code for programmatic handling.
  */
 declare class CryptoError extends Error {
     readonly code: 'KEY_IMPORT_FAILED' | 'VERIFICATION_FAILED' | 'NOT_INITIALIZED' | 'INVALID_SIGNATURE';
+    /**
+     * Creates a new cryptography error.
+     * @param message A description of the cryptographic failure.
+     * @param code A machine-readable error code identifying the failure type.
+     */
     constructor(message: string, code: 'KEY_IMPORT_FAILED' | 'VERIFICATION_FAILED' | 'NOT_INITIALIZED' | 'INVALID_SIGNATURE');
 }
 
@@ -909,20 +980,35 @@ declare class SignatureValidator {
 declare class AuthorizationCache {
     private cache;
     private maxSize;
+    /**
+     * Creates a new authorization cache.
+     * @param maxSize The maximum number of entries to store before evicting the oldest. Defaults to 100.
+     */
     constructor(maxSize?: number);
     /**
      * Gets a cached authorization if it exists and has not expired.
      * On hit, re-inserts the entry to move it to the end (pseudo-LRU freshness).
+     *
+     * @param licenseId The license identifier.
+     * @param serviceKeyId The service key identifier.
+     * @returns The cached authorization, or null if not cached or expired.
      */
     get(licenseId: string, serviceKeyId: string): LicenseAuthorization | null;
     /**
      * Stores an authorization in the cache.
      * Evicts the oldest entry if max size is reached.
+     *
+     * @param licenseId The license identifier.
+     * @param serviceKeyId The service key identifier.
+     * @param authorization The license authorization to cache.
      */
     set(licenseId: string, serviceKeyId: string, authorization: LicenseAuthorization): void;
     /** Removes all cached entries */
     clearCache(): void;
-    /** Removes all cached entries for a specific license across all service keys */
+    /**
+     * Removes all cached entries for a specific license across all service keys.
+     * @param licenseId The license identifier to invalidate.
+     */
     invalidate(licenseId: string): void;
 }
 
@@ -1013,21 +1099,35 @@ declare const useLicensingContextValue: () => LicensingContextValue;
  * Named LicensingContextType to avoid collision with the React context in LicensingContext.tsx.
  */
 interface LicensingContextType {
+    /** Unique identifier for the license. */
     licenseId: string;
+    /** Unique identifier for the service key used for signature verification. */
     serviceKeyId: string;
+    /** Base64-encoded public key for cryptographic signature verification. */
     serviceKeyPublicMember: string;
+    /** API access key for authenticating requests to the licensing service. */
     apiAccessKey: string;
+    /** Optional billable resource identifier for consumption metering (GUID string). */
     billableResourceId?: string;
+    /** Optional billable plan identifier for consumption metering. */
     billablePlanId?: string;
 }
 /**
  * Creates a LicensingContextType from an encoded credential string.
  * Billable fields are NOT included in the encoding (per .NET behavior) and must be provided separately.
+ *
+ * @param encoded The encoded credential string (SIDUB_LIC_...) to decode.
+ * @param billableResourceId Optional billable resource identifier for consumption metering.
+ * @param billablePlanId Optional billable plan identifier for consumption metering.
+ * @returns A fully-populated licensing context.
  */
 declare function licensingContextFromEncodedString(encoded: string, billableResourceId?: string, billablePlanId?: string): LicensingContextType;
 /**
  * Encodes a LicensingContextType to a portable string.
  * Per .NET behavior: only the 4 credential fields are encoded, NOT billable fields.
+ *
+ * @param context The licensing context to encode.
+ * @returns A portable encoded string prefixed with SIDUB_LIC_.
  */
 declare function licensingContextToEncodedString(context: LicensingContextType): string;
 
@@ -1039,6 +1139,10 @@ declare function licensingContextToEncodedString(context: LicensingContextType):
  * (e.g., per-tenant lookup from database or session store).
  */
 interface ILicensingContextProvider {
+    /**
+     * Resolves the licensing context for the current tenant or user.
+     * @returns The resolved licensing context, or null if no credentials are available.
+     */
     resolveContext(): Promise<LicensingContextType | null>;
 }
 
@@ -1050,7 +1154,16 @@ interface ILicensingContextProvider {
 declare class ConfigurationContextProvider implements ILicensingContextProvider {
     private readonly config;
     private cached;
+    /**
+     * Creates a new configuration-based context provider.
+     * @param config The licensing configuration to extract credentials from.
+     */
     constructor(config: LicensingConfig);
+    /**
+     * Resolves licensing context from the configured credentials.
+     * Returns null if no credentials are available. Caches the result after first call.
+     * @returns The resolved licensing context, or null if no credentials are configured.
+     */
     resolveContext(): Promise<LicensingContextType | null>;
 }