@nexussdk/sdk 0.0.1

package/src/nexus.ts

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview Unified Nexus singleton facade wrapping Flags and Tracker clients.
+ * @module @nexus/sdk/nexus
+ */
+
+import { NexusFlagsClient } from '@nexussdk/flags';
+import type { NexusFlagsOptions } from '@nexussdk/flags';
+import { NexusTrackerClient } from '@nexussdk/tracker';
+import type { NexusTrackerOptions } from '@nexussdk/tracker';
+import type { UserContext } from '@nexussdk/contracts';
+
+/**
+ * Unified initialization options for the Nexus SDK umbrella.
+ *
+ * @example
+ * Nexus.init({
+ *   apiKey: 'pk_live_...',
+ *   baseUrl: 'http://localhost:8080',
+ *   user: { id: 'usr_12345', country: 'VN' },
+ *   environment: 'production',
+ *   autoCapture: true,
+ * });
+ */
+export interface NexusInitOptions {
+  /** Public API key. Resolved from env if omitted. */
+  apiKey?: string;
+  /** Base URL for all API calls. */
+  baseUrl?: string;
+  /** Initial user context for flag targeting and error attribution. */
+  user?: UserContext;
+  /** Target environment for telemetry routing. Defaults to 'production'. */
+  environment?: string;
+  /** Global tags attached to all telemetry events. */
+  tags?: Record<string, string>;
+  /** Toggle automated global error capture. Defaults to true. */
+  autoCapture?: boolean;
+  /** Additional flags-specific options. */
+  flags?: Partial<NexusFlagsOptions>;
+  /** Additional tracker-specific options. */
+  tracker?: Partial<NexusTrackerOptions>;
+}
+
+/**
+ * The Nexus singleton class — the primary unified entry point for the SDK.
+ *
+ * Provides access to both the feature flags client and the error tracker client.
+ * Initialize once, then use throughout your application.
+ *
+ * @example
+ * // Initialize (call once at app startup)
+ * Nexus.init({ apiKey: 'pk_live_...' });
+ *
+ * // Feature flags
+ * const showBanner = Nexus.isEnabled('promo_banner_v2', false);
+ *
+ * // Error tracking
+ * Nexus.captureError(new Error('Something went wrong'));
+ *
+ * // Update user context
+ * await Nexus.identify({ id: 'usr_12345', country: 'VN' });
+ */
+export class Nexus {
+  private static instance: Nexus | null = null;
+
+  /** The underlying feature flags client instance. */
+  public readonly flags: NexusFlagsClient;
+  /** The underlying error tracker client instance. */
+  public readonly tracker: NexusTrackerClient;
+
+  private constructor(options: NexusInitOptions = {}) {
+    const { apiKey, baseUrl, user, environment, tags, autoCapture, flags: flagsOpts, tracker: trackerOpts } = options;
+
+    this.flags = new NexusFlagsClient({
+      apiKey,
+      baseUrl,
+      user,
+      ...flagsOpts,
+    });
+
+    this.tracker = new NexusTrackerClient({
+      apiKey,
+      baseUrl,
+      environment,
+      tags,
+      autoCapture,
+      ...trackerOpts,
+    });
+  }
+
+  /**
+   * Initializes the Nexus SDK singleton.
+   * Must be called before any other SDK methods.
+   * Safe to call multiple times — returns existing instance after first init.
+   *
+   * @param options - SDK configuration options.
+   * @returns The initialized Nexus singleton instance.
+   *
+   * @example
+   * const nexus = Nexus.init({ apiKey: 'pk_live_...' });
+   */
+  public static init(options: NexusInitOptions = {}): Nexus {
+    if (!Nexus.instance) {
+      Nexus.instance = new Nexus(options);
+    }
+    return Nexus.instance;
+  }
+
+  /**
+   * Returns the current Nexus singleton instance.
+   *
+   * @returns The active Nexus instance.
+   * @throws {Error} If `Nexus.init()` has not been called yet.
+   *
+   * @example
+   * const nexus = Nexus.getInstance();
+   * nexus.flags.isEnabled('checkout_v2');
+   */
+  public static getInstance(): Nexus {
+    if (!Nexus.instance) {
+      throw new Error('[Nexus SDK] Not initialized. Call Nexus.init({ apiKey: "..." }) first.');
+    }
+    return Nexus.instance;
+  }
+
+  /**
+   * Convenience method: Check if a feature flag is enabled.
+   *
+   * @param key - Flag identifier.
+   * @param defaultValue - Fallback if flag is missing.
+   * @returns Boolean enabled state.
+   *
+   * @example
+   * if (Nexus.isEnabled('checkout_redesign')) { ... }
+   */
+  public static isEnabled(key: string, defaultValue = false): boolean {
+    return Nexus.getInstance().flags.isEnabled(key, defaultValue);
+  }
+
+  /**
+   * Convenience method: Get a flag variant value.
+   *
+   * @param key - Flag identifier.
+   * @param variantKey - Variant property name.
+   * @param defaultValue - Fallback value.
+   * @returns Variant value cast to type T.
+   *
+   * @example
+   * const rate = Nexus.getVariant<number>('promo_banner_v2', 'discount_rate', 10);
+   */
+  public static getVariant<T = unknown>(key: string, variantKey: string, defaultValue?: T): T {
+    return Nexus.getInstance().flags.getVariant<T>(key, variantKey, defaultValue);
+  }
+
+  /**
+   * Convenience method: Capture an error manually.
+   *
+   * @param error - Error instance, string, or unknown value.
+   * @param extra - Optional metadata tags.
+   *
+   * @example
+   * Nexus.captureError(new TypeError('Cannot read properties of null'));
+   */
+  public static captureError(error: unknown, extra?: Record<string, unknown>): void {
+    Nexus.getInstance().tracker.captureError(error, extra);
+  }
+
+  /**
+   * Convenience method: Update user context for both flags and tracker.
+   *
+   * @param user - New user context (merged with existing).
+   * @returns Promise resolving after flags refresh.
+   *
+   * @example
+   * await Nexus.identify({ id: 'usr_12345', country: 'VN' });
+   */
+  public static async identify(user: UserContext): Promise<void> {
+    const instance = Nexus.getInstance();
+    instance.tracker.setUser(user);
+    await instance.flags.identify(user);
+  }
+
+  /**
+   * Resets user context to anonymous state (e.g. on logout).
+   *
+   * @example
+   * Nexus.reset(); // called on user logout
+   */
+  public static reset(): void {
+    const instance = Nexus.getInstance();
+    instance.tracker.setUser(null);
+    instance.flags.reset();
+  }
+
+  /**
+   * Gracefully tears down both clients, closing SSE connections and flushing pending events.
+   *
+   * @example
+   * await Nexus.destroy();
+   */
+  public static async destroy(): Promise<void> {
+    if (Nexus.instance) {
+      await Nexus.instance.tracker.flush();
+      Nexus.instance.tracker.destroy();
+      Nexus.instance.flags.destroy();
+      Nexus.instance = null;
+    }
+  }
+}

