@qazuor/qzpay-core 1.0.0 → 1.0.1

package/README.md

@@ -16,6 +16,8 @@ pnpm add @qazuor/qzpay-core
 - **Metrics Service**: MRR, churn, and revenue calculations
 - **Health Service**: System health monitoring
 - **Logger**: Structured logging with customizable providers
+- **Input Validation**: Zod-based validation for all create operations
+- **Promo Code Validation**: Full validation with plan applicability and usage limits
 - **Utilities**: Date, money, validation, and hash helpers
 - **Runtime Agnostic**: Works in Node.js, Bun, Deno, and Edge runtimes (no direct `process.env` access)
 
@@ -240,6 +242,73 @@ isValidAmount(100); // true
 isValidAmount(-50); // false
 ```
 
+### Input Validation
+
+All create operations now include comprehensive Zod validation:
+
+```typescript
+// Customer creation with validation
+try {
+  const customer = await billing.customers.create({
+    email: 'invalid-email', // Will throw validation error
+    name: 'John Doe'
+  });
+} catch (error) {
+  // error.code === 'VALIDATION_ERROR'
+  // error.details contains validation failure info
+}
+
+// Payment with validation
+await billing.payments.process({
+  customerId: 'cus_123',
+  amount: -100, // Will throw validation error (negative amount)
+  currency: 'INVALID' // Will throw validation error (invalid currency)
+});
+
+// Invoice creation with validation
+await billing.invoices.create({
+  customerId: 'cus_123',
+  items: [] // Will throw validation error (empty items array)
+});
+```
+
+### Promo Code Validation
+
+Promo codes are validated against multiple criteria:
+
+```typescript
+// The system automatically validates:
+// 1. Plan applicability
+const promoCode = await billing.promoCodes.create({
+  code: 'SUMMER2024',
+  discountType: 'percentage',
+  discountValue: 20,
+  applicablePlans: ['plan_premium', 'plan_enterprise'] // Only works for these plans
+});
+
+// 2. Per-customer usage limits
+await billing.promoCodes.validate({
+  code: 'SUMMER2024',
+  customerId: 'cus_123',
+  planId: 'plan_basic' // Will fail if not in applicablePlans
+});
+
+// 3. Date ranges
+await billing.promoCodes.create({
+  code: 'NEWYEAR2024',
+  validFrom: new Date('2024-01-01'),
+  validTo: new Date('2024-01-31') // Only valid in January
+});
+
+// 4. Max uses and active status
+await billing.promoCodes.create({
+  code: 'LIMITED',
+  maxUses: 100, // Can only be used 100 times total
+  maxUsesPerCustomer: 1, // Each customer can use it once
+  active: true // Must be active
+});
+```
+
 ## Types
 
 ### Core Types

package/dist/index.cjs

@@ -1280,6 +1280,108 @@ var noopLogger = {
   }
 };
 
+// src/utils/validation.utils.ts
+function qzpayIsValidEmail(email) {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(email);
+}
+function qzpayIsValidCurrency(currency) {
+  return QZPAY_CURRENCY_VALUES.includes(currency.toUpperCase());
+}
+function qzpayIsPositiveInteger(value) {
+  return Number.isInteger(value) && value > 0;
+}
+function qzpayIsNonNegativeInteger(value) {
+  return Number.isInteger(value) && value >= 0;
+}
+function qzpayIsValidPercentage(value) {
+  return value >= 0 && value <= 100;
+}
+function qzpayIsValidUuid(value) {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidRegex.test(value);
+}
+function qzpayIsRequiredString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function qzpayValidateRequired(obj, requiredFields) {
+  const errors = [];
+  for (const field of requiredFields) {
+    const value = obj[field];
+    if (value === void 0 || value === null || value === "") {
+      errors.push(`${String(field)} is required`);
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function qzpayAssert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+function qzpayAssertDefined(value, name) {
+  if (value === null || value === void 0) {
+    throw new Error(`${name} is required`);
+  }
+}
+function qzpayCreateValidator(obj) {
+  return new QZPayValidator(obj);
+}
+var QZPayValidator = class {
+  constructor(obj) {
+    this.obj = obj;
+  }
+  errors = [];
+  required(field, message) {
+    const value = this.obj[field];
+    if (value === void 0 || value === null || value === "") {
+      this.errors.push(message ?? `${String(field)} is required`);
+    }
+    return this;
+  }
+  email(field, message) {
+    const value = this.obj[field];
+    if (typeof value === "string" && !qzpayIsValidEmail(value)) {
+      this.errors.push(message ?? `${String(field)} must be a valid email`);
+    }
+    return this;
+  }
+  positiveInteger(field, message) {
+    const value = this.obj[field];
+    if (typeof value === "number" && !qzpayIsPositiveInteger(value)) {
+      this.errors.push(message ?? `${String(field)} must be a positive integer`);
+    }
+    return this;
+  }
+  currency(field, message) {
+    const value = this.obj[field];
+    if (typeof value === "string" && !qzpayIsValidCurrency(value)) {
+      this.errors.push(message ?? `${String(field)} must be a valid currency`);
+    }
+    return this;
+  }
+  custom(condition, message) {
+    if (!condition) {
+      this.errors.push(message);
+    }
+    return this;
+  }
+  validate() {
+    return {
+      valid: this.errors.length === 0,
+      errors: [...this.errors]
+    };
+  }
+  assertValid() {
+    if (this.errors.length > 0) {
+      throw new Error(`Validation failed: ${this.errors.join(", ")}`);
+    }
+  }
+};
+
 // src/billing.ts
 var QZPayBillingImpl = class {
   storage;
@@ -1307,40 +1409,128 @@ var QZPayBillingImpl = class {
     this.logger.info("QZPayBilling initialized", { livemode: this.livemode });
   }
   get customers() {
+    const storage = this.storage;
+    const emitter = this.emitter;
+    const paymentAdapter = this.paymentAdapter;
     return {
       create: async (input) => {
-        const customer = await this.storage.customers.create(input);
-        await this.emitter.emit("customer.created", customer);
+        qzpayCreateValidator(input).required("email", "Email is required").email("email", "Invalid email format").required("externalId", "External ID is required").custom(!input.name || typeof input.name === "string" && input.name.trim().length > 0, "Name cannot be empty string").assertValid();
+        const customer = await storage.customers.create(input);
+        if (paymentAdapter) {
+          try {
+            const providerInput = {
+              email: input.email,
+              externalId: input.externalId
+            };
+            if (input.name !== void 0) providerInput.name = input.name;
+            if (input.metadata) providerInput.metadata = input.metadata;
+            const providerCustomerId = await paymentAdapter.customers.create(providerInput);
+            const updated = await storage.customers.update(customer.id, {
+              providerCustomerIds: {
+                ...customer.providerCustomerIds,
+                [paymentAdapter.provider]: providerCustomerId
+              }
+            });
+            await emitter.emit("customer.created", updated ?? customer);
+            return updated ?? customer;
+          } catch (error) {
+            this.logger.error("Failed to create customer in provider", {
+              provider: paymentAdapter.provider,
+              error: error instanceof Error ? error.message : String(error)
+            });
+            await emitter.emit("customer.created", customer);
+            return customer;
+          }
+        }
+        await emitter.emit("customer.created", customer);
         return customer;
       },
-      get: (id) => this.storage.customers.findById(id),
-      getByExternalId: (externalId) => this.storage.customers.findByExternalId(externalId),
+      get: (id) => storage.customers.findById(id),
+      getByExternalId: (externalId) => storage.customers.findByExternalId(externalId),
       update: async (id, input) => {
-        const customer = await this.storage.customers.update(id, input);
+        const customer = await storage.customers.update(id, input);
         if (customer) {
-          await this.emitter.emit("customer.updated", customer);
+          await emitter.emit("customer.updated", customer);
         }
         return customer;
       },
       delete: async (id) => {
-        await this.storage.customers.delete(id);
-        const customer = await this.storage.customers.findById(id);
+        await storage.customers.delete(id);
+        const customer = await storage.customers.findById(id);
         if (customer) {
-          await this.emitter.emit("customer.deleted", customer);
+          await emitter.emit("customer.deleted", customer);
         }
       },
-      list: (options) => this.storage.customers.list(options),
+      list: (options) => storage.customers.list(options),
       syncUser: async (input) => {
-        const existing = await this.storage.customers.findByExternalId(input.externalId ?? "");
+        const existing = await storage.customers.findByExternalId(input.externalId ?? "");
         if (existing) {
-          const updated = await this.storage.customers.update(existing.id, input);
+          if (paymentAdapter && !existing.providerCustomerIds[paymentAdapter.provider]) {
+            try {
+              const email = input.email ?? existing.email;
+              const name = input.name !== void 0 ? input.name : existing.name;
+              const metadata = input.metadata ?? existing.metadata;
+              const externalId = input.externalId ?? existing.externalId;
+              const providerInput = {
+                email,
+                externalId
+              };
+              if (name !== void 0) providerInput.name = name;
+              if (metadata) providerInput.metadata = metadata;
+              const providerCustomerId = await paymentAdapter.customers.create(providerInput);
+              const updated2 = await storage.customers.update(existing.id, {
+                ...input,
+                providerCustomerIds: {
+                  ...existing.providerCustomerIds,
+                  [paymentAdapter.provider]: providerCustomerId
+                }
+              });
+              if (updated2) {
+                await emitter.emit("customer.updated", updated2);
+              }
+              return updated2 ?? existing;
+            } catch (error) {
+              this.logger.error("Failed to sync existing customer with provider", {
+                provider: paymentAdapter.provider,
+                customerId: existing.id,
+                error: error instanceof Error ? error.message : String(error)
+              });
+            }
+          }
+          const updated = await storage.customers.update(existing.id, input);
           if (updated) {
-            await this.emitter.emit("customer.updated", updated);
+            await emitter.emit("customer.updated", updated);
           }
           return updated ?? existing;
         }
-        const customer = await this.storage.customers.create(input);
-        await this.emitter.emit("customer.created", customer);
+        const customer = await storage.customers.create(input);
+        if (paymentAdapter) {
+          try {
+            const providerInput = {
+              email: input.email,
+              externalId: input.externalId
+            };
+            if (input.name !== void 0) providerInput.name = input.name;
+            if (input.metadata) providerInput.metadata = input.metadata;
+            const providerCustomerId = await paymentAdapter.customers.create(providerInput);
+            const updated = await storage.customers.update(customer.id, {
+              providerCustomerIds: {
+                ...customer.providerCustomerIds,
+                [paymentAdapter.provider]: providerCustomerId
+              }
+            });
+            await emitter.emit("customer.created", updated ?? customer);
+            return updated ?? customer;
+          } catch (error) {
+            this.logger.error("Failed to sync new customer with provider", {
+              provider: paymentAdapter.provider,
+              error: error instanceof Error ? error.message : String(error)
+            });
+            await emitter.emit("customer.created", customer);
+            return customer;
+          }
+        }
+        await emitter.emit("customer.created", customer);
         return customer;
       }
     };
@@ -1416,13 +1606,29 @@ var QZPayBillingImpl = class {
         if (!currentSubscription) {
           throw new Error(`Subscription ${id} not found`);
         }
-        const currentPlan = planMap.get(currentSubscription.planId);
-        const currentPrice = currentPlan?.prices[0] ?? null;
-        const newPlan = planMap.get(options.newPlanId);
+        let currentPlan = planMap.get(currentSubscription.planId);
+        if (!currentPlan) {
+          currentPlan = await storage.plans.findById(currentSubscription.planId) ?? void 0;
+        }
+        let currentPrice = currentPlan?.prices[0] ?? null;
+        if (currentPlan && (!currentPlan.prices || currentPlan.prices.length === 0)) {
+          const storagePrices = await storage.prices.findByPlanId(currentSubscription.planId);
+          if (storagePrices.length > 0) {
+            currentPrice = storagePrices[0] ?? null;
+          }
+        }
+        let newPlan = planMap.get(options.newPlanId);
+        if (!newPlan) {
+          newPlan = await storage.plans.findById(options.newPlanId) ?? void 0;
+        }
         if (!newPlan) {
           throw new Error(`Plan ${options.newPlanId} not found`);
         }
-        const newPrice = options.newPriceId ? newPlan.prices.find((p) => p.id === options.newPriceId) : newPlan.prices[0];
+        let newPlanPrices = newPlan.prices || [];
+        if (newPlanPrices.length === 0) {
+          newPlanPrices = await storage.prices.findByPlanId(options.newPlanId);
+        }
+        const newPrice = options.newPriceId ? newPlanPrices.find((p) => p.id === options.newPriceId) : newPlanPrices[0];
         if (!newPrice) {
           throw new Error(`Price not found for plan ${options.newPlanId}`);
         }
@@ -1476,6 +1682,7 @@ var QZPayBillingImpl = class {
     return {
       // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Complex payment processing with provider integration and error handling
       process: async (input) => {
+        qzpayCreateValidator(input).required("amount", "Amount is required").custom(typeof input.amount === "number" && input.amount > 0, "Amount must be greater than 0").required("currency", "Currency is required").currency("currency", "Invalid currency code").assertValid();
         const paymentId = crypto.randomUUID();
         const now = /* @__PURE__ */ new Date();
         const payment = await storage.payments.create({
@@ -1511,6 +1718,15 @@ var QZPayBillingImpl = class {
             if (input.subscriptionId !== void 0) paymentInput.subscriptionId = input.subscriptionId;
             if (input.invoiceId !== void 0) paymentInput.invoiceId = input.invoiceId;
             if (input.metadata !== void 0) paymentInput.metadata = input.metadata;
+            if (input.token !== void 0) paymentInput.token = input.token;
+            if (input.cardId !== void 0) paymentInput.cardId = input.cardId;
+            if (input.installments !== void 0) paymentInput.installments = input.installments;
+            if (input.payerEmail) {
+              paymentInput.payerEmail = input.payerEmail;
+            } else if (customer?.email) {
+              paymentInput.payerEmail = customer.email;
+            }
+            if (input.payerIdentification) paymentInput.payerIdentification = input.payerIdentification;
             const result = await paymentAdapter.payments.create(providerCustomerId, paymentInput);
             const updated = await storage.payments.update(paymentId, {
               status: "succeeded",
@@ -1518,8 +1734,20 @@ var QZPayBillingImpl = class {
             });
             await emitter.emit("payment.succeeded", updated);
             return updated;
-          } catch {
-            const failed = await storage.payments.update(paymentId, { status: "failed" });
+          } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown payment error";
+            this.logger.error("Payment processing failed", {
+              provider: paymentAdapter.provider,
+              customerId: input.customerId,
+              amount: input.amount,
+              currency: input.currency,
+              error: errorMessage
+            });
+            const failed = await storage.payments.update(paymentId, {
+              status: "failed",
+              failureMessage: errorMessage,
+              failureCode: "payment_failed"
+            });
             await emitter.emit("payment.failed", failed);
             return failed;
           }
@@ -1528,6 +1756,39 @@ var QZPayBillingImpl = class {
       },
       get: (id) => storage.payments.findById(id),
       getByCustomerId: (customerId) => storage.payments.findByCustomerId(customerId),
+      /**
+       * Record an external payment (already processed by a payment provider)
+       * Use this when the payment was processed by an external system (e.g., backend API)
+       * and you need to create a local record for tracking purposes.
+       */
+      record: async (input) => {
+        const now = /* @__PURE__ */ new Date();
+        const providerPaymentIds = {};
+        if (input.provider && input.providerPaymentId) {
+          providerPaymentIds[input.provider] = input.providerPaymentId;
+        }
+        const payment = await storage.payments.create({
+          id: input.id,
+          customerId: input.customerId,
+          amount: input.amount,
+          currency: input.currency,
+          status: input.status,
+          invoiceId: input.invoiceId ?? null,
+          subscriptionId: input.subscriptionId ?? null,
+          paymentMethodId: null,
+          failureCode: null,
+          failureMessage: null,
+          metadata: input.metadata ?? {},
+          livemode: this.livemode,
+          createdAt: now,
+          updatedAt: now,
+          providerPaymentIds
+        });
+        if (input.status === "succeeded") {
+          await emitter.emit("payment.succeeded", payment);
+        }
+        return payment;
+      },
       refund: async (input) => {
         const payment = await storage.payments.findById(input.paymentId);
         if (!payment) {
@@ -1549,6 +1810,10 @@ var QZPayBillingImpl = class {
     const emitter = this.emitter;
     return {
       create: async (input) => {
+        qzpayCreateValidator(input).required("customerId", "Customer ID is required").required("lines", "Invoice lines are required").custom(Array.isArray(input.lines) && input.lines.length > 0, "Invoice must have at least one line item").assertValid();
+        for (const line of input.lines) {
+          qzpayCreateValidator(line).custom(typeof line.quantity === "number" && line.quantity > 0, "Line quantity must be greater than 0").custom(typeof line.unitAmount === "number" && line.unitAmount >= 0, "Line unit amount must be non-negative").assertValid();
+        }
         const invoice = await storage.invoices.create({
           id: crypto.randomUUID(),
           customerId: input.customerId,
@@ -1601,7 +1866,7 @@ var QZPayBillingImpl = class {
   get promoCodes() {
     const storage = this.storage;
     return {
-      validate: async (code, _customerId, _planId) => {
+      validate: async (code, customerId, planId) => {
         const promoCode = await storage.promoCodes.findByCode(code);
         if (!promoCode) {
           return { valid: false, promoCode: null, error: "Promo code not found" };
@@ -1609,12 +1874,26 @@ var QZPayBillingImpl = class {
         if (!promoCode.active) {
           return { valid: false, promoCode, error: "Promo code is not active" };
         }
-        if (promoCode.validUntil && /* @__PURE__ */ new Date() > promoCode.validUntil) {
+        const now = /* @__PURE__ */ new Date();
+        if (promoCode.validFrom && now < promoCode.validFrom) {
+          return { valid: false, promoCode, error: "Promo code is not yet valid" };
+        }
+        if (promoCode.validUntil && now > promoCode.validUntil) {
           return { valid: false, promoCode, error: "Promo code has expired" };
         }
         if (promoCode.maxRedemptions && promoCode.currentRedemptions >= promoCode.maxRedemptions) {
           return { valid: false, promoCode, error: "Promo code has reached max redemptions" };
         }
+        if (planId && promoCode.applicablePlanIds.length > 0 && !promoCode.applicablePlanIds.includes(planId)) {
+          return { valid: false, promoCode, error: "Promo code is not applicable to this plan" };
+        }
+        if (customerId && promoCode.maxRedemptionsPerCustomer !== null && promoCode.maxRedemptionsPerCustomer > 0) {
+          const customerSubscriptions = await storage.subscriptions.findByCustomerId(customerId);
+          const redemptionCount = customerSubscriptions.filter((sub) => sub.promoCodeId === promoCode.id).length;
+          if (redemptionCount >= promoCode.maxRedemptionsPerCustomer) {
+            return { valid: false, promoCode, error: "You have reached the maximum redemption limit for this promo code" };
+          }
+        }
         const result = {
           valid: true,
           promoCode
@@ -1767,6 +2046,10 @@ var QZPayBillingImpl = class {
     const emitter = this.emitter;
     return {
       create: async (input) => {
+        qzpayCreateValidator(input).required("name", "Add-on name is required").required("unitAmount", "Unit amount is required").custom(typeof input.unitAmount === "number" && input.unitAmount > 0, "Unit amount must be greater than 0").required("currency", "Currency is required").currency("currency", "Invalid currency code").custom(
+          !input.billingIntervalCount || typeof input.billingIntervalCount === "number" && input.billingIntervalCount > 0,
+          "Billing interval count must be greater than 0"
+        ).assertValid();
         const addon = await storage.addons.create({
           id: input.id ?? crypto.randomUUID(),
           ...input
@@ -6768,108 +7051,6 @@ function createHealthService(config) {
   return new QZPayHealthService(config);
 }
 
-// src/utils/validation.utils.ts
-function qzpayIsValidEmail(email) {
-  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-  return emailRegex.test(email);
-}
-function qzpayIsValidCurrency(currency) {
-  return QZPAY_CURRENCY_VALUES.includes(currency);
-}
-function qzpayIsPositiveInteger(value) {
-  return Number.isInteger(value) && value > 0;
-}
-function qzpayIsNonNegativeInteger(value) {
-  return Number.isInteger(value) && value >= 0;
-}
-function qzpayIsValidPercentage(value) {
-  return value >= 0 && value <= 100;
-}
-function qzpayIsValidUuid(value) {
-  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-  return uuidRegex.test(value);
-}
-function qzpayIsRequiredString(value) {
-  return typeof value === "string" && value.trim().length > 0;
-}
-function qzpayValidateRequired(obj, requiredFields) {
-  const errors = [];
-  for (const field of requiredFields) {
-    const value = obj[field];
-    if (value === void 0 || value === null || value === "") {
-      errors.push(`${String(field)} is required`);
-    }
-  }
-  return {
-    valid: errors.length === 0,
-    errors
-  };
-}
-function qzpayAssert(condition, message) {
-  if (!condition) {
-    throw new Error(message);
-  }
-}
-function qzpayAssertDefined(value, name) {
-  if (value === null || value === void 0) {
-    throw new Error(`${name} is required`);
-  }
-}
-function qzpayCreateValidator(obj) {
-  return new QZPayValidator(obj);
-}
-var QZPayValidator = class {
-  constructor(obj) {
-    this.obj = obj;
-  }
-  errors = [];
-  required(field, message) {
-    const value = this.obj[field];
-    if (value === void 0 || value === null || value === "") {
-      this.errors.push(message ?? `${String(field)} is required`);
-    }
-    return this;
-  }
-  email(field, message) {
-    const value = this.obj[field];
-    if (typeof value === "string" && !qzpayIsValidEmail(value)) {
-      this.errors.push(message ?? `${String(field)} must be a valid email`);
-    }
-    return this;
-  }
-  positiveInteger(field, message) {
-    const value = this.obj[field];
-    if (typeof value === "number" && !qzpayIsPositiveInteger(value)) {
-      this.errors.push(message ?? `${String(field)} must be a positive integer`);
-    }
-    return this;
-  }
-  currency(field, message) {
-    const value = this.obj[field];
-    if (typeof value === "string" && !qzpayIsValidCurrency(value)) {
-      this.errors.push(message ?? `${String(field)} must be a valid currency`);
-    }
-    return this;
-  }
-  custom(condition, message) {
-    if (!condition) {
-      this.errors.push(message);
-    }
-    return this;
-  }
-  validate() {
-    return {
-      valid: this.errors.length === 0,
-      errors: [...this.errors]
-    };
-  }
-  assertValid() {
-    if (this.errors.length > 0) {
-      throw new Error(`Validation failed: ${this.errors.join(", ")}`);
-    }
-  }
-};
-
 exports.QZPAY_BILLING_EVENT = QZPAY_BILLING_EVENT;
 exports.QZPAY_BILLING_EVENT_VALUES = QZPAY_BILLING_EVENT_VALUES;
 exports.QZPAY_BILLING_INTERVAL = QZPAY_BILLING_INTERVAL;