anmo 1.0.0

package/README.md

@@ -0,0 +1,243 @@
+# Anmo SDK
+
+Official Node.js SDK for Anmo Feature Flags - a modern, real-time feature flag management service.
+
+## Installation
+
+```bash
+npm install anmo
+```
+
+## Quick Start
+
+```typescript
+import { AnmoClient } from "anmo";
+
+const client = new AnmoClient({
+  apiKey: "anmo_your_api_key_here",
+  autoFetch: true, // Automatically fetch flags on init
+  autoStream: true, // Automatically start streaming updates
+});
+
+// Wait for initial flags to load
+await client.ready();
+
+// Check if a flag is enabled
+if (client.isEnabled("new-dashboard")) {
+  console.log("New dashboard is enabled!");
+}
+```
+
+## Features
+
+- 🚀 **Real-time Updates** - Automatically sync flag changes via Server-Sent Events
+- 🔒 **Type-safe** - Full TypeScript support with type definitions
+- 📦 **Lightweight** - Minimal dependencies
+- 🎯 **Simple API** - Easy to use, hard to misuse
+- ⚡ **Fast** - Built for performance
+- ⚛️ **React Hooks** - First-class React support with custom hooks
+
+## Installation
+
+```bash
+npm install anmo
+```
+
+For React applications, React 16.8+ is required (for hooks support).
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { AnmoClient } from "anmo";
+
+const client = new AnmoClient({
+  apiKey: "anmo_your_api_key_here",
+  baseUrl: "https://your-anmo-instance.com",
+});
+
+// Wait for initial flags to load
+await client.ready();
+
+// Check individual flag
+if (client.isEnabled("new-dashboard")) {
+  console.log("New dashboard is enabled!");
+}
+
+// Get a specific flag with a default value
+const darkMode = client.getFlag("dark-mode", false);
+
+// Get all flags
+const allFlags = client.getAllFlags();
+console.log("All flags:", allFlags);
+```
+
+### Real-time Updates
+
+```typescript
+const client = new AnmoClient({
+  apiKey: "anmo_your_api_key_here",
+  baseUrl: "https://your-anmo-instance.com",
+  autoStream: true, // Start streaming immediately
+});
+
+// Listen for flag updates
+client.onUpdate((flags) => {
+  console.log("Flags updated:", flags);
+
+  // React to changes
+  if (flags["maintenance-mode"]) {
+    showMaintenanceBanner();
+  }
+});
+
+// Clean up when done
+process.on("SIGINT", () => {
+  client.destroy();
+  process.exit();
+});
+```
+
+### Manual Streaming Control
+
+```typescript
+const client = new AnmoClient({
+  apiKey: "anmo_your_api_key_here",
+  baseUrl: "https://your-anmo-instance.com",
+  autoStream: false, // Don't auto-start
+});
+
+// Start streaming manually
+client.startStream();
+
+// Stop streaming when needed
+client.stopStream();
+```
+
+### React Usage
+
+The SDK provides React hooks for easy integration:
+
+#### Basic Hook
+
+```tsx
+import { useFeatureFlag } from "anmo/react";
+
+function App() {
+  const showNewDashboard = useFeatureFlag("new-dashboard", {
+    apiKey: process.env.REACT_APP_ANMO_API_KEY!,
+  });
+  const useDarkMode = useFeatureFlag("use-dark-mode", {
+    apiKey: process.env.REACT_APP_ANMO_API_KEY!,
+  });
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      {showNewDashboard && <NewDashboard />}
+      {useDarkMode && <DarkModeToggle />}
+    </div>
+  );
+}
+```
+
+## React API Reference
+
+### `useFeatureFlag(flagKey, options, defaultValue?)`
+
+Hook for a single feature flag. Returns boolean indicating if the flag is enabled.
+
+## Node.js API Reference
+
+### Constructor Options
+
+```typescript
+interface AnmoClientOptions {
+  apiKey: string; // Required: Your Anmo API key
+  baseUrl?: string; // Optional: Base URL (default: 'http://localhost:3000')
+  autoFetch?: boolean; // Optional: Auto-fetch on init (default: true)
+  autoStream?: boolean; // Optional: Auto-start streaming (default: false)
+}
+```
+
+### Methods
+
+#### `ready(): Promise<void>`
+
+Wait for the client to be ready (initial flags fetched).
+
+#### `getFlags(): Promise<FlagMap>`
+
+Manually fetch all feature flags. Usually not needed if `autoFetch` is enabled.
+
+#### `isEnabled(key: string, defaultValue?: boolean): boolean`
+
+Check if a feature flag is enabled. Returns `defaultValue` (default: `false`) if flag doesn't exist.
+
+#### `getFlag(key: string, defaultValue?: boolean): boolean`
+
+Alias for `isEnabled()`.
+
+#### `getAllFlags(): FlagMap`
+
+Get a copy of all current flags as an object.
+
+#### `onUpdate(listener: (flags: FlagMap) => void): () => void`
+
+Subscribe to flag updates. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = client.onUpdate((flags) => {
+  console.log("Updated flags:", flags);
+});
+
+// Later, to unsubscribe:
+unsubscribe();
+```
+
+#### `startStream(): void`
+
+Start streaming real-time updates via Server-Sent Events.
+
+#### `stopStream(): void`
+
+Stop streaming updates and close the connection.
+
+#### `destroy(): void`
+
+Clean up all resources, close connections, and remove all listeners.
+
+## Publishing to npm
+
+To publish this package to npm:
+
+```bash
+cd sdks/javascript
+npm install
+npm run build
+npm publish --access public
+```
+
+## Development
+
+To work on the SDK locally:
+
+```bash
+cd sdks/javascript
+npm install
+npm run build
+npm link
+```
+
+Then in your project:
+
+```bash
+npm link anmo
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Type representing a map of feature flag keys to their enabled state
+ */
+export type FlagMap = Record<string, boolean>;
+/**
+ * Configuration options for the Anmo client
+ */
+export interface AnmoClientOptions {
+    /**
+     * Your Anmo API key (starts with 'anmo_')
+     */
+    apiKey: string;
+    /**
+     * Base URL of your Anmo instance
+     * @default 'https://anmo.io'
+     */
+    baseUrl?: string;
+    /**
+     * Whether to automatically fetch flags on initialization
+     * @default true
+     */
+    autoFetch?: boolean;
+    /**
+     * Whether to automatically start streaming updates
+     * @default false
+     */
+    autoStream?: boolean;
+}
+/**
+ * Anmo Feature Flag Client
+ *
+ * This client provides methods to interact with the Anmo feature flag service,
+ * including fetching flags, checking if flags are enabled, and subscribing to
+ * real-time updates via Server-Sent Events (SSE).
+ *
+ * @example
+ * ```typescript
+ * const client = new AnmoClient({
+ *   apiKey: 'anmo_your_api_key_here',
+ *   baseUrl: 'https://your-anmo-instance.com',
+ *   autoFetch: true,
+ *   autoStream: true
+ * });
+ *
+ * // Wait for initial flags to load
+ * await client.ready();
+ *
+ * // Check if a flag is enabled
+ * if (client.isEnabled('new-dashboard')) {
+ *   console.log('New dashboard is enabled!');
+ * }
+ *
+ * // Listen for flag updates
+ * client.onUpdate((flags) => {
+ *   console.log('Flags updated:', flags);
+ * });
+ * ```
+ */
+export declare class AnmoClient {
+    private apiKey;
+    private baseUrl;
+    private flags;
+    private eventSource;
+    private updateListeners;
+    private readyPromise;
+    private readyResolve;
+    private isReady;
+    constructor(options: AnmoClientOptions);
+    /**
+     * Wait for the client to be ready (initial flags fetched)
+     * @returns Promise that resolves when flags are ready
+     */
+    ready(): Promise<void>;
+    /**
+     * Fetch all feature flags for the environment
+     * @returns Promise resolving to the flag map
+     */
+    getFlags(): Promise<FlagMap>;
+    /**
+     * Check if a feature flag is enabled
+     * @param key - The flag key to check
+     * @param defaultValue - Default value if flag is not found (default: false)
+     * @returns Whether the flag is enabled
+     */
+    isEnabled(key: string, defaultValue?: boolean): boolean;
+    /**
+     * Get the value of a specific flag
+     * @param key - The flag key
+     * @param defaultValue - Default value if flag is not found
+     * @returns The flag value
+     */
+    getFlag(key: string, defaultValue?: boolean): boolean;
+    /**
+     * Get all current flags
+     * @returns A copy of all flags
+     */
+    getAllFlags(): FlagMap;
+    /**
+     * Subscribe to flag updates
+     * @param listener - Callback function to call when flags update
+     * @returns Unsubscribe function
+     */
+    onUpdate(listener: (flags: FlagMap) => void): () => void;
+    /**
+     * Start streaming real-time updates via Server-Sent Events
+     */
+    startStream(): void;
+    /**
+     * Stop streaming updates
+     */
+    stopStream(): void;
+    /**
+     * Notify all listeners of flag updates
+     */
+    private notifyListeners;
+    /**
+     * Clean up resources and close connections
+     */
+    destroy(): void;
+}
+export default AnmoClient;

package/dist/index.js

@@ -0,0 +1,224 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnmoClient = void 0;
+const eventsource_1 = __importDefault(require("eventsource"));
+/**
+ * Anmo Feature Flag Client
+ *
+ * This client provides methods to interact with the Anmo feature flag service,
+ * including fetching flags, checking if flags are enabled, and subscribing to
+ * real-time updates via Server-Sent Events (SSE).
+ *
+ * @example
+ * ```typescript
+ * const client = new AnmoClient({
+ *   apiKey: 'anmo_your_api_key_here',
+ *   baseUrl: 'https://your-anmo-instance.com',
+ *   autoFetch: true,
+ *   autoStream: true
+ * });
+ *
+ * // Wait for initial flags to load
+ * await client.ready();
+ *
+ * // Check if a flag is enabled
+ * if (client.isEnabled('new-dashboard')) {
+ *   console.log('New dashboard is enabled!');
+ * }
+ *
+ * // Listen for flag updates
+ * client.onUpdate((flags) => {
+ *   console.log('Flags updated:', flags);
+ * });
+ * ```
+ */
+class AnmoClient {
+    constructor(options) {
+        this.flags = {};
+        this.eventSource = null;
+        this.updateListeners = [];
+        this.readyPromise = null;
+        this.readyResolve = null;
+        this.isReady = false;
+        if (!options.apiKey) {
+            throw new Error("API key is required");
+        }
+        if (!options.apiKey.startsWith("anmo_")) {
+            console.warn('API key should start with "anmo_"');
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl || "https://anmo.io";
+        // Create ready promise
+        this.readyPromise = new Promise((resolve) => {
+            this.readyResolve = resolve;
+        });
+        // Auto-fetch flags if enabled
+        if (options.autoFetch !== false) {
+            this.getFlags().catch((error) => {
+                console.error("Failed to fetch initial flags:", error);
+            });
+        }
+        // Auto-start streaming if enabled
+        if (options.autoStream === true) {
+            this.startStream();
+        }
+    }
+    /**
+     * Wait for the client to be ready (initial flags fetched)
+     * @returns Promise that resolves when flags are ready
+     */
+    async ready() {
+        if (this.isReady)
+            return;
+        return this.readyPromise;
+    }
+    /**
+     * Fetch all feature flags for the environment
+     * @returns Promise resolving to the flag map
+     */
+    async getFlags() {
+        try {
+            const response = await fetch(`${this.baseUrl}/api/client/flags`, {
+                headers: {
+                    "x-api-key": this.apiKey,
+                },
+            });
+            if (!response.ok) {
+                const error = (await response
+                    .json()
+                    .catch(() => ({ error: "Unknown error" })));
+                throw new Error(`Failed to fetch flags: ${response.statusText} - ${error.error || ""}`);
+            }
+            const data = (await response.json());
+            this.flags = data.flags;
+            if (!this.isReady) {
+                this.isReady = true;
+                this.readyResolve?.();
+            }
+            return this.flags;
+        }
+        catch (error) {
+            console.error("Error fetching flags:", error);
+            throw error;
+        }
+    }
+    /**
+     * Check if a feature flag is enabled
+     * @param key - The flag key to check
+     * @param defaultValue - Default value if flag is not found (default: false)
+     * @returns Whether the flag is enabled
+     */
+    isEnabled(key, defaultValue = false) {
+        if (!(key in this.flags)) {
+            return defaultValue;
+        }
+        return this.flags[key] === true;
+    }
+    /**
+     * Get the value of a specific flag
+     * @param key - The flag key
+     * @param defaultValue - Default value if flag is not found
+     * @returns The flag value
+     */
+    getFlag(key, defaultValue = false) {
+        return this.isEnabled(key, defaultValue);
+    }
+    /**
+     * Get all current flags
+     * @returns A copy of all flags
+     */
+    getAllFlags() {
+        return { ...this.flags };
+    }
+    /**
+     * Subscribe to flag updates
+     * @param listener - Callback function to call when flags update
+     * @returns Unsubscribe function
+     */
+    onUpdate(listener) {
+        this.updateListeners.push(listener);
+        // Return unsubscribe function
+        return () => {
+            const index = this.updateListeners.indexOf(listener);
+            if (index > -1) {
+                this.updateListeners.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Start streaming real-time updates via Server-Sent Events
+     */
+    startStream() {
+        if (this.eventSource) {
+            console.warn("Stream already started");
+            return;
+        }
+        const url = `${this.baseUrl}/api/client/stream`;
+        this.eventSource = new eventsource_1.default(url, {
+            headers: {
+                "x-api-key": this.apiKey,
+            },
+        });
+        this.eventSource.onmessage = (event) => {
+            try {
+                const data = JSON.parse(event.data);
+                if (data.type === "initial" || data.type === "update") {
+                    this.flags = data.flags;
+                    if (!this.isReady) {
+                        this.isReady = true;
+                        this.readyResolve?.();
+                    }
+                    this.notifyListeners();
+                }
+            }
+            catch (error) {
+                console.error("Error parsing SSE message:", error);
+            }
+        };
+        this.eventSource.onerror = (error) => {
+            console.error("SSE error:", error);
+            this.stopStream();
+            // Attempt to reconnect after 5 seconds
+            setTimeout(() => {
+                console.log("Attempting to reconnect...");
+                this.startStream();
+            }, 5000);
+        };
+    }
+    /**
+     * Stop streaming updates
+     */
+    stopStream() {
+        if (this.eventSource) {
+            this.eventSource.close();
+            this.eventSource = null;
+        }
+    }
+    /**
+     * Notify all listeners of flag updates
+     */
+    notifyListeners() {
+        const currentFlags = this.getAllFlags();
+        this.updateListeners.forEach((listener) => {
+            try {
+                listener(currentFlags);
+            }
+            catch (error) {
+                console.error("Error in update listener:", error);
+            }
+        });
+    }
+    /**
+     * Clean up resources and close connections
+     */
+    destroy() {
+        this.stopStream();
+        this.updateListeners = [];
+    }
+}
+exports.AnmoClient = AnmoClient;
+// Re-export for convenience
+exports.default = AnmoClient;

package/dist/react.d.ts

@@ -0,0 +1,18 @@
+import type { FlagMap, AnmoClientOptions } from "./index";
+export type { FlagMap, AnmoClientOptions };
+/**
+ * React hook for a single feature flag with real-time updates
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const isNewDashboard = useFeatureFlag('new-dashboard', {
+ *     apiKey: 'anmo_your_api_key',
+ *     baseUrl: 'https://anmo.io'
+ *   }, false);
+ *
+ *   return isNewDashboard ? <NewDashboard /> : <OldDashboard />;
+ * }
+ * ```
+ */
+export declare function useFeatureFlag(flagKey: string, options: AnmoClientOptions, defaultValue?: boolean): boolean;

