@krizaka/credits 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @krizaka/credits
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**One credits ledger for every Krizaka product.** It replaces three models: Yomizaka's `audit_credits` and `free_audit_used_at` columns on `accounts` (`reserveAudit` / `releaseAudit` / `refundFailedAudit`), Orochia's `wallet_ledger` with holds, and the Java kit's `credit_wallet` / `credit_ledger_entry` / `credit_hold` (`krizaka-billing`, whose names and events it follows). The coupons module (#46) grants capped credits through it.
+
+> **The ledger is append-only and the balance is derived.** Nothing stores a balance that could drift: what is left of a pot is the sum of its lines. A database trigger refuses any `UPDATE` or `DELETE` of a line. Credits are integers, never floats.
+
+```ts
+import { emitMigration, transaction } from "@krizaka/db";
+import { createCredits, creditsSchema } from "@krizaka/credits";
+import { creditsSettings, readCreditsSettings } from "@krizaka/credits/settings";
+
+emitMigration(creditsSchema, 1, { tables: { owner: "accounts" } }); // commit the SQL once, in your migrations
+
+const credits = createCredits({ clock, settings: () => readCreditsSettings((key) => settings.get(key)), outbox });
+
+await transaction(connect, async (tx) => {
+  // a coupon's free credits: 20 audits, at most 5 a day, then stop; they lapse in 30 days
+  await credits.grant(tx, { accountId, amount: 20, capPerDay: 5, expiresAt, onExhausted: "stop", source: `coupon:${redemptionId}`, idempotencyKey: `redeem-${redemptionId}` });
+  // credits bought (the payment webhook, in the event's transaction)
+  await credits.purchase(tx, { accountId, amount: 10, source: `purchase:${paymentRef}`, idempotencyKey: `pay-${paymentRef}` });
+});
+
+// spending: it refuses with a typed code, writes nothing when it refuses, and a replay of the key spends nothing more
+const { draws } = await credits.consume(tx, { accountId, amount: 1, reason: `audit:${auditId}`, idempotencyKey: `audit-${auditId}` });
+await credits.refund(tx, { accountId, consumed: `audit-${auditId}`, reason: "the run failed" }); // back to the same pots, once
+```
+
+## The model
+
+- **Two kinds of pot.** A **granted** pot is free usage (a coupon, an allowance, a demo): it always **expires**, may be capped **per day** and **per month**, and says what happens when it runs out: `stop` or `fallback_paid`. A **purchased** pot does not expire and is never capped.
+- **`consume(tx, { accountId, amount, reason, idempotencyKey })`** draws from the granted pots that **expire first**, each within its caps, then from purchased credits. Nothing is partial: it covers the whole amount or refuses.
+  - past a pot's cap: `CREDITS_CAP_DAY` / `CREDITS_CAP_MONTH` (a fair-use limit: purchased credits do not bypass it; another granted pot still can serve);
+  - a `stop` pot that is empty: `CREDITS_EXHAUSTED`, even if purchased credits exist;
+  - a `fallback_paid` pot that is empty: it moves on to purchased credits, then answers `PAYWALL`;
+  - no credits at all: `PAYWALL`.
+  Refusals are `CreditsError`s with a `code` and the HTTP `status` a route may answer (402 / 429).
+- **Holds.** `hold` keeps credits back for work in progress (it counts against the caps and the balance, and expires after `credits.holdTtlSeconds`); `settle(holdId, { amount? })` spends what the work cost (at most the hold) and frees the rest; `release` frees it all. Once each; a replay answers the first result.
+- **`refund`** gives back what a consume (or a settled hold) spent, to the same pots, once. **`expire(grantId)`** writes off what is left of a pot (a revoked coupon: credits already spent are never taken back); **`expireDue`** sweeps the lapsed pots in a job. **`adjust`** is an administrator's signed correction, never below zero.
+- **`balance`** is `{ total, granted, purchased, held, available, grants[] }`, derived; **`history`** pages the lines newest first.
+- **Idempotency.** Every writing call takes a key; the lines of an operation are `<kind>.<key>:<n>` (unique in the database). Keys are unique per ledger, not per account: use an id (a payment ref, a job id). A key already used by **another account** is refused (`CREDITS_KEY_REUSED`). Keys carry no colon.
+- **Concurrency.** Every writer takes `pg_advisory_xact_lock` on the account first, then reads and decides: concurrent consumption of the last credit never goes negative, a cap holds under load, and one key sent many times spends once (all proved on PostgreSQL, in loops).
+- **Days and months** are cut by PostgreSQL in the admin's IANA zone (`credits.timeZone`, default `America/Toronto`), so daylight-saving shifts are the database's own tz data; « today » comes from the injected clock.
+- **Events** (through `@krizaka/outbox`, in the caller's transaction, ids derived from the fact so each is announced once): `evt.credit.granted.v1` and `evt.credit.exhausted.v1`, the names of `krizaka-billing-api`, with a JSON Schema each (`CREDIT_EVENT_SCHEMAS`).
+- **Settings** (`@krizaka/credits/settings`): `credits.timeZone` (a choice among the runtime's IANA zones) and `credits.holdTtlSeconds` (900, 30–86400).
+- **Tables** (`creditsSchema`, Postgres schema `credits`): `grant`, `entry`, `hold`. The one product table it references is the owner (`owner`, the account table). An account that has credits is **anonymised, never deleted**: it is an accounting record, like an invoice.
+- `creditsLedgerContract` (`@krizaka/credits/testkit`) is the contract every store runs; `memoryCreditStore()` is for unit tests (it has no transaction, so `lock` does nothing: concurrency is proved on PostgreSQL).
+
+## Adopting it (Yomizaka)
+
+`audit_credits` becomes a purchased pot (`purchase` once per account for the balance it has, key `import-<accountId>`), the free audit a granted pot with `onExhausted: "fallback_paid"`, `reserveAudit` a `consume` (a `PAYWALL` is already Yomizaka's 402), `releaseAudit` and `refundFailedAudit` a `refund` of the consume key.

package/dist/chunk-34Y2HXOB.js

@@ -0,0 +1,109 @@
+import {
+  BUCKET,
+  CREDITS_CODE,
+  CreditsError,
+  ON_EXHAUSTED
+} from "./chunk-WDHQ7QHY.js";
+
+// src/rules.ts
+import { isAfter } from "@krizaka/time";
+var CREDITS_DEFAULTS = { timeZone: "America/Toronto", holdTtlSeconds: 900 };
+var HOLD_TTL_BOUNDS = [30, 86400];
+var alive = (s, now) => !s.closed && (s.grant.expiresAt === null || isAfter(s.grant.expiresAt, now));
+var byExpiry = (a, b) => (a.grant.expiresAt?.valueOf() ?? Infinity) - (b.grant.expiresAt?.valueOf() ?? Infinity) || a.grant.createdAt.valueOf() - b.grant.createdAt.valueOf() || a.grant.id.localeCompare(b.grant.id);
+function drawGranted(granted, need) {
+  const draws = [];
+  let left = need;
+  let capped = null;
+  for (const s of granted) {
+    if (left === 0) break;
+    const dayLeft = s.grant.capPerDay === null ? Infinity : Math.max(0, s.grant.capPerDay - s.usedToday);
+    const monthLeft = s.grant.capPerMonth === null ? Infinity : Math.max(0, s.grant.capPerMonth - s.usedThisMonth);
+    const take = Math.min(left, s.remaining, dayLeft, monthLeft);
+    if (take < Math.min(left, s.remaining)) capped ??= dayLeft <= monthLeft ? CREDITS_CODE.capDay : CREDITS_CODE.capMonth;
+    if (take > 0) {
+      draws.push({ grantId: s.grant.id, amount: take });
+      left -= take;
+    }
+  }
+  return { draws, left, capped };
+}
+function drawPurchased(purchased, need) {
+  const draws = [];
+  let left = need;
+  const oldestFirst = [...purchased].sort((a, b) => a.grant.createdAt.valueOf() - b.grant.createdAt.valueOf() || a.grant.id.localeCompare(b.grant.id));
+  for (const s of oldestFirst) {
+    if (left === 0) break;
+    const take = Math.min(left, s.remaining);
+    draws.push({ grantId: s.grant.id, amount: take });
+    left -= take;
+  }
+  return { draws, left };
+}
+function planDraws(states, need, now) {
+  const live = states.filter((s) => alive(s, now));
+  const granted = live.filter((s) => s.grant.bucket === BUCKET.granted && s.remaining > 0).sort(byExpiry);
+  const first = drawGranted(granted, need);
+  if (first.left === 0) return { ok: true, draws: first.draws };
+  if (first.capped) return { ok: false, code: first.capped };
+  const taken = new Map(first.draws.map((d) => [d.grantId, d.amount]));
+  const stopped = live.some((s) => s.grant.bucket === BUCKET.granted && s.grant.onExhausted === ON_EXHAUSTED.stop && s.remaining - (taken.get(s.grant.id) ?? 0) <= 0);
+  if (stopped) return { ok: false, code: CREDITS_CODE.exhausted };
+  const rest = drawPurchased(live.filter((s) => s.grant.bucket === BUCKET.purchased && s.remaining > 0), first.left);
+  return rest.left === 0 ? { ok: true, draws: [...first.draws, ...rest.draws] } : { ok: false, code: CREDITS_CODE.paywall };
+}
+function skipFirst(draws, skip) {
+  let toSkip = skip;
+  const out = [];
+  for (const d of draws) {
+    const dropped = Math.min(toSkip, d.amount);
+    toSkip -= dropped;
+    if (d.amount > dropped) out.push({ grantId: d.grantId, amount: d.amount - dropped });
+  }
+  return out;
+}
+function checkAmount(n, what = "an amount") {
+  if (!Number.isSafeInteger(n) || n <= 0) throw new CreditsError(CREDITS_CODE.badAmount, `${what} of credits is a positive integer, got ${n}`);
+  return n;
+}
+var KEY = /^[\x21-\x7e]{1,150}$/;
+function checkKey(key) {
+  if (!KEY.test(key) || key.includes(":")) throw new CreditsError(CREDITS_CODE.badKey, "An idempotency key is 1 to 150 printable characters, without spaces or a colon");
+  return key;
+}
+function checkSettings(s) {
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: s.timeZone });
+  } catch {
+    throw new CreditsError(CREDITS_CODE.badSettings, `Not an IANA time zone: ${s.timeZone}`);
+  }
+  if (!Number.isSafeInteger(s.holdTtlSeconds) || s.holdTtlSeconds < HOLD_TTL_BOUNDS[0] || s.holdTtlSeconds > HOLD_TTL_BOUNDS[1]) {
+    throw new CreditsError(CREDITS_CODE.badSettings, `holdTtlSeconds is ${HOLD_TTL_BOUNDS[0]} to ${HOLD_TTL_BOUNDS[1]}`);
+  }
+  return s;
+}
+var MAX_SOURCE = 200;
+function checkGrantedTerms(input, now) {
+  if (!(input.expiresAt instanceof Date) || Number.isNaN(input.expiresAt.valueOf()) || input.expiresAt <= now) throw new CreditsError(CREDITS_CODE.badGrant, "A granted pot lapses in the future");
+  for (const cap of [input.capPerDay, input.capPerMonth]) if (cap !== void 0 && cap !== null) checkAmount(cap, "a cap");
+  if (input.onExhausted !== ON_EXHAUSTED.stop && input.onExhausted !== ON_EXHAUSTED.fallbackPaid) throw new CreditsError(CREDITS_CODE.badGrant, "onExhausted is stop or fallback_paid");
+}
+function checkNewGrant(kind, input, now) {
+  checkAmount(input.amount, "a grant");
+  checkKey(input.idempotencyKey);
+  if (!input.accountId) throw new CreditsError(CREDITS_CODE.badGrant, "A grant has an account");
+  if (!input.source || input.source.length > MAX_SOURCE) throw new CreditsError(CREDITS_CODE.badGrant, `A source is 1 to ${MAX_SOURCE} characters`);
+  if (kind === "grant") checkGrantedTerms(input, now);
+}
+
+export {
+  CREDITS_DEFAULTS,
+  HOLD_TTL_BOUNDS,
+  planDraws,
+  skipFirst,
+  checkAmount,
+  checkKey,
+  checkSettings,
+  checkNewGrant
+};
+//# sourceMappingURL=chunk-34Y2HXOB.js.map

