@usehercules/sdk 1.3.0 → 1.5.0

package/src/resources/beta/pay/pay.ts

@@ -108,34 +108,76 @@ export interface PayCancelResponse {
  */
 export interface PayCheckResponse {
   /**
-   * Whether the customer has the entitlement
-   */
-  has_entitlement: boolean;
-
-  /**
-   * The entitlement key that was checked
+   * The entitlement ID that was checked
    */
-  key: string;
+  entitlement_id: string;
 
   /**
-   * The active entitlement ID if present
+   * Whether the customer has the entitlement
    */
-  entitlement_id?: string | null;
+  has_entitlement: boolean;
 }
 
 /**
- * Checkout session response
+ * Checkout response. For new customers, returns a checkout URL. For existing
+ * subscribers, returns the updated subscription.
  */
 export interface PayCheckoutResponse {
   /**
-   * The checkout session ID
+   * The checkout session ID (for checkout action) or subscription ID (for update
+   * action)
    */
   id: string;
 
   /**
-   * The checkout URL to redirect the customer to
+   * The action taken: 'checkout' for new subscriptions (redirect to URL), 'update'
+   * for subscription changes (already applied)
+   */
+  action: 'checkout' | 'update';
+
+  /**
+   * The checkout mode: subscription for recurring prices, payment for one-time
+   * prices. Only present for 'checkout' action.
+   */
+  mode?: 'subscription' | 'payment' | null;
+
+  /**
+   * The updated subscription details. Only present for 'update' action.
+   */
+  subscription?: PayCheckoutResponse.Subscription | null;
+
+  /**
+   * The checkout URL to redirect the customer to. Only present for 'checkout'
+   * action.
+   */
+  url?: string | null;
+}
+
+export namespace PayCheckoutResponse {
+  /**
+   * The updated subscription details. Only present for 'update' action.
    */
-  url: string;
+  export interface Subscription {
+    /**
+     * The subscription ID
+     */
+    id: string;
+
+    /**
+     * The product ID
+     */
+    product_id: string;
+
+    /**
+     * The subscription status
+     */
+    status: string;
+
+    /**
+     * The variant ID if applicable
+     */
+    variant_id?: string | null;
+  }
 }
 
 export interface PayCancelParams {
@@ -163,9 +205,9 @@ export interface PayCheckParams {
   customer_id: string;
 
   /**
-   * The entitlement key to check for access
+   * The entitlement ID to check for access
    */
-  entitlement_key: string;
+  entitlement_id: string;
 }
 
 export interface PayCheckoutParams {
@@ -175,15 +217,23 @@ export interface PayCheckoutParams {
   customer_id: string;
 
   /**
-   * The product ID to subscribe to
+   * The product ID to purchase
    */
   product_id: string;
 
   /**
-   * Optional custom ID for the subscription. If not provided, one will be generated.
+   * Optional custom ID for the subscription or payment. If not provided, one will be
+   * generated.
    */
   id?: string;
 
+  /**
+   * Override billing cycle anchor behavior for subscription updates. 'now' resets to
+   * current time, 'unchanged' keeps original anchor. If not provided, uses the
+   * price's configured default.
+   */
+  billing_cycle_anchor?: 'now' | 'unchanged';
+
   /**
    * URL to redirect on cancel
    */
@@ -194,10 +244,30 @@ export interface PayCheckoutParams {
    */
   promotion_code?: string;
 
+  /**
+   * Override proration behavior for subscription updates. 'default' creates
+   * prorations, 'none' disables them. If not provided, uses the price's configured
+   * default.
+   */
+  proration_behavior?: 'default' | 'none';
+
+  /**
+   * Override proration date calculation for subscription updates. 'now' uses current
+   * time, 'start_of_period' uses billing period start. If not provided, uses the
+   * price's configured default.
+   */
+  proration_date?: 'now' | 'start_of_period';
+
   /**
    * URL to redirect on success
    */
   success_url?: string;
+
+  /**
+   * Optional variant ID to specify a particular pricing tier. If not provided, the
+   * product's default price is used.
+   */
+  variant_id?: string;
 }
 
 Pay.Customers = Customers;

package/src/resources/beta/pay/products/entitlements.ts

@@ -59,7 +59,7 @@ export type ProductEntitlementsCursorIDPage = CursorIDPage<ProductEntitlement>;
  */
 export interface ProductEntitlement {
   /**
-   * Unique identifier for the entitlement
+   * Unique identifier for the price
    */
   id: string;
 

package/src/resources/beta/pay/products/index.ts

@@ -16,3 +16,13 @@ export {
   type ProductListParams,
   type ProductsCursorIDPage,
 } from './products';
+export {
+  Variants,
+  type Variant,
+  type VariantCreateParams,
+  type VariantUpdateParams,
+  type VariantListParams,
+  type VariantArchiveParams,
+  type VariantGetParams,
+  type VariantsCursorIDPage,
+} from './variants';

package/src/resources/beta/pay/products/products.ts

@@ -10,6 +10,17 @@ import {
   ProductEntitlement,
   ProductEntitlementsCursorIDPage,
 } from './entitlements';
+import * as VariantsAPI from './variants';
+import {
+  Variant,
+  VariantArchiveParams,
+  VariantCreateParams,
+  VariantGetParams,
+  VariantListParams,
+  VariantUpdateParams,
+  Variants,
+  VariantsCursorIDPage,
+} from './variants';
 import { APIPromise } from '../../../../core/api-promise';
 import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../../../core/pagination';
 import { RequestOptions } from '../../../../internal/request-options';
@@ -17,6 +28,7 @@ import { path } from '../../../../internal/utils/path';
 
 export class Products extends APIResource {
   entitlements: EntitlementsAPI.Entitlements = new EntitlementsAPI.Entitlements(this._client);
+  variants: VariantsAPI.Variants = new VariantsAPI.Variants(this._client);
 
   /**
    * Creates a new subscription product with a recurring price. Common examples
@@ -72,18 +84,18 @@ export class Products extends APIResource {
 export type ProductsCursorIDPage = CursorIDPage<Product>;
 
 /**
- * A subscription product that customers can subscribe to. Products define pricing
- * and billing intervals. Attach entitlements to a product to grant features to all
- * subscribed customers.
+ * A product that customers can purchase. Products can be one-time purchases or
+ * recurring subscriptions. Attach entitlements to a product to grant features to
+ * customers.
  */
 export interface Product {
   /**
-   * Unique identifier for the entitlement
+   * Unique identifier for the price
    */
   id: string;
 
   /**
-   * Whether the product is available for new subscriptions
+   * Whether the product is available for new purchases
    */
   active: boolean;
 
@@ -98,7 +110,7 @@ export interface Product {
   name: string;
 
   /**
-   * The recurring price configuration for a product
+   * Price configuration for a product. Can be one-time or recurring (subscription).
    */
   default_price?: Product.DefaultPrice | null;
 
@@ -110,28 +122,53 @@ export interface Product {
 
 export namespace Product {
   /**
-   * The recurring price configuration for a product
+   * Price configuration for a product. Can be one-time or recurring (subscription).
    */
   export interface DefaultPrice {
     /**
-     * Unique identifier for the entitlement
+     * Unique identifier for the price
      */
     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)
      */
     currency: string;
 
     /**
-     * Billing frequency: day, week, month, or year
+     * Billing frequency for recurring prices: day, week, month, or year. Null for
+     * one-time prices.
+     */
+    interval: 'day' | 'week' | 'month' | 'year' | null;
+
+    /**
+     * Number of intervals between billings for recurring prices. Null for one-time
+     * prices.
+     */
+    interval_count: number | null;
+
+    /**
+     * How to handle prorations when switching plans. 'default' creates prorations,
+     * 'none' disables them. Null for one-time prices.
      */
-    interval: 'day' | 'week' | 'month' | 'year';
+    proration_behavior: 'default' | 'none' | null;
 
     /**
-     * Number of intervals between billings (e.g., 2 for biweekly)
+     * 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.
      */
-    interval_count: number;
+    proration_date: 'now' | 'start_of_period' | null;
+
+    /**
+     * Price type: one_time for single purchases, recurring for subscriptions
+     */
+    type: 'one_time' | 'recurring';
 
     /**
      * Price amount in the smallest currency unit (e.g., cents)
@@ -168,14 +205,21 @@ export interface ProductCreateParams {
   description?: string;
 
   /**
-   * Billing frequency: day, week, month, or year
+   * 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
+   * Number of intervals between billings for recurring prices. Required for
+   * recurring type, ignored for one_time.
    */
   interval_count?: number;
+
+  /**
+   * Price type: one_time for single purchases, recurring for subscriptions
+   */
+  type?: 'one_time' | 'recurring';
 }
 
 export interface ProductUpdateParams {
@@ -203,6 +247,7 @@ export interface ProductListParams extends CursorIDPageParams {
 }
 
 Products.Entitlements = Entitlements;
+Products.Variants = Variants;
 
 export declare namespace Products {
   export {
@@ -221,4 +266,15 @@ export declare namespace Products {
     type EntitlementAttachParams as EntitlementAttachParams,
     type EntitlementRemoveParams as EntitlementRemoveParams,
   };
+
+  export {
+    Variants as Variants,
+    type Variant as Variant,
+    type VariantsCursorIDPage as VariantsCursorIDPage,
+    type VariantCreateParams as VariantCreateParams,
+    type VariantUpdateParams as VariantUpdateParams,
+    type VariantListParams as VariantListParams,
+    type VariantArchiveParams as VariantArchiveParams,
+    type VariantGetParams as VariantGetParams,
+  };
 }

package/src/resources/beta/pay/products/variants.ts

@@ -0,0 +1,279 @@
+// 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.
+   */
+  create(productID: string, body: VariantCreateParams, options?: RequestOptions): APIPromise<Variant> {
+    return this._client.post(path`/v1/pay/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.
+   */
+  update(variantID: string, params: VariantUpdateParams, options?: RequestOptions): APIPromise<Variant> {
+    const { product_id, ...body } = params;
+    return this._client.patch(path`/v1/pay/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.
+   */
+  list(
+    productID: string,
+    query: VariantListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<VariantsCursorIDPage, Variant> {
+    return this._client.getAPIList(path`/v1/pay/products/${productID}/variants`, CursorIDPage<Variant>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Archives a variant, preventing new subscriptions. The associated Stripe Price is
+   * also archived. Existing subscriptions remain active.
+   */
+  archive(variantID: string, params: VariantArchiveParams, options?: RequestOptions): APIPromise<Variant> {
+    const { product_id } = params;
+    return this._client.delete(path`/v1/pay/products/${product_id}/variants/${variantID}`, options);
+  }
+
+  /**
+   * Retrieves a variant by ID. Returns the variant object including pricing details
+   * and status.
+   */
+  get(variantID: string, params: VariantGetParams, options?: RequestOptions): APIPromise<Variant> {
+    const { product_id } = params;
+    return this._client.get(path`/v1/pay/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 price
+   */
+  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;
+
+  /**
+   * Price configuration for a product. Can be one-time or recurring (subscription).
+   */
+  default_price?: Variant.DefaultPrice | null;
+
+  /**
+   * Detailed description of what this variant includes
+   */
+  description?: string | null;
+}
+
+export namespace Variant {
+  /**
+   * Price configuration for a product. Can be one-time or recurring (subscription).
+   */
+  export interface DefaultPrice {
+    /**
+     * Unique identifier for the price
+     */
+    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)
+     */
+    currency: string;
+
+    /**
+     * Billing frequency for recurring prices: day, week, month, or year. Null for
+     * one-time prices.
+     */
+    interval: 'day' | 'week' | 'month' | 'year' | null;
+
+    /**
+     * Number of intervals between billings for recurring prices. Null for one-time
+     * 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
+     */
+    type: 'one_time' | 'recurring';
+
+    /**
+     * Price amount in the smallest currency unit (e.g., cents)
+     */
+    unit_amount: number | null;
+  }
+}
+
+export interface VariantCreateParams {
+  /**
+   * Display name for the variant (e.g., Basic, Standard, Premium)
+   */
+  name: string;
+
+  /**
+   * Price amount in the smallest currency unit (e.g., cents). Use 0 for free
+   * variants.
+   */
+  unit_amount: number;
+
+  /**
+   * Optional custom ID for the variant. If not provided, one will be generated.
+   */
+  id?: string;
+
+  /**
+   * Default billing cycle anchor behavior when switching to this price. 'now' resets
+   * to current time, 'unchanged' keeps original anchor. Only applies to recurring
+   * prices.
+   */
+  billing_cycle_anchor?: 'now' | 'unchanged';
+
+  /**
+   * Three-letter ISO currency code
+   */
+  currency?: string;
+
+  /**
+   * Detailed description of what this variant 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;
+
+  /**
+   * Default proration behavior when switching to this price. 'default' creates
+   * prorations, 'none' disables them. Only applies to recurring prices.
+   */
+  proration_behavior?: 'default' | 'none';
+
+  /**
+   * Default proration date calculation when switching to this price. 'now' uses
+   * current time, 'start_of_period' uses billing period start. Only applies to
+   * recurring prices.
+   */
+  proration_date?: 'now' | 'start_of_period';
+
+  /**
+   * Price type: one_time for single purchases, recurring for subscriptions
+   */
+  type?: 'one_time' | 'recurring';
+}
+
+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: Display name for the variant
+   */
+  name?: string;
+}
+
+export interface VariantListParams extends CursorIDPageParams {
+  /**
+   * Filter by active status
+   */
+  active?: 'true' | 'false';
+}
+
+export interface VariantArchiveParams {
+  /**
+   * The unique identifier of the product
+   */
+  product_id: string;
+}
+
+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 VariantArchiveParams as VariantArchiveParams,
+    type VariantGetParams as VariantGetParams,
+  };
+}

package/src/resources/beta/push-notifications/index.ts

@@ -0,0 +1,14 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  PushNotifications,
+  type PushNotificationEnableResponse,
+  type PushNotificationSendResponse,
+  type PushNotificationSendParams,
+} from './push-notifications';
+export {
+  Subscriptions,
+  type SubscriptionCreateResponse,
+  type SubscriptionDeleteResponse,
+  type SubscriptionCreateParams,
+} from './subscriptions';