autumn-js 0.1.10 → 0.1.12

package/dist/utils/encryptUtils.js

@@ -484,22 +484,92 @@ var Autumn = class {
   entities = entityMethods(this);
   referrals = referralMethods(this);
   features = featureMethods(this);
-  static checkout = (params) => staticWrapper(handleCheckout, void 0, { params });
+  /**
+   * Initiates a checkout flow for a product purchase.
+   * 
+   * The checkout function handles the purchase process for products with pricing.
+   * It determines whether to show a dialog for user input or redirect directly
+   * to Stripe based on the customer's state and product requirements.
+   * 
+   * @param params - Checkout parameters including product ID, customer data, and options
+   * @returns Promise resolving to checkout details including pricing, prorations, and URLs
+   * 
+   * @example
+   * ```typescript
+   * const result = await autumn.checkout({
+   *   customer_id: "user_123",
+   *   product_id: "pro",
+   *   success_url: "https://myapp.com/success"
+   * });
+   * 
+   * if (result.url) {
+   *   // Redirect to Stripe checkout
+   *   window.location.href = result.url;
+   * }
+   * ```
+   */
   async checkout(params) {
     return handleCheckout({
       instance: this,
       params
     });
   }
-  static attach = (params) => staticWrapper(handleAttach, void 0, { params });
+  static checkout = (params) => staticWrapper(handleCheckout, void 0, { params });
   static usage = (params) => staticWrapper(handleUsage, void 0, { params });
+  /**
+   * Attaches a product to a customer, enabling access and handling billing.
+   * 
+   * The attach function activates a product for a customer and applies all product items.
+   * When you attach a product:
+   * - The customer gains access to all features in the product
+   * - If the product has prices, the customer will be billed accordingly  
+   * - If there's no existing payment method, a checkout URL will be generated
+   * 
+   * @param params - Attach parameters including customer ID, product ID, and options
+   * @returns Promise resolving to attachment result with checkout URL if needed
+   * 
+   * @example
+   * ```typescript
+   * const result = await autumn.attach({
+   *   customer_id: "user_123",
+   *   product_id: "pro",
+   *   success_url: "https://myapp.com/success"
+   * });
+   * 
+   * if (result.checkout_url) {
+   *   // Payment required - redirect to checkout
+   *   window.location.href = result.checkout_url;
+   * } else {
+   *   // Product successfully attached
+   *   console.log("Access granted:", result.message);
+   * }
+   * ```
+   */
   async attach(params) {
     return handleAttach({
       instance: this,
       params
     });
   }
+  static attach = (params) => staticWrapper(handleAttach, void 0, { params });
   static setupPayment = (params) => staticWrapper(handleSetupPayment, void 0, { params });
+  /**
+   * Sets up a payment method for a customer.
+   * 
+   * This method allows you to set up payment methods for customers without 
+   * immediately charging them. Useful for collecting payment information
+   * before product attachment or for updating existing payment methods.
+   * 
+   * @param params - Setup payment parameters including customer information
+   * @returns Promise resolving to setup payment result
+   * 
+   * @example
+   * ```typescript
+   * const result = await autumn.setupPayment({
+   *   customer_id: "user_123"
+   * });
+   * ```
+   */
   async setupPayment(params) {
     return handleSetupPayment({
       instance: this,
@@ -507,6 +577,24 @@ var Autumn = class {
     });
   }
   static cancel = (params) => staticWrapper(handleCancel, void 0, { params });
+  /**
+   * Cancels a customer's subscription or product attachment.
+   * 
+   * This method allows you to cancel a customer's subscription to a specific product.
+   * You can choose to cancel immediately or at the end of the billing cycle.
+   * 
+   * @param params - Cancel parameters including customer ID and product ID
+   * @returns Promise resolving to cancellation result
+   * 
+   * @example
+   * ```typescript
+   * const result = await autumn.cancel({
+   *   customer_id: "user_123",
+   *   product_id: "pro",
+   *   cancel_immediately: false // Cancel at end of billing cycle
+   * });
+   * ```
+   */
   async cancel(params) {
     return handleCancel({
       instance: this,
@@ -514,6 +602,29 @@ var Autumn = class {
     });
   }
   static check = (params) => staticWrapper(handleCheck, void 0, { params });
+  /**
+   * Checks if a customer has access to a specific feature.
+   * 
+   * This method verifies whether a customer has permission to use a feature
+   * and checks their remaining balance/usage limits. It can be used to gate
+   * features and determine when to show upgrade prompts.
+   * 
+   * @param params - Check parameters including customer ID and feature ID
+   * @returns Promise resolving to access check result with allowed status and balance info
+   * 
+   * @example
+   * ```typescript
+   * const result = await autumn.check({
+   *   customer_id: "user_123",
+   *   feature_id: "messages",
+   *   required_balance: 1
+   * });
+   * 
+   * if (!result.allowed) {
+   *   console.log("Feature access denied - upgrade required");
+   * }
+   * ```
+   */
   async check(params) {
     return handleCheck({
       instance: this,
@@ -521,12 +632,50 @@ var Autumn = class {
     });
   }
   static track = (params) => staticWrapper(handleTrack, void 0, { params });
+  /**
+   * Tracks usage events for features or analytics.
+   * 
+   * This method records usage events for metered features, updating the customer's
+   * balance and usage statistics. It's typically used server-side to ensure
+   * accurate tracking that cannot be manipulated by users.
+   * 
+   * @param params - Track parameters including customer ID, feature ID, and usage value
+   * @returns Promise resolving to tracking result
+   * 
+   * @example
+   * ```typescript
+   * const result = await autumn.track({
+   *   customer_id: "user_123",
+   *   feature_id: "messages",
+   *   value: 1 // Track 1 message sent
+   * });
+   * ```
+   */
   async track(params) {
     return handleTrack({
       instance: this,
       params
     });
   }
+  /**
+   * Retrieves usage statistics and analytics for a customer.
+   * 
+   * This method fetches detailed usage information for a customer's features,
+   * including current balances, usage history, and analytics data. Useful
+   * for displaying usage dashboards or generating reports.
+   * 
+   * @param params - Usage parameters including customer ID and optional filters
+   * @returns Promise resolving to usage statistics and analytics data
+   * 
+   * @example
+   * ```typescript
+   * const result = await autumn.usage({
+   *   customer_id: "user_123",
+   *   feature_id: "messages" 
+   *   value: 20 // Usage value
+   * });
+   * ```
+   */
   async usage(params) {
     return handleUsage({
       instance: this,
@@ -534,6 +683,25 @@ var Autumn = class {
     });
   }
   static query = (params) => staticWrapper(handleQuery, void 0, { params });
+  /**
+   * Performs advanced queries on customer data and analytics.
+   * 
+   * This method allows you to run complex queries against customer data,
+   * usage patterns, and billing information. Useful for generating reports,
+   * analytics, and custom data insights.
+   * 
+   * @param params - Query parameters including customer ID and query specifications
+   * @returns Promise resolving to query results with requested data
+   * 
+   * @example
+   * ```typescript
+   * const result = await autumn.query({
+   *   customer_id: "user_123",
+   *   feature_id: "messages" // feature id to fetch for query, can also be an array
+   * });
+   * 
+   * ```
+   */
   async query(params) {
     return handleQuery({
       instance: this,
@@ -557,8 +725,8 @@ var ProductItemInterval = /* @__PURE__ */ ((ProductItemInterval2) => {
 })(ProductItemInterval || {});
 
 // src/sdk/customers/cusEnums.ts
-var import_zod = require("zod");
-var CustomerExpandEnum = import_zod.z.enum([
+var import_v4 = require("zod/v4");
+var CustomerExpandEnum = import_v4.z.enum([
   "invoices",
   "rewards",
   "trials_used",
@@ -568,192 +736,194 @@ var CustomerExpandEnum = import_zod.z.enum([
 ]);
 
 // src/sdk/customers/cusTypes.ts
-var import_zod2 = require("zod");
-var CoreCusFeatureSchema = import_zod2.z.object({
-  unlimited: import_zod2.z.boolean().optional(),
-  interval: import_zod2.z.nativeEnum(ProductItemInterval).optional(),
-  balance: import_zod2.z.number().nullish(),
-  usage: import_zod2.z.number().optional(),
-  included_usage: import_zod2.z.number().optional(),
-  next_reset_at: import_zod2.z.number().nullish(),
-  overage_allowed: import_zod2.z.boolean().optional(),
-  usage_limit: import_zod2.z.number().optional(),
-  rollovers: import_zod2.z.object({
-    balance: import_zod2.z.number(),
-    expires_at: import_zod2.z.number()
+var import_v42 = require("zod/v4");
+var CoreCusFeatureSchema = import_v42.z.object({
+  unlimited: import_v42.z.boolean().optional(),
+  interval: import_v42.z.enum(ProductItemInterval).optional(),
+  balance: import_v42.z.number().nullish(),
+  usage: import_v42.z.number().optional(),
+  included_usage: import_v42.z.number().optional(),
+  next_reset_at: import_v42.z.number().nullish(),
+  overage_allowed: import_v42.z.boolean().optional(),
+  usage_limit: import_v42.z.number().optional(),
+  rollovers: import_v42.z.object({
+    balance: import_v42.z.number(),
+    expires_at: import_v42.z.number()
   }).optional(),
-  breakdown: import_zod2.z.array(
-    import_zod2.z.object({
-      interval: import_zod2.z.nativeEnum(ProductItemInterval),
-      balance: import_zod2.z.number().optional(),
-      usage: import_zod2.z.number().optional(),
-      included_usage: import_zod2.z.number().optional(),
-      next_reset_at: import_zod2.z.number().optional()
+  breakdown: import_v42.z.array(
+    import_v42.z.object({
+      interval: import_v42.z.enum(ProductItemInterval),
+      balance: import_v42.z.number().optional(),
+      usage: import_v42.z.number().optional(),
+      included_usage: import_v42.z.number().optional(),
+      next_reset_at: import_v42.z.number().optional()
     })
   ).optional(),
-  credit_schema: import_zod2.z.array(
-    import_zod2.z.object({
-      feature_id: import_zod2.z.string(),
-      credit_amount: import_zod2.z.number()
+  credit_schema: import_v42.z.array(
+    import_v42.z.object({
+      feature_id: import_v42.z.string(),
+      credit_amount: import_v42.z.number()
     })
   ).optional()
 });
-var CustomerDataSchema = import_zod2.z.object({
-  name: import_zod2.z.string().nullish(),
-  email: import_zod2.z.string().nullish(),
-  fingerprint: import_zod2.z.string().nullish()
+var CustomerDataSchema = import_v42.z.object({
+  name: import_v42.z.string().nullish(),
+  email: import_v42.z.string().nullish(),
+  fingerprint: import_v42.z.string().nullish()
 });
-var CreateCustomerParamsSchema = import_zod2.z.object({
-  id: import_zod2.z.string().nullish(),
-  email: import_zod2.z.string().nullish(),
-  name: import_zod2.z.string().nullish(),
-  fingerprint: import_zod2.z.string().nullish(),
-  metadata: import_zod2.z.record(import_zod2.z.any()).optional(),
-  expand: import_zod2.z.array(CustomerExpandEnum).optional()
+var CreateCustomerParamsSchema = import_v42.z.object({
+  id: import_v42.z.string().nullish(),
+  email: import_v42.z.string().nullish(),
+  name: import_v42.z.string().nullish(),
+  fingerprint: import_v42.z.string().nullish(),
+  metadata: import_v42.z.record(import_v42.z.string(), import_v42.z.any()).optional(),
+  expand: import_v42.z.array(CustomerExpandEnum).optional()
 });
-var BillingPortalParamsSchema = import_zod2.z.object({
-  return_url: import_zod2.z.string().optional()
+var BillingPortalParamsSchema = import_v42.z.object({
+  return_url: import_v42.z.string().optional()
 });
-var UpdateBalancesParamsSchema = import_zod2.z.object({
-  feature_id: import_zod2.z.string(),
-  balance: import_zod2.z.number()
+var UpdateBalancesParamsSchema = import_v42.z.object({
+  feature_id: import_v42.z.string(),
+  balance: import_v42.z.number()
 }).or(
-  import_zod2.z.array(
-    import_zod2.z.object({
-      feature_id: import_zod2.z.string(),
-      balance: import_zod2.z.number()
+  import_v42.z.array(
+    import_v42.z.object({
+      feature_id: import_v42.z.string(),
+      balance: import_v42.z.number()
     })
   )
 );
 
 // src/sdk/general/checkTypes.ts
-var import_zod3 = require("zod");
-var CheckFeatureResultSchema = import_zod3.z.object({
-  allowed: import_zod3.z.boolean(),
-  feature_id: import_zod3.z.string(),
-  customer_id: import_zod3.z.string(),
-  entity_id: import_zod3.z.string().optional(),
-  required_balance: import_zod3.z.number()
+var import_v43 = require("zod/v4");
+var CheckFeatureResultSchema = import_v43.z.object({
+  allowed: import_v43.z.boolean(),
+  feature_id: import_v43.z.string(),
+  customer_id: import_v43.z.string(),
+  entity_id: import_v43.z.string().optional(),
+  required_balance: import_v43.z.number()
 }).extend(CoreCusFeatureSchema.shape);
 
 // src/sdk/customers/entities/entTypes.ts
-var import_zod4 = require("zod");
-var EntityDataSchema = import_zod4.z.object({
-  name: import_zod4.z.string().optional(),
-  feature_id: import_zod4.z.string()
+var import_v44 = require("zod/v4");
+var EntityDataSchema = import_v44.z.object({
+  name: import_v44.z.string().optional(),
+  feature_id: import_v44.z.string()
 });
-var TransferProductParamsSchema = import_zod4.z.object({
-  from_entity_id: import_zod4.z.string(),
-  to_entity_id: import_zod4.z.string(),
-  product_id: import_zod4.z.string()
+var TransferProductParamsSchema = import_v44.z.object({
+  from_entity_id: import_v44.z.string(),
+  to_entity_id: import_v44.z.string(),
+  product_id: import_v44.z.string()
 });
 
 // src/sdk/general/genTypes.ts
-var import_zod5 = require("zod");
-var CancelParamsSchema = import_zod5.z.object({
-  customer_id: import_zod5.z.string(),
-  product_id: import_zod5.z.string(),
-  entity_id: import_zod5.z.string().optional(),
-  cancel_immediately: import_zod5.z.boolean().optional()
+var import_v45 = require("zod/v4");
+var CancelParamsSchema = import_v45.z.object({
+  customer_id: import_v45.z.string(),
+  product_id: import_v45.z.string(),
+  entity_id: import_v45.z.string().optional(),
+  cancel_immediately: import_v45.z.boolean().optional()
 });
-var CancelResultSchema = import_zod5.z.object({
-  success: import_zod5.z.boolean(),
-  customer_id: import_zod5.z.string(),
-  product_id: import_zod5.z.string()
+var CancelResultSchema = import_v45.z.object({
+  success: import_v45.z.boolean(),
+  customer_id: import_v45.z.string(),
+  product_id: import_v45.z.string()
 });
-var TrackParamsSchema = import_zod5.z.object({
-  customer_id: import_zod5.z.string(),
-  value: import_zod5.z.number().optional(),
-  feature_id: import_zod5.z.string().optional(),
-  event_name: import_zod5.z.string().optional(),
-  entity_id: import_zod5.z.string().optional(),
-  customer_data: import_zod5.z.any().optional(),
-  idempotency_key: import_zod5.z.string().optional(),
-  entity_data: import_zod5.z.any().optional()
+var TrackParamsSchema = import_v45.z.object({
+  customer_id: import_v45.z.string(),
+  value: import_v45.z.number().optional(),
+  feature_id: import_v45.z.string().optional(),
+  event_name: import_v45.z.string().optional(),
+  entity_id: import_v45.z.string().optional(),
+  customer_data: import_v45.z.any().optional(),
+  idempotency_key: import_v45.z.string().optional(),
+  entity_data: import_v45.z.any().optional()
 });
-var TrackResultSchema = import_zod5.z.object({
-  id: import_zod5.z.string(),
-  code: import_zod5.z.string(),
-  customer_id: import_zod5.z.string(),
-  feature_id: import_zod5.z.string().optional(),
-  event_name: import_zod5.z.string().optional()
+var TrackResultSchema = import_v45.z.object({
+  id: import_v45.z.string(),
+  code: import_v45.z.string(),
+  customer_id: import_v45.z.string(),
+  feature_id: import_v45.z.string().optional(),
+  event_name: import_v45.z.string().optional()
 });
-var CheckParamsSchema = import_zod5.z.object({
-  customer_id: import_zod5.z.string(),
-  feature_id: import_zod5.z.string().optional(),
-  product_id: import_zod5.z.string().optional(),
-  entity_id: import_zod5.z.string().optional(),
-  customer_data: import_zod5.z.any().optional(),
-  required_balance: import_zod5.z.number().optional(),
-  send_event: import_zod5.z.boolean().optional(),
-  with_preview: import_zod5.z.boolean().optional(),
+var CheckParamsSchema = import_v45.z.object({
+  customer_id: import_v45.z.string(),
+  feature_id: import_v45.z.string().optional(),
+  product_id: import_v45.z.string().optional(),
+  entity_id: import_v45.z.string().optional(),
+  customer_data: import_v45.z.any().optional(),
+  required_balance: import_v45.z.number().optional(),
+  send_event: import_v45.z.boolean().optional(),
+  with_preview: import_v45.z.boolean().optional(),
   entity_data: EntityDataSchema.optional()
 });
-var QueryRangeEnum = import_zod5.z.enum(["24h", "7d", "30d", "90d", "last_cycle"]);
-var QueryParamsSchema = import_zod5.z.object({
-  customer_id: import_zod5.z.string(),
-  feature_id: import_zod5.z.string().or(import_zod5.z.array(import_zod5.z.string())),
+var QueryRangeEnum = import_v45.z.enum(["24h", "7d", "30d", "90d", "last_cycle"]);
+var QueryParamsSchema = import_v45.z.object({
+  customer_id: import_v45.z.string(),
+  feature_id: import_v45.z.string().or(import_v45.z.array(import_v45.z.string())),
   range: QueryRangeEnum.optional()
 });
 
 // src/sdk/referrals/referralTypes.ts
-var import_zod6 = require("zod");
-var CreateReferralCodeParamsSchema = import_zod6.z.object({
-  customer_id: import_zod6.z.string(),
-  program_id: import_zod6.z.string()
+var import_v46 = require("zod/v4");
+var CreateReferralCodeParamsSchema = import_v46.z.object({
+  customer_id: import_v46.z.string(),
+  program_id: import_v46.z.string()
 });
-var RedeemReferralCodeParamsSchema = import_zod6.z.object({
-  code: import_zod6.z.string(),
-  customer_id: import_zod6.z.string()
+var RedeemReferralCodeParamsSchema = import_v46.z.object({
+  code: import_v46.z.string(),
+  customer_id: import_v46.z.string()
 });
 
 // src/sdk/general/attachTypes.ts
-var import_zod7 = require("zod");
-var AttachFeatureOptionsSchema = import_zod7.z.object({
-  feature_id: import_zod7.z.string(),
-  quantity: import_zod7.z.number()
+var import_v47 = require("zod/v4");
+var AttachFeatureOptionsSchema = import_v47.z.object({
+  feature_id: import_v47.z.string(),
+  quantity: import_v47.z.number()
 });
-var AttachParamsSchema = import_zod7.z.object({
-  customer_id: import_zod7.z.string(),
-  product_id: import_zod7.z.string().optional(),
-  entity_id: import_zod7.z.string().optional(),
-  options: import_zod7.z.array(AttachFeatureOptionsSchema).optional(),
-  product_ids: import_zod7.z.array(import_zod7.z.string()).optional(),
-  free_trial: import_zod7.z.boolean().optional(),
-  success_url: import_zod7.z.string().optional(),
-  metadata: import_zod7.z.record(import_zod7.z.string()).optional(),
-  force_checkout: import_zod7.z.boolean().optional(),
+var AttachParamsSchema = import_v47.z.object({
+  customer_id: import_v47.z.string(),
+  product_id: import_v47.z.string().optional(),
+  entity_id: import_v47.z.string().optional(),
+  options: import_v47.z.array(AttachFeatureOptionsSchema).optional(),
+  product_ids: import_v47.z.array(import_v47.z.string()).optional(),
+  free_trial: import_v47.z.boolean().optional(),
+  success_url: import_v47.z.string().optional(),
+  metadata: import_v47.z.record(import_v47.z.string(), import_v47.z.string()).optional(),
+  force_checkout: import_v47.z.boolean().optional(),
   customer_data: CustomerDataSchema.optional(),
-  entity_data: import_zod7.z.any().optional(),
-  checkout_session_params: import_zod7.z.record(import_zod7.z.any()).optional(),
-  reward: import_zod7.z.string().optional(),
-  invoice: import_zod7.z.boolean().optional()
+  entity_data: import_v47.z.any().optional(),
+  checkout_session_params: import_v47.z.record(import_v47.z.string(), import_v47.z.any()).optional(),
+  reward: import_v47.z.string().optional(),
+  invoice: import_v47.z.boolean().optional()
 });
-var AttachResultSchema = import_zod7.z.object({
-  checkout_url: import_zod7.z.string().optional(),
-  customer_id: import_zod7.z.string(),
-  product_ids: import_zod7.z.array(import_zod7.z.string()),
-  code: import_zod7.z.string(),
-  message: import_zod7.z.string(),
-  customer_data: import_zod7.z.any().optional(),
-  invoice: import_zod7.z.object({
-    status: import_zod7.z.string(),
-    stripe_id: import_zod7.z.string(),
-    hosted_invoice_url: import_zod7.z.string().nullable(),
-    total: import_zod7.z.number(),
-    currency: import_zod7.z.string()
+var AttachResultSchema = import_v47.z.object({
+  checkout_url: import_v47.z.string().optional(),
+  customer_id: import_v47.z.string(),
+  product_ids: import_v47.z.array(import_v47.z.string()),
+  code: import_v47.z.string(),
+  message: import_v47.z.string(),
+  customer_data: import_v47.z.any().optional(),
+  invoice: import_v47.z.object({
+    status: import_v47.z.string(),
+    stripe_id: import_v47.z.string(),
+    hosted_invoice_url: import_v47.z.string().nullable(),
+    total: import_v47.z.number(),
+    currency: import_v47.z.string()
   }).optional()
 });
-var CheckoutParamsSchema = import_zod7.z.object({
-  customer_id: import_zod7.z.string(),
-  product_id: import_zod7.z.string(),
-  entity_id: import_zod7.z.string().optional(),
-  options: import_zod7.z.array(AttachFeatureOptionsSchema).optional(),
-  success_url: import_zod7.z.string().optional(),
+var CheckoutParamsSchema = import_v47.z.object({
+  customer_id: import_v47.z.string(),
+  product_id: import_v47.z.string(),
+  entity_id: import_v47.z.string().optional(),
+  options: import_v47.z.array(AttachFeatureOptionsSchema).optional(),
+  force_checkout: import_v47.z.boolean().optional(),
+  invoice: import_v47.z.boolean().optional(),
+  success_url: import_v47.z.string().optional(),
   customer_data: CustomerDataSchema.optional(),
-  entity_data: import_zod7.z.any().optional(),
-  checkout_session_params: import_zod7.z.record(import_zod7.z.any()).optional(),
-  reward: import_zod7.z.string().optional()
+  entity_data: import_v47.z.any().optional(),
+  checkout_session_params: import_v47.z.record(import_v47.z.string(), import_v47.z.any()).optional(),
+  reward: import_v47.z.string().optional()
 });
 
 // src/utils/encryptUtils.tsx