@withwiz/coupon 0.1.0 → 0.2.0

package/README.md

@@ -250,6 +250,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
 

package/dist/index.cjs

@@ -55,7 +55,23 @@ var LIMITS = {
   PAGINATION_DEFAULT_LIMIT: 50,
   PAGINATION_MAX_LIMIT: 200,
   NAME_MAX_LENGTH: 200,
-  CURRENCY_LENGTH: 3
+  CURRENCY_LENGTH: 3,
+  /**
+   * [L] Caller-supplied identifier caps. Ids (coupon / campaign / cursor) are
+   * bounded by the audit log's `resourceId VarChar(64)`; `orderRef` by the
+   * redemption table's `VarChar(128)`. User / actor ids share the same bound
+   * so an unbounded string can never reach a Json or text column unchecked.
+   */
+  ID_MAX_LENGTH: 64,
+  USER_ID_MAX_LENGTH: 128,
+  ORDER_REF_MAX_LENGTH: 128,
+  /** [L] Upper bound on serialized `metadata` (bytes of JSON text). */
+  METADATA_MAX_BYTES: 16384,
+  /** [L] Per-list entry cap and per-entry length cap for eligibility rules. */
+  ELIGIBILITY_MAX_ENTRIES: 1e3,
+  ELIGIBILITY_ENTRY_MAX_LENGTH: 128,
+  /** [L] Length cap for `context.plan / productId / categoryId`. */
+  CONTEXT_VALUE_MAX_LENGTH: 128
 };
 var AUDIT_ACTION = {
   COUPON_CREATED: "coupon.created",
@@ -617,6 +633,40 @@ function lockCouponRow(tx, table, couponId, tenantId) {
   });
   return tx.$queryRaw(strings, couponId, tenantId);
 }
+function assertOptionalString(name, value, max) {
+  if (value === void 0 || value === null) return;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ValidationError(`${name} must be a non-empty string`);
+  }
+  if (value.length > max) {
+    throw new ValidationError(`${name} length exceeds max (${max})`);
+  }
+}
+function assertRequiredString(name, value, max) {
+  if (value === void 0 || value === null) {
+    throw new ValidationError(`${name} is required`);
+  }
+  assertOptionalString(name, value, max);
+}
+function assertContext(context) {
+  if (context === void 0 || context === null) return;
+  if (typeof context !== "object" || Array.isArray(context)) {
+    throw new ValidationError("context must be a plain object");
+  }
+  const c = context;
+  assertOptionalString("context.plan", c.plan, LIMITS.CONTEXT_VALUE_MAX_LENGTH);
+  assertOptionalString("context.productId", c.productId, LIMITS.CONTEXT_VALUE_MAX_LENGTH);
+  assertOptionalString("context.categoryId", c.categoryId, LIMITS.CONTEXT_VALUE_MAX_LENGTH);
+}
+function assertCouponStatus(status) {
+  if (status === void 0) return;
+  const allowed = Object.values(COUPON_STATUS);
+  if (typeof status !== "string" || !allowed.includes(status)) {
+    throw new ValidationError(
+      `status must be one of ${allowed.join(", ")}`
+    );
+  }
+}
 function assertTenantId(value) {
   if (typeof value !== "string" || value.length === 0) {
     throw new ValidationError("tenantId is required");
@@ -678,6 +728,17 @@ function assertMetadata(meta) {
       );
     }
   }
+  let serialized;
+  try {
+    serialized = JSON.stringify(rec);
+  } catch {
+    throw new ValidationError("metadata must be JSON-serializable");
+  }
+  if (Buffer.byteLength(serialized, "utf8") > LIMITS.METADATA_MAX_BYTES) {
+    throw new ValidationError(
+      `metadata exceeds max size (${LIMITS.METADATA_MAX_BYTES} bytes)`
+    );
+  }
   return rec;
 }
 function assertPaginationLimit(limit) {
@@ -729,6 +790,16 @@ function assertEligibility(rules) {
         `eligibility.${key} must be an array of non-empty strings`
       );
     }
+    if (v.length > LIMITS.ELIGIBILITY_MAX_ENTRIES) {
+      throw new ValidationError(
+        `eligibility.${key} exceeds max entries (${LIMITS.ELIGIBILITY_MAX_ENTRIES})`
+      );
+    }
+    if (v.some((x) => x.length > LIMITS.ELIGIBILITY_ENTRY_MAX_LENGTH)) {
+      throw new ValidationError(
+        `eligibility.${key} entry exceeds max length (${LIMITS.ELIGIBILITY_ENTRY_MAX_LENGTH})`
+      );
+    }
     out[key] = v;
   }
   return out;
