@withwiz/coupon 0.1.0 → 0.3.0

package/README.md

@@ -54,7 +54,12 @@ const campaign = await coupon.campaigns.create({
   endsAt: new Date("2026-04-30"),
   maxCoupons: 10_000,
 });
-await coupon.campaigns.issue({ campaignId: campaign.id, count: 10_000, codeLength: 10 });
+await coupon.campaigns.issue({
+  campaignId: campaign.id,
+  count: 10_000,
+  codeLength: 10,
+  maxRedemptions: 1, // single-use codes; omit for unlimited
+});
 
 // 2) Customer applies a code at checkout (non-destructive preview)
 const preview = await coupon.validate({
@@ -142,10 +147,38 @@ const coupon = createCouponClient({
 });
 ```
 
-Both maps accept plain SQL identifiers only (`[A-Za-z_][A-Za-z0-9_]*`); a
+### Tables outside `public` with a driver adapter
+
+The row lock is raw SQL, so it does not inherit the schema from your Prisma
+datasource. With a driver adapter (Prisma 7, e.g. `@prisma/adapter-pg`) an
+unqualified table name resolves through the connection's `search_path`, which
+is usually `public`. If the coupon tables live in another schema, name it:
+
+```ts
+const coupon = createCouponClient({ prisma, schema: "billing" });
+```
+
+Without it, `redeem()` cannot see the coupon row and fails with `NOT_FOUND`.
+
+`models`, `tables` and `schema` accept plain SQL identifiers only (`[A-Za-z_][A-Za-z0-9_]*`); a
 malformed name raises `InvalidModelNameError` when the client is created, and
 a name that matches no delegate raises it on the first call that needs it.
 
+## Discount duration
+
+A policy may declare how many billing cycles it applies to:
+
+```ts
+discount: { kind: "PERCENT", percent: 20, duration: { kind: "REPEATING", months: 3 } }
+```
+
+`ONCE` (the default when `duration` is absent), `REPEATING` (1 to 36 months) or
+`FOREVER`. The package stores and validates it and returns it inside
+`coupon.discount` and `discount.appliedPolicy`; `resolveDuration(policy)` gives the
+effective value. Redemption still happens once. To discount later cycles of a
+subscription, keep the policy and call `calculateDiscount({ subtotal, currency, policy })`
+for each cycle on your side.
+
 ## Errors
 
 All errors extend `CouponError` and carry a stable string `code`.
@@ -250,6 +283,28 @@ never touch tenantId again.
   no dropped rows.
 - No `$executeRawUnsafe` / `$queryRawUnsafe` is used anywhere in this
   package.
+- **`userId` must come from your authenticated session, never from the
+  request body.** Eligibility (`allowedUserIds`), `maxRedemptionsPerUser` and
+  the duplicate-order guard all key on it. A coupon that sets
+  `maxRedemptionsPerUser` refuses anonymous `validate()` / `redeem()` calls
+  with `ValidationError`, so the cap cannot be bypassed by omitting the user.
+- The idempotency index is `(couponId, redeemedByUserId, orderRef)`. Postgres
+  treats `NULL` as distinct, so **pass `orderRef` on every redeem** if you
+  need double-submit protection; without it, a coupon that has no
+  `maxRedemptionsPerUser` can be redeemed repeatedly by the same user.
+- Caller-supplied strings are bounded: ids and cursors 64 chars, user / actor
+  ids and `orderRef` 128 chars, `metadata` 16 KiB of JSON, eligibility lists
+  1,000 entries of 128 chars. Oversized input throws `ValidationError`
+  before it reaches the database.
+- Only a genuine unique-constraint conflict (Prisma `P2002`) is translated
+  into `CouponAlreadyRedeemedError` / "code already exists". Any other
+  database failure propagates unchanged, so the rejection audit log never
+  records a connection error as `ALREADY_REDEEMED`. The original Prisma
+  error is attached as `error.cause`, never placed in `error.details`.
+- Generated codes use a cryptographic RNG (`nanoid`) over a 31-character
+  alphabet. The default length of 8 gives roughly 2^40 combinations, which is
+  adequate **only behind rate limiting** on your `validate` / `redeem`
+  endpoints; raise `codeLength` for high-value or long-lived coupons.
 
 ## Development
 
@@ -279,6 +334,16 @@ pnpm install --frozen-lockfile
 pnpm run prisma:generate && pnpm run db:push && pnpm run test
 ```
 
+`examples/consumer-prisma7` runs the same kind of checks on Prisma 7 with
+`@prisma/adapter-pg`, a renamed `CouponCampaign` model and a non-`public` schema:
+
+```bash
+cd examples/consumer-prisma7
+export DATABASE_URL="postgresql://postgres:postgres@localhost:13011/coupon_test?schema=consumer_prisma7"
+pnpm install --frozen-lockfile
+pnpm run prisma:generate && pnpm run db:push && pnpm run test
+```
+
 CI provisions its own Postgres on the same port 13011, so the workflow sets
 `DATABASE_URL` itself and does not use `docker-compose.yml`.