@krizaka/coupons 0.0.0-stage → 0.1.1

package/dist/coupons-BF-3HFdw.d.ts

@@ -0,0 +1,172 @@
+import { p as CouponSettings, a as AuditPort, F as RateLimitPort, s as CreditsPort, y as OutboxPort, C as CouponStore, A as Actor, N as NewCoupon, j as Coupon, n as CouponPatch, m as CouponFilter, H as RedemptionFilter, G as Redemption, z as Partner, B as PartnerRow, u as DiscountTerms, t as DiscountEffect, i as CheckoutContext, r as CreditEffect, o as CouponRefusal } from './rules-CCd1HhOA.js';
+import { Clock, Query } from '@krizaka/db';
+
+interface CouponsDeps {
+    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: CouponSettings | (() => CouponSettings | Promise<CouponSettings>);
+    /** The trail (`createAudit(...)` of `@krizaka/audit`): every admin change and every redemption is recorded in the caller's transaction. */
+    audit: AuditPort;
+    /** The limiter (`createLimiter(...)` of `@krizaka/rate-limit`): each attempt with a code counts one hit on `COUPON_ATTEMPT_ACTION`. */
+    rateLimit: RateLimitPort;
+    /** The credits ledger (`createCredits(...)` of `@krizaka/credits`): needed for credit coupons. */
+    credits?: CreditsPort;
+    /** The outbox (`createOutbox(...)` of `@krizaka/outbox`): the events are appended in the caller's transaction. */
+    outbox?: OutboxPort;
+    /** The store over a query (a pool or a transaction). Default: the PostgreSQL store on schema `coupons`. */
+    storeFor?: (query: Query) => CouponStore;
+    /** The Postgres schema, when the product renamed the module's (used by the default store). */
+    schema?: string;
+    /** Fresh ids; default random UUIDs. */
+    newId?: () => string;
+}
+/** The system as an actor (a webhook, a sweeper). */
+declare const SYSTEM: Actor;
+/** What the flows and the admin share: the clock, the settings, the store, the trail and the outbox. */
+interface Kernel {
+    deps: CouponsDeps;
+    now(): Date;
+    settings(): Promise<CouponSettings>;
+    store(query: Query): CouponStore;
+    newId(): string;
+    record(tx: Query, actor: Actor, action: string, target: {
+        type: string;
+        id: string;
+    }, detail?: Record<string, unknown>): Promise<void>;
+    announce(tx: Query, type: string, seed: string, payload: Record<string, unknown>): Promise<void>;
+}
+
+interface PartnerInput {
+    displayName: string;
+    contactEmail?: string | null;
+}
+/** The admin's side (ADR-002 §6): coupons and partners, every change audited in the caller's transaction. */
+declare function makeAdmin(k: Kernel): {
+    generateCode: (query: Query) => Promise<string>;
+    create: (tx: Query, actor: Actor, input: NewCoupon) => Promise<Coupon>;
+    update: (tx: Query, actor: Actor, id: string, patch: CouponPatch) => Promise<Coupon>;
+    pause: (tx: Query, actor: Actor, id: string) => Promise<Coupon>;
+    resume: (tx: Query, actor: Actor, id: string) => Promise<Coupon>;
+    archive: (tx: Query, actor: Actor, id: string) => Promise<Coupon>;
+    get: (query: Query, id: string) => Promise<Coupon | null>;
+    list: (query: Query, filter?: Partial<CouponFilter>) => Promise<Coupon[]>;
+    redemptions: (query: Query, filter?: Partial<RedemptionFilter>) => Promise<Redemption[]>;
+    checkPrices: (tx: Query, prices: readonly {
+        plan: string;
+        amountMinor: number;
+        currency: string;
+    }[]) => Promise<string[]>;
+    partners: {
+        create: (tx: Query, actor: Actor, input: PartnerInput) => Promise<Partner>;
+        archive: (tx: Query, actor: Actor, id: string) => Promise<Partner>;
+        restore: (tx: Query, actor: Actor, id: string) => Promise<Partner>;
+        erase: (tx: Query, actor: Actor, id: string) => Promise<Partner>;
+        get: (query: Query, id: string) => Promise<Partner | null>;
+        list: (query: Query, options?: {
+            includeArchived?: boolean;
+            limit?: number;
+            offset?: number;
+        }) => Promise<Partner[]>;
+        export: (query: Query, id: string) => Promise<{
+            partner: Partner;
+            rows: PartnerRow[];
+        }>;
+        report: (tx: Query, actor: Actor, id: string, period?: {
+            from?: Date;
+            to?: Date;
+        }) => Promise<PartnerRow[]>;
+    };
+};
+type CouponAdmin = ReturnType<typeof makeAdmin>;
+
+/** The coupon as a checkout shows it. Never the limits or the partner. */
+interface CouponView {
+    id: string;
+    code: string;
+    kind: Coupon["kind"];
+    purpose: Coupon["purpose"];
+    endsAt: Date | null;
+}
+type Validation = {
+    ok: true;
+    coupon: CouponView;
+    effect: DiscountEffect | CreditEffect;
+} | {
+    ok: false;
+    code: CouponRefusal;
+    retryAfterSeconds?: number;
+};
+interface ApplyInput extends Omit<CheckoutContext, "mode"> {
+    code: string;
+    /** One key per checkout attempt: a replay returns the same reservation. */
+    idempotencyKey: string;
+}
+interface Applied {
+    redemptionId: string;
+    /** The immutable terms for the payments port's `checkout({ discount })`. */
+    discount: DiscountTerms;
+    effect: DiscountEffect;
+    reservedUntil: Date;
+    replayed: boolean;
+}
+interface RedeemInput {
+    /** From the checkout's metadata (`redemption_id`); found first. */
+    redemptionId?: string | null;
+    /** The checkout session's reference; found when the metadata is missing. */
+    checkoutRef?: string | null;
+    /** The payment (a payment intent), or the invoice for a subscription; null for a free checkout. */
+    paymentRef: string | null;
+    amountPaidMinor: number | null;
+    amountDiscountMinor: number;
+    currency: string | null;
+}
+interface CreditRedemption {
+    redemptionId: string;
+    grantId: string;
+    credits: number;
+    expiresAt: Date;
+    replayed: boolean;
+}
+
+/** The coupons of a product (ADR-002 §5.1). Every function takes the `Query` it works through: pass `tx` to join a unit of work. */
+interface Coupons {
+    /** Read-only: what a code would give, or why not. Counts one attempt on the limiter, before any lookup. Never reserves. */
+    validate(query: Query, code: string, context: CheckoutContext): Promise<Validation>;
+    /** Reserves a use of a discount code for a checkout (a short transaction: no network inside), idempotent by key. */
+    apply(tx: Query, input: ApplyInput): Promise<Applied>;
+    /** Stores the provider's session on the reservation and makes it outlive the session. */
+    attachCheckout(tx: Query, redemptionId: string, checkoutRef: string, sessionExpiresAt?: Date | null): Promise<void>;
+    /** On the payment event, in its transaction: confirms the use once. A payment after the release is confirmed anyway (`overLimit`). */
+    redeem(tx: Query, input: RedeemInput): Promise<"confirmed" | "already" | "unknown">;
+    /** Frees an unpaid reservation (a failed session, an expired checkout). `false` when there was none to free. */
+    release(tx: Query, ref: {
+        redemptionId?: string;
+        checkoutRef?: string;
+    }): Promise<boolean>;
+    /** The sweeper: frees the reservations past their deadline. */
+    releaseExpired(tx: Query): Promise<number>;
+    /** A refund (cumulative amount). Gives the use back only on a full refund with `coupons.refundRestoresUse`. */
+    refund(tx: Query, input: {
+        paymentRef?: string | null;
+        invoiceRef?: string | null;
+        amountRefunded: number;
+    }): Promise<"refunded" | "already" | "unknown">;
+    /** Redeems a credit code: the same rules, then a capped grant in the credits ledger, in the same transaction. Idempotent by key. */
+    redeemCredit(tx: Query, input: {
+        code: string;
+        accountId: string;
+        idempotencyKey: string;
+        ip?: string | null;
+        hasPaidBefore?: boolean;
+    }): Promise<CreditRedemption>;
+    /** The admin revokes a credit redemption: what is left of its grant is written off; credits already spent are never taken back. */
+    revoke(tx: Query, actor: Actor, redemptionId: string): Promise<void>;
+    admin: CouponAdmin;
+}
+/**
+ * The coupons of a product.
+ * @param deps the clock, the settings, the trail, the limiter, and optionally the credits ledger, the outbox, the store
+ */
+declare function createCoupons(deps: CouponsDeps): Coupons;
+
+export { type Applied as A, type CouponAdmin as C, type PartnerInput as P, type RedeemInput as R, SYSTEM as S, type Validation as V, type ApplyInput as a, type CouponView as b, type Coupons as c, type CouponsDeps as d, type CreditRedemption as e, createCoupons as f };

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+export { A as Applied, a as ApplyInput, C as CouponAdmin, b as CouponView, c as Coupons, d as CouponsDeps, e as CreditRedemption, P as PartnerInput, R as RedeemInput, S as SYSTEM, V as Validation, f as createCoupons } from './coupons-BF-3HFdw.js';
+import { C as CouponStore } from './rules-CCd1HhOA.js';
+export { A as Actor, a as AuditPort, b as COUPON_ATTEMPT_ACTION, c as COUPON_BOUNDS, d as COUPON_CODE, e as COUPON_DEFAULTS, f as COUPON_ERROR, g as COUPON_STATUS, h as COUPON_STATUS_CODE, i as CheckoutContext, j as Coupon, k as CouponError, l as CouponErrorCode, m as CouponFilter, n as CouponPatch, o as CouponRefusal, p as CouponSettings, q as CouponStatus, r as CreditEffect, s as CreditsPort, D as DURATION, t as DiscountEffect, u as DiscountTerms, v as Duration, K as KIND, w as Kind, N as NewCoupon, O as ON_EXHAUSTED, x as OnExhausted, y as OutboxPort, P as PURPOSE, z as Partner, B as PartnerRow, E as Purpose, R as REDEMPTION_STATUS, F as RateLimitPort, G as Redemption, H as RedemptionFilter, I as RedemptionPatch, J as RedemptionStatus, U as Usage, L as countsAsUse, M as effectOf, Q as generateCode, S as normalizeCode, T as refusalOf, V as termsOf } from './rules-CCd1HhOA.js';
+import * as _krizaka_db from '@krizaka/db';
+import { Query } from '@krizaka/db';
+export { Clock, Query } from '@krizaka/db';
+
+/** The topic the coupons' events are appended to on the outbox. */
+declare const COUPONS_TOPIC = "coupons";
+declare const COUPON_EVENT: {
+    readonly redeemed: "evt.coupon.redeemed.v1";
+    readonly released: "evt.coupon.released.v1";
+    readonly refunded: "evt.coupon.refunded.v1";
+    readonly exhausted: "evt.coupon.exhausted.v1";
+};
+/** A stable UUID (version 5 shaped) from a seed: the same fact announced twice is one outbox message. */
+declare function uuidOf(seed: string): string;
+/** The JSON Schema of each event's payload. `evt.coupon.redeemed.v1` is the hook of the later commissions module: it carries the partner and the amounts. */
+declare const COUPON_EVENT_SCHEMAS: {
+    readonly "evt.coupon.redeemed.v1": {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["redemptionId", "couponId", "kind", "purpose", "partnerId", "amountPaidMinor", "amountDiscountMinor", "currency", "credits", "overLimit"];
+        readonly properties: {
+            readonly redemptionId: {
+                readonly type: "string";
+            };
+            readonly couponId: {
+                readonly type: "string";
+            };
+            readonly kind: {
+                readonly enum: readonly ["discount", "credit"];
+            };
+            readonly purpose: {
+                readonly enum: readonly ["partner", "promo", "demo", "support"];
+            };
+            readonly partnerId: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly amountPaidMinor: {
+                readonly type: readonly ["integer", "null"];
+            };
+            readonly amountDiscountMinor: {
+                readonly type: readonly ["integer", "null"];
+            };
+            readonly currency: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly credits: {
+                readonly type: readonly ["integer", "null"];
+            };
+            readonly overLimit: {
+                readonly type: "boolean";
+            };
+        };
+    };
+    readonly "evt.coupon.released.v1": {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["redemptionId", "couponId"];
+        readonly properties: {
+            readonly redemptionId: {
+                readonly type: "string";
+            };
+            readonly couponId: {
+                readonly type: "string";
+            };
+        };
+    };
+    readonly "evt.coupon.refunded.v1": {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["redemptionId", "couponId", "partnerId", "amountRefundedMinor", "currency", "useRestored"];
+        readonly properties: {
+            readonly redemptionId: {
+                readonly type: "string";
+            };
+            readonly couponId: {
+                readonly type: "string";
+            };
+            readonly partnerId: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly amountRefundedMinor: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+            readonly currency: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly useRestored: {
+                readonly type: "boolean";
+            };
+        };
+    };
+    readonly "evt.coupon.exhausted.v1": {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["couponId", "partnerId"];
+        readonly properties: {
+            readonly couponId: {
+                readonly type: "string";
+            };
+            readonly partnerId: {
+                readonly type: readonly ["string", "null"];
+            };
+        };
+    };
+};
+
+/**
+ * An in-memory store, for unit tests and demos: the same behaviour as the database's (the contract kit runs on both) except that
+ * `forUpdate` locks nothing, because it has no transaction to hold a lock in. Concurrency is proved on PostgreSQL.
+ */
+declare function memoryCouponStore(): CouponStore;
+
+/**
+ * The PostgreSQL store of coupons, in schema `coupons` (see `couponsSchema`), over the `Query` it is given: the caller's
+ * transaction, so the work commits or rolls back with the product's. `couponByKey(…, true)` is `SELECT … FOR UPDATE`: the last use of a
+ * code is taken by one request at a time. The guarded transition of `updateRedemption` is one `UPDATE … WHERE status = ANY(…)`.
+ * Times come from the caller (the injected clock), never from the database's `now()`.
+ * @param schema the Postgres schema of the module, default `coupons`
+ */
+declare function dbCouponStore(query: Query, schema?: string): CouponStore;
+
+/**
+ * The tables of « coupons » (ADR-002), in their own Postgres schema: `partner` (a person who sells for us: a name and an optional
+ * e-mail, erasable), `coupon` (the code, its window, its limits and its terms: a discount or capped credits) and `redemption` (a use:
+ * reserved, confirmed, released or revoked, with the amounts and the provider's references). The one product table referenced is the
+ * owner (`owner`, the account table): a deleted account leaves its redemptions (`ON DELETE SET NULL`), because uses and revenue stay.
+ * Version 1 is frozen once released: a change is version 2.
+ */
+declare const couponsSchema: _krizaka_db.ModuleSchema;
+
+export { COUPONS_TOPIC, COUPON_EVENT, COUPON_EVENT_SCHEMAS, CouponStore, couponsSchema, dbCouponStore, memoryCouponStore, uuidOf };

