@sidub-inc/licensing-client 1.4.0 → 1.5.51

package/dist/index.d.ts

@@ -16,6 +16,26 @@ declare class LicensingError extends Error {
     constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
 }
 
+/**
+ * SEM-03 / Phase 11 D-14: thrown by `LicensingClient.assertLicense` when a
+ * rate-limited feature's assertion evaluates false.
+ *
+ * Distinguishable from transient network errors by type alone:
+ *   `catch (e) { if (e instanceof RateLimitError) { ... } }`
+ *
+ * Matches the .NET `Sidub.Licensing.Client.Exceptions.RateLimitException` shape.
+ * Minimal surface — only `featureKey` and `message`. No retry-after, no counters.
+ */
+declare class RateLimitError extends Error {
+    readonly featureKey: string;
+    /**
+     * Creates a new RateLimitError.
+     * @param featureKey The key of the feature whose rate limit was exceeded.
+     * @param message A human-readable description of the violation.
+     */
+    constructor(featureKey: string, message: string);
+}
+
 /**
  * License classification types defining the licensing model.
  * Matches the .NET LicenseClassificationType enum.
@@ -201,6 +221,46 @@ interface ClientLicenseConfiguration {
     /** Configuration metadata */
     metadata?: Record<string, unknown>;
 }
