@usehercules/sdk 1.8.0 → 1.10.0

package/resources/beta/commerce/products/products.d.ts

@@ -62,6 +62,11 @@ export interface ProductCreateResponse {
      * Display name for the product (e.g., Pro, Business, Teams)
      */
     name: string;
+    /**
+     * ID of the subscription group this product belongs to. Subscription groups define
+     * shared billing configuration. All products must belong to a subscription group.
+     */
+    product_group_id: string;
     /**
      * Price configuration for a product. Can be one-time or recurring (subscription).
      */
@@ -80,11 +85,6 @@ export interface ProductCreateResponse {
     metadata?: {
         [key: string]: unknown;
     };
-    /**
-     * ID of the product group this product belongs to. Product groups define shared
-     * billing configuration.
-     */
-    product_group_id?: string | null;
     /**
      * Resources attached to this product. Customers get access to these resources when
      * they purchase the product.
@@ -104,11 +104,6 @@ export declare namespace ProductCreateResponse {
          * Unique identifier for the topic subscription
          */
         id: string;
-        /**
-         * How to handle the billing cycle when switching plans. 'now' resets to current
-         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
-         */
-        billing_cycle_anchor: 'now' | 'unchanged' | null;
         /**
          * Three-letter ISO currency code (e.g., usd, eur)
          */
@@ -123,16 +118,6 @@ export declare namespace ProductCreateResponse {
          * prices.
          */
         interval_count: number | null;
-        /**
-         * How to handle prorations when switching plans. 'default' creates prorations,
-         * 'none' disables them. Null for one-time prices.
-         */
-        proration_behavior: 'default' | 'none' | null;
-        /**
-         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
-         * billing period start. Null for one-time prices or to use Stripe's default.
-         */
-        proration_date: 'now' | 'start_of_period' | null;
         /**
          * Price type: one_time for single purchases, recurring for subscriptions
          */
@@ -147,13 +132,33 @@ export declare namespace ProductCreateResponse {
      */
     interface Media {
         /**
-         * Type of media: image, video, or external link
+         * CDN file ID
          */
-        type: 'image' | 'video' | 'external';
+        id: string;
         /**
-         * URL of the media resource
+         * Display order in gallery (0-indexed)
+         */
+        display_order: number;
+        /**
+         * Type of media: image or video
+         */
+        type: 'image' | 'video';
+        /**
+         * CDN URL of the media resource
          */
         url: string;
+        /**
+         * File size in bytes
+         */
+        file_size?: number;
+        /**
+         * Original filename
+         */
+        filename?: string;
+        /**
+         * Optimized thumbnail URL for images
+         */
+        thumbnail_url?: string;
     }
     /**
      * A resource that can be attached to products to grant access to customers.
@@ -173,25 +178,25 @@ export declare namespace ProductCreateResponse {
          */
         created: string;
         /**
-         * Type of resource: custom_entitlement, file, content, course, or ticket
+         * Type of resource
          */
-        type: 'custom_entitlement' | 'file' | 'content' | 'course' | 'ticket';
+        type: 'feature';
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         custom_entitlement?: Resource.CustomEntitlement | null;
     }
     namespace Resource {
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         interface CustomEntitlement {
             /**
-             * Unique identifier for the custom entitlement. Must not contain '.'
+             * The feature key that identifies what access is granted (e.g., 'pro_features')
              */
             id: string;
             /**
-             * Custom metadata for the entitlement
+             * Custom metadata for the feature grant
              */
             metadata?: {
                 [key: string]: unknown;
@@ -221,6 +226,11 @@ export interface ProductUpdateResponse {
      * Display name for the product (e.g., Pro, Business, Teams)
      */
     name: string;
+    /**
+     * ID of the subscription group this product belongs to. Subscription groups define
+     * shared billing configuration. All products must belong to a subscription group.
+     */
+    product_group_id: string;
     /**
      * Price configuration for a product. Can be one-time or recurring (subscription).
      */
@@ -239,11 +249,6 @@ export interface ProductUpdateResponse {
     metadata?: {
         [key: string]: unknown;
     };
-    /**
-     * ID of the product group this product belongs to. Product groups define shared
-     * billing configuration.
-     */
-    product_group_id?: string | null;
     /**
      * Resources attached to this product. Customers get access to these resources when
      * they purchase the product.
@@ -263,11 +268,6 @@ export declare namespace ProductUpdateResponse {
          * Unique identifier for the topic subscription
          */
         id: string;
-        /**
-         * How to handle the billing cycle when switching plans. 'now' resets to current
-         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
-         */
-        billing_cycle_anchor: 'now' | 'unchanged' | null;
         /**
          * Three-letter ISO currency code (e.g., usd, eur)
          */
@@ -282,16 +282,6 @@ export declare namespace ProductUpdateResponse {
          * prices.
          */
         interval_count: number | null;
-        /**
-         * How to handle prorations when switching plans. 'default' creates prorations,
-         * 'none' disables them. Null for one-time prices.
-         */
-        proration_behavior: 'default' | 'none' | null;
-        /**
-         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
-         * billing period start. Null for one-time prices or to use Stripe's default.
-         */
-        proration_date: 'now' | 'start_of_period' | null;
         /**
          * Price type: one_time for single purchases, recurring for subscriptions
          */
@@ -306,13 +296,33 @@ export declare namespace ProductUpdateResponse {
      */
     interface Media {
         /**
-         * Type of media: image, video, or external link
+         * CDN file ID
          */
-        type: 'image' | 'video' | 'external';
+        id: string;
+        /**
+         * Display order in gallery (0-indexed)
+         */
+        display_order: number;
+        /**
+         * Type of media: image or video
+         */
+        type: 'image' | 'video';
         /**
-         * URL of the media resource
+         * CDN URL of the media resource
          */
         url: string;
+        /**
+         * File size in bytes
+         */
+        file_size?: number;
+        /**
+         * Original filename
+         */
+        filename?: string;
+        /**
+         * Optimized thumbnail URL for images
+         */
+        thumbnail_url?: string;
     }
     /**
      * A resource that can be attached to products to grant access to customers.
@@ -332,25 +342,25 @@ export declare namespace ProductUpdateResponse {
          */
         created: string;
         /**
-         * Type of resource: custom_entitlement, file, content, course, or ticket
+         * Type of resource
          */
-        type: 'custom_entitlement' | 'file' | 'content' | 'course' | 'ticket';
+        type: 'feature';
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         custom_entitlement?: Resource.CustomEntitlement | null;
     }
     namespace Resource {
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         interface CustomEntitlement {
             /**
-             * Unique identifier for the custom entitlement. Must not contain '.'
+             * The feature key that identifies what access is granted (e.g., 'pro_features')
              */
             id: string;
             /**
-             * Custom metadata for the entitlement
+             * Custom metadata for the feature grant
              */
             metadata?: {
                 [key: string]: unknown;
@@ -380,6 +390,11 @@ export interface ProductListResponse {
      * Display name for the product (e.g., Pro, Business, Teams)
      */
     name: string;
+    /**
+     * ID of the subscription group this product belongs to. Subscription groups define
+     * shared billing configuration. All products must belong to a subscription group.
+     */
+    product_group_id: string;
     /**
      * Price configuration for a product. Can be one-time or recurring (subscription).
      */
@@ -398,11 +413,6 @@ export interface ProductListResponse {
     metadata?: {
         [key: string]: unknown;
     };
-    /**
-     * ID of the product group this product belongs to. Product groups define shared
-     * billing configuration.
-     */
-    product_group_id?: string | null;
     /**
      * Resources attached to this product. Customers get access to these resources when
      * they purchase the product.
@@ -422,11 +432,6 @@ export declare namespace ProductListResponse {
          * Unique identifier for the topic subscription
          */
         id: string;
-        /**
-         * How to handle the billing cycle when switching plans. 'now' resets to current
-         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
-         */
-        billing_cycle_anchor: 'now' | 'unchanged' | null;
         /**
          * Three-letter ISO currency code (e.g., usd, eur)
          */
@@ -441,16 +446,6 @@ export declare namespace ProductListResponse {
          * prices.
          */
         interval_count: number | null;
-        /**
-         * How to handle prorations when switching plans. 'default' creates prorations,
-         * 'none' disables them. Null for one-time prices.
-         */
-        proration_behavior: 'default' | 'none' | null;
-        /**
-         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
-         * billing period start. Null for one-time prices or to use Stripe's default.
-         */
-        proration_date: 'now' | 'start_of_period' | null;
         /**
          * Price type: one_time for single purchases, recurring for subscriptions
          */
@@ -465,13 +460,33 @@ export declare namespace ProductListResponse {
      */
     interface Media {
         /**
-         * Type of media: image, video, or external link
+         * CDN file ID
+         */
+        id: string;
+        /**
+         * Display order in gallery (0-indexed)
+         */
+        display_order: number;
+        /**
+         * Type of media: image or video
          */
-        type: 'image' | 'video' | 'external';
+        type: 'image' | 'video';
         /**
-         * URL of the media resource
+         * CDN URL of the media resource
          */
         url: string;
+        /**
+         * File size in bytes
+         */
+        file_size?: number;
+        /**
+         * Original filename
+         */
+        filename?: string;
+        /**
+         * Optimized thumbnail URL for images
+         */
+        thumbnail_url?: string;
     }
     /**
      * A resource that can be attached to products to grant access to customers.
@@ -491,25 +506,25 @@ export declare namespace ProductListResponse {
          */
         created: string;
         /**
-         * Type of resource: custom_entitlement, file, content, course, or ticket
+         * Type of resource
          */
-        type: 'custom_entitlement' | 'file' | 'content' | 'course' | 'ticket';
+        type: 'feature';
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         custom_entitlement?: Resource.CustomEntitlement | null;
     }
     namespace Resource {
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         interface CustomEntitlement {
             /**
-             * Unique identifier for the custom entitlement. Must not contain '.'
+             * The feature key that identifies what access is granted (e.g., 'pro_features')
              */
             id: string;
             /**
-             * Custom metadata for the entitlement
+             * Custom metadata for the feature grant
              */
             metadata?: {
                 [key: string]: unknown;
@@ -539,6 +554,11 @@ export interface ProductArchiveResponse {
      * Display name for the product (e.g., Pro, Business, Teams)
      */
     name: string;
+    /**
+     * ID of the subscription group this product belongs to. Subscription groups define
+     * shared billing configuration. All products must belong to a subscription group.
+     */
+    product_group_id: string;
     /**
      * Price configuration for a product. Can be one-time or recurring (subscription).
      */
@@ -557,11 +577,6 @@ export interface ProductArchiveResponse {
     metadata?: {
         [key: string]: unknown;
     };
-    /**
-     * ID of the product group this product belongs to. Product groups define shared
-     * billing configuration.
-     */
-    product_group_id?: string | null;
     /**
      * Resources attached to this product. Customers get access to these resources when
      * they purchase the product.
@@ -581,11 +596,6 @@ export declare namespace ProductArchiveResponse {
          * Unique identifier for the topic subscription
          */
         id: string;
-        /**
-         * How to handle the billing cycle when switching plans. 'now' resets to current
-         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
-         */
-        billing_cycle_anchor: 'now' | 'unchanged' | null;
         /**
          * Three-letter ISO currency code (e.g., usd, eur)
          */
@@ -600,16 +610,6 @@ export declare namespace ProductArchiveResponse {
          * prices.
          */
         interval_count: number | null;
-        /**
-         * How to handle prorations when switching plans. 'default' creates prorations,
-         * 'none' disables them. Null for one-time prices.
-         */
-        proration_behavior: 'default' | 'none' | null;
-        /**
-         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
-         * billing period start. Null for one-time prices or to use Stripe's default.
-         */
-        proration_date: 'now' | 'start_of_period' | null;
         /**
          * Price type: one_time for single purchases, recurring for subscriptions
          */
@@ -624,13 +624,33 @@ export declare namespace ProductArchiveResponse {
      */
     interface Media {
         /**
-         * Type of media: image, video, or external link
+         * CDN file ID
+         */
+        id: string;
+        /**
+         * Display order in gallery (0-indexed)
          */
-        type: 'image' | 'video' | 'external';
+        display_order: number;
         /**
-         * URL of the media resource
+         * Type of media: image or video
+         */
+        type: 'image' | 'video';
+        /**
+         * CDN URL of the media resource
          */
         url: string;
+        /**
+         * File size in bytes
+         */
+        file_size?: number;
+        /**
+         * Original filename
+         */
+        filename?: string;
+        /**
+         * Optimized thumbnail URL for images
+         */
+        thumbnail_url?: string;
     }
     /**
      * A resource that can be attached to products to grant access to customers.
@@ -650,25 +670,25 @@ export declare namespace ProductArchiveResponse {
          */
         created: string;
         /**
-         * Type of resource: custom_entitlement, file, content, course, or ticket
+         * Type of resource
          */
-        type: 'custom_entitlement' | 'file' | 'content' | 'course' | 'ticket';
+        type: 'feature';
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         custom_entitlement?: Resource.CustomEntitlement | null;
     }
     namespace Resource {
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         interface CustomEntitlement {
             /**
-             * Unique identifier for the custom entitlement. Must not contain '.'
+             * The feature key that identifies what access is granted (e.g., 'pro_features')
              */
             id: string;
             /**
-             * Custom metadata for the entitlement
+             * Custom metadata for the feature grant
              */
             metadata?: {
                 [key: string]: unknown;
@@ -698,6 +718,11 @@ export interface ProductGetResponse {
      * Display name for the product (e.g., Pro, Business, Teams)
      */
     name: string;
+    /**
+     * ID of the subscription group this product belongs to. Subscription groups define
+     * shared billing configuration. All products must belong to a subscription group.
+     */
+    product_group_id: string;
     /**
      * Price configuration for a product. Can be one-time or recurring (subscription).
      */
@@ -716,11 +741,6 @@ export interface ProductGetResponse {
     metadata?: {
         [key: string]: unknown;
     };
-    /**
-     * ID of the product group this product belongs to. Product groups define shared
-     * billing configuration.
-     */
-    product_group_id?: string | null;
     /**
      * Resources attached to this product. Customers get access to these resources when
      * they purchase the product.
@@ -740,11 +760,6 @@ export declare namespace ProductGetResponse {
          * Unique identifier for the topic subscription
          */
         id: string;
-        /**
-         * How to handle the billing cycle when switching plans. 'now' resets to current
-         * time, 'unchanged' keeps the original anchor. Null for one-time prices.
-         */
-        billing_cycle_anchor: 'now' | 'unchanged' | null;
         /**
          * Three-letter ISO currency code (e.g., usd, eur)
          */
@@ -759,16 +774,6 @@ export declare namespace ProductGetResponse {
          * prices.
          */
         interval_count: number | null;
-        /**
-         * How to handle prorations when switching plans. 'default' creates prorations,
-         * 'none' disables them. Null for one-time prices.
-         */
-        proration_behavior: 'default' | 'none' | null;
-        /**
-         * When to calculate proration. 'now' uses current time, 'start_of_period' uses the
-         * billing period start. Null for one-time prices or to use Stripe's default.
-         */
-        proration_date: 'now' | 'start_of_period' | null;
         /**
          * Price type: one_time for single purchases, recurring for subscriptions
          */
@@ -783,13 +788,33 @@ export declare namespace ProductGetResponse {
      */
     interface Media {
         /**
-         * Type of media: image, video, or external link
+         * CDN file ID
+         */
+        id: string;
+        /**
+         * Display order in gallery (0-indexed)
          */
-        type: 'image' | 'video' | 'external';
+        display_order: number;
         /**
-         * URL of the media resource
+         * Type of media: image or video
+         */
+        type: 'image' | 'video';
+        /**
+         * CDN URL of the media resource
          */
         url: string;
+        /**
+         * File size in bytes
+         */
+        file_size?: number;
+        /**
+         * Original filename
+         */
+        filename?: string;
+        /**
+         * Optimized thumbnail URL for images
+         */
+        thumbnail_url?: string;
     }
     /**
      * A resource that can be attached to products to grant access to customers.
@@ -809,25 +834,25 @@ export declare namespace ProductGetResponse {
          */
         created: string;
         /**
-         * Type of resource: custom_entitlement, file, content, course, or ticket
+         * Type of resource
          */
-        type: 'custom_entitlement' | 'file' | 'content' | 'course' | 'ticket';
+        type: 'feature';
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         custom_entitlement?: Resource.CustomEntitlement | null;
     }
     namespace Resource {
         /**
-         * Custom entitlement data. Required when type is 'custom_entitlement'.
+         * Feature grant data. Required when type is 'feature'.
          */
         interface CustomEntitlement {
             /**
-             * Unique identifier for the custom entitlement. Must not contain '.'
+             * The feature key that identifies what access is granted (e.g., 'pro_features')
              */
             id: string;
             /**
-             * Custom metadata for the entitlement
+             * Custom metadata for the feature grant
              */
             metadata?: {
                 [key: string]: unknown;
@@ -841,34 +866,21 @@ export interface ProductCreateParams {
      */
     name: string;
     /**
-     * Price amount in the smallest currency unit (e.g., cents). Use 0 for free
-     * products.
+     * Variants to create with the product. Each variant has its own pricing. At least
+     * one variant is required.
      */
-    unit_amount: number;
+    variants: Array<ProductCreateParams.Variant>;
     /**
-     * Optional custom ID for the product. If not provided, one will be generated.
+     * Optional custom ID for the product. Must start with 'prod\_'. If not provided,
+     * one will be generated.
      */
     id?: string;
-    /**
-     * Three-letter ISO currency code
-     */
-    currency?: string;
     /**
      * Detailed description of what the product includes
      */
     description?: string;
     /**
-     * Billing frequency for recurring prices: day, week, month, or year. Required for
-     * recurring type, ignored for one_time.
-     */
-    interval?: 'day' | 'week' | 'month' | 'year';
-    /**
-     * Number of intervals between billings for recurring prices. Required for
-     * recurring type, ignored for one_time.
-     */
-    interval_count?: number;
-    /**
-     * Media attachments (images, videos) for the product
+     * Media attachments by CDN file ID
      */
     media?: Array<ProductCreateParams.Media>;
     /**
@@ -878,32 +890,107 @@ export interface ProductCreateParams {
         [key: string]: unknown;
     };
     /**
-     * ID of the product group this product belongs to. Product groups define shared
-     * billing configuration.
+     * ID of the subscription group this product belongs to. Subscription groups define
+     * shared billing configuration.
      */
     product_group_id?: string;
     /**
      * Tags for categorizing and filtering products
      */
     tags?: Array<string>;
-    /**
-     * Price type: one_time for single purchases, recurring for subscriptions
-     */
-    type?: 'one_time' | 'recurring';
 }
 export declare namespace ProductCreateParams {
     /**
-     * Media attachment for products or variants
+     * Variant configuration for inline creation with a product
+     */
+    interface Variant {
+        /**
+         * Display name for the variant
+         */
+        name: string;
+        /**
+         * Optional custom ID for the variant. Must start with 'var\_'.
+         */
+        id?: string;
+        /**
+         * Three-letter ISO currency code
+         */
+        currency?: string;
+        /**
+         * Detailed description of what this variant includes
+         */
+        description?: string;
+        /**
+         * Mark as the default variant for checkout. Only one variant can be default.
+         */
+        is_default?: boolean;
+        /**
+         * Media attachments by CDN file ID
+         */
+        media?: Array<Variant.Media>;
+        /**
+         * Custom metadata for the variant
+         */
+        metadata?: {
+            [key: string]: unknown;
+        };
+        /**
+         * Recurring billing configuration for subscription variants
+         */
+        recurring?: Variant.Recurring;
+        /**
+         * Price amount in smallest currency unit (e.g., cents)
+         */
+        unit_amount?: number;
+    }
+    namespace Variant {
+        /**
+         * Media input for attaching to products or variants
+         */
+        interface Media {
+            /**
+             * CDN file ID from upload
+             */
+            cdn_file_id: string;
+            /**
+             * Type of media: image or video
+             */
+            type: 'image' | 'video';
+            /**
+             * Display order in gallery (0-indexed)
+             */
+            display_order?: number;
+        }
+        /**
+         * Recurring billing configuration for subscription variants
+         */
+        interface Recurring {
+            /**
+             * Billing frequency: day, week, month, or year
+             */
+            interval: 'day' | 'week' | 'month' | 'year';
+            /**
+             * Number of intervals between billings
+             */
+            interval_count?: number;
+        }
+    }
+    /**
+     * Media input for attaching to products or variants
      */
     interface Media {
         /**
-         * Type of media: image, video, or external link
+         * CDN file ID from upload
          */
-        type: 'image' | 'video' | 'external';
+        cdn_file_id: string;
         /**
-         * URL of the media resource
+         * Type of media: image or video
          */
-        url: string;
+        type: 'image' | 'video';
+        /**
+         * Display order in gallery (0-indexed)
+         */
+        display_order?: number;
     }
 }
 export interface ProductUpdateParams {
@@ -916,7 +1003,7 @@ export interface ProductUpdateParams {
      */
     description?: string;
     /**
-     * Media attachments (images, videos) for the product
+     * Replace all media attachments. Pass empty array to remove all media.
      */
     media?: Array<ProductUpdateParams.Media>;
     /**
@@ -930,9 +1017,10 @@ export interface ProductUpdateParams {
      */
     name?: string;
     /**
-     * ID of the product group. Set to null to remove from a group.
+     * ID of the subscription group to move this product to. All products must belong
+     * to a subscription group.
      */
-    product_group_id?: string | null;
+    product_group_id?: string;
     /**
      * Tags for categorizing and filtering products
      */
@@ -940,17 +1028,21 @@ export interface ProductUpdateParams {
 }
 export declare namespace ProductUpdateParams {
     /**
-     * Media attachment for products or variants
+     * Media input for attaching to products or variants
      */
     interface Media {
         /**
-         * Type of media: image, video, or external link
+         * CDN file ID from upload
          */
-        type: 'image' | 'video' | 'external';
+        cdn_file_id: string;
         /**
-         * URL of the media resource
+         * Type of media: image or video
          */
-        url: string;
+        type: 'image' | 'video';
+        /**
+         * Display order in gallery (0-indexed)
+         */
+        display_order?: number;
     }
 }
 export interface ProductListParams extends CursorIDPageParams {