package/dist/chunk-34Y2HXOB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/rules.ts"],"sourcesContent":["import { isAfter } from \"@krizaka/time\";\n\nimport { BUCKET, CREDITS_CODE, type CreditsCode, CreditsError, type CreditsSettings, type GrantState, ON_EXHAUSTED } from \"./port\";\n\n/** How much of one grant a consumption takes. */\nexport interface Draw {\n  grantId: string;\n  amount: number;\n}\n\nexport type Plan = { ok: true; draws: Draw[] } | { ok: false; code: CreditsCode };\n\n/** The defaults and bounds of the settings (the admin changes them without a redeploy). */\nexport const CREDITS_DEFAULTS: CreditsSettings = { timeZone: \"America/Toronto\", holdTtlSeconds: 900 };\n// @fixed: bounds on the lifetime of a hold, in seconds: 30 seconds to a day (a sanity range, not a business parameter)\nexport const HOLD_TTL_BOUNDS = [30, 86_400] as const;\n\nconst alive = (s: GrantState, now: Date) => !s.closed && (s.grant.expiresAt === null || isAfter(s.grant.expiresAt, now));\nconst byExpiry = (a: GrantState, b: GrantState) =>\n  (a.grant.expiresAt?.valueOf() ?? Infinity) - (b.grant.expiresAt?.valueOf() ?? Infinity) || a.grant.createdAt.valueOf() - b.grant.createdAt.valueOf() || a.grant.id.localeCompare(b.grant.id);\n\n/** What the granted pots can give, each within its caps, and the first cap that held one back. */\nfunction drawGranted(granted: readonly GrantState[], need: number): { draws: Draw[]; left: number; capped: CreditsCode | null } {\n  const draws: Draw[] = [];\n  let left = need;\n  let capped: CreditsCode | null = null;\n  for (const s of granted) {\n    if (left === 0) break;\n    const dayLeft = s.grant.capPerDay === null ? Infinity : Math.max(0, s.grant.capPerDay - s.usedToday);\n    const monthLeft = s.grant.capPerMonth === null ? Infinity : Math.max(0, s.grant.capPerMonth - s.usedThisMonth);\n    const take = Math.min(left, s.remaining, dayLeft, monthLeft);\n    if (take < Math.min(left, s.remaining)) capped ??= dayLeft <= monthLeft ? CREDITS_CODE.capDay : CREDITS_CODE.capMonth;\n    if (take > 0) {\n      draws.push({ grantId: s.grant.id, amount: take });\n      left -= take;\n    }\n  }\n  return { draws, left, capped };\n}\n\n/** What the purchased pots can give, the oldest first. */\nfunction drawPurchased(purchased: readonly GrantState[], need: number): { draws: Draw[]; left: number } {\n  const draws: Draw[] = [];\n  let left = need;\n  const oldestFirst = [...purchased].sort((a, b) => a.grant.createdAt.valueOf() - b.grant.createdAt.valueOf() || a.grant.id.localeCompare(b.grant.id));\n  for (const s of oldestFirst) {\n    if (left === 0) break;\n    const take = Math.min(left, s.remaining);\n    draws.push({ grantId: s.grant.id, amount: take });\n    left -= take;\n  }\n  return { draws, left };\n}\n\n/**\n * Plans where `need` credits come from, or says why they cannot. Pure: the same states give the same plan.\n *\n * Granted credits go first, the pot that lapses first first, each within its caps of the day and the month. If the granted pots cannot\n * give it all: a pot held back by a cap answers `CREDITS_CAP_DAY` / `CREDITS_CAP_MONTH` (the cap is a fair-use limit: purchased\n * credits do not bypass it); else a `stop` pot that is empty answers `CREDITS_EXHAUSTED`; else the purchased credits give the rest, and\n * when they cannot, `PAYWALL`. Nothing is partial: the plan covers the whole amount or refuses.\n * @param states every grant of the account with what is left (`CreditStore.grantStates`)\n * @param need credits wanted, a positive integer\n * @param now the injected clock's instant\n */\nexport function planDraws(states: readonly GrantState[], need: number, now: Date): Plan {\n  const live = states.filter((s) => alive(s, now));\n  const granted = live.filter((s) => s.grant.bucket === BUCKET.granted && s.remaining > 0).sort(byExpiry);\n  const first = drawGranted(granted, need);\n  if (first.left === 0) return { ok: true, draws: first.draws };\n  if (first.capped) return { ok: false, code: first.capped };\n  const taken = new Map(first.draws.map((d) => [d.grantId, d.amount]));\n  const stopped = live.some((s) => s.grant.bucket === BUCKET.granted && s.grant.onExhausted === ON_EXHAUSTED.stop && s.remaining - (taken.get(s.grant.id) ?? 0) <= 0);\n  if (stopped) return { ok: false, code: CREDITS_CODE.exhausted };\n  const rest = drawPurchased(live.filter((s) => s.grant.bucket === BUCKET.purchased && s.remaining > 0), first.left);\n  return rest.left === 0 ? { ok: true, draws: [...first.draws, ...rest.draws] } : { ok: false, code: CREDITS_CODE.paywall };\n}\n\n/** Drops the first `skip` credits of a plan (the ones already held back by active holds), keeping the order. */\nexport function skipFirst(draws: readonly Draw[], skip: number): Draw[] {\n  let toSkip = skip;\n  const out: Draw[] = [];\n  for (const d of draws) {\n    const dropped = Math.min(toSkip, d.amount);\n    toSkip -= dropped;\n    if (d.amount > dropped) out.push({ grantId: d.grantId, amount: d.amount - dropped });\n  }\n  return out;\n}\n\n/** Whether `n` is an amount of credits: a positive safe integer. @throws CreditsError `CREDITS_BAD_AMOUNT` */\nexport function checkAmount(n: number, what = \"an amount\"): number {\n  if (!Number.isSafeInteger(n) || n <= 0) throw new CreditsError(CREDITS_CODE.badAmount, `${what} of credits is a positive integer, got ${n}`);\n  return n;\n}\n\nconst KEY = /^[\\x21-\\x7e]{1,150}$/;\n/** An idempotency key: printable ASCII without spaces, 1 to 150 characters. @throws CreditsError `CREDITS_BAD_KEY` */\nexport function checkKey(key: string): string {\n  if (!KEY.test(key) || key.includes(\":\")) throw new CreditsError(CREDITS_CODE.badKey, \"An idempotency key is 1 to 150 printable characters, without spaces or a colon\");\n  return key;\n}\n\n/** Checks the settings the service was given. @throws CreditsError `CREDITS_BAD_SETTINGS` */\nexport function checkSettings(s: CreditsSettings): CreditsSettings {\n  try {\n    new Intl.DateTimeFormat(\"en\", { timeZone: s.timeZone });\n  } catch {\n    throw new CreditsError(CREDITS_CODE.badSettings, `Not an IANA time zone: ${s.timeZone}`);\n  }\n  if (!Number.isSafeInteger(s.holdTtlSeconds) || s.holdTtlSeconds < HOLD_TTL_BOUNDS[0] || s.holdTtlSeconds > HOLD_TTL_BOUNDS[1]) {\n    throw new CreditsError(CREDITS_CODE.badSettings, `holdTtlSeconds is ${HOLD_TTL_BOUNDS[0]} to ${HOLD_TTL_BOUNDS[1]}`);\n  }\n  return s;\n}\n\n// @fixed: the longest source a line of the ledger carries (its CHECK)\nconst MAX_SOURCE = 200;\n\n/** The shape of what `grant` and `purchase` take, for the checks. */\ninterface NewGrantInput {\n  accountId: string;\n  amount: number;\n  source: string;\n  idempotencyKey: string;\n  expiresAt?: Date;\n  capPerDay?: number | null;\n  capPerMonth?: number | null;\n  onExhausted?: string;\n}\n\n/** The checks of a granted pot's own terms: it lapses in the future, its caps are whole numbers, it says what happens when it runs out. */\nfunction checkGrantedTerms(input: NewGrantInput, now: Date): void {\n  if (!(input.expiresAt instanceof Date) || Number.isNaN(input.expiresAt.valueOf()) || input.expiresAt <= now) throw new CreditsError(CREDITS_CODE.badGrant, \"A granted pot lapses in the future\");\n  for (const cap of [input.capPerDay, input.capPerMonth]) if (cap !== undefined && cap !== null) checkAmount(cap, \"a cap\");\n  if (input.onExhausted !== ON_EXHAUSTED.stop && input.onExhausted !== ON_EXHAUSTED.fallbackPaid) throw new CreditsError(CREDITS_CODE.badGrant, \"onExhausted is stop or fallback_paid\");\n}\n\n/**\n * Checks what `grant` or `purchase` was given, before any store call.\n * @throws CreditsError `CREDITS_BAD_AMOUNT`, `CREDITS_BAD_KEY` or `CREDITS_BAD_GRANT`\n */\nexport function checkNewGrant(kind: \"grant\" | \"purchase\", input: NewGrantInput, now: Date): void {\n  checkAmount(input.amount, \"a grant\");\n  checkKey(input.idempotencyKey);\n  if (!input.accountId) throw new CreditsError(CREDITS_CODE.badGrant, \"A grant has an account\");\n  if (!input.source || input.source.length > MAX_SOURCE) throw new CreditsError(CREDITS_CODE.badGrant, `A source is 1 to ${MAX_SOURCE} characters`);\n  if (kind === \"grant\") checkGrantedTerms(input, now);\n}\n"],"mappings":";;;;;;;;AAAA,SAAS,eAAe;AAajB,IAAM,mBAAoC,EAAE,UAAU,mBAAmB,gBAAgB,IAAI;AAE7F,IAAM,kBAAkB,CAAC,IAAI,KAAM;AAE1C,IAAM,QAAQ,CAAC,GAAe,QAAc,CAAC,EAAE,WAAW,EAAE,MAAM,cAAc,QAAQ,QAAQ,EAAE,MAAM,WAAW,GAAG;AACtH,IAAM,WAAW,CAAC,GAAe,OAC9B,EAAE,MAAM,WAAW,QAAQ,KAAK,aAAa,EAAE,MAAM,WAAW,QAAQ,KAAK,aAAa,EAAE,MAAM,UAAU,QAAQ,IAAI,EAAE,MAAM,UAAU,QAAQ,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,MAAM,EAAE;AAG7L,SAAS,YAAY,SAAgC,MAA2E;AAC9H,QAAM,QAAgB,CAAC;AACvB,MAAI,OAAO;AACX,MAAI,SAA6B;AACjC,aAAW,KAAK,SAAS;AACvB,QAAI,SAAS,EAAG;AAChB,UAAM,UAAU,EAAE,MAAM,cAAc,OAAO,WAAW,KAAK,IAAI,GAAG,EAAE,MAAM,YAAY,EAAE,SAAS;AACnG,UAAM,YAAY,EAAE,MAAM,gBAAgB,OAAO,WAAW,KAAK,IAAI,GAAG,EAAE,MAAM,cAAc,EAAE,aAAa;AAC7G,UAAM,OAAO,KAAK,IAAI,MAAM,EAAE,WAAW,SAAS,SAAS;AAC3D,QAAI,OAAO,KAAK,IAAI,MAAM,EAAE,SAAS,EAAG,YAAW,WAAW,YAAY,aAAa,SAAS,aAAa;AAC7G,QAAI,OAAO,GAAG;AACZ,YAAM,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,QAAQ,KAAK,CAAC;AAChD,cAAQ;AAAA,IACV;AAAA,EACF;AACA,SAAO,EAAE,OAAO,MAAM,OAAO;AAC/B;AAGA,SAAS,cAAc,WAAkC,MAA+C;AACtG,QAAM,QAAgB,CAAC;AACvB,MAAI,OAAO;AACX,QAAM,cAAc,CAAC,GAAG,SAAS,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,MAAM,UAAU,QAAQ,IAAI,EAAE,MAAM,UAAU,QAAQ,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,MAAM,EAAE,CAAC;AACnJ,aAAW,KAAK,aAAa;AAC3B,QAAI,SAAS,EAAG;AAChB,UAAM,OAAO,KAAK,IAAI,MAAM,EAAE,SAAS;AACvC,UAAM,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,QAAQ,KAAK,CAAC;AAChD,YAAQ;AAAA,EACV;AACA,SAAO,EAAE,OAAO,KAAK;AACvB;AAaO,SAAS,UAAU,QAA+B,MAAc,KAAiB;AACtF,QAAM,OAAO,OAAO,OAAO,CAAC,MAAM,MAAM,GAAG,GAAG,CAAC;AAC/C,QAAM,UAAU,KAAK,OAAO,CAAC,MAAM,EAAE,MAAM,WAAW,OAAO,WAAW,EAAE,YAAY,CAAC,EAAE,KAAK,QAAQ;AACtG,QAAM,QAAQ,YAAY,SAAS,IAAI;AACvC,MAAI,MAAM,SAAS,EAAG,QAAO,EAAE,IAAI,MAAM,OAAO,MAAM,MAAM;AAC5D,MAAI,MAAM,OAAQ,QAAO,EAAE,IAAI,OAAO,MAAM,MAAM,OAAO;AACzD,QAAM,QAAQ,IAAI,IAAI,MAAM,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AACnE,QAAM,UAAU,KAAK,KAAK,CAAC,MAAM,EAAE,MAAM,WAAW,OAAO,WAAW,EAAE,MAAM,gBAAgB,aAAa,QAAQ,EAAE,aAAa,MAAM,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;AAClK,MAAI,QAAS,QAAO,EAAE,IAAI,OAAO,MAAM,aAAa,UAAU;AAC9D,QAAM,OAAO,cAAc,KAAK,OAAO,CAAC,MAAM,EAAE,MAAM,WAAW,OAAO,aAAa,EAAE,YAAY,CAAC,GAAG,MAAM,IAAI;AACjH,SAAO,KAAK,SAAS,IAAI,EAAE,IAAI,MAAM,OAAO,CAAC,GAAG,MAAM,OAAO,GAAG,KAAK,KAAK,EAAE,IAAI,EAAE,IAAI,OAAO,MAAM,aAAa,QAAQ;AAC1H;AAGO,SAAS,UAAU,OAAwB,MAAsB;AACtE,MAAI,SAAS;AACb,QAAM,MAAc,CAAC;AACrB,aAAW,KAAK,OAAO;AACrB,UAAM,UAAU,KAAK,IAAI,QAAQ,EAAE,MAAM;AACzC,cAAU;AACV,QAAI,EAAE,SAAS,QAAS,KAAI,KAAK,EAAE,SAAS,EAAE,SAAS,QAAQ,EAAE,SAAS,QAAQ,CAAC;AAAA,EACrF;AACA,SAAO;AACT;AAGO,SAAS,YAAY,GAAW,OAAO,aAAqB;AACjE,MAAI,CAAC,OAAO,cAAc,CAAC,KAAK,KAAK,EAAG,OAAM,IAAI,aAAa,aAAa,WAAW,GAAG,IAAI,0CAA0C,CAAC,EAAE;AAC3I,SAAO;AACT;AAEA,IAAM,MAAM;AAEL,SAAS,SAAS,KAAqB;AAC5C,MAAI,CAAC,IAAI,KAAK,GAAG,KAAK,IAAI,SAAS,GAAG,EAAG,OAAM,IAAI,aAAa,aAAa,QAAQ,gFAAgF;AACrK,SAAO;AACT;AAGO,SAAS,cAAc,GAAqC;AACjE,MAAI;AACF,QAAI,KAAK,eAAe,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC;AAAA,EACxD,QAAQ;AACN,UAAM,IAAI,aAAa,aAAa,aAAa,0BAA0B,EAAE,QAAQ,EAAE;AAAA,EACzF;AACA,MAAI,CAAC,OAAO,cAAc,EAAE,cAAc,KAAK,EAAE,iBAAiB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,gBAAgB,CAAC,GAAG;AAC7H,UAAM,IAAI,aAAa,aAAa,aAAa,qBAAqB,gBAAgB,CAAC,CAAC,OAAO,gBAAgB,CAAC,CAAC,EAAE;AAAA,EACrH;AACA,SAAO;AACT;AAGA,IAAM,aAAa;AAenB,SAAS,kBAAkB,OAAsB,KAAiB;AAChE,MAAI,EAAE,MAAM,qBAAqB,SAAS,OAAO,MAAM,MAAM,UAAU,QAAQ,CAAC,KAAK,MAAM,aAAa,IAAK,OAAM,IAAI,aAAa,aAAa,UAAU,oCAAoC;AAC/L,aAAW,OAAO,CAAC,MAAM,WAAW,MAAM,WAAW,EAAG,KAAI,QAAQ,UAAa,QAAQ,KAAM,aAAY,KAAK,OAAO;AACvH,MAAI,MAAM,gBAAgB,aAAa,QAAQ,MAAM,gBAAgB,aAAa,aAAc,OAAM,IAAI,aAAa,aAAa,UAAU,sCAAsC;AACtL;AAMO,SAAS,cAAc,MAA4B,OAAsB,KAAiB;AAC/F,cAAY,MAAM,QAAQ,SAAS;AACnC,WAAS,MAAM,cAAc;AAC7B,MAAI,CAAC,MAAM,UAAW,OAAM,IAAI,aAAa,aAAa,UAAU,wBAAwB;AAC5F,MAAI,CAAC,MAAM,UAAU,MAAM,OAAO,SAAS,WAAY,OAAM,IAAI,aAAa,aAAa,UAAU,oBAAoB,UAAU,aAAa;AAChJ,MAAI,SAAS,QAAS,mBAAkB,OAAO,GAAG;AACpD;","names":[]}

