@gorilla-engine-sdk/ge-product-hub 0.1.4

package/dist/lib/clients.js

@@ -0,0 +1,2036 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProductHub = exports.HARDWARE_FINGERPRINT_VERSION = exports.SIGNATURE_SEED_VERSION = void 0;
+const errors_1 = require("./errors");
+const types_1 = require("./types");
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const credentialStore_1 = require("./credentialStore");
+/**
+ * @internal
+ * Product Hub API base URL.
+ * Can be overridden via the PRODUCT_HUB_BASE_URL environment variable
+ * (used by the e2e test suite to target non-production environments).
+ */
+const BASE_URL = process.env['PRODUCT_HUB_BASE_URL'] ?? 'https://producthub.ujam.com/api/v1';
+/**
+ * @internal
+ * Fixed signature seed version used for cryptographic verification.
+ */
+exports.SIGNATURE_SEED_VERSION = 6;
+/**
+ * @internal
+ * Hardware fingerprint version for system identification.
+ */
+exports.HARDWARE_FINGERPRINT_VERSION = 2;
+/**
+ * @internal
+ * HTTP client wrapper that handles Product Hub API responses and errors.
+ */
+async function callApi(url, opts = {}) {
+    let response;
+    try {
+        response = await fetch(url, opts);
+    }
+    catch (ex) {
+        throw new errors_1.ProductHubError(`Network error: ${ex?.message || ex}`, undefined);
+    }
+    if (!response.ok) {
+        let body = undefined;
+        try {
+            body = await response.json();
+        }
+        catch {
+            /* ignore parse errors */
+        }
+        const message = body?.message || response.statusText || 'Request failed';
+        if (response.status === 401) {
+            throw new errors_1.NotAuthorizedError(message, body);
+        }
+        throw new errors_1.ProductHubError(message, response.status, body);
+    }
+    try {
+        return (await response.json());
+    }
+    catch (ex) {
+        throw new errors_1.ProductHubError(`Failed to parse JSON: ${ex?.message || ex}`, response.status);
+    }
+}
+/**
+ * @internal
+ * Hardware fingerprint management utility.
+ * This singleton handles automatic hardware identification and validation.
+ * Used internally by AudioPluginClient - not for direct use.
+ */
+class HardwareFingerprintUtil {
+    constructor() {
+        this.fingerprint = undefined;
+        this.fingerprintOverride = undefined;
+        // Detect test environment and set test fingerprint
+        if (isTestEnvironment()) {
+            this.fingerprintOverride = 'test-hardware-fingerprint-12345';
+        }
+    }
+    static getInstance() {
+        if (!HardwareFingerprintUtil.instance) {
+            HardwareFingerprintUtil.instance = new HardwareFingerprintUtil();
+        }
+        return HardwareFingerprintUtil.instance;
+    }
+    generateFingerprint() {
+        try {
+            return process
+                ._linkedBinding('hwfp')
+                .Fingerprint(exports.HARDWARE_FINGERPRINT_VERSION)
+                .toString();
+        }
+        catch (ex) {
+            try {
+                return process
+                    .binding('hwfp')
+                    .Fingerprint(exports.HARDWARE_FINGERPRINT_VERSION)
+                    .toString();
+            }
+            catch (ex2) {
+                throw new errors_1.ProductHubError('Unable to generate hardware fingerprint');
+            }
+        }
+    }
+    getFingerprint() {
+        if (this.fingerprintOverride) {
+            // If we have an override, use it otherwise it's gonna fuck up our tests
+            return this.fingerprintOverride;
+        }
+        if (!this.fingerprint) {
+            // Lazy load fingerprint native module whe we are not in a testing scenario
+            this.fingerprint = this.generateFingerprint();
+        }
+        return this.fingerprint;
+    }
+    setFingerprintOverride(fingerprint) {
+        this.fingerprintOverride = fingerprint;
+    }
+    validate(fingerprint) {
+        // If we have an override, we can't use native validation - just compare strings
+        if (this.fingerprintOverride) {
+            return fingerprint === this.fingerprintOverride;
+        }
+        try {
+            const hwfp = process._linkedBinding?.('hwfp') || process.binding?.('hwfp');
+            return hwfp?.validate ? hwfp.validate(fingerprint) : fingerprint === this.getFingerprint();
+        }
+        catch {
+            return fingerprint === this.getFingerprint();
+        }
+    }
+}
+/**
+ * Gorilla Engine Product Hub Client Library
+ *
+ * Provides comprehensive audio plugin licensing with
+ * activation management & trial handling.
+ */
+var ProductHub;
+(function (ProductHub) {
+    /**
+     * @internal
+     * Low-level API client for Product Hub communication.
+     * This class is used internally and should not be used directly.
+     * Use AudioPluginClient instead for a complete audio plugin licensing solution.
+     */
+    class APIClient {
+        /**
+         * Create a low-level Product Hub API client.
+         *
+        * @param options - Product, manufacturer, and optional fingerprint settings.
+         * @throws {@link ProductHubError} If a required identifier is missing, the runtime is older
+         * than Node.js 18.3, global `fetch` is unavailable, or fingerprint generation fails.
+        * @remarks One stored login session is shared by all products from this manufacturer.
+        * `hardwareFingerprint` is intended for tests; production clients should use the Gorilla
+        * Engine hardware-fingerprinting binding.
+         * @example
+         * ```typescript
+         * const apiClient = new ProductHub.APIClient({
+         *   manufacturerId: 'manufacturer-id',
+         *   productId: 'product-id',
+         * });
+         * ```
+         */
+        constructor(options) {
+            this.bearerToken = null;
+            const { manufacturerId, productId, hardwareFingerprint } = options;
+            if (!manufacturerId) {
+                throw new errors_1.ProductHubError('manufacturerId is required when constructing APIClient');
+            }
+            if (!productId) {
+                throw new errors_1.ProductHubError('productId is required when constructing APIClient');
+            }
+            this.manufacturerId = manufacturerId;
+            this.productId = productId;
+            this.hwfpUtil = HardwareFingerprintUtil.getInstance();
+            // Update fingerprint if provided
+            if (hardwareFingerprint) {
+                this.hwfpUtil.setFingerprintOverride(hardwareFingerprint);
+            }
+            // Verify Node.js version
+            this.validateNodeVersion();
+        }
+        credentialLocation() {
+            return (0, credentialStore_1.createCredentialLocation)(this.manufacturerId);
+        }
+        isTokenUsable(token) {
+            try {
+                const parts = token.split('.');
+                if (parts.length !== 3) {
+                    return false;
+                }
+                const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+                if (payload.aud !== this.manufacturerId) {
+                    return false;
+                }
+                if (typeof payload.exp === 'number' && payload.exp * 1000 <= Date.now()) {
+                    return false;
+                }
+                if (payload.sub !== this.hwfpUtil.getFingerprint()) {
+                    return false;
+                }
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        async readPersistedToken() {
+            const location = this.credentialLocation();
+            try {
+                const token = (await (0, credentialStore_1.getCredential)(location.service, location.account))?.trim();
+                if (!token) {
+                    return { token: null, status: types_1.SessionStatus.None };
+                }
+                if (!this.isTokenUsable(token)) {
+                    await (0, credentialStore_1.deleteCredential)(location.service, location.account).catch(() => undefined);
+                    return { token: null, status: types_1.SessionStatus.Invalid };
+                }
+                return { token, status: types_1.SessionStatus.Valid };
+            }
+            catch {
+                return { token: null, status: types_1.SessionStatus.None };
+            }
+        }
+        async loadPersistedToken() {
+            return (await this.readPersistedToken()).token;
+        }
+        async persistToken(token) {
+            const location = this.credentialLocation();
+            try {
+                await (0, credentialStore_1.setCredential)(location.service, location.account, token);
+            }
+            catch {
+                // Credential persistence is best-effort and must not break login flow.
+            }
+        }
+        /**
+         * Check whether a usable login session is stored for this product and device.
+         *
+         * @returns A promise resolving to `true` when a usable session exists; otherwise `false`.
+         * @remarks Malformed, expired, or wrong-scope stored tokens are removed before returning.
+         */
+        async hasStoredSession() {
+            return (await this.loadPersistedToken()) !== null;
+        }
+        /**
+         * Read non-sensitive claims from the active stored login session.
+         *
+         * @returns The stored session's email, user ID, and expiration, or `null` when no usable
+         * session exists. The bearer token is never exposed.
+         * @remarks Malformed, expired, or wrong-scope stored tokens are removed before returning.
+         */
+        async getStoredSessionInfo() {
+            const token = await this.loadPersistedToken();
+            if (!token)
+                return null;
+            try {
+                const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString());
+                return {
+                    email: typeof payload.email === 'string' ? payload.email : null,
+                    userId: typeof payload.user_id === 'string' ? payload.user_id : null,
+                    expiresAt: typeof payload.exp === 'number' ? new Date(payload.exp * 1000) : null,
+                };
+            }
+            catch {
+                return null;
+            }
+        }
+        /**
+         * Clear the active login session.
+         *
+         * @returns A promise that resolves after clearing the in-memory token and attempting to
+         * remove the persisted credential.
+         * @remarks Credential-store deletion is best-effort and failures are intentionally ignored.
+         */
+        async clearStoredSession() {
+            this.bearerToken = null;
+            const location = this.credentialLocation();
+            await (0, credentialStore_1.deleteCredential)(location.service, location.account).catch(() => undefined);
+        }
+        /**
+         * Activate the product using the active stored login session.
+         *
+         * @param serial - Optional reseller serial to claim and activate instead of using Product
+         * Hub's normal license selection.
+         * @returns The independent session status and the activation response, if one was available.
+         * A valid session with no matching activation returns `activation: null`.
+         * @throws {@link ProductHubError} If the API cannot be reached or an unexpected API error
+         * occurs. Authentication failures are returned as `SessionStatus.Invalid` instead.
+         * @remarks
+         * This method never performs a credential login. Missing sessions return
+         * `SessionStatus.None`; malformed, expired, wrong-scope, or API-rejected sessions return
+         * `SessionStatus.Invalid` and are removed. HTTP 404 and 409 responses return a valid session
+         * with no activation.
+         * @example
+         * ```typescript
+         * const result = await apiClient.activateProductWithStoredSession();
+         * if (result.sessionStatus === SessionStatus.Valid && result.activation) {
+         *   console.log(result.activation.serial);
+         * }
+         * ```
+         */
+        async activateProductWithStoredSession(serial) {
+            const storedSession = await this.readPersistedToken();
+            if (!storedSession.token) {
+                return { sessionStatus: storedSession.status, activation: null };
+            }
+            try {
+                return {
+                    sessionStatus: types_1.SessionStatus.Valid,
+                    activation: await this.activateProductWithToken(storedSession.token, serial),
+                };
+            }
+            catch (ex) {
+                if (ex instanceof errors_1.NotAuthorizedError) {
+                    await this.clearStoredSession();
+                    return { sessionStatus: types_1.SessionStatus.Invalid, activation: null };
+                }
+                if (ex instanceof errors_1.ProductHubError && (ex.status === 404 || ex.status === 409)) {
+                    return { sessionStatus: types_1.SessionStatus.Valid, activation: null };
+                }
+                throw ex;
+            }
+        }
+        validateNodeVersion() {
+            const nodeVersion = globalThis?.process?.versions?.node;
+            if (!nodeVersion) {
+                throw new errors_1.ProductHubError('Unsupported runtime: Node >=18.3 is required.');
+            }
+            const [majorStr, minorStr] = nodeVersion.split('.');
+            const major = parseInt(majorStr, 10);
+            const minor = parseInt(minorStr || '0', 10);
+            if (major < 18 || (major === 18 && minor < 3)) {
+                throw new errors_1.ProductHubError(`Node >=18.3 required. Detected ${nodeVersion}. Upgrade your runtime.`);
+            }
+            if (!globalThis.fetch) {
+                throw new errors_1.ProductHubError('Global fetch not found. Node >=18.3 should provide fetch by default.');
+            }
+        }
+        /**
+         * Authenticate a user and make the returned token the active session.
+         *
+         * @param email - End-user email address.
+         * @param password - End-user password.
+         * @returns The bearer token returned by Product Hub.
+         * @throws {@link NotAuthorizedError} If the credentials are rejected.
+         * @throws {@link ProductHubError} If fingerprint generation, networking, response parsing,
+         * or another API operation fails.
+        * @remarks The token is retained in memory and persisted in the operating system's secure
+        * credential store on a best-effort basis.
+         * @example
+         * ```typescript
+         * const token = await apiClient.loginUser('user@example.com', 'secret');
+         * ```
+         */
+        async loginUser(email, password) {
+            const url = `${BASE_URL}/clients/any/manufacturers/${this.manufacturerId}/users/login`;
+            const hardwareFingerprint = this.hwfpUtil.getFingerprint();
+            const response = await callApi(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    email,
+                    password,
+                    fingerprint: hardwareFingerprint,
+                }),
+            });
+            this.bearerToken = response.token;
+            await this.persistToken(response.token);
+            return response.token;
+        }
+        /**
+         * Activate a product with a license
+         */
+        async activateProductWithToken(bearer, serial) {
+            const hardwareFingerprint = this.hwfpUtil.getFingerprint();
+            const url = `${BASE_URL}/clients/any/products/${this.productId}/activations`;
+            return await callApi(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${bearer}`,
+                },
+                body: JSON.stringify({
+                    hardware_fingerprint: hardwareFingerprint,
+                    hardware_fingerprint_version: exports.HARDWARE_FINGERPRINT_VERSION,
+                    signature_seed_version: exports.SIGNATURE_SEED_VERSION,
+                    ...(serial && { serial }),
+                }),
+            });
+        }
+        /**
+         * Authenticate with explicit credentials and activate the product.
+         *
+         * @param params - Credentials and an optional reseller serial to claim and activate.
+         * @returns The signed Product Hub activation response.
+         * @throws {@link NotAuthorizedError} If login or activation authorization fails.
+         * @throws {@link ProductHubError} If fingerprint generation, networking, response parsing,
+         * or another API operation fails.
+         * @remarks Explicit credentials always replace the active stored session. If activation is
+         * rejected as unauthorized after login, the newly stored session is cleared.
+         * @example
+         * ```typescript
+         * const activation = await apiClient.activateProduct({
+         *   email: 'user@example.com',
+         *   password: 'secret',
+         *   serial: 'STD-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX',
+         * });
+         * ```
+         */
+        async activateProduct(params) {
+            const bearer = await this.loginUser(params.email, params.password);
+            try {
+                return await this.activateProductWithToken(bearer, params.serial);
+            }
+            catch (ex) {
+                if (ex instanceof errors_1.NotAuthorizedError) {
+                    await this.clearStoredSession();
+                }
+                throw ex;
+            }
+        }
+        /**
+         * Activate a product using email and serial only — no login or Bearer token required.
+         *
+         * @remarks
+         * Only works when the manufacturer has "Authentication Type = None" and
+         * "Email+Serial Claiming" enabled in Product Hub. The license is claimed
+         * (if not claimed so far) and activated in a single API call.
+         *
+         * @param email - End-user email address used to identify or create the account.
+         * @param serial - License serial received after purchase.
+         * @returns The signed Product Hub activation response.
+         * @throws {@link NotAuthorizedError} If email-and-serial activation is not authorized.
+         * @throws {@link ProductHubError} If fingerprint generation, networking, response parsing,
+         * or another API operation fails.
+         * @example
+         * ```typescript
+         * const activation = await apiClient.activateProductWithEmailAndSerial(
+         *   'user@example.com',
+         *   'STD-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX',
+         * );
+         * ```
+         */
+        async activateProductWithEmailAndSerial(email, serial) {
+            const hardwareFingerprint = this.hwfpUtil.getFingerprint();
+            const url = `${BASE_URL}/clients/any/products/${this.productId}/activations`;
+            return await callApi(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    email,
+                    serial,
+                    hardware_fingerprint: hardwareFingerprint,
+                    hardware_fingerprint_version: exports.HARDWARE_FINGERPRINT_VERSION,
+                    signature_seed_version: exports.SIGNATURE_SEED_VERSION,
+                }),
+            });
+        }
+        /**
+         * Activate a hardware-bound trial for the product.
+         *
+         * @returns The signed Product Hub trial response.
+         * @throws {@link ProductHubError} If fingerprint generation, networking, response parsing,
+         * or the trial API request fails.
+         * @remarks This low-level method returns API data without verifying or persisting it. Use
+         * {@link AudioPluginClient.activateTrial} for the complete plugin workflow.
+         * @example
+         * ```typescript
+         * const trial = await apiClient.activateTrial();
+         * console.log(trial.trial_days);
+         * ```
+         */
+        async activateTrial() {
+            const url = `${BASE_URL}/clients/any/products/${this.productId}/trials`;
+            return await callApi(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    hardware_fingerprint: this.hwfpUtil.getFingerprint(),
+                    hardware_fingerprint_version: exports.HARDWARE_FINGERPRINT_VERSION,
+                    signature_seed_version: exports.SIGNATURE_SEED_VERSION,
+                }),
+            });
+        }
+        /**
+         * Get the latest product version from the Release distribution channel.
+         *
+         * @returns The available builds and optional update referral URL for this product.
+         * @throws {@link ProductHubError} If the request fails or its response cannot be parsed.
+         * @example
+         * ```typescript
+         * const latest = await apiClient.getLatestProductVersion();
+         * console.log(latest.builds);
+         * ```
+         */
+        async getLatestProductVersion() {
+            const url = `${BASE_URL}/clients/any/products/${this.productId}/latest`;
+            return await callApi(url, {
+                method: 'GET',
+            });
+        }
+        /**
+         * Get downloadable files for a specific product build.
+         *
+         * @param buildId - Product Hub build identifier.
+         * @returns The files attached to the selected build.
+         * @throws {@link ProductHubError} If the request fails or its response cannot be parsed.
+         * @example
+         * ```typescript
+         * const files = await apiClient.getBuildFiles('build-id');
+         * ```
+         */
+        async getBuildFiles(buildId) {
+            const url = `${BASE_URL}/clients/any/products/${this.productId}/builds/${buildId}/files`;
+            return await callApi(url, {
+                method: 'GET',
+            });
+        }
+    }
+    ProductHub.APIClient = APIClient;
+    /**
+     * Complete audio plugin licensing client with automatic activation management.
+     *
+     * This is the main class for integrating Gorilla Engine Product Hub licensing
+     * into your audio plugins. It handles everything from user authentication to
+     * local file persistence, signature verification, and trial management.
+     *
+     * ## Key Features
+     * - 🎫 **License Activation**: Activate full licenses with user credentials
+     * - ⏰ **Trial Management**: Start trials and track remaining time
+     * - 💾 **Local Persistence**: Automatic .ops/.lts file management
+     * - 🔄 **Subscription Auto-Refresh**: Silently refreshes persisted subscription activations when cached tokens are available
+     * - 🔒 **Signature Verification**: Built-in RSA-SHA256 cryptographic verification
+     * - 🖥️ **Hardware Fingerprinting**: Automatic system identification when used with Gorilla Engine "Hardware fingerprinting" native module
+     *
+     * @example
+     * ```typescript
+     * import { ProductHub, ActivationStatus, TrialExpiredError, ProductHubError, NotAuthorizedError } from "@gorilla-engine-sdk/ge-product-hub";
+     *
+     * const client = new ProductHub.AudioPluginClient({
+     *   manufacturerId: "7222d546-9c72-43d5-8bd4-1667ce390ea4",
+     *   productId: "1487a36d-9bc8-4220-ba31-9998d743071f",
+     *   productName: "Groove Master 3000",
+     *   productPublicKey: `-----BEGIN PUBLIC KEY-----
+     * MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+     * -----END PUBLIC KEY-----`,
+     *   userResourceBaseDirectory: "/Users/<username>/Library/Application Support/<manufacturername>"
+     * });
+     *
+     * ///////////////////////////////////////////
+     * // check whether we can unlock the plugin or need to show the activation prompt
+     * if( client.isActivated() ) {
+     *   // already activated - ready to go!
+     *   console.log("Plugin ready to use!");
+     *
+     *   // unlock via function defined below
+     *   unlockPlugin();
+     *
+     *   if( client.getActivationStatus() == ActivationStatus.Trial ) {
+     *     // if desired: disable non-realtime bouncing when in trial mode
+     *     GorillaEngine.getPluginNRTB(false);
+     *   }
+     * } else {
+     *   // not yet activated, neither with a trial nor regular activation
+     *   showActivationOverlay();
+     * }
+     *
+     *
+     *
+     * ///////////////////////////////////////////
+     * // Handle trial activation
+     * try {
+     *   const success = await client.activateTrial();
+     *   if( success ) {
+     *     unlockPlugin();
+     *     hideActivationOverlay();
+     *     showMessageBox(`Trial active. ${getRemainingTrialDays(client.remainingTrialTime())} left.`);
+     *   }
+     * } catch( ex ) {
+     *   if( ex instanceof TrialExpiredError ) {
+     *     activationOverlay.setMessage("Trial expired. Please activate with license.");
+     *   } else {
+     *     activationOverlay.setMessage(`An error occurred: ${(ex as ProductHubError).message}`);
+     *   }
+     * }
+     *
+     *
+     * ///////////////////////////////////////////
+     * // Handle activation with license
+     * try {
+     *   const success = await client.activateProduct({
+     *     email: "user@example.com",
+     *     password: "secret"
+     *   });
+     *
+     *   if( success ) {
+     *     unlockPlugin();
+     *     hideActivationOverlay();
+     *     aboutDialog.setSerialCodeForDisplay(client.licenseSerial());
+     *   }
+     * }
+     * catch( ex ) {
+     *   if( ex instanceof NotAuthorizedError ) {
+     *     activationOverlay.setMessage("Invalid credentials.");
+     *   } else {
+     *     activationOverlay.setMessage(`An error occurred: ${(ex as ProductHubError).message}`);
+     *   }
+     * }
+     *
+     *
+     * ///////////////////////////////////////////
+     * // assess the activation status of the local installation
+     * localActivationState = client.getActivationStatus();
+     * switch( localActivationState ) {
+     *   case ActivationStatus.None:
+     *     console.log("No successful activation found");
+     *     break;
+     *   case ActivationStatus.Trial:
+     *     console.log("Active trial");
+     *     break;
+     *   case ActivationStatus.TrialExpired:
+     *     console.log("Found a trial activation but the trial period is expired");
+     *     break;
+     *   case ActivationStatus.Licensed:
+     *     console.log(`Plugin is licensed with serial ${client.licenseSerial()}`);
+     *     const expires = client.licenseExpiration();
+     *     if (expires) {
+     *       console.log(`License expires on ${expires.toDateString()}`);
+     *     }
+     *     break;
+     *   case ActivationStatus.SubscriptionExpired:
+     *     console.log("Subscription license has expired - please renew");
+     *     break;
+     *   case ActivationStatus.LicenseExpired:
+     *     console.log("License has expired - please renew or reactivate");
+     *     break;
+     *   default:
+     *     console.log(`Invalid activation state: ${localActivationState}`)
+     * }
+     *
+     *
+     * ///////////////////////////////////////////
+     * // unlock audio & MIDI in your plugin
+     * function unlockPlugin(trial: boolean = false) {
+     *   // Note: It is vital to uncheck the following two options in Gorilla Compiler's
+     *   // "Copy Protection" tab when building your plugin:
+     *   // 1. MIDI enabled on startup
+     *   // 2. Audio enabled on startup
+     *   //
+     *   // It is better to do it this way round rather than enabling MIDI and audio in Compiler
+     *   // and disabling it here when isActivated() returns false as the plugin stays unlocked
+     *   // even if an exception is provoked inside its JavaScript code
+     *
+     *   // Enable MIDI processing
+     *   GorillaEngine.getPluginMM(true);
+     *
+     *   // Enable audio processing
+     *   GorillaEngine.getPluginAE(true);
+     * }
+     *
+     *
+     * ///////////////////////////////////////////
+     * // get remaining trial time in days
+     * function getRemainingTrialDays(remainingMs: number) {
+     *   return Math.floor(remainingMs / (24 * 60 * 60 * 1000));
+     * }
+     * ```
+     */
+    class AudioPluginClient {
+        /**
+         * Create a new AudioPluginClient instance.
+         *
+         * Sets up everything needed for audio plugin licensing including hardware
+         * fingerprinting, API communication, and local file management.
+         *
+         * @remarks
+         * The constructor performs two fire-and-forget background checks:
+         * - automatic product update check (`checkForUpdates()`)
+         * - automatic silent subscription refresh (`checkUpdateSubscription()`) when
+         *   both a local subscription activation and a stored login token exist
+         *
+         * These checks are not awaited by construction and may log asynchronous failures.
+         *
+         * @param options - Configuration options for the client
+         *
+         * @example
+         * ```typescript
+         * const client = new ProductHub.AudioPluginClient({
+         *   manufacturerId: "7222d546-9c72-43d5-8bd4-1667ce390ea4",
+         *   productId: "1487a36d-9bc8-4220-ba31-9998d743071f",
+         *   productName: "Groove Master 3000",
+         *   productPublicKey: `-----BEGIN PUBLIC KEY-----
+         * MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+         * -----END PUBLIC KEY-----`,
+         *   userResourceBaseDirectory: "/Users/<username>/Library/Application Support/<manufacturername>"
+         * });
+         * ```
+         *
+         * @example Testing with fingerprint override
+         * ```typescript
+         * // For automated testing - never use in production!
+         * const testClient = new ProductHub.AudioPluginClient({
+         *   // ... other options
+         *   hardwareFingerprint: "test-fingerprint-12345"
+         * });
+         * ```
+         *
+         * @throws {@link ProductHubError} If required parameters are missing
+         */
+        constructor(options) {
+            this.updateCheckResult = null;
+            const { manufacturerId, productId, productName, productPublicKey, userResourceBaseDirectory, hardwareFingerprint, currentVersion, currentBuildNumber, } = options;
+            if (!manufacturerId) {
+                throw new errors_1.ProductHubError('manufacturerId is required when constructing AudioPluginClient');
+            }
+            if (!productId) {
+                throw new errors_1.ProductHubError('productId is required when constructing AudioPluginClient');
+            }
+            if (!productName) {
+                throw new errors_1.ProductHubError('productName is required when constructing AudioPluginClient');
+            }
+            if (!productPublicKey) {
+                throw new errors_1.ProductHubError('productPublicKey is required when constructing AudioPluginClient');
+            }
+            if (hasLeadingWhitespaceLines(productPublicKey)) {
+                throw new errors_1.ProductHubError('productPublicKey must not contain lines with leading whitespaces');
+            }
+            if (!userResourceBaseDirectory) {
+                throw new errors_1.ProductHubError('userResourceBaseDirectory is required when constructing AudioPluginClient');
+            }
+            this.apiClient = new APIClient({
+                manufacturerId,
+                productId,
+            });
+            this.manufacturerId = manufacturerId;
+            this.productId = productId;
+            this.productName = productName;
+            this.productPublicKey = productPublicKey;
+            this.userResourceBaseDirectory = userResourceBaseDirectory;
+            this.currentVersion = currentVersion ?? null;
+            this.currentBuildNumber = currentBuildNumber ?? null;
+            this.hwfpUtil = HardwareFingerprintUtil.getInstance();
+            this.isTestEnvironment = isTestEnvironment();
+            if (hardwareFingerprint) {
+                if (!this.isTestEnvironment) {
+                    console.warn('Using overridden hardware fingerprint - not intended for production use!');
+                }
+                // hwfp util is a singleton so APIClient will also use the same override
+                this.hwfpUtil.setFingerprintOverride(hardwareFingerprint);
+            }
+            // Automatically check for updates on construction (fire-and-forget)
+            this.checkForUpdates().catch((ex) => {
+                console.error('Update check failed during AudioPluginClient construction:', ex);
+            });
+            this.checkUpdateSubscription().catch((ex) => {
+                if (!this.isTestEnvironment) {
+                    console.error('Subscription update check failed during AudioPluginClient construction:', ex);
+                }
+            });
+        }
+        /**
+         * Check and silently refresh persisted subscription activations when possible.
+         *
+         * If a local activation exists and is a subscription, and a login token is available
+         * in the configured credential backend, this method calls {@link updateSubscription}.
+         *
+         * @returns Promise that resolves to `true` if a newer subscription activation was persisted
+         * @remarks Returns `false` unless a local subscription and usable stored session both exist.
+         * A successful refresh may overwrite the local activation with a later expiration.
+         * @example
+         * ```typescript
+         * const refreshed = await client.checkUpdateSubscription();
+         * ```
+         */
+        async checkUpdateSubscription() {
+            const localActivation = this.loadActivationFromDisk();
+            if (!localActivation || localActivation.type !== types_1.LicenseType.Subscription) {
+                return false;
+            }
+            if (!(await this.apiClient.hasStoredSession())) {
+                return false;
+            }
+            return await this.updateSubscription();
+        }
+        /**
+         * Refresh an existing persisted subscription activation from the Product Hub API.
+         *
+         * This method uses the token persisted in the configured credential backend to call product
+         * activation without interactive credentials. If the retrieved subscription has a later
+         * expiration timestamp than the currently persisted subscription activation, the local
+         * activation file is overwritten.
+         *
+         * @returns Promise that resolves to `true` if local subscription activation was updated
+         * @remarks Only an existing subscription can be updated, and only when the verified remote
+         * activation expires later. Non-applicable cases and operational failures return `false`.
+         * @example
+         * ```typescript
+         * const updated = await client.updateSubscription();
+         * ```
+         */
+        async updateSubscription() {
+            try {
+                const existingActivation = this.loadActivationFromDisk();
+                if (!existingActivation || existingActivation.type !== types_1.LicenseType.Subscription) {
+                    return false;
+                }
+                const existingExpiration = existingActivation.expires
+                    ? new Date(existingActivation.expires).getTime()
+                    : null;
+                if (!existingExpiration) {
+                    return false;
+                }
+                const result = await this.apiClient.activateProductWithStoredSession();
+                const refreshedActivation = result.activation;
+                if (result.sessionStatus !== types_1.SessionStatus.Valid ||
+                    !refreshedActivation ||
+                    refreshedActivation.type !== types_1.LicenseType.Subscription) {
+                    return false;
+                }
+                if (!this.verifyActivation(refreshedActivation)) {
+                    return false;
+                }
+                const refreshedExpiration = refreshedActivation.expires
+                    ? new Date(refreshedActivation.expires).getTime()
+                    : null;
+                if (!refreshedExpiration || refreshedExpiration <= existingExpiration) {
+                    return false;
+                }
+                this.persistActivationOnDisk(refreshedActivation);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        /**
+         * Activate your audio plugin with a full license using user credentials.
+         *
+         * This method authenticates the user, activates the product, verifies the activation
+         * signature, and automatically persists the activation data to local .ops files
+         * for future offline validation.
+         *
+         * @param params - User credentials for activation
+         * @returns Promise that resolves to `true` if activation was successful, `false` for network/server errors
+         * @throws {NotAuthorizedError} When email/password credentials are invalid
+         *
+         * @example
+         * ```typescript
+         * try {
+         *   const success = await client.activateProduct({
+         *     email: "user@example.com",
+         *     password: "userPassword123"
+         *   });
+         *
+         *   if (success) {
+         *     console.log("License activated successfully!");
+         *     console.log("Serial:", client.licenseSerial());
+         *   } else {
+         *     console.log("Activation failed, please retry");
+         *   }
+         * } catch (error) {
+         *   if (error instanceof NotAuthorizedError) {
+         *     console.log("Invalid email or password");
+         *   }
+         * }
+         * ```
+         *
+         * @remarks
+         * - Hardware fingerprint is detected automatically
+         * - Activation data is cryptographically verified before persistence
+         * - Safe to call multiple times - won't create duplicate activations
+         * - Authentication errors (wrong credentials) throw `NotAuthorizedError`
+         * - Network/server errors, missing licenses etc. return `false`
+         */
+        async activateProduct(params) {
+            try {
+                const response = await this.apiClient.activateProduct({
+                    email: params.email,
+                    password: params.password,
+                });
+                if (this.verifyActivation(response)) {
+                    this.persistActivationOnDisk(response);
+                    return true;
+                }
+                return false;
+            }
+            catch (ex) {
+                if (ex instanceof errors_1.NotAuthorizedError) {
+                    throw ex;
+                }
+                else {
+                    if (!this.isTestEnvironment) {
+                        console.error(`Activation failed: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                    }
+                    return false;
+                }
+            }
+        }
+        /**
+         * Activate the product using only email and serial — no password or login required.
+         *
+         * The license is claimed and activated in a single call. Use this flow when the
+         * manufacturer has "Authentication Type = None" and "Email+Serial Claiming" enabled
+         * in Product Hub (i.e. no SSO provider is configured).
+         *
+         * @param params - Email and serial received from purchase
+         * @returns Promise that resolves to `true` if activation was successful, `false` otherwise
+         * @throws {NotAuthorizedError} When email+serial claiming is not enabled for this manufacturer, or the serial is not found
+         *
+         * @example
+         * ```typescript
+         * try {
+         *   const success = await client.activateProductWithSerial({
+         *     email: 'user@example.com',
+         *     serial: 'STD-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX',
+         *   });
+         *   if (success) {
+         *     unlockPlugin();
+         *     aboutDialog.setSerialCodeForDisplay(client.licenseSerial());
+         *   }
+         * } catch (ex) {
+         *   if (ex instanceof NotAuthorizedError) {
+         *     activationOverlay.setMessage('Unable to activate. Check your email and serial code.');
+         *   }
+         * }
+         * ```
+         */
+        async activateProductWithSerial(params) {
+            try {
+                const response = await this.apiClient.activateProductWithEmailAndSerial(params.email, params.serial);
+                if (this.verifyActivation(response)) {
+                    this.persistActivationOnDisk(response);
+                    return true;
+                }
+                return false;
+            }
+            catch (ex) {
+                if (ex instanceof errors_1.NotAuthorizedError) {
+                    throw ex;
+                }
+                else {
+                    if (!this.isTestEnvironment) {
+                        console.error(`Activation failed: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                    }
+                    return false;
+                }
+            }
+        }
+        /**
+         * Claim a reseller-purchased serial to the user's account and activate in one call.
+         *
+         * Use this when a user already has an account (SSO login) but bought a license
+         * serial from a reseller shop. The serial is claimed to their account and then
+         * activated, all in a single operation.
+         *
+         * This method always logs in with the supplied credentials. To claim a serial using
+         * the active stored session, call {@link claimAndActivateLicenseWithStoredSession}.
+         *
+         * @param params - User credentials and reseller serial
+         * @returns Promise that resolves to `true` if activation was successful, `false` otherwise
+         * @throws {@link NotAuthorizedError} When the supplied credentials are invalid.
+         *
+         * @example
+         * ```typescript
+         * try {
+         *   const success = await client.claimAndActivateLicenseWithSerial({
+         *     email: 'user@example.com',
+         *     password: 'secret',
+         *     serial: 'STD-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX',
+         *   });
+         *   if (success) {
+         *     unlockPlugin();
+         *     aboutDialog.setSerialCodeForDisplay(client.licenseSerial());
+         *   }
+         * } catch (ex) {
+         *   if (ex instanceof NotAuthorizedError) {
+         *     activationOverlay.setMessage('Invalid credentials or serial already owned by another account.');
+         *   }
+         * }
+         * ```
+         *
+         * @remarks A verified activation is persisted locally. Missing, disabled, or conflicting
+         * serials and other non-authentication failures return `false`.
+         */
+        async claimAndActivateLicenseWithSerial(params) {
+            try {
+                const response = await this.apiClient.activateProduct({
+                    email: params.email,
+                    password: params.password,
+                    serial: params.serial,
+                });
+                if (this.verifyActivation(response)) {
+                    this.persistActivationOnDisk(response);
+                    return true;
+                }
+                return false;
+            }
+            catch (ex) {
+                if (ex instanceof errors_1.NotAuthorizedError) {
+                    throw ex;
+                }
+                else {
+                    if (!this.isTestEnvironment) {
+                        console.error(`Activation failed: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                    }
+                    return false;
+                }
+            }
+        }
+        /**
+         * Claim a reseller serial and activate it using the active stored session.
+         *
+         * @param params - Reseller serial to claim and activate.
+         * @returns `true` when a signed activation is verified and persisted; otherwise `false`.
+         * @remarks
+         * This method never performs a credential login. Missing or invalid sessions, serial
+         * conflicts, network failures, and invalid activation signatures are converted to `false`.
+         * Use {@link restoreActivationFromStoredSession} when the caller needs independent session
+         * and activation statuses.
+         * @example
+         * ```typescript
+         * const activated = await client.claimAndActivateLicenseWithStoredSession({
+         *   serial: 'STD-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX',
+         * });
+         * ```
+         */
+        async claimAndActivateLicenseWithStoredSession(params) {
+            try {
+                const result = await this.apiClient.activateProductWithStoredSession(params.serial);
+                if (result.activation && this.verifyActivation(result.activation)) {
+                    this.persistActivationOnDisk(result.activation);
+                    return true;
+                }
+                return false;
+            }
+            catch (ex) {
+                if (!this.isTestEnvironment) {
+                    console.error(`Activation failed: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                }
+                return false;
+            }
+        }
+        /**
+         * Check whether a usable login session is stored for this product and device.
+         *
+         * @returns A promise resolving to `true` when a usable session exists; otherwise `false`.
+         * @remarks Invalid stored tokens are removed by the underlying credential-store check.
+         */
+        async hasStoredSession() {
+            return await this.apiClient.hasStoredSession();
+        }
+        /**
+         * Read non-sensitive claims from the active stored login session.
+         *
+         * @returns The stored session's email, user ID, and expiration, or `null` when no usable
+         * session exists. The bearer token is never exposed.
+         * @example
+         * ```typescript
+         * const session = await client.getStoredSessionInfo();
+         * if (session) console.log(session.email, session.expiresAt);
+         * ```
+         */
+        async getStoredSessionInfo() {
+            return await this.apiClient.getStoredSessionInfo();
+        }
+        /**
+         * Clear the active stored login session.
+         *
+         * @returns A promise that resolves after the in-memory token and persisted credential have
+         * been cleared on a best-effort basis.
+         * @remarks This does not remove the locally persisted `.ops` activation file.
+         * @example
+         * ```typescript
+         * await client.clearStoredSession();
+         * ```
+         */
+        async clearStoredSession() {
+            await this.apiClient.clearStoredSession();
+        }
+        /**
+         * Restore product activation using the active stored session.
+         *
+         * @returns Independent session validity and local product activation statuses.
+         * @throws {@link ProductHubError} If the API request fails unexpectedly or the returned
+         * activation has an invalid signature.
+         * @remarks
+         * Session validity and product activation are independent: a valid session can return an
+         * unlicensed or expired activation status. Valid signed activations are persisted locally;
+         * invalid sessions are removed by the underlying API client.
+         * @example
+         * ```typescript
+         * const result = await client.restoreActivationFromStoredSession();
+         * if (
+         *   result.activationStatus === ActivationStatus.Licensed ||
+         *   result.activationStatus === ActivationStatus.Subscription
+         * ) {
+         *   unlockPlugin();
+         * }
+         * ```
+         */
+        async restoreActivationFromStoredSession() {
+            const result = await this.apiClient.activateProductWithStoredSession();
+            if (result.sessionStatus !== types_1.SessionStatus.Valid || !result.activation) {
+                return {
+                    sessionStatus: result.sessionStatus,
+                    activationStatus: this.getActivationStatus(),
+                };
+            }
+            if (!this.verifyActivation(result.activation)) {
+                throw new errors_1.ProductHubError('Stored-session activation signature verification failed');
+            }
+            this.persistActivationOnDisk(result.activation);
+            return {
+                sessionStatus: types_1.SessionStatus.Valid,
+                activationStatus: this.getActivationStatus(),
+            };
+        }
+        /**
+         * Activate a trial period for your audio plugin.
+         *
+         * Starts a new trial or reuses an existing valid trial activation.
+         * No user authentication is required - trials are tied to the hardware fingerprint.
+         * The trial data is automatically verified and persisted to local .ops files.
+         *
+         * @returns Promise that resolves to `true` if trial activation was successful, `false` otherwise
+         * @throws {TrialExpiredError} When a trial was already used on this machine and has expired
+         *
+         * @example
+         * ```typescript
+         * const success = await client.activateTrial();
+         *
+         * if (success) {
+         *   const remainingMs = client.remainingTrialTime();
+         *   const days = Math.floor(remainingMs / (24 * 60 * 60 * 1000));
+         *   console.log(`Trial activated! ${days} days remaining.`);
+         * } else {
+         *   console.log("Trial activation failed");
+         * }
+         * ```
+         *
+         * @remarks
+         * - Hardware fingerprint prevents trial abuse across different machines
+         * - Trial period is determined by Product Hub configuration
+         * - Automatically updates last launch time
+         * - Expired trials throw `TrialExpiredError`
+         * - Safe to call multiple times - reuses existing valid trials
+         */
+        async activateTrial() {
+            try {
+                const response = await this.apiClient.activateTrial();
+                if (this.verifyTrial(response)) {
+                    this.persistTrialActivationOnDisk(response);
+                    return this.remainingTrialTime() > 0;
+                }
+            }
+            catch (ex) {
+                if (!this.isTestEnvironment) {
+                    console.error(`Trial activation failed: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                }
+                if (ex.status === 403 &&
+                    ex.message === 'Trial expired') {
+                    throw new errors_1.TrialExpiredError();
+                }
+                return false;
+            }
+            return false;
+        }
+        /**
+         * Check if the plugin is activated with a full license.
+         *
+         * Verifies that a valid license activation exists locally, including
+         * signature verification and hardware fingerprint validation.
+         *
+         * @returns `true` if the plugin has a valid full license, `false` otherwise
+         *
+         * @example
+         * ```typescript
+         * if (client.isActivatedWithLicense()) {
+         *   console.log("Full license active!");
+         *   console.log("License serial:", client.licenseSerial());
+         * } else {
+         *   console.log("No license - maybe try activation or trial");
+         * }
+         * ```
+         *
+         * @remarks
+         * - Validates hardware fingerprint to prevent license transfer
+         * - Safe to call frequently - uses cached local data
+         */
+        isActivatedWithLicense() {
+            try {
+                const activation = this.loadActivationFromDisk();
+                if (!activation) {
+                    return false;
+                }
+                // Check if license has expired
+                if (activation.expires) {
+                    const expirationDate = new Date(activation.expires);
+                    const now = new Date();
+                    if (now > expirationDate) {
+                        return false;
+                    }
+                }
+                return this.verifyActivation(activation);
+            }
+            catch (ex) {
+                if (!this.isTestEnvironment) {
+                    console.error(`Could not assess whether product is activated with license: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                }
+                return false;
+            }
+        }
+        /**
+         * Get the remaining trial time in milliseconds.
+         *
+         * Calculates how much time is left in the current trial period, including
+         * signature verification and hardware fingerprint validation. Returns 0
+         * if no valid trial exists or if the trial has expired.
+         *
+         * @returns Remaining trial time in milliseconds, or 0 if no valid trial
+         *
+         * @example
+         * ```typescript
+         * const remainingMs = client.remainingTrialTime();
+         *
+         * if (remainingMs > 0) {
+         *   const days = Math.floor(remainingMs / (24 * 60 * 60 * 1000));
+         *   const hours = Math.floor((remainingMs % (24 * 60 * 60 * 1000)) / (60 * 60 * 1000));
+         *   console.log(`Trial: ${days} days, ${hours} hours remaining`);
+         * } else {
+         *   console.log("No active trial");
+         * }
+         * ```
+         *
+         * @remarks
+         * - Automatically updates last launch time when called
+         * - Performs cryptographic verification of trial data
+         * - Returns exact milliseconds for precise timing calculations
+         */
+        remainingTrialTime() {
+            try {
+                const now = Date.now();
+                const lastLaunch = this.readLastTrialLaunchTime() || 0;
+                if (lastLaunch > now) {
+                    // Prevent clock tampering by ensuring last launch time is not in the future
+                    if (!this.isTestEnvironment) {
+                        console.warn('System clock appears to have been set back - invalidating trial');
+                    }
+                    return 0;
+                }
+                const trial = this.loadTrialActivationFromDisk();
+                if (!trial) {
+                    return 0;
+                }
+                const valid = this.verifyTrial(trial);
+                if (!valid) {
+                    return 0;
+                }
+                const periodMs = trial.trial_days * 24 * 60 * 60 * 1000;
+                const remaining = Math.max(0, trial.timestamp + periodMs - now);
+                this.updateLastTrialLaunchTime();
+                return remaining;
+            }
+            catch (ex) {
+                if (!this.isTestEnvironment) {
+                    console.error(`Could not assess remaining trial time: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                }
+                return 0;
+            }
+        }
+        /**
+         * Check if the plugin is activated and ready to use.
+         *
+         * Returns `true` if the plugin has either a valid full license OR a valid trial
+         * with remaining time. This is the primary method to check if your plugin
+         * should be functional.
+         *
+         * @returns `true` if plugin is activated (licensed or trial), `false` otherwise
+         *
+         * @example
+         * ```typescript
+         * // Basic usage
+         * if (client.isActivated()) {
+         *   // Enable all plugin features
+         *   enableAudioProcessing();
+         * } else {
+         *   // Show activation dialog or disable features
+         *   showActivationDialog();
+         * }
+         *
+         * // Advanced usage with status details
+         * if (client.isActivated()) {
+         *   if (client.isActivatedWithLicense()) {
+         *     console.log("Full license - all features activated");
+         *   } else {
+         *     const days = Math.floor(client.remainingTrialTime() / (24 * 60 * 60 * 1000));
+         *     console.log(`Trial mode - ${days} days remaining`);
+         *   }
+         * }
+         * ```
+         *
+         * @remarks
+         * - This is typically the main method you'll use in your plugin logic
+         * - Combines both license and trial validation
+         * - Efficient - uses cached data where possible
+         */
+        isActivated() {
+            return this.isActivatedWithLicense() || this.remainingTrialTime() > 0;
+        }
+        /**
+         * Get detailed activation status information.
+         *
+         * Provides more granular information about the current activation state
+         * than the simple boolean methods. Useful for showing specific UI states
+         * or handling different scenarios in your plugin.
+         *
+         * @returns Current activation status as an enum value
+         *
+         * @example
+         * ```typescript
+         * import { ActivationStatus } from "@gorilla-engine-sdk/ge-product-hub";
+         *
+         * switch (client.getActivationStatus()) {
+         *   case ActivationStatus.Licensed:
+         *     showLicensedUI();
+         *     console.log("Serial:", client.licenseSerial());
+         *     break;
+         *
+         *   case ActivationStatus.Trial:
+         *     const days = Math.floor(client.remainingTrialTime() / (24 * 60 * 60 * 1000));
+         *     showTrialUI(days);
+         *     break;
+         *
+         *   case ActivationStatus.TrialExpired:
+         *     showTrialExpiredUI();
+         *     break;
+         *
+         *   case ActivationStatus.None:
+         *   case ActivationStatus.LicenseExpired:
+         *   case ActivationStatus.SubscriptionExpired:
+         *     showActivationRequiredUI();
+         *     break;
+         * }
+         * ```
+         *
+         * @see {@link ActivationStatus} for all possible status values
+         *
+         * @remarks
+         * - More informative than `isActivated()` or `isActivatedWithLicense()`
+         * - Helps tailor user experience based on exact activation state
+         * - Always returns a valid enum value
+         * - Note that this is the local activation status. This is especially important in regard to trials as there can be a possible edge case.
+    If the user trialed the product in the past and then later deleted the installation and they now want to trial again, the local activation state would be `None` and
+    `activateTrial()` would throw `TrialExpiredError` with the local activation state staying `None`. If on the other hand the installation is not deleted so the activation
+    file still exists, the local activation state would be `TrialExpired`.
+         */
+        getActivationStatus() {
+            // Check for any persisted license activation on disk (valid or expired)
+            const activation = this.loadActivationFromDisk();
+            if (activation) {
+                // we have a license activation - check if it's valid
+                if (this.isActivatedWithLicense()) {
+                    // license is valid
+                    if (activation.type === types_1.LicenseType.Subscription) {
+                        return types_1.ActivationStatus.Subscription;
+                    }
+                    return types_1.ActivationStatus.Licensed;
+                }
+                else if (activation.expires) {
+                    // License exists but is expired
+                    if (activation.type === types_1.LicenseType.Subscription) {
+                        return types_1.ActivationStatus.SubscriptionExpired;
+                    }
+                    return types_1.ActivationStatus.LicenseExpired;
+                }
+                // if we've come to this point, license exists but signature verification failed - treat as None
+            }
+            // No valid license - check for trial activation
+            if (this.remainingTrialTime() > 0) {
+                return types_1.ActivationStatus.Trial;
+            }
+            if (this.loadTrialActivationFromDisk() !== undefined) {
+                return types_1.ActivationStatus.TrialExpired;
+            }
+            return types_1.ActivationStatus.None;
+        }
+        /**
+         * Get the license serial number if the plugin is fully activated.
+         *
+         * Returns the unique serial number associated with the current license
+         * activation. Useful for support purposes, logging, or displaying
+         * license information to users.
+         *
+         * @returns License serial number if licensed, empty string otherwise
+         *
+         * @example
+         * ```typescript
+         * const serial = client.licenseSerial();
+         *
+         * if (serial) {
+         *   console.log(`Licensed version - Serial: ${serial}`);
+         *   // Maybe show in about dialog
+         *   showAboutDialog({ serial });
+         * } else {
+         *   console.log("Not licensed");
+         * }
+         * ```
+         *
+         * @remarks
+         * - Only returns a value when `isActivatedWithLicense()` is `true`
+         * - Serial numbers are unique per license activation
+         * - Useful for customer support and license tracking
+         */
+        licenseSerial() {
+            if (!this.isActivatedWithLicense())
+                return '';
+            const activation = this.loadActivationFromDisk();
+            return activation?.serial || '';
+        }
+        /**
+         * Get the type of the current license.
+         *
+         * Returns the license type (Standard, NFR, Free, or Subscription) if the
+         * plugin is activated with a valid license. Returns null for trial activations
+         * or when no valid license exists.
+         *
+         * @returns License type if activated with license, null otherwise
+         *
+         * @example
+         * ```typescript
+         * const type = client.licenseType();
+         * if (type) {
+         *   console.log(`License type: ${type}`);
+         *   if (type === LicenseType.Subscription) {
+         *     console.log("Subscription license - check expiration");
+         *   }
+         * }
+         * ```
+         *
+         * @remarks
+         * - Returns null for trials (use `getActivationStatus()` to check for trials)
+         * - Useful for displaying license information to users
+         * - Only meaningful when `isActivatedWithLicense()` is `true`
+         */
+        licenseType() {
+            if (!this.isActivatedWithLicense())
+                return null;
+            const activation = this.loadActivationFromDisk();
+            return activation?.type ? activation.type : null;
+        }
+        /**
+         * Check if the current license is time-limited (subscription or expiring).
+         *
+         * Returns `true` if the persisted license activation has an expiration date.
+         *
+         * @returns `true` if license is time-limited, `false` if perpetual, trial or no license
+         *
+         * @example
+         * ```typescript
+         * if (client.isTimeLimitedLicense()) {
+         *   const expires = client.licenseExpiration();
+         *   if (expires) {
+         *     console.log(`License expires on ${expires.toDateString()}`);
+         *   }
+         * } else {
+         *   console.log("Perpetual license");
+         * }
+         * ```
+         *
+         * @remarks
+         * - This method does not verify the persisted activation or check whether it has expired
+         * - Helps determine if renewal reminders are needed
+         * - Time-limited licenses have an `expires` date in the activation data
+         */
+        isTimeLimitedLicense() {
+            const activation = this.loadActivationFromDisk();
+            return activation?.expires ? true : false;
+        }
+        /**
+         * Get the expiration date from the persisted license activation.
+         *
+         * Returns the persisted expiration date, or null if the license is perpetual
+         * (never expires), no license activation exists, or the activation is a trial.
+         * For trials, use `remainingTrialTime()` to check remaining time.
+         *
+         * @returns Expiration date if licensed and has expiration, null otherwise (even for active trials)
+         *
+         * @example
+         * ```typescript
+         * const expires = client.licenseExpiration();
+         * if (expires) {
+         *   const daysLeft = Math.ceil((expires.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+         *   console.log(`License expires in ${daysLeft} days`);
+         * } else {
+         *   console.log("Perpetual license");
+         * }
+         * ```
+         *
+         * @remarks This method does not verify the persisted activation or check whether the date
+         * has passed. Use {@link getActivationStatus} to determine current validity.
+         */
+        licenseExpiration() {
+            const activation = this.loadActivationFromDisk();
+            return activation?.expires ? new Date(activation.expires) : null;
+        }
+        /**
+         * Write an offline activation file for support purposes.
+         *
+         * This method creates an offline activation file (`.ops`) containing your product's hardware
+         * fingerprint and configuration details. This is useful when end users don't have internet
+         * access - they can send you this file to obtain their system information, allowing you to
+         * create a manual activation in the Product Hub backend and provide them with a signed
+         * activation file for offline use.
+         *
+         * @param options - Configuration options for the offline activation file
+         * @returns Nothing. Writes `{productName}.ops`, or leaves an existing file untouched when
+         * `overwriteExisting` is `false`.
+         * @throws {@link ProductHubError} If hardware fingerprint generation fails.
+         * @throws {@link Error} If the destination cannot be created or written.
+         *
+         * @example
+         * ```typescript
+         * // Write to default location without overwriting
+         * client.writeOfflineActivationFile();
+         *
+         * // Write to custom location with overwrite enabled
+         * client.writeOfflineActivationFile({
+         *   customFolderPath: "/Users/username/Desktop",
+         *   overwriteExisting: true
+         * });
+         *
+         * // Just enable overwriting in default location
+         * client.writeOfflineActivationFile({ overwriteExisting: true });
+         * ```
+         *
+         * @remarks
+         * - The file contains hardware fingerprint, product ID, and signature versions
+         * - File is named `{productName}.ops` (e.g., "MyPlugin.ops")
+         * - Safe to call multiple times - respects `overwriteExisting` option
+         * - Automatically creates necessary directories
+         * - For offline activation workflow with customer support
+         */
+        writeOfflineActivationFile(options = {}) {
+            const { customFolderPath, overwriteExisting = false } = options;
+            const filePath = path.join(path.join(customFolderPath || this.opsFileFolderPath()), `${this.productName}.ops`);
+            if (fs.existsSync(filePath)) {
+                if (!this.isTestEnvironment) {
+                    console.log(`Offline .ops file already exists at ${filePath} - ${overwriteExisting ? 'overwriting' : 'not overwriting'}`);
+                }
+                if (overwriteExisting) {
+                    fs.unlinkSync(filePath);
+                }
+                else {
+                    return;
+                }
+            }
+            const payload = {
+                signature: 'offline',
+                product_id: this.productId,
+                product_name: this.productName,
+                manufacturer_id: this.manufacturerId,
+                hardware_fingerprint: this.hwfpUtil.getFingerprint(),
+                hardware_fingerprint_version: exports.HARDWARE_FINGERPRINT_VERSION,
+                signature_seed_version: exports.SIGNATURE_SEED_VERSION,
+            };
+            safeWriteJSON(filePath, payload);
+        }
+        /**
+         * Verify activation signature (v6 format only)
+         */
+        verifyActivation(input) {
+            const { serial, signature, expires, signature_seed_version } = input;
+            let message;
+            if (signature_seed_version === 5) {
+                // Version 5 signature: fingerprint:serial:product_identifier:version
+                message = `${this.hwfpUtil.getFingerprint()}:${serial}:${this.productName}:${signature_seed_version}`;
+            }
+            else {
+                // Version 6+ signature: fingerprint:serial:product_id:expires:version
+                const expiresTimestamp = expires ? new Date(expires).getTime() : null;
+                message = `${this.hwfpUtil.getFingerprint()}:${serial}:${this.productId}:${expiresTimestamp}:${signature_seed_version || exports.SIGNATURE_SEED_VERSION}`;
+            }
+            return verifySignature(this.productPublicKey, message, signature);
+        }
+        /**
+         * Verify trial signature
+         */
+        verifyTrial(input) {
+            const { timestamp, trial_days, signature, signature_seed_version } = input;
+            let message;
+            if (signature_seed_version === 5) {
+                // Version 5 trial signature: fingerprint:timestamp:product_identifier:trial_days:version
+                message = `${this.hwfpUtil.getFingerprint()}:${timestamp}:${this.productName}:${trial_days}:${signature_seed_version}`;
+            }
+            else {
+                // Version 6+ trial signature: fingerprint:timestamp:product_id:trial_days:version
+                message = `${this.hwfpUtil.getFingerprint()}:${timestamp}:${this.productId}:${trial_days}:${signature_seed_version || exports.SIGNATURE_SEED_VERSION}`;
+            }
+            return verifySignature(this.productPublicKey, message, signature);
+        }
+        // File persistence methods
+        opsFileFolderPath() {
+            return path.join(this.userResourceBaseDirectory, this.productName);
+        }
+        opsFilePath() {
+            return path.join(this.opsFileFolderPath(), `${this.productName}.ops`);
+        }
+        ltsFilePath() {
+            return path.join(this.opsFileFolderPath(), `${this.productName}.lts`);
+        }
+        persistActivationOnDisk(activationResponseJson) {
+            safeWriteJSON(this.opsFilePath(), activationResponseJson);
+        }
+        persistTrialActivationOnDisk(activationResponseJson) {
+            safeWriteJSON(this.opsFilePath(), activationResponseJson);
+        }
+        loadActivationFromDisk() {
+            const opsFileJson = safeReadJSON(this.opsFilePath());
+            if (!opsFileJson || !opsFileJson.signature) {
+                return undefined;
+            }
+            // Detect version 5 vs version 6 format
+            if (opsFileJson.version === 5) {
+                // Version 5 format: map fields to version 6 structure
+                if (!opsFileJson.license_key || !opsFileJson.fingerprint) {
+                    return undefined;
+                }
+                return {
+                    type: types_1.LicenseType.Standard, // Assume Standard license for version 5
+                    serial: opsFileJson.license_key,
+                    signature: opsFileJson.signature,
+                    expires: opsFileJson.expires || null,
+                    hardware_fingerprint: opsFileJson.fingerprint,
+                    hardware_fingerprint_version: opsFileJson.hwfp_version || 2,
+                    signature_seed_version: 5,
+                    // Required fields with null values for version 5 compatibility
+                    user_id: null,
+                    user_email: opsFileJson.user_email || null,
+                    product_id: this.productId,
+                    product_name: this.productName,
+                    manufacturer_id: null,
+                    manufacturer_name: null,
+                };
+            }
+            else {
+                // Version 6+ format: use current structure
+                if (!opsFileJson.serial) {
+                    return undefined;
+                }
+                return opsFileJson;
+            }
+        }
+        loadTrialActivationFromDisk() {
+            const opsFileJson = safeReadJSON(this.opsFilePath());
+            if (!opsFileJson || !opsFileJson.signature) {
+                return undefined;
+            }
+            // Detect version 5 vs version 6 format
+            if (opsFileJson.version === 5) {
+                // Version 5 trial format: map fields to version 6 structure
+                if (!opsFileJson.timestamp || opsFileJson.trialDays == null) {
+                    return undefined;
+                }
+                return {
+                    signature: opsFileJson.signature,
+                    timestamp: Number(opsFileJson.timestamp),
+                    trial_days: Number(opsFileJson.trialDays),
+                    hardware_fingerprint: opsFileJson.fingerprint || this.hwfpUtil.getFingerprint(),
+                    hardware_fingerprint_version: opsFileJson.hwfp_version || 2,
+                    signature_seed_version: 5,
+                    // Required fields with null values for version 5 compatibility
+                    product_id: this.productId,
+                    product_name: this.productName,
+                    manufacturer_id: null,
+                    manufacturer_name: null,
+                };
+            }
+            else {
+                // Version 6+ format: use current structure
+                if (!opsFileJson.timestamp || opsFileJson.trial_days == null) {
+                    return undefined;
+                }
+                return opsFileJson;
+            }
+        }
+        updateLastTrialLaunchTime() {
+            try {
+                const payload = { lts: Date.now() };
+                safeWriteJSON(this.ltsFilePath(), payload);
+            }
+            catch (ex) {
+                if (!this.isTestEnvironment) {
+                    console.error(`Could not update last trial launch time: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                }
+            }
+        }
+        readLastTrialLaunchTime() {
+            try {
+                const ltsFileJson = safeReadJSON(this.ltsFilePath());
+                if (!ltsFileJson || !ltsFileJson.lts) {
+                    return undefined;
+                }
+                return ltsFileJson.lts;
+            }
+            catch (ex) {
+                if (!this.isTestEnvironment) {
+                    console.error(`Could not read last trial launch time: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                }
+                return undefined;
+            }
+        }
+        /**
+         * Check for product updates from the Product Hub API.
+         *
+         * This method queries the latest version available in the Release distribution channel
+         * and compares it with the currently installed version. Results are cached and can
+         * be accessed via `isUpdateAvailable()`, `getUpdateReferralURL()`, and `getUpdateFiles()`.
+         *
+         * The method is automatically called once during construction but can be called again
+         * to re-check for updates (e.g., if the initial check failed due to network issues).
+         *
+         * @returns Promise that resolves to `true` if the check succeeded, `false` if it failed
+         *
+         * @example
+         * ```typescript
+         * // Manual re-check for updates
+         * const success = await client.checkForUpdates();
+         * if (success && client.isUpdateAvailable()) {
+         *   console.log("Update available!");
+         * }
+         * ```
+         */
+        async checkForUpdates() {
+            // If no version was provided, update checking is disabled
+            if (!this.currentVersion) {
+                this.updateCheckResult = {
+                    success: false,
+                    updateAvailable: false,
+                    latestBuild: null,
+                    updateReferralUrl: null,
+                };
+                return false;
+            }
+            try {
+                // Get latest version from API
+                const response = await this.apiClient.getLatestProductVersion();
+                // Detect current OS
+                const currentOs = this.detectOperatingSystem();
+                // Find matching build for our OS
+                const matchingBuild = this.selectBuildForOS(response.builds, currentOs);
+                if (!matchingBuild) {
+                    // No build available for this OS
+                    this.updateCheckResult = {
+                        success: true,
+                        updateAvailable: false,
+                        latestBuild: null,
+                        updateReferralUrl: response.update_referral_url,
+                    };
+                    return true;
+                }
+                // Compare versions
+                const updateAvailable = this.isNewerVersion(matchingBuild);
+                this.updateCheckResult = {
+                    success: true,
+                    updateAvailable,
+                    latestBuild: matchingBuild,
+                    updateReferralUrl: response.update_referral_url,
+                };
+                return true;
+            }
+            catch (ex) {
+                if (!this.isTestEnvironment) {
+                    console.error(`Update check failed: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                }
+                this.updateCheckResult = {
+                    success: false,
+                    updateAvailable: false,
+                    latestBuild: null,
+                    updateReferralUrl: null,
+                };
+                return false;
+            }
+        }
+        /**
+         * Check if an update is available for this product.
+         *
+         * @returns `true` if an update is available, `false` otherwise
+         *
+         * @remarks
+         * Returns `false` if the update check hasn't been performed yet, failed,
+         * or if no update is available.
+         *
+         * @example
+         * ```typescript
+         * if (client.isUpdateAvailable()) {
+         *   console.log("New version available!");
+         *   console.log("Download from:", client.getUpdateReferralURL());
+         * }
+         * ```
+         */
+        isUpdateAvailable() {
+            return this.updateCheckResult?.updateAvailable ?? false;
+        }
+        /**
+         * Get the update referral URL for this product.
+         *
+         * This URL can be used to direct users to a download page or update instructions.
+         * The URL is configured per-product in the Product Hub web interface.
+         *
+         * @returns The update referral URL, or `null` if not available or check failed
+         *
+         * @example
+         * ```typescript
+         * const url = client.getUpdateReferralURL();
+         * if (url) {
+         *   // Open URL in browser or show to user
+         *   console.log("Visit:", url);
+         * }
+         * ```
+         */
+        getUpdateReferralURL() {
+            return this.updateCheckResult?.updateReferralUrl ?? null;
+        }
+        /**
+         * Get the downloadable files for the latest product update.
+         *
+         * Returns an array of files (installers, packages, etc.) that can be downloaded
+         * to update the product. Files are specific to the current operating system.
+         *
+         * @returns Promise that resolves to an array of build files, or empty array if unavailable
+         *
+         * @remarks
+         * - Returns empty array if update check failed or no update is available
+         * - Files are automatically filtered for the current operating system
+         * - Each file includes: id, name, size, sha256 hash, and download URL
+         *
+         * @example
+         * ```typescript
+         * const files = await client.getUpdateFiles();
+         * for (const file of files) {
+         *   console.log(`Download: ${file.name} (${file.size} bytes)`);
+         *   console.log(`URL: ${file.url}`);
+         *   console.log(`SHA256: ${file.sha256}`);
+         * }
+         * ```
+         */
+        async getUpdateFiles() {
+            if (!this.updateCheckResult?.success ||
+                !this.updateCheckResult?.updateAvailable ||
+                !this.updateCheckResult?.latestBuild) {
+                return [];
+            }
+            try {
+                const buildId = this.updateCheckResult.latestBuild.id;
+                return await this.apiClient.getBuildFiles(buildId);
+            }
+            catch (ex) {
+                if (!this.isTestEnvironment) {
+                    console.error(`Failed to fetch update files: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+                }
+                return [];
+            }
+        }
+        /**
+         * Detect the current operating system.
+         * @private
+         */
+        detectOperatingSystem() {
+            const platform = process.platform;
+            if (platform === 'darwin') {
+                return 'macOS';
+            }
+            else if (platform === 'win32') {
+                return 'Windows';
+            }
+            // Something is wrong here - unsupported platform
+            if (!this.isTestEnvironment) {
+                console.error(`Unrecognized platform "${platform}" - defaulting to "unknown" OS for update checks`);
+            }
+            return 'unknown';
+        }
+        /**
+         * Select the appropriate build for the given OS.
+         * Prefers exact OS match over "any".
+         * @private
+         */
+        selectBuildForOS(builds, os) {
+            // First try to find exact OS match
+            const exactMatch = builds.find((b) => b.os === os);
+            if (exactMatch) {
+                return exactMatch;
+            }
+            // Fall back to "any" OS
+            const anyMatch = builds.find((b) => b.os === 'any');
+            if (anyMatch) {
+                return anyMatch;
+            }
+            return null;
+        }
+        /**
+         * Check if the remote build version is newer than the current version.
+         * @private
+         */
+        isNewerVersion(remoteBuild) {
+            // This method is only called after we've verified currentVersion is not null
+            if (!this.currentVersion)
+                return false;
+            // Parse current version (format: "major.minor.revision")
+            const currentParts = this.currentVersion.split('.').map((p) => parseInt(p, 10));
+            const currentMajor = currentParts[0] || 0;
+            const currentMinor = currentParts[1] || 0;
+            const currentRevision = currentParts[2] || 0;
+            const currentBuild = this.currentBuildNumber ?? 0;
+            const remoteMajor = remoteBuild.major;
+            const remoteMinor = remoteBuild.minor;
+            const remoteRevision = remoteBuild.revision;
+            const remoteBuildNum = remoteBuild.build_number ?? 0;
+            // Compare major.minor.revision first
+            if (remoteMajor > currentMajor)
+                return true;
+            if (remoteMajor < currentMajor)
+                return false;
+            if (remoteMinor > currentMinor)
+                return true;
+            if (remoteMinor < currentMinor)
+                return false;
+            if (remoteRevision > currentRevision)
+                return true;
+            if (remoteRevision < currentRevision)
+                return false;
+            // If major.minor.revision are equal, compare build numbers
+            return remoteBuildNum > currentBuild;
+        }
+    }
+    ProductHub.AudioPluginClient = AudioPluginClient;
+})(ProductHub || (exports.ProductHub = ProductHub = {}));
+// --------------- Internal Helper Functions ---------------
+/**
+ * @internal
+ * Detect if we're running in a test environment.
+ * Checks multiple indicators commonly used by test frameworks.
+ */
+function isTestEnvironment() {
+    return (process.env.NODE_ENV === 'test' ||
+        typeof process.env.JEST_WORKER_ID !== 'undefined' ||
+        typeof global.it === 'function');
+}
+/**
+ * @internal
+ * Verify RSA-SHA256 signature using Node.js crypto module.
+ */
+function verifySignature(publicKey, message, signatureB64) {
+    try {
+        const verifier = (0, crypto_1.createVerify)('RSA-SHA256');
+        verifier.update(message);
+        verifier.end();
+        return verifier.verify(publicKey, new Uint8Array(Buffer.from(signatureB64, 'base64')));
+    }
+    catch (ex) {
+        if (!isTestEnvironment()) {
+            console.error(`Could not verify signature: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+        }
+        return false;
+    }
+}
+/**
+ * @internal
+ * Safely write JSON data to file with automatic directory creation.
+ */
+function safeWriteJSON(filePath, data) {
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+    }
+    catch (ex) {
+        if (!isTestEnvironment()) {
+            console.error(`Could not write JSON file to ${filePath}: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+        }
+    }
+}
+/**
+ * @internal
+ * Safely read and parse JSON data from file.
+ */
+function safeReadJSON(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return undefined;
+        const raw = fs.readFileSync(filePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (ex) {
+        if (!isTestEnvironment()) {
+            console.error(`Could not read JSON file from ${filePath}: ${ex?.message || ex}\n\nStack trace:\n${ex?.stack || ''}`);
+        }
+        return undefined;
+    }
+}
+/**
+ * @internal
+ * Validate if a string has any lines with leading whitespace.
+ */
+function hasLeadingWhitespaceLines(str) {
+    const lines = str.split('\n');
+    return lines.some((line) => /^\s+/.test(line));
+}