{"_id":"@d3ara1n/pi-usage-block-core","_rev":"8-ad28fa111f671a301c94bb1d925c2113","name":"@d3ara1n/pi-usage-block-core","dist-tags":{"latest":"3.1.1"},"versions":{"1.0.0":{"name":"@d3ara1n/pi-usage-block-core","version":"1.0.0","keywords":["pi-package"],"license":"MIT","_id":"@d3ara1n/pi-usage-block-core@1.0.0","maintainers":[{"name":"d3ara1n","email":"d3ara1n@outlook.com"}],"homepage":"https://github.com/d3ara1n/pi-extensions#readme","bugs":{"url":"https://github.com/d3ara1n/pi-extensions/issues"},"dist":{"shasum":"46cd5c268c5dece04946964a56a60bfb5d02a020","tarball":"https://registry.npmjs.org/@d3ara1n/pi-usage-block-core/-/pi-usage-block-core-1.0.0.tgz","fileCount":2,"integrity":"sha512-n0I8tR6eWcbdkDaX8vbHRdX7SB+HIxWfsQ+Qd0an0tCzAOwqn/CZdlen8omn3sB3JxOiGAIywGXAYKX2gKrw2A==","signatures":[{"sig":"MEYCIQCsbkUCTUGgL7DARWNiteJOp5wWSIN4HU1xqU/RxTvFxQIhAKGn/KlN9In0L5uvOrg1R4xRN0/Be4zoVt9fxv2/7gSy","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2776},"main":"src/index.ts","types":"src/index.ts","gitHead":"5aba0174bd8968739c3cbfe1c8faaf216a5faf0a","_npmUser":{"name":"d3ara1n","email":"d3ara1n@outlook.com"},"repository":{"url":"git+https://github.com/d3ara1n/pi-extensions.git","type":"git","directory":"packages/pi-usage-block-core"},"_npmVersion":"11.16.0","description":"Shared types and registry for pi-usage-block — provider-agnostic usage quota reporting","directories":{},"_nodeVersion":"26.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pi-usage-block-core_1.0.0_1780469426892_0.016147673982860544","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@d3ara1n/pi-usage-block-core","version":"2.0.0","license":"MIT","_id":"@d3ara1n/pi-usage-block-core@2.0.0","maintainers":[{"name":"d3ara1n","email":"d3ara1n@outlook.com"}],"homepage":"https://github.com/d3ara1n/pi-extensions#readme","bugs":{"url":"https://github.com/d3ara1n/pi-extensions/issues"},"dist":{"shasum":"5abc2f293eead25b789150beaad15d441b2174a0","tarball":"https://registry.npmjs.org/@d3ara1n/pi-usage-block-core/-/pi-usage-block-core-2.0.0.tgz","fileCount":3,"integrity":"sha512-lOlZqGQvy+M6Ut2hWNf35CMWqJmPCUZzxP54E0ai79QyTBui7sPlBHLHHWWHwNCYDAVDWZdjAHKCH8wZBJh57Q==","signatures":[{"sig":"MEUCIQCHfiGaC17j2oJ3UuhjWEiUBFDgfTrxE/hshEkNbZRQ9AIgcaWPmvbkgVhVVEF+dusTeORXhm21j9fZK+Z9inG9bbg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":7415},"main":"src/index.ts","types":"src/index.ts","gitHead":"3827019a4a017d304709038e70d073a3088fd7aa","_npmUser":{"name":"d3ara1n","email":"d3ara1n@outlook.com"},"repository":{"url":"git+https://github.com/d3ara1n/pi-extensions.git","type":"git","directory":"packages/pi-usage-block-core"},"_npmVersion":"11.16.0","description":"Shared types and registry for pi-usage-block — provider-agnostic usage quota reporting","directories":{},"_nodeVersion":"26.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pi-usage-block-core_2.0.0_1780473451647_0.421804318732377","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"name":"@d3ara1n/pi-usage-block-core","version":"2.1.0","license":"MIT","_id":"@d3ara1n/pi-usage-block-core@2.1.0","maintainers":[{"name":"d3ara1n","email":"d3ara1n@outlook.com"}],"homepage":"https://github.com/d3ara1n/pi-extensions#readme","bugs":{"url":"https://github.com/d3ara1n/pi-extensions/issues"},"dist":{"shasum":"bf392e9588ca444ffbddb9088c368e45611bb6db","tarball":"https://registry.npmjs.org/@d3ara1n/pi-usage-block-core/-/pi-usage-block-core-2.1.0.tgz","fileCount":3,"integrity":"sha512-Qu419zziTOV2GfCDZr7Jb9L77bxEwq+IxmjisI+bhIMRhw9D/OzP3C587OM9v31gIixwYD/Qf1wlBUPJEPJ0TQ==","signatures":[{"sig":"MEYCIQDoq20naF4gAzw+jcc6AXBXQSrxgKS0uBdfO3cWGR8QNgIhAJCAXs2mD+pr17+VHJmdr+PXh2a7MyTZ2zR4gvvFVfjA","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@d3ara1n%2fpi-usage-block-core@2.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":7415},"main":"src/index.ts","types":"src/index.ts","gitHead":"4e899d9e66b158c8a6f9c0ab867d9f1a826fa68a","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:988cc98f-f4ce-423c-8532-17a76aca20ec"}},"repository":{"url":"git+https://github.com/d3ara1n/pi-extensions.git","type":"git","directory":"packages/pi-usage-block-core"},"_npmVersion":"11.13.0","description":"Shared types and registry for pi-usage-block — provider-agnostic usage quota reporting","directories":{},"_nodeVersion":"24.16.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pi-usage-block-core_2.1.0_1780743998006_0.417891675793046","host":"s3://npm-registry-packages-npm-production"}},"2.1.1":{"name":"@d3ara1n/pi-usage-block-core","version":"2.1.1","license":"MIT","_id":"@d3ara1n/pi-usage-block-core@2.1.1","maintainers":[{"name":"d3ara1n","email":"d3ara1n@outlook.com"}],"homepage":"https://github.com/d3ara1n/pi-extensions#readme","bugs":{"url":"https://github.com/d3ara1n/pi-extensions/issues"},"dist":{"shasum":"27c4a26a5006bd2c671e08c666311f8a7b157e6f","tarball":"https://registry.npmjs.org/@d3ara1n/pi-usage-block-core/-/pi-usage-block-core-2.1.1.tgz","fileCount":3,"integrity":"sha512-1y77JdcZmh5hPGAiLYZQr5hjF66+CnRBBMmvW2SR4EjvITBIrrmgSR2l+52mSe1D0vqaiw2QlDbhE3gsrS4iYQ==","signatures":[{"sig":"MEQCICrNMqLsZF6T5s3rIl3RcZZsut3/DKjrrzASwp47xlBtAiBiaWJ8sdUojN3mteQml3z8vISR2hMC4aM3Up7b8tUFBg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@d3ara1n%2fpi-usage-block-core@2.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":7385},"main":"src/index.ts","type":"module","types":"src/index.ts","gitHead":"b64ec29054d0726977c811c7cede7464f3b9028b","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:988cc98f-f4ce-423c-8532-17a76aca20ec"}},"repository":{"url":"git+https://github.com/d3ara1n/pi-extensions.git","type":"git","directory":"packages/pi-usage-block-core"},"_npmVersion":"11.13.0","description":"Shared types and registry for pi-usage-block — provider-agnostic usage quota reporting","directories":{},"_nodeVersion":"24.16.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pi-usage-block-core_2.1.1_1782228765799_0.004723699424076688","host":"s3://npm-registry-packages-npm-production"}},"2.1.2":{"name":"@d3ara1n/pi-usage-block-core","version":"2.1.2","license":"MIT","_id":"@d3ara1n/pi-usage-block-core@2.1.2","maintainers":[{"name":"d3ara1n","email":"d3ara1n@outlook.com"}],"homepage":"https://github.com/d3ara1n/pi-extensions#readme","bugs":{"url":"https://github.com/d3ara1n/pi-extensions/issues"},"dist":{"shasum":"3fc1ae5f07e248e3956dd6521bceedf6d545117e","tarball":"https://registry.npmjs.org/@d3ara1n/pi-usage-block-core/-/pi-usage-block-core-2.1.2.tgz","fileCount":3,"integrity":"sha512-YfR0CiAtzgJS0gKLjWY0PglFQfn5WwFMrIvT1BUmZqc3dHi33TQNC/ncf2poTUSqDu1zPTQPhkWBka89k4hSqQ==","signatures":[{"sig":"MEYCIQDli3r1/FtGwGMWXSO2WBrWjicwdMtg85zLUZdqxNSBWAIhAK4jzdqWJSMLVdaAmbSyBTzPwMhPQiEfxf2iLxc2Y9zu","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@d3ara1n%2fpi-usage-block-core@2.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":7412},"main":"src/index.ts","type":"module","types":"src/index.ts","gitHead":"58c73768103d4e79a15ca983fb68772ef8731cf8","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:988cc98f-f4ce-423c-8532-17a76aca20ec"}},"repository":{"url":"git+https://github.com/d3ara1n/pi-extensions.git","type":"git","directory":"packages/pi-usage-block-core"},"_npmVersion":"11.16.0","description":"Shared types and registry for pi-usage-block — provider-agnostic usage quota reporting","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pi-usage-block-core_2.1.2_1783661988023_0.24473853878201757","host":"s3://npm-registry-packages-npm-production"}},"3.0.0":{"name":"@d3ara1n/pi-usage-block-core","version":"3.0.0","license":"MIT","_id":"@d3ara1n/pi-usage-block-core@3.0.0","maintainers":[{"name":"d3ara1n","email":"d3ara1n@outlook.com"}],"homepage":"https://github.com/d3ara1n/pi-extensions#readme","bugs":{"url":"https://github.com/d3ara1n/pi-extensions/issues"},"dist":{"shasum":"0ddec0d2441a1d3f474ea940f4ad8fb55752b00a","tarball":"https://registry.npmjs.org/@d3ara1n/pi-usage-block-core/-/pi-usage-block-core-3.0.0.tgz","fileCount":3,"integrity":"sha512-DYjWzFxU5v0wno3xuqeVk3vbNP/7tJ57Ksru1t07WBv2hgOHxAfisxog5PDvzkaFjlSPcFODVFYAWlySqXEQ7g==","signatures":[{"sig":"MEUCIHD7v0DQ3K6leve7c+5XOqlyiPc5+308bO6tgs/u7rWpAiEA9eQjuhbyoc/tFgr5xqS+GKq1sf9yn3RfKkkFvvCrh5c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@d3ara1n%2fpi-usage-block-core@3.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":9964},"main":"src/index.ts","type":"module","types":"src/index.ts","gitHead":"16f8623fc54cec51a56d9c3ef6093953925c916c","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:988cc98f-f4ce-423c-8532-17a76aca20ec"}},"repository":{"url":"git+https://github.com/d3ara1n/pi-extensions.git","type":"git","directory":"packages/pi-usage-block-core"},"_npmVersion":"11.16.0","description":"Shared types and registry for pi-usage-block — provider-agnostic usage quota reporting","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pi-usage-block-core_3.0.0_1783697392898_0.4731600763077297","host":"s3://npm-registry-packages-npm-production"}},"3.1.0":{"name":"@d3ara1n/pi-usage-block-core","version":"3.1.0","license":"MIT","_id":"@d3ara1n/pi-usage-block-core@3.1.0","maintainers":[{"name":"d3ara1n","email":"d3ara1n@outlook.com"}],"homepage":"https://github.com/d3ara1n/pi-extensions#readme","bugs":{"url":"https://github.com/d3ara1n/pi-extensions/issues"},"dist":{"shasum":"d60a0278986a72b33b13b0cd98375959b98856b8","tarball":"https://registry.npmjs.org/@d3ara1n/pi-usage-block-core/-/pi-usage-block-core-3.1.0.tgz","fileCount":3,"integrity":"sha512-dxb8q1+46+JDBKDc/6AiUaL7XcfEuBD8vHPmWyiKCfQBqRwuRNIArsyhoFTPr2HTjOCY2ZDUUII33QtsNFC5Aw==","signatures":[{"sig":"MEUCIQCgTU8mbE1tOxTafof1fM+yPSMU/5xaRTG7GvlT7DTTHwIgc+1am2xNnmCoLKiYBnP/7p2NN6swUYwXzR15YJyeqhA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@d3ara1n%2fpi-usage-block-core@3.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":9964},"main":"src/index.ts","type":"module","types":"src/index.ts","gitHead":"3dff05783498217a7026867216662f96fa8145bc","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:988cc98f-f4ce-423c-8532-17a76aca20ec"}},"repository":{"url":"git+https://github.com/d3ara1n/pi-extensions.git","type":"git","directory":"packages/pi-usage-block-core"},"_npmVersion":"11.16.0","description":"Shared types and registry for pi-usage-block — provider-agnostic usage quota reporting","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pi-usage-block-core_3.1.0_1783716962722_0.7780854801730146","host":"s3://npm-registry-packages-npm-production"}},"3.1.1":{"name":"@d3ara1n/pi-usage-block-core","version":"3.1.1","type":"module","description":"Shared types and registry for pi-usage-block — provider-agnostic usage quota reporting","main":"src/index.ts","types":"src/index.ts","license":"MIT","repository":{"type":"git","url":"git+https://github.com/d3ara1n/pi-extensions.git","directory":"packages/pi-usage-block-core"},"gitHead":"b1527ffd378324ee11621b07380c60f36a8bb01a","_id":"@d3ara1n/pi-usage-block-core@3.1.1","bugs":{"url":"https://github.com/d3ara1n/pi-extensions/issues"},"homepage":"https://github.com/d3ara1n/pi-extensions#readme","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-PDNiFxim0wyYUSgweOsp+ugpqXpwvb3bb59jQ77OSpVZhaDQvy1tMHdSYp2dKOytZgvHk2BS8A0rOwp4ghpghA==","shasum":"6b9e948c60f4d9b77a1f03bfae3241613a4e4783","tarball":"https://registry.npmjs.org/@d3ara1n/pi-usage-block-core/-/pi-usage-block-core-3.1.1.tgz","fileCount":3,"unpackedSize":9997,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@d3ara1n%2fpi-usage-block-core@3.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBY1t6J242uhBYJb810lsrQzrdIylHcPKnxxPeVuE25uAiBkyzQXAz74MuB+xSv7+PhB5v0QfoT2d3HHf4eZetaUQw=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:988cc98f-f4ce-423c-8532-17a76aca20ec"}},"directories":{},"maintainers":[{"name":"d3ara1n","email":"d3ara1n@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-usage-block-core_3.1.1_1786705952359_0.7377593081113492"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T06:50:26.676Z","modified":"2026-08-14T11:12:32.770Z","1.0.0":"2026-06-03T06:50:27.037Z","2.0.0":"2026-06-03T07:57:31.773Z","2.1.0":"2026-06-06T11:06:38.144Z","2.1.1":"2026-06-23T15:32:45.953Z","2.1.2":"2026-07-10T05:39:48.144Z","3.0.0":"2026-07-10T15:29:53.060Z","3.1.0":"2026-07-10T20:56:02.891Z","3.1.1":"2026-08-14T11:12:32.489Z"},"bugs":{"url":"https://github.com/d3ara1n/pi-extensions/issues"},"license":"MIT","homepage":"https://github.com/d3ara1n/pi-extensions#readme","repository":{"type":"git","url":"git+https://github.com/d3ara1n/pi-extensions.git","directory":"packages/pi-usage-block-core"},"description":"Shared types and registry for pi-usage-block — provider-agnostic usage quota reporting","maintainers":[{"name":"d3ara1n","email":"d3ara1n@outlook.com"}],"readme":"# @d3ara1n/pi-usage-block-core\n\nShared types and registry for usage reporting in [Pi Coding Agent](https://pi.dev).\n\nProvider-agnostic — any provider plugin can register itself, and any UI plugin (e.g. [`@d3ara1n/pi-usage-block`](../pi-usage-block)) can consume the data.\n\nA provider is one of two **kinds**, discriminated by `kind`:\n\n- **`quota`** — usage consumed within a time window (e.g. a 5h tokens quota). Has a natural denominator (`limit`), so the display shows a percentage.\n- **`balance`** — an absolute prepaid amount on an account (e.g. $32.50 remaining). No window, no reset — just an amount and currency.\n\n## Dependencies\n\nNone.\n\n## Installation\n\n```bash\nnpm install @d3ara1n/pi-usage-block-core\n```\n\n> This package is a **library**, not a standalone pi extension. It is installed automatically when used by a provider or UI plugin dependency; install it directly only when building against its API. For writing a provider end-to-end, see [`@d3ara1n/pi-usage-block`](../pi-usage-block#building-a-usage-provider).\n\n## Types\n\n### `UsageUnit`\n\nShared unit of measurement:\n\n```ts\ntype UsageUnit = \"requests\" | \"tokens\" | \"dollars\";\n```\n\n### `QuotaWindow` — `kind: \"quota\"`\n\nA single quota window (e.g. 5h tokens, weekly tokens).\n\n```ts\ninterface QuotaWindow {\n  period: string;        // label, e.g. \"5h\", \"weekly\"\n  used: number;          // amount consumed (or percentage if limit=100)\n  limit: number;         // maximum allowed (use 100 for percentage-only data)\n  unit: UsageUnit;\n  resetAt?: Date;        // when the quota resets; omit if unknown\n}\n```\n\n### `BalanceInfo` — `kind: \"balance\"`\n\nAn absolute remaining balance with no time window.\n\n```ts\ninterface BalanceInfo {\n  amount: number;        // remaining amount, e.g. 32.5\n  currency: string;      // ISO 4217 currency code, e.g. \"USD\", \"CNY\"\n}\n```\n\n### `QuotaProvider`\n\n```ts\ninterface QuotaProvider {\n  kind: \"quota\";\n  id: string;            // must match the pi provider key\n  name: string;\n  source: \"api\" | \"headers\";\n  fetchUsage?(): Promise<QuotaWindow[]>;                              // [source=\"api\"]\n  parseHeaders?(headers: Record<string, string>): QuotaWindow[] | null;  // [source=\"headers\"]\n}\n```\n\n`source` picks how data is obtained (orthogonal to `kind`):\n\n- **`api`** — `fetchUsage()` is polled periodically by the UI plugin.\n- **`headers`** — `parseHeaders()` is called on every provider response.\n\n### `BalanceProvider`\n\n```ts\ninterface BalanceProvider {\n  kind: \"balance\";\n  id: string;            // must match the pi provider key\n  name: string;\n  source: \"api\" | \"headers\";\n  fetchBalance?(): Promise<BalanceInfo>;                              // [source=\"api\"]\n  parseHeaders?(headers: Record<string, string>): BalanceInfo | null;      // [source=\"headers\"]\n}\n```\n\n`source` is orthogonal to `kind`, so balances may be polled (`api`) or read from response headers (`headers`).\n\n### `UsageProvider`\n\nDiscriminated union of the two:\n\n```ts\ntype UsageProvider = QuotaProvider | BalanceProvider;\n```\n\n## Registry\n\n`usageRegistry` is a global singleton shared across all extensions via `globalThis`:\n\n```ts\nimport { usageRegistry } from \"@d3ara1n/pi-usage-block-core\";\n\n// quota provider\nusageRegistry.register({\n  kind: \"quota\",\n  id: \"my-provider\",\n  name: \"My Provider\",\n  source: \"api\",\n  async fetchUsage() {\n    return [{ period: \"5h\", used: 53, limit: 100, unit: \"tokens\" }];\n  },\n});\n\n// balance provider\nusageRegistry.register({\n  kind: \"balance\",\n  id: \"my-prepaid\",\n  name: \"My Prepaid\",\n  source: \"api\",\n  async fetchBalance() {\n    return { amount: 32.5, currency: \"USD\" };\n  },\n});\n```\n\n## API\n\n```ts\nusageRegistry.register(provider: UsageProvider): void;   // overwrites if id exists\nusageRegistry.unregister(id: string): void;\nusageRegistry.get(id: string): UsageProvider | undefined;\nusageRegistry.getAll(): UsageProvider[];\nusageRegistry.size: number;\n```\n\n## Why a separate package?\n\nPi extensions can load the same package under distinct module identities. Storing this registry on `globalThis` keeps provider and UI plugins connected across those identities and reloads.\n","readmeFilename":"README.md"}