{"_id":"@ashhforrd/feature-flags-js","name":"@ashhforrd/feature-flags-js","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ashhforrd/feature-flags-js","version":"0.1.0","description":"JavaScript SDK for evaluating feature flags and recording experiment conversions.","type":"module","main":"src/index.js","exports":{".":"./src/index.js"},"scripts":{"test":"node --test"},"keywords":["feature-flags","feature-toggle","experimentation","ab-testing","sdk"],"author":{"name":"ashhforrd"},"license":"MIT","publishConfig":{"access":"public"},"gitHead":"9e296b49e8f48ffba70a421cbf4fd70514679a8a","_id":"@ashhforrd/feature-flags-js@0.1.0","_nodeVersion":"22.20.0","_npmVersion":"11.6.3","dist":{"integrity":"sha512-dxOGz3kTiQxpPeg9JzDZ017Oy591+QSpOXsiYLtqOEZIgdVsYKB32LQgoAerjhgqrh24fepOpwfKr9MvKLpIXA==","shasum":"006462d29d05b27bda6297f7d126b0a0e0549b5a","tarball":"https://registry.npmjs.org/@ashhforrd/feature-flags-js/-/feature-flags-js-0.1.0.tgz","fileCount":3,"unpackedSize":5529,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIG8CMYmiqmWGw9dSCowU00rultFMHNcUMktcRXywMHEFAiAF/LP1fCxtqr/xzL+9vSLo1CtXVRRxy8kCTY8TpVFmYQ=="}]},"_npmUser":{"name":"ashhforrd","email":"atqiyahaydar15@gmail.com"},"directories":{},"maintainers":[{"name":"ashhforrd","email":"atqiyahaydar15@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/feature-flags-js_0.1.0_1783497642630_0.6480296163753321"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-08T08:00:42.482Z","0.1.0":"2026-07-08T08:00:42.811Z","modified":"2026-07-08T08:00:43.014Z"},"maintainers":[{"name":"ashhforrd","email":"atqiyahaydar15@gmail.com"}],"description":"JavaScript SDK for evaluating feature flags and recording experiment conversions.","keywords":["feature-flags","feature-toggle","experimentation","ab-testing","sdk"],"author":{"name":"ashhforrd"},"license":"MIT","readme":"# Feature Flags JavaScript SDK\n\nJavaScript SDK for evaluating feature flags and recording conversion events against the Feature Flag Platform config service.\n\nUse this package inside an application when you want to ask the platform whether a feature should be enabled for a specific user.\n\n## Install\n\n```sh\nnpm install @ashhforrd/feature-flags-js\n```\n\nFor local development inside this monorepo, the demo app imports the SDK directly from `packages/js-sdk/src/index.js`.\n\n## Quick Start\n\n```js\nimport { FeatureFlagClient } from \"@ashhforrd/feature-flags-js\"\n\nconst client = new FeatureFlagClient({\n  baseUrl: \"http://localhost:8080\"\n})\n\nconst user = {\n  id: \"user-123\",\n  attributes: {\n    country: \"ID\",\n    email: \"alice@example.com\"\n  }\n}\n\nconst enabled = await client.isEnabled(\"new-checkout\", user, false)\n\nif (enabled) {\n  // Show the new feature.\n} else {\n  // Show the existing experience.\n}\n```\n\n## Evaluate a Flag\n\nUse `evaluate` when the app needs the full decision response, including the reason and rollout metadata.\n\n```js\nconst result = await client.evaluate(\"new-checkout\", user, false)\n\nconsole.log(result.enabled)\nconsole.log(result.reason)\n```\n\nExample response:\n\n```json\n{\n  \"flagKey\": \"new-checkout\",\n  \"enabled\": true,\n  \"reason\": \"PERCENTAGE_ROLLOUT\",\n  \"bucket\": 42,\n  \"rolloutPercentage\": 50\n}\n```\n\n## Boolean Helper\n\nUse `isEnabled` when the app only needs `true` or `false`.\n\n```js\nconst enabled = await client.isEnabled(\"new-checkout\", user, false)\n```\n\n## Record a Conversion\n\nUse `recordConversion` after the user completes the business action being measured.\n\n```js\nconst recorded = await client.recordConversion(\n  \"new-checkout\",\n  \"user-123\",\n  \"checkout_completed\"\n)\n```\n\nIt returns `true` when the config service records the event successfully. It returns `false` if the request fails.\n\n## Fail-Safe Behavior\n\nFeature flag SDKs should not crash product experiences when the flag service is unavailable.\n\nIf `evaluate` fails because of a network error or non-OK response, it returns the caller-provided default value:\n\n```js\nconst result = await client.evaluate(\"new-checkout\", user, false)\n```\n\nFallback response:\n\n```json\n{\n  \"flagKey\": \"new-checkout\",\n  \"enabled\": false,\n  \"reason\": \"SDK_REQUEST_FAILED\"\n}\n```\n\n`recordConversion` is also fail-safe. It returns `false` instead of throwing.\n\n## API Reference\n\n### `new FeatureFlagClient(options)`\n\nCreates a client.\n\n```js\nconst client = new FeatureFlagClient({\n  baseUrl: \"http://localhost:8080\"\n})\n```\n\nOptions:\n\n- `baseUrl`: config service base URL. Required.\n\n### `client.evaluate(flagKey, user, defaultValue)`\n\nReturns the full evaluation response from the config service.\n\nParameters:\n\n- `flagKey`: unique flag key, for example `new-checkout`.\n- `user`: user object with `id` and optional `attributes`.\n- `defaultValue`: value to return when the flag service cannot make a decision.\n\n### `client.isEnabled(flagKey, user, defaultValue)`\n\nReturns only the boolean decision.\n\n### `client.recordConversion(flagKey, userId, eventName)`\n\nRecords a conversion event for experiment results.\n\nParameters:\n\n- `flagKey`: unique flag key.\n- `userId`: user identifier.\n- `eventName`: conversion event name, for example `checkout_completed`.\n\n## Backend Requirement\n\nThis SDK expects the config service to expose these endpoints:\n\n- `POST /flags/{key}/evaluate`\n- `POST /flags/{key}/conversions`\n\n## Development\n\nRun tests from `packages/js-sdk`:\n\n```sh\nnpm test\n```\n\nCheck the package contents before publishing:\n\n```sh\nnpm pack --dry-run\n```\n","readmeFilename":"README.md","_rev":"1-48698edfda32074fb295b9d5f17495c9"}