{"_id":"@allowancejs/react","_rev":"5-be0b388249a2662b48990b80dbb67294","name":"@allowancejs/react","dist-tags":{"latest":"0.4.0"},"versions":{"0.2.0":{"name":"@allowancejs/react","version":"0.2.0","_id":"@allowancejs/react@0.2.0","maintainers":[{"name":"ptiger10","email":"dhfort@gmail.com"}],"homepage":"https://github.com/withallowance/platform#readme","bugs":{"url":"https://github.com/withallowance/platform/issues"},"dist":{"shasum":"8f61dd4219ab27aa8ba8760eb3f31d0e2def68d5","tarball":"https://registry.npmjs.org/@allowancejs/react/-/react-0.2.0.tgz","fileCount":14,"integrity":"sha512-Br2WofJ33gxk/HNs5dtJF4QjyuUiHM6iqrMrVxtzWHDgvBw1I6pzNjDp5HJXoyYBkaw362EriH59whxuqjhvVA==","signatures":[{"sig":"MEQCIDbP+15zVIrhDP96RmmNCpZirUhP7jOAEJc2jv3ALFpjAiAYff+N3RQb6COsZgpVQ0rCIUwYfhQc/cNCbk0TZpWA2Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27488},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","development":"./src/index.ts"}},"gitHead":"3c6a789d2473f4a5a207dd55c94539828d17bc0f","scripts":{"test":"vitest run","build":"tsc --project tsconfig.build.json","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"ptiger10","email":"dhfort@gmail.com"},"repository":{"url":"git+https://github.com/withallowance/platform.git","type":"git","directory":"frontend/packages/react"},"_npmVersion":"11.11.1","description":"React bindings for the AllowanceJS SDK: owning the instance lifecycle, typed // wrappers over the web components, and hooks (useTab, useLedger, useReceipt, useAllowanceEvent) over the headle","directories":{},"sideEffects":false,"_nodeVersion":"25.8.2","dependencies":{"@lit/react":"^1.0.8","@allowancejs/sdk":"0.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"react":"^19.2.7","react-dom":"^19.2.7","typescript":"^6.0.3","@types/react":"^19.2.17","@types/react-dom":"^19.2.3","@allowancejs/api-client":"0.2.0"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/react_0.2.0_1781641585325_0.7775459034343453","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@allowancejs/react","version":"0.3.0","_id":"@allowancejs/react@0.3.0","maintainers":[{"name":"ptiger10","email":"dhfort@gmail.com"}],"homepage":"https://github.com/withallowance/platform#readme","bugs":{"url":"https://github.com/withallowance/platform/issues"},"dist":{"shasum":"5b6ba93fc4437726762543298d649be82e31d4b1","tarball":"https://registry.npmjs.org/@allowancejs/react/-/react-0.3.0.tgz","fileCount":17,"integrity":"sha512-+OC34yx9/f8ukPlQqVYMrDxf4jtwyb8QUCRdkKUjw8sfdhi4hoErORNWsKoKPpCntGSdjuBdwSHNzBXefLcWEA==","signatures":[{"sig":"MEYCIQDtOGVLyVaPb/mALFzZ9oqNraP7fo/PBAn0coiBkDnrBgIhAJo5x6WaJ73XUl1cT9pwpSMn9kbyjF3ptoWRNPLsvVBo","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38978},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","development":"./src/index.ts"}},"gitHead":"71f647aebd7ec1b486449d7e9f8553c883666575","scripts":{"test":"vitest run","build":"tsc --project tsconfig.build.json","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:afce8e4d-c490-47b0-b085-faa7147f938a"}},"repository":{"url":"git+https://github.com/withallowance/platform.git","type":"git","directory":"frontend/packages/react"},"_npmVersion":"11.17.0","description":"React bindings for the AllowanceJS SDK: owning the instance lifecycle, typed // wrappers over the web components, and hooks (useBalance, useFeatureBreakdown, useReceipt, useAllowanceEvent) o","directories":{},"sideEffects":false,"_nodeVersion":"22.22.3","dependencies":{"@lit/react":"^1.0.8","@allowancejs/sdk":"0.3.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"react":"^19.2.7","react-dom":"^19.2.7","typescript":"^6.0.3","@types/react":"^19.2.17","@types/react-dom":"^19.2.3","@allowancejs/api-client":"0.3.0"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/react_0.3.0_1782321688378_0.5331321246963927","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@allowancejs/react","version":"0.4.0","description":"React bindings for the AllowanceJS SDK: owning the instance lifecycle, typed // wrappers over the web components, and hooks (useBalance, useFeatureBreakdown, useReceipt, useAllowanceEvent) o","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"development":"./src/index.ts","types":"./dist/index.d.ts","import":"./dist/index.js"}},"sideEffects":false,"scripts":{"build":"tsc --project tsconfig.build.json","clean":"rm -rf dist","prepublishOnly":"npm run build","typecheck":"tsc --noEmit","test":"vitest run"},"dependencies":{"@allowancejs/sdk":"0.4.0","@lit/react":"^1.0.8"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0"},"devDependencies":{"@allowancejs/api-client":"0.4.0","@types/react":"^19.2.17","@types/react-dom":"^19.2.3","react":"^19.2.7","react-dom":"^19.2.7","typescript":"^6.0.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/withallowance/platform.git","directory":"frontend/packages/react"},"gitHead":"7a079baf304623ce861732363259125c695beaee","_id":"@allowancejs/react@0.4.0","bugs":{"url":"https://github.com/withallowance/platform/issues"},"homepage":"https://github.com/withallowance/platform#readme","_nodeVersion":"22.23.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-TQK5gZ42A0hMc/ZlpCneRCnASKAhHUE1fcrlWk55XG3mGZ3PdlKgmgoVvka5wWn8ICqyUtb4JfLm5LK9I5qw+A==","shasum":"06eb6cb19dfaf49eecbaf40202ce7b19a4742556","tarball":"https://registry.npmjs.org/@allowancejs/react/-/react-0.4.0.tgz","fileCount":17,"unpackedSize":37362,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCcQjj7cZp2zBB47Ri72GMjmc9yi14F+fw7oeNSGvsLlgIhAISoL33gbqd+t9RTpIYm7MCQBzX+4J9OdTlW1/uS/FOX"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:afce8e4d-c490-47b0-b085-faa7147f938a"}},"directories":{},"maintainers":[{"name":"ptiger10","email":"dhfort@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/react_0.4.0_1782351615584_0.8995016486080281"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-16T20:26:25.062Z","modified":"2026-06-25T01:40:15.868Z","0.1.0":"2026-06-11T06:25:14.075Z","0.2.0":"2026-06-16T20:26:25.473Z","0.3.0":"2026-06-24T17:21:28.531Z","0.4.0":"2026-06-25T01:40:15.737Z"},"bugs":{"url":"https://github.com/withallowance/platform/issues"},"homepage":"https://github.com/withallowance/platform#readme","repository":{"type":"git","url":"git+https://github.com/withallowance/platform.git","directory":"frontend/packages/react"},"description":"React bindings for the AllowanceJS SDK: owning the instance lifecycle, typed // wrappers over the web components, and hooks (useBalance, useFeatureBreakdown, useReceipt, useAllowanceEvent) o","maintainers":[{"name":"ptiger10","email":"dhfort@gmail.com"}],"readme":"# @allowancejs/react\n\nReact bindings for the AllowanceJS SDK.\n\nThree layers: `` owns the page-singleton instance lifecycle; ``, ``, and `` are typed JSX wrappers around the web components (the coin and bar are glanceable indicators; the guard gates an action by greying out + blocking the button when it's unavailable); and `useAllowance`, `useAllowances`, `useFeatureBreakdown`, and `useAllowanceClient` expose the headless data surface as React hooks — render your own detail UI from them. Two more hooks — `useMemberPortal` and `useCustomerPortal` — launch the hosted self-service and governance portals from anywhere in the host's own UI.\n\n## Install\n\n```bash\nnpm install @allowancejs/react @allowancejs/sdk\n```\n\nPeer dependency: `react ^18 || ^19`.\n\n## Setup\n\nWrap your app (or the subtree that uses balance UI) with ``:\n\n```tsx\nimport { AllowanceProvider } from \"@allowancejs/react\";\n\nexport function App() {\n return (\n getSessionJwt(),\n }}\n >\n \n \n );\n}\n```\n\nIf your boot code calls `AllowanceJS.init()` directly, pass the instance instead:\n\n```tsx\n...\n```\n\n## Components\n\n```tsx\nimport { AllowanceCoin, AllowanceBar, AllowanceGuard } from \"@allowancejs/react\";\n\nfunction BalancePanel() {\n return (\n <>\n \n \n \n \n \n \n );\n}\n```\n\n## Hooks\n\n```tsx\nimport { useAllowance, useFeatureBreakdown } from \"@allowancejs/react\";\n\n// Live glanceable summary\nfunction BalanceSummary() {\n const a = useAllowance();\n return (\n \n {a.remainingUnits} remaining ({a.pctUsed}%)\n \n );\n}\n\n// \"AI off, app on\": one app-level notice when the admin has suspended this\n// user's access — the rest of your app keeps rendering; only guarded actions\n// are blocked. The flag rides the balance you already poll.\nfunction AccessBanner() {\n const a = useAllowance();\n if (!a.accessSuspended) return null;\n return
{a.accessMessage || \"AI features are paused for your account.\"}
;\n}\n\n// Full period breakdown\nfunction SpendHistory() {\n const { breakdown, loading, error } = useFeatureBreakdown();\n if (loading) return Loading…;\n if (error) return Error loading breakdown;\n return (\n
    \n {breakdown?.lines.map((l) => (\n
  • {l.feature}: {l.spent}
    • \n ))}\n
\n );\n}\n```\n\n> **Widget events** are dispatched as raw `allowancejs:*` DOM `CustomEvent`s on\n> `window` (e.g. `allowancejs:threshold_crossed`, `allowancejs:limit_reached`).\n> There is no React event hook — listen with `window.addEventListener` (in an\n> effect) when you need them for notifications.\n\n## Portal launchers\n\nDrop a button anywhere in your own UI to open one of the two hosted portals. Both\nmint a single-use link and open it in a new tab; `open()` never rejects — a failed\nmint is surfaced on `error`, so wire it straight to `onClick`.\n\n```tsx\nimport { useMemberPortal, useCustomerPortal } from \"@allowancejs/react\";\n\n// A member's own usage & alerts. Minted client-side with the SDK's read token,\n// so it just works inside — no backend call needed.\nfunction ManageUsageButton() {\n const portal = useMemberPortal();\n return (\n \n );\n}\n\n// The customer-admin governance portal. Minting it is admin-scoped and the SDK\n// never holds an admin token, so YOUR backend mints the link (Portal/CreateSession)\n// and returns it through `resolve`. Needs no .\nfunction ManageTeamButton() {\n const portal = useCustomerPortal({\n resolve: async () => {\n const res = await fetch(\"/api/allowance/admin-portal\", { method: \"POST\" });\n const { url } = await res.json();\n return url;\n },\n });\n return (\n \n );\n}\n```\n\n## Runtime updates\n\n`` diffs `period`, `displayUnit`, `pollMs`, `locale`, and `appearance` on every render and forwards changes to `instance.update()`. Identity-level options (`baseUrl`, `getToken`) are read once at mount; to change them, remount the provider with a new `key`.\n\n## Next.js App Router\n\n`` carries a `\"use client\"` directive and is safe to use in App Router layouts and page components.\n\n## Re-exports\n\nAll SDK types (`InitOptions`, `Allowance`, `Ledger`, `Appearance`, `WidgetEvent`, etc.) and `init`, `AllowanceJS`, `SDK_VERSION`, `compactUsage` are re-exported from this package — a React host needs only one dependency.\n","readmeFilename":"README.md"}