@krizaka/credits 0.0.0-stage → 0.1.0

package/dist/credits-Do0guD2C.d.ts

@@ -0,0 +1,258 @@
+import { Query, Clock } from '@krizaka/db';
+import { g as CreditsSettings, e as CreditsCode, j as GrantState, G as Grant, m as OnExhausted, E as Entry, C as CreditStore } from './port-C0Qw77Bp.js';
+
+/** The topic the ledger's events are appended to on the outbox. */
+declare const CREDITS_TOPIC = "credits";
+/** Event types: the names of `krizaka-billing-api`, so a TypeScript product and a Java service speak alike. */
+declare const CREDIT_EVENT: {
+    readonly granted: "evt.credit.granted.v1";
+    readonly exhausted: "evt.credit.exhausted.v1";
+};
+/** The part of `@krizaka/outbox`'s `Outbox` this package needs: structural, so `credits` does not depend on `outbox`. */
+interface OutboxPort {
+    append(tx: Query, message: {
+        topic: string;
+        type: string;
+        payload: unknown;
+        id?: string;
+    }): Promise<{
+        id: string;
+        appended: boolean;
+    }>;
+}
+/** A stable UUID (version 5 shaped) from a seed: announcing the same fact twice is one outbox message. */
+declare function uuidOf(seed: string): string;
+/** The JSON Schema of each event's payload (a consumer validates against it; the Java twin publishes the same names). */
+declare const CREDIT_EVENT_SCHEMAS: {
+    readonly "evt.credit.granted.v1": {
+        readonly required: readonly ["accountId", "grantId", "bucket", "amount", "source", "onExhausted"];
+        readonly properties: {
+            readonly accountId: {
+                readonly type: "string";
+            };
+            readonly grantId: {
+                readonly type: "string";
+            };
+            readonly bucket: {
+                readonly enum: readonly ["granted", "purchased"];
+            };
+            readonly amount: {
+                readonly type: "integer";
+                readonly minimum: 1;
+            };
+            readonly expiresAt: {
+                readonly type: readonly ["string", "null"];
+                readonly format: "date-time";
+            };
+            readonly capPerDay: {
+                readonly type: readonly ["integer", "null"];
+                readonly minimum: 1;
+            };
+            readonly capPerMonth: {
+                readonly type: readonly ["integer", "null"];
+                readonly minimum: 1;
+            };
+            readonly onExhausted: {
+                readonly enum: readonly ["stop", "fallback_paid"];
+            };
+            readonly source: {
+                readonly type: "string";
+            };
+        };
+        readonly type: "object";
+        readonly additionalProperties: false;
+    };
+    readonly "evt.credit.exhausted.v1": {
+        readonly required: readonly ["accountId", "grantId", "bucket", "source", "onExhausted"];
+        readonly properties: {
+            readonly accountId: {
+                readonly type: "string";
+            };
+            readonly grantId: {
+                readonly type: "string";
+            };
+            readonly bucket: {
+                readonly enum: readonly ["granted", "purchased"];
+            };
+            readonly onExhausted: {
+                readonly enum: readonly ["stop", "fallback_paid"];
+            };
+            readonly source: {
+                readonly type: "string";
+            };
+        };
+        readonly type: "object";
+        readonly additionalProperties: false;
+    };
+};
+
+/** How much of one grant a consumption takes. */
+interface Draw {
+    grantId: string;
+    amount: number;
+}
+type Plan = {
+    ok: true;
+    draws: Draw[];
+} | {
+    ok: false;
+    code: CreditsCode;
+};
+/** The defaults and bounds of the settings (the admin changes them without a redeploy). */
+declare const CREDITS_DEFAULTS: CreditsSettings;
+declare const HOLD_TTL_BOUNDS: readonly [30, 86400];
+/**
+ * Plans where `need` credits come from, or says why they cannot. Pure: the same states give the same plan.
+ *
+ * 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
+ * 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
+ * credits do not bypass it); else a `stop` pot that is empty answers `CREDITS_EXHAUSTED`; else the purchased credits give the rest, and
+ * when they cannot, `PAYWALL`. Nothing is partial: the plan covers the whole amount or refuses.
+ * @param states every grant of the account with what is left (`CreditStore.grantStates`)
+ * @param need credits wanted, a positive integer
+ * @param now the injected clock's instant
+ */
+declare function planDraws(states: readonly GrantState[], need: number, now: Date): Plan;
+/** Drops the first `skip` credits of a plan (the ones already held back by active holds), keeping the order. */
+declare function skipFirst(draws: readonly Draw[], skip: number): Draw[];
+
+interface CreditsDeps {
+    clock: Clock;
+    /** The settings, read at each call so the admin's change applies at once: an object, or a function over the settings service. */
+    settings: CreditsSettings | (() => CreditsSettings | Promise<CreditsSettings>);
+    /** The store over a query (a pool or a transaction). Default: the PostgreSQL store on schema `credits`. */
+    storeFor?: (query: Query) => CreditStore;
+    /** The Postgres schema, when the product renamed the module's (used by the default store). */
+    schema?: string;
+    /** Announces `evt.credit.granted.v1` and `evt.credit.exhausted.v1` in the caller's transaction (`createOutbox(...)` of `@krizaka/outbox`). */
+    outbox?: OutboxPort;
+    /** Fresh ids; default random UUIDs. */
+    newId?: () => string;
+}
+interface GrantInput {
+    accountId: string;
+    /** Credits, a positive integer. */
+    amount: number;
+    /** When the pot lapses. Required, in the future. */
+    expiresAt: Date;
+    capPerDay?: number | null;
+    capPerMonth?: number | null;
+    onExhausted: OnExhausted;
+    /** `coupon:<redemptionId>`, `plan:monthly`… */
+    source: string;
+    /** One key per grant: a replay answers the same grant and writes nothing. */
+    idempotencyKey: string;
+}
+interface PurchaseInput {
+    accountId: string;
+    amount: number;
+    /** `purchase:<paymentRef>`. */
+    source: string;
+    idempotencyKey: string;
+}
+interface ConsumeInput {
+    accountId: string;
+    amount: number;
+    /** What it was spent on (`audit:<id>`): kept on the line. */
+    reason: string;
+    idempotencyKey: string;
+}
+interface Consumed {
+    draws: Draw[];
+    /** True when the key was seen before: the first answer is repeated and nothing was written. */
+    replayed: boolean;
+}
+interface Balance {
+    /** What can be spent now (not lapsed, not closed), holds not subtracted. */
+    total: number;
+    granted: number;
+    purchased: number;
+    /** Kept back by active holds. */
+    held: number;
+    /** `total - held`, never negative. */
+    available: number;
+    grants: {
+        id: string;
+        bucket: Grant["bucket"];
+        remaining: number;
+        expiresAt: Date | null;
+        source: string;
+        capPerDay: number | null;
+        capPerMonth: number | null;
+        onExhausted: OnExhausted;
+    }[];
+}
+/** The ledger as a product uses it. Every function takes the `Query` it works through: pass `tx` to join a unit of work. */
+interface Credits {
+    /** Free usage that lapses, with optional caps. Idempotent by key. */
+    grant(tx: Query, input: GrantInput): Promise<{
+        grantId: string;
+        replayed: boolean;
+    }>;
+    /** Paid usage: it does not lapse and has no cap. Idempotent by key. */
+    purchase(tx: Query, input: PurchaseInput): Promise<{
+        grantId: string;
+        replayed: boolean;
+    }>;
+    /** Spends credits from the pots that lapse first, within their caps; refuses with `CREDITS_CAP_DAY`, `CREDITS_CAP_MONTH`, `CREDITS_EXHAUSTED` or `PAYWALL`. Nothing is partial. */
+    consume(tx: Query, input: ConsumeInput): Promise<Consumed>;
+    /** Keeps credits back for work that has not finished; the reserve counts against caps and balance. */
+    hold(tx: Query, input: {
+        accountId: string;
+        amount: number;
+        ttlSeconds?: number;
+        idempotencyKey: string;
+    }): Promise<{
+        holdId: string;
+        expiresAt: Date;
+        replayed: boolean;
+    }>;
+    /** Spends what the work cost (at most the hold's amount; default all of it) and frees the rest. Once. */
+    settle(tx: Query, holdId: string, options?: {
+        amount?: number;
+        reason?: string;
+    }): Promise<Consumed>;
+    /** Frees a hold without spending. Idempotent. */
+    release(tx: Query, holdId: string): Promise<void>;
+    /** Gives back what an earlier consume or settle spent, to the same pots, once. */
+    refund(tx: Query, input: {
+        accountId: string;
+        consumed?: string;
+        settledHold?: string;
+        reason: string;
+    }): Promise<{
+        refunded: number;
+        replayed: boolean;
+    }>;
+    /** Closes a pot: what is left is written off by an EXPIRY line. Credits already spent are never taken back. Idempotent. */
+    expire(tx: Query, grantId: string): Promise<{
+        expired: number;
+    }>;
+    /** Closes the granted pots past their date that still hold credits (a job's sweep). */
+    expireDue(tx: Query, options?: {
+        limit?: number;
+    }): Promise<number>;
+    /** A signed correction by an administrator, never taking a pot below zero. */
+    adjust(tx: Query, input: {
+        accountId: string;
+        grantId: string;
+        amount: number;
+        reason: string;
+        idempotencyKey: string;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    balance(query: Query, accountId: string): Promise<Balance>;
+    history(query: Query, accountId: string, options?: {
+        limit?: number;
+        before?: Date;
+    }): Promise<Entry[]>;
+}
+/**
+ * The credits ledger of a product.
+ * @param deps the clock, the settings, and optionally the store, the schema, the outbox and the id source
+ * @returns the ledger's functions
+ */
+declare function createCredits(deps: CreditsDeps): Credits;
+
+export { type Balance as B, CREDITS_DEFAULTS as C, type Draw as D, type GrantInput as G, HOLD_TTL_BOUNDS as H, type OutboxPort as O, type Plan as P, CREDITS_TOPIC as a, CREDIT_EVENT as b, CREDIT_EVENT_SCHEMAS as c, type ConsumeInput as d, type Consumed as e, type Credits as f, type CreditsDeps as g, type PurchaseInput as h, createCredits as i, planDraws as p, skipFirst as s, uuidOf as u };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+export { B as Balance, C as CREDITS_DEFAULTS, a as CREDITS_TOPIC, b as CREDIT_EVENT, c as CREDIT_EVENT_SCHEMAS, d as ConsumeInput, e as Consumed, f as Credits, g as CreditsDeps, D as Draw, G as GrantInput, H as HOLD_TTL_BOUNDS, O as OutboxPort, P as Plan, h as PurchaseInput, i as createCredits, p as planDraws, s as skipFirst, u as uuidOf } from './credits-Do0guD2C.js';
+import { C as CreditStore, E as Entry } from './port-C0Qw77Bp.js';
+export { B as BUCKET, a as Bucket, b as CREDITS_CODE, c as CREDITS_STATUS, d as Calendar, e as CreditsCode, f as CreditsError, g as CreditsSettings, h as ENTRY_TYPE, i as EntryType, G as Grant, j as GrantState, H as HOLD_STATUS, k as Hold, l as HoldStatus, O as ON_EXHAUSTED, m as OnExhausted } from './port-C0Qw77Bp.js';
+import * as _krizaka_db from '@krizaka/db';
+import { Query } from '@krizaka/db';
+export { Clock, Query } from '@krizaka/db';
+
+/**
+ * An in-memory ledger, for unit tests and demos: the same behaviour as the database's (the contract kit runs on both) except that
+ * `lock` does nothing, because it has no transaction to hold it in. It is for one flow at a time; concurrency is proved on PostgreSQL.
+ */
+declare function memoryCreditStore(): CreditStore & {
+    entries(): readonly Readonly<Entry>[];
+};
+
+/**
+ * The PostgreSQL store of the ledger, in schema `credits` (see `creditsSchema`), over the `Query` it is given: the caller's transaction
+ * for every writing call, so the lines commit or roll back with the product's work. `lock` is `pg_advisory_xact_lock` on the account:
+ * two requests spending the last credit take turns, and the second sees the first's lines. Days and months are cut in the calendar's
+ * IANA zone BY POSTGRES (`AT TIME ZONE`), so daylight-saving shifts are the database's own tz data. Times come from the caller.
+ * @param schema the Postgres schema of the module, default `credits`
+ */
+declare function dbCreditStore(query: Query, schema?: string): CreditStore;
+
+/**
+ * The tables of « credits », in their own Postgres schema (ADR-001 §3), following `krizaka-billing`'s model and names: `grant` (a pot:
+ * `granted` with an expiry and optional caps, or `purchased`), `entry` (the ledger: GRANT, PURCHASE, DEBIT, REFUND, EXPIRY, ADJUSTMENT;
+ * APPEND-ONLY, a trigger refuses any UPDATE or DELETE) and `hold` (credits kept back for work in progress). Nothing stores a balance: what is
+ * left of a pot is the sum of its lines. The one product table referenced is the owner (`owner`: the account table), declared by the product;
+ * an account that has credits is anonymised, never deleted (it is an accounting record), exactly like an invoice.
+ * Version 1 is frozen once released: a change is version 2.
+ */
+declare const creditsSchema: _krizaka_db.ModuleSchema;
+
+export { CreditStore, Entry, creditsSchema, dbCreditStore, memoryCreditStore };