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

package/dist/lib/clients.d.ts

@@ -0,0 +1,1039 @@
+import { ActivateProductParams, ActivateProductResponse, ActivationRestoreResult, StoredSessionActivationResult, ActivateTrialResponse, APIClientOptions, AudioPluginClientOptions, AudioPluginActivationParams, AudioPluginActivationWithSerialParams, AudioPluginClaimAndActivateParams, AudioPluginStoredSessionSerialParams, ActivationStatus, StoredSessionInfo, OfflineActivationFileOptions, LicenseType, LatestProductVersionResponse, BuildFile } from './types';
+/**
+ * @internal
+ * Fixed signature seed version used for cryptographic verification.
+ */
+export declare const SIGNATURE_SEED_VERSION = 6;
+/**
+ * @internal
+ * Hardware fingerprint version for system identification.
+ */
+export declare const HARDWARE_FINGERPRINT_VERSION = 2;
+/**
+ * Gorilla Engine Product Hub Client Library
+ *
+ * Provides comprehensive audio plugin licensing with
+ * activation management & trial handling.
+ */
+export declare namespace 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 {
+        private manufacturerId;
+        private productId;
+        private hwfpUtil;
+        private bearerToken;
+        /**
+         * 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: APIClientOptions);
+        private credentialLocation;
+        private isTokenUsable;
+        private readPersistedToken;
+        private loadPersistedToken;
+        private persistToken;
+        /**
+         * 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.
+         */
+        hasStoredSession(): Promise<boolean>;
+        /**
+         * 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.
+         */
+        getStoredSessionInfo(): Promise<StoredSessionInfo | 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.
+         */
+        clearStoredSession(): Promise<void>;
+        /**
+         * 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);
+         * }
+         * ```
+         */
+        activateProductWithStoredSession(serial?: string): Promise<StoredSessionActivationResult>;
+        private validateNodeVersion;
+        /**
+         * 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');
+         * ```
+         */
+        loginUser(email: string, password: string): Promise<string>;
+        /**
+         * Activate a product with a license
+         */
+        private activateProductWithToken;
+        /**
+         * 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',
+         * });
+         * ```
+         */
+        activateProduct(params: ActivateProductParams): Promise<ActivateProductResponse>;
+        /**
+         * 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',
+         * );
+         * ```
+         */
+        activateProductWithEmailAndSerial(email: string, serial: string): Promise<ActivateProductResponse>;
+        /**
+         * 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);
+         * ```
+         */
+        activateTrial(): Promise<ActivateTrialResponse>;
+        /**
+         * 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);
+         * ```
+         */
+        getLatestProductVersion(): Promise<LatestProductVersionResponse>;
+        /**
+         * 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');
+         * ```
+         */
+        getBuildFiles(buildId: string): Promise<BuildFile[]>;
+    }
+    /**
+     * 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 {
+        private apiClient;
+        private manufacturerId;
+        private productId;
+        private productName;
+        private productPublicKey;
+        private userResourceBaseDirectory;
+        private hwfpUtil;
+        private readonly isTestEnvironment;
+        private currentVersion;
+        private currentBuildNumber;
+        private updateCheckResult;
+        /**
+         * 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: AudioPluginClientOptions);
+        /**
+         * 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();
+         * ```
+         */
+        checkUpdateSubscription(): Promise<boolean>;
+        /**
+         * 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();
+         * ```
+         */
+        updateSubscription(): Promise<boolean>;
+        /**
+         * 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`
+         */
+        activateProduct(params: AudioPluginActivationParams): Promise<boolean>;
+        /**
+         * 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.');
+         *   }
+         * }
+         * ```
+         */
+        activateProductWithSerial(params: AudioPluginActivationWithSerialParams): Promise<boolean>;
+        /**
+         * 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`.
+         */
+        claimAndActivateLicenseWithSerial(params: AudioPluginClaimAndActivateParams): Promise<boolean>;
+        /**
+         * 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',
+         * });
+         * ```
+         */
+        claimAndActivateLicenseWithStoredSession(params: AudioPluginStoredSessionSerialParams): Promise<boolean>;
+        /**
+         * 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.
+         */
+        hasStoredSession(): Promise<boolean>;
+        /**
+         * 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);
+         * ```
+         */
+        getStoredSessionInfo(): Promise<StoredSessionInfo | null>;
+        /**
+         * 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();
+         * ```
+         */
+        clearStoredSession(): Promise<void>;
+        /**
+         * 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();
+         * }
+         * ```
+         */
+        restoreActivationFromStoredSession(): Promise<ActivationRestoreResult>;
+        /**
+         * 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
+         */
+        activateTrial(): Promise<boolean>;
+        /**
+         * 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(): boolean;
+        /**
+         * 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(): number;
+        /**
+         * 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(): boolean;
+        /**
+         * 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(): ActivationStatus;
+        /**
+         * 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(): string;
+        /**
+         * 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(): LicenseType | 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(): boolean;
+        /**
+         * 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(): Date | 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?: OfflineActivationFileOptions): void;
+        /**
+         * Verify activation signature (v6 format only)
+         */
+        private verifyActivation;
+        /**
+         * Verify trial signature
+         */
+        private verifyTrial;
+        private opsFileFolderPath;
+        private opsFilePath;
+        private ltsFilePath;
+        private persistActivationOnDisk;
+        private persistTrialActivationOnDisk;
+        private loadActivationFromDisk;
+        private loadTrialActivationFromDisk;
+        private updateLastTrialLaunchTime;
+        private readLastTrialLaunchTime;
+        /**
+         * 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!");
+         * }
+         * ```
+         */
+        checkForUpdates(): Promise<boolean>;
+        /**
+         * 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(): boolean;
+        /**
+         * 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(): string | 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}`);
+         * }
+         * ```
+         */
+        getUpdateFiles(): Promise<BuildFile[]>;
+        /**
+         * Detect the current operating system.
+         * @private
+         */
+        private detectOperatingSystem;
+        /**
+         * Select the appropriate build for the given OS.
+         * Prefers exact OS match over "any".
+         * @private
+         */
+        private selectBuildForOS;
+        /**
+         * Check if the remote build version is newer than the current version.
+         * @private
+         */
+        private isNewerVersion;
+    }
+}