autumn-js 0.1.11 → 0.1.12

package/dist/libraries/react/index.mjs

@@ -512,22 +512,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,
@@ -535,6 +605,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,
@@ -542,6 +630,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,
@@ -549,12 +660,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,
@@ -562,6 +711,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,
@@ -777,6 +945,8 @@ var CheckoutParamsSchema = z7.object({
   product_id: z7.string(),
   entity_id: z7.string().optional(),
   options: z7.array(AttachFeatureOptionsSchema).optional(),
+  force_checkout: z7.boolean().optional(),
+  invoice: z7.boolean().optional(),
   success_url: z7.string().optional(),
   customer_data: CustomerDataSchema.optional(),
   entity_data: z7.any().optional(),
@@ -1476,7 +1646,6 @@ var useAutumnBase = ({
   };
   return {
     attach,
-    // check,
     track,
     cancel,
     openBillingPortal,
@@ -1696,16 +1865,6 @@ var useCustomerBase = ({
         context
       });
       return res;
-    },
-    /** @deprecated Use check() instead */
-    allowed: (params2) => {
-      const result = handleCheck2({
-        customer,
-        params: params2,
-        isEntity: false,
-        context
-      });
-      return result.data.allowed;
     }
   };
 };

package/dist/libraries/react/{prodTypes-B8NdKyKo.d.ts → prodTypes-C8xRoBP7.d.mts}

@@ -168,4 +168,4 @@ interface Product {
     };
 }
 
-export { AppEnv as A, type CheckFeaturePreview as C, type Product as P, type ProductItem as a, type CheckFeatureResult as b, type CheckProductResult as c, ProductItemInterval as d, type ProductScenario as e };
+export { AppEnv as A, type CheckFeaturePreview as C, type Product as P, type CheckFeatureResult as a, type CheckProductResult as b, type ProductItem as c, ProductItemInterval as d, type ProductScenario as e };

package/dist/libraries/react/{prodTypes-B8NdKyKo.d.mts → prodTypes-C8xRoBP7.d.ts}

@@ -168,4 +168,4 @@ interface Product {
     };
 }
 
-export { AppEnv as A, type CheckFeaturePreview as C, type Product as P, type ProductItem as a, type CheckFeatureResult as b, type CheckProductResult as c, ProductItemInterval as d, type ProductScenario as e };
+export { AppEnv as A, type CheckFeaturePreview as C, type Product as P, type CheckFeatureResult as a, type CheckProductResult as b, type ProductItem as c, ProductItemInterval as d, type ProductScenario as e };

package/dist/next/client/hooks/useCustomer.d.mts

@@ -17,28 +17,65 @@ declare const RedeemReferralCodeParamsSchema: z.ZodObject<{
 }, z.core.$strip>;
 type RedeemReferralCodeParams = z.infer<typeof RedeemReferralCodeParamsSchema>;
 
