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

package/dist/lib/credentialStore.d.ts

@@ -0,0 +1,8 @@
+export interface CredentialLocation {
+    service: string;
+    account: string;
+}
+export declare function createCredentialLocation(manufacturerId: string): CredentialLocation;
+export declare function getCredential(service: string, account: string): Promise<string | null>;
+export declare function setCredential(service: string, account: string, password: string): Promise<void>;
+export declare function deleteCredential(service: string, account: string): Promise<void>;

package/dist/lib/credentialStore.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCredentialLocation = createCredentialLocation;
+exports.getCredential = getCredential;
+exports.setCredential = setCredential;
+exports.deleteCredential = deleteCredential;
+const cross_keychain_1 = require("cross-keychain");
+const testCredentials = new Map();
+const windowsCredentialManagerBackend = 'windows';
+const audioPluginClientService = 'PH-Audio-Plugin-Client';
+let keychainInitialization;
+function createCredentialLocation(manufacturerId) {
+    return {
+        service: audioPluginClientService,
+        account: manufacturerId,
+    };
+}
+function credentialKey(service, account) {
+    return `${service}\0${account}`;
+}
+function credentialTarget(service, account) {
+    return process.platform === 'win32'
+        ? `${service}:${account}`
+        : `service=${service}, account=${account}`;
+}
+async function ensureSecureKeychain() {
+    if (process.platform !== 'win32') {
+        return (0, cross_keychain_1.getKeyring)();
+    }
+    keychainInitialization ?? (keychainInitialization = (async () => {
+        await (0, cross_keychain_1.initBackend)((backend) => backend.id === windowsCredentialManagerBackend);
+        const backend = await (0, cross_keychain_1.getKeyring)();
+        if (backend.id !== windowsCredentialManagerBackend) {
+            throw new Error('The CLI-based Windows Credential Manager backend is required for Product Hub sessions');
+        }
+        return backend;
+    })());
+    return keychainInitialization;
+}
+async function getCredential(service, account) {
+    if (process.env.NODE_ENV === 'test') {
+        return testCredentials.get(credentialKey(service, account)) ?? null;
+    }
+    try {
+        await ensureSecureKeychain();
+        return await (0, cross_keychain_1.getPassword)(service, account);
+    }
+    catch (error) {
+        console.error(`[Product Hub credentials] read failed; target=${credentialTarget(service, account)}`, error);
+        throw error;
+    }
+}
+async function setCredential(service, account, password) {
+    if (process.env.NODE_ENV === 'test') {
+        testCredentials.set(credentialKey(service, account), password);
+        return;
+    }
+    try {
+        await ensureSecureKeychain();
+        await (0, cross_keychain_1.setPassword)(service, account, password);
+    }
+    catch (error) {
+        console.error(`[Product Hub credentials] write failed; target=${credentialTarget(service, account)}`, error);
+        throw error;
+    }
+}
+async function deleteCredential(service, account) {
+    if (process.env.NODE_ENV === 'test') {
+        testCredentials.delete(credentialKey(service, account));
+        return;
+    }
+    try {
+        await ensureSecureKeychain();
+        await (0, cross_keychain_1.deletePassword)(service, account);
+    }
+    catch (error) {
+        console.error(`[Product Hub credentials] delete failed; target=${credentialTarget(service, account)}`, error);
+        throw error;
+    }
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,48 @@
+/** Error returned for Product Hub API, network, runtime, and verification failures. */
+export declare class ProductHubError extends Error {
+    status?: number;
+    details?: any;
+    /**
+     * Create a Product Hub error.
+     *
+     * @param message - Human-readable failure description.
+     * @param status - Optional HTTP response status associated with the failure.
+     * @param details - Optional structured response or diagnostic details.
+     * @remarks API errors retain their HTTP status and response details when available.
+     * @example
+     * ```typescript
+     * throw new ProductHubError('Request failed', 500, { requestId: 'request-id' });
+     * ```
+     */
+    constructor(message: string, status?: number, details?: any);
+}
+/** Error indicating that Product Hub rejected authentication or authorization. */
+export declare class NotAuthorizedError extends ProductHubError {
+    /**
+     * Create an authorization error with HTTP status 401.
+     *
+     * @param message - Human-readable failure description.
+     * @param details - Optional structured response or diagnostic details.
+     * @remarks The default message is `Not authorized` and the status is always 401.
+     * @example
+     * ```typescript
+     * throw new NotAuthorizedError('Invalid credentials');
+     * ```
+     */
+    constructor(message?: string, details?: any);
+}
+/** Error indicating that the device's Product Hub trial has expired. */
+export declare class TrialExpiredError extends ProductHubError {
+    /**
+     * Create a trial-expiration error with HTTP status 403.
+     *
+     * @param message - Human-readable failure description.
+     * @param details - Optional structured response or diagnostic details.
+     * @remarks The default message is `Trial expired` and the status is always 403.
+     * @example
+     * ```typescript
+     * throw new TrialExpiredError();
+     * ```
+     */
+    constructor(message?: string, details?: any);
+}

package/dist/lib/errors.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrialExpiredError = exports.NotAuthorizedError = exports.ProductHubError = void 0;
+/** Error returned for Product Hub API, network, runtime, and verification failures. */
+class ProductHubError extends Error {
+    /**
+     * Create a Product Hub error.
+     *
+     * @param message - Human-readable failure description.
+     * @param status - Optional HTTP response status associated with the failure.
+     * @param details - Optional structured response or diagnostic details.
+     * @remarks API errors retain their HTTP status and response details when available.
+     * @example
+     * ```typescript
+     * throw new ProductHubError('Request failed', 500, { requestId: 'request-id' });
+     * ```
+     */
+    constructor(message, status, details) {
+        super(message);
+        this.name = 'ProductHubError';
+        this.status = status;
+        this.details = details;
+    }
+}
+exports.ProductHubError = ProductHubError;
+/** Error indicating that Product Hub rejected authentication or authorization. */
+class NotAuthorizedError extends ProductHubError {
+    /**
+     * Create an authorization error with HTTP status 401.
+     *
+     * @param message - Human-readable failure description.
+     * @param details - Optional structured response or diagnostic details.
+     * @remarks The default message is `Not authorized` and the status is always 401.
+     * @example
+     * ```typescript
+     * throw new NotAuthorizedError('Invalid credentials');
+     * ```
+     */
+    constructor(message = 'Not authorized', details) {
+        super(message, 401, details);
+        this.name = 'NotAuthorizedError';
+    }
+}
+exports.NotAuthorizedError = NotAuthorizedError;
+/** Error indicating that the device's Product Hub trial has expired. */
+class TrialExpiredError extends ProductHubError {
+    /**
+     * Create a trial-expiration error with HTTP status 403.
+     *
+     * @param message - Human-readable failure description.
+     * @param details - Optional structured response or diagnostic details.
+     * @remarks The default message is `Trial expired` and the status is always 403.
+     * @example
+     * ```typescript
+     * throw new TrialExpiredError();
+     * ```
+     */
+    constructor(message = 'Trial expired', details) {
+        super(message, 403, details);
+        this.name = 'TrialExpiredError';
+    }
+}
+exports.TrialExpiredError = TrialExpiredError;

package/dist/lib/types.d.ts

@@ -0,0 +1,406 @@
+/**
+ * Activation status values indicating the current state of plugin licensing.
+ *
+ * @remarks
+ * - `None`: No activation found
+ * - `Trial`: Active trial period
+ * - `TrialExpired`: Trial period has ended
+ * - `Licensed`: Valid perpetual license (Standard, NFR, or Free)
+ * - `LicenseExpired`: License has expired
+ * - `Subscription`: Valid subscription license
+ * - `SubscriptionExpired`: Subscription has expired
+ */
+export declare enum ActivationStatus {
+    None = "None",
+    Trial = "Trial",
+    TrialExpired = "TrialExpired",
+    Licensed = "Licensed",
+    LicenseExpired = "LicenseExpired",
+    Subscription = "Subscription",
+    SubscriptionExpired = "SubscriptionExpired"
+}
+/**
+ * Status of the login session stored for this product and device.
+ *
+ * @remarks
+ * - `None`: No stored login session is available
+ * - `Valid`: The stored session is valid
+ * - `Invalid`: The session is malformed, expired, revoked, or belongs to another scope
+ */
+export declare enum SessionStatus {
+    None = "None",
+    Valid = "Valid",
+    Invalid = "Invalid"
+}
+/**
+ * License type values representing different categories of product licenses.
+ *
+ * @remarks
+ * - `Standard`: Standard perpetual license
+ * - `NFR`: Not-for-resale perpetual license (typically for partners/reviewers)
+ * - `Free`: Free perpetual license
+ * - `Subscription`: Time-limited subscription license
+ */
+export declare enum LicenseType {
+    Standard = "Standard",// our standard perpetual license
+    NFR = "NFR",// not-for-resale perpetual license
+    Free = "Free",// free license (perpetual)
+    Subscription = "Subscription"
+}
+/**
+ * Configuration options for the APIClient.
+ *
+ * The APIClient provides low-level access to the Product Hub API endpoints
+ * for authentication, product activation, and trial management.
+ *
+ * @example
+ * ```typescript
+ * const apiClient = new ProductHub.APIClient({
+ *   manufacturerId: "b7d86bee-7a7c-491b-a719-29cd99425fbe",
+ *   productId: "6307d4da-cf56-4917-a793-0354f6ad235f"
+ * });
+ * ```
+ */
+export interface APIClientOptions {
+    /**
+     * Your manufacturer ID in Gorilla Engine Product Hub.
+     *
+     * @remarks
+     * You can find your manufacturer ID in the Product Hub web interface.
+     *
+     * @example
+     * "7222d546-9c72-43d5-8bd4-1667ce390ea4"
+     */
+    manufacturerId: string;
+    /**
+     * The ID of the product in Gorilla Engine Product Hub.
+     *
+     * @remarks
+     * You can find your product ID in the Product Hub web interface.
+     *
+     * @example
+     * "1487a36d-9bc8-4220-ba31-9998d743071f"
+     */
+    productId: string;
+    /**
+     * Optional hardware fingerprint override for testing purposes.
+     * When provided, this fingerprint will be used instead of generating
+     * one automatically. Useful for unit tests and development scenarios.
+     *
+     * @remarks
+     * In production, omit this parameter to use the automatically generated
+     * hardware fingerprint based on the user's system characteristics.
+     */
+    hardwareFingerprint?: string;
+}
+/**
+ * Configuration options for the AudioPluginClient.
+ *
+ * The AudioPluginClient extends the APIClient with additional functionality
+ * specifically designed for audio plugin activation workflows, including
+ * automatic file persistence, signature verification, and hardware fingerprint management.
+ *
+ * @example
+ * ```typescript
+ * const pluginClient = new ProductHub.AudioPluginClient({
+ *   manufacturerId: "b7d86bee-7a7c-491b-a719-29cd99425fbe",
+ *   productId: "6307d4da-cf56-4917-a793-0354f6ad235f",
+ *   productName: "Your Product",
+ *   productPublicKey: "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
+ *   userResourceBaseDirectory: "/Users/<username>/Library/Application Support/<manufacturername>"
+ * });
+ * ```
+ */
+export interface AudioPluginClientOptions extends APIClientOptions {
+    /**
+     * The name of the product, exactly matching the name configured in Gorilla Compiler.
+     *
+     * @remarks
+     * Used for filename and path generation in regard to persisting activations and trials.
+     *
+     * @example
+     * "Groove Master 3000"
+     */
+    productName: string;
+    /**
+     * RSA public key in PEM format for signature verification.
+     * This key is used to verify activations and trials.
+     *
+     * @remarks
+     * You can obtain the public key from the product configuration page in the Product Hub web interface.
+     * It is automatically generated when creating a new product.
+     *
+     * @example
+     * ```plaintext
+     * -----BEGIN PUBLIC KEY-----
+     * MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+     * -----END PUBLIC KEY-----
+     * ```
+     */
+    productPublicKey: string;
+    /**
+     * Base directory where the product's folder containing the plugin's user specific settings, activations and other resources are stored.
+     * Typically this should point to the user-specific manufacturer's application support directory.
+     *
+     * @remarks
+     * The client will create e.g. `.ops` (activation) files or user specific settings files
+     * in `<userResourceBaseDirectory>/<productName>` to persist information locally.
+     *
+     * @example
+     * "/Users/<username>/Library/Application Support/<manufacturername>" (macOS)
+     * "C:\\Users\\<username>\\AppData\\Roaming\\<manufacturername>" (Windows)
+     */
+    userResourceBaseDirectory: string;
+    /**
+     * Optional hardware fingerprint override for testing purposes.
+     * When provided, this fingerprint will be used instead of generating
+     * one automatically. Useful for unit tests and development scenarios.
+     *
+     * @remarks
+     * In production, make sure the "Hardware fingerprinting" native module is enabled
+     * in Gorilla Compiler and omit this parameter to use the automatically generated
+     * hardware fingerprint based on the user's system characteristics.
+     */
+    hardwareFingerprint?: string;
+    /**
+     * The current installed version of the product in semantic versioning format.
+     *
+     * @remarks
+     * Optional. Used for update checking. Format: "major.minor.revision" (e.g., "1.2.3")
+     * If not provided, update checking will be disabled (checkForUpdates will always return false,
+     * isUpdateAvailable will always return false).
+     *
+     * @example
+     * "1.2.3"
+     */
+    currentVersion?: string;
+    /**
+     * The current installed build number of the product.
+     *
+     * @remarks
+     * Optional. Used for update checking when comparing versions with equal major.minor.revision.
+     *
+     * @example
+     * 456
+     */
+    currentBuildNumber?: number;
+}
+/**
+ * Parameters for activating a product in the AudioPluginClient.
+ */
+export interface AudioPluginActivationParams {
+    /** The email the end user is registered with */
+    email: string;
+    /** End-user's password. */
+    password: string;
+}
+/**
+ * Parameters for activating a product using email + serial only (no login required).
+ *
+ * @remarks
+ * Only works when the manufacturer has "Authentication Type = None" and
+ * "Email+Serial Claiming" enabled in Product Hub. The license is claimed and
+ * activated in a single call — no separate claim step is needed.
+ */
+export interface AudioPluginActivationWithSerialParams {
+    /** The email address the end user used when purchasing. */
+    email: string;
+    /** The license serial number received after purchase. */
+    serial: string;
+}
+/**
+ * Parameters for claiming a reseller-purchased serial and activating in one call.
+ *
+ * @remarks
+ * Use this when an authenticated user (with SSO credentials) purchased a serial
+ * from a reseller and needs to add it to their account before activating.
+ * The serial is claimed to the account and then activated in a single call.
+ */
+export interface AudioPluginClaimAndActivateParams {
+    /** End-user's email address. */
+    email: string;
+    /** End-user's password. */
+    password: string;
+    /** The license serial number received from the reseller. */
+    serial: string;
+}
+/** Parameters for claiming a reseller serial with the active stored session. */
+export interface AudioPluginStoredSessionSerialParams {
+    /** The license serial number received from the reseller. */
+    serial: string;
+}
+/** Non-sensitive details decoded from the active stored login session. */
+export interface StoredSessionInfo {
+    email: string | null;
+    userId: string | null;
+    expiresAt: Date | null;
+}
+/**
+ * Authentication response containing the bearer token for subsequent
+ * protected Product Hub requests (e.g. product activation).
+ *
+ * @remarks Used by APIClient.loginUser()
+ */
+export interface LoginUserResponse {
+    /**
+     * JWT bearer token.
+     */
+    token: string;
+}
+/**
+ * Parameters for product activation.
+ *
+ * @remarks Used by APIClient.activateProduct()
+ */
+export interface ActivateProductParams {
+    /** End-user email for login. */
+    email: string;
+    /** End-user password for login. */
+    password: string;
+    /**
+     * License serial number. When provided, this specific license is claimed
+     * (if not already owned) and activated instead of the priority-selected one.
+     */
+    serial?: string;
+}
+/**
+ * Response from product activation.
+ *
+ * @remarks Returned by APIClient.activateProduct()
+ */
+export interface ActivateProductResponse {
+    type: LicenseType;
+    expires: Date | null;
+    signature: string;
+    serial: string;
+    user_id: string;
+    user_email: string;
+    product_id: string;
+    product_name: string;
+    manufacturer_id: string;
+    manufacturer_name: string;
+    hardware_fingerprint: string;
+    hardware_fingerprint_version: number;
+    signature_seed_version: number;
+}
+/** Result of attempting an activation request with the active stored session. */
+export interface StoredSessionActivationResult {
+    sessionStatus: SessionStatus;
+    activation: ActivateProductResponse | null;
+}
+/** Result of restoring product activation with the active stored session. */
+export interface ActivationRestoreResult {
+    sessionStatus: SessionStatus;
+    activationStatus: ActivationStatus;
+}
+/**
+ * Response from trial activation.
+ *
+ * @remarks Returned by APIClient.activateTrial()
+ */
+export interface ActivateTrialResponse {
+    signature: string;
+    timestamp: number;
+    trial_days: number;
+    product_id: string;
+    product_name: string;
+    manufacturer_id: string;
+    manufacturer_name: string;
+    hardware_fingerprint: string;
+    hardware_fingerprint_version: number;
+    signature_seed_version: number;
+}
+export interface VerifyActivationInput {
+    serial: string;
+    signature: string;
+    expires?: Date | null;
+    signature_seed_version?: number;
+}
+export interface VerifyTrialInput {
+    timestamp: number;
+    trial_days: number;
+    signature: string;
+    signature_seed_version?: number;
+}
+/**
+ * Stored activation data with legacy compatibility.
+ * Allows null values for fields that might not exist in version 5 format.
+ */
+export interface StoredActivation extends Omit<ActivateProductResponse, 'user_id' | 'user_email' | 'manufacturer_id' | 'manufacturer_name'> {
+    user_id: string | null;
+    user_email: string | null;
+    manufacturer_id: string | null;
+    manufacturer_name: string | null;
+}
+/**
+ * Stored trial data with legacy compatibility.
+ * Allows null values for fields that might not exist in version 5 format.
+ */
+export interface StoredTrial extends Omit<ActivateTrialResponse, 'manufacturer_id' | 'manufacturer_name'> {
+    manufacturer_id: string | null;
+    manufacturer_name: string | null;
+}
+/**
+ * Options for writing an offline activation file.
+ *
+ * @remarks Used by AudioPluginClient.writeOfflineActivationFile()
+ */
+export interface OfflineActivationFileOptions {
+    /**
+     * Custom folder path where the activation file should be written.
+     * If not provided, uses the default installation directory.
+     *
+     * @example
+     * "/Users/username/Desktop" (macOS)
+     * "C:\\Users\\Username\\Desktop" (Windows)
+     */
+    customFolderPath?: string;
+    /**
+     * Whether to overwrite an existing activation file.
+     * @default false
+     */
+    overwriteExisting?: boolean;
+}
+/**
+ * Build information from the Product Hub API.
+ */
+export interface ProductBuild {
+    /** The unique identifier for this build */
+    id: string;
+    /** The operating system this build is for */
+    os: 'any' | 'macOS' | 'Windows';
+    /** Major version number (0-255) */
+    major: number;
+    /** Minor version number (0-255) */
+    minor: number;
+    /** Revision version number (0-255) */
+    revision: number;
+    /** Build number (0 or greater, nullable) */
+    build_number: number | null;
+}
+/**
+ * Response from the latest product version API endpoint.
+ */
+export interface LatestProductVersionResponse {
+    /** Array of builds from the latest release */
+    builds: ProductBuild[];
+    /** The URL to redirect users to for updates */
+    update_referral_url: string | null;
+}
+/**
+ * Build file information from the Product Hub API.
+ */
+export interface BuildFile {
+    /** The unique identifier of this particular file */
+    id: string;
+    /** The name of the file */
+    name: string;
+    /** The size of the file in bytes */
+    size: number;
+    /** The SHA256 hash of the file */
+    sha256: string;
+    /** Indicates if the file was stored before the product hub existed */
+    legacy_storage: boolean;
+    /** The URL to download the file */
+    url: string;
+}

package/dist/lib/types.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LicenseType = exports.SessionStatus = exports.ActivationStatus = void 0;
+// prettier-ignore
+/**
+ * Activation status values indicating the current state of plugin licensing.
+ *
+ * @remarks
+ * - `None`: No activation found
+ * - `Trial`: Active trial period
+ * - `TrialExpired`: Trial period has ended
+ * - `Licensed`: Valid perpetual license (Standard, NFR, or Free)
+ * - `LicenseExpired`: License has expired
+ * - `Subscription`: Valid subscription license
+ * - `SubscriptionExpired`: Subscription has expired
+ */
+var ActivationStatus;
+(function (ActivationStatus) {
+    ActivationStatus["None"] = "None";
+    ActivationStatus["Trial"] = "Trial";
+    ActivationStatus["TrialExpired"] = "TrialExpired";
+    ActivationStatus["Licensed"] = "Licensed";
+    ActivationStatus["LicenseExpired"] = "LicenseExpired";
+    ActivationStatus["Subscription"] = "Subscription";
+    ActivationStatus["SubscriptionExpired"] = "SubscriptionExpired";
+})(ActivationStatus || (exports.ActivationStatus = ActivationStatus = {}));
+// prettier-ignore
+/**
+ * Status of the login session stored for this product and device.
+ *
+ * @remarks
+ * - `None`: No stored login session is available
+ * - `Valid`: The stored session is valid
+ * - `Invalid`: The session is malformed, expired, revoked, or belongs to another scope
+ */
+var SessionStatus;
+(function (SessionStatus) {
+    SessionStatus["None"] = "None";
+    SessionStatus["Valid"] = "Valid";
+    SessionStatus["Invalid"] = "Invalid";
+})(SessionStatus || (exports.SessionStatus = SessionStatus = {}));
+// prettier-ignore
+/**
+ * License type values representing different categories of product licenses.
+ *
+ * @remarks
+ * - `Standard`: Standard perpetual license
+ * - `NFR`: Not-for-resale perpetual license (typically for partners/reviewers)
+ * - `Free`: Free perpetual license
+ * - `Subscription`: Time-limited subscription license
+ */
+var LicenseType;
+(function (LicenseType) {
+    LicenseType["Standard"] = "Standard";
+    LicenseType["NFR"] = "NFR";
+    LicenseType["Free"] = "Free";
+    LicenseType["Subscription"] = "Subscription";
+})(LicenseType || (exports.LicenseType = LicenseType = {}));