@withwiz/coupon 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -68,6 +68,24 @@ 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;
+    /** Upper bound for `duration.months` on a REPEATING discount. */
+    readonly DURATION_MAX_MONTHS: 36;
 };
 /**
  * Audit log action strings (stable identifiers).
@@ -91,17 +109,32 @@ type AuditAction = (typeof AUDIT_ACTION)[keyof typeof AUDIT_ACTION];
  * No Prisma generated types imported here (see contract §10 PrismaLike rule).
  */
 
+/**
+ * How many billing cycles a discount applies to. Absent = ONCE.
+ * The package records it; applying it to recurring charges is the consumer's job
+ * (re-run `calculateDiscount` per cycle with the stored policy).
+ */
+type DiscountDuration = {
+    kind: "ONCE";
+} | {
+    kind: "REPEATING";
+    months: number;
+} | {
+    kind: "FOREVER";
+};
 type DiscountPolicy = {
     kind: "PERCENT";
     percent: number;
     maxDiscount?: number;
     minOrder?: number;
     currency?: string;
+    duration?: DiscountDuration;
 } | {
     kind: "FIXED";
     amount: number;
     currency: string;
     minOrder?: number;
+    duration?: DiscountDuration;
 };
 type EligibilityRules = {
     allowedUserIds?: string[];
@@ -325,6 +358,13 @@ type CampaignIssueArgs = {
     codeLength?: number;
     maxAttempts?: number;
     actorId?: string;
+    /**
+     * Redemption limits stamped on each issued code. Unset = unlimited, which
+     * is rarely what a batch of unique codes wants: pass `maxRedemptions: 1`
+     * for single-use codes.
+     */
+    maxRedemptions?: number | null;
+    maxRedemptionsPerUser?: number | null;
 };
 type CampaignSummary = {
     id: string;
@@ -557,6 +597,15 @@ type CouponClientConfig = {
      * @example { coupon: "coupons" }
      */
     tables?: Partial<TableNameMap>;
+    /**
+     * Postgres schema that holds the coupon tables, used to qualify the
+     * `SELECT ... FOR UPDATE` row lock. Needed when the tables live outside
+     * `public` and the client uses a driver adapter (Prisma 7), whose raw
+     * queries resolve unqualified names through the connection's `search_path`.
+     *
+     * @example "billing"
+     */
+    schema?: string;
 };
 interface CouponClient {
     coupons: {
@@ -638,6 +687,8 @@ declare function validateDiscountPolicy(policy: DiscountPolicy): void;
  * Throws MinimumOrderNotMetError if subtotal < policy.minOrder.
  */
 declare function calculate(input: DiscountInput): DiscountBreakdown;
+/** The effective duration of a policy. Policies without one apply ONCE. */
+declare function resolveDuration(policy: DiscountPolicy): DiscountDuration;
 
 /**
  * Error taxonomy for @withwiz/coupon.
@@ -752,4 +803,4 @@ declare class TenantMismatchError extends CouponError {
     constructor(message?: string, ctx?: CouponErrorContext);
 }
 
-export { AUDIT_ACTION, type AuditAction, type AuditLog, type BulkIssuanceResult, CAMPAIGN_STATUS, COUPON_REJECT_REASON, COUPON_STATUS, type Campaign, CampaignCapacityExceededError, CampaignClosedError, type CampaignIssueArgs, type CampaignStatus, type CampaignSummary, type Coupon, CouponAlreadyRedeemedError, CouponArchivedError, type CouponClient, type CouponClientConfig, CouponError, type CouponEvent, type CouponEventHandler, CouponExhaustedError, CouponExpiredError, CouponInactiveError, type CouponLogger, type CouponModelKey, CouponNotFoundError, type CouponRejectReason, type CouponStatus, type CreateCampaignInput, type CreateCouponInput, CurrencyMismatchError, DEFAULT_MODEL_NAMES, type DiscountBreakdown, type DiscountInput, type DiscountPolicy, type EligibilityRules, IneligibleCategoryError, IneligiblePlanError, IneligibleProductError, IneligibleUserError, InvalidDateRangeError, InvalidDiscountPolicyError, InvalidModelNameError, type Issuance, type IssueBulkInput, type IssueCouponInput, LIMITS, type ListAuditLogsArgs, type ListCampaignsArgs, type ListCouponsArgs, type ListIssuancesArgs, type ListRedemptionsArgs, MinimumOrderNotMetError, type ModelNameMap, type Paged, PerUserLimitExceededError, type PrismaLike, type PrismaTxLike, type RedeemInput, type Redemption, type RedemptionResult, type TableNameMap, TenantMismatchError, type ValidateContext, type ValidateInput, ValidationError, type ValidationResult, calculate as calculateDiscount, createCouponClient, validateDiscountPolicy };
+export { AUDIT_ACTION, type AuditAction, type AuditLog, type BulkIssuanceResult, CAMPAIGN_STATUS, COUPON_REJECT_REASON, COUPON_STATUS, type Campaign, CampaignCapacityExceededError, CampaignClosedError, type CampaignIssueArgs, type CampaignStatus, type CampaignSummary, type Coupon, CouponAlreadyRedeemedError, CouponArchivedError, type CouponClient, type CouponClientConfig, CouponError, type CouponEvent, type CouponEventHandler, CouponExhaustedError, CouponExpiredError, CouponInactiveError, type CouponLogger, type CouponModelKey, CouponNotFoundError, type CouponRejectReason, type CouponStatus, type CreateCampaignInput, type CreateCouponInput, CurrencyMismatchError, DEFAULT_MODEL_NAMES, type DiscountBreakdown, type DiscountDuration, type DiscountInput, type DiscountPolicy, type EligibilityRules, IneligibleCategoryError, IneligiblePlanError, IneligibleProductError, IneligibleUserError, InvalidDateRangeError, InvalidDiscountPolicyError, InvalidModelNameError, type Issuance, type IssueBulkInput, type IssueCouponInput, LIMITS, type ListAuditLogsArgs, type ListCampaignsArgs, type ListCouponsArgs, type ListIssuancesArgs, type ListRedemptionsArgs, MinimumOrderNotMetError, type ModelNameMap, type Paged, PerUserLimitExceededError, type PrismaLike, type PrismaTxLike, type RedeemInput, type Redemption, type RedemptionResult, type TableNameMap, TenantMismatchError, type ValidateContext, type ValidateInput, ValidationError, type ValidationResult, calculate as calculateDiscount, createCouponClient, resolveDuration, validateDiscountPolicy };

package/dist/index.d.ts

@@ -68,6 +68,24 @@ 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;
+    /** Upper bound for `duration.months` on a REPEATING discount. */
+    readonly DURATION_MAX_MONTHS: 36;
 };
 /**
  * Audit log action strings (stable identifiers).
@@ -91,17 +109,32 @@ type AuditAction = (typeof AUDIT_ACTION)[keyof typeof AUDIT_ACTION];
  * No Prisma generated types imported here (see contract §10 PrismaLike rule).
  */
 
+/**
+ * How many billing cycles a discount applies to. Absent = ONCE.
+ * The package records it; applying it to recurring charges is the consumer's job
+ * (re-run `calculateDiscount` per cycle with the stored policy).
+ */
+type DiscountDuration = {
+    kind: "ONCE";
+} | {
+    kind: "REPEATING";
+    months: number;
+} | {
+    kind: "FOREVER";
+};
 type DiscountPolicy = {
     kind: "PERCENT";
     percent: number;
     maxDiscount?: number;
     minOrder?: number;
     currency?: string;
+    duration?: DiscountDuration;
 } | {
     kind: "FIXED";
     amount: number;
     currency: string;
     minOrder?: number;
+    duration?: DiscountDuration;
 };
 type EligibilityRules = {
     allowedUserIds?: string[];
@@ -325,6 +358,13 @@ type CampaignIssueArgs = {
     codeLength?: number;
     maxAttempts?: number;
     actorId?: string;
+    /**
+     * Redemption limits stamped on each issued code. Unset = unlimited, which
+     * is rarely what a batch of unique codes wants: pass `maxRedemptions: 1`
+     * for single-use codes.
+     */
+    maxRedemptions?: number | null;
+    maxRedemptionsPerUser?: number | null;
 };
 type CampaignSummary = {
     id: string;
@@ -557,6 +597,15 @@ type CouponClientConfig = {
      * @example { coupon: "coupons" }
      */
     tables?: Partial<TableNameMap>;
+    /**
+     * Postgres schema that holds the coupon tables, used to qualify the
+     * `SELECT ... FOR UPDATE` row lock. Needed when the tables live outside
+     * `public` and the client uses a driver adapter (Prisma 7), whose raw
+     * queries resolve unqualified names through the connection's `search_path`.
+     *
+     * @example "billing"
+     */
+    schema?: string;
 };
 interface CouponClient {
     coupons: {
@@ -638,6 +687,8 @@ declare function validateDiscountPolicy(policy: DiscountPolicy): void;
  * Throws MinimumOrderNotMetError if subtotal < policy.minOrder.
  */
 declare function calculate(input: DiscountInput): DiscountBreakdown;
+/** The effective duration of a policy. Policies without one apply ONCE. */
+declare function resolveDuration(policy: DiscountPolicy): DiscountDuration;
 
 /**
  * Error taxonomy for @withwiz/coupon.
@@ -752,4 +803,4 @@ declare class TenantMismatchError extends CouponError {
     constructor(message?: string, ctx?: CouponErrorContext);
 }
 
-export { AUDIT_ACTION, type AuditAction, type AuditLog, type BulkIssuanceResult, CAMPAIGN_STATUS, COUPON_REJECT_REASON, COUPON_STATUS, type Campaign, CampaignCapacityExceededError, CampaignClosedError, type CampaignIssueArgs, type CampaignStatus, type CampaignSummary, type Coupon, CouponAlreadyRedeemedError, CouponArchivedError, type CouponClient, type CouponClientConfig, CouponError, type CouponEvent, type CouponEventHandler, CouponExhaustedError, CouponExpiredError, CouponInactiveError, type CouponLogger, type CouponModelKey, CouponNotFoundError, type CouponRejectReason, type CouponStatus, type CreateCampaignInput, type CreateCouponInput, CurrencyMismatchError, DEFAULT_MODEL_NAMES, type DiscountBreakdown, type DiscountInput, type DiscountPolicy, type EligibilityRules, IneligibleCategoryError, IneligiblePlanError, IneligibleProductError, IneligibleUserError, InvalidDateRangeError, InvalidDiscountPolicyError, InvalidModelNameError, type Issuance, type IssueBulkInput, type IssueCouponInput, LIMITS, type ListAuditLogsArgs, type ListCampaignsArgs, type ListCouponsArgs, type ListIssuancesArgs, type ListRedemptionsArgs, MinimumOrderNotMetError, type ModelNameMap, type Paged, PerUserLimitExceededError, type PrismaLike, type PrismaTxLike, type RedeemInput, type Redemption, type RedemptionResult, type TableNameMap, TenantMismatchError, type ValidateContext, type ValidateInput, ValidationError, type ValidationResult, calculate as calculateDiscount, createCouponClient, validateDiscountPolicy };
+export { AUDIT_ACTION, type AuditAction, type AuditLog, type BulkIssuanceResult, CAMPAIGN_STATUS, COUPON_REJECT_REASON, COUPON_STATUS, type Campaign, CampaignCapacityExceededError, CampaignClosedError, type CampaignIssueArgs, type CampaignStatus, type CampaignSummary, type Coupon, CouponAlreadyRedeemedError, CouponArchivedError, type CouponClient, type CouponClientConfig, CouponError, type CouponEvent, type CouponEventHandler, CouponExhaustedError, CouponExpiredError, CouponInactiveError, type CouponLogger, type CouponModelKey, CouponNotFoundError, type CouponRejectReason, type CouponStatus, type CreateCampaignInput, type CreateCouponInput, CurrencyMismatchError, DEFAULT_MODEL_NAMES, type DiscountBreakdown, type DiscountDuration, type DiscountInput, type DiscountPolicy, type EligibilityRules, IneligibleCategoryError, IneligiblePlanError, IneligibleProductError, IneligibleUserError, InvalidDateRangeError, InvalidDiscountPolicyError, InvalidModelNameError, type Issuance, type IssueBulkInput, type IssueCouponInput, LIMITS, type ListAuditLogsArgs, type ListCampaignsArgs, type ListCouponsArgs, type ListIssuancesArgs, type ListRedemptionsArgs, MinimumOrderNotMetError, type ModelNameMap, type Paged, PerUserLimitExceededError, type PrismaLike, type PrismaTxLike, type RedeemInput, type Redemption, type RedemptionResult, type TableNameMap, TenantMismatchError, type ValidateContext, type ValidateInput, ValidationError, type ValidationResult, calculate as calculateDiscount, createCouponClient, resolveDuration, validateDiscountPolicy };