@hyphen/react-sdk 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hyphen
+
+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,264 @@
+![Hyphen AI](https://github.com/Hyphen/nodejs-sdk/raw/main/logo.png)
+
+[![npm](https://img.shields.io/npm/v/@hyphen/react-sdk)](https://www.npmjs.com/package/@hyphen/react-sdk)
+[![npm](https://img.shields.io/npm/dm/@hyphen/react-sdk)](https://www.npmjs.com/package/@hyphen/react-sdk)
+[![license](https://img.shields.io/github/license/Hyphen/react-sdk)](https://github.com/hyphen/react-sdk/blob/main/LICENSE)
+[![tests](https://github.com/Hyphen/react-sdk/actions/workflows/tests.yaml/badge.svg)](https://github.com/Hyphen/react-sdk/actions/workflows/tests.yaml)
+[![codecov](https://codecov.io/gh/Hyphen/react-sdk/graph/badge.svg?token=pZP47YorSv)](https://codecov.io/gh/Hyphen/react-sdk)
+
+# Hyphen React SDK
+
+The Hyphen React SDK provides React components, hooks, and higher-order components (HOCs) for integrating Hyphen's feature flag and toggle service into your React applications.
+
+## Installation
+
+```bash
+npm install @hyphen/react-sdk
+```
+
+## Quick Start
+
+The SDK provides three ways to integrate Hyphen into your React application:
+
+### 1. Higher-Order Component (HOC) Pattern
+
+Wrap your root component with `withToggleProvider()`:
+
+```tsx
+import { withToggleProvider } from '@hyphen/react-sdk';
+import App from './App';
+
+export default withToggleProvider({
+  publicApiKey: 'public_...',
+  applicationId: 'my-app',
+  environment: 'production',
+  defaultContext: {
+    user: {
+      id: 'user-123',
+      email: 'user@example.com'
+    }
+  }
+})(App);
+```
+
+### 2. Provider Component Pattern
+
+Use the `ToggleProvider` component directly:
+
+```tsx
+import { ToggleProvider } from '@hyphen/react-sdk';
+import App from './App';
+
+function Root() {
+  return (
+    <ToggleProvider
+      publicApiKey="public_..."
+      applicationId="my-app"
+      environment="production"
+      defaultContext={{
+        user: {
+          id: 'user-123',
+          email: 'user@example.com'
+        }
+      }}
+    >
+      <App />
+    </ToggleProvider>
+  );
+}
+```
+
+### 3. Using the `useToggle` Hook
+
+Access feature flags in any component:
+
+```tsx
+import { useToggle } from '@hyphen/react-sdk';
+
+function MyComponent() {
+  const toggle = useToggle();
+
+  // Get boolean feature flag
+  const isNewFeatureEnabled = toggle.getBoolean('new-feature', false);
+
+  // Get string feature flag
+  const theme = toggle.getString('theme', 'light');
+
+  // Get number feature flag
+  const maxItems = toggle.getNumber('max-items', 10);
+
+  // Get object feature flag
+  const config = toggle.getObject('ui-config', { layout: 'grid' });
+
+  return (
+    <div>
+      {isNewFeatureEnabled && <NewFeature />}
+      <p>Theme: {theme}</p>
+      <p>Max Items: {maxItems}</p>
+    </div>
+  );
+}
+```
+
+## Configuration Options
+
+All configuration options are passed to the Toggle instance from `@hyphen/browser-sdk`:
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `publicApiKey` | string | Yes | Your Hyphen public API key (starts with `public_`) |
+| `applicationId` | string | No | Application identifier |
+| `environment` | string | No | Environment name (e.g., 'development', 'production') |
+| `defaultContext` | object | No | Default evaluation context (user, targeting, etc.) |
+| `horizonUrls` | string[] | No | Custom Horizon endpoint URLs for load balancing |
+| `defaultTargetKey` | string | No | Default targeting key |
+
+### Default Context
+
+The `defaultContext` option allows you to set default user and targeting information:
+
+```tsx
+{
+  defaultContext: {
+    targetingKey: 'user-123',
+    user: {
+      id: 'user-123',
+      email: 'user@example.com',
+      name: 'John Doe',
+      customAttributes: {
+        plan: 'premium',
+        region: 'us-west'
+      }
+    },
+    ipAddress: '192.168.1.1',
+    customAttributes: {
+      deviceType: 'mobile'
+    }
+  }
+}
+```
+
+## API Reference
+
+### `ToggleProvider`
+
+React context provider component that creates and provides a Toggle instance.
+
+**Props:** Extends `ToggleOptions` from `@hyphen/browser-sdk` plus:
+- `children`: ReactNode - Components to wrap with the provider
+
+### `withToggleProvider(options)`
+
+Higher-order component that wraps a component with `ToggleProvider`.
+
+**Parameters:**
+- `options`: `ToggleOptions` - Configuration for the Toggle instance
+
+**Returns:** Function that accepts a component and returns a wrapped component
+
+### `useToggle()`
+
+React hook to access the Toggle instance from context.
+
+**Returns:** `Toggle` instance from `@hyphen/browser-sdk`
+
+**Throws:** Error if used outside of `ToggleProvider`
+
+### Toggle Methods
+
+The `Toggle` instance provides these methods:
+
+- `getBoolean(key, defaultValue, options?)` - Get a boolean feature flag
+- `getString(key, defaultValue, options?)` - Get a string feature flag
+- `getNumber(key, defaultValue, options?)` - Get a number feature flag
+- `getObject<T>(key, defaultValue, options?)` - Get an object feature flag
+- `get<T>(key, defaultValue, options?)` - Generic getter for any type
+
+All methods accept an optional `options` parameter for context overrides:
+
+```tsx
+const isEnabled = toggle.getBoolean('feature-key', false, {
+  context: {
+    user: { id: 'different-user' }
+  }
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions out of the box.
+
+```tsx
+import type { ToggleProviderProps } from '@hyphen/react-sdk';
+
+const config: ToggleProviderProps = {
+  publicApiKey: 'public_...',
+  applicationId: 'my-app',
+  children: <App />
+};
+```
+
+## Examples
+
+### Conditional Rendering
+
+```tsx
+function FeatureFlag({ flagKey, children }) {
+  const toggle = useToggle();
+  const isEnabled = toggle.getBoolean(flagKey, false);
+
+  return isEnabled ? <>{children}</> : null;
+}
+
+// Usage
+<FeatureFlag flagKey="new-dashboard">
+  <NewDashboard />
+</FeatureFlag>
+```
+
+### A/B Testing
+
+```tsx
+function ABTest() {
+  const toggle = useToggle();
+  const variant = toggle.getString('homepage-variant', 'control');
+
+  switch (variant) {
+    case 'variant-a':
+      return <HomepageVariantA />;
+    case 'variant-b':
+      return <HomepageVariantB />;
+    default:
+      return <HomepageControl />;
+  }
+}
+```
+
+### Dynamic Configuration
+
+```tsx
+function ConfigurableComponent() {
+  const toggle = useToggle();
+  const config = toggle.getObject('component-config', {
+    maxItems: 10,
+    showImages: true,
+    layout: 'grid'
+  });
+
+  return (
+    <Component
+      maxItems={config.maxItems}
+      showImages={config.showImages}
+      layout={config.layout}
+    />
+  );
+}
+```
+
+# Contributing
+
+We welcome contributions to the Hyphen Node.js SDK! If you have an idea for a new feature, bug fix, or improvement, please follow the [Contribution](./CONTRIBUTING.md) guidelines and our [Code of Conduct](./CODE_OF_CONDUCT.md).
+
+# License and Copyright
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+The copyright for this project is held by Hyphen, Inc. All rights reserved.

package/dist/index.cjs

@@ -0,0 +1,98 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Toggle: () => import_browser_sdk2.Toggle,
+  ToggleContext: () => ToggleContext,
+  ToggleProvider: () => ToggleProvider,
+  useToggle: () => useToggle,
+  withToggleProvider: () => withToggleProvider
+});
+module.exports = __toCommonJS(index_exports);
+var import_browser_sdk2 = require("@hyphen/browser-sdk");
+
+// src/toggle-provider.tsx
+var import_react = require("react");
+var import_browser_sdk = require("@hyphen/browser-sdk");
+var ToggleContext = /* @__PURE__ */ (0, import_react.createContext)(null);
+function ToggleProvider({ children, publicApiKey, applicationId, environment, defaultContext, horizonUrls, defaultTargetKey }) {
+  const toggle = (0, import_react.useMemo)(() => {
+    return new import_browser_sdk.Toggle({
+      publicApiKey,
+      applicationId,
+      environment,
+      defaultContext,
+      horizonUrls,
+      defaultTargetKey
+    });
+  }, [
+    publicApiKey,
+    applicationId,
+    environment,
+    defaultContext,
+    horizonUrls,
+    defaultTargetKey
+  ]);
+  (0, import_react.useEffect)(() => {
+    return () => {
+    };
+  }, [
+    toggle
+  ]);
+  return /* @__PURE__ */ React.createElement(ToggleContext.Provider, {
+    value: toggle
+  }, children);
+}
+__name(ToggleProvider, "ToggleProvider");
+
+// src/use-toggle.tsx
+var import_react2 = require("react");
+function useToggle() {
+  const toggle = (0, import_react2.useContext)(ToggleContext);
+  if (!toggle) {
+    throw new Error("useToggle must be used within a ToggleProvider. Wrap your component tree with <ToggleProvider> or use withToggleProvider().");
+  }
+  return toggle;
+}
+__name(useToggle, "useToggle");
+
+// src/with-toggle-provider.tsx
+function withToggleProvider(options) {
+  return function(Component) {
+    const WrappedComponent = /* @__PURE__ */ __name((props) => {
+      return /* @__PURE__ */ React.createElement(ToggleProvider, options, /* @__PURE__ */ React.createElement(Component, props));
+    }, "WrappedComponent");
+    const componentName = Component.displayName || Component.name || "Component";
+    WrappedComponent.displayName = `withToggleProvider(${componentName})`;
+    return WrappedComponent;
+  };
+}
+__name(withToggleProvider, "withToggleProvider");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Toggle,
+  ToggleContext,
+  ToggleProvider,
+  useToggle,
+  withToggleProvider
+});
+/* v8 ignore next -- @preserve */

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+import { ToggleOptions, Toggle } from '@hyphen/browser-sdk';
+export { Toggle, ToggleOptions } from '@hyphen/browser-sdk';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, Context, ComponentType } from 'react';
+
+/**
+ * Props for the ToggleProvider component
+ * Extends ToggleOptions from @hyphen/browser-sdk
+ */
+interface ToggleProviderProps extends ToggleOptions {
+    /**
+     * React children to be wrapped by the provider
+     */
+    children: ReactNode;
+}
+
+/**
+ * React Context for the Toggle instance
+ */
+declare const ToggleContext: Context<Toggle | null>;
+/**
+ * Provider component that creates and provides a Toggle instance to the React tree
+ *
+ * @example
+ * ```tsx
+ * <ToggleProvider publicApiKey="public_..." applicationId="my-app">
+ *   <App />
+ * </ToggleProvider>
+ * ```
+ */
+declare function ToggleProvider({ children, publicApiKey, applicationId, environment, defaultContext, horizonUrls, defaultTargetKey, }: ToggleProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Hook to access the Toggle instance from the ToggleProvider
+ *
+ * @throws {Error} If used outside of a ToggleProvider
+ * @returns {Toggle} The Toggle instance from the provider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const toggle = useToggle();
+ *   const isEnabled = toggle.getBoolean('my-feature', false);
+ *
+ *   return <div>{isEnabled ? 'Feature enabled' : 'Feature disabled'}</div>;
+ * }
+ * ```
+ */
+declare function useToggle(): Toggle;
+
+/**
+ * Higher-order component that wraps a component with ToggleProvider
+ *
+ * @param options - Configuration options for the Toggle instance
+ * @returns A function that wraps a component with ToggleProvider
+ *
+ * @example
+ * ```tsx
+ * export default withToggleProvider({
+ *   publicApiKey: "public_...",
+ *   applicationId: "my-app",
+ *   environment: "production",
+ *   defaultContext: {
+ *     user: { id: "user-123" }
+ *   }
+ * })(App);
+ * ```
+ */
+declare function withToggleProvider(options: ToggleOptions): <P extends object>(Component: ComponentType<P>) => ComponentType<P>;
+
+export { ToggleContext, ToggleProvider, type ToggleProviderProps, useToggle, withToggleProvider };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { ToggleOptions, Toggle } from '@hyphen/browser-sdk';
+export { Toggle, ToggleOptions } from '@hyphen/browser-sdk';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, Context, ComponentType } from 'react';
+
+/**
+ * Props for the ToggleProvider component
+ * Extends ToggleOptions from @hyphen/browser-sdk
+ */
+interface ToggleProviderProps extends ToggleOptions {
+    /**
+     * React children to be wrapped by the provider
+     */
+    children: ReactNode;
+}
+
+/**
+ * React Context for the Toggle instance
+ */
+declare const ToggleContext: Context<Toggle | null>;
+/**
+ * Provider component that creates and provides a Toggle instance to the React tree
+ *
+ * @example
+ * ```tsx
+ * <ToggleProvider publicApiKey="public_..." applicationId="my-app">
+ *   <App />
+ * </ToggleProvider>
+ * ```
+ */
+declare function ToggleProvider({ children, publicApiKey, applicationId, environment, defaultContext, horizonUrls, defaultTargetKey, }: ToggleProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Hook to access the Toggle instance from the ToggleProvider
+ *
+ * @throws {Error} If used outside of a ToggleProvider
+ * @returns {Toggle} The Toggle instance from the provider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const toggle = useToggle();
+ *   const isEnabled = toggle.getBoolean('my-feature', false);
+ *
+ *   return <div>{isEnabled ? 'Feature enabled' : 'Feature disabled'}</div>;
+ * }
+ * ```
+ */
+declare function useToggle(): Toggle;
+
+/**
+ * Higher-order component that wraps a component with ToggleProvider
+ *
+ * @param options - Configuration options for the Toggle instance
+ * @returns A function that wraps a component with ToggleProvider
+ *
+ * @example
+ * ```tsx
+ * export default withToggleProvider({
+ *   publicApiKey: "public_...",
+ *   applicationId: "my-app",
+ *   environment: "production",
+ *   defaultContext: {
+ *     user: { id: "user-123" }
+ *   }
+ * })(App);
+ * ```
+ */
+declare function withToggleProvider(options: ToggleOptions): <P extends object>(Component: ComponentType<P>) => ComponentType<P>;
+
+export { ToggleContext, ToggleProvider, type ToggleProviderProps, useToggle, withToggleProvider };

package/dist/index.js

@@ -0,0 +1,71 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+import { Toggle as Toggle2 } from "@hyphen/browser-sdk";
+
+// src/toggle-provider.tsx
+import { createContext, useMemo, useEffect } from "react";
+import { Toggle } from "@hyphen/browser-sdk";
+var ToggleContext = /* @__PURE__ */ createContext(null);
+function ToggleProvider({ children, publicApiKey, applicationId, environment, defaultContext, horizonUrls, defaultTargetKey }) {
+  const toggle = useMemo(() => {
+    return new Toggle({
+      publicApiKey,
+      applicationId,
+      environment,
+      defaultContext,
+      horizonUrls,
+      defaultTargetKey
+    });
+  }, [
+    publicApiKey,
+    applicationId,
+    environment,
+    defaultContext,
+    horizonUrls,
+    defaultTargetKey
+  ]);
+  useEffect(() => {
+    return () => {
+    };
+  }, [
+    toggle
+  ]);
+  return /* @__PURE__ */ React.createElement(ToggleContext.Provider, {
+    value: toggle
+  }, children);
+}
+__name(ToggleProvider, "ToggleProvider");
+
+// src/use-toggle.tsx
+import { useContext } from "react";
+function useToggle() {
+  const toggle = useContext(ToggleContext);
+  if (!toggle) {
+    throw new Error("useToggle must be used within a ToggleProvider. Wrap your component tree with <ToggleProvider> or use withToggleProvider().");
+  }
+  return toggle;
+}
+__name(useToggle, "useToggle");
+
+// src/with-toggle-provider.tsx
+function withToggleProvider(options) {
+  return function(Component) {
+    const WrappedComponent = /* @__PURE__ */ __name((props) => {
+      return /* @__PURE__ */ React.createElement(ToggleProvider, options, /* @__PURE__ */ React.createElement(Component, props));
+    }, "WrappedComponent");
+    const componentName = Component.displayName || Component.name || "Component";
+    WrappedComponent.displayName = `withToggleProvider(${componentName})`;
+    return WrappedComponent;
+  };
+}
+__name(withToggleProvider, "withToggleProvider");
+export {
+  Toggle2 as Toggle,
+  ToggleContext,
+  ToggleProvider,
+  useToggle,
+  withToggleProvider
+};
+/* v8 ignore next -- @preserve */

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@hyphen/react-sdk",
+  "version": "0.5.0",
+  "description": "Hyphen SDK for React",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "hyphen",
+    "sdk",
+    "browser",
+    "react",
+    "javascript",
+    "typescript"
+  ],
+  "author": "Team Hyphen <hello@hyphen.ai>",
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.5",
+    "@faker-js/faker": "^10.1.0",
+    "@swc/core": "^1.15.2",
+    "@testing-library/react": "^16.0.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^18.3.18",
+    "@vitest/coverage-v8": "^4.0.9",
+    "dotenv": "^17.2.3",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.1.0",
+    "tsd": "^0.33.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.9"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@hyphen/browser-sdk": "^1.0.3",
+    "hookified": "^1.13.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
+  "scripts": {
+    "lint": "biome check --write --error-on-warnings",
+    "test": "pnpm lint && vitest run --coverage",
+    "test:ci": "biome check --error-on-warnings && vitest run --coverage",
+    "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts",
+    "clean": "rimraf ./dist pnpm-lock.yaml node_modules coverage"
+  }
+}