@sidub-inc/licensing-client 1.3.43

package/dist/index.d.ts

@@ -0,0 +1,1058 @@
+import React, { ReactNode } from 'react';
+
+/**
+ * Error class for licensing-related errors
+ */
+declare class LicensingError extends Error {
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+
+/**
+ * License classification types
+ */
+declare enum LicenseClassificationType {
+    /** Perpetual license with no expiration */
+    Perpetual = "Perpetual",
+    /** Subscription license with recurring billing */
+    Subscription = "Subscription",
+    /** Trial license with time-based expiration */
+    Trial = "Trial"
+}
+/**
+ * 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).
+ */
+declare function normalizeLicenseClassificationType(value: number | string | null | undefined): LicenseClassificationType | undefined;
+/**
+ * Billing interval units for subscription licenses.
+ * Matches .NET BillingIntervalUnit enum with singular names.
+ */
+declare enum BillingIntervalUnit {
+    Hour = "Hour",
+    Day = "Day",
+    Week = "Week",
+    Month = "Month",
+    Year = "Year"
+}
+/**
+ * Normalizes a billing interval unit value from server integer or string to the TypeScript enum.
+ */
+declare function normalizeBillingIntervalUnit(value: number | string | null | undefined): BillingIntervalUnit | undefined;
+
+/**
+ * Base interface for license features
+ */
+interface ILicenseFeature {
+    /** Unique identifier for the feature type */
+    featureId: string;
+}
+/**
+ * Rate agreement for subscription-based licenses
+ */
+interface RateAgreement {
+    /** Amount charged per billing interval */
+    amount: number;
+    /** Currency code (e.g., 'USD', 'EUR') */
+    currency: string;
+    /** Billing interval (e.g., 1, 3, 12) */
+    billingInterval?: number;
+    /** Unit of billing interval */
+    billingIntervalUnit?: BillingIntervalUnit;
+}
+/**
+ * License information returned from the server
+ */
+interface License {
+    /** Unique identifier for the license */
+    licenseId: string;
+    /** Client ID this license belongs to */
+    clientId: string;
+    /** Issuer client ID */
+    issuerClientId: string;
+    /** License classification */
+    classification: LicenseClassificationType;
+    /** Display name for the license */
+    name: string;
+    /** Features included in the license */
+    features?: ILicenseFeature[];
+    /** Rate agreement for subscription licenses */
+    rateAgreement?: RateAgreement;
+    /** Creation timestamp */
+    createdAt?: Date;
+    /** Last updated timestamp */
+    updatedAt?: Date;
+}
+/**
+ * License authorization containing validated license information.
+ * Includes cryptographic signature for integrity verification.
+ */
+interface LicenseAuthorization {
+    /** Unique identifier for the authorization */
+    authorizationId?: string;
+    /** Unique identifier for the license */
+    licenseId: string;
+    /** License classification */
+    classification: LicenseClassificationType;
+    /** Features available in this authorization */
+    features: ILicenseFeature[];
+    /** When this authorization was issued */
+    issuedAt: Date;
+    /** When this authorization expires (optional) */
+    expiresAt?: Date;
+    /** Base64-encoded cryptographic signature for integrity verification */
+    signature?: string;
+    /** Whether signature has been validated */
+    signatureValidated?: boolean;
+}
+/**
+ * License feature state operation for consumption reporting
+ */
+interface LicenseFeatureStateOperation<T extends ILicenseFeature> {
+    /** License ID */
+    licenseId: string;
+    /** Feature being consumed */
+    feature: T;
+    /** Operation type (e.g., 'increment', 'decrement') */
+    operationType: string;
+    /** Quantity of consumption */
+    quantity?: number;
+    /** Timestamp of the operation */
+    timestamp: Date;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for the licensing client
+ */
+interface LicensingConfig {
+    /** Base URI for the licensing service */
+    licenseServiceUri: string;
+    /** Optional: Base URI for consumption reporting service */
+    consumptionServiceUri?: string;
+    /** Optional: Default API key for authentication */
+    apiKey?: string;
+    /** Optional: Timeout for HTTP requests in milliseconds */
+    timeout?: number;
+    /**
+     * Optional: Encoded credential string (SIDUB_LIC_...) containing all license credentials.
+     * If provided, this will be decoded to extract licenseId, serviceKeyId, serviceKeyPublicMember, and apiKey.
+     */
+    encodedCredential?: string;
+    /** Optional: Service key ID for signature verification (extracted from encodedCredential if not set) */
+    serviceKeyId?: string;
+    /** Optional: Base64-encoded public key for signature verification (extracted from encodedCredential if not set) */
+    serviceKeyPublicMember?: string;
+    /** Optional: License ID (extracted from encodedCredential if not set) */
+    licenseId?: string;
+    /**
+     * Optional: Whether to validate authorization signatures (default: true if crypto config available).
+     * Set to false to disable signature validation (not recommended for production).
+     */
+    validateSignatures?: boolean;
+    /** Optional: Billable resource ID for consumption metering (GUID string) */
+    billableResourceId?: string;
+    /** Optional: Billable plan ID for consumption metering */
+    billablePlanId?: string;
+    /** Optional: Enable or disable authorization caching (default: true) */
+    cacheEnabled?: boolean;
+    /** Optional: Maximum number of cached authorizations (default: 100) */
+    cacheMaxSize?: number;
+    /** Optional: Custom context provider for multi-tenant credential resolution */
+    contextProvider?: {
+        resolveContext(): Promise<{
+            licenseId: string;
+            serviceKeyId: string;
+            serviceKeyPublicMember: string;
+            apiAccessKey: string;
+            billableResourceId?: string;
+            billablePlanId?: string;
+        } | null>;
+    };
+}
+/**
+ * Client license configuration
+ */
+interface ClientLicenseConfiguration {
+    /** Client ID */
+    clientId: string;
+    /** API key for the client */
+    apiKey: string;
+    /** Configuration metadata */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Licensing credential containing the essential license identification and authentication values.
+ * This matches the .NET LicensingCredential record for cross-platform compatibility.
+ */
+interface LicensingCredential {
+    /** Unique identifier for the license */
+    licenseId: string;
+    /** Unique identifier for the service key used for signature verification */
+    serviceKeyId: string;
+    /** Base64-encoded public key for signature verification */
+    serviceKeyPublicMember: string;
+    /** API access key for authentication */
+    apiAccessKey: string;
+}
+/**
+ * Encodes a licensing credential to a portable string.
+ * This matches the .NET LicensingCredential.ToEncodedString() format.
+ *
+ * @param credential The credential to encode
+ * @returns A portable encoded string prefixed with SIDUB_LIC_
+ */
+declare function encodeCredential(credential: LicensingCredential): string;
+/**
+ * Decodes a licensing credential from an encoded string.
+ * This matches the .NET LicensingCredential.FromEncodedString() format.
+ *
+ * @param encodedString The encoded credential string
+ * @returns The decoded credential
+ * @throws {Error} If the format is invalid
+ */
+declare function decodeCredential(encodedString: string): LicensingCredential;
+/**
+ * Attempts to parse an encoded credential string.
+ *
+ * @param encodedString The encoded credential string
+ * @returns The decoded credential, or null if parsing failed
+ */
+declare function tryDecodeCredential(encodedString: string | null | undefined): LicensingCredential | null;
+/**
+ * Validates that a credential has all required fields for signature verification.
+ *
+ * @param credential The credential to validate
+ * @returns True if the credential has all required cryptography fields
+ */
+declare function hasValidCryptoConfig(credential: LicensingCredential | null | undefined): boolean;
+
+/**
+ * Extended feature interface that accounts for server response casing variations.
+ * The server may return features with PascalCase (FeatureKey) or camelCase (featureId).
+ */
+interface ServerFeature extends ILicenseFeature {
+    /** Server-side PascalCase feature key */
+    FeatureKey?: string;
+    /** Server-side service access level (PascalCase, may be string or integer) */
+    ServiceAccessLevel?: string | number;
+    /** Server-side sample seconds (PascalCase) */
+    SampleSeconds?: number;
+    /** Server-side rate limit (PascalCase) */
+    RateLimit?: number;
+    /** Server-side current consumption (PascalCase) */
+    CurrentConsumption?: number;
+    /** Client-side service access level (camelCase) */
+    serviceAccessLevel?: string;
+    /** Client-side sample seconds (camelCase) */
+    sampleSeconds?: number;
+    /** Client-side rate limit (camelCase) */
+    rateLimit?: number;
+    /** Client-side current consumption (camelCase) */
+    currentConsumption?: number;
+    /** Additional server properties */
+    [key: string]: unknown;
+}
+/**
+ * Gets the normalized feature key from a feature object.
+ * Handles both client-side (featureId) and server-side (FeatureKey) naming conventions.
+ *
+ * @param feature The feature object to extract the key from
+ * @returns The feature key, or empty string if not found
+ */
+declare function getFeatureKey(feature: ILicenseFeature | ServerFeature): string;
+/**
+ * Checks if a feature matches the specified feature key.
+ * Handles both client-side (featureId) and server-side (FeatureKey) naming conventions.
+ *
+ * @param feature The feature to check
+ * @param featureKey The key to match against
+ * @returns True if the feature matches the key
+ */
+declare function matchesFeatureKey(feature: ILicenseFeature | ServerFeature, featureKey: string): boolean;
+/**
+ * Finds a feature by key in a feature array.
+ *
+ * @param features Array of features to search
+ * @param featureKey The key to find
+ * @returns The matching feature, or undefined if not found
+ */
+declare function findFeatureByKey<T extends ILicenseFeature>(features: T[] | undefined | null, featureKey: string): T | undefined;
+/**
+ * Checks if a feature with the specified key exists in the array.
+ *
+ * @param features Array of features to search
+ * @param featureKey The key to check for
+ * @returns True if a feature with the key exists
+ */
+declare function hasFeature(features: ILicenseFeature[] | undefined | null, featureKey: string): boolean;
+
+/**
+ * Status of a checkout session.
+ */
+type CheckoutSessionStatus = 'pending' | 'completed' | 'failed';
+/**
+ * Request parameters for creating an embedded checkout session.
+ * Matches .NET CreateCheckoutSessionParameters entity.
+ */
+interface CheckoutRequest {
+    /** The offering to purchase */
+    offeringId: string;
+    /** The issuer client ID */
+    issuerClientId: string;
+    /** Correlation ID for tracking this checkout across systems */
+    correlationId: string;
+    /** Customer email address */
+    customerEmail: string;
+    /** URL to redirect to on successful checkout (absolute HTTPS URL) */
+    successUrl?: string;
+    /** URL to redirect to on cancelled checkout (absolute HTTPS URL) */
+    cancelUrl?: string;
+}
+/**
+ * Response from creating a checkout session.
+ * Matches .NET CheckoutSession entity.
+ */
+interface CheckoutSession {
+    /** Unique session identifier */
+    sessionId: string;
+    /** Payment provider URL for checkout (null for free/trial offerings) */
+    sessionUrl?: string | null;
+}
+/**
+ * Result of polling a checkout session for completion.
+ * Matches .NET CheckoutSessionResult entity.
+ */
+interface CheckoutSessionResult {
+    /** Current session status */
+    status: CheckoutSessionStatus;
+    /** Correlation ID from the original request */
+    correlationId?: string;
+    /** Encoded licensing credential (SIDUB_LIC_...) — present when status is 'completed' */
+    encodedCredential?: string;
+    /** License ID provisioned by checkout — present when status is 'completed' */
+    licenseId?: string;
+    /** Offering ID from the original request */
+    offeringId?: string;
+    /** Error message — present when status is 'failed' */
+    error?: string;
+}
+
+/**
+ * Base interface for license assertions.
+ * Assertions encapsulate the logic for checking if a license satisfies specific conditions.
+ *
+ * @typeParam _T The type of license feature this assertion operates on (for documentation purposes)
+ */
+interface ILicenseAssertion<_T extends ILicenseFeature = ILicenseFeature> {
+    /**
+     * The feature key identifying the license feature this assertion targets.
+     */
+    readonly featureKey: string;
+    /**
+     * Evaluates whether the assertion is satisfied for the given authorization.
+     * @param authorization The license authorization to evaluate
+     * @returns True if the assertion is satisfied, false otherwise
+     */
+    isSatisfied(authorization: LicenseAuthorization): boolean;
+}
+/**
+ * Base class for implementing license assertions.
+ * Provides a foundation for creating custom assertion logic.
+ *
+ * @typeParam T The type of license feature this assertion operates on
+ */
+declare abstract class LicenseAssertion<T extends ILicenseFeature = ILicenseFeature> implements ILicenseAssertion<T> {
+    /**
+     * The feature key identifying the license feature this assertion targets.
+     */
+    abstract readonly featureKey: string;
+    /**
+     * Evaluates whether the assertion is satisfied.
+     * Must be implemented by derived classes.
+     */
+    abstract isSatisfied(authorization: LicenseAuthorization): boolean;
+}
+
+/**
+ * Service access level types
+ */
+declare enum ServiceAccessLevel {
+    Denied = "Denied",
+    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).
+ */
+declare function normalizeServiceAccessLevel(value: number | string | null | undefined): ServiceAccessLevel | undefined;
+/**
+ * Service access license feature with access control
+ */
+interface ServiceAccessLicenseFeature extends ILicenseFeature {
+    featureId: string;
+    /** Service type identifier */
+    serviceType?: string;
+    /** Access level for this feature */
+    serviceAccessLevel?: ServiceAccessLevel;
+}
+/**
+ * Assertion that checks if a service/feature has the required access level.
+ *
+ * @example
+ * ```typescript
+ * // Check if 'premium-features' is allowed
+ * const assertion = ServiceAccessAssertion.create('premium-features', ServiceAccessLevel.Allowed);
+ * const hasAccess = assertion.isSatisfied(authorization);
+ * ```
+ */
+declare class ServiceAccessAssertion extends LicenseAssertion<ServiceAccessLicenseFeature> {
+    readonly requiredAccessLevel: ServiceAccessLevel;
+    readonly serviceType?: string | undefined;
+    readonly featureKey: string;
+    /**
+     * Creates a new service access assertion
+     * @param featureKey The feature key to check
+     * @param requiredAccessLevel The required access level (default: Allowed)
+     * @param serviceType Optional service type to filter by
+     */
+    constructor(featureKey: string, requiredAccessLevel?: ServiceAccessLevel, serviceType?: string | undefined);
+    /**
+     * Checks if the authorization contains the feature with the required access level
+     */
+    isSatisfied(authorization: LicenseAuthorization): boolean;
+    /**
+     * Factory method to create a service access assertion
+     * @param featureKey The feature key to check
+     * @param requiredAccessLevel The required access level (default: Allowed)
+     * @param serviceType Optional service type to filter by
+     */
+    static create(featureKey: string, requiredAccessLevel?: ServiceAccessLevel, serviceType?: string): ServiceAccessAssertion;
+}
+
+/**
+ * Tracks timestamped consumption metrics for a rate-limited feature.
+ * Mirrors the .NET RateLimitLicenseFeatureState pattern.
+ *
+ * Entries older than sampleSeconds are pruned on every getConsumption() call.
+ * Local state is additive/conservative — may over-count (safer than under-counting).
+ */
+declare class RateLimitFeatureState {
+    private metrics;
+    private sampleSeconds;
+    constructor(sampleSeconds: number);
+    /** Records a consumption event with the current timestamp */
+    consumeRate(amount: number): void;
+    /** Returns total consumption within the sample window, pruning stale entries */
+    getConsumption(): number;
+}
+
+/**
+ * Rate limit license feature with consumption tracking
+ */
+interface RateLimitLicenseFeature extends ILicenseFeature {
+    featureId: string;
+    /** Sample period in seconds */
+    sampleSeconds?: number;
+    /** Rate limit (max requests per sample period) */
+    rateLimit?: number;
+    /** Current consumption count */
+    currentConsumption?: number;
+}
+/**
+ * Assertion that checks if a rate-limited feature is within its limit.
+ *
+ * @example
+ * ```typescript
+ * // Key-based construction (preferred)
+ * const assertion = RateLimitAssertion.create('api-calls');
+ * const withinLimit = assertion.isSatisfied(authorization);
+ *
+ * // Feature-based construction (when you already have the feature)
+ * const assertion = RateLimitAssertion.create(feature);
+ * ```
+ */
+declare class RateLimitAssertion extends LicenseAssertion<RateLimitLicenseFeature> {
+    readonly featureKey: string;
+    /**
+     * Creates a new rate limit assertion.
+     * @param featureKeyOrFeature A feature key string or a rate limit feature instance.
+     */
+    constructor(featureKeyOrFeature: string | RateLimitLicenseFeature);
+    /**
+     * Checks if the feature's consumption is within its rate limit.
+     * Prefers local feature state when available, falls back to server currentConsumption.
+     */
+    isSatisfied(authorization: LicenseAuthorization, featureStates?: Map<string, RateLimitFeatureState>): boolean;
+    /**
+     * Factory method to create a rate limit assertion from a feature key.
+     * @param featureKey The feature key to check
+     */
+    static create(featureKey: string): RateLimitAssertion;
+    /**
+     * Factory method to create a rate limit assertion from a feature instance.
+     * @param feature The rate limit feature to check
+     */
+    static create(feature: RateLimitLicenseFeature): RateLimitAssertion;
+}
+
+/**
+ * Assertion that checks if a feature with a specific key exists in the authorization.
+ * This is the simplest form of assertion for basic feature checking.
+ *
+ * @example
+ * ```typescript
+ * const assertion = FeatureExistsAssertion.create('premium-analytics');
+ * const hasFeature = assertion.isSatisfied(authorization);
+ * ```
+ */
+declare class FeatureExistsAssertion extends LicenseAssertion {
+    readonly featureKey: string;
+    /**
+     * Creates a new feature exists assertion
+     * @param featureKey The feature key to check for
+     */
+    constructor(featureKey: string);
+    /**
+     * Checks if the authorization contains a feature with the specified key
+     */
+    isSatisfied(authorization: LicenseAuthorization): boolean;
+    /**
+     * Factory method to create a feature exists assertion
+     * @param featureKey The feature key to check for
+     */
+    static create(featureKey: string): FeatureExistsAssertion;
+}
+/**
+ * Assertion that combines multiple assertions with AND logic.
+ * All assertions must be satisfied for this to return true.
+ *
+ * @example
+ * ```typescript
+ * const assertion = CompositeAssertion.and(
+ *   FeatureExistsAssertion.create('feature1'),
+ *   FeatureExistsAssertion.create('feature2')
+ * );
+ * ```
+ */
+declare class CompositeAssertion extends LicenseAssertion {
+    readonly assertions: LicenseAssertion[];
+    readonly logic: 'and' | 'or';
+    readonly featureKey: string;
+    /**
+     * Creates a new composite assertion
+     * @param assertions The assertions to combine
+     * @param logic The logic to apply ('and' or 'or')
+     */
+    constructor(assertions: LicenseAssertion[], logic?: 'and' | 'or');
+    /**
+     * Evaluates all assertions according to the logic
+     */
+    isSatisfied(authorization: LicenseAuthorization): boolean;
+    /**
+     * Factory method to create an AND composite assertion
+     * @param assertions The assertions to combine with AND logic
+     */
+    static and(...assertions: LicenseAssertion[]): CompositeAssertion;
+    /**
+     * Factory method to create an OR composite assertion
+     * @param assertions The assertions to combine with OR logic
+     */
+    static or(...assertions: LicenseAssertion[]): CompositeAssertion;
+}
+/**
+ * Assertion that inverts another assertion's result.
+ *
+ * @example
+ * ```typescript
+ * const assertion = NotAssertion.create(
+ *   FeatureExistsAssertion.create('blocked-feature')
+ * );
+ * // Returns true if the feature does NOT exist
+ * ```
+ */
+declare class NotAssertion extends LicenseAssertion {
+    readonly assertion: LicenseAssertion;
+    readonly featureKey: string;
+    /**
+     * Creates a new NOT assertion
+     * @param assertion The assertion to invert
+     */
+    constructor(assertion: LicenseAssertion);
+    /**
+     * Returns the opposite of the wrapped assertion's result
+     */
+    isSatisfied(authorization: LicenseAuthorization): boolean;
+    /**
+     * Factory method to create a NOT assertion
+     * @param assertion The assertion to invert
+     */
+    static create(assertion: LicenseAssertion): NotAssertion;
+}
+
+/**
+ * Parameters for generating a license authorization
+ */
+interface GenerateLicenseAuthorizationParameters {
+    RequestId?: string;
+    LicenseClassification?: LicenseClassificationType;
+    LicenseId: string;
+}
+/**
+ * Main client for interacting with the Sidub Licensing service.
+ * Provides minimal API surface with only 3 core operations needed for runtime enforcement.
+ *
+ * Supports cryptographic signature validation to ensure authorization integrity.
+ */
+declare class LicensingClient {
+    private config;
+    private readonly credential;
+    private signatureValidator;
+    private validateSignatures;
+    private readonly authorizationCache;
+    private readonly cacheEnabled;
+    private readonly featureStates;
+    private readonly featureMetadata;
+    private contextResolved;
+    private contextResolutionPromise;
+    /**
+     * Creates a new instance of the LicensingClient
+     * @param config Configuration for the licensing service
+     */
+    constructor(config: LicensingConfig);
+    /**
+     * Ensures context provider has been resolved before making API calls.
+     * Called once per client lifetime; concurrent callers share the same promise.
+     */
+    private ensureContextResolved;
+    /**
+     * Builds the cryptography configuration from the resolved config values
+     */
+    private buildCryptoConfig;
+    /**
+     * Gets whether cryptographic signature validation is enabled
+     */
+    get isSignatureValidationEnabled(): boolean;
+    /**
+     * Gets the configured license ID (from credential or explicit config)
+     */
+    get configuredLicenseId(): string | undefined;
+    /**
+     * Retrieves a license authorization from the server.
+     * This is the primary method for validating and obtaining license information.
+     *
+     * If cryptographic configuration is provided, the authorization signature will be
+     * validated to ensure integrity. This mirrors the .NET LicensingService behavior.
+     *
+     * @param licenseId The unique identifier of the license (optional if configured via encodedCredential)
+     * @param apiKey Optional API key for authentication (overrides config default)
+     * @returns A promise resolving to the license authorization
+     * @throws {LicensingError} If the request fails or authorization is denied
+     * @throws {CryptoError} If signature validation fails (when crypto config is provided)
+     */
+    getAuthorization(licenseId?: string, apiKey?: string): Promise<LicenseAuthorization>;
+    /**
+     * Maps server feature format to client format.
+     * Explicitly constructs camelCase feature objects instead of spreading server properties.
+     * This prevents PascalCase duplicates and ensures consistent property access.
+     */
+    private mapFeatures;
+    /**
+     * Normalizes the signature from server response.
+     * Handles both base64 string format (from .NET Convert.ToBase64String)
+     * and byte array format (JSON array of numbers).
+     *
+     * @param rawSignature The raw signature from server response
+     * @returns Normalized base64 string, or undefined if not present
+     */
+    private normalizeSignature;
+    /**
+     * Asserts whether a license condition is satisfied using the provided assertion.
+     * This evaluates the assertion against a license authorization.
+     *
+     * @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);
+     * ```
+     */
+    assertLicense<T extends ILicenseFeature = ILicenseFeature>(assertion: ILicenseAssertion<T>, authorization: LicenseAuthorization): boolean;
+    /** Clears all cached authorizations */
+    clearCache(): void;
+    /** Invalidates all cached authorizations for a specific license */
+    invalidateCache(licenseId: string): void;
+    /** Gets the local feature state for a license+feature combination */
+    getFeatureState(licenseId: string, featureKey: string): RateLimitFeatureState | undefined;
+    /** Sets/replaces the local feature state for a license+feature combination */
+    setFeatureState(licenseId: string, featureKey: string, state: RateLimitFeatureState): void;
+    /**
+     * Reports license feature consumption/usage to the server.
+     * This is used for metering and billing purposes.
+     *
+     * @param operation The operation to report
+     * @returns A promise that resolves when the operation is reported
+     * @throws {LicensingError} If the request fails
+     */
+    performOperation<T extends ILicenseFeature>(operation: LicenseFeatureStateOperation<T>): Promise<void>;
+    /**
+     * Reports a telemetry-only access check event to the server.
+     * This does not affect billing — IsBillable is always false.
+     * Used for tracking feature access patterns without metering costs.
+     *
+     * @param licenseId The license ID (optional if configured)
+     * @param featureKey The feature being accessed
+     * @param apiKey Optional API key override
+     */
+    reportAccessCheck(licenseId?: string, featureKey?: string, apiKey?: string): Promise<void>;
+    /**
+     * Creates an embedded checkout session for purchasing an offering.
+     * For free/trial offerings, the license is provisioned immediately (sessionUrl will be null).
+     * For paid offerings, sessionUrl will contain the payment provider URL.
+     *
+     * Uses licenseServiceUri (not consumptionServiceUri) — checkout is a licensing operation.
+     *
+     * @param request Checkout request parameters
+     * @param apiKey Optional API key override (reseller's API key)
+     * @returns The created checkout session with sessionId and optional sessionUrl
+     * @throws {LicensingError} If the request fails
+     */
+    createCheckoutSession(request: CheckoutRequest, apiKey?: string): Promise<CheckoutSession>;
+    /**
+     * Retrieves the result of a checkout session.
+     * Poll this method after creating a checkout session to check if the purchase is complete.
+     *
+     * For free/trial offerings, the result is immediately available (status = 'completed').
+     * For paid offerings, status will be 'pending' until the customer completes payment.
+     *
+     * @param sessionId The session ID from createCheckoutSession()
+     * @param apiKey Optional API key override
+     * @returns The checkout session result with status, credential, and error fields
+     * @throws {LicensingError} If the request fails
+     */
+    getCheckoutResult(sessionId: string, apiKey?: string): Promise<CheckoutSessionResult>;
+    /**
+     * Generates a unique request ID for tracking
+     * @private
+     */
+    private generateRequestId;
+    /**
+     * Polls for a checkout session result with exponential backoff.
+     * Replaces the useCheckout hook pattern with an imperative API.
+     *
+     * @param sessionId The session ID from createCheckoutSession()
+     * @param options Optional: apiKey override, AbortSignal for cancellation, maxAttempts (default 60)
+     * @returns The completed or failed checkout session result
+     * @throws {LicensingError} If polling times out or the request fails
+     */
+    pollCheckoutResult(sessionId: string, options?: {
+        apiKey?: string;
+        signal?: AbortSignal;
+        maxAttempts?: number;
+    }): Promise<CheckoutSessionResult>;
+    /**
+     * Gets the current configuration
+     */
+    getConfig(): Readonly<LicensingConfig>;
+}
+
+declare class LicensingConfigurationException extends LicensingError {
+    constructor(message: string);
+}
+
+/**
+ * Cryptography service for license signature validation.
+ * Uses the Web Crypto API for cross-platform compatibility.
+ */
+/**
+ * Configuration for the cryptography service
+ */
+interface CryptoConfig {
+    /** The service key ID used for signature verification */
+    serviceKeyId: string;
+    /** Base64-encoded public key for signature verification */
+    serviceKeyPublicMember: string;
+}
+/**
+ * Service for cryptographic operations on license entities.
+ * Implements signature verification using ECDSA with P-256 curve and SHA-256.
+ */
+declare class CryptoService {
+    private publicKey;
+    private readonly config;
+    constructor(config: CryptoConfig);
+    /**
+     * Gets the service key ID
+     */
+    get serviceKeyId(): string;
+    /**
+     * Initializes the public key from the configured base64 string.
+     * Must be called before verifying signatures.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Verifies the signature of a signed entity.
+     *
+     * @param data The data that was signed (serialized entity without signature)
+     * @param signature The signature to verify (base64-encoded)
+     * @returns True if the signature is valid, false otherwise
+     */
+    verifySignature(data: ArrayBuffer, signature: string): Promise<boolean>;
+    /**
+     * Converts a base64 string to an ArrayBuffer.
+     * Handles both standard base64 and base64url encoding.
+     */
+    private base64ToArrayBuffer;
+}
+/**
+ * Error class for cryptography-related errors
+ */
+declare class CryptoError extends Error {
+    readonly code: 'KEY_IMPORT_FAILED' | 'VERIFICATION_FAILED' | 'NOT_INITIALIZED' | 'INVALID_SIGNATURE';
+    constructor(message: string, code: 'KEY_IMPORT_FAILED' | 'VERIFICATION_FAILED' | 'NOT_INITIALIZED' | 'INVALID_SIGNATURE');
+}
+
+/**
+ * Signature validator for license authorization entities.
+ * Validates that the authorization returned from the server has not been tampered with.
+ */
+
+/**
+ * Options for signature validation behavior
+ */
+interface SignatureValidationOptions {
+    /** Whether to throw an error if signature validation fails (default: true) */
+    throwOnInvalid?: boolean;
+    /** Whether signature validation is required (default: true if crypto config provided) */
+    required?: boolean;
+}
+/**
+ * Result of signature validation
+ */
+interface SignatureValidationResult {
+    /** Whether the signature is valid */
+    isValid: boolean;
+    /** Whether validation was skipped (e.g., no signature present and not required) */
+    skipped: boolean;
+    /** Error message if validation failed */
+    error?: string;
+}
+/**
+ * Raw server response for authorization (before client mapping).
+ * Uses PascalCase property names matching the .NET server response.
+ */
+interface RawAuthorizationResponse {
+    AuthorizationId: string;
+    LicenseId: string;
+    LicenseClassification: string | number;
+    IssueDate: string;
+    ExpiryDate?: string;
+    Features: unknown[];
+    __sidub_entitySignature?: string;
+    [key: string]: unknown;
+}
+/**
+ * Validates license authorization signatures to ensure integrity.
+ *
+ * This class implements the client-side portion of the signature verification
+ * that mirrors the .NET LicensingService.GetAuthorization() validation logic.
+ */
+declare class SignatureValidator {
+    private cryptoService;
+    private initialized;
+    /**
+     * Creates a new SignatureValidator instance.
+     *
+     * @param config Cryptography configuration. If null, validation will be skipped.
+     */
+    constructor(config: CryptoConfig | null);
+    /**
+     * Gets whether cryptographic validation is configured
+     */
+    get isConfigured(): boolean;
+    /**
+     * Initializes the validator. Must be called before validating signatures.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Validates the signature of a license authorization using the raw server response.
+     *
+     * The validation process:
+     * 1. Extracts the signature from __sidub_entitySignature
+     * 2. Serializes the raw response data (excluding signature field)
+     * 3. Verifies the signature using the configured public key
+     *
+     * @param rawResponse The raw server response (before client mapping)
+     * @param options Validation options
+     * @returns Validation result
+     * @throws {CryptoError} If throwOnInvalid is true and validation fails
+     */
+    validateRawResponse(rawResponse: RawAuthorizationResponse, options?: SignatureValidationOptions): Promise<SignatureValidationResult>;
+    /**
+     * Serializes the raw server response for signature verification.
+     * Removes the __sidub_entitySignature field and serializes to JSON.
+     */
+    private serializeRawForVerification;
+}
+
+/**
+ * In-memory authorization cache with TTL-based expiry and pseudo-LRU eviction.
+ * Cache key format: {licenseId}.{serviceKeyId}
+ * One cache instance per LicensingClient — no singletons.
+ */
+declare class AuthorizationCache {
+    private cache;
+    private maxSize;
+    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).
+     */
+    get(licenseId: string, serviceKeyId: string): LicenseAuthorization | null;
+    /**
+     * Stores an authorization in the cache.
+     * Evicts the oldest entry if max size is reached.
+     */
+    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 */
+    invalidate(licenseId: string): void;
+}
+
+/**
+ * Context for providing the LicensingClient to React components
+ */
+interface LicensingContextValue {
+    client: LicensingClient;
+    /** Whether signature validation is enabled */
+    isSignatureValidationEnabled: boolean;
+    /** The configured license ID (if provided via credential) */
+    configuredLicenseId: string | undefined;
+}
+/**
+ * Props for the LicensingProvider component
+ */
+interface LicensingProviderProps {
+    /** Configuration for the licensing client */
+    config: LicensingConfig;
+    /** Child components */
+    children: ReactNode;
+}
+/**
+ * Provider component for the Sidub Licensing context.
+ * Wraps your application to provide licensing functionality to all child components.
+ *
+ * Supports cryptographic signature validation when configured with serviceKeyId
+ * and serviceKeyPublicMember (either directly or via encodedCredential).
+ *
+ * @example
+ * ```tsx
+ * // Basic usage (no signature validation)
+ * <LicensingProvider config={{
+ *   licenseServiceUri: 'https://api.example.com',
+ *   apiKey: 'your-api-key'
+ * }}>
+ *   <App />
+ * </LicensingProvider>
+ *
+ * // With encoded credential (includes signature validation)
+ * <LicensingProvider config={{
+ *   licenseServiceUri: 'https://api.example.com',
+ *   encodedCredential: 'SIDUB_LIC_...'
+ * }}>
+ *   <App />
+ * </LicensingProvider>
+ * ```
+ */
+declare const LicensingProvider: React.FC<LicensingProviderProps>;
+/**
+ * Hook to access the LicensingClient from context.
+ * Must be used within a LicensingProvider.
+ *
+ * @throws {Error} If used outside of a LicensingProvider
+ * @returns The LicensingClient instance
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const client = useLicensingContext();
+ *   // Use client.getAuthorization(), etc.
+ * }
+ * ```
+ */
+declare const useLicensingContext: () => LicensingClient;
+/**
+ * Hook to access the full licensing context including metadata.
+ * Must be used within a LicensingProvider.
+ *
+ * @throws {Error} If used outside of a LicensingProvider
+ * @returns The full licensing context value
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { client, isSignatureValidationEnabled, configuredLicenseId } = useLicensingContextValue();
+ *
+ *   if (!isSignatureValidationEnabled) {
+ *     console.warn('Signature validation is disabled');
+ *   }
+ * }
+ * ```
+ */
+declare const useLicensingContextValue: () => LicensingContextValue;
+
+/**
+ * Licensing context data type matching the .NET LicensingContext sealed record.
+ * Named LicensingContextType to avoid collision with the React context in LicensingContext.tsx.
+ */
+interface LicensingContextType {
+    licenseId: string;
+    serviceKeyId: string;
+    serviceKeyPublicMember: string;
+    apiAccessKey: string;
+    billableResourceId?: string;
+    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.
+ */
+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.
+ */
+declare function licensingContextToEncodedString(context: LicensingContextType): string;
+
+/**
+ * Interface for pluggable licensing context resolution.
+ * Matches the .NET ILicensingContextProvider pattern.
+ *
+ * Implement this interface for custom credential resolution strategies
+ * (e.g., per-tenant lookup from database or session store).
+ */
+interface ILicensingContextProvider {
+    resolveContext(): Promise<LicensingContextType | null>;
+}
+
+/**
+ * Default context provider that builds a LicensingContextType from LicensingConfig.
+ * Returns null when no credentials are configured (user hasn't purchased a license yet).
+ * Caches the result after first resolution (lazy, one-shot).
+ */
+declare class ConfigurationContextProvider implements ILicensingContextProvider {
+    private readonly config;
+    private cached;
+    constructor(config: LicensingConfig);
+    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 };