pp-flags 1.0.0

package/__tests__/isFeatureEnabled.test.js

@@ -0,0 +1,232 @@
+import { jest } from '@jest/globals';
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+
+// Mock posthog-js with config structure for initialization check
+const mockPostHog = {
+    config: {
+        api_key: 'test-api-key',
+    },
+    isFeatureEnabled: jest.fn((flagName) => {
+        const mockFlags = {
+            'test-feature': true,
+            'disabled-feature': false,
+        };
+        return mockFlags[flagName] || false;
+    }),
+};
+
+jest.unstable_mockModule('posthog-js', () => ({
+    default: mockPostHog,
+}));
+
+// Mock fetch globally
+global.fetch = jest.fn();
+
+// Mock window for browser environment
+global.window = {};
+
+/**
+ * Helper: set up fetch mock to return a JSON version response,
+ * import a fresh module, configure it, and wait for version to load.
+ */
+async function importModuleWithVersion(version) {
+    global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ version }),
+    });
+
+    const mod = await import(`../index.js?t=${Date.now()}-${Math.random()}`);
+
+    // Configure with a fake site API URL — this triggers version loading
+    // Awaiting configure() ensures the version is fully loaded before returning
+    await mod.configure({ siteApiBaseUrl: 'http://localhost:3003/a' });
+
+    return mod;
+}
+
+async function importModuleWithFailedFetch() {
+    global.fetch.mockResolvedValueOnce({ ok: false });
+
+    const mod = await import(`../index.js?t=${Date.now()}-${Math.random()}`);
+
+    await mod.configure({ siteApiBaseUrl: 'http://localhost:3003/a' });
+
+    return mod;
+}
+
+describe('isFeatureEnabled', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        global.fetch.mockClear();
+
+        // Reset PostHog mock
+        mockPostHog.config = { api_key: 'test-api-key' };
+        mockPostHog.isFeatureEnabled.mockImplementation((flagName) => {
+            const mockFlags = {
+                'test-feature': true,
+                'disabled-feature': false,
+            };
+            return mockFlags[flagName] || false;
+        });
+    });
+
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    describe('PostHog feature flags (ph:)', () => {
+        let isFeatureEnabled;
+
+        beforeEach(async () => {
+            const mod = await import(`../index.js?t=${Date.now()}-${Math.random()}`);
+            isFeatureEnabled = mod.isFeatureEnabled;
+        });
+
+        it('should return true for enabled PostHog feature', () => {
+            mockPostHog.isFeatureEnabled.mockReturnValue(true);
+
+            const result = isFeatureEnabled('ph:test-feature');
+            expect(result).toBe(true);
+        });
+
+        it('should return false for disabled PostHog feature', () => {
+            mockPostHog.isFeatureEnabled.mockReturnValue(false);
+
+            const result = isFeatureEnabled('ph:disabled-feature');
+            expect(result).toBe(false);
+        });
+
+        it('should return false if PostHog is not initialized', async () => {
+            const originalConfig = mockPostHog.config;
+            mockPostHog.config = null;
+
+            const freshModule = await import(`../index.js?t=${Date.now()}-uninit`);
+            const freshIsFeatureEnabled = freshModule.isFeatureEnabled;
+
+            const result = freshIsFeatureEnabled('ph:test-feature');
+            expect(result).toBe(false);
+
+            mockPostHog.config = originalConfig;
+        });
+
+        it('should return false for empty PostHog flag name', () => {
+            const result = isFeatureEnabled('ph:');
+            expect(result).toBe(false);
+        });
+    });
+
+    describe('nf-ext feature flags', () => {
+        it('should return true if feature exists and is enabled in current version', async () => {
+            // Version 1.0.2 has "paapi" enabled in nfExtensions
+            const mod = await importModuleWithVersion('1.0.2');
+
+            const result = mod.isFeatureEnabled('nf-ext:paapi');
+            expect(result).toBe(true);
+            expect(global.fetch).toHaveBeenCalledWith('http://localhost:3003/a/nf-ext/version');
+        });
+
+        it('should return false if feature does not exist in current version', async () => {
+            const mod = await importModuleWithVersion('1.0.2');
+
+            const result = mod.isFeatureEnabled('nf-ext:nonexistent-feature');
+            expect(result).toBe(false);
+        });
+
+        it('should return false if version does not exist in nfExtensions', async () => {
+            const mod = await importModuleWithVersion('1.0.99');
+
+            const result = mod.isFeatureEnabled('nf-ext:paapi');
+            expect(result).toBe(false);
+        });
+
+        it('should use cached version on subsequent calls', async () => {
+            const mod = await importModuleWithVersion('1.0.2');
+
+            const result1 = mod.isFeatureEnabled('nf-ext:paapi');
+            expect(result1).toBe(true);
+            const fetchCallCount = global.fetch.mock.calls.length;
+
+            // Second call should use cache (no new fetch)
+            const result2 = mod.isFeatureEnabled('nf-ext:paapi');
+            expect(result2).toBe(true);
+            expect(global.fetch.mock.calls.length).toBe(fetchCallCount);
+        });
+
+        it('should return false if fetch fails', async () => {
+            const mod = await importModuleWithFailedFetch();
+
+            const result = mod.isFeatureEnabled('nf-ext:paapi');
+            expect(result).toBe(false);
+        });
+
+        it('should return false for empty feature name', async () => {
+            const mod = await importModuleWithVersion('1.0.2');
+
+            const result = mod.isFeatureEnabled('nf-ext:');
+            expect(result).toBe(false);
+        });
+
+        it('should return false if configure() was not called', async () => {
+            // Import without calling configure — no siteApiBaseUrl set
+            const mod = await import(`../index.js?t=${Date.now()}-noconfig`);
+
+            const result = mod.isFeatureEnabled('nf-ext:paapi');
+            expect(result).toBe(false);
+        });
+
+        it('should return true if specified version >= current version (nf-ext:version:XXX)', async () => {
+            const mod = await importModuleWithVersion('1.0.3');
+
+            // Current version is 1.0.3
+            expect(mod.isFeatureEnabled('nf-ext:version:1.0.3')).toBe(true);  // 1.0.3 >= 1.0.3
+            expect(mod.isFeatureEnabled('nf-ext:version:1.0.4')).toBe(true);  // 1.0.4 >= 1.0.3
+            expect(mod.isFeatureEnabled('nf-ext:version:1.0.2')).toBe(false); // 1.0.2 < 1.0.3
+        });
+
+        it('should handle multi-part version numbers correctly', async () => {
+            const mod = await importModuleWithVersion('1.2.5');
+
+            expect(mod.isFeatureEnabled('nf-ext:version:1.2.5')).toBe(true);  // 1.2.5 >= 1.2.5
+            expect(mod.isFeatureEnabled('nf-ext:version:1.2.6')).toBe(true);  // 1.2.6 >= 1.2.5
+            expect(mod.isFeatureEnabled('nf-ext:version:1.3.0')).toBe(true);  // 1.3.0 >= 1.2.5
+            expect(mod.isFeatureEnabled('nf-ext:version:1.2.4')).toBe(false); // 1.2.4 < 1.2.5
+            expect(mod.isFeatureEnabled('nf-ext:version:1.1.9')).toBe(false); // 1.1.9 < 1.2.5
+        });
+
+        it('should return false for empty version in nf-ext:version:', async () => {
+            const mod = await importModuleWithVersion('1.0.2');
+
+            const result = mod.isFeatureEnabled('nf-ext:version:');
+            expect(result).toBe(false);
+        });
+    });
+
+    describe('Invalid inputs', () => {
+        let isFeatureEnabled;
+
+        beforeEach(async () => {
+            const mod = await import(`../index.js?t=${Date.now()}-${Math.random()}`);
+            isFeatureEnabled = mod.isFeatureEnabled;
+        });
+
+        it('should return false for null input', () => {
+            expect(isFeatureEnabled(null)).toBe(false);
+        });
+
+        it('should return false for undefined input', () => {
+            expect(isFeatureEnabled(undefined)).toBe(false);
+        });
+
+        it('should return false for non-string input', () => {
+            expect(isFeatureEnabled(123)).toBe(false);
+        });
+
+        it('should return false for string without colon', () => {
+            expect(isFeatureEnabled('invalid-format')).toBe(false);
+        });
+
+        it('should return false for unknown prefix', () => {
+            expect(isFeatureEnabled('unknown:value')).toBe(false);
+        });
+    });
+});

