{"_id":"@allowancejs/sdk","_rev":"5-fd68c79c00dab0b8f1b9d3d6e6b87e96","name":"@allowancejs/sdk","dist-tags":{"latest":"0.4.0"},"versions":{"0.2.0":{"name":"@allowancejs/sdk","version":"0.2.0","_id":"@allowancejs/sdk@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":"875fda93e69de194dfee5ce290aa47ffac46c69e","tarball":"https://registry.npmjs.org/@allowancejs/sdk/-/sdk-0.2.0.tgz","fileCount":21,"integrity":"sha512-CIh9OcGm2/r4WKoha/BCy/nQ7kgbcrgqcetGEPBdDGlk40NVnchpPtEPLUZpqH2wp42jWDPWwSAyQHEJaTxMdw==","signatures":[{"sig":"MEUCIFUt/86n3kq2BDEt/SyGVKQaBey/ny0/zyD+dSN4PFcWAiEAlBkPkipxkvQtXgzgmUn/o/WhXkVBU/wPwvVWc5Sy/Ls=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":769897},"main":"./dist/allowancejs-sdk.es.js","type":"module","types":"./dist/types/index.d.ts","module":"./dist/allowancejs-sdk.es.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/allowancejs-sdk.es.js","development":"./src/index.ts"}},"gitHead":"3c6a789d2473f4a5a207dd55c94539828d17bc0f","scripts":{"test":"vitest run","build":"vite 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/sdk"},"_npmVersion":"11.11.1","description":"AllowanceJS browser SDK: init, shared Hub, and style-isolated <allowancejs-coin> / <allowancejs-bar> / <allowancejs-guard> web components (Lit + Shadow DOM), plus headless Tab, Ledger, and Receipt data objects for custom UI.","directories":{},"_nodeVersion":"25.8.2","dependencies":{"lit":"^3.2.0","@allowancejs/api-client":"0.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.0.16","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1781641601460_0.2547663539216525","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@allowancejs/sdk","version":"0.3.0","_id":"@allowancejs/sdk@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":"29aaca72acec242fc9384d95007ea7a0d60fcd1e","tarball":"https://registry.npmjs.org/@allowancejs/sdk/-/sdk-0.3.0.tgz","fileCount":22,"integrity":"sha512-ArlaNDknE3G6n8j77RyYO3P8yMb5/riPcvh+1uGn/n9i5zvBSNunh1doeXtz1yFj7qFzxc1DyRdizU6aWjWwEA==","signatures":[{"sig":"MEYCIQDJEmDgdGbRhhipNAT7BVUJdy72bw4CSd8lHCzZ3WtQkQIhAPZmaD9BNph+rIdHyQo1DoaDF19TtA4RwS00FyPw9YQ7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":760503},"main":"./dist/allowancejs-sdk.es.js","type":"module","types":"./dist/types/index.d.ts","module":"./dist/allowancejs-sdk.es.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/allowancejs-sdk.es.js","development":"./src/index.ts"}},"gitHead":"71f647aebd7ec1b486449d7e9f8553c883666575","scripts":{"test":"vitest run","build":"vite 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:a2cd07d9-7395-41fa-8c89-1ee96c2bd75b"}},"repository":{"url":"git+https://github.com/withallowance/platform.git","type":"git","directory":"frontend/packages/sdk"},"_npmVersion":"11.17.0","description":"AllowanceJS browser SDK: init, shared Hub, and style-isolated <allowancejs-coin> / <allowancejs-bar> / <allowancejs-guard> web components (Lit + Shadow DOM), plus headless Tab, Ledger, and Receipt data objects for custom UI.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"lit":"^3.2.0","@allowancejs/api-client":"0.3.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.0.16","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.3.0_1782321689098_0.21349772031326975","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@allowancejs/sdk","version":"0.4.0","description":"AllowanceJS browser SDK: init, shared Hub, and style-isolated <allowancejs-coin> / <allowancejs-bar> / <allowancejs-guard> web components (Lit + Shadow DOM), plus headless Tab, Ledger, and Receipt data objects for custom UI.","type":"module","main":"./dist/allowancejs-sdk.es.js","module":"./dist/allowancejs-sdk.es.js","types":"./dist/types/index.d.ts","exports":{".":{"development":"./src/index.ts","types":"./dist/types/index.d.ts","import":"./dist/allowancejs-sdk.es.js"}},"scripts":{"build":"vite build && tsc --project tsconfig.build.json","clean":"rm -rf dist","prepublishOnly":"npm run build","typecheck":"tsc --noEmit","test":"vitest run"},"dependencies":{"@allowancejs/api-client":"0.4.0","lit":"^3.2.0"},"devDependencies":{"typescript":"^6.0.3","vite":"^8.0.16"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/withallowance/platform.git","directory":"frontend/packages/sdk"},"gitHead":"7a079baf304623ce861732363259125c695beaee","_id":"@allowancejs/sdk@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-k7ktFV4teXpA1+hCWa0Mh2+m0Ii6wKZJIx1gN299foOYnhXjfy6msmRu34XJ514DCQXGMlJb2fr92xZ1FAjhaw==","shasum":"ab6bae12fadaee6098082b2b1c2435693db578ad","tarball":"https://registry.npmjs.org/@allowancejs/sdk/-/sdk-0.4.0.tgz","fileCount":21,"unpackedSize":688871,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICKh2MNHMkqz6ryDZHqNJbkGkBZdiSLRsnXwd2yLNC/1AiBBd3kyxqN/3FfgH56JwmX1RtCpKyY/bsWtXwIPudnzHA=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:a2cd07d9-7395-41fa-8c89-1ee96c2bd75b"}},"directories":{},"maintainers":[{"name":"ptiger10","email":"dhfort@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.4.0_1782351615792_0.3816621007042027"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-16T20:26:41.240Z","modified":"2026-06-25T01:40:16.084Z","0.1.0":"2026-06-11T06:25:28.331Z","0.2.0":"2026-06-16T20:26:41.652Z","0.3.0":"2026-06-24T17:21:29.240Z","0.4.0":"2026-06-25T01:40:15.977Z"},"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/sdk"},"description":"AllowanceJS browser SDK: init, shared Hub, and style-isolated <allowancejs-coin> / <allowancejs-bar> / <allowancejs-guard> web components (Lit + Shadow DOM), plus headless Tab, Ledger, and Receipt data objects for custom UI.","maintainers":[{"name":"ptiger10","email":"dhfort@gmail.com"}],"readme":"# @allowancejs/sdk\n\nAllowanceJS browser SDK — drop-in token budget widgets and a headless balance surface.\n\nBundles `AllowanceJS.init()`, a shared polling Hub, style-isolated Lit/Shadow DOM web components (`<allowancejs-coin>`, `<allowancejs-bar>`, `<allowancejs-guard>`), and headless Allowance and Ledger data objects for custom UI.\n\n## Install\n\n```bash\nnpm install @allowancejs/sdk\n```\n\nOr via CDN (standalone UMD bundle):\n\n```html\n<script src=\"https://unpkg.com/@allowancejs/sdk/dist/allowancejs-sdk.umd.js\"></script>\n```\n\n## Quick start\n\n```ts\nimport { AllowanceJS } from \"@allowancejs/sdk\";\n\nconst allowance = await AllowanceJS.init({\n  baseUrl: \"https://api.example.com\",\n  // A short-lived, READ-ONLY JWT minted by your app's backend (the SDK only ever\n  // reads balances — it can never spend, grant, or change policy). Called on each\n  // poll / request, so return a fresh token as the old one expires.\n  getToken: async () => getSessionJwt(),\n});\n```\n\n`init()` is idempotent — call it once at page load. It returns the same instance on repeated calls.\n\n## Web components\n\nAfter `init()`, drop any widget into your markup:\n\n```html\n<!-- Glanceable budget ring: a status ring plus a hover/focus tooltip -->\n<allowancejs-coin></allowancejs-coin>\n\n<!-- The same glanceable meter as a slim inline horizontal bar -->\n<allowancejs-bar></allowancejs-bar>\n\n<!-- Gate an action on remaining budget: greys out + blocks the button when unavailable -->\n<allowancejs-guard feature=\"summarize\">\n  <button>Summarize</button>\n</allowancejs-guard>\n```\n\nThe coin and bar are **glanceable indicators only** — a status ring/strip with a\nhover/focus tooltip. They are not clickable and open no panel. For a full\nbreakdown, history, or a \"request more\" affordance, drive your own UI from the\nheadless data API below (and the raw DOM events).\n\n### Multiple allowances\n\nA user can hold several allowances at once — per unit and with arbitrary windows\n(e.g. *1,000 credits / 5h* **and** *10,000 / 7d*). `getBalance` returns\n`balances[]`, one per allowance. Bind a surface to a specific one with the\n**`allowance`** attribute (its id or label); omit it to track the **primary**\n(first) balance. A guard with no `allowance` gates on **any** breached window.\n\n```html\n<allowancejs-coin allowance=\"Every 5 hours\"></allowancejs-coin>\n<allowancejs-bar allowance=\"Daily\"></allowancejs-bar>\n```\n\n## Headless usage\n\nUse the data objects to drive your own UI instead of (or alongside) the shipped components:\n\n```ts\nimport { AllowanceJS, subscribeAllowance, fetchLedger } from \"@allowancejs/sdk\";\n\nconst instance = await AllowanceJS.init({ ... });\n\n// Live glanceable summary — updates on every poll\nsubscribeAllowance(instance, (a) => {\n  console.log(a.pctUsed, a.tone, a.consumedUnits, a.remainingUnits, a.resetsAt);\n});\n\n// Full period breakdown on demand\nconst ledger = await fetchLedger(instance);\nledger.lines.forEach((line) => console.log(line.feature, line.spent));\n```\n\n### Account access suspension (\"AI off, app on\")\n\nWhen a customer admin turns a user's app access off, every `<allowancejs-guard>`\nalready blocks its action and shows the admin's message. To avoid a wall of\ngreyed-out buttons, render **one** app-level notice from the same summary — and\nleave the rest of your app running. The flag rides the balance you already poll\n(no extra request):\n\n```ts\nsubscribeAllowance(instance, (a) => {\n  if (a.accessSuspended) {\n    showBanner(a.accessMessage || \"AI features are paused for your account.\");\n  } else {\n    hideBanner();\n  }\n});\n```\n\nThis is the \"happy medium\": the user stays signed in and can use the rest of the\napp; only the token-consuming features are blocked. A hard lockout (no login at\nall) is your IdP's job — wire it off the signed `user.suspended` webhook if you\nwant it.\n\n## Appearance\n\n```ts\nAllowanceJS.init({\n  ...\n  appearance: {\n    theme: \"dark\",                          // \"light\" | \"dark\"\n    variables: { \"--aljs-accent\": \"#6366f1\" },\n  },\n});\n```\n\nCSS custom properties pierce Shadow DOM so widgets inherit your brand colours without any extra setup.\n\n## Events\n\nThe SDK dispatches its widget events as raw `allowancejs:*` DOM `CustomEvent`s on\n`window` — listen for them with `window.addEventListener` to drive your own\nnotifications. There is no JS event-callback or emitter (no `onEvent`, `on`,\n`off`, or `onAny`); the DOM events are the whole event surface.\n\nThe forwarded event types are `threshold_crossed`, `limit_reached`, and `error`.\nUse the `domEventName` helper (or just prefix with `allowancejs:`) to build the\nlistener name:\n\n```ts\nimport { domEventName } from \"@allowancejs/sdk\";\n\nwindow.addEventListener(domEventName(\"threshold_crossed\"), (e) => {\n  console.log(\"threshold crossed\", e.detail);\n});\n```\n\n## Key exports\n\n`AllowanceJS`, `init`, `Hub`, `HubController`, `buildAllowance`, `subscribeAllowance`, `allowanceOf`, `allowancesOf`, `selectBalance`, `accessOf`, `buildLedger`, `fetchLedger`, `AllowanceJSCoin`, `AllowanceJSBar`, `AllowanceJSGuard`, `SDK_VERSION`, `SUPPORTED_LOCALES` — plus all `InitOptions`, `Allowance`, `AccessStanding`, `Ledger`, `Appearance`, and event types.\n","readmeFilename":"README.md"}