@jsontech/react 0.0.6 → 0.0.7

package/README.md

@@ -0,0 +1,158 @@
+# @jsontech/react
+
+React hooks and provider for ShipIt feature flags.
+
+## Installation
+
+```bash
+npm install @jsontech/react
+# or
+pnpm add @jsontech/react
+# or
+yarn add @jsontech/react
+```
+
+**Peer Dependencies:**
+
+- `react >= 18`
+- `react-dom >= 18`
+
+## Usage
+
+### Setup Provider
+
+Wrap your app with `ShipItProvider`:
+
+```typescript
+import { ShipItProvider } from '@jsontech/react';
+
+export function App() {
+  return (
+    <ShipItProvider
+      config={{
+        // SDK automatically uses window.location.origin in browser
+        sdkKey: 'shipit_cli_...' // Client key for browser
+      }}
+      initialUser={{ id: 'user-123' }}
+    >
+      {/* Your app */}
+    </ShipItProvider>
+  );
+}
+```
+
+### Read Flags
+
+Use the `useBoolFlag` hook to read boolean flags:
+
+```typescript
+import { useBoolFlag } from '@jsontech/react';
+
+export function NewNav() {
+  const { value, loading, error } = useBoolFlag('new-nav', false);
+  
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return value ? <div>New nav ON</div> : <div>New nav OFF</div>;
+}
+```
+
+### Update User
+
+Use the `useShipItUser` hook to get and update the current user:
+
+```typescript
+import { useShipItUser } from '@jsontech/react';
+
+export function UserSwitcher() {
+  const [user, setUser] = useShipItUser();
+
+  return (
+    <button
+      onClick={() =>
+        setUser({
+          ...(user ?? { id: 'user-123' }),
+          meta: { ...(user?.meta ?? {}), companyId: 'northwind' }
+        })
+      }
+    >
+      Switch user
+    </button>
+  );
+}
+```
+
+## API Reference
+
+### `ShipItProvider`
+
+Provider component that wraps your app and provides the ShipIt client context.
+
+#### Props
+
+- `config: ShipItReactConfig` - Configuration object
+  - `sdkKey?: string` - Client SDK key (recommended). If not provided, reads from `SHIPIT_CLIENT_KEY` env var.
+  - `projectKey?: string` - Legacy: project key (requires `envKey`). Not recommended.
+  - `envKey?: string` - Environment key (default: `'production'`). Only used with `projectKey`.
+- `initialUser: ShipItUserPayload` - Initial user payload
+- `user?: ShipItUserPayload` - Controlled user (requires `onUserChange`)
+- `onUserChange?: (user: ShipItUserPayload) => void` - Callback for user changes (required if using controlled `user`)
+- `children: React.ReactNode` - Your app components
+
+### `useBoolFlag(flagKey: string, defaultValue: boolean)`
+
+Hook to evaluate a boolean feature flag.
+
+**Returns:**
+
+- `value: boolean` - The flag value
+- `loading: boolean` - Whether the evaluation is in progress
+- `error: Error | null` - Error if evaluation failed
+
+**Example:**
+
+```typescript
+const { value, loading, error } = useBoolFlag('feature-flag', false);
+```
+
+### `useShipItUser()`
+
+Hook to get and update the current user.
+
+**Returns:**
+
+`[user: ShipItUserPayload | null, setUser: (user: ShipItUserPayload) => void]`
+
+**Example:**
+
+```typescript
+const [user, setUser] = useShipItUser();
+```
+
+## Environment Variables
+
+The SDK automatically reads from environment variables if `sdkKey` is not provided:
+
+- `SHIPIT_CLIENT_KEY` - Client SDK key
+
+```typescript
+// This will use SHIPIT_CLIENT_KEY from env if sdkKey is not provided
+<ShipItProvider config={{}} initialUser={{ id: 'user-123' }}>
+  {/* ... */}
+</ShipItProvider>
+```
+
+## API Base URL
+
+The SDK automatically uses `window.location.origin` in the browser (assumes API is on same origin). The API URL cannot be overridden.
+
+## SDK Keys
+
+Use **client keys** (`shipit_cli_...`) for browser/mobile applications. Client keys are not secret and will be visible in your JavaScript bundle.
+
+Get your SDK keys from the ShipIt Console → Environments.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsontech/react",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "sideEffects": false,
   "scripts": {
@@ -32,7 +33,7 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@jsontech/sdk-js": "0.0.6"
+    "@jsontech/sdk-js": "0.0.7"
   },
   "devDependencies": {
     "@types/react": "^18.3.12",