@@ -745,6 +816,9 @@ function validateCreateCouponInput(input) {
   validateDiscountPolicy(input.discount);
   assertDateRange(input.startsAt ?? null, input.endsAt ?? null);
   assertMetadata(input.metadata);
+  assertCouponStatus(input.status);
+  assertOptionalString("campaignId", input.campaignId, LIMITS.ID_MAX_LENGTH);
+  assertOptionalString("actorId", input.actorId, LIMITS.USER_ID_MAX_LENGTH);
   if (input.maxRedemptions !== void 0 && input.maxRedemptions !== null) {
     if (typeof input.maxRedemptions !== "number" || !Number.isInteger(input.maxRedemptions) || input.maxRedemptions <= 0) {
       throw new ValidationError("maxRedemptions must be a positive integer or null");
@@ -780,14 +854,16 @@ function validateIssueBulkInput(input) {
   validateDiscountPolicy(input.discount);
   assertDateRange(input.startsAt ?? null, input.endsAt ?? null);
   assertMetadata(input.metadata);
+  assertOptionalString("campaignId", input.campaignId, LIMITS.ID_MAX_LENGTH);
+  assertOptionalString("actorId", input.actorId, LIMITS.USER_ID_MAX_LENGTH);
 }
 function validateIssueCouponInput(input) {
   if (!input || typeof input !== "object") {
     throw new ValidationError("input must be an object");
   }
-  if (typeof input.couponId !== "string" || input.couponId.length === 0) {
-    throw new ValidationError("couponId is required");
-  }
+  assertRequiredString("couponId", input.couponId, LIMITS.ID_MAX_LENGTH);
+  assertOptionalString("issuedToUserId", input.issuedToUserId, LIMITS.USER_ID_MAX_LENGTH);
+  assertOptionalString("issuedBy", input.issuedBy, LIMITS.USER_ID_MAX_LENGTH);
   assertMetadata(input.metadata);
 }
 function validateValidateInput(input) {
@@ -797,6 +873,8 @@ function validateValidateInput(input) {
   if (typeof input.code !== "string" || input.code.length === 0) {
     throw new ValidationError("code is required");
   }
+  assertOptionalString("userId", input.userId, LIMITS.USER_ID_MAX_LENGTH);
+  assertContext(input.context);
   if (input.subtotal !== void 0) {
     if (typeof input.subtotal !== "number" || !Number.isInteger(input.subtotal) || input.subtotal < 0) {
       throw new ValidationError("subtotal must be a non-negative integer");
@@ -817,6 +895,9 @@ function validateRedeemInput(input) {
     throw new ValidationError("subtotal must be a non-negative integer");
   }
   assertCurrency(input.currency);
+  assertOptionalString("userId", input.userId, LIMITS.USER_ID_MAX_LENGTH);
+  assertOptionalString("orderRef", input.orderRef, LIMITS.ORDER_REF_MAX_LENGTH);
+  assertContext(input.context);
   assertMetadata(input.metadata);
 }
 function validateCreateCampaignInput(input) {
@@ -834,6 +915,7 @@ function validateCreateCampaignInput(input) {
   validateDiscountPolicy(input.discount);
   assertDateRange(input.startsAt ?? null, input.endsAt ?? null);
   assertMetadata(input.metadata);
+  assertOptionalString("actorId", input.actorId, LIMITS.USER_ID_MAX_LENGTH);
   if (input.maxCoupons !== void 0 && input.maxCoupons !== null) {
     if (typeof input.maxCoupons !== "number" || !Number.isInteger(input.maxCoupons) || input.maxCoupons <= 0) {
       throw new ValidationError(
@@ -867,6 +949,9 @@ zod.z.discriminatedUnion("kind", [
 function w(v) {
   return v;
 }
+function isUniqueViolation(err) {
+  return typeof err === "object" && err !== null && err.code === "P2002";
+}
 var NOOP_LOGGER = {
   debug() {
   },
@@ -912,6 +997,13 @@ async function safeEmit(handler, logger, event) {
     });
   }
 }
+function assertUserIdForPerUserLimit(userId) {
+  if (typeof userId !== "string" || userId.length === 0) {
+    throw new ValidationError(
+      "userId is required: this coupon enforces maxRedemptionsPerUser"
+    );
+  }
+}
 async function resolveLazyStatus(delegates, tx, coupon, now) {
   if (coupon.status === COUPON_STATUS.ARCHIVED) {
     return { kind: "reject", reason: "ARCHIVED", coupon };
@@ -1003,20 +1095,21 @@ function createCouponClient(config) {
         const created = await delegates.coupon(tx).create({ data: row });
         return rowToCoupon(created);
       } catch (err) {
+        if (!isUniqueViolation(err)) throw err;
         lastError = err;
         if (baseCode) {
           throw new ValidationError(
             `coupon code already exists in tenant`,
-            { prismaError: err instanceof Error ? err.message : String(err) },
-            { tenantId, couponCode: baseCode }
+            void 0,
+            { tenantId, couponCode: baseCode, cause: err }
           );
         }
       }
     }
     throw new ValidationError(
       `failed to create coupon after ${maxAttempts} attempts (unique code collision)`,
-      { lastError: lastError instanceof Error ? lastError.message : String(lastError) },
-      { tenantId }
+      void 0,
+      { tenantId, cause: lastError }
     );
   }
   const coupons = {
@@ -1121,15 +1214,25 @@ function createCouponClient(config) {
       let skipped = 0;
       let totalAttempts = 0;
       await prisma.$transaction(async (tx) => {
+        const seen = /* @__PURE__ */ new Set();
         for (let i = 0; i < input.count; i++) {
           let placed = null;
           for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             totalAttempts++;
-            const code = cfg.codeGenerator({ length: codeLength });
+            const canonical = canonicalizeCode(
+              cfg.codeGenerator({ length: codeLength })
+            );
+            const collided = seen.has(canonical) || await delegates.coupon(tx).findFirst({
+              where: { tenantId, code: canonical },
+              select: { id: true }
+            }) !== null;
+            if (collided) {
+              if (attempt === maxAttempts) skipped++;
+              continue;
+            }
+            let row;
             try {
-              sanitizeCode(code);
-              const canonical = canonicalizeCode(code);
-              const row = await delegates.coupon(tx).create({
+              row = await delegates.coupon(tx).create({
                 data: {
                   id: cfg.idGenerator(),
                   tenantId,
@@ -1145,13 +1248,17 @@ function createCouponClient(config) {
                   metadata: w(metadata ?? null)
                 }
               });
-              placed = rowToCoupon(row);
-              break;
             } catch (err) {
-              if (attempt === maxAttempts) {
-                skipped++;
-              }
+              if (!isUniqueViolation(err)) throw err;
+              throw new ValidationError(
+                "bulk issuance aborted: coupon code collided with a concurrent insert",
+                void 0,
+                { tenantId, couponCode: canonical, cause: err }
+              );
             }
+            seen.add(canonical);
+            placed = rowToCoupon(row);
+            break;
           }
           if (placed) {
             created.push(placed);
@@ -1244,9 +1351,7 @@ function createCouponClient(config) {
     },
     async get(args) {
       const tenantId = tid(args.tenantId);
-      if (!args.id || typeof args.id !== "string") {
-        throw new ValidationError("id is required");
-      }
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
       const row = await delegates.coupon(prisma).findFirst({
         where: { id: args.id, tenantId }
       });
@@ -1255,6 +1360,8 @@ function createCouponClient(config) {
     async list(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("campaignId", args.campaignId, LIMITS.ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.campaignId) where.campaignId = args.campaignId;
       if (args.status) where.status = args.status;
@@ -1269,6 +1376,8 @@ function createCouponClient(config) {
     },
     async pause(args) {
       const tenantId = tid(args.tenantId);
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       const now = cfg.now();
       const coupon = await prisma.$transaction(async (tx) => {
         const row = await delegates.coupon(tx).findFirst({
@@ -1302,6 +1411,8 @@ function createCouponClient(config) {
     },
     async resume(args) {
       const tenantId = tid(args.tenantId);
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       const now = cfg.now();
       const coupon = await prisma.$transaction(async (tx) => {
         const row = await delegates.coupon(tx).findFirst({
@@ -1335,6 +1446,8 @@ function createCouponClient(config) {
     },
     async archive(args) {
       const tenantId = tid(args.tenantId);
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       const now = cfg.now();
       const coupon = await prisma.$transaction(async (tx) => {
         const row = await delegates.coupon(tx).findFirst({
@@ -1392,7 +1505,8 @@ function createCouponClient(config) {
       if (!elig.ok) {
         return { ok: false, reason: elig.reason };
       }
-      if (coupon.maxRedemptionsPerUser !== null && input.userId) {
+      if (coupon.maxRedemptionsPerUser !== null) {
+        assertUserIdForPerUserLimit(input.userId);
         const count = await delegates.couponRedemption(tx).count({
           where: {
             tenantId,
@@ -1476,7 +1590,8 @@ function createCouponClient(config) {
     if (!elig.ok) {
       throw eligibilityReasonToError(elig.reason);
     }
-    if (coupon.maxRedemptionsPerUser !== null && input.userId) {
+    if (coupon.maxRedemptionsPerUser !== null) {
+      assertUserIdForPerUserLimit(input.userId);
       const userCount = await delegates.couponRedemption(tx).count({
         where: {
           tenantId,
@@ -1550,6 +1665,7 @@ function createCouponClient(config) {
       });
       redemption = rowToRedemption(inserted);
     } catch (err) {
+      if (!isUniqueViolation(err)) throw err;
       throw new CouponAlreadyRedeemedError(void 0, {
         tenantId,
         couponId: coupon.id,
@@ -1557,7 +1673,7 @@ function createCouponClient(config) {
         cause: err
       });
     }
-    if (coupon.maxRedemptionsPerUser !== null && input.userId) {
+    if (coupon.maxRedemptionsPerUser !== null) {
       const userCountFinal = await delegates.couponRedemption(tx).count({
         where: {
           tenantId,
@@ -1657,20 +1773,30 @@ function createCouponClient(config) {
       const metadata = assertMetadata(input.metadata);
       const now = cfg.now();
       const campaign = await prisma.$transaction(async (tx) => {
-        const row = await delegates.campaign(tx).create({
-          data: {
-            id: cfg.idGenerator(),
-            tenantId,
-            name: input.name,
-            status: CAMPAIGN_STATUS.ACTIVE,
-            discount: w(input.discount),
-            eligibility: w(eligibility),
-            startsAt: input.startsAt ?? null,
-            endsAt: input.endsAt ?? null,
-            maxCoupons: input.maxCoupons ?? null,
-            metadata: w(metadata ?? null)
-          }
-        });
+        let row;
+        try {
+          row = await delegates.campaign(tx).create({
+            data: {
+              id: cfg.idGenerator(),
+              tenantId,
+              name: input.name,
+              status: CAMPAIGN_STATUS.ACTIVE,
+              discount: w(input.discount),
+              eligibility: w(eligibility),
+              startsAt: input.startsAt ?? null,
+              endsAt: input.endsAt ?? null,
+              maxCoupons: input.maxCoupons ?? null,
+              metadata: w(metadata ?? null)
+            }
+          });
+        } catch (err) {
+          if (!isUniqueViolation(err)) throw err;
+          throw new ValidationError(
+            "campaign name already exists in tenant",
+            void 0,
+            { tenantId, cause: err }
+          );
+        }
         const campaign2 = rowToCampaign(row);
         await writeAudit(delegates.couponAuditLog(tx), {
           tenantId,
@@ -1692,7 +1818,7 @@ function createCouponClient(config) {
     },
     async get(args) {
       const tenantId = tid(args.tenantId);
-      if (!args.id) throw new ValidationError("id is required");
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
       const row = await delegates.campaign(prisma).findFirst({
         where: { id: args.id, tenantId }
       });
@@ -1701,6 +1827,7 @@ function createCouponClient(config) {
     async list(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.status) where.status = args.status;
       return paginate(
@@ -1714,9 +1841,8 @@ function createCouponClient(config) {
     },
     async issue(args) {
       if (!args || typeof args !== "object") throw new ValidationError("args required");
-      if (typeof args.campaignId !== "string" || !args.campaignId) {
-        throw new ValidationError("campaignId is required");
-      }
+      assertRequiredString("campaignId", args.campaignId, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       if (typeof args.count !== "number" || !Number.isInteger(args.count) || args.count <= 0 || args.count > LIMITS.BULK_MAX_COUNT) {
         throw new ValidationError(
           `count must be a positive integer <= ${LIMITS.BULK_MAX_COUNT}`
@@ -1751,7 +1877,7 @@ function createCouponClient(config) {
     },
     async summary(args) {
       const tenantId = tid(args.tenantId);
-      if (!args.id) throw new ValidationError("id is required");
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
       const campRow = await delegates.campaign(prisma).findFirst({
         where: { id: args.id, tenantId }
       });
@@ -1804,7 +1930,8 @@ function createCouponClient(config) {
     },
     async close(args) {
       const tenantId = tid(args.tenantId);
-      if (!args.id) throw new ValidationError("id is required");
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       const now = cfg.now();
       const campaign = await prisma.$transaction(async (tx) => {
         const row = await delegates.campaign(tx).findFirst({
@@ -1842,6 +1969,9 @@ function createCouponClient(config) {
     async listIssuances(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("couponId", args.couponId, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("issuedToUserId", args.issuedToUserId, LIMITS.USER_ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.couponId) where.couponId = args.couponId;
       if (args.issuedToUserId) where.issuedToUserId = args.issuedToUserId;
@@ -1857,6 +1987,9 @@ function createCouponClient(config) {
     async listRedemptions(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("couponId", args.couponId, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("redeemedByUserId", args.redeemedByUserId, LIMITS.USER_ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.couponId) where.couponId = args.couponId;
       if (args.redeemedByUserId) where.redeemedByUserId = args.redeemedByUserId;
@@ -1872,6 +2005,8 @@ function createCouponClient(config) {
     async listLogs(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("resourceId", args.resourceId, LIMITS.ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.action) where.action = args.action;
       if (args.resourceId) where.resourceId = args.resourceId;

package/dist/index.d.cts

@@ -68,6 +68,22 @@ declare const LIMITS: {
     readonly PAGINATION_MAX_LIMIT: 200;
     readonly NAME_MAX_LENGTH: 200;
     readonly CURRENCY_LENGTH: 3;
+    /**
+     * [L] Caller-supplied identifier caps. Ids (coupon / campaign / cursor) are
+     * bounded by the audit log's `resourceId VarChar(64)`; `orderRef` by the
+     * redemption table's `VarChar(128)`. User / actor ids share the same bound
+     * so an unbounded string can never reach a Json or text column unchecked.
+     */
+    readonly ID_MAX_LENGTH: 64;
+    readonly USER_ID_MAX_LENGTH: 128;
+    readonly ORDER_REF_MAX_LENGTH: 128;
+    /** [L] Upper bound on serialized `metadata` (bytes of JSON text). */
+    readonly METADATA_MAX_BYTES: 16384;
+    /** [L] Per-list entry cap and per-entry length cap for eligibility rules. */
+    readonly ELIGIBILITY_MAX_ENTRIES: 1000;
+    readonly ELIGIBILITY_ENTRY_MAX_LENGTH: 128;
+    /** [L] Length cap for `context.plan / productId / categoryId`. */
+    readonly CONTEXT_VALUE_MAX_LENGTH: 128;
 };
 /**
  * Audit log action strings (stable identifiers).

package/dist/index.d.ts

@@ -68,6 +68,22 @@ declare const LIMITS: {
     readonly PAGINATION_MAX_LIMIT: 200;
     readonly NAME_MAX_LENGTH: 200;
     readonly CURRENCY_LENGTH: 3;
+    /**
+     * [L] Caller-supplied identifier caps. Ids (coupon / campaign / cursor) are
+     * bounded by the audit log's `resourceId VarChar(64)`; `orderRef` by the
+     * redemption table's `VarChar(128)`. User / actor ids share the same bound
+     * so an unbounded string can never reach a Json or text column unchecked.
+     */
+    readonly ID_MAX_LENGTH: 64;
+    readonly USER_ID_MAX_LENGTH: 128;
+    readonly ORDER_REF_MAX_LENGTH: 128;
+    /** [L] Upper bound on serialized `metadata` (bytes of JSON text). */
+    readonly METADATA_MAX_BYTES: 16384;
+    /** [L] Per-list entry cap and per-entry length cap for eligibility rules. */
+    readonly ELIGIBILITY_MAX_ENTRIES: 1000;
+    readonly ELIGIBILITY_ENTRY_MAX_LENGTH: 128;
+    /** [L] Length cap for `context.plan / productId / categoryId`. */
+    readonly CONTEXT_VALUE_MAX_LENGTH: 128;
 };
 /**
  * Audit log action strings (stable identifiers).

package/dist/index.mjs

@@ -53,7 +53,23 @@ var LIMITS = {
   PAGINATION_DEFAULT_LIMIT: 50,
   PAGINATION_MAX_LIMIT: 200,
   NAME_MAX_LENGTH: 200,
-  CURRENCY_LENGTH: 3
+  CURRENCY_LENGTH: 3,
+  /**
+   * [L] Caller-supplied identifier caps. Ids (coupon / campaign / cursor) are
+   * bounded by the audit log's `resourceId VarChar(64)`; `orderRef` by the
+   * redemption table's `VarChar(128)`. User / actor ids share the same bound
+   * so an unbounded string can never reach a Json or text column unchecked.
+   */
+  ID_MAX_LENGTH: 64,
+  USER_ID_MAX_LENGTH: 128,
+  ORDER_REF_MAX_LENGTH: 128,
+  /** [L] Upper bound on serialized `metadata` (bytes of JSON text). */
+  METADATA_MAX_BYTES: 16384,
+  /** [L] Per-list entry cap and per-entry length cap for eligibility rules. */
+  ELIGIBILITY_MAX_ENTRIES: 1e3,
+  ELIGIBILITY_ENTRY_MAX_LENGTH: 128,
+  /** [L] Length cap for `context.plan / productId / categoryId`. */
+  CONTEXT_VALUE_MAX_LENGTH: 128
 };
 var AUDIT_ACTION = {
   COUPON_CREATED: "coupon.created",
@@ -615,6 +631,40 @@ function lockCouponRow(tx, table, couponId, tenantId) {
   });
   return tx.$queryRaw(strings, couponId, tenantId);
 }
+function assertOptionalString(name, value, max) {
+  if (value === void 0 || value === null) return;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ValidationError(`${name} must be a non-empty string`);
+  }
+  if (value.length > max) {
+    throw new ValidationError(`${name} length exceeds max (${max})`);
+  }
+}
+function assertRequiredString(name, value, max) {
+  if (value === void 0 || value === null) {
+    throw new ValidationError(`${name} is required`);
+  }
+  assertOptionalString(name, value, max);
+}
+function assertContext(context) {
+  if (context === void 0 || context === null) return;
+  if (typeof context !== "object" || Array.isArray(context)) {
+    throw new ValidationError("context must be a plain object");
+  }
+  const c = context;
+  assertOptionalString("context.plan", c.plan, LIMITS.CONTEXT_VALUE_MAX_LENGTH);
+  assertOptionalString("context.productId", c.productId, LIMITS.CONTEXT_VALUE_MAX_LENGTH);
+  assertOptionalString("context.categoryId", c.categoryId, LIMITS.CONTEXT_VALUE_MAX_LENGTH);
+}
+function assertCouponStatus(status) {
+  if (status === void 0) return;
+  const allowed = Object.values(COUPON_STATUS);
+  if (typeof status !== "string" || !allowed.includes(status)) {
+    throw new ValidationError(
+      `status must be one of ${allowed.join(", ")}`
+    );
+  }
+}
 function assertTenantId(value) {
   if (typeof value !== "string" || value.length === 0) {
     throw new ValidationError("tenantId is required");
@@ -676,6 +726,17 @@ function assertMetadata(meta) {
       );
     }
   }
+  let serialized;
+  try {
+    serialized = JSON.stringify(rec);
+  } catch {
+    throw new ValidationError("metadata must be JSON-serializable");
+  }
+  if (Buffer.byteLength(serialized, "utf8") > LIMITS.METADATA_MAX_BYTES) {
+    throw new ValidationError(
+      `metadata exceeds max size (${LIMITS.METADATA_MAX_BYTES} bytes)`
+    );
+  }
   return rec;
 }
 function assertPaginationLimit(limit) {
@@ -727,6 +788,16 @@ function assertEligibility(rules) {
         `eligibility.${key} must be an array of non-empty strings`
       );
     }
+    if (v.length > LIMITS.ELIGIBILITY_MAX_ENTRIES) {
+      throw new ValidationError(
+        `eligibility.${key} exceeds max entries (${LIMITS.ELIGIBILITY_MAX_ENTRIES})`
+      );
+    }
+    if (v.some((x) => x.length > LIMITS.ELIGIBILITY_ENTRY_MAX_LENGTH)) {
+      throw new ValidationError(
+        `eligibility.${key} entry exceeds max length (${LIMITS.ELIGIBILITY_ENTRY_MAX_LENGTH})`
+      );
+    }
     out[key] = v;
   }
   return out;
@@ -743,6 +814,9 @@ function validateCreateCouponInput(input) {
   validateDiscountPolicy(input.discount);
   assertDateRange(input.startsAt ?? null, input.endsAt ?? null);
   assertMetadata(input.metadata);
+  assertCouponStatus(input.status);
+  assertOptionalString("campaignId", input.campaignId, LIMITS.ID_MAX_LENGTH);
+  assertOptionalString("actorId", input.actorId, LIMITS.USER_ID_MAX_LENGTH);
   if (input.maxRedemptions !== void 0 && input.maxRedemptions !== null) {
     if (typeof input.maxRedemptions !== "number" || !Number.isInteger(input.maxRedemptions) || input.maxRedemptions <= 0) {
       throw new ValidationError("maxRedemptions must be a positive integer or null");
@@ -778,14 +852,16 @@ function validateIssueBulkInput(input) {
   validateDiscountPolicy(input.discount);
   assertDateRange(input.startsAt ?? null, input.endsAt ?? null);
   assertMetadata(input.metadata);
+  assertOptionalString("campaignId", input.campaignId, LIMITS.ID_MAX_LENGTH);
+  assertOptionalString("actorId", input.actorId, LIMITS.USER_ID_MAX_LENGTH);
 }
 function validateIssueCouponInput(input) {
   if (!input || typeof input !== "object") {
     throw new ValidationError("input must be an object");
   }
-  if (typeof input.couponId !== "string" || input.couponId.length === 0) {
-    throw new ValidationError("couponId is required");
-  }
+  assertRequiredString("couponId", input.couponId, LIMITS.ID_MAX_LENGTH);
+  assertOptionalString("issuedToUserId", input.issuedToUserId, LIMITS.USER_ID_MAX_LENGTH);
+  assertOptionalString("issuedBy", input.issuedBy, LIMITS.USER_ID_MAX_LENGTH);
   assertMetadata(input.metadata);
 }
 function validateValidateInput(input) {
@@ -795,6 +871,8 @@ function validateValidateInput(input) {
   if (typeof input.code !== "string" || input.code.length === 0) {
     throw new ValidationError("code is required");
   }
+  assertOptionalString("userId", input.userId, LIMITS.USER_ID_MAX_LENGTH);
+  assertContext(input.context);
   if (input.subtotal !== void 0) {
     if (typeof input.subtotal !== "number" || !Number.isInteger(input.subtotal) || input.subtotal < 0) {
       throw new ValidationError("subtotal must be a non-negative integer");
@@ -815,6 +893,9 @@ function validateRedeemInput(input) {
     throw new ValidationError("subtotal must be a non-negative integer");
   }
   assertCurrency(input.currency);
+  assertOptionalString("userId", input.userId, LIMITS.USER_ID_MAX_LENGTH);
+  assertOptionalString("orderRef", input.orderRef, LIMITS.ORDER_REF_MAX_LENGTH);
+  assertContext(input.context);
   assertMetadata(input.metadata);
 }
 function validateCreateCampaignInput(input) {
@@ -832,6 +913,7 @@ function validateCreateCampaignInput(input) {
   validateDiscountPolicy(input.discount);
   assertDateRange(input.startsAt ?? null, input.endsAt ?? null);
   assertMetadata(input.metadata);
+  assertOptionalString("actorId", input.actorId, LIMITS.USER_ID_MAX_LENGTH);
   if (input.maxCoupons !== void 0 && input.maxCoupons !== null) {
     if (typeof input.maxCoupons !== "number" || !Number.isInteger(input.maxCoupons) || input.maxCoupons <= 0) {
       throw new ValidationError(
@@ -865,6 +947,9 @@ z.discriminatedUnion("kind", [
 function w(v) {
   return v;
 }
+function isUniqueViolation(err) {
+  return typeof err === "object" && err !== null && err.code === "P2002";
+}
 var NOOP_LOGGER = {
   debug() {
   },
@@ -910,6 +995,13 @@ async function safeEmit(handler, logger, event) {
     });
   }
 }
+function assertUserIdForPerUserLimit(userId) {
+  if (typeof userId !== "string" || userId.length === 0) {
+    throw new ValidationError(
+      "userId is required: this coupon enforces maxRedemptionsPerUser"
+    );
+  }
+}
 async function resolveLazyStatus(delegates, tx, coupon, now) {
   if (coupon.status === COUPON_STATUS.ARCHIVED) {
     return { kind: "reject", reason: "ARCHIVED", coupon };
@@ -1001,20 +1093,21 @@ function createCouponClient(config) {
         const created = await delegates.coupon(tx).create({ data: row });
         return rowToCoupon(created);
       } catch (err) {
+        if (!isUniqueViolation(err)) throw err;
         lastError = err;
         if (baseCode) {
           throw new ValidationError(
             `coupon code already exists in tenant`,
-            { prismaError: err instanceof Error ? err.message : String(err) },
-            { tenantId, couponCode: baseCode }
+            void 0,
+            { tenantId, couponCode: baseCode, cause: err }
           );
         }
       }
     }
     throw new ValidationError(
       `failed to create coupon after ${maxAttempts} attempts (unique code collision)`,
-      { lastError: lastError instanceof Error ? lastError.message : String(lastError) },
-      { tenantId }
+      void 0,
+      { tenantId, cause: lastError }
     );
   }
   const coupons = {
@@ -1119,15 +1212,25 @@ function createCouponClient(config) {
       let skipped = 0;
       let totalAttempts = 0;
       await prisma.$transaction(async (tx) => {
+        const seen = /* @__PURE__ */ new Set();
         for (let i = 0; i < input.count; i++) {
           let placed = null;
           for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             totalAttempts++;
-            const code = cfg.codeGenerator({ length: codeLength });
+            const canonical = canonicalizeCode(
+              cfg.codeGenerator({ length: codeLength })
+            );
+            const collided = seen.has(canonical) || await delegates.coupon(tx).findFirst({
+              where: { tenantId, code: canonical },
+              select: { id: true }
+            }) !== null;
+            if (collided) {
+              if (attempt === maxAttempts) skipped++;
+              continue;
+            }
+            let row;
             try {
-              sanitizeCode(code);
-              const canonical = canonicalizeCode(code);
-              const row = await delegates.coupon(tx).create({
+              row = await delegates.coupon(tx).create({
                 data: {
                   id: cfg.idGenerator(),
                   tenantId,
@@ -1143,13 +1246,17 @@ function createCouponClient(config) {
                   metadata: w(metadata ?? null)
                 }
               });
-              placed = rowToCoupon(row);
-              break;
             } catch (err) {
-              if (attempt === maxAttempts) {
-                skipped++;
-              }
+              if (!isUniqueViolation(err)) throw err;
+              throw new ValidationError(
+                "bulk issuance aborted: coupon code collided with a concurrent insert",
+                void 0,
+                { tenantId, couponCode: canonical, cause: err }
+              );
             }
+            seen.add(canonical);
+            placed = rowToCoupon(row);
+            break;
           }
           if (placed) {
             created.push(placed);
@@ -1242,9 +1349,7 @@ function createCouponClient(config) {
     },
     async get(args) {
       const tenantId = tid(args.tenantId);
-      if (!args.id || typeof args.id !== "string") {
-        throw new ValidationError("id is required");
-      }
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
       const row = await delegates.coupon(prisma).findFirst({
         where: { id: args.id, tenantId }
       });
@@ -1253,6 +1358,8 @@ function createCouponClient(config) {
     async list(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("campaignId", args.campaignId, LIMITS.ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.campaignId) where.campaignId = args.campaignId;
       if (args.status) where.status = args.status;
@@ -1267,6 +1374,8 @@ function createCouponClient(config) {
     },
     async pause(args) {
       const tenantId = tid(args.tenantId);
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       const now = cfg.now();
       const coupon = await prisma.$transaction(async (tx) => {
         const row = await delegates.coupon(tx).findFirst({
@@ -1300,6 +1409,8 @@ function createCouponClient(config) {
     },
     async resume(args) {
       const tenantId = tid(args.tenantId);
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       const now = cfg.now();
       const coupon = await prisma.$transaction(async (tx) => {
         const row = await delegates.coupon(tx).findFirst({
@@ -1333,6 +1444,8 @@ function createCouponClient(config) {
     },
     async archive(args) {
       const tenantId = tid(args.tenantId);
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       const now = cfg.now();
       const coupon = await prisma.$transaction(async (tx) => {
         const row = await delegates.coupon(tx).findFirst({
@@ -1390,7 +1503,8 @@ function createCouponClient(config) {
       if (!elig.ok) {
         return { ok: false, reason: elig.reason };
       }
-      if (coupon.maxRedemptionsPerUser !== null && input.userId) {
+      if (coupon.maxRedemptionsPerUser !== null) {
+        assertUserIdForPerUserLimit(input.userId);
         const count = await delegates.couponRedemption(tx).count({
           where: {
             tenantId,
@@ -1474,7 +1588,8 @@ function createCouponClient(config) {
     if (!elig.ok) {
       throw eligibilityReasonToError(elig.reason);
     }
-    if (coupon.maxRedemptionsPerUser !== null && input.userId) {
+    if (coupon.maxRedemptionsPerUser !== null) {
+      assertUserIdForPerUserLimit(input.userId);
       const userCount = await delegates.couponRedemption(tx).count({
         where: {
           tenantId,
@@ -1548,6 +1663,7 @@ function createCouponClient(config) {
       });
       redemption = rowToRedemption(inserted);
     } catch (err) {
+      if (!isUniqueViolation(err)) throw err;
       throw new CouponAlreadyRedeemedError(void 0, {
         tenantId,
         couponId: coupon.id,
@@ -1555,7 +1671,7 @@ function createCouponClient(config) {
         cause: err
       });
     }
-    if (coupon.maxRedemptionsPerUser !== null && input.userId) {
+    if (coupon.maxRedemptionsPerUser !== null) {
       const userCountFinal = await delegates.couponRedemption(tx).count({
         where: {
           tenantId,
@@ -1655,20 +1771,30 @@ function createCouponClient(config) {
       const metadata = assertMetadata(input.metadata);
       const now = cfg.now();
       const campaign = await prisma.$transaction(async (tx) => {
-        const row = await delegates.campaign(tx).create({
-          data: {
-            id: cfg.idGenerator(),
-            tenantId,
-            name: input.name,
-            status: CAMPAIGN_STATUS.ACTIVE,
-            discount: w(input.discount),
-            eligibility: w(eligibility),
-            startsAt: input.startsAt ?? null,
-            endsAt: input.endsAt ?? null,
-            maxCoupons: input.maxCoupons ?? null,
-            metadata: w(metadata ?? null)
-          }
-        });
+        let row;
+        try {
+          row = await delegates.campaign(tx).create({
+            data: {
+              id: cfg.idGenerator(),
+              tenantId,
+              name: input.name,
+              status: CAMPAIGN_STATUS.ACTIVE,
+              discount: w(input.discount),
+              eligibility: w(eligibility),
+              startsAt: input.startsAt ?? null,
+              endsAt: input.endsAt ?? null,
+              maxCoupons: input.maxCoupons ?? null,
+              metadata: w(metadata ?? null)
+            }
+          });
+        } catch (err) {
+          if (!isUniqueViolation(err)) throw err;
+          throw new ValidationError(
+            "campaign name already exists in tenant",
+            void 0,
+            { tenantId, cause: err }
+          );
+        }
         const campaign2 = rowToCampaign(row);
         await writeAudit(delegates.couponAuditLog(tx), {
           tenantId,
@@ -1690,7 +1816,7 @@ function createCouponClient(config) {
     },
     async get(args) {
       const tenantId = tid(args.tenantId);
-      if (!args.id) throw new ValidationError("id is required");
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
       const row = await delegates.campaign(prisma).findFirst({
         where: { id: args.id, tenantId }
       });
@@ -1699,6 +1825,7 @@ function createCouponClient(config) {
     async list(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.status) where.status = args.status;
       return paginate(
@@ -1712,9 +1839,8 @@ function createCouponClient(config) {
     },
     async issue(args) {
       if (!args || typeof args !== "object") throw new ValidationError("args required");
-      if (typeof args.campaignId !== "string" || !args.campaignId) {
-        throw new ValidationError("campaignId is required");
-      }
+      assertRequiredString("campaignId", args.campaignId, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       if (typeof args.count !== "number" || !Number.isInteger(args.count) || args.count <= 0 || args.count > LIMITS.BULK_MAX_COUNT) {
         throw new ValidationError(
           `count must be a positive integer <= ${LIMITS.BULK_MAX_COUNT}`
@@ -1749,7 +1875,7 @@ function createCouponClient(config) {
     },
     async summary(args) {
       const tenantId = tid(args.tenantId);
-      if (!args.id) throw new ValidationError("id is required");
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
       const campRow = await delegates.campaign(prisma).findFirst({
         where: { id: args.id, tenantId }
       });
@@ -1802,7 +1928,8 @@ function createCouponClient(config) {
     },
     async close(args) {
       const tenantId = tid(args.tenantId);
-      if (!args.id) throw new ValidationError("id is required");
+      assertRequiredString("id", args.id, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("actorId", args.actorId, LIMITS.USER_ID_MAX_LENGTH);
       const now = cfg.now();
       const campaign = await prisma.$transaction(async (tx) => {
         const row = await delegates.campaign(tx).findFirst({
@@ -1840,6 +1967,9 @@ function createCouponClient(config) {
     async listIssuances(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("couponId", args.couponId, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("issuedToUserId", args.issuedToUserId, LIMITS.USER_ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.couponId) where.couponId = args.couponId;
       if (args.issuedToUserId) where.issuedToUserId = args.issuedToUserId;
@@ -1855,6 +1985,9 @@ function createCouponClient(config) {
     async listRedemptions(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("couponId", args.couponId, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("redeemedByUserId", args.redeemedByUserId, LIMITS.USER_ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.couponId) where.couponId = args.couponId;
       if (args.redeemedByUserId) where.redeemedByUserId = args.redeemedByUserId;
@@ -1870,6 +2003,8 @@ function createCouponClient(config) {
     async listLogs(args) {
       const tenantId = tid(args.tenantId);
       const limit = assertPaginationLimit(args.limit);
+      assertOptionalString("cursor", args.cursor, LIMITS.ID_MAX_LENGTH);
+      assertOptionalString("resourceId", args.resourceId, LIMITS.ID_MAX_LENGTH);
       const where = { tenantId };
       if (args.action) where.action = args.action;
       if (args.resourceId) where.resourceId = args.resourceId;

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "pnpm@11.10.0",
   "name": "@withwiz/coupon",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Multi-tenant, concurrency-safe coupon domain core for Prisma + Node.js applications",
   "license": "MIT",
   "author": "withwiz",
@@ -76,11 +76,12 @@
   },
   "devDependencies": {
     "@prisma/client": "^6.0.0",
-    "@types/node": "^20.12.0",
-    "@vitest/coverage-v8": "^1.6.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^5.0.0",
     "prisma": "^6.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
-    "vitest": "^1.6.0"
+    "vite": "^7.0.0",
+    "vitest": "^5.0.0"
   }
 }