@usehercules/sdk 1.2.0 → 1.4.0

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

@@ -0,0 +1,218 @@
+// 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 Coupons extends APIResource {
+  /**
+   * Creates a discount coupon with a promo code. Coupons can offer percentage or
+   * fixed-amount discounts and can be limited by redemption count or expiration
+   * date. Customers can apply coupons during checkout.
+   */
+  create(body: CouponCreateParams, options?: RequestOptions): APIPromise<Coupon> {
+    return this._client.post('/v1/pay/coupons', { body, ...options });
+  }
+
+  /**
+   * Updates an existing coupon. Use this to modify the display name or deactivate
+   * the coupon. Discount amounts and codes cannot be changed after creation.
+   */
+  update(
+    couponID: string,
+    body: CouponUpdateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Coupon> {
+    return this._client.patch(path`/v1/pay/coupons/${couponID}`, { body, ...options });
+  }
+
+  /**
+   * Retrieves a paginated list of all coupons. Coupons provide discounts that
+   * customers can apply during checkout using a promo code.
+   */
+  list(
+    query: CouponListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CouponsCursorIDPage, Coupon> {
+    return this._client.getAPIList('/v1/pay/coupons', CursorIDPage<Coupon>, { query, ...options });
+  }
+
+  /**
+   * Permanently deletes a coupon. The promo code can no longer be used. Existing
+   * discounts applied to active subscriptions are not affected.
+   */
+  delete(couponID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/pay/coupons/${couponID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Retrieves a coupon by ID. Returns the coupon object including discount details
+   * and redemption statistics.
+   */
+  get(couponID: string, options?: RequestOptions): APIPromise<Coupon> {
+    return this._client.get(path`/v1/pay/coupons/${couponID}`, options);
+  }
+}
+
+export type CouponsCursorIDPage = CursorIDPage<Coupon>;
+
+/**
+ * A discount coupon that customers can apply during checkout using a promo code
+ */
+export interface Coupon {
+  /**
+   * Unique identifier for the price
+   */
+  id: string;
+
+  /**
+   * Whether the coupon is currently active and can be redeemed
+   */
+  active: boolean;
+
+  /**
+   * The promo code customers enter to apply the discount
+   */
+  code: string;
+
+  /**
+   * Timestamp when the coupon was created
+   */
+  created: string;
+
+  /**
+   * How long the discount applies: once (first payment only), repeating (for
+   * duration_in_months), or forever
+   */
+  duration: 'once' | 'repeating' | 'forever';
+
+  /**
+   * Number of times this coupon has been successfully redeemed
+   */
+  times_redeemed: number;
+
+  /**
+   * Fixed discount amount in the smallest currency unit (e.g., cents). Mutually
+   * exclusive with percent_off.
+   */
+  amount_off?: number | null;
+
+  /**
+   * Three-letter ISO currency code for amount_off discounts
+   */
+  currency?: string | null;
+
+  /**
+   * Number of months the discount applies when duration is 'repeating'
+   */
+  duration_in_months?: number | null;
+
+  /**
+   * Maximum number of times this coupon can be redeemed across all customers
+   */
+  max_redemptions?: number | null;
+
+  /**
+   * Display name for the coupon (shown to customers)
+   */
+  name?: string | null;
+
+  /**
+   * Percentage discount (1-100). Mutually exclusive with amount_off.
+   */
+  percent_off?: number | null;
+
+  /**
+   * Expiration date after which the coupon can no longer be redeemed
+   */
+  redeem_by?: string | null;
+}
+
+export interface CouponCreateParams {
+  /**
+   * The promo code customers will enter to apply the discount
+   */
+  code: string;
+
+  /**
+   * Optional custom ID for the coupon. If not provided, one will be generated.
+   */
+  id?: string;
+
+  /**
+   * Fixed discount in the smallest currency unit (e.g., cents). Mutually exclusive
+   * with percent_off.
+   */
+  amount_off?: number;
+
+  /**
+   * Three-letter ISO currency code for amount_off discounts
+   */
+  currency?: string;
+
+  /**
+   * How long the discount applies: once (first payment only), repeating (for
+   * duration_in_months), or forever
+   */
+  duration?: 'once' | 'repeating' | 'forever';
+
+  /**
+   * Number of months the discount applies when duration is 'repeating'
+   */
+  duration_in_months?: number;
+
+  /**
+   * Maximum number of times this coupon can be redeemed
+   */
+  max_redemptions?: number;
+
+  /**
+   * Display name for the coupon (shown to customers)
+   */
+  name?: string;
+
+  /**
+   * Percentage discount (1-100). Mutually exclusive with amount_off.
+   */
+  percent_off?: number;
+
+  /**
+   * Expiration date after which the coupon can no longer be redeemed
+   */
+  redeem_by?: string;
+}
+
+export interface CouponUpdateParams {
+  /**
+   * Whether the coupon is active and can be redeemed
+   */
+  active?: boolean;
+
+  /**
+   * Display name for the coupon
+   */
+  name?: string;
+}
+
+export interface CouponListParams extends CursorIDPageParams {
+  /**
+   * Filter by active status
+   */
+  active?: boolean;
+}
+
+export declare namespace Coupons {
+  export {
+    type Coupon as Coupon,
+    type CouponsCursorIDPage as CouponsCursorIDPage,
+    type CouponCreateParams as CouponCreateParams,
+    type CouponUpdateParams as CouponUpdateParams,
+    type CouponListParams as CouponListParams,
+  };
+}

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 price
+   */
+  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/{subscriptions → pay}/entitlements.ts

@@ -8,84 +8,89 @@ import { path } from '../../../internal/utils/path';
 
 export class Entitlements extends APIResource {
   /**
-   * Create Entitlement
+   * 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/subscriptions/entitlements', { body, ...options });
+    return this._client.post('/v1/pay/entitlements', { body, ...options });
   }
 
   /**
-   * Update Entitlement
+   * Updates an existing entitlement. Use this to modify the name or deactivate the
+   * entitlement.
    */
   update(
     entitlementID: string,
     body: EntitlementUpdateParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<Entitlement> {
-    return this._client.patch(path`/v1/subscriptions/entitlements/${entitlementID}`, { body, ...options });
+    return this._client.patch(path`/v1/pay/entitlements/${entitlementID}`, { body, ...options });
   }
 
   /**
-   * List Entitlements
+   * Retrieves a paginated list of all entitlements. Entitlements represent features
+   * or capabilities in your app that can be gated by subscription.
    */
   list(
     query: EntitlementListParams | null | undefined = {},
     options?: RequestOptions,
   ): PagePromise<EntitlementsCursorIDPage, Entitlement> {
-    return this._client.getAPIList('/v1/subscriptions/entitlements', CursorIDPage<Entitlement>, {
-      query,
-      ...options,
-    });
+    return this._client.getAPIList('/v1/pay/entitlements', CursorIDPage<Entitlement>, { query, ...options });
   }
 
   /**
-   * Get Entitlement
+   * Retrieves an entitlement by ID. Returns the entitlement object including its
+   * active status.
    */
   get(entitlementID: string, options?: RequestOptions): APIPromise<Entitlement> {
-    return this._client.get(path`/v1/subscriptions/entitlements/${entitlementID}`, options);
+    return this._client.get(path`/v1/pay/entitlements/${entitlementID}`, options);
   }
 }
 
 export type EntitlementsCursorIDPage = CursorIDPage<Entitlement>;
 
 /**
- * An entitlement that can be attached to products
+ * The entitlement attached to the product
  */
 export interface Entitlement {
   /**
-   * An id for a data item
+   * Unique identifier for the price
    */
   id: string;
 
+  /**
+   * Whether the entitlement is active and can be attached to products
+   */
   active: boolean;
 
-  livemode: boolean;
-
-  lookup_key: string;
-
+  /**
+   * Display name for the entitlement (e.g., API Access, Premium Support)
+   */
   name: string;
 }
 
 export interface EntitlementCreateParams {
   /**
-   * A unique key to identify the entitlement in your system
+   * Display name for the entitlement (e.g., API Access, Premium Support)
    */
-  lookup_key: string;
+  name: string;
 
   /**
-   * The name of the entitlement
+   * Optional custom ID for the entitlement. If not provided, one will be generated.
    */
-  name: string;
+  id?: string;
 }
 
 export interface EntitlementUpdateParams {
   /**
-   * Whether the entitlement is active
+   * Whether the entitlement is active. Deactivating removes it from access checks.
    */
   active?: boolean;
 
   /**
-   * The name of the entitlement
+   * Display name for the entitlement
    */
   name?: string;
 }
@@ -94,12 +99,7 @@ export interface EntitlementListParams extends CursorIDPageParams {
   /**
    * Filter by archived status
    */
-  archived?: boolean;
-
-  /**
-   * Filter by lookup key
-   */
-  lookup_key?: string;
+  archived?: 'true' | 'false';
 }
 
 export declare namespace Entitlements {

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

@@ -28,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';