package/dist/react.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFeatureFlag = useFeatureFlag;
+const react_1 = require("react");
+const index_1 = require("./index");
+/**
+ * React hook for a single feature flag with real-time updates
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const isNewDashboard = useFeatureFlag('new-dashboard', {
+ *     apiKey: 'anmo_your_api_key',
+ *     baseUrl: 'https://anmo.io'
+ *   }, false);
+ *
+ *   return isNewDashboard ? <NewDashboard /> : <OldDashboard />;
+ * }
+ * ```
+ */
+function useFeatureFlag(flagKey, options, defaultValue = false) {
+    const [value, setValue] = (0, react_1.useState)(defaultValue);
+    // Create client instance (memoized by API key and URL)
+    const client = (0, react_1.useMemo)(() => {
+        return new index_1.AnmoClient({
+            ...options,
+            autoFetch: false,
+            autoStream: false,
+        });
+    }, [options.apiKey, options.baseUrl]);
+    (0, react_1.useEffect)(() => {
+        let mounted = true;
+        // Fetch initial flags
+        const fetchFlags = async () => {
+            try {
+                const flags = await client.getFlags();
+                if (mounted) {
+                    setValue(flags[flagKey] ?? defaultValue);
+                }
+            }
+            catch (err) {
+                console.error("Failed to fetch flags:", err);
+                if (mounted) {
+                    setValue(defaultValue);
+                }
+            }
+        };
+        fetchFlags();
+        // Subscribe to updates
+        const unsubscribe = client.onUpdate((updatedFlags) => {
+            if (mounted) {
+                setValue(updatedFlags[flagKey] ?? defaultValue);
+            }
+        });
+        // Start streaming
+        client.startStream();
+        // Cleanup
+        return () => {
+            mounted = false;
+            unsubscribe();
+            client.destroy();
+        };
+    }, [client, flagKey, defaultValue]);
+    return value;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "anmo",
+    "version": "1.0.0",
+    "description": "Official Node.js SDK for Anmo Feature Flags",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./react": {
+            "types": "./dist/react.d.ts",
+            "default": "./dist/react.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build",
+        "clean": "rm -rf dist",
+        "test": "npm run build && node test.js"
+    },
+    "keywords": [
+        "feature-flags",
+        "feature-toggles",
+        "anmo",
+        "sdk",
+        "nodejs"
+    ],
+    "author": "",
+    "license": "MIT",
+    "dependencies": {
+        "eventsource": "^2.0.2"
+    },
+    "peerDependencies": {
+        "react": ">=16.8.0"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@types/eventsource": "^1.1.15",
+        "@types/node": "^22.0.0",
+        "@types/react": "^18.0.0",
+        "typescript": "^5.0.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/AndrewVos/anmo"
+    }
+}