@fluxcontrolsdk/js-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FluxControl Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# FluxControl JavaScript SDK
+
+High-performance JavaScript/TypeScript SDK for feature flags and experimentation in web applications.
+
+## Installation
+
+```bash
+npm install @fluxcontrol/js-sdk
+# or
+yarn add @fluxcontrol/js-sdk
+```
+
+## Quick Start
+
+### Vanilla JavaScript/TypeScript
+
+```typescript
+import { FluxClient } from '@fluxcontrol/js-sdk';
+
+// Initialize client
+const client = new FluxClient('your-sdk-key', {
+  edgeUrl: 'https://edge.fluxcontrol.io',
+  enableAnalytics: true
+});
+
+// Create context
+const context = {
+  userId: 'user-123',
+  attributes: {
+    plan: 'premium',
+    country: 'US'
+  }
+};
+
+// Evaluate boolean flag
+const enabled = await client.boolVariation('new-feature', context, false);
+if (enabled) {
+  // New feature code
+}
+
+// Evaluate string flag
+const theme = await client.stringVariation('ui-theme', context, 'light');
+
+// Track custom event
+await client.track('button_clicked', context, {
+  buttonId: 'checkout',
+  page: 'cart'
+});
+
+// Cleanup
+client.close();
+```
+
+### React
+
+```tsx
+import { FluxProvider, useFeature, useTrack } from '@fluxcontrol/js-sdk';
+
+// Wrap your app
+function App() {
+  return (
+    <FluxProvider 
+      sdkKey="your-sdk-key"
+      context={{ userId: 'user-123' }}
+    >
+      <MyComponent />
+    </FluxProvider>
+  );
+}
+
+// Use in components
+function MyComponent() {
+  // Evaluate flag
+  const checkoutFlow = useFeature('checkout-flow', 'standard');
+  
+  // Track events
+  const track = useTrack();
+  
+  const handleClick = () => {
+    track('button_clicked', { button: 'checkout' });
+  };
+  
+  if (checkoutFlow === 'one-click') {
+    return <OneClickCheckout onClick={handleClick} />;
+  }
+  
+  return <StandardCheckout onClick={handleClick} />;
+}
+```
+
+## API Reference
+
+### FluxClient
+
+Main client for evaluating feature flags.
+
+#### Constructor
+
+```typescript
+new FluxClient(sdkKey: string, config?: Config)
+```
+
+**Config Options:**
+- `edgeUrl` - Edge evaluator URL (default: 'https://edge.fluxcontrol.io')
+- `pollingInterval` - Cache refresh interval in ms (default: 60000)
+- `enableAnalytics` - Enable event tracking (default: true)
+- `localStorage` - Use localStorage for caching (default: true)
+
+#### Methods
+
+**`boolVariation(flagKey, context, defaultValue)`**
+Evaluate a boolean flag.
+
+**`stringVariation(flagKey, context, defaultValue)`**
+Evaluate a string flag.
+
+**`numberVariation(flagKey, context, defaultValue)`**
+Evaluate a number flag.
+
+**`jsonVariation<T>(flagKey, context, defaultValue)`**
+Evaluate a JSON flag with type safety.
+
+**`track(eventName, context, properties?, value?)`**
+Track a custom event.
+
+**`close()`**
+Cleanup and stop polling.
+
+### React Hooks
+
+#### `FluxProvider`
+
+Provider component to wrap your app.
+
+```tsx
+<FluxProvider 
+  sdkKey="your-key"
+  config={{ edgeUrl: 'https://...' }}
+  context={{ userId: 'user-123' }}
+>
+  {children}
+</FluxProvider>
+```
+
+#### `useFeature(flagKey, defaultValue, contextOverride?)`
+
+Hook to evaluate a feature flag.
+
+```tsx
+const theme = useFeature('ui-theme', 'light');
+const enabled = useFeature('new-feature', false);
+const config = useFeature('feature-config', { timeout: 5000 });
+```
+
+#### `useFluxClient()`
+
+Get the client instance for advanced usage.
+
+```tsx
+const client = useFluxClient();
+await client.track('custom_event', context);
+```
+
+#### `useTrack()`
+
+Hook to track custom events.
+
+```tsx
+const track = useTrack();
+track('purchase', { productId: '123' }, 99.99);
+```
+
+## Context
+
+The context object provides user attributes for targeting:
+
+```typescript
+interface Context {
+  userId?: string;
+  sessionId?: string;
+  attributes?: Record<string, any>;
+}
+```
+
+**Standard attributes:**
+- `userId` - Unique user identifier
+- `sessionId` - Session identifier
+- `attributes` - Custom attributes (plan, country, etc.)
+
+## Features
+
+- ✅ **TypeScript Support** - Full type definitions
+- ✅ **React Integration** - Hooks and Provider
+- ✅ **Local Caching** - localStorage for offline support
+- ✅ **Auto-refresh** - Polling for flag updates
+- ✅ **Event Tracking** - Automatic exposure tracking
+- ✅ **Edge Evaluation** - Secure server-side evaluation
+- ✅ **SSR Compatible** - Works with Next.js and other frameworks
+
+## Advanced Usage
+
+### Custom Context per Evaluation
+
+```tsx
+const enabled = useFeature('feature', false, {
+  attributes: { experiment: 'variant-a' }
+});
+```
+
+### Conditional Rendering
+
+```tsx
+function FeatureGate({ flagKey, children }) {
+  const enabled = useFeature(flagKey, false);
+  return enabled ? <>{children}</> : null;
+}
+
+<FeatureGate flagKey="new-ui">
+  <NewUI />
+</FeatureGate>
+```
+
+### A/B Testing
+
+```tsx
+function Experiment() {
+  const variant = useFeature('homepage-hero', 'control');
+  const track = useTrack();
+  
+  useEffect(() => {
+    // Track impression
+    track('hero_viewed', { variant });
+  }, [variant]);
+  
+  const handleClick = () => {
+    track('hero_clicked', { variant });
+  };
+  
+  switch (variant) {
+    case 'variant-a':
+      return <HeroA onClick={handleClick} />;
+    case 'variant-b':
+      return <HeroB onClick={handleClick} />;
+    default:
+      return <HeroControl onClick={handleClick} />;
+  }
+}
+```
+
+## Browser Support
+
+- Chrome/Edge: Latest 2 versions
+- Firefox: Latest 2 versions
+- Safari: Latest 2 versions
+- iOS Safari: iOS 12+
+- Android Chrome: Latest 2 versions
+
+## License
+
+Internal use only.

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+import { Context, Config, EvaluationResult, Ruleset } from './types';
+export { Context, Config, EvaluationResult, Ruleset };
+/**
+ * FluxControl JavaScript SDK (Thick Client)
+ *
+ * Downloads rulesets and evaluates flags locally.
+ */
+export declare class FluxClient {
+    private sdkKey;
+    private config;
+    private evaluator;
+    private ruleset;
+    private pollingInterval;
+    constructor(sdkKey: string, config?: Config);
+    /**
+     * Initialize the SDK (fetch ruleset).
+     */
+    init(): Promise<void>;
+    /**
+     * Fetch ruleset from API.
+     */
+    fetchRuleset(): Promise<void>;
+    /**
+     * Evaluate a boolean flag.
+     * Note: Sync evaluation now possible if ruleset is loaded!
+     * But we keep async signature if needed or make it sync?
+     * Legacy SDK was async. Let's make it sync but helpful.
+     * Actually, if init() is async, we can't guarantee ruleset is there immediately.
+     */
+    boolVariation(flagKey: string, context: Context, defaultValue: boolean): boolean;
+    stringVariation(flagKey: string, context: Context, defaultValue: string): string;
+    numberVariation(flagKey: string, context: Context, defaultValue: number): number;
+    jsonVariation<T = any>(flagKey: string, context: Context, defaultValue: T): T;
+    isEnabled(flagKey: string, contextOrId: Context | string, defaultValue?: boolean): boolean;
+    /**
+     * Internal evaluation.
+     */
+    private evaluate;
+    /**
+     * Track a custom event.
+     */
+    track(eventName: string, context: Context, properties?: Record<string, any>, value?: number): Promise<void>;
+    close(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC;AAEtD;;;;GAIG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,eAAe,CAAM;gBAEjB,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW;IAe/C;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BnC;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO;IAKhF,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAKhF,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAKhF,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC;IAI7E,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,EAAE,YAAY,GAAE,OAAe,GAAG,OAAO;IAMjG;;OAEG;IACH,OAAO,CAAC,QAAQ;IAahB;;OAEG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBjH,KAAK;CAGR"}

package/dist/evaluator.d.ts

@@ -0,0 +1,40 @@
+import { Context, Ruleset, EvaluationResult } from './types';
+/**
+ * Evaluates feature flags against targeting rules.
+ */
+export declare class Evaluator {
+    /**
+     * Evaluate a flag.
+     */
+    evaluate(flagKey: string, context: Context, ruleset: Ruleset, defaultValue: any): EvaluationResult;
+    /**
+     * Evaluate all conditions in a rule.
+     */
+    private evaluateConditions;
+    /**
+     * Evaluate a single condition.
+     */
+    private evaluateCondition;
+    /**
+     * Serve a specific variation.
+     */
+    private serveVariation;
+    /**
+     * Serve variation based on percentage rollout.
+     */
+    private servePercentageRollout;
+    /**
+     * Serve variation based on boolean rollout (simplified format: {on: percentage}).
+     * Used for boolean flags where 'on' represents the percentage for 'true'.
+     */
+    private serveBooleanRollout;
+    /**
+     * Get consistent bucket (0-9999) for user using MD5 hash.
+     */
+    /**
+     * Get consistent bucket (0-9999) for user using simple hash (DJB2).
+     * Format: flagKey:userId (matches Python SDK for cross-SDK consistency)
+     */
+    private getBucket;
+}
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../src/evaluator.ts"],"names":[],"mappings":"AACA,OAAO,EACH,OAAO,EACP,OAAO,EAIP,gBAAgB,EAGnB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,SAAS;IAClB;;OAEG;IACH,QAAQ,CACJ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,GAAG,GAClB,gBAAgB;IA0CnB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAqDzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAsBtB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA8B9B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA2C3B;;OAEG;IACH;;;OAGG;IACH,OAAO,CAAC,SAAS;CAQpB"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * FluxControl JavaScript SDK
+ *
+ * @packageDocumentation
+ */
+export * from './types';
+export * from './client';
+export * from './react';
+import { FluxClient } from './client';
+export default FluxClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,eAAe,UAAU,CAAC"}