package/dist/chunk-WDHQ7QHY.js

@@ -0,0 +1,56 @@
+// src/port.ts
+var BUCKET = { granted: "granted", purchased: "purchased" };
+var ON_EXHAUSTED = { stop: "stop", fallbackPaid: "fallback_paid" };
+var ENTRY_TYPE = { grant: "GRANT", purchase: "PURCHASE", debit: "DEBIT", refund: "REFUND", expiry: "EXPIRY", adjustment: "ADJUSTMENT" };
+var HOLD_STATUS = { active: "active", settled: "settled", released: "released" };
+var CREDITS_CODE = {
+  capDay: "CREDITS_CAP_DAY",
+  capMonth: "CREDITS_CAP_MONTH",
+  exhausted: "CREDITS_EXHAUSTED",
+  paywall: "PAYWALL",
+  badAmount: "CREDITS_BAD_AMOUNT",
+  badGrant: "CREDITS_BAD_GRANT",
+  badKey: "CREDITS_BAD_KEY",
+  badSettings: "CREDITS_BAD_SETTINGS",
+  unknownGrant: "CREDITS_UNKNOWN_GRANT",
+  unknownHold: "CREDITS_UNKNOWN_HOLD",
+  holdClosed: "CREDITS_HOLD_CLOSED",
+  keyReused: "CREDITS_KEY_REUSED",
+  nothingToRefund: "CREDITS_NOTHING_TO_REFUND"
+};
+var CREDITS_STATUS = {
+  CREDITS_CAP_DAY: 429,
+  CREDITS_CAP_MONTH: 429,
+  CREDITS_EXHAUSTED: 402,
+  PAYWALL: 402,
+  CREDITS_BAD_AMOUNT: 400,
+  CREDITS_BAD_GRANT: 400,
+  CREDITS_BAD_KEY: 400,
+  CREDITS_BAD_SETTINGS: 500,
+  CREDITS_UNKNOWN_GRANT: 404,
+  CREDITS_UNKNOWN_HOLD: 404,
+  CREDITS_HOLD_CLOSED: 409,
+  CREDITS_KEY_REUSED: 409,
+  CREDITS_NOTHING_TO_REFUND: 404
+};
+var CreditsError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CreditsError";
+    this.status = CREDITS_STATUS[code];
+  }
+  code;
+  status;
+};
+
+export {
+  BUCKET,
+  ON_EXHAUSTED,
+  ENTRY_TYPE,
+  HOLD_STATUS,
+  CREDITS_CODE,
+  CREDITS_STATUS,
+  CreditsError
+};
+//# sourceMappingURL=chunk-WDHQ7QHY.js.map

