@usehercules/sdk 1.2.0 → 1.4.0

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

@@ -0,0 +1,326 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as CouponsAPI from './coupons';
+import {
+  Coupon,
+  CouponCreateParams,
+  CouponListParams,
+  CouponUpdateParams,
+  Coupons,
+  CouponsCursorIDPage,
+} from './coupons';
+import * as CustomersAPI from './customers';
+import {
+  Customer,
+  CustomerAddress,
+  CustomerBillingPortalParams,
+  CustomerBillingPortalResponse,
+  CustomerCreateParams,
+  CustomerListParams,
+  CustomerUpdateParams,
+  Customers,
+  CustomersCursorIDPage,
+} from './customers';
+import * as EntitlementsAPI from './entitlements';
+import {
+  Entitlement,
+  EntitlementCreateParams,
+  EntitlementListParams,
+  EntitlementUpdateParams,
+  Entitlements,
+  EntitlementsCursorIDPage,
+} from './entitlements';
+import * as ProductsAPI from './products/products';
+import {
+  Product,
+  ProductCreateParams,
+  ProductListParams,
+  ProductUpdateParams,
+  Products,
+  ProductsCursorIDPage,
+} from './products/products';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+
+export class Pay extends APIResource {
+  customers: CustomersAPI.Customers = new CustomersAPI.Customers(this._client);
+  products: ProductsAPI.Products = new ProductsAPI.Products(this._client);
+  entitlements: EntitlementsAPI.Entitlements = new EntitlementsAPI.Entitlements(this._client);
+  coupons: CouponsAPI.Coupons = new CouponsAPI.Coupons(this._client);
+
+  /**
+   * Cancels a customer's subscription. By default, the subscription remains active
+   * until the end of the current billing period. Set cancellation_timing to
+   * 'immediate' to cancel immediately.
+   */
+  cancel(body: PayCancelParams, options?: RequestOptions): APIPromise<PayCancelResponse> {
+    return this._client.post('/v1/pay/cancel', { body, ...options });
+  }
+
+  /**
+   * Verifies if a customer has access to a specific feature. Use this to gate
+   * features in your app based on the customer's active subscription and the
+   * entitlements attached to their product. Hercules recommends calling this before
+   * allowing access to premium features.
+   */
+  check(body: PayCheckParams, options?: RequestOptions): APIPromise<PayCheckResponse> {
+    return this._client.post('/v1/pay/check', { body, ...options });
+  }
+
+  /**
+   * Creates a checkout session for a customer to subscribe to a product. Returns a
+   * URL to redirect the customer to for payment. After successful payment, the
+   * customer is subscribed to the product and gains access to its entitlements.
+   */
+  checkout(body: PayCheckoutParams, options?: RequestOptions): APIPromise<PayCheckoutResponse> {
+    return this._client.post('/v1/pay/checkout', { body, ...options });
+  }
+}
+
+/**
+ * Cancel subscription response
+ */
+export interface PayCancelResponse {
+  /**
+   * The subscription ID
+   */
+  id: string;
+
+  /**
+   * When the cancellation takes effect
+   */
+  cancellation_timing: 'immediate' | 'at_billing_period_end';
+
+  /**
+   * The subscription status
+   */
+  status: string;
+
+  /**
+   * When the subscription was canceled
+   */
+  canceled_at?: string | null;
+}
+
+/**
+ * Check entitlement response
+ */
+export interface PayCheckResponse {
+  /**
+   * The entitlement ID that was checked
+   */
+  entitlement_id: string;
+
+  /**
+   * Whether the customer has the entitlement
+   */
+  has_entitlement: boolean;
+}
+
+/**
+ * Checkout response. For new customers, returns a checkout URL. For existing
+ * subscribers, returns the updated subscription.
+ */
+export interface PayCheckoutResponse {
+  /**
+   * The checkout session ID (for checkout action) or subscription ID (for update
+   * action)
+   */
+  id: string;
+
+  /**
+   * 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.
+   */
+  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 {
+  /**
+   * The customer ID
+   */
+  customer_id: string;
+
+  /**
+   * The subscription ID to cancel
+   */
+  subscription_id: string;
+
+  /**
+   * When to cancel the subscription. Defaults to 'at_billing_period_end' to allow
+   * customers to use remaining time.
+   */
+  cancellation_timing?: 'immediate' | 'at_billing_period_end';
+}
+
+export interface PayCheckParams {
+  /**
+   * The customer ID
+   */
+  customer_id: string;
+
+  /**
+   * The entitlement ID to check for access
+   */
+  entitlement_id: string;
+}
+
+export interface PayCheckoutParams {
+  /**
+   * The customer ID
+   */
+  customer_id: string;
+
+  /**
+   * The product ID to purchase
+   */
+  product_id: string;
+
+  /**
+   * 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
+   */
+  cancel_url?: string;
+
+  /**
+   * Promotion code to apply
+   */
+  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;
+Pay.Products = Products;
+Pay.Entitlements = Entitlements;
+Pay.Coupons = Coupons;
+
+export declare namespace Pay {
+  export {
+    type PayCancelResponse as PayCancelResponse,
+    type PayCheckResponse as PayCheckResponse,
+    type PayCheckoutResponse as PayCheckoutResponse,
+    type PayCancelParams as PayCancelParams,
+    type PayCheckParams as PayCheckParams,
+    type PayCheckoutParams as PayCheckoutParams,
+  };
+
+  export {
+    Customers as Customers,
+    type Customer as Customer,
+    type CustomerAddress as CustomerAddress,
+    type CustomerBillingPortalResponse as CustomerBillingPortalResponse,
+    type CustomersCursorIDPage as CustomersCursorIDPage,
+    type CustomerCreateParams as CustomerCreateParams,
+    type CustomerUpdateParams as CustomerUpdateParams,
+    type CustomerListParams as CustomerListParams,
+    type CustomerBillingPortalParams as CustomerBillingPortalParams,
+  };
+
+  export {
+    Products as Products,
+    type Product as Product,
+    type ProductsCursorIDPage as ProductsCursorIDPage,
+    type ProductCreateParams as ProductCreateParams,
+    type ProductUpdateParams as ProductUpdateParams,
+    type ProductListParams as ProductListParams,
+  };
+
+  export {
+    Entitlements as Entitlements,
+    type Entitlement as Entitlement,
+    type EntitlementsCursorIDPage as EntitlementsCursorIDPage,
+    type EntitlementCreateParams as EntitlementCreateParams,
+    type EntitlementUpdateParams as EntitlementUpdateParams,
+    type EntitlementListParams as EntitlementListParams,
+  };
+
+  export {
+    Coupons as Coupons,
+    type Coupon as Coupon,
+    type CouponsCursorIDPage as CouponsCursorIDPage,
+    type CouponCreateParams as CouponCreateParams,
+    type CouponUpdateParams as CouponUpdateParams,
+    type CouponListParams as CouponListParams,
+  };
+}

package/src/resources/beta/{subscriptions/plans → pay/products}/entitlements.ts

@@ -10,56 +10,61 @@ import { path } from '../../../../internal/utils/path';
 
 export class Entitlements extends APIResource {
   /**
-   * List Plan Entitlements
+   * Retrieves all entitlements attached to a product. These entitlements define the
+   * features that customers subscribed to this product can access.
    */
   list(
-    planID: string,
+    productID: string,
     query: EntitlementListParams | null | undefined = {},
     options?: RequestOptions,
-  ): PagePromise<PlanEntitlementsCursorIDPage, PlanEntitlement> {
+  ): PagePromise<ProductEntitlementsCursorIDPage, ProductEntitlement> {
     return this._client.getAPIList(
-      path`/v1/subscriptions/plans/${planID}/entitlements`,
-      CursorIDPage<PlanEntitlement>,
+      path`/v1/pay/products/${productID}/entitlements`,
+      CursorIDPage<ProductEntitlement>,
       { query, ...options },
     );
   }
 
   /**
-   * Attach Entitlement to Plan
+   * Attaches an entitlement to a product. All customers subscribed to this product
+   * will gain access to the attached feature. Hercules recommends attaching
+   * entitlements when creating or updating products to keep feature access in sync.
    */
   attach(
-    planID: string,
+    productID: string,
     body: EntitlementAttachParams,
     options?: RequestOptions,
-  ): APIPromise<PlanEntitlement> {
-    return this._client.post(path`/v1/subscriptions/plans/${planID}/entitlements`, { body, ...options });
+  ): APIPromise<ProductEntitlement> {
+    return this._client.post(path`/v1/pay/products/${productID}/entitlements`, { body, ...options });
   }
 
   /**
-   * Remove Entitlement from Plan
+   * Removes an entitlement from a product. Customers subscribed to this product will
+   * lose access to the feature. Existing subscriptions are affected immediately.
    */
   remove(featureID: string, params: EntitlementRemoveParams, options?: RequestOptions): APIPromise<void> {
-    const { plan_id } = params;
-    return this._client.delete(path`/v1/subscriptions/plans/${plan_id}/entitlements/${featureID}`, {
+    const { product_id } = params;
+    return this._client.delete(path`/v1/pay/products/${product_id}/entitlements/${featureID}`, {
       ...options,
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 }
 
-export type PlanEntitlementsCursorIDPage = CursorIDPage<PlanEntitlement>;
+export type ProductEntitlementsCursorIDPage = CursorIDPage<ProductEntitlement>;
 
 /**
- * An entitlement attached to a plan
+ * An entitlement attached to a product. All customers subscribed to the product
+ * gain access to this entitlement.
  */
-export interface PlanEntitlement {
+export interface ProductEntitlement {
   /**
-   * An id for a data item
+   * Unique identifier for the price
    */
   id: string;
 
   /**
-   * An entitlement that can be attached to products
+   * The entitlement attached to the product
    */
   entitlement: EntitlementsAPI.Entitlement;
 }
@@ -68,19 +73,19 @@ export interface EntitlementListParams extends CursorIDPageParams {}
 
 export interface EntitlementAttachParams {
   /**
-   * The ID of the entitlement to attach
+   * The ID of the entitlement to attach to the product
    */
   entitlement: string;
 }
 
 export interface EntitlementRemoveParams {
-  plan_id: string;
+  product_id: string;
 }
 
 export declare namespace Entitlements {
   export {
-    type PlanEntitlement as PlanEntitlement,
-    type PlanEntitlementsCursorIDPage as PlanEntitlementsCursorIDPage,
+    type ProductEntitlement as ProductEntitlement,
+    type ProductEntitlementsCursorIDPage as ProductEntitlementsCursorIDPage,
     type EntitlementListParams as EntitlementListParams,
     type EntitlementAttachParams as EntitlementAttachParams,
     type EntitlementRemoveParams as EntitlementRemoveParams,

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

@@ -0,0 +1,28 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Entitlements,
+  type ProductEntitlement,
+  type EntitlementListParams,
+  type EntitlementAttachParams,
+  type EntitlementRemoveParams,
+  type ProductEntitlementsCursorIDPage,
+} from './entitlements';
+export {
+  Products,
+  type Product,
+  type ProductCreateParams,
+  type ProductUpdateParams,
+  type ProductListParams,
+  type ProductsCursorIDPage,
+} from './products';
+export {
+  Variants,
+  type Variant,
+  type VariantCreateParams,
+  type VariantUpdateParams,
+  type VariantListParams,
+  type VariantArchiveParams,
+  type VariantGetParams,
+  type VariantsCursorIDPage,
+} from './variants';