@adriangalilea/utils 0.17.1 → 0.19.0

package/dist/bot/payments/schemas.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Runtime schemas for the persisted ledger records. Wired into
+ * `stores.ts` as the optional validator on `botRecord<T>` — every read
+ * from storage gets `.parse()`'d, so a corrupted Redis record throws
+ * a clear `SourcedError({ source: 'storage', operation: 'validate' })`
+ * instead of NaN-ing downstream.
+ *
+ * Why zod? It's the canonical TS validator with the right API surface
+ * (`{ parse(data): T }`). The library's `RecordValidator<T>` type is
+ * structural, so swapping to valibot / ArkType / a hand-rolled guard
+ * just works — but zod is what we ship the default with.
+ *
+ * Schemas mirror the TS types in `types.ts` 1:1. Keep them in sync; the
+ * type system enforces that via the `z.infer<>` round-trip — if a
+ * schema drifts from the type, `satisfies ZodType<X>` on each export
+ * blows up. We use `satisfies` (not `as`) so the TS error points at the
+ * mismatch, not the assertion.
+ */
+import { z } from "zod";
+/**
+ * `ChargeRecord` schema. Mutable fields stay loose-typed (zod doesn't
+ * enforce readonly the way TS does) but every field is structurally
+ * present.
+ */
+export declare const chargeRecordSchema: z.ZodObject<{
+    chargeId: z.ZodString;
+    userId: z.ZodNumber;
+    productKey: z.ZodString;
+    xtr: z.ZodNumber;
+    receivedAt: z.ZodNumber;
+    payload: z.ZodString;
+    waiverSnapshot: z.ZodObject<{
+        at: z.ZodNumber;
+        version: z.ZodString;
+        locale: z.ZodString;
+    }, z.core.$strip>;
+    subscriptionExpiresAt: z.ZodOptional<z.ZodNumber>;
+    creditsGranted: z.ZodNumber;
+    vipRung: z.ZodOptional<z.ZodNumber>;
+    perkKey: z.ZodOptional<z.ZodString>;
+    paysupportState: z.ZodEnum<{
+        none: "none";
+        opened: "opened";
+        refunded: "refunded";
+    }>;
+    refundedAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    payoutBatchId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const payoutRecordSchema: z.ZodObject<{
+    batchId: z.ZodString;
+    fromMs: z.ZodNumber;
+    toMs: z.ZodNumber;
+    tonAmount: z.ZodNumber;
+    eurAtReceipt: z.ZodNumber;
+    recordedAt: z.ZodNumber;
+    facturaNumber: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/bot/payments/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;iBAeK,CAAC;AAErC,eAAO,MAAM,kBAAkB;;;;;;;;iBAQK,CAAC"}

package/dist/bot/payments/schemas.js

@@ -0,0 +1,55 @@
+/**
+ * Runtime schemas for the persisted ledger records. Wired into
+ * `stores.ts` as the optional validator on `botRecord<T>` — every read
+ * from storage gets `.parse()`'d, so a corrupted Redis record throws
+ * a clear `SourcedError({ source: 'storage', operation: 'validate' })`
+ * instead of NaN-ing downstream.
+ *
+ * Why zod? It's the canonical TS validator with the right API surface
+ * (`{ parse(data): T }`). The library's `RecordValidator<T>` type is
+ * structural, so swapping to valibot / ArkType / a hand-rolled guard
+ * just works — but zod is what we ship the default with.
+ *
+ * Schemas mirror the TS types in `types.ts` 1:1. Keep them in sync; the
+ * type system enforces that via the `z.infer<>` round-trip — if a
+ * schema drifts from the type, `satisfies ZodType<X>` on each export
+ * blows up. We use `satisfies` (not `as`) so the TS error points at the
+ * mismatch, not the assertion.
+ */
+import { z } from "zod";
+const waiverRecordSchema = z.object({
+    at: z.number(),
+    version: z.string(),
+    locale: z.string(),
+});
+/**
+ * `ChargeRecord` schema. Mutable fields stay loose-typed (zod doesn't
+ * enforce readonly the way TS does) but every field is structurally
+ * present.
+ */
+export const chargeRecordSchema = z.object({
+    chargeId: z.string(),
+    userId: z.number(),
+    productKey: z.string(),
+    xtr: z.number(),
+    receivedAt: z.number(),
+    payload: z.string(),
+    waiverSnapshot: waiverRecordSchema,
+    subscriptionExpiresAt: z.number().optional(),
+    creditsGranted: z.number(),
+    vipRung: z.number().optional(),
+    perkKey: z.string().optional(),
+    paysupportState: z.enum(["none", "opened", "refunded"]),
+    refundedAt: z.number().nullable().optional(),
+    payoutBatchId: z.string().nullable().optional(),
+});
+export const payoutRecordSchema = z.object({
+    batchId: z.string(),
+    fromMs: z.number(),
+    toMs: z.number(),
+    tonAmount: z.number(),
+    eurAtReceipt: z.number(),
+    recordedAt: z.number(),
+    facturaNumber: z.string().optional(),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/bot/payments/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/bot/payments/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAmC,CAAC;AAErC;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,cAAc,EAAE,kBAAkB;IAClC,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,eAAe,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IACvD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC5C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC/C,CAAmC,CAAC;AAErC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACpC,CAAmC,CAAC"}

package/dist/bot/payments/state.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Pure state computation over the charge log.
+ *
+ * This file is `state.ts` (not `derive.ts`) because gramio's `derive`
+ * concept is reserved for ctx decoration (see `derive.ts` alongside,
+ * which builds `ctx.payments`). The reducers here are bot-id and ctx
+ * agnostic — they take `ChargeRecord[]` and a session-shaped object
+ * and mutate the session in place.
+ *
+ * The charge log (`pay:charge:{chargeId}`) is the single source of truth
+ * (CLAUDE.md §"Storage layout"). Session state is a cache for O(1)
+ * runtime checks. This module owns the function that rebuilds the cache
+ * from the log.
+ *
+ * Two surfaces:
+ *
+ *   `deriveState(charges)`     — pure, reduces a chronological list of
+ *                                NON-refunded charges into the cache
+ *                                shape. Used by reconcile and refund
+ *                                (after marking the refunded charge).
+ *
+ *   `applyCharge(session, …)`  — incremental, mutates one session record
+ *                                for a single new charge. Used by
+ *                                `handlers.ts` on `successful_payment`.
+ *
+ *   `revertCreditsForCharge(session, charge)` — targeted decrement
+ *                                used by refund (vip/perks are full
+ *                                re-derive territory; credits is not,
+ *                                because consumption isn't in the log).
+ *
+ * Credits balance is **not fully derivable** from the log alone — the
+ * log records grants, not consumption. `deriveState` therefore returns
+ * `totalCreditsGranted` (sum) and callers decide whether to use it as
+ * the balance (reconcile of fresh state) or to ignore (incremental).
+ */
+import type { ChargeRecord, DerivedPaymentsState, PaymentsSession } from "./types.js";
+/**
+ * Result of `deriveState`. `totalCreditsGranted` is informational —
+ * subtract consumption (which isn't logged) for the real balance.
+ */
+export type DeriveResult = DerivedPaymentsState & {
+    readonly totalCreditsGranted: number;
+};
+/**
+ * Pure reducer over a chronological list of charges. Caller is
+ * responsible for filtering out refunded ones if they want
+ * "current state after refunds" semantics.
+ */
+export declare const deriveState: (charges: ReadonlyArray<ChargeRecord>) => DeriveResult;
+/**
+ * Apply a single new charge to a session in place. Idempotent across
+ * `chargeId` because the caller (handlers.ts) guards via the
+ * `pay:idempotency:{chargeId}` sentinel before this fires; we don't
+ * re-check here.
+ *
+ *   - vip:     replaces `session.pay.vip` (renewals update expiresAt;
+ *              tier upgrades replace rung)
+ *   - credits: increments `session.pay.credits` by the granted amount
+ *              (covers both pack purchases AND vip renewal grants)
+ *   - perks:   set-if-absent on `session.pay.perks[key]`
+ */
+export declare const applyCharge: (session: {
+    pay?: PaymentsSession;
+}, charge: ChargeRecord) => void;
+/**
+ * Subtract a refunded charge's `creditsGranted` from the session
+ * balance, clamping at zero. The "clamp at zero" semantics are
+ * deliberate: a user may have already consumed credits when the refund
+ * arrives, and going negative would let them buy back into a debt — we
+ * refuse that and accept the asymmetry (the refunded Stars are already
+ * leaving the bot's balance via `refundStarPayment` either way).
+ */
+export declare const revertCreditsForCharge: (session: {
+    pay?: PaymentsSession;
+}, charge: ChargeRecord) => void;
+/**
+ * Rebuild vip + perks (the fully-derivable parts of session.pay.*)
+ * from a fresh chronological view of the charge log, **after** the
+ * caller has marked any newly-refunded charges. Credits balance is
+ * NOT touched — caller handles that explicitly via
+ * `revertCreditsForCharge` for the targeted decrement semantics.
+ *
+ * Used by:
+ *   - refund.ts after `refundStarPayment` succeeds
+ *   - reconcile (admin command) for full state recovery
+ */
+export declare const rebuildVipAndPerks: (session: {
+    pay?: PaymentsSession;
+}, charges: ReadonlyArray<ChargeRecord>) => void;
+//# sourceMappingURL=state.d.ts.map

package/dist/bot/payments/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EACX,YAAY,EACZ,oBAAoB,EACpB,eAAe,EAGf,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,oBAAoB,GAAG;IACjD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACvB,SAAS,aAAa,CAAC,YAAY,CAAC,KAClC,YAwCF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,GACvB,SAAS;IAAE,GAAG,CAAC,EAAE,eAAe,CAAA;CAAE,EAClC,QAAQ,YAAY,KAClB,IA0BF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GAClC,SAAS;IAAE,GAAG,CAAC,EAAE,eAAe,CAAA;CAAE,EAClC,QAAQ,YAAY,KAClB,IAMF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAC9B,SAAS;IAAE,GAAG,CAAC,EAAE,eAAe,CAAA;CAAE,EAClC,SAAS,aAAa,CAAC,YAAY,CAAC,KAClC,IAMF,CAAC"}

package/dist/bot/payments/state.js

@@ -0,0 +1,149 @@
+/**
+ * Pure state computation over the charge log.
+ *
+ * This file is `state.ts` (not `derive.ts`) because gramio's `derive`
+ * concept is reserved for ctx decoration (see `derive.ts` alongside,
+ * which builds `ctx.payments`). The reducers here are bot-id and ctx
+ * agnostic — they take `ChargeRecord[]` and a session-shaped object
+ * and mutate the session in place.
+ *
+ * The charge log (`pay:charge:{chargeId}`) is the single source of truth
+ * (CLAUDE.md §"Storage layout"). Session state is a cache for O(1)
+ * runtime checks. This module owns the function that rebuilds the cache
+ * from the log.
+ *
+ * Two surfaces:
+ *
+ *   `deriveState(charges)`     — pure, reduces a chronological list of
+ *                                NON-refunded charges into the cache
+ *                                shape. Used by reconcile and refund
+ *                                (after marking the refunded charge).
+ *
+ *   `applyCharge(session, …)`  — incremental, mutates one session record
+ *                                for a single new charge. Used by
+ *                                `handlers.ts` on `successful_payment`.
+ *
+ *   `revertCreditsForCharge(session, charge)` — targeted decrement
+ *                                used by refund (vip/perks are full
+ *                                re-derive territory; credits is not,
+ *                                because consumption isn't in the log).
+ *
+ * Credits balance is **not fully derivable** from the log alone — the
+ * log records grants, not consumption. `deriveState` therefore returns
+ * `totalCreditsGranted` (sum) and callers decide whether to use it as
+ * the balance (reconcile of fresh state) or to ignore (incremental).
+ */
+/**
+ * Pure reducer over a chronological list of charges. Caller is
+ * responsible for filtering out refunded ones if they want
+ * "current state after refunds" semantics.
+ */
+export const deriveState = (charges) => {
+    let vip;
+    const perks = {};
+    let totalCreditsGranted = 0;
+    // Charges are oldest-first by convention. Vip latest-wins by
+    // receivedAt; perks first-wins (an idempotent unlock — buying twice
+    // shouldn't change the unlock date).
+    for (const c of charges) {
+        if (c.paysupportState === "refunded")
+            continue;
+        totalCreditsGranted += c.creditsGranted;
+        if (c.vipRung !== undefined && c.subscriptionExpiresAt !== undefined) {
+            // Replace the active subscription only when this charge is newer
+            // or this is the first vip charge encountered.
+            if (!vip || c.receivedAt >= (vip.expiresAt ?? 0) || c.receivedAt > 0) {
+                vip = {
+                    rung: c.vipRung,
+                    chargeId: c.chargeId,
+                    expiresAt: c.subscriptionExpiresAt,
+                    canceled: false,
+                };
+            }
+        }
+        if (c.perkKey && !perks[c.perkKey]) {
+            perks[c.perkKey] = {
+                chargeId: c.chargeId,
+                at: c.receivedAt,
+            };
+        }
+    }
+    return {
+        credits: totalCreditsGranted,
+        vip,
+        perks,
+        totalCreditsGranted,
+    };
+};
+/**
+ * Apply a single new charge to a session in place. Idempotent across
+ * `chargeId` because the caller (handlers.ts) guards via the
+ * `pay:idempotency:{chargeId}` sentinel before this fires; we don't
+ * re-check here.
+ *
+ *   - vip:     replaces `session.pay.vip` (renewals update expiresAt;
+ *              tier upgrades replace rung)
+ *   - credits: increments `session.pay.credits` by the granted amount
+ *              (covers both pack purchases AND vip renewal grants)
+ *   - perks:   set-if-absent on `session.pay.perks[key]`
+ */
+export const applyCharge = (session, charge) => {
+    session.pay ??= {};
+    const pay = session.pay;
+    if (charge.creditsGranted > 0) {
+        pay.credits = (pay.credits ?? 0) + charge.creditsGranted;
+    }
+    if (charge.vipRung !== undefined &&
+        charge.subscriptionExpiresAt !== undefined) {
+        pay.vip = {
+            rung: charge.vipRung,
+            chargeId: charge.chargeId,
+            expiresAt: charge.subscriptionExpiresAt,
+            canceled: false,
+        };
+    }
+    if (charge.perkKey) {
+        pay.perks ??= {};
+        if (!pay.perks[charge.perkKey]) {
+            pay.perks[charge.perkKey] = {
+                chargeId: charge.chargeId,
+                at: charge.receivedAt,
+            };
+        }
+    }
+};
+/**
+ * Subtract a refunded charge's `creditsGranted` from the session
+ * balance, clamping at zero. The "clamp at zero" semantics are
+ * deliberate: a user may have already consumed credits when the refund
+ * arrives, and going negative would let them buy back into a debt — we
+ * refuse that and accept the asymmetry (the refunded Stars are already
+ * leaving the bot's balance via `refundStarPayment` either way).
+ */
+export const revertCreditsForCharge = (session, charge) => {
+    if (!charge.creditsGranted)
+        return;
+    session.pay ??= {};
+    const pay = session.pay;
+    const current = pay.credits ?? 0;
+    pay.credits = Math.max(0, current - charge.creditsGranted);
+};
+/**
+ * Rebuild vip + perks (the fully-derivable parts of session.pay.*)
+ * from a fresh chronological view of the charge log, **after** the
+ * caller has marked any newly-refunded charges. Credits balance is
+ * NOT touched — caller handles that explicitly via
+ * `revertCreditsForCharge` for the targeted decrement semantics.
+ *
+ * Used by:
+ *   - refund.ts after `refundStarPayment` succeeds
+ *   - reconcile (admin command) for full state recovery
+ */
+export const rebuildVipAndPerks = (session, charges) => {
+    const derived = deriveState(charges);
+    session.pay ??= {};
+    const pay = session.pay;
+    pay.vip = derived.vip;
+    pay.perks = derived.perks;
+};
+//# sourceMappingURL=state.js.map

package/dist/bot/payments/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/bot/payments/state.ts"],"names":[],"mappings":"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"}

package/dist/bot/payments/stores.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The plugin's storage layout, in one place.
+ *
+ * Replaces the scattered `chargeKey` / `userChargesIndexKey` /
+ * `idempotencyKey` / `payoutKey` / `payoutsIndexKey` helpers that used
+ * to live in `handlers.ts`, `refund.ts`, `payouts.ts`. Every storage
+ * operation in the plugin goes through one of these handles.
+ *
+ * Built once at plugin construction (in `plugin.ts`) and threaded
+ * through every concern that needs it.
+ */
+import type { Storage } from "@gramio/storage";
+import { botIndex, botRecord, botSentinel } from "../storage.js";
+import type { ChargeRecord, PayoutRecord } from "./types.js";
+export type PaymentsStores = {
+    /** `pay:charge:<chargeId>` — authoritative per-charge record. */
+    readonly charges: ReturnType<typeof botRecord<ChargeRecord>>;
+    /** `pay:idem:<chargeId>` — fulfillment idempotency sentinel. */
+    readonly idempotency: ReturnType<typeof botSentinel>;
+    /**
+     * `pay:user:<userId>:charges` — newest-first cap of chargeIds for
+     * `/refunds` listing + menu history (v2). Factory because the key
+     * is per-user.
+     */
+    readonly userCharges: (userId: number) => ReturnType<typeof botIndex>;
+    /** `pay:payout:<batchId>` — Fragment payout record. */
+    readonly payouts: ReturnType<typeof botRecord<PayoutRecord>>;
+    /** `pay:payouts:index` — newest-first batchIds for export. */
+    readonly payoutsIndex: ReturnType<typeof botIndex>;
+};
+/**
+ * Construct the plugin's storage handles. Called once at plugin
+ * construction; the result is passed into every concern that reads or
+ * writes plugin state.
+ *
+ * Schemas are wired in — every `.get()` on `charges` / `payouts` runs
+ * the corresponding zod schema's `.parse()` and throws a clear
+ * `SourcedError({ source: 'storage', operation: 'validate' })` on a
+ * corrupted record (instead of NaN-ing downstream when the consumer
+ * reads a now-missing field). `idempotency` is a presence-only sentinel
+ * so no schema applies; `*Index` stores `string[]` so likewise.
+ */
+export declare const buildStores: (storage: Storage) => PaymentsStores;
+//# sourceMappingURL=stores.d.ts.map

package/dist/bot/payments/stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/stores.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAO7D,MAAM,MAAM,cAAc,GAAG;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAC7D,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IACrD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;IACtE,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAC7D,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;CACnD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,OAAO,KAAG,cAS7C,CAAC"}

package/dist/bot/payments/stores.js

@@ -0,0 +1,39 @@
+/**
+ * The plugin's storage layout, in one place.
+ *
+ * Replaces the scattered `chargeKey` / `userChargesIndexKey` /
+ * `idempotencyKey` / `payoutKey` / `payoutsIndexKey` helpers that used
+ * to live in `handlers.ts`, `refund.ts`, `payouts.ts`. Every storage
+ * operation in the plugin goes through one of these handles.
+ *
+ * Built once at plugin construction (in `plugin.ts`) and threaded
+ * through every concern that needs it.
+ */
+import { botIndex, botRecord, botSentinel } from "../storage.js";
+import { chargeRecordSchema, payoutRecordSchema } from "./schemas.js";
+/** Cap on the per-user `pay:user:<id>:charges` index. Older charges
+ *  drop off the list but remain in `pay:charge:<id>` for the gestor
+ *  export (which scans charges directly, not the index). */
+const USER_CHARGES_CAP = 100;
+/**
+ * Construct the plugin's storage handles. Called once at plugin
+ * construction; the result is passed into every concern that reads or
+ * writes plugin state.
+ *
+ * Schemas are wired in — every `.get()` on `charges` / `payouts` runs
+ * the corresponding zod schema's `.parse()` and throws a clear
+ * `SourcedError({ source: 'storage', operation: 'validate' })` on a
+ * corrupted record (instead of NaN-ing downstream when the consumer
+ * reads a now-missing field). `idempotency` is a presence-only sentinel
+ * so no schema applies; `*Index` stores `string[]` so likewise.
+ */
+export const buildStores = (storage) => ({
+    charges: botRecord(storage, "pay:charge", chargeRecordSchema),
+    idempotency: botSentinel(storage, "pay:idem"),
+    userCharges: (userId) => botIndex(storage, `pay:user:${userId}:charges`, {
+        capacity: USER_CHARGES_CAP,
+    }),
+    payouts: botRecord(storage, "pay:payout", payoutRecordSchema),
+    payoutsIndex: botIndex(storage, "pay:payouts:index"),
+});
+//# sourceMappingURL=stores.js.map

package/dist/bot/payments/stores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.js","sourceRoot":"","sources":["../../../src/bot/payments/stores.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGtE;;4DAE4D;AAC5D,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAmB7B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAgB,EAAkB,EAAE,CAAC,CAAC;IACjE,OAAO,EAAE,SAAS,CAAe,OAAO,EAAE,YAAY,EAAE,kBAAkB,CAAC;IAC3E,WAAW,EAAE,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7C,WAAW,EAAE,CAAC,MAAc,EAAE,EAAE,CAC/B,QAAQ,CAAC,OAAO,EAAE,YAAY,MAAM,UAAU,EAAE;QAC/C,QAAQ,EAAE,gBAAgB;KAC1B,CAAC;IACH,OAAO,EAAE,SAAS,CAAe,OAAO,EAAE,YAAY,EAAE,kBAAkB,CAAC;IAC3E,YAAY,EAAE,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;CACpD,CAAC,CAAC"}