@usehercules/sdk 1.1.0 → 1.3.0

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

@@ -0,0 +1,229 @@
+// 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 Customers extends APIResource {
+  /**
+   * Creates a new billable customer. A customer represents the entity in your app
+   * that will be charged—typically a user, organization, or project. Hercules
+   * recommends creating a customer immediately after creating the corresponding
+   * entity in your app.
+   */
+  create(body: CustomerCreateParams | null | undefined = {}, options?: RequestOptions): APIPromise<Customer> {
+    return this._client.post('/v1/pay/customers', { body, ...options });
+  }
+
+  /**
+   * Updates an existing customer. Use this to modify contact information or billing
+   * address. Only provided fields are updated; omitted fields remain unchanged.
+   */
+  update(
+    customerID: string,
+    body: CustomerUpdateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Customer> {
+    return this._client.patch(path`/v1/pay/customers/${customerID}`, { body, ...options });
+  }
+
+  /**
+   * Retrieves a paginated list of all customers. Customers are the billable entities
+   * in your app—typically users, organizations, or projects.
+   */
+  list(
+    query: CustomerListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CustomersCursorIDPage, Customer> {
+    return this._client.getAPIList('/v1/pay/customers', CursorIDPage<Customer>, { query, ...options });
+  }
+
+  /**
+   * Permanently deletes a customer. This also cancels any active subscriptions. This
+   * action cannot be undone.
+   */
+  delete(customerID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/pay/customers/${customerID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Generates a URL to a hosted billing portal where the customer can view invoices,
+   * update payment methods, and manage billing details. Redirect the customer to the
+   * returned URL.
+   */
+  billingPortal(
+    customerID: string,
+    body: CustomerBillingPortalParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<CustomerBillingPortalResponse> {
+    return this._client.post(path`/v1/pay/customers/${customerID}/billing_portal`, { body, ...options });
+  }
+
+  /**
+   * Retrieves a customer by ID. Returns the customer object including contact
+   * information and billing address.
+   */
+  get(customerID: string, options?: RequestOptions): APIPromise<Customer> {
+    return this._client.get(path`/v1/pay/customers/${customerID}`, options);
+  }
+}
+
+export type CustomersCursorIDPage = CursorIDPage<Customer>;
+
+/**
+ * A billable customer. Represents the entity in your app that will be
+ * charged—typically a user, organization, or project.
+ */
+export interface Customer {
+  /**
+   * Unique identifier for the entitlement
+   */
+  id: string;
+
+  /**
+   * Timestamp when the customer was created
+   */
+  created: string;
+
+  /**
+   * The customer's billing address
+   */
+  address?: CustomerAddress | null;
+
+  /**
+   * The customer's email address for receipts and notifications
+   */
+  email?: string | null;
+
+  /**
+   * The customer's full name
+   */
+  name?: string | null;
+
+  /**
+   * The customer's phone number
+   */
+  phone?: string | null;
+}
+
+/**
+ * The customer's billing address
+ */
+export interface CustomerAddress {
+  /**
+   * City name
+   */
+  city?: string | null;
+
+  /**
+   * Two-letter ISO country code
+   */
+  country?: string | null;
+
+  /**
+   * Street address line 1
+   */
+  line1?: string | null;
+
+  /**
+   * Street address line 2 (apartment, suite, etc.)
+   */
+  line2?: string | null;
+
+  /**
+   * Postal or ZIP code
+   */
+  postal_code?: string | null;
+
+  /**
+   * State, province, or region
+   */
+  state?: string | null;
+}
+
+/**
+ * Response containing the billing portal URL
+ */
+export interface CustomerBillingPortalResponse {
+  /**
+   * URL to redirect the customer to for the billing portal
+   */
+  url: string;
+}
+
+export interface CustomerCreateParams {
+  /**
+   * Optional custom ID for the customer. If not provided, one will be generated.
+   */
+  id?: string;
+
+  /**
+   * The customer's billing address
+   */
+  address?: CustomerAddress;
+
+  /**
+   * The customer's email address for receipts and notifications
+   */
+  email?: string;
+
+  /**
+   * The customer's full name
+   */
+  name?: string;
+
+  /**
+   * The customer's phone number
+   */
+  phone?: string;
+}
+
+export interface CustomerUpdateParams {
+  /**
+   * The customer's billing address
+   */
+  address?: CustomerAddress;
+
+  /**
+   * The customer's email address for receipts and notifications
+   */
+  email?: string;
+
+  /**
+   * The customer's full name
+   */
+  name?: string;
+
+  /**
+   * The customer's phone number
+   */
+  phone?: string;
+}
+
+export interface CustomerListParams extends CursorIDPageParams {}
+
+export interface CustomerBillingPortalParams {
+  /**
+   * URL to redirect the customer to after they exit the billing portal
+   */
+  return_url?: string;
+}
+
+export declare namespace Customers {
+  export {
+    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,
+  };
+}

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

@@ -0,0 +1,135 @@
+// 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 Entitlements extends APIResource {
+  /**
+   * Creates a new feature entitlement. Entitlements represent features or
+   * capabilities in your app that can be gated by subscription. After creating an
+   * entitlement, attach it to one or more plans to grant access to customers on
+   * those plans.
+   */
+  create(body: EntitlementCreateParams, options?: RequestOptions): APIPromise<Entitlement> {
+    return this._client.post('/v1/pay/entitlements', { body, ...options });
+  }
+
+  /**
+   * Updates an existing entitlement. Use this to modify the name or deactivate the
+   * entitlement. The key cannot be changed after creation.
+   */
+  update(
+    entitlementID: string,
+    body: EntitlementUpdateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Entitlement> {
+    return this._client.patch(path`/v1/pay/entitlements/${entitlementID}`, { body, ...options });
+  }
+
+  /**
+   * Retrieves a paginated list of all entitlements. Entitlements represent features
+   * or capabilities in your app that can be gated by subscription. Use the key
+   * filter to find a specific entitlement by its key.
+   */
+  list(
+    query: EntitlementListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EntitlementsCursorIDPage, Entitlement> {
+    return this._client.getAPIList('/v1/pay/entitlements', CursorIDPage<Entitlement>, { query, ...options });
+  }
+
+  /**
+   * Retrieves an entitlement by ID. Returns the entitlement object including its
+   * lookup key and active status.
+   */
+  get(entitlementID: string, options?: RequestOptions): APIPromise<Entitlement> {
+    return this._client.get(path`/v1/pay/entitlements/${entitlementID}`, options);
+  }
+}
+
+export type EntitlementsCursorIDPage = CursorIDPage<Entitlement>;
+
+/**
+ * The entitlement attached to the product
+ */
+export interface Entitlement {
+  /**
+   * Unique identifier for the entitlement
+   */
+  id: string;
+
+  /**
+   * Whether the entitlement is active and can be attached to products
+   */
+  active: boolean;
+
+  /**
+   * Unique key to identify the entitlement when checking access in your app
+   */
+  key: string;
+
+  /**
+   * Whether this is a live mode entitlement (vs test mode)
+   */
+  livemode: boolean;
+
+  /**
+   * Display name for the entitlement (e.g., API Access, Premium Support)
+   */
+  name: string;
+}
+
+export interface EntitlementCreateParams {
+  /**
+   * Unique key to identify the entitlement when checking access. Use a descriptive,
+   * stable key (e.g., api_access, premium_support).
+   */
+  key: string;
+
+  /**
+   * Display name for the entitlement (e.g., API Access, Premium Support)
+   */
+  name: string;
+
+  /**
+   * Optional custom ID for the entitlement. If not provided, one will be generated.
+   */
+  id?: string;
+}
+
+export interface EntitlementUpdateParams {
+  /**
+   * Whether the entitlement is active. Deactivating removes it from access checks.
+   */
+  active?: boolean;
+
+  /**
+   * Display name for the entitlement
+   */
+  name?: string;
+}
+
+export interface EntitlementListParams extends CursorIDPageParams {
+  /**
+   * Filter by archived status
+   */
+  archived?: 'true' | 'false';
+
+  /**
+   * Filter by exact key match
+   */
+  key?: string;
+}
+
+export declare namespace Entitlements {
+  export {
+    type Entitlement as Entitlement,
+    type EntitlementsCursorIDPage as EntitlementsCursorIDPage,
+    type EntitlementCreateParams as EntitlementCreateParams,
+    type EntitlementUpdateParams as EntitlementUpdateParams,
+    type EntitlementListParams as EntitlementListParams,
+  };
+}

package/src/resources/beta/{subscriptions → pay}/index.ts

@@ -3,11 +3,9 @@
 export {
   Coupons,
   type Coupon,
-  type CouponValidateResponse,
   type CouponCreateParams,
   type CouponUpdateParams,
   type CouponListParams,
-  type CouponValidateParams,
   type CouponsCursorIDPage,
 } from './coupons';
 export {
@@ -30,19 +28,19 @@ export {
   type EntitlementsCursorIDPage,
 } from './entitlements';
 export {
-  Plans,
-  type Plan,
-  type PlanCreateParams,
-  type PlanUpdateParams,
-  type PlanListParams,
-  type PlansCursorIDPage,
-} from './plans/index';
+  Pay,
+  type PayCancelResponse,
+  type PayCheckResponse,
+  type PayCheckoutResponse,
+  type PayCancelParams,
+  type PayCheckParams,
+  type PayCheckoutParams,
+} from './pay';
 export {
-  Subscriptions,
-  type SubscriptionCancelResponse,
-  type SubscriptionCheckResponse,
-  type SubscriptionCheckoutResponse,
-  type SubscriptionCancelParams,
-  type SubscriptionCheckParams,
-  type SubscriptionCheckoutParams,
-} from './subscriptions';
+  Products,
+  type Product,
+  type ProductCreateParams,
+  type ProductUpdateParams,
+  type ProductListParams,
+  type ProductsCursorIDPage,
+} from './products/index';

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

@@ -7,8 +7,6 @@ import {
   CouponCreateParams,
   CouponListParams,
   CouponUpdateParams,
-  CouponValidateParams,
-  CouponValidateResponse,
   Coupons,
   CouponsCursorIDPage,
 } from './coupons';
@@ -33,62 +31,66 @@ import {
   Entitlements,
   EntitlementsCursorIDPage,
 } from './entitlements';
-import * as PlansAPI from './plans/plans';
+import * as ProductsAPI from './products/products';
 import {
-  Plan,
-  PlanCreateParams,
-  PlanListParams,
-  PlanUpdateParams,
-  Plans,
-  PlansCursorIDPage,
-} from './plans/plans';
+  Product,
+  ProductCreateParams,
+  ProductListParams,
+  ProductUpdateParams,
+  Products,
+  ProductsCursorIDPage,
+} from './products/products';
 import { APIPromise } from '../../../core/api-promise';
 import { RequestOptions } from '../../../internal/request-options';
 
-export class Subscriptions extends APIResource {
+export class Pay extends APIResource {
   customers: CustomersAPI.Customers = new CustomersAPI.Customers(this._client);
-  plans: PlansAPI.Plans = new PlansAPI.Plans(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);
 
   /**
-   * Cancel Subscription
+   * 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: SubscriptionCancelParams, options?: RequestOptions): APIPromise<SubscriptionCancelResponse> {
-    return this._client.post('/v1/subscriptions/cancel', { body, ...options });
+  cancel(body: PayCancelParams, options?: RequestOptions): APIPromise<PayCancelResponse> {
+    return this._client.post('/v1/pay/cancel', { body, ...options });
   }
 
   /**
-   * Check Entitlement
+   * 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: SubscriptionCheckParams, options?: RequestOptions): APIPromise<SubscriptionCheckResponse> {
-    return this._client.post('/v1/subscriptions/check', { body, ...options });
+  check(body: PayCheckParams, options?: RequestOptions): APIPromise<PayCheckResponse> {
+    return this._client.post('/v1/pay/check', { body, ...options });
   }
 
   /**
-   * Create Checkout Session
+   * 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: SubscriptionCheckoutParams,
-    options?: RequestOptions,
-  ): APIPromise<SubscriptionCheckoutResponse> {
-    return this._client.post('/v1/subscriptions/checkout', { body, ...options });
+  checkout(body: PayCheckoutParams, options?: RequestOptions): APIPromise<PayCheckoutResponse> {
+    return this._client.post('/v1/pay/checkout', { body, ...options });
   }
 }
 
 /**
  * Cancel subscription response
  */
-export interface SubscriptionCancelResponse {
+export interface PayCancelResponse {
   /**
    * The subscription ID
    */
   id: string;
 
   /**
-   * Whether the subscription will cancel at period end
+   * When the cancellation takes effect
    */
-  cancel_at_period_end: boolean;
+  cancellation_timing: 'immediate' | 'at_billing_period_end';
 
   /**
    * The subscription status
@@ -104,16 +106,16 @@ export interface SubscriptionCancelResponse {
 /**
  * Check entitlement response
  */
-export interface SubscriptionCheckResponse {
+export interface PayCheckResponse {
   /**
    * Whether the customer has the entitlement
    */
   has_entitlement: boolean;
 
   /**
-   * The entitlement lookup key that was checked
+   * The entitlement key that was checked
    */
-  lookup_key: string;
+  key: string;
 
   /**
    * The active entitlement ID if present
@@ -124,7 +126,7 @@ export interface SubscriptionCheckResponse {
 /**
  * Checkout session response
  */
-export interface SubscriptionCheckoutResponse {
+export interface PayCheckoutResponse {
   /**
    * The checkout session ID
    */
@@ -136,7 +138,7 @@ export interface SubscriptionCheckoutResponse {
   url: string;
 }
 
-export interface SubscriptionCancelParams {
+export interface PayCancelParams {
   /**
    * The customer ID
    */
@@ -148,58 +150,69 @@ export interface SubscriptionCancelParams {
   subscription_id: string;
 
   /**
-   * Whether to cancel at period end or immediately
+   * When to cancel the subscription. Defaults to 'at_billing_period_end' to allow
+   * customers to use remaining time.
    */
-  cancel_at_period_end?: boolean;
+  cancellation_timing?: 'immediate' | 'at_billing_period_end';
 }
 
-export interface SubscriptionCheckParams {
+export interface PayCheckParams {
   /**
    * The customer ID
    */
   customer_id: string;
 
   /**
-   * The entitlement feature lookup key to check
+   * The entitlement key to check for access
    */
-  entitlement_lookup_key: string;
+  entitlement_key: string;
 }
 
-export interface SubscriptionCheckoutParams {
+export interface PayCheckoutParams {
   /**
    * The customer ID
    */
   customer_id: string;
 
   /**
-   * The plan ID to subscribe to
+   * The product ID to subscribe to
    */
-  plan_id: string;
+  product_id: string;
+
+  /**
+   * Optional custom ID for the subscription. If not provided, one will be generated.
+   */
+  id?: string;
 
   /**
    * URL to redirect on cancel
    */
   cancel_url?: string;
 
+  /**
+   * Promotion code to apply
+   */
+  promotion_code?: string;
+
   /**
    * URL to redirect on success
    */
   success_url?: string;
 }
 
-Subscriptions.Customers = Customers;
-Subscriptions.Plans = Plans;
-Subscriptions.Entitlements = Entitlements;
-Subscriptions.Coupons = Coupons;
+Pay.Customers = Customers;
+Pay.Products = Products;
+Pay.Entitlements = Entitlements;
+Pay.Coupons = Coupons;
 
-export declare namespace Subscriptions {
+export declare namespace Pay {
   export {
-    type SubscriptionCancelResponse as SubscriptionCancelResponse,
-    type SubscriptionCheckResponse as SubscriptionCheckResponse,
-    type SubscriptionCheckoutResponse as SubscriptionCheckoutResponse,
-    type SubscriptionCancelParams as SubscriptionCancelParams,
-    type SubscriptionCheckParams as SubscriptionCheckParams,
-    type SubscriptionCheckoutParams as SubscriptionCheckoutParams,
+    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 {
@@ -215,12 +228,12 @@ export declare namespace Subscriptions {
   };
 
   export {
-    Plans as Plans,
-    type Plan as Plan,
-    type PlansCursorIDPage as PlansCursorIDPage,
-    type PlanCreateParams as PlanCreateParams,
-    type PlanUpdateParams as PlanUpdateParams,
-    type PlanListParams as PlanListParams,
+    Products as Products,
+    type Product as Product,
+    type ProductsCursorIDPage as ProductsCursorIDPage,
+    type ProductCreateParams as ProductCreateParams,
+    type ProductUpdateParams as ProductUpdateParams,
+    type ProductListParams as ProductListParams,
   };
 
   export {
@@ -235,11 +248,9 @@ export declare namespace Subscriptions {
   export {
     Coupons as Coupons,
     type Coupon as Coupon,
-    type CouponValidateResponse as CouponValidateResponse,
     type CouponsCursorIDPage as CouponsCursorIDPage,
     type CouponCreateParams as CouponCreateParams,
     type CouponUpdateParams as CouponUpdateParams,
     type CouponListParams as CouponListParams,
-    type CouponValidateParams as CouponValidateParams,
   };
 }