+/**
+ * Per-feature view returned by LicensingClient.getState().
+ */
+interface FeatureView {
+    /** Unique feature key (matches the key used in assertions). */
+    featureKey: string;
+    /** Human-readable display name for the feature. */
+    displayName: string;
+}
+/**
+ * Per-feature consumption snapshot for rate-limited features.
+ * `percentage` is a RAW number 0..100+ — no bucketing applied.
+ */
+interface ConsumptionView {
+    /** Feature key this measurement belongs to. */
+    featureKey: string;
+    /** Local consumption count within the current sliding window. */
+    currentUsage: number;
+    /** Maximum allowed within the window (from authorization). */
+    limit: number;
+    /** Sliding-window duration in seconds. */
+    windowSeconds: number;
+    /** Ratio of currentUsage to limit expressed as a percentage (may exceed 100). */
+    percentage: number;
+}
+/**
+ * Composite license-state snapshot returned by LicensingClient.getState().
+ * Provides a framework-agnostic read-model suitable for display or serialization
+ * without exposing internal SKU IDs, pricing, or other-customer PII.
+ */
+interface LicenseStateView {
+    /** Unique identifier of the active license. */
+    licenseId: string;
+    /** All features granted by the license. */
+    features: FeatureView[];
+    /** Consumption data for rate-limited features only (empty when none are active). */
+    consumption: ConsumptionView[];
+    /** Authorization expiry, or null if the authorization has no expiry. */
+    expiry: Date | null;
+}
 
 /**
  * Licensing credential containing the essential license identification and authentication values.
@@ -465,15 +525,21 @@ declare class ServiceAccessAssertion extends LicenseAssertion<ServiceAccessLicen
  *
  * Entries older than sampleSeconds are pruned on every getConsumption() call.
  * Local state is additive/conservative — may over-count (safer than under-counting).
+ *
+ * When a storageKey is provided, metrics are persisted to localStorage and restored
+ * on construction, surviving page refreshes. Cross-tab sync is available via onSync().
  */
 declare class RateLimitFeatureState {
     private metrics;
     private sampleSeconds;
+    private storageKey;
+    private unsubscribe;
     /**
      * Creates a new rate limit feature state tracker.
      * @param sampleSeconds The sliding window duration in seconds for rate limit evaluation.
+     * @param storageKey Optional localStorage key for persisting metrics across page refreshes.
      */
-    constructor(sampleSeconds: number);
+    constructor(sampleSeconds: number, storageKey?: string);
     /**
      * Records a consumption event with the current timestamp.
      * @param amount The quantity consumed in this event.
@@ -484,6 +550,18 @@ declare class RateLimitFeatureState {
      * @returns The sum of all consumption amounts within the sliding window.
      */
     getConsumption(): number;
+    /**
+     * Registers a cross-tab sync listener. When another tab modifies the same storageKey,
+     * the in-memory metrics are replaced with the new values and the callback is invoked.
+     *
+     * @param callback Invoked after in-memory state is updated from another tab.
+     * @returns An unsubscribe function to remove the listener.
+     */
+    onSync(callback: () => void): () => void;
+    /**
+     * Removes the cross-tab sync listener if active.
+     */
+    dispose(): void;
 }
 
 /**
@@ -651,20 +729,32 @@ interface GenerateLicenseAuthorizationParameters {
  */
 declare class LicensingClient {
     private config;
-    private readonly credential;
+    private credential;
     private signatureValidator;
     private validateSignatures;
     private readonly authorizationCache;
     private readonly cacheEnabled;
     private readonly featureStates;
     private readonly featureMetadata;
+    private readonly disposables;
     private contextResolved;
     private contextResolutionPromise;
+    private static readonly METADATA_STORAGE_KEY;
+    private static readonly CONSUMPTION_STORAGE_PREFIX;
+    private static readonly AUTH_STORAGE_PREFIX;
     /**
      * Creates a new instance of the LicensingClient
      * @param config Configuration for the licensing service
      */
     constructor(config: LicensingConfig);
+    /**
+     * Restores RateLimitFeatureState instances from localStorage for all known features.
+     */
+    private restoreFeatureStates;
+    /**
+     * Persists the featureMetadata map to localStorage.
+     */
+    private persistFeatureMetadata;
     /**
      * Ensures context provider has been resolved before making API calls.
      * Called once per client lifetime; concurrent callers share the same promise.
@@ -720,6 +810,23 @@ declare class LicensingClient {
      * @param authorization The license authorization to check against.
      * @returns True if the assertion is satisfied, false otherwise.
      */
+    /**
+     * Phase 11 D-01 (LCYC-02): Composes an in-memory LicenseStateView from the current
+     * authorization. Returns null when no license is configured or the authorization cannot
+     * be retrieved.
+     */
+    getState(): Promise<LicenseStateView | null>;
+    /**
+     * Phase 11 D-11 (LCYC-06): Invalidates all cached state and rebuilds internal credential
+     * configuration from a new encodedCredential — without requiring a React component remount.
+     *
+     * Call this from a useEffect keyed on the credential string; the `key={credential}` idiom
+     * is a deprecated fallback.
+     *
+     * @param newConfig A LicensingConfig carrying the updated encodedCredential (all other
+     *   fields are merged; explicit fields on newConfig take precedence).
+     */
+    refresh(newConfig: LicensingConfig): Promise<void>;
     assertLicense<T extends ILicenseFeature = ILicenseFeature>(assertion: ILicenseAssertion<T>, authorization: LicenseAuthorization): boolean;
     /**
      * Clears all cached authorizations.
@@ -730,6 +837,12 @@ declare class LicensingClient {
      * @param licenseId The license identifier to invalidate.
      */
     invalidateCache(licenseId: string): void;
+    /**
+     * Releases all resources held by this client instance:
+     * removes cross-tab StorageEvent listeners and disposes cache/state objects.
+     * Call this when the client is no longer needed (e.g., on component unmount).
+     */
+    dispose(): void;
     /**
      * Gets the local feature state for a license+feature combination.
      * @param licenseId The license identifier.
@@ -973,18 +1086,24 @@ declare class SignatureValidator {
 }
 
 /**
- * In-memory authorization cache with TTL-based expiry and pseudo-LRU eviction.
+ * Authorization cache with TTL-based expiry, pseudo-LRU eviction, and localStorage persistence.
  * Cache key format: {licenseId}.{serviceKeyId}
  * One cache instance per LicensingClient — no singletons.
+ *
+ * When a storagePrefix is provided, entries are persisted to localStorage and restored
+ * on construction, surviving page refreshes. Cross-tab sync is available via onSync().
  */
 declare class AuthorizationCache {
     private cache;
     private maxSize;
+    private storagePrefix;
+    private unsubscribe;
     /**
      * Creates a new authorization cache.
      * @param maxSize The maximum number of entries to store before evicting the oldest. Defaults to 100.
+     * @param storagePrefix Optional localStorage key prefix for persisting entries across page refreshes.
      */
-    constructor(maxSize?: number);
+    constructor(maxSize?: number, storagePrefix?: string);
     /**
      * 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).
@@ -1010,8 +1129,64 @@ declare class AuthorizationCache {
      * @param licenseId The license identifier to invalidate.
      */
     invalidate(licenseId: string): void;
+    /**
+     * Registers a cross-tab sync listener. When another tab modifies auth cache entries,
+     * the in-memory cache is updated and the callback is invoked.
+     *
+     * @param callback Invoked after in-memory state is updated from another tab.
+     * @returns An unsubscribe function to remove the listener.
+     */
+    onSync(callback: () => void): () => void;
+    /**
+     * Removes the cross-tab sync listener if active.
+     */
+    dispose(): void;
+    /**
+     * Serializes a cache entry for localStorage storage.
+     * Converts Date objects to epoch numbers for safe JSON round-tripping.
+     */
+    private serializeEntry;
+    /**
+     * Deserializes a cache entry from localStorage, reconstructing Date objects.
+     */
+    private deserializeEntry;
 }
 
+/**
+ * Thin localStorage abstraction for persisting SDK state across page refreshes.
+ * All methods are SSR-safe — they no-op when `window`/`localStorage` is unavailable.
+ *
+ * Used by RateLimitFeatureState and AuthorizationCache for transparent persistence.
+ */
+/**
+ * Serializes and stores a value under the given key.
+ * No-op in SSR/Node environments.
+ */
+declare function save<T>(key: string, data: T): void;
+/**
+ * Loads and deserializes a value from the given key.
+ * Returns null if the key is missing, the value cannot be parsed, or in SSR.
+ */
+declare function load<T>(key: string): T | null;
+/**
+ * Removes a value from localStorage.
+ * No-op in SSR/Node environments.
+ */
+declare function remove(key: string): void;
+/**
+ * Returns all localStorage keys that start with the given prefix.
+ * Returns an empty array in SSR/Node environments.
+ */
+declare function listKeys(prefix: string): string[];
+/**
+ * Registers a listener for localStorage changes from OTHER tabs.
+ * Filters events by key prefix and calls the callback with the full key and new value.
+ *
+ * Returns an unsubscribe function that removes the listener.
+ * Returns a no-op in SSR/Node environments.
+ */
+declare function onStorageChange(prefix: string, callback: (key: string, newValue: string | null) => void): () => void;
+
 /**
  * Context for providing the LicensingClient to React components
  */
@@ -1167,5 +1342,5 @@ declare class ConfigurationContextProvider implements ILicensingContextProvider
     resolveContext(): Promise<LicensingContextType | null>;
 }
 
