@krizaka/credits 0.1.4 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # @krizaka/credits
 
-**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`), 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.
+**One credits ledger for every Krizaka product.** It replaces three models: Verikora's `audit_credits` and `free_audit_used_at` columns on `accounts` (`reserveAudit` / `releaseAudit` / `refundFailedAudit`), 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.
 
@@ -15,13 +15,31 @@ const credits = createCredits({ clock, settings: () => readCreditsSettings((key)
 
 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}` });
+  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}` });
+  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}` });
+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
 ```
 
@@ -33,7 +51,7 @@ await credits.refund(tx, { accountId, consumed: `audit-${auditId}`, reason: "the
   - 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).
+    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.
@@ -45,6 +63,6 @@ await credits.refund(tx, { accountId, consumed: `audit-${auditId}`, reason: "the
 - **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)
+## Adopting it (Verikora)
 
-`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.
+`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 Verikora's 402), `releaseAudit` and `refundFailedAudit` a `refund` of the consume key.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krizaka/credits",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "One credits ledger for every Krizaka product: grants that expire with daily and monthly caps, purchases, debits, refunds, holds. Append-only; the balance is derived. Concurrent consumption never goes negative and never spends twice. No database client, no wall clock.",
   "keywords": [
     "krizaka",
@@ -56,13 +56,13 @@
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
     "zod": "^4.6.7",
-    "@krizaka/config": "^0.20.0"
+    "@krizaka/config": "^0.21.0"
   },
   "dependencies": {
     "@krizaka/intl": "^0.4.1",
     "@krizaka/db": "^0.3.1",
     "@krizaka/time": "^0.2.0",
-    "@krizaka/settings": "^0.6.0"
+    "@krizaka/settings": "^0.7.0"
   },
   "peerDependencies": {
     "vitest": ">=4",