package/src/react.tsx

@@ -0,0 +1,204 @@
+'use client';
+
+/**
+ * @fileoverview React Context Provider and hooks for the Nexus SDK umbrella.
+ * @module @nexus/sdk/react
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { Nexus } from './nexus.js';
+import type { NexusInitOptions } from './nexus.js';
+import type { FlagEvaluationResult } from '@nexussdk/contracts';
+import type { NexusFlagsClient } from '@nexussdk/flags';
+import type { NexusTrackerClient } from '@nexussdk/tracker';
+
+// ---------------------------------------------------------------------------
+// Context Definition
+// ---------------------------------------------------------------------------
+
+interface NexusContextValue {
+  flags: NexusFlagsClient;
+  tracker: NexusTrackerClient;
+  nexus: Nexus;
+}
+
+const NexusContext = createContext<NexusContextValue | null>(null);
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for the NexusProvider component.
+ */
+export interface NexusProviderProps extends NexusInitOptions {
+  /** Child components that will have access to Nexus context. */
+  children?: React.ReactNode | any;
+}
+
+/**
+ * React Context Provider that initializes the Nexus SDK and makes it available
+ * to all descendant components via `useFlag` and `useNexus` hooks.
+ *
+ * Mount once at the root of your application (e.g. in `layout.tsx`).
+ *
+ * @param props - Provider configuration options (see {@link NexusProviderProps}).
+ * @returns Provider-wrapped children.
+ *
+ * @example
+ * // app/layout.tsx
+ * import { NexusProvider } from '@nexussdk/sdk/react';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <NexusProvider apiKey={process.env.NEXT_PUBLIC_NEXUS_API_KEY}>
+ *           {children}
+ *         </NexusProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ */
+export function NexusProvider({ children, ...initOptions }: NexusProviderProps): React.ReactElement {
+  const nexusRef = useRef<Nexus | null>(null);
+
+  if (!nexusRef.current) {
+    nexusRef.current = Nexus.init(initOptions);
+  }
+
+  const contextValue = useMemo<NexusContextValue>(
+    () => ({
+      flags: nexusRef.current!.flags,
+      tracker: nexusRef.current!.tracker,
+      nexus: nexusRef.current!,
+    }),
+    [],
+  );
+
+  useEffect(() => {
+    return () => {
+      void Nexus.destroy();
+    };
+  }, []);
+
+  return React.createElement(NexusContext.Provider, { value: contextValue }, children);
+}
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the full Nexus SDK instance from context.
+ *
+ * @returns Object with `flags`, `tracker`, and `nexus` properties.
+ * @throws {Error} If called outside of a `NexusProvider`.
+ *
+ * @example
+ * const { flags, tracker } = useNexus();
+ * const enabled = flags.isEnabled('checkout_v2');
+ * tracker.captureError(new Error('something failed'));
+ */
+export function useNexus(): NexusContextValue {
+  const ctx = useContext(NexusContext);
+  if (!ctx) {
+    throw new Error('[Nexus SDK] useNexus() must be called inside a <NexusProvider>.');
+  }
+  return ctx;
+}
+
+/**
+ * Return value of the `useFlag` hook.
+ */
+export interface UseFlagResult {
+  /** Whether the flag is currently enabled for the current user. */
+  enabled: boolean;
+  /**
+   * Retrieves a specific variant value from this flag.
+   *
+   * @param variantKey - Property name inside the variants object.
+   * @param defaultValue - Fallback if variant is not found.
+   * @returns Typed variant value.
+   *
+   * @example
+   * const { enabled, getVariant } = useFlag('promo_banner_v2');
+   * const rate = getVariant<number>('discount_rate', 10);
+   */
+  getVariant: <T = unknown>(variantKey: string, defaultValue?: T) => T;
+  /** Full evaluation result including reason and version. */
+  result: FlagEvaluationResult | null;
+}
+
+/**
+ * React hook for subscribing to a feature flag's real-time state.
+ *
+ * Automatically re-renders when the flag changes via SSE updates.
+ * Returns a stable result without triggering additional re-renders if unchanged.
+ *
+ * @param key - Flag programmatic identifier.
+ * @param defaultEnabled - Fallback boolean if flag is not yet evaluated. Defaults to false.
+ * @returns {@link UseFlagResult} with `enabled`, `getVariant`, and `result`.
+ *
+ * @example
+ * function CheckoutButton() {
+ *   const { enabled, getVariant } = useFlag('checkout_redesign');
+ *   const theme = getVariant<string>('theme', 'default');
+ *
+ *   return (
+ *     <button className={enabled ? `btn-${theme}` : 'btn-default'}>
+ *       {enabled ? 'New Checkout' : 'Checkout'}
+ *     </button>
+ *   );
+ * }
+ */
+export function useFlag(key: string, defaultEnabled = false): UseFlagResult {
+  const { flags } = useNexus();
+
+  const [result, setResult] = useState<FlagEvaluationResult | null>(() => {
+    const cached = flags.isEnabled(key) !== defaultEnabled
+      ? { key, enabled: flags.isEnabled(key), variants: {}, reason: 'DEFAULT_ENABLED' as const, version: 0 }
+      : null;
+    return cached;
+  });
+
+  useEffect(() => {
+    // Get current state immediately
+    const currentEnabled = flags.isEnabled(key, defaultEnabled);
+    if (currentEnabled !== (result?.enabled ?? defaultEnabled)) {
+      setResult({
+        key,
+        enabled: currentEnabled,
+        variants: {},
+        reason: 'DEFAULT_ENABLED',
+        version: 0,
+      });
+    }
+
+    // Subscribe to real-time updates
+    const unsubscribe = flags.onFlagChange(key, (newResult) => {
+      setResult(newResult);
+    });
+
+    return unsubscribe;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  return useMemo(
+    () => ({
+      enabled: result?.enabled ?? flags.isEnabled(key, defaultEnabled),
+      getVariant: <T = unknown>(variantKey: string, def?: T): T =>
+        flags.getVariant<T>(key, variantKey, def),
+      result,
+    }),
+    [result, key, flags, defaultEnabled],
+  );
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "jsx": "react-jsx",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"]
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,40 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig([
+  // Main bundle (no React)
+  {
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs', 'iife'],
+    globalName: 'Nexus',
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    clean: true,
+    minify: true,
+    treeshake: true,
+    target: 'es2022',
+    external: ['react', 'react-dom'],
+    outExtension({ format }) {
+      return {
+        js: format === 'esm' ? '.mjs' : format === 'cjs' ? '.cjs' : '.global.js',
+      };
+    },
+  },
+  // React sub-bundle
+  {
+    entry: { react: 'src/react.tsx' },
+    format: ['esm', 'cjs'],
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    minify: true,
+    treeshake: true,
+    target: 'es2022',
+    external: ['react', 'react-dom', '@nexussdk/flags', '@nexussdk/tracker', '@nexussdk/contracts'],
+    outExtension({ format }) {
+      return {
+        js: format === 'esm' ? '.mjs' : '.cjs',
+      };
+    },
+  },
+]);