autumn-js 0.1.11 → 0.1.13

package/dist/sdk/index.d.mts

@@ -487,6 +487,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>>;
@@ -527,52 +529,16 @@ declare enum FeatureType {
 declare const FeatureSchema: z$1.ZodObject<{
     id: z$1.ZodString;
     name: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
-    type: z$1.ZodNativeEnum<typeof FeatureType>;
+    type: z$1.ZodEnum<typeof FeatureType>;
     display: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodObject<{
         singular: z$1.ZodString;
         plural: z$1.ZodString;
-    }, "strip", z$1.ZodTypeAny, {
-        singular: string;
-        plural: string;
-    }, {
-        singular: string;
-        plural: string;
-    }>>>;
+    }, z$1.core.$strip>>>;
     credit_schema: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodArray<z$1.ZodObject<{
         metered_feature_id: z$1.ZodString;
         credit_cost: z$1.ZodNumber;
-    }, "strip", z$1.ZodTypeAny, {
-        metered_feature_id: string;
-        credit_cost: number;
-    }, {
-        metered_feature_id: string;
-        credit_cost: number;
-    }>, "many">>>;
-}, "strip", z$1.ZodTypeAny, {
-    id: string;
-    type: FeatureType;
-    credit_schema?: {
-        metered_feature_id: string;
-        credit_cost: number;
-    }[] | null | undefined;
-    name?: string | null | undefined;
-    display?: {
-        singular: string;
-        plural: string;
-    } | null | undefined;
-}, {
-    id: string;
-    type: FeatureType;
-    credit_schema?: {
-        metered_feature_id: string;
-        credit_cost: number;
-    }[] | null | undefined;
-    name?: string | null | undefined;
-    display?: {
-        singular: string;
-        plural: string;
-    } | null | undefined;
-}>;
+    }, z$1.core.$strip>>>>;
+}, z$1.core.$strip>;
 type Feature = z$1.infer<typeof FeatureSchema>;
 
 type Success<T> = {
@@ -670,9 +636,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;
@@ -687,8 +707,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;
@@ -704,18 +723,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;
@@ -724,6 +801,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;
@@ -731,8 +827,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>>;
 }
 

package/dist/sdk/index.d.ts

@@ -487,6 +487,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>>;
@@ -527,52 +529,16 @@ declare enum FeatureType {
 declare const FeatureSchema: z$1.ZodObject<{
     id: z$1.ZodString;
     name: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodString>>;
-    type: z$1.ZodNativeEnum<typeof FeatureType>;
+    type: z$1.ZodEnum<typeof FeatureType>;
     display: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodObject<{
         singular: z$1.ZodString;
         plural: z$1.ZodString;
-    }, "strip", z$1.ZodTypeAny, {
-        singular: string;
-        plural: string;
-    }, {
-        singular: string;
-        plural: string;
-    }>>>;
+    }, z$1.core.$strip>>>;
     credit_schema: z$1.ZodOptional<z$1.ZodNullable<z$1.ZodArray<z$1.ZodObject<{
         metered_feature_id: z$1.ZodString;
         credit_cost: z$1.ZodNumber;
-    }, "strip", z$1.ZodTypeAny, {
-        metered_feature_id: string;
-        credit_cost: number;
-    }, {
-        metered_feature_id: string;
-        credit_cost: number;
-    }>, "many">>>;
-}, "strip", z$1.ZodTypeAny, {
-    id: string;
-    type: FeatureType;
-    credit_schema?: {
-        metered_feature_id: string;
-        credit_cost: number;
-    }[] | null | undefined;
-    name?: string | null | undefined;
-    display?: {
-        singular: string;
-        plural: string;
-    } | null | undefined;
-}, {
-    id: string;
-    type: FeatureType;
-    credit_schema?: {
-        metered_feature_id: string;
-        credit_cost: number;
-    }[] | null | undefined;
-    name?: string | null | undefined;
-    display?: {
-        singular: string;
-        plural: string;
-    } | null | undefined;
-}>;
+    }, z$1.core.$strip>>>>;
+}, z$1.core.$strip>;
 type Feature = z$1.infer<typeof FeatureSchema>;
 
 type Success<T> = {
@@ -670,9 +636,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;
@@ -687,8 +707,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;
@@ -704,18 +723,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;
@@ -724,6 +801,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;
@@ -731,8 +827,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>>;
 }