-export { AuthorizationCache, BillingIntervalUnit, CompositeAssertion, ConfigurationContextProvider, CryptoError, CryptoService, FeatureExistsAssertion, LicenseAssertion, LicenseClassificationType, LicensingClient, LicensingConfigurationException, LicensingError, LicensingProvider, NotAssertion, RateLimitAssertion, RateLimitFeatureState, ServiceAccessAssertion, ServiceAccessLevel, SignatureValidator, decodeCredential, encodeCredential, findFeatureByKey, getFeatureKey, hasFeature, hasValidCryptoConfig, licensingContextFromEncodedString, licensingContextToEncodedString, matchesFeatureKey, normalizeBillingIntervalUnit, normalizeLicenseClassificationType, normalizeServiceAccessLevel, tryDecodeCredential, useLicensingContext, useLicensingContextValue };
-export type { CheckoutRequest, CheckoutSession, CheckoutSessionResult, CheckoutSessionStatus, ClientLicenseConfiguration, CryptoConfig, GenerateLicenseAuthorizationParameters, ILicenseAssertion, ILicenseFeature, ILicensingContextProvider, License, LicenseAuthorization, LicenseFeatureStateOperation, LicensingConfig, LicensingContextType, LicensingCredential, LicensingProviderProps, RateAgreement, RateLimitLicenseFeature, RawAuthorizationResponse, ServerFeature, ServiceAccessLicenseFeature, SignatureValidationOptions, SignatureValidationResult };
+export { AuthorizationCache, BillingIntervalUnit, CompositeAssertion, ConfigurationContextProvider, CryptoError, CryptoService, FeatureExistsAssertion, LicenseAssertion, LicenseClassificationType, LicensingClient, LicensingConfigurationException, LicensingError, LicensingProvider, NotAssertion, RateLimitAssertion, RateLimitError, RateLimitFeatureState, ServiceAccessAssertion, ServiceAccessLevel, SignatureValidator, decodeCredential, encodeCredential, findFeatureByKey, getFeatureKey, hasFeature, hasValidCryptoConfig, licensingContextFromEncodedString, licensingContextToEncodedString, listKeys, load, matchesFeatureKey, normalizeBillingIntervalUnit, normalizeLicenseClassificationType, normalizeServiceAccessLevel, onStorageChange, remove, save, tryDecodeCredential, useLicensingContext, useLicensingContextValue };
+export type { CheckoutRequest, CheckoutSession, CheckoutSessionResult, CheckoutSessionStatus, ClientLicenseConfiguration, ConsumptionView, CryptoConfig, FeatureView, GenerateLicenseAuthorizationParameters, ILicenseAssertion, ILicenseFeature, ILicensingContextProvider, License, LicenseAuthorization, LicenseFeatureStateOperation, LicenseStateView, LicensingConfig, LicensingContextType, LicensingCredential, LicensingProviderProps, RateAgreement, RateLimitLicenseFeature, RawAuthorizationResponse, ServerFeature, ServiceAccessLicenseFeature, SignatureValidationOptions, SignatureValidationResult };