package/index.js

@@ -0,0 +1,295 @@
+// Import posthog - it will be initialized by the app before use
+import posthog from 'posthog-js';
+
+/**
+ * Cached PostHog client (checked at module initialization)
+ */
+let cachedPostHogClient = null;
+
+/**
+ * Initialize PostHog client check (called at module load)
+ */
+function initializePostHogClient() {
+    if (typeof window === 'undefined') {
+        return;
+    }
+
+    // Check if PostHog is initialized (has config with api_key)
+    if (posthog && posthog.config && posthog.config.api_key) {
+        cachedPostHogClient = posthog;
+    }
+}
+
+/**
+ * Get PostHog client (synchronous, returns cached value)
+ * @returns {object|null} - PostHog client if available and initialized, null otherwise
+ */
+function getPostHogClient() {
+    return cachedPostHogClient;
+}
+
+// Check PostHog initialization when module loads
+initializePostHogClient();
+
+// Also check periodically in case PostHog initializes later
+if (typeof window !== 'undefined') {
+    // Check again after a short delay in case PostHog initializes asynchronously
+    setTimeout(() => {
+        initializePostHogClient();
+    }, 100);
+}
+
+const nfExtensions = {
+    "1.0.2": {
+        "paapi": true,
+        "amazon-scrape": false,
+        "product-boxes": true
+    },
+    "1.0.1": {
+        "amazon-scrape": true
+    }
+};
+
+/**
+ * Configured site API base URL (set via configure())
+ */
+let siteApiBaseUrl = null;
+
+/**
+ * Cached current extension version (loaded at module initialization)
+ */
+let cachedExtensionVersion = null;
+
+/**
+ * Promise that resolves when the extension version is loaded
+ */
+let versionLoadPromise = null;
+
+/**
+ * Get the version load promise (for testing purposes)
+ * @returns {Promise<string|null>|null} - The version load promise or null
+ */
+export function getVersionLoadPromise() {
+    return versionLoadPromise;
+}
+
+/**
+ * Compare two semantic versions
+ * @param {string} version1 - First version to compare
+ * @param {string} version2 - Second version to compare
+ * @returns {number} - Returns 1 if version1 > version2, -1 if version1 < version2, 0 if equal
+ */
+function compareVersions(version1, version2) {
+    const v1Parts = version1.split('.').map(Number);
+    const v2Parts = version2.split('.').map(Number);
+
+    // Pad shorter version with zeros
+    const maxLength = Math.max(v1Parts.length, v2Parts.length);
+    while (v1Parts.length < maxLength) v1Parts.push(0);
+    while (v2Parts.length < maxLength) v2Parts.push(0);
+
+    for (let i = 0; i < maxLength; i++) {
+        if (v1Parts[i] > v2Parts[i]) return 1;
+        if (v1Parts[i] < v2Parts[i]) return -1;
+    }
+
+    return 0;
+}
+
+/**
+ * Load the current extension version from the site API (async)
+ * The site API proxies the request to Google's update server to avoid CORS issues.
+ * @returns {Promise<string|null>} - The version string or null if not found
+ */
+async function loadExtensionVersion() {
+    try {
+        if (!siteApiBaseUrl) {
+            return null;
+        }
+
+        const response = await fetch(`${siteApiBaseUrl}/nf-ext/version`);
+        if (!response.ok) {
+            return null;
+        }
+
+        const data = await response.json();
+        return data.version || null;
+    } catch (error) {
+        return null;
+    }
+}
+
+/**
+ * Get the current extension version (synchronous, returns cached value)
+ * @returns {string|null} - The version string or null if not loaded yet
+ */
+function getCurrentExtensionVersion() {
+    return cachedExtensionVersion;
+}
+
+/**
+ * Initialize extension version loading (called after configure())
+ * Fetches the extension version from the site API.
+ */
+function initializeExtensionVersion() {
+    if (typeof window === 'undefined') {
+        // Server-side, skip loading
+        return;
+    }
+
+    // Only fetch from site API if configured
+    if (!siteApiBaseUrl) {
+        return;
+    }
+
+    if (versionLoadPromise) {
+        // Already loading or loaded
+        return;
+    }
+
+    versionLoadPromise = loadExtensionVersion().then(version => {
+        cachedExtensionVersion = version;
+        return version;
+    }).catch(() => {
+        cachedExtensionVersion = null;
+        return null;
+    });
+}
+
+/**
+ * Configure the flags package with required settings.
+ * Must be called (and awaited) before nf-ext flags will work.
+ *
+ * @example
+ * ```js
+ * import { configure } from 'pp-flags';
+ * await configure({ siteApiBaseUrl: 'http://localhost:3003/a' });
+ * // Now isFeatureEnabled('nf-ext:...') will have the version loaded
+ * ```
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.siteApiBaseUrl - The base URL for the site API (e.g., 'http://localhost:3003/a')
+ * @returns {Promise<string|null>} - Resolves with the loaded version, or null if loading failed
+ */
+export async function configure({ siteApiBaseUrl: url }) {
+    if (url) {
+        siteApiBaseUrl = url;
+    }
+
+    // Trigger version loading now that we have the URL
+    initializeExtensionVersion();
+
+    // Wait for version to finish loading before returning
+    if (versionLoadPromise) {
+        return versionLoadPromise;
+    }
+
+    return null;
+}
+
+
+/**
+ * Check if a featured version is enabled by comparing with XML version or PostHog feature flag
+ *
+ * This function uses the global PostHog instance (initialized via posthog.init() in your app).
+ * The XML version and PostHog client are pre-loaded when the module is imported.
+ *
+ * @example Using in React components:
+ * ```jsx
+ * import { isFeatureEnabled } from 'pp-flags';
+ *
+ * function MyComponent() {
+ *   // Synchronous check - no async/await needed
+ *   const isEnabled = isFeatureEnabled('ph:my-feature');
+ *   const isPaapiEnabled = isFeatureEnabled('nf-ext:paapi');
+ *   const isVersionOk = isFeatureEnabled('nf-ext:version:1.0.3');
+ *   // ...
+ * }
+ * ```
+ *
+ * @param {string} flagString - Flag string in format "nf-ext:feature-name" (e.g., "nf-ext:paapi"), "nf-ext:version:1.0.3", or "ph:feature-flag-name"
+ * @returns {boolean} - True if enabled, false otherwise. Returns false if version/PostHog not loaded yet.
+ */
+export function isFeatureEnabled(flagString) {
+    try {
+        // Extract version from parameter string
+        if (!flagString || typeof flagString !== 'string') {
+            return false;
+        }
+
+        // Check if this is a PostHog feature flag (starts with "ph:")
+        if (flagString.startsWith('ph:')) {
+            const featureFlagName = flagString.substring(3); // Get everything after "ph:"
+            if (!featureFlagName) {
+                return false;
+            }
+
+            // Get PostHog client (cached at module load)
+            const posthogClient = getPostHogClient();
+
+            // Check if PostHog is available and has the method
+            if (posthogClient && typeof posthogClient.isFeatureEnabled === 'function') {
+                try {
+                    return posthogClient.isFeatureEnabled(featureFlagName) || false;
+                } catch (error) {
+                    // Return false if PostHog check fails
+                    return false;
+                }
+            }
+            // Return false if PostHog is not available or not initialized
+            return false;
+        }
+
+        // Handle nf-ext feature check (e.g., "nf-ext:paapi" or "nf-ext:version:1.0.3")
+        if (flagString.startsWith('nf-ext:')) {
+            const afterPrefix = flagString.substring(7); // Get everything after "nf-ext:"
+            if (!afterPrefix) {
+                return false;
+            }
+
+            // Get current version from cache (loaded at module initialization)
+            const currentVersion = getCurrentExtensionVersion();
+            if (!currentVersion) {
+                // Version not loaded yet, return false
+                return false;
+            }
+
+            // Check if this is a version comparison (nf-ext:version:XXX)
+            if (afterPrefix.startsWith('version:')) {
+                const specifiedVersion = afterPrefix.substring(8); // Get everything after "version:"
+                if (!specifiedVersion) {
+                    return false;
+                }
+
+                // Compare versions: return true if specifiedVersion >= currentVersion
+                // This means: return true if the specified version is at least the current version
+                const comparison = compareVersions(specifiedVersion, currentVersion);
+                return comparison >= 0;
+            }
+
+            // Otherwise, treat it as a feature name (e.g., "nf-ext:paapi")
+            const featureName = afterPrefix;
+
+            // Look up features for this version in nfExtensions
+            const versionFeatures = nfExtensions[currentVersion];
+            if (!versionFeatures) {
+                return false;
+            }
+
+            // Check if the feature exists and is enabled
+            return !!versionFeatures[featureName];
+        }
+
+        // Handle other prefixes (legacy support or future extensions)
+        const parts = flagString.split(':');
+        if (parts.length < 2) {
+            return false;
+        }
+
+        // For other formats, return false (or implement custom logic)
+        return false;
+    } catch (error) {
+        // Return false on any error
+        return false;
+    }
+}

package/jest.config.js

@@ -0,0 +1,7 @@
+// jest.config.js
+export default {
+    transform: {},
+    moduleNameMapper: {
+        '^(\\.{1,2}/.*)\\.js$': '$1',
+    }
+};

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "pp-flags",
+  "version": "1.0.0",
+  "description": "Minimal feature flags package for frontend and backend",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "posthog-js": "^1.227.0"
+  }
+}