@forge/feature-flags-node 1.0.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @forge/feature-flags-node
+
+## 1.0.0-next.0
+
+### Major Changes
+
+- ebad936: Initial release of @forge/feature-flags-node
+
+### Patch Changes
+
+- Updated dependencies [ebad936]
+  - @forge/api@6.0.2-next.3

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Atlassian
+Permission is hereby granted to use this software in accordance with the terms 
+and conditions outlined in the Atlassian Developer Terms, which can be found 
+at the following URL:
+https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
+By using this software, you agree to comply with these terms and conditions. 
+If you do not agree with these terms, you are not permitted to use this software.

package/README.md

@@ -0,0 +1,145 @@
+# @forge/feature-flags-node
+
+A feature flag SDK for Atlassian Forge apps running on Forge Node Runtime. This package provides a simple interface for evaluating feature flags.
+
+## Installation
+
+```bash
+yarn add @forge/feature-flags-node
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { getAppContext } from "@forge/api";
+import { ForgeFeatureFlags } from "@forge/feature-flags-node";
+
+export const handler = async (payload, context) => {
+  const { environmentType } = getAppContext();
+
+  // Initialize the feature flags service
+  const featureFlags = new ForgeFeatureFlags();
+  await featureFlags.initialize({
+    environment: environmentType?.toLowerCase() || "development" // Optional, defaults to 'development'
+  });
+
+  // Define a user
+  const user = {
+    userID: context?.principal?.accountId,
+    custom: { 
+      license: context?.license?.isActive
+    }
+  };
+
+  // Check a feature flag (synchronous after initialization)
+  const isEnabled = featureFlags.checkFlag(user, "new-feature");
+
+  // Get multiple flags at once (synchronous)
+  const flags = featureFlags.getFeatureFlags(user, ["feature-a", "feature-b"]);
+
+  // Shutdown when done
+  await featureFlags.shutdown();
+}
+
+```
+
+## ⚠️ Important: Initialization Best Practices
+
+**ALWAYS initialize the ForgeFeatureFlags SDK inside your handler function, NEVER initialize globally as it will use the stale feature flags**
+
+### ✅ Correct Pattern - Initialize Inside Handler
+
+```typescript
+import { getAppContext } from "@forge/api";
+import { ForgeFeatureFlags } from "@forge/feature-flags-node";
+
+export const handler = async (payload, context) => {
+  // ✅ Initialize inside the handler function
+  const featureFlags = new ForgeFeatureFlags();
+  await featureFlags.initialize({
+    environment: getAppContext().environmentType?.toLowerCase() || "development"
+  });
+
+  // Use feature flags...
+  const isEnabled = featureFlags.checkFlag(user, "new-feature");
+
+  // Shutdown when done
+  await featureFlags.shutdown();
+}
+```
+
+### ❌ Incorrect Pattern - Global Initialization
+
+```typescript
+// ❌ NEVER do this - Global initialization
+const featureFlags = new ForgeFeatureFlags();
+await featureFlags.initialize(); // This will cause problems!
+
+export const handler = async (payload, context) => {
+  // This will fail if token expires or network issues occur
+  const isEnabled = featureFlags.checkFlag(user, "new-feature");
+}
+```
+
+## Polling Behavior
+
+The package automatically polls for feature flag updates every 30 seconds:
+
+1. **Cache Updates**: New data is cached for fallback purposes
+2. **Error Resilience**: If a fetch fails, the package falls back to cached data
+3. **Immediate Updates**: Feature flag changes are reflected within 30 seconds
+
+```typescript
+// Polling happens automatically in the background
+const featureFlags = new ForgeFeatureFlags();
+await featureFlags.initialize();
+
+// Feature flags are automatically updated every 30 seconds
+// No manual intervention required
+```
+
+## API Reference
+
+### `ForgeFeatureFlags`
+
+#### `constructor()`
+Creates a new instance of the ForgeFeatureFlags class.
+
+#### `initialize(config?: ForgeFeatureFlagConfig): Promise<void>`
+Initializes the feature flags service with the provided configuration.
+
+```typescript
+interface ForgeFeatureFlagConfig {
+  environment?: 'development' | 'staging' | 'production';
+}
+```
+
+#### `checkFlag(user: ForgeUser, flagName: string): boolean`
+Checks if a feature flag is enabled for the given user. **Synchronous** after initialization.
+
+#### `getFeatureFlags(user: ForgeUser, flagNames: string[]): Record<string, boolean>`
+Gets multiple feature flags at once. **Synchronous** after initialization.
+
+#### `shutdown(): Promise<void>`
+Shuts down the feature flags service and cleans up resources.
+
+#### `isInitialized(): boolean`
+Checks if the service is initialized.
+
+### User Interface
+
+```typescript
+interface ForgeUser {
+  userID: string;
+  custom?: Record<string, string | number | boolean>;
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `environment` | `'development' \| 'staging' \| 'production'` | `'development'` | Environment tier for feature flag evaluation |
+

package/out/data-adapter.d.ts

@@ -0,0 +1,15 @@
+import { IDataAdapter, AdapterResponse } from 'statsig-node';
+export declare class ForgeDataAdapter implements IDataAdapter {
+    private readonly pollingIntervalMs;
+    private readonly pollingEnabled;
+    private readonly cache;
+    constructor(pollingIntervalMs?: number, pollingEnabled?: boolean);
+    get(key: string): Promise<AdapterResponse>;
+    private fetchFromAtlassianServers;
+    set(key: string, value: string): Promise<void>;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    supportsPollingUpdatesFor(key: string): boolean;
+    getPollingIntervalMs(): number;
+}
+//# sourceMappingURL=data-adapter.d.ts.map

package/out/data-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-adapter.d.ts","sourceRoot":"","sources":["../src/data-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAK7D,qBAAa,gBAAiB,YAAW,YAAY;IAIjD,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAJjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;gBAGrC,iBAAiB,GAAE,MAAc,EACjC,cAAc,GAAE,OAAc;IAM3C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;YA+ClC,yBAAyB;IAiCjC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ/B,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IA8B/C,oBAAoB,IAAI,MAAM;CAG/B"}

package/out/data-adapter.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeDataAdapter = void 0;
+const api_1 = require("@forge/api");
+class ForgeDataAdapter {
+    pollingIntervalMs;
+    pollingEnabled;
+    cache = new Map();
+    constructor(pollingIntervalMs = 30000, pollingEnabled = true) {
+        this.pollingIntervalMs = pollingIntervalMs;
+        this.pollingEnabled = pollingEnabled;
+    }
+    async get(key) {
+        try {
+            const data = await this.fetchFromAtlassianServers();
+            if (data) {
+                const serializedData = JSON.stringify(data);
+                this.cache.set(key, serializedData);
+                return {
+                    result: serializedData,
+                    time: Date.now()
+                };
+            }
+            const cachedValue = this.cache.get(key);
+            if (cachedValue) {
+                return {
+                    result: cachedValue,
+                    time: Date.now()
+                };
+            }
+            return {
+                result: undefined,
+                time: Date.now()
+            };
+        }
+        catch {
+            const cachedValue = this.cache.get(key);
+            if (cachedValue) {
+                return {
+                    result: cachedValue,
+                    time: Date.now()
+                };
+            }
+            return {
+                result: undefined,
+                time: Date.now()
+            };
+        }
+    }
+    async fetchFromAtlassianServers() {
+        const runtime = (0, api_1.__getRuntime)();
+        if (runtime.proxy?.tokenExpiry && runtime.proxy.tokenExpiry * 1000 < Date.now()) {
+            return null;
+        }
+        const remainingTime = runtime.lambdaContext?.getRemainingTimeInMillis?.();
+        if (remainingTime !== undefined && remainingTime < 5000) {
+            return null;
+        }
+        const response = await (0, api_1.__fetchProduct)({ provider: 'app', remote: 'feature-flags', type: 'feature-flags' })('/', {
+            method: 'GET',
+            redirect: 'follow',
+            headers: {
+                'Content-Type': 'application/json'
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        return response.json();
+    }
+    async set(key, value) {
+        try {
+            this.cache.set(key, value);
+        }
+        catch { }
+    }
+    async initialize() { }
+    async shutdown() {
+        this.cache.clear();
+    }
+    supportsPollingUpdatesFor(key) {
+        if (!this.pollingEnabled) {
+            return false;
+        }
+        try {
+            const runtime = (0, api_1.__getRuntime)();
+            if (runtime.proxy?.tokenExpiry && runtime.proxy.tokenExpiry * 1000 < Date.now()) {
+                return false;
+            }
+            const remainingTime = runtime.lambdaContext?.getRemainingTimeInMillis?.();
+            if (remainingTime !== undefined && remainingTime < 10000) {
+                return false;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    getPollingIntervalMs() {
+        return this.pollingIntervalMs;
+    }
+}
+exports.ForgeDataAdapter = ForgeDataAdapter;

package/out/index.d.ts

@@ -0,0 +1,19 @@
+export interface ForgeFeatureFlagConfig {
+    environment?: 'development' | 'staging' | 'production';
+}
+export interface ForgeUser {
+    userID: string;
+    custom?: Record<string, string | number | boolean>;
+}
+export declare class ForgeFeatureFlags {
+    private initialized;
+    private dataAdapter;
+    initialize(config?: ForgeFeatureFlagConfig): Promise<void>;
+    checkFlag(user: ForgeUser, flagName: string): boolean;
+    getFeatureFlags(user: ForgeUser, flagNames: string[]): Record<string, boolean>;
+    shutdown(): Promise<void>;
+    isInitialized(): boolean;
+    private ensureInitialized;
+    private convertUser;
+}
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;CACxD;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACpD;AAKD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAiC;IAKvC,UAAU,CAAC,MAAM,GAAE,sBAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BpE,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAQrD,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAcxE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAe/B,aAAa,IAAI,OAAO;IAI/B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,WAAW;CAMpB"}

package/out/index.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeFeatureFlags = void 0;
+const statsig_node_1 = require("statsig-node");
+const data_adapter_1 = require("./data-adapter");
+class ForgeFeatureFlags {
+    initialized = false;
+    dataAdapter = null;
+    async initialize(config = {}) {
+        if (this.initialized) {
+            return;
+        }
+        try {
+            statsig_node_1.Statsig.shutdown();
+        }
+        catch { }
+        this.dataAdapter = new data_adapter_1.ForgeDataAdapter(30000, true);
+        const statsigOptions = {
+            environment: { tier: config.environment || 'development' },
+            disableRulesetsSync: false,
+            disableIdListsSync: true,
+            initTimeoutMs: 3000,
+            localMode: true,
+            dataAdapter: this.dataAdapter
+        };
+        await statsig_node_1.Statsig.initialize('forge-internal-key', statsigOptions);
+        this.initialized = true;
+    }
+    checkFlag(user, flagName) {
+        this.ensureInitialized();
+        return statsig_node_1.Statsig.checkGate(this.convertUser(user), flagName);
+    }
+    getFeatureFlags(user, flagNames) {
+        this.ensureInitialized();
+        const results = {};
+        for (const flagName of flagNames) {
+            results[flagName] = statsig_node_1.Statsig.checkGate(this.convertUser(user), flagName);
+        }
+        return results;
+    }
+    async shutdown() {
+        if (!this.initialized) {
+            return;
+        }
+        statsig_node_1.Statsig.shutdown();
+        if (this.dataAdapter) {
+            await this.dataAdapter.shutdown();
+        }
+        this.initialized = false;
+    }
+    isInitialized() {
+        return this.initialized;
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('ForgeFeatureFlags not initialized. Call initialize() first.');
+        }
+    }
+    convertUser(user) {
+        return {
+            userID: user.userID,
+            custom: user.custom
+        };
+    }
+}
+exports.ForgeFeatureFlags = ForgeFeatureFlags;

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@forge/feature-flags-node",
+  "version": "1.0.0-next.0",
+  "description": "Feature Flags Node SDK for Atlassian Forge apps running on Node Runtime",
+  "author": "Atlassian",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "main": "out/index.js",
+  "types": "out/index.d.ts",
+  "scripts": {
+    "build": "yarn run clean && yarn run compile",
+    "clean": "rm -rf ./out && rm -f tsconfig.tsbuildinfo",
+    "compile": "tsc -b -v"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.1"
+  },
+  "dependencies": {
+    "@forge/api": "^6.0.2-next.3",
+    "statsig-node": "^6.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://packages.atlassian.com/api/npm/npm-public/"
+  }
+}