package/dist/index.js

@@ -0,0 +1,63 @@
+import {
+  COUPONS_TOPIC,
+  COUPON_EVENT,
+  COUPON_EVENT_SCHEMAS,
+  SYSTEM,
+  couponsSchema,
+  createCoupons,
+  dbCouponStore,
+  memoryCouponStore,
+  uuidOf
+} from "./chunk-ECCGFGSV.js";
+import {
+  COUPON_ATTEMPT_ACTION,
+  COUPON_BOUNDS,
+  COUPON_CODE,
+  COUPON_DEFAULTS,
+  COUPON_ERROR,
+  COUPON_STATUS,
+  COUPON_STATUS_CODE,
+  CouponError,
+  DURATION,
+  KIND,
+  ON_EXHAUSTED,
+  PURPOSE,
+  REDEMPTION_STATUS,
+  countsAsUse,
+  effectOf,
+  generateCode,
+  normalizeCode,
+  refusalOf,
+  termsOf
+} from "./chunk-JMQO6PTK.js";
+export {
+  COUPONS_TOPIC,
+  COUPON_ATTEMPT_ACTION,
+  COUPON_BOUNDS,
+  COUPON_CODE,
+  COUPON_DEFAULTS,
+  COUPON_ERROR,
+  COUPON_EVENT,
+  COUPON_EVENT_SCHEMAS,
+  COUPON_STATUS,
+  COUPON_STATUS_CODE,
+  CouponError,
+  DURATION,
+  KIND,
+  ON_EXHAUSTED,
+  PURPOSE,
+  REDEMPTION_STATUS,
+  SYSTEM,
+  countsAsUse,
+  couponsSchema,
+  createCoupons,
+  dbCouponStore,
+  effectOf,
+  generateCode,
+  memoryCouponStore,
+  normalizeCode,
+  refusalOf,
+  termsOf,
+  uuidOf
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}