@krizaka/coupons 0.0.0-stage → 0.1.0

package/dist/rules-CCd1HhOA.d.ts

@@ -0,0 +1,408 @@
+import { Query } from '@krizaka/db';
+
+/**
+ * The ports of « coupons » (ADR-002): discount and credit coupons that the admin manages, with the product's database as the source
+ * of truth. Generic: no product import, no vendor, no database client (a `Query` comes in), no wall clock (a `Clock` comes in), no
+ * network. The provider is `@krizaka/payments`' port (this module hands it immutable DiscountTerms); credits are
+ * `@krizaka/credits`' ledger; the audit trail, the outbox and the limiter are structural ports, so this package depends on none of them.
+ */
+
+declare const KIND: {
+    readonly discount: "discount";
+    readonly credit: "credit";
+};
+type Kind = (typeof KIND)[keyof typeof KIND];
+/** Why the coupon exists: a person who sells for us, a public promotion, a demo, a support gesture. */
+declare const PURPOSE: {
+    readonly partner: "partner";
+    readonly promo: "promo";
+    readonly demo: "demo";
+    readonly support: "support";
+};
+type Purpose = (typeof PURPOSE)[keyof typeof PURPOSE];
+/** Stored states. « Not started », « expired » and « exhausted » are COMPUTED from the dates and the uses, so no cron is needed. */
+declare const COUPON_STATUS: {
+    readonly active: "active";
+    readonly paused: "paused";
+    readonly archived: "archived";
+};
+type CouponStatus = (typeof COUPON_STATUS)[keyof typeof COUPON_STATUS];
+declare const REDEMPTION_STATUS: {
+    readonly reserved: "reserved";
+    readonly confirmed: "confirmed";
+    readonly released: "released";
+    readonly revoked: "revoked";
+};
+type RedemptionStatus = (typeof REDEMPTION_STATUS)[keyof typeof REDEMPTION_STATUS];
+declare const DURATION: {
+    readonly once: "once";
+    readonly repeating: "repeating";
+    readonly forever: "forever";
+};
+type Duration = (typeof DURATION)[keyof typeof DURATION];
+declare const ON_EXHAUSTED: {
+    readonly stop: "stop";
+    readonly fallbackPaid: "fallback_paid";
+};
+type OnExhausted = (typeof ON_EXHAUSTED)[keyof typeof ON_EXHAUSTED];
+/** The terms a provider adapter needs to apply a discount: vendor-free, IMMUTABLE per `(couponId, termsVersion)` (`@krizaka/payments`' `DiscountTerms`). */
+interface DiscountTerms {
+    couponId: string;
+    termsVersion: number;
+    percentOffBp?: number;
+    amountOffMinor?: number;
+    currency?: string;
+    duration: Duration;
+    durationMonths?: number;
+}
+interface Coupon {
+    id: string;
+    /** As the admin typed it. */
+    code: string;
+    /** Normalised (upper case, no spaces or hyphens): the lookup key, unique in the product. */
+    codeKey: string;
+    kind: Kind;
+    purpose: Purpose;
+    partnerId: string | null;
+    status: CouponStatus;
+    startsAt: Date;
+    endsAt: Date | null;
+    maxRedemptions: number | null;
+    maxPerAccount: number;
+    newCustomersOnly: boolean;
+    /** Plan kinds of the product; empty = all. */
+    plans: string[];
+    percentOffBp: number | null;
+    amountOffMinor: number | null;
+    currency: string | null;
+    duration: Duration | null;
+    durationMonths: number | null;
+    minimumMinor: number | null;
+    credits: number | null;
+    capPerDay: number | null;
+    capPerMonth: number | null;
+    creditsValidDays: number | null;
+    onExhausted: OnExhausted | null;
+    termsVersion: number;
+    createdAt: Date;
+    createdBy: string | null;
+    updatedAt: Date;
+}
+interface Partner {
+    id: string;
+    /** Null once erased (Loi 25). */
+    displayName: string | null;
+    contactEmail: string | null;
+    status: "active" | "archived";
+    createdAt: Date;
+    createdBy: string | null;
+    erasedAt: Date | null;
+}
+interface Redemption {
+    id: string;
+    couponId: string;
+    /** Null once the account was deleted: the use still counts and the revenue stays. */
+    accountId: string | null;
+    /** Copied at redemption: attribution never moves. */
+    partnerId: string | null;
+    status: RedemptionStatus;
+    idempotencyKey: string;
+    reservedUntil: Date | null;
+    checkoutRef: string | null;
+    paymentRef: string | null;
+    amountPaidMinor: number | null;
+    amountDiscountMinor: number | null;
+    /** CUMULATIVE, partial or full. */
+    amountRefundedMinor: number;
+    /** A full refund gave the use back (the setting). */
+    useRestored: boolean;
+    currency: string | null;
+    creditGrantId: string | null;
+    /** A late payment honoured past a limit. */
+    overLimit: boolean;
+    createdAt: Date;
+    confirmedAt: Date | null;
+    endedAt: Date | null;
+}
+/** What a guarded update may change. */
+type RedemptionPatch = Partial<Pick<Redemption, "status" | "reservedUntil" | "checkoutRef" | "paymentRef" | "amountPaidMinor" | "amountDiscountMinor" | "amountRefundedMinor" | "useRestored" | "currency" | "creditGrantId" | "overLimit" | "confirmedAt" | "endedAt">>;
+/** What a coupon's terms and rules may be changed to (the admin's update). */
+type CouponPatch = Partial<Omit<Coupon, "id" | "codeKey" | "createdAt" | "createdBy" | "updatedAt" | "kind">>;
+interface Usage {
+    /** Uses that count overall. */
+    total: number;
+    /** Uses that count for the account. */
+    account: number;
+}
+interface CouponFilter {
+    status?: CouponStatus;
+    kind?: Kind;
+    purpose?: Purpose;
+    partnerId?: string;
+    limit: number;
+    offset: number;
+}
+interface RedemptionFilter {
+    couponId?: string;
+    partnerId?: string;
+    status?: RedemptionStatus;
+    from?: Date;
+    to?: Date;
+    limit: number;
+    offset: number;
+}
+/** One row of the partner view: a coupon's uses in a period, in one currency. Never a customer's identity. */
+interface PartnerRow {
+    couponId: string;
+    code: string;
+    currency: string | null;
+    redemptions: number;
+    discountMinor: number;
+    /** Paid minus refunded. */
+    revenueMinor: number;
+    creditsGranted: number;
+}
+/** Where coupons live. Every adapter runs `couponsContract` (`@krizaka/coupons/testkit`). Times come from the caller. */
+interface CouponStore {
+    insertCoupon(coupon: Coupon): Promise<void>;
+    /** `forUpdate` locks the row until the transaction ends: the last use is taken by one request at a time. */
+    couponById(id: string, forUpdate?: boolean): Promise<Coupon | null>;
+    couponByKey(codeKey: string, forUpdate?: boolean): Promise<Coupon | null>;
+    updateCoupon(id: string, patch: CouponPatch, at: Date): Promise<Coupon | null>;
+    listCoupons(filter: CouponFilter): Promise<Coupon[]>;
+    /** Whether any redemption (even released) exists: the terms are locked once there is one. */
+    hasRedemptions(couponId: string): Promise<boolean>;
+    insertPartner(partner: Partner): Promise<void>;
+    partnerById(id: string): Promise<Partner | null>;
+    updatePartner(id: string, patch: Partial<Pick<Partner, "displayName" | "contactEmail" | "status" | "erasedAt">>): Promise<Partner | null>;
+    listPartners(options: {
+        includeArchived: boolean;
+        limit: number;
+        offset: number;
+    }): Promise<Partner[]>;
+    insertRedemption(redemption: Redemption): Promise<void>;
+    redemptionById(id: string): Promise<Redemption | null>;
+    redemptionByKey(idempotencyKey: string): Promise<Redemption | null>;
+    redemptionByCheckoutRef(checkoutRef: string): Promise<Redemption | null>;
+    redemptionByPaymentRef(paymentRef: string): Promise<Redemption | null>;
+    /** The guarded transition: applies the patch only if the redemption is in one of `from`. Answers the new row, or null when the guard failed. */
+    updateRedemption(id: string, from: readonly RedemptionStatus[] | null, patch: RedemptionPatch): Promise<Redemption | null>;
+    /** The uses that count (see `countsAsUse`), overall and for the account, at `now`. */
+    usage(couponId: string, accountId: string | null, now: Date): Promise<Usage>;
+    listRedemptions(filter: RedemptionFilter): Promise<Redemption[]>;
+    /** Releases the reservations past `reserved_until` and answers them. */
+    releaseExpired(now: Date, limit: number): Promise<Redemption[]>;
+    partnerReport(partnerId: string, period: {
+        from?: Date;
+        to?: Date;
+    }, now: Date): Promise<PartnerRow[]>;
+    /** Active coupons with a fixed amount (for `checkPrices`). */
+    activeAmountCoupons(): Promise<Coupon[]>;
+}
+/** The knobs of the module, read from the admin's settings (`@krizaka/coupons/settings`). */
+interface CouponSettings {
+    /** Shows the field and accepts codes. */
+    enabled: boolean;
+    /** How long a checkout holds a use (40 to 1440 minutes: the provider's session window). */
+    reservationMinutes: number;
+    attemptsPerAccountPerHour: number;
+    attemptsPerIpPerHour: number;
+    minCodeLength: number;
+    generatedCodeLength: number;
+    /** The highest percent a discount may have (1 to 99). */
+    maxPercentOff: number;
+    /** A full refund gives the use back. */
+    refundRestoresUse: boolean;
+}
+/** Who acts (for the audit trail). */
+interface Actor {
+    id: string | null;
+    label: string;
+}
+/** The trail (`@krizaka/audit`'s `Audit`), structurally. */
+interface AuditPort {
+    record(query: Query, entry: {
+        actorId: string | null;
+        actorLabel: string;
+        action: string;
+        target?: {
+            type: string;
+            id: string;
+        } | null;
+        detail?: Record<string, unknown>;
+    }): Promise<void>;
+}
+/** The outbox (`@krizaka/outbox`'s `Outbox`), structurally. */
+interface OutboxPort {
+    append(tx: Query, message: {
+        topic: string;
+        type: string;
+        payload: unknown;
+        id?: string;
+    }): Promise<{
+        id: string;
+        appended: boolean;
+    }>;
+}
+/** The limiter (`@krizaka/rate-limit`'s `Limiter`), structurally. */
+interface RateLimitPort {
+    check(action: string, keys: {
+        ip?: string | null | undefined;
+        subject?: string | null | undefined;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        retryAfterSeconds: number;
+    }>;
+}
+/** The credits ledger (`@krizaka/credits`' `Credits`), structurally. */
+interface CreditsPort {
+    grant(tx: Query, input: {
+        accountId: string;
+        amount: number;
+        expiresAt: Date;
+        capPerDay?: number | null;
+        capPerMonth?: number | null;
+        onExhausted: OnExhausted;
+        source: string;
+        idempotencyKey: string;
+    }): Promise<{
+        grantId: string;
+        replayed: boolean;
+    }>;
+    expire(tx: Query, grantId: string): Promise<{
+        expired: number;
+    }>;
+}
+/** The refusals of validation and redemption (typed, `as const`). */
+declare const COUPON_CODE: {
+    readonly unknown: "COUPON_UNKNOWN";
+    readonly notStarted: "COUPON_NOT_STARTED";
+    readonly expired: "COUPON_EXPIRED";
+    readonly paused: "COUPON_PAUSED";
+    readonly exhausted: "COUPON_EXHAUSTED";
+    readonly accountLimit: "COUPON_ACCOUNT_LIMIT";
+    readonly newCustomersOnly: "COUPON_NEW_CUSTOMERS_ONLY";
+    readonly notForPlan: "COUPON_NOT_FOR_PLAN";
+    readonly minimum: "COUPON_MINIMUM";
+    readonly currency: "COUPON_CURRENCY";
+    readonly tooLarge: "COUPON_TOO_LARGE";
+    readonly kind: "COUPON_KIND";
+    readonly provider: "COUPON_PROVIDER";
+    readonly rateLimited: "COUPON_RATE_LIMITED";
+    readonly disabled: "COUPON_DISABLED";
+};
+type CouponRefusal = (typeof COUPON_CODE)[keyof typeof COUPON_CODE];
+/** The errors of the admin and of the flows (not refusals of a customer's code). */
+declare const COUPON_ERROR: {
+    readonly badInput: "COUPON_BAD_INPUT";
+    readonly codeTaken: "COUPON_CODE_TAKEN";
+    readonly termsLocked: "COUPON_TERMS_LOCKED";
+    readonly notFound: "COUPON_NOT_FOUND";
+    readonly redemptionNotFound: "COUPON_REDEMPTION_NOT_FOUND";
+    readonly partnerNotFound: "COUPON_PARTNER_NOT_FOUND";
+    readonly keyReused: "COUPON_KEY_REUSED";
+    readonly notRevocable: "COUPON_NOT_REVOCABLE";
+    readonly badSettings: "COUPON_BAD_SETTINGS";
+};
+type CouponErrorCode = (typeof COUPON_ERROR)[keyof typeof COUPON_ERROR];
+/** The HTTP status a route may answer for each refusal or error. */
+declare const COUPON_STATUS_CODE: Record<CouponRefusal | CouponErrorCode, number>;
+/** A refusal thrown by a flow (`apply`, `redeemCredit`): a stable `code`, the HTTP `status`, and `retryAfterSeconds` for a rate limit. */
+declare class CouponError extends Error {
+    readonly code: CouponRefusal | CouponErrorCode;
+    readonly retryAfterSeconds?: number | undefined;
+    readonly status: number;
+    constructor(code: CouponRefusal | CouponErrorCode, message?: string, retryAfterSeconds?: number | undefined);
+}
+
+/** Defaults and bounds of the settings (the admin changes them without a redeploy). `maxPercentOff`'s default is Oussama's call (krizaka-ts#61). */
+declare const COUPON_DEFAULTS: CouponSettings;
+/** The action name of the limiter for attempts with a code: each `validate`, `apply` and `redeemCredit` counts one hit. */
+declare const COUPON_ATTEMPT_ACTION = "couponAttempt";
+/** [min, max] of each numeric setting. */
+declare const COUPON_BOUNDS: {
+    readonly reservationMinutes: readonly [40, 1440];
+    readonly attemptsPerAccountPerHour: readonly [1, 100];
+    readonly attemptsPerIpPerHour: readonly [1, 500];
+    readonly minCodeLength: readonly [4, 40];
+    readonly generatedCodeLength: readonly [8, 20];
+    readonly maxPercentOff: readonly [1, 99];
+};
+/**
+ * The lookup key of a code: upper case, without spaces, hyphens or underscores, so « summer-2026 », « SUMMER 2026 » and « Summer2026 »
+ * are one code. A code is then letters and digits only.
+ * @returns the key, or null when what is left is empty, too long or not letters and digits
+ */
+declare function normalizeCode(input: string): string | null;
+/** A random code of `length` characters from an alphabet without I, L, O, U (about 5 bits each). */
+declare function generateCode(length: number, pick?: (max: number) => number): string;
+/** Whether a redemption consumes a use at `now`: confirmed or revoked and not restored, or reserved and not yet past its deadline. */
+declare function countsAsUse(r: Pick<Redemption, "status" | "useRestored" | "reservedUntil">, now: Date): boolean;
+/** What the person typed and where they are: a checkout (discount codes) or a place that redeems credits (credit codes). */
+interface CheckoutContext {
+    mode: "checkout" | "redeem";
+    accountId: string;
+    /** The plan kind being bought. Checkout only. */
+    plan?: string;
+    /** The price before the discount, in minor units. Checkout only. */
+    amountMinor?: number;
+    currency?: string;
+    /** Whether the account has paid before (from `payments`). */
+    hasPaidBefore?: boolean;
+    /** False when the product's provider cannot apply discounts (CCBill, Segpay). Default true. */
+    providerSupportsDiscounts?: boolean;
+    ip?: string | null;
+}
+interface DiscountEffect {
+    kind: typeof KIND.discount;
+    percentOffBp: number | null;
+    amountOffMinor: number | null;
+    currency: string | null;
+    duration: NonNullable<Coupon["duration"]>;
+    durationMonths: number | null;
+    /** What the first payment loses, in minor units. */
+    discountMinor: number;
+    payableMinor: number;
+}
+interface CreditEffect {
+    kind: typeof KIND.credit;
+    credits: number;
+    capPerDay: number | null;
+    capPerMonth: number | null;
+    validDays: number;
+    onExhausted: NonNullable<Coupon["onExhausted"]>;
+}
+/** What a code gives, in numbers. Informational for a discount: the provider computes the real amount and its taxes. */
+declare function effectOf(coupon: Coupon, amountMinor: number): DiscountEffect | CreditEffect;
+/** The immutable terms a provider adapter turns into its object. */
+declare function termsOf(coupon: Coupon): DiscountTerms;
+/** The first rule a code breaks for a context at `now`, or none. The order is the order of the refusals' table. */
+declare function refusalOf(coupon: Coupon, ctx: CheckoutContext, usage: Usage, now: Date, settings: CouponSettings): CouponRefusal | null;
+/** What the admin gives to create a coupon (the kind decides which terms are required). */
+interface NewCoupon {
+    code: string;
+    kind: Coupon["kind"];
+    purpose: Coupon["purpose"];
+    partnerId?: string | null;
+    startsAt: Date;
+    endsAt?: Date | null;
+    maxRedemptions?: number | null;
+    maxPerAccount?: number;
+    newCustomersOnly?: boolean;
+    plans?: string[];
+    percentOffBp?: number | null;
+    amountOffMinor?: number | null;
+    currency?: string | null;
+    duration?: Coupon["duration"];
+    durationMonths?: number | null;
+    minimumMinor?: number | null;
+    credits?: number | null;
+    capPerDay?: number | null;
+    capPerMonth?: number | null;
+    creditsValidDays?: number | null;
+    onExhausted?: Coupon["onExhausted"];
+}
+
+export { type Actor as A, type PartnerRow as B, type CouponStore as C, DURATION as D, type Purpose as E, type RateLimitPort as F, type Redemption as G, type RedemptionFilter as H, type RedemptionPatch as I, type RedemptionStatus as J, KIND as K, countsAsUse as L, effectOf as M, type NewCoupon as N, ON_EXHAUSTED as O, PURPOSE as P, generateCode as Q, REDEMPTION_STATUS as R, normalizeCode as S, refusalOf as T, type Usage as U, termsOf as V, type AuditPort as a, COUPON_ATTEMPT_ACTION as b, COUPON_BOUNDS as c, COUPON_CODE as d, COUPON_DEFAULTS as e, COUPON_ERROR as f, COUPON_STATUS as g, COUPON_STATUS_CODE as h, type CheckoutContext as i, type Coupon as j, CouponError as k, type CouponErrorCode as l, type CouponFilter as m, type CouponPatch as n, type CouponRefusal as o, type CouponSettings as p, type CouponStatus as q, type CreditEffect as r, type CreditsPort as s, type DiscountEffect as t, type DiscountTerms as u, type Duration as v, type Kind as w, type OnExhausted as x, type OutboxPort as y, type Partner as z };

package/dist/settings.d.ts

@@ -0,0 +1,34 @@
+import * as _krizaka_settings from '@krizaka/settings';
+import { p as CouponSettings } from './rules-CCd1HhOA.js';
+export { b as COUPON_ATTEMPT_ACTION } from './rules-CCd1HhOA.js';
+import '@krizaka/db';
+
+/**
+ * The settings of « coupons », a fragment the product adds to its registry (`@krizaka/coupons/settings`): the admin changes them
+ * without a redeploy, every change audited by the settings service. Global scope only. The zone of the credit caps is
+ * `credits.timeZone` (`@krizaka/credits/settings`).
+ */
+declare const couponSettings: {
+    readonly "coupons.enabled": _krizaka_settings.Def<boolean>;
+    readonly "coupons.reservationMinutes": _krizaka_settings.Def<number>;
+    readonly "coupons.attemptsPerAccountPerHour": _krizaka_settings.Def<number>;
+    readonly "coupons.attemptsPerIpPerHour": _krizaka_settings.Def<number>;
+    readonly "coupons.minCodeLength": _krizaka_settings.Def<number>;
+    readonly "coupons.generatedCodeLength": _krizaka_settings.Def<number>;
+    readonly "coupons.maxPercentOff": _krizaka_settings.Def<number>;
+    readonly "coupons.refundRestoresUse": _krizaka_settings.Def<boolean>;
+};
+type Reader = (key: keyof typeof couponSettings) => boolean | number | undefined | Promise<boolean | number | undefined>;
+/**
+ * The module's settings as `createCoupons` takes them, from the product's accessor (`(key) => service.get(key, ctx)`).
+ * A key the accessor does not know falls back to the default.
+ */
+declare function readCouponSettings(read: Reader): Promise<CouponSettings>;
+
+declare const couponAttemptLimit: (s: Pick<CouponSettings, "attemptsPerAccountPerHour" | "attemptsPerIpPerHour">) => {
+    perIp: number;
+    perSubject: number;
+    windowSeconds: number;
+};
+
+export { couponAttemptLimit, couponSettings, readCouponSettings };

package/dist/settings.js

@@ -0,0 +1,52 @@
+import {
+  COUPON_ATTEMPT_ACTION,
+  COUPON_BOUNDS,
+  COUPON_DEFAULTS
+} from "./chunk-JMQO6PTK.js";
+
+// src/settings.ts
+import { flag, integer } from "@krizaka/settings";
+var int = (key, unit) => integer("coupons", COUPON_DEFAULTS[key], { min: COUPON_BOUNDS[key][0], max: COUPON_BOUNDS[key][1], unit });
+var couponSettings = {
+  "coupons.enabled": flag("coupons", COUPON_DEFAULTS.enabled),
+  "coupons.reservationMinutes": int("reservationMinutes", "minutes"),
+  "coupons.attemptsPerAccountPerHour": int("attemptsPerAccountPerHour", "attempts"),
+  "coupons.attemptsPerIpPerHour": int("attemptsPerIpPerHour", "attempts"),
+  "coupons.minCodeLength": int("minCodeLength", "characters"),
+  "coupons.generatedCodeLength": int("generatedCodeLength", "characters"),
+  "coupons.maxPercentOff": int("maxPercentOff", "percent"),
+  "coupons.refundRestoresUse": flag("coupons", COUPON_DEFAULTS.refundRestoresUse)
+};
+async function readCouponSettings(read) {
+  const number = async (key) => {
+    const value = await read(`coupons.${key}`);
+    return typeof value === "number" ? value : COUPON_DEFAULTS[key];
+  };
+  const bool = async (key) => {
+    const value = await read(`coupons.${key}`);
+    return typeof value === "boolean" ? value : COUPON_DEFAULTS[key];
+  };
+  return {
+    enabled: await bool("enabled"),
+    reservationMinutes: await number("reservationMinutes"),
+    attemptsPerAccountPerHour: await number("attemptsPerAccountPerHour"),
+    attemptsPerIpPerHour: await number("attemptsPerIpPerHour"),
+    minCodeLength: await number("minCodeLength"),
+    generatedCodeLength: await number("generatedCodeLength"),
+    maxPercentOff: await number("maxPercentOff"),
+    refundRestoresUse: await bool("refundRestoresUse")
+  };
+}
+var couponAttemptLimit = (s) => ({
+  perIp: s.attemptsPerIpPerHour,
+  perSubject: s.attemptsPerAccountPerHour,
+  // @fixed: the settings are « per hour », so the window is an hour
+  windowSeconds: 3600
+});
+export {
+  COUPON_ATTEMPT_ACTION,
+  couponAttemptLimit,
+  couponSettings,
+  readCouponSettings
+};
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/settings.ts"],"sourcesContent":["import { flag, integer, type Registry } from \"@krizaka/settings\";\n\nimport type { CouponSettings } from \"./port\";\nimport { COUPON_ATTEMPT_ACTION, COUPON_BOUNDS, COUPON_DEFAULTS } from \"./rules\";\n\nconst int = <K extends keyof typeof COUPON_BOUNDS>(key: K, unit: string) => integer(\"coupons\", COUPON_DEFAULTS[key], { min: COUPON_BOUNDS[key][0], max: COUPON_BOUNDS[key][1], unit });\n\n/**\n * The settings of « coupons », a fragment the product adds to its registry (`@krizaka/coupons/settings`): the admin changes them\n * without a redeploy, every change audited by the settings service. Global scope only. The zone of the credit caps is\n * `credits.timeZone` (`@krizaka/credits/settings`).\n */\nexport const couponSettings = {\n  \"coupons.enabled\": flag(\"coupons\", COUPON_DEFAULTS.enabled),\n  \"coupons.reservationMinutes\": int(\"reservationMinutes\", \"minutes\"),\n  \"coupons.attemptsPerAccountPerHour\": int(\"attemptsPerAccountPerHour\", \"attempts\"),\n  \"coupons.attemptsPerIpPerHour\": int(\"attemptsPerIpPerHour\", \"attempts\"),\n  \"coupons.minCodeLength\": int(\"minCodeLength\", \"characters\"),\n  \"coupons.generatedCodeLength\": int(\"generatedCodeLength\", \"characters\"),\n  \"coupons.maxPercentOff\": int(\"maxPercentOff\", \"percent\"),\n  \"coupons.refundRestoresUse\": flag(\"coupons\", COUPON_DEFAULTS.refundRestoresUse),\n} as const satisfies Registry;\n\ntype Reader = (key: keyof typeof couponSettings) => boolean | number | undefined | Promise<boolean | number | undefined>;\n\n/**\n * The module's settings as `createCoupons` takes them, from the product's accessor (`(key) => service.get(key, ctx)`).\n * A key the accessor does not know falls back to the default.\n */\nexport async function readCouponSettings(read: Reader): Promise<CouponSettings> {\n  const number = async (key: keyof typeof COUPON_BOUNDS): Promise<number> => {\n    const value = await read(`coupons.${key}`);\n    return typeof value === \"number\" ? value : COUPON_DEFAULTS[key];\n  };\n  const bool = async (key: \"enabled\" | \"refundRestoresUse\"): Promise<boolean> => {\n    const value = await read(`coupons.${key}`);\n    return typeof value === \"boolean\" ? value : COUPON_DEFAULTS[key];\n  };\n  return {\n    enabled: await bool(\"enabled\"),\n    reservationMinutes: await number(\"reservationMinutes\"),\n    attemptsPerAccountPerHour: await number(\"attemptsPerAccountPerHour\"),\n    attemptsPerIpPerHour: await number(\"attemptsPerIpPerHour\"),\n    minCodeLength: await number(\"minCodeLength\"),\n    generatedCodeLength: await number(\"generatedCodeLength\"),\n    maxPercentOff: await number(\"maxPercentOff\"),\n    refundRestoresUse: await bool(\"refundRestoresUse\"),\n  };\n}\n\n/** The limit the settings give the attempts action (hourly, per address and per account): `limits: (action) => action === COUPON_ATTEMPT_ACTION ? couponAttemptLimit(settings) : …`. */\nexport { COUPON_ATTEMPT_ACTION };\nexport const couponAttemptLimit = (s: Pick<CouponSettings, \"attemptsPerAccountPerHour\" | \"attemptsPerIpPerHour\">) => ({\n  perIp: s.attemptsPerIpPerHour,\n  perSubject: s.attemptsPerAccountPerHour,\n  // @fixed: the settings are « per hour », so the window is an hour\n  windowSeconds: 3600,\n});\n"],"mappings":";;;;;;;AAAA,SAAS,MAAM,eAA8B;AAK7C,IAAM,MAAM,CAAuC,KAAQ,SAAiB,QAAQ,WAAW,gBAAgB,GAAG,GAAG,EAAE,KAAK,cAAc,GAAG,EAAE,CAAC,GAAG,KAAK,cAAc,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC;AAO9K,IAAM,iBAAiB;AAAA,EAC5B,mBAAmB,KAAK,WAAW,gBAAgB,OAAO;AAAA,EAC1D,8BAA8B,IAAI,sBAAsB,SAAS;AAAA,EACjE,qCAAqC,IAAI,6BAA6B,UAAU;AAAA,EAChF,gCAAgC,IAAI,wBAAwB,UAAU;AAAA,EACtE,yBAAyB,IAAI,iBAAiB,YAAY;AAAA,EAC1D,+BAA+B,IAAI,uBAAuB,YAAY;AAAA,EACtE,yBAAyB,IAAI,iBAAiB,SAAS;AAAA,EACvD,6BAA6B,KAAK,WAAW,gBAAgB,iBAAiB;AAChF;AAQA,eAAsB,mBAAmB,MAAuC;AAC9E,QAAM,SAAS,OAAO,QAAqD;AACzE,UAAM,QAAQ,MAAM,KAAK,WAAW,GAAG,EAAE;AACzC,WAAO,OAAO,UAAU,WAAW,QAAQ,gBAAgB,GAAG;AAAA,EAChE;AACA,QAAM,OAAO,OAAO,QAA2D;AAC7E,UAAM,QAAQ,MAAM,KAAK,WAAW,GAAG,EAAE;AACzC,WAAO,OAAO,UAAU,YAAY,QAAQ,gBAAgB,GAAG;AAAA,EACjE;AACA,SAAO;AAAA,IACL,SAAS,MAAM,KAAK,SAAS;AAAA,IAC7B,oBAAoB,MAAM,OAAO,oBAAoB;AAAA,IACrD,2BAA2B,MAAM,OAAO,2BAA2B;AAAA,IACnE,sBAAsB,MAAM,OAAO,sBAAsB;AAAA,IACzD,eAAe,MAAM,OAAO,eAAe;AAAA,IAC3C,qBAAqB,MAAM,OAAO,qBAAqB;AAAA,IACvD,eAAe,MAAM,OAAO,eAAe;AAAA,IAC3C,mBAAmB,MAAM,KAAK,mBAAmB;AAAA,EACnD;AACF;AAIO,IAAM,qBAAqB,CAAC,OAAmF;AAAA,EACpH,OAAO,EAAE;AAAA,EACT,YAAY,EAAE;AAAA;AAAA,EAEd,eAAe;AACjB;","names":[]}