-interface AllowedParams {
-    featureId?: string;
-    productId?: string;
-    requiredBalance?: number;
-}
-
 interface UseCustomerResult {
+    /** The current customer data including subscription and feature information */
     customer: Customer | null;
+    /** Whether customer data is currently being loaded */
     isLoading: boolean;
+    /** Any error that occurred while fetching customer data */
     error: AutumnError | null;
+    /**
+     * Attaches a product to the current customer, enabling access and handling billing.
+     * Activates a product and applies all product items with automatic payment handling.
+     */
     attach: (params: AttachParams) => AutumnPromise<AttachResult | CheckResult>;
+    /**
+     * Tracks usage events for metered features.
+     * Records feature usage and updates customer balances server-side.
+     */
     track: (params: TrackParams) => AutumnPromise<TrackResult>;
+    /**
+     * Cancels a customer's subscription or product attachment.
+     * Can cancel immediately or at the end of the billing cycle.
+     */
     cancel: (params: CancelParams) => AutumnPromise<CancelResult>;
+    /**
+     * Sets up a payment method for the customer.
+     * Collects payment information without immediately charging.
+     */
     setupPayment: (params: SetupPaymentParams) => AutumnPromise<SetupPaymentResult>;
+    /**
+     * Opens the Stripe billing portal for the customer.
+     * Allows customers to manage their subscription and payment methods.
+     */
     openBillingPortal: (params?: OpenBillingPortalParams) => AutumnPromise<BillingPortalResult>;
+    /**
+     * Initiates a checkout flow for product purchase.
+     * Handles payment collection and redirects to Stripe checkout when needed.
+     */
     checkout: (params: CheckoutParams) => AutumnPromise<CheckoutResult>;
+    /** Refetches the customer data from the server */
     refetch: () => Promise<Customer | null>;
+    /**
+     * Creates new entities for granular feature tracking.
+     * Entities allow per-user or per-workspace feature limits.
+     */
     createEntity: (params: CreateEntityParams | CreateEntityParams[]) => AutumnPromise<Entity | Entity[]>;
+    /**
+     * Creates a referral code for the customer.
+     * Generates codes that can be shared for referral programs.
+     */
     createReferralCode: (params: CreateReferralCodeParams) => AutumnPromise<CreateReferralCodeResult>;
+    /**
+     * Redeems a referral code for the customer.
+     * Applies referral benefits when a valid code is provided.
+     */
     redeemReferralCode: (params: RedeemReferralCodeParams) => AutumnPromise<RedeemReferralCodeResult>;
+    /**
+     * Checks if a customer has access to a feature and shows paywalls if needed.
+     * Client-side feature gating with optional dialog display for upgrades.
+     */
     check: (params: CheckParams) => Success<CheckResult>;
-    allowed: (params: AllowedParams) => boolean;
 }
 interface UseCustomerParams {
     errorOnNotFound?: boolean;

package/dist/next/client/hooks/useCustomer.d.ts

@@ -17,28 +17,65 @@ declare const RedeemReferralCodeParamsSchema: z.ZodObject<{
 }, z.core.$strip>;
 type RedeemReferralCodeParams = z.infer<typeof RedeemReferralCodeParamsSchema>;
 
-interface AllowedParams {
-    featureId?: string;
-    productId?: string;
-    requiredBalance?: number;
-}
-
 interface UseCustomerResult {
+    /** The current customer data including subscription and feature information */
     customer: Customer | null;
+    /** Whether customer data is currently being loaded */
     isLoading: boolean;
+    /** Any error that occurred while fetching customer data */
     error: AutumnError | null;
+    /**
+     * Attaches a product to the current customer, enabling access and handling billing.
+     * Activates a product and applies all product items with automatic payment handling.
+     */
     attach: (params: AttachParams) => AutumnPromise<AttachResult | CheckResult>;
+    /**
+     * Tracks usage events for metered features.
+     * Records feature usage and updates customer balances server-side.
+     */
     track: (params: TrackParams) => AutumnPromise<TrackResult>;
+    /**
+     * Cancels a customer's subscription or product attachment.
+     * Can cancel immediately or at the end of the billing cycle.
+     */
     cancel: (params: CancelParams) => AutumnPromise<CancelResult>;
+    /**
+     * Sets up a payment method for the customer.
+     * Collects payment information without immediately charging.
+     */
     setupPayment: (params: SetupPaymentParams) => AutumnPromise<SetupPaymentResult>;
+    /**
+     * Opens the Stripe billing portal for the customer.
+     * Allows customers to manage their subscription and payment methods.
+     */
     openBillingPortal: (params?: OpenBillingPortalParams) => AutumnPromise<BillingPortalResult>;
+    /**
+     * Initiates a checkout flow for product purchase.
+     * Handles payment collection and redirects to Stripe checkout when needed.
+     */
     checkout: (params: CheckoutParams) => AutumnPromise<CheckoutResult>;
+    /** Refetches the customer data from the server */
     refetch: () => Promise<Customer | null>;
+    /**
+     * Creates new entities for granular feature tracking.
+     * Entities allow per-user or per-workspace feature limits.
+     */
     createEntity: (params: CreateEntityParams | CreateEntityParams[]) => AutumnPromise<Entity | Entity[]>;
+    /**
+     * Creates a referral code for the customer.
+     * Generates codes that can be shared for referral programs.
+     */
     createReferralCode: (params: CreateReferralCodeParams) => AutumnPromise<CreateReferralCodeResult>;
+    /**
+     * Redeems a referral code for the customer.
+     * Applies referral benefits when a valid code is provided.
+     */
     redeemReferralCode: (params: RedeemReferralCodeParams) => AutumnPromise<RedeemReferralCodeResult>;
+    /**
+     * Checks if a customer has access to a feature and shows paywalls if needed.
+     * Client-side feature gating with optional dialog display for upgrades.
+     */
     check: (params: CheckParams) => Success<CheckResult>;
-    allowed: (params: AllowedParams) => boolean;
 }
 interface UseCustomerParams {
     errorOnNotFound?: boolean;

package/dist/next/server/cusActions.d.mts

@@ -114,6 +114,8 @@ declare const CheckoutParamsSchema: z.ZodObject<{
         feature_id: z.ZodString;
         quantity: z.ZodNumber;
     }, z.core.$strip>>>;
+    force_checkout: z.ZodOptional<z.ZodBoolean>;
+    invoice: z.ZodOptional<z.ZodBoolean>;
     success_url: z.ZodOptional<z.ZodString>;
     customer_data: z.ZodOptional<z.ZodObject<{
         name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -178,11 +180,11 @@ declare const FeatureSchema: z$1.ZodObject<{
 }, "strip", z$1.ZodTypeAny, {
     id: string;
     type: FeatureType;
+    name?: string | null | undefined;
     credit_schema?: {
         metered_feature_id: string;
         credit_cost: number;
     }[] | null | undefined;
-    name?: string | null | undefined;
     display?: {
         singular: string;
         plural: string;
@@ -190,11 +192,11 @@ declare const FeatureSchema: z$1.ZodObject<{
 }, {
     id: string;
     type: FeatureType;
+    name?: string | null | undefined;
     credit_schema?: {
         metered_feature_id: string;
         credit_cost: number;
     }[] | null | undefined;
-    name?: string | null | undefined;
     display?: {
         singular: string;
         plural: string;
@@ -279,9 +281,63 @@ declare class Autumn {
             list: Feature[];
         }, AutumnError>>;
     };
-    static checkout: (params: CheckoutParams) => Promise<Result<CheckoutResult, AutumnError>>;
+    /**
+     * 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;
+     * }
+     * ```
+     */
     checkout(params: CheckoutParams): Promise<Result<CheckoutResult, AutumnError>>;
-    static attach: (params: AttachParams) => Promise<Result<{
+    static checkout: (params: CheckoutParams) => Promise<Result<CheckoutResult, AutumnError>>;
+    static usage: (params: UsageParams) => Promise<Result<UsageResult, AutumnError>>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    attach(params: AttachParams): Promise<Result<{
         customer_id: string;
         product_ids: string[];
         code: string;
@@ -296,8 +352,7 @@ declare class Autumn {
             currency: string;
         } | undefined;
     }, AutumnError>>;
-    static usage: (params: UsageParams) => Promise<Result<UsageResult, AutumnError>>;
-    attach(params: AttachParams): Promise<Result<{
+    static attach: (params: AttachParams) => Promise<Result<{
         customer_id: string;
         product_ids: string[];
         code: string;
@@ -313,18 +368,76 @@ declare class Autumn {
         } | undefined;
     }, AutumnError>>;
     static setupPayment: (params: SetupPaymentParams) => Promise<Result<SetupPaymentResult, AutumnError>>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
     setupPayment(params: SetupPaymentParams): Promise<Result<SetupPaymentResult, AutumnError>>;
     static cancel: (params: CancelParams) => Promise<Result<{
         success: boolean;
         customer_id: string;
         product_id: string;
     }, AutumnError>>;
+    /**
+     * 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
+     * });
+     * ```
+     */
     cancel(params: CancelParams): Promise<Result<{
         success: boolean;
         customer_id: string;
         product_id: string;
     }, AutumnError>>;
     static check: (params: CheckParams) => Promise<Result<CheckResult, AutumnError>>;
+    /**
+     * 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");
+     * }
+     * ```
+     */
     check(params: CheckParams): Promise<Result<CheckResult, AutumnError>>;
     static track: (params: TrackParams) => Promise<Result<{
         id: string;
@@ -333,6 +446,25 @@ declare class Autumn {
         feature_id?: string | undefined;
         event_name?: string | undefined;
     }, AutumnError>>;
+    /**
+     * 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
+     * });
+     * ```
+     */
     track(params: TrackParams): Promise<Result<{
         id: string;
         code: string;
@@ -340,8 +472,46 @@ declare class Autumn {
         feature_id?: string | undefined;
         event_name?: string | undefined;
     }, AutumnError>>;
+    /**
+     * 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
+     * });
+     * ```
+     */
     usage(params: UsageParams): Promise<Result<UsageResult, AutumnError>>;
     static query: (params: QueryParams) => Promise<Result<QueryResult, AutumnError>>;
+    /**
+     * 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
+     * });
+     *
+     * ```
+     */
     query(params: QueryParams): Promise<Result<QueryResult, AutumnError>>;
 }