package/dist/chunk-WDHQ7QHY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/port.ts"],"sourcesContent":["/**\n * The ports of « credits »: ONE ledger of usage credits per account. Generic: no product import, no database client (a `Query`\n * comes in), no wall clock (a `Clock` comes in). Credits are integers (never floats). The ledger is append-only and the balance is\n * DERIVED from it: nothing stores a balance that could drift.\n *\n * Two kinds of credit live in it. A GRANT is free usage (a coupon, a monthly allowance, a demo): it expires, may be capped per day or\n * month, and says what happens when it runs out (`stop`, or `fallback_paid`: go on with what the person bought). A PURCHASE is paid\n * usage: it does not expire and is never capped.\n */\nexport type { Clock, Query } from \"@krizaka/db\";\n\nexport const BUCKET = { granted: \"granted\", purchased: \"purchased\" } as const;\nexport type Bucket = (typeof BUCKET)[keyof typeof BUCKET];\n\n/** What happens when a grant has run out: refuse (`stop`), or move on to purchased credits (`fallback_paid`). */\nexport const ON_EXHAUSTED = { stop: \"stop\", fallbackPaid: \"fallback_paid\" } as const;\nexport type OnExhausted = (typeof ON_EXHAUSTED)[keyof typeof ON_EXHAUSTED];\n\n/** The kinds of line of the ledger. Amounts are signed: credits in are positive, credits out negative. */\nexport const ENTRY_TYPE = { grant: \"GRANT\", purchase: \"PURCHASE\", debit: \"DEBIT\", refund: \"REFUND\", expiry: \"EXPIRY\", adjustment: \"ADJUSTMENT\" } as const;\nexport type EntryType = (typeof ENTRY_TYPE)[keyof typeof ENTRY_TYPE];\n\nexport const HOLD_STATUS = { active: \"active\", settled: \"settled\", released: \"released\" } as const;\nexport type HoldStatus = (typeof HOLD_STATUS)[keyof typeof HOLD_STATUS];\n\n/** A pot of credits. Immutable: what is left of it is derived from the ledger. */\nexport interface Grant {\n  id: string;\n  accountId: string;\n  bucket: Bucket;\n  /** What it started with. */\n  amount: number;\n  /** The most it gives in a calendar day (in the settings' time zone), or none. Granted only. */\n  capPerDay: number | null;\n  /** The most it gives in a calendar month, or none. Granted only. */\n  capPerMonth: number | null;\n  /** When it lapses. Required for a granted pot, none for a purchased one. */\n  expiresAt: Date | null;\n  onExhausted: OnExhausted;\n  /** Where it comes from (`coupon:<redemptionId>`, `plan:monthly`, `purchase:<paymentRef>`). */\n  source: string;\n  createdAt: Date;\n}\n\n/** One line of the ledger. */\nexport interface Entry {\n  id: string;\n  accountId: string;\n  grantId: string | null;\n  type: EntryType;\n  /** Signed. */\n  amount: number;\n  reason: string;\n  /** The caller's key for the whole operation: a replay finds its lines. */\n  operation: string;\n  /** Unique: `<operation>:<n>`. */\n  idempotencyKey: string;\n  /** For a REFUND: the operation it gives back. */\n  reverses: string | null;\n  holdId: string | null;\n  at: Date;\n}\n\nexport interface Hold {\n  id: string;\n  accountId: string;\n  amount: number;\n  expiresAt: Date;\n  status: HoldStatus;\n  /** What it settled for, when settled. */\n  settledAmount: number | null;\n  createdAt: Date;\n  closedAt: Date | null;\n  operation: string;\n}\n\n/** A grant as the planner sees it: what is left, what it gave today and this month, and whether it was closed by an expiry line. */\nexport interface GrantState {\n  grant: Grant;\n  remaining: number;\n  usedToday: number;\n  usedThisMonth: number;\n  /** An EXPIRY line closed it (revoked, or swept after its date). */\n  closed: boolean;\n}\n\n/** The calendar the caps are counted in: the zone, and the local day and month of « now » in it (`2026-10-26`, `2026-10`). */\nexport interface Calendar {\n  timeZone: string;\n  day: string;\n  month: string;\n}\n\n/** Where the ledger lives. Every adapter runs `creditStoreContract` (`@krizaka/credits/testkit`). Times come from the caller. */\nexport interface CreditStore {\n  /** Serialises the writers of one account until the transaction ends (an advisory lock). Call it before reading to decide. */\n  lock(accountId: string): Promise<void>;\n  insertGrant(grant: Grant): Promise<void>;\n  grantById(grantId: string): Promise<Grant | null>;\n  /** The account's grants, with what is left and what each gave in the calendar's day and month. Includes lapsed and closed ones. */\n  grantStates(accountId: string, calendar: Calendar): Promise<GrantState[]>;\n  /** Writes lines. A duplicate `idempotencyKey` is a bug of the caller (it checked `entriesOf` first, under the lock) and throws. */\n  insertEntries(entries: Entry[]): Promise<void>;\n  /** The lines of one operation, in order. */\n  entriesOf(operation: string): Promise<Entry[]>;\n  /** The lines of the account, newest first. */\n  history(accountId: string, options: { limit: number; before?: Date }): Promise<Entry[]>;\n  insertHold(hold: Hold): Promise<void>;\n  holdById(holdId: string): Promise<Hold | null>;\n  holdByOperation(operation: string): Promise<Hold | null>;\n  /** What the account's active holds that have not expired at `now` keep back, except `exceptHoldId`. */\n  heldAmount(accountId: string, now: Date, exceptHoldId?: string): Promise<number>;\n  closeHold(holdId: string, status: typeof HOLD_STATUS.settled | typeof HOLD_STATUS.released, settledAmount: number | null, at: Date): Promise<void>;\n  /** Granted pots past their date that still hold credits and no EXPIRY line, oldest first. */\n  lapsedWithCredits(now: Date, limit: number): Promise<{ grantId: string; accountId: string }[]>;\n}\n\n/** The knobs of the ledger, read from the admin's settings (`@krizaka/credits/settings`). */\nexport interface CreditsSettings {\n  /** The IANA zone that days and months are counted in. */\n  timeZone: string;\n  /** Seconds a hold keeps credits back when the caller names no lifetime. */\n  holdTtlSeconds: number;\n}\n\n/** Stable codes of the refusals of this package. */\nexport const CREDITS_CODE = {\n  capDay: \"CREDITS_CAP_DAY\",\n  capMonth: \"CREDITS_CAP_MONTH\",\n  exhausted: \"CREDITS_EXHAUSTED\",\n  paywall: \"PAYWALL\",\n  badAmount: \"CREDITS_BAD_AMOUNT\",\n  badGrant: \"CREDITS_BAD_GRANT\",\n  badKey: \"CREDITS_BAD_KEY\",\n  badSettings: \"CREDITS_BAD_SETTINGS\",\n  unknownGrant: \"CREDITS_UNKNOWN_GRANT\",\n  unknownHold: \"CREDITS_UNKNOWN_HOLD\",\n  holdClosed: \"CREDITS_HOLD_CLOSED\",\n  keyReused: \"CREDITS_KEY_REUSED\",\n  nothingToRefund: \"CREDITS_NOTHING_TO_REFUND\",\n} as const;\nexport type CreditsCode = (typeof CREDITS_CODE)[keyof typeof CREDITS_CODE];\n\n/** The HTTP status a route may answer for each refusal. */\nexport const CREDITS_STATUS: Record<CreditsCode, number> = {\n  CREDITS_CAP_DAY: 429,\n  CREDITS_CAP_MONTH: 429,\n  CREDITS_EXHAUSTED: 402,\n  PAYWALL: 402,\n  CREDITS_BAD_AMOUNT: 400,\n  CREDITS_BAD_GRANT: 400,\n  CREDITS_BAD_KEY: 400,\n  CREDITS_BAD_SETTINGS: 500,\n  CREDITS_UNKNOWN_GRANT: 404,\n  CREDITS_UNKNOWN_HOLD: 404,\n  CREDITS_HOLD_CLOSED: 409,\n  CREDITS_KEY_REUSED: 409,\n  CREDITS_NOTHING_TO_REFUND: 404,\n};\n\n/** A refusal: a stable `code`, the HTTP `status` a route may answer, and a message. */\nexport class CreditsError extends Error {\n  readonly status: number;\n  constructor(\n    readonly code: CreditsCode,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"CreditsError\";\n    this.status = CREDITS_STATUS[code];\n  }\n}\n"],"mappings":";AAWO,IAAM,SAAS,EAAE,SAAS,WAAW,WAAW,YAAY;AAI5D,IAAM,eAAe,EAAE,MAAM,QAAQ,cAAc,gBAAgB;AAInE,IAAM,aAAa,EAAE,OAAO,SAAS,UAAU,YAAY,OAAO,SAAS,QAAQ,UAAU,QAAQ,UAAU,YAAY,aAAa;AAGxI,IAAM,cAAc,EAAE,QAAQ,UAAU,SAAS,WAAW,UAAU,WAAW;AAwGjF,IAAM,eAAe;AAAA,EAC1B,QAAQ;AAAA,EACR,UAAU;AAAA,EACV,WAAW;AAAA,EACX,SAAS;AAAA,EACT,WAAW;AAAA,EACX,UAAU;AAAA,EACV,QAAQ;AAAA,EACR,aAAa;AAAA,EACb,cAAc;AAAA,EACd,aAAa;AAAA,EACb,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,iBAAiB;AACnB;AAIO,IAAM,iBAA8C;AAAA,EACzD,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,mBAAmB;AAAA,EACnB,SAAS;AAAA,EACT,oBAAoB;AAAA,EACpB,mBAAmB;AAAA,EACnB,iBAAiB;AAAA,EACjB,sBAAsB;AAAA,EACtB,uBAAuB;AAAA,EACvB,sBAAsB;AAAA,EACtB,qBAAqB;AAAA,EACrB,oBAAoB;AAAA,EACpB,2BAA2B;AAC7B;AAGO,IAAM,eAAN,cAA2B,MAAM;AAAA,EAEtC,YACW,MACT,SACA;AACA,UAAM,OAAO;AAHJ;AAIT,SAAK,OAAO;AACZ,SAAK,SAAS,eAAe,IAAI;AAAA,EACnC;AAAA,EANW;AAAA,EAFF;AASX;","names":[]}