package/dist/testkit.d.ts

@@ -0,0 +1,60 @@
+import { c as Coupons } from './coupons-BF-3HFdw.js';
+import { p as CouponSettings, s as CreditsPort, N as NewCoupon } from './rules-CCd1HhOA.js';
+export { e as COUPON_DEFAULTS } from './rules-CCd1HhOA.js';
+import { Query } from '@krizaka/db';
+
+/** What a store (through the module) is run against: the module on that store, a clock the test moves, and fakes for its neighbours. */
+interface CouponsHarness {
+    coupons: Coupons;
+    /** The query every call goes through (the transaction; a no-op for memory). */
+    tx: Query;
+    /** Moves the injected clock. */
+    setNow(instant: Date): void;
+    /** Changes the settings the module reads at each call. */
+    setSettings(patch: Partial<CouponSettings>): void;
+    /** A fresh account id (a row in the owner table, when the store has one). */
+    newAccount(): Promise<string>;
+    /** The messages appended to the outbox so far. */
+    announced(): {
+        type: string;
+        id: string | undefined;
+        payload: Record<string, unknown>;
+    }[];
+    /** The audit actions recorded so far, with their target. */
+    audited(): {
+        action: string;
+        target: {
+            type: string;
+            id: string;
+        } | null | undefined;
+        detail: Record<string, unknown> | undefined;
+    }[];
+    /** The credits ledger's calls (a fake, or the real one wrapped to record). */
+    credits: {
+        granted: Parameters<CreditsPort["grant"]>[1][];
+        expired: string[];
+    };
+    /** The limiter: the attempts counted, and a way to refuse the next ones. */
+    limiter: {
+        attempts: {
+            action: string;
+            ip: string | null | undefined;
+            subject: string | null | undefined;
+        }[];
+        refuse(retryAfterSeconds: number | null): void;
+    };
+}
+/** Midday on 26 October 2026 in Toronto: the day the scenarios start on. */
+declare const T0: Date;
+/** A discount of 20 % for three months on a monthly plan. */
+declare const discount: (over?: Partial<NewCoupon>) => NewCoupon;
+/** 20 free audits, at most 5 a day, valid 30 days. */
+declare const credit: (over?: Partial<NewCoupon>) => NewCoupon;
+/**
+ * What every coupons store must do, behind the same module: the window and the refusals, the counting rule of the uses, reservation,
+ * confirmation and release, refunds, credit coupons, partners, the admin. `make` gives an EMPTY module, the clock at {@link T0},
+ * `coupons.enabled` on.
+ */
+declare function couponsContract(name: string, make: () => Promise<CouponsHarness>): void;
+
+export { type CouponsHarness, T0, couponsContract, credit, discount };