@usehercules/sdk 1.10.1 → 1.12.0

package/src/resources/commerce/products/resources.ts

@@ -0,0 +1,226 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Resources extends APIResource {
+  /**
+   * Retrieves all resources attached to a product. Resources define the entitlements
+   * customers gain access to when purchasing this product.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const resourceListResponse of client.commerce.products.resources.list(
+   *   'product_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    productID: string,
+    query: ResourceListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ResourceListResponsesCursorIDPage, ResourceListResponse> {
+    return this._client.getAPIList(
+      path`/v1/commerce/products/${productID}/resources`,
+      CursorIDPage<ResourceListResponse>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Attaches one or more resources to a product. Customers who purchase this product
+   * will gain access to the attached resources. Resource type is inferred from the
+   * ID prefix (e.g., 'feat\_' for features).
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.commerce.products.resources.attach(
+   *     'product_id',
+   *     { resource_ids: ['string'] },
+   *   );
+   * ```
+   */
+  attach(
+    productID: string,
+    body: ResourceAttachParams,
+    options?: RequestOptions,
+  ): APIPromise<ResourceAttachResponse> {
+    return this._client.post(path`/v1/commerce/products/${productID}/resources`, { body, ...options });
+  }
+
+  /**
+   * Detaches one or more resources from a product. Customers will lose access to
+   * these resources when they purchase this product.
+   *
+   * @example
+   * ```ts
+   * await client.commerce.products.resources.detach(
+   *   'product_id',
+   *   { resource_ids: ['string'] },
+   * );
+   * ```
+   */
+  detach(productID: string, body: ResourceDetachParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/commerce/products/${productID}/resources`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type ResourceListResponsesCursorIDPage = CursorIDPage<ResourceListResponse>;
+
+/**
+ * A resource that can be attached to products to grant access to customers.
+ * Resources represent monetizable content or features in your app.
+ */
+export interface ResourceListResponse {
+  /**
+   * Unique identifier for the resource
+   */
+  id: string;
+
+  /**
+   * Whether the resource is active and grants access
+   */
+  active: boolean;
+
+  /**
+   * Timestamp when the resource was created
+   */
+  created: string;
+
+  /**
+   * Type of resource
+   */
+  type: 'feature';
+
+  /**
+   * Feature grant that provides access to features or functionality in your app
+   */
+  feature?: ResourceListResponse.Feature | null;
+}
+
+export namespace ResourceListResponse {
+  /**
+   * Feature grant that provides access to features or functionality in your app
+   */
+  export interface Feature {
+    /**
+     * The feature key that identifies what access is granted (e.g., 'pro_features')
+     */
+    id: string;
+
+    /**
+     * Custom metadata for the feature grant
+     */
+    metadata?: { [key: string]: unknown };
+  }
+}
+
+/**
+ * Response containing attached resources
+ */
+export interface ResourceAttachResponse {
+  /**
+   * Array of attached resource objects
+   */
+  data: Array<ResourceAttachResponse.Data>;
+}
+
+export namespace ResourceAttachResponse {
+  /**
+   * A resource that can be attached to products to grant access to customers.
+   * Resources represent monetizable content or features in your app.
+   */
+  export interface Data {
+    /**
+     * Unique identifier for the resource
+     */
+    id: string;
+
+    /**
+     * Whether the resource is active and grants access
+     */
+    active: boolean;
+
+    /**
+     * Timestamp when the resource was created
+     */
+    created: string;
+
+    /**
+     * Type of resource
+     */
+    type: 'feature';
+
+    /**
+     * Feature grant that provides access to features or functionality in your app
+     */
+    feature?: Data.Feature | null;
+  }
+
+  export namespace Data {
+    /**
+     * Feature grant that provides access to features or functionality in your app
+     */
+    export interface Feature {
+      /**
+       * The feature key that identifies what access is granted (e.g., 'pro_features')
+       */
+      id: string;
+
+      /**
+       * Custom metadata for the feature grant
+       */
+      metadata?: { [key: string]: unknown };
+    }
+  }
+}
+
+export interface ResourceListParams extends CursorIDPageParams {
+  /**
+   * Filter by active status
+   */
+  active?: boolean;
+
+  /**
+   * Filter by resource type
+   */
+  type?: 'feature';
+}
+
+export interface ResourceAttachParams {
+  /**
+   * Resource IDs to attach. Type is inferred from ID prefix (e.g., 'feat\_' for
+   * features).
+   */
+  resource_ids: Array<string>;
+}
+
+export interface ResourceDetachParams {
+  /**
+   * Resource IDs to detach from the product.
+   */
+  resource_ids: Array<string>;
+}
+
+export declare namespace Resources {
+  export {
+    type ResourceListResponse as ResourceListResponse,
+    type ResourceAttachResponse as ResourceAttachResponse,
+    type ResourceListResponsesCursorIDPage as ResourceListResponsesCursorIDPage,
+    type ResourceListParams as ResourceListParams,
+    type ResourceAttachParams as ResourceAttachParams,
+    type ResourceDetachParams as ResourceDetachParams,
+  };
+}

package/src/resources/commerce/products/variants.ts

@@ -0,0 +1,366 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../../core/pagination';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Variants extends APIResource {
+  /**
+   * Creates a new variant with pricing for a product. Use variants to offer multiple
+   * pricing tiers or configurations (e.g., Basic at $10/month, Pro at $25/month). A
+   * Stripe Price is automatically created.
+   *
+   * @example
+   * ```ts
+   * const variant =
+   *   await client.commerce.products.variants.create(
+   *     'product_id',
+   *     { name: 'name' },
+   *   );
+   * ```
+   */
+  create(productID: string, body: VariantCreateParams, options?: RequestOptions): APIPromise<Variant> {
+    return this._client.post(path`/v1/commerce/products/${productID}/variants`, { body, ...options });
+  }
+
+  /**
+   * Updates an existing variant. Use this to modify the name, description, or active
+   * status. Pricing cannot be changed after creation—create a new variant instead.
+   *
+   * @example
+   * ```ts
+   * const variant =
+   *   await client.commerce.products.variants.update(
+   *     'variant_id',
+   *     { product_id: 'product_id' },
+   *   );
+   * ```
+   */
+  update(variantID: string, params: VariantUpdateParams, options?: RequestOptions): APIPromise<Variant> {
+    const { product_id, ...body } = params;
+    return this._client.patch(path`/v1/commerce/products/${product_id}/variants/${variantID}`, {
+      body,
+      ...options,
+    });
+  }
+
+  /**
+   * Retrieves all variants for a product. Variants represent different pricing tiers
+   * or configurations (e.g., Basic, Pro, Enterprise) within a single product.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const variant of client.commerce.products.variants.list(
+   *   'product_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    productID: string,
+    query: VariantListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<VariantsCursorIDPage, Variant> {
+    return this._client.getAPIList(path`/v1/commerce/products/${productID}/variants`, CursorIDPage<Variant>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Retrieves a variant by ID. Returns the variant object including pricing details
+   * and status.
+   *
+   * @example
+   * ```ts
+   * const variant = await client.commerce.products.variants.get(
+   *   'variant_id',
+   *   { product_id: 'product_id' },
+   * );
+   * ```
+   */
+  get(variantID: string, params: VariantGetParams, options?: RequestOptions): APIPromise<Variant> {
+    const { product_id } = params;
+    return this._client.get(path`/v1/commerce/products/${product_id}/variants/${variantID}`, options);
+  }
+}
+
+export type VariantsCursorIDPage = CursorIDPage<Variant>;
+
+/**
+ * A product variant representing a specific tier or configuration. Each variant
+ * has its own pricing. Variants allow a single product to have multiple pricing
+ * options (e.g., Basic, Pro, Enterprise tiers).
+ */
+export interface Variant {
+  /**
+   * Unique identifier for the variant
+   */
+  id: string;
+
+  /**
+   * Whether the variant is available for new purchases
+   */
+  active: boolean;
+
+  /**
+   * Timestamp when the variant was created
+   */
+  created: string;
+
+  /**
+   * Display name for the variant (e.g., Basic, Standard, Premium)
+   */
+  name: string;
+
+  /**
+   * Three-letter ISO currency code
+   */
+  currency?: string;
+
+  /**
+   * Detailed description of what this variant includes
+   */
+  description?: string | null;
+
+  /**
+   * Media attachments (images, videos) for the variant
+   */
+  media?: Array<Variant.Media>;
+
+  /**
+   * Custom metadata for the variant
+   */
+  metadata?: { [key: string]: unknown };
+
+  /**
+   * Recurring billing configuration for subscription variants
+   */
+  recurring?: Variant.Recurring | null;
+
+  /**
+   * Price amount in the smallest currency unit (e.g., cents). 0 for free variants.
+   */
+  unit_amount?: number;
+}
+
+export namespace Variant {
+  /**
+   * Media attachment for products or variants
+   */
+  export interface Media {
+    /**
+     * CDN file ID
+     */
+    id: string;
+
+    /**
+     * 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;
+  }
+
+  /**
+   * Recurring billing configuration for subscription variants
+   */
+  export interface Recurring {
+    /**
+     * Billing frequency: day, week, month, or year
+     */
+    interval: 'day' | 'week' | 'month' | 'year';
+
+    /**
+     * Number of intervals between billings
+     */
+    interval_count?: number;
+  }
+}
+
+export interface VariantCreateParams {
+  /**
+   * Display name for the variant (e.g., Basic, Standard, Premium)
+   */
+  name: string;
+
+  /**
+   * Optional custom ID for the variant. Must start with 'var\_'. If not provided,
+   * one will be generated.
+   */
+  id?: string;
+
+  /**
+   * Three-letter ISO currency code
+   */
+  currency?: string;
+
+  /**
+   * Detailed description of what this variant includes
+   */
+  description?: string;
+
+  /**
+   * Media attachments by CDN file ID
+   */
+  media?: Array<VariantCreateParams.Media>;
+
+  /**
+   * Custom metadata for the variant
+   */
+  metadata?: { [key: string]: unknown };
+
+  /**
+   * Recurring billing configuration for subscription variants
+   */
+  recurring?: VariantCreateParams.Recurring;
+
+  /**
+   * Price amount in the smallest currency unit (e.g., cents). Use 0 for free
+   * variants.
+   */
+  unit_amount?: number;
+}
+
+export namespace VariantCreateParams {
+  /**
+   * Media input for attaching to products or variants
+   */
+  export 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
+   */
+  export interface Recurring {
+    /**
+     * Billing frequency: day, week, month, or year
+     */
+    interval: 'day' | 'week' | 'month' | 'year';
+
+    /**
+     * Number of intervals between billings
+     */
+    interval_count?: number;
+  }
+}
+
+export interface VariantUpdateParams {
+  /**
+   * Path param: The unique identifier of the product
+   */
+  product_id: string;
+
+  /**
+   * Body param: Whether the variant is available for new purchases
+   */
+  active?: boolean;
+
+  /**
+   * Body param: Detailed description of what this variant includes
+   */
+  description?: string;
+
+  /**
+   * Body param: Replace all media attachments. Pass empty array to remove all media.
+   */
+  media?: Array<VariantUpdateParams.Media>;
+
+  /**
+   * Body param: Custom metadata for the variant
+   */
+  metadata?: { [key: string]: unknown };
+
+  /**
+   * Body param: Display name for the variant
+   */
+  name?: string;
+}
+
+export namespace VariantUpdateParams {
+  /**
+   * Media input for attaching to products or variants
+   */
+  export 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;
+  }
+}
+
+export interface VariantListParams extends CursorIDPageParams {
+  /**
+   * Filter by active status
+   */
+  active?: boolean;
+}
+
+export interface VariantGetParams {
+  /**
+   * The unique identifier of the product
+   */
+  product_id: string;
+}
+
+export declare namespace Variants {
+  export {
+    type Variant as Variant,
+    type VariantsCursorIDPage as VariantsCursorIDPage,
+    type VariantCreateParams as VariantCreateParams,
+    type VariantUpdateParams as VariantUpdateParams,
+    type VariantListParams as VariantListParams,
+    type VariantGetParams as VariantGetParams,
+  };
+}

package/src/resources/commerce/subscription-groups.ts

@@ -0,0 +1,5 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+
+export class SubscriptionGroups extends APIResource {}

package/src/resources/{beta/content → content}/assets.ts

@@ -1,11 +1,11 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../core/resource';
-import { APIPromise } from '../../../core/api-promise';
-import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../../core/pagination';
-import { buildHeaders } from '../../../internal/headers';
-import { RequestOptions } from '../../../internal/request-options';
-import { path } from '../../../internal/utils/path';
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
 
 export class Assets extends APIResource {
   /**
@@ -74,7 +74,7 @@ export type AssetsCursorIDPage = CursorIDPage<Asset>;
  */
 export interface Asset {
   /**
-   * Unique identifier for the topic subscription
+   * Unique identifier for the asset
    */
   id: string;
 

package/src/resources/{beta/content → content}/content.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../core/resource';
+import { APIResource } from '../../core/resource';
 import * as AssetsAPI from './assets';
 import {
   Asset,
@@ -51,6 +51,9 @@ import {
   ReleasesCursorIDPage,
 } from './releases/releases';
 
+/**
+ * Content APIs are currently in beta.
+ */
 export class Content extends APIResource {
   models: ModelsAPI.Models = new ModelsAPI.Models(this._client);
   entries: EntriesAPI.Entries = new EntriesAPI.Entries(this._client);

package/src/resources/{beta/content → content}/entries.ts

@@ -1,10 +1,10 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../core/resource';
-import { APIPromise } from '../../../core/api-promise';
-import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../../core/pagination';
-import { RequestOptions } from '../../../internal/request-options';
-import { path } from '../../../internal/utils/path';
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
 
 export class Entries extends APIResource {
   /**
@@ -86,7 +86,7 @@ export type EntriesCursorIDPage = CursorIDPage<Entry>;
  */
 export interface Entry {
   /**
-   * Unique identifier for the topic subscription
+   * Unique identifier for the entry
    */
   id: string;
 

package/src/resources/{beta/content → content}/locales.ts

@@ -1,11 +1,11 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../core/resource';
-import { APIPromise } from '../../../core/api-promise';
-import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../../core/pagination';
-import { buildHeaders } from '../../../internal/headers';
-import { RequestOptions } from '../../../internal/request-options';
-import { path } from '../../../internal/utils/path';
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
 
 export class Locales extends APIResource {
   /**
@@ -66,7 +66,7 @@ export type LocalesCursorIDPage = CursorIDPage<Locale>;
  */
 export interface Locale {
   /**
-   * Unique identifier for the topic subscription
+   * Unique identifier for the locale
    */
   id: string;
 
@@ -155,7 +155,7 @@ export interface LocaleListParams extends CursorIDPageParams {
   /**
    * Filter by active status
    */
-  active?: 'true' | 'false';
+  active?: boolean;
 }
 
 export declare namespace Locales {