@usehercules/sdk 1.10.1 → 1.12.0

package/src/resources/{beta/commerce → commerce/customers}/customers.ts

@@ -1,67 +1,82 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../../core/resource';
+import * as BalanceTransactionsAPI from './balance-transactions';
+import { BalanceTransactions } from './balance-transactions';
 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 {
+  balanceTransactions: BalanceTransactionsAPI.BalanceTransactions =
+    new BalanceTransactionsAPI.BalanceTransactions(this._client);
+
   /**
    * 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.
+   *
+   * @example
+   * ```ts
+   * const customer = await client.commerce.customers.create();
+   * ```
    */
-  create(
-    body: CustomerCreateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<CustomerCreateResponse> {
+  create(body: CustomerCreateParams | null | undefined = {}, options?: RequestOptions): APIPromise<Customer> {
     return this._client.post('/v1/commerce/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.
+   *
+   * @example
+   * ```ts
+   * const customer = await client.commerce.customers.update(
+   *   'cus_1234567890',
+   * );
+   * ```
    */
   update(
     customerID: string,
     body: CustomerUpdateParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<CustomerUpdateResponse> {
+  ): APIPromise<Customer> {
     return this._client.patch(path`/v1/commerce/customers/${customerID}`, { body, ...options });
   }
 
   /**
    * Retrieves a paginated list of all customers. Customers are the billable entities
    * in your app—typically users, organizations, or projects.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const customer of client.commerce.customers.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: CustomerListParams | null | undefined = {},
     options?: RequestOptions,
-  ): PagePromise<CustomerListResponsesCursorIDPage, CustomerListResponse> {
-    return this._client.getAPIList('/v1/commerce/customers', CursorIDPage<CustomerListResponse>, {
-      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/commerce/customers/${customerID}`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  ): PagePromise<CustomersCursorIDPage, Customer> {
+    return this._client.getAPIList('/v1/commerce/customers', CursorIDPage<Customer>, { query, ...options });
   }
 
   /**
    * 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.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.commerce.customers.billingPortal(
+   *     'cus_1234567890',
+   *   );
+   * ```
    */
   billingPortal(
     customerID: string,
@@ -75,21 +90,28 @@ export class Customers extends APIResource {
    * Retrieves a customer by ID. Returns the customer object including contact
    * information, billing address, active subscriptions, recent invoices, and saved
    * payment methods.
+   *
+   * @example
+   * ```ts
+   * const customer = await client.commerce.customers.get(
+   *   'cus_1234567890',
+   * );
+   * ```
    */
   get(customerID: string, options?: RequestOptions): APIPromise<CustomerGetResponse> {
     return this._client.get(path`/v1/commerce/customers/${customerID}`, options);
   }
 }
 
-export type CustomerListResponsesCursorIDPage = CursorIDPage<CustomerListResponse>;
+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 CustomerCreateResponse {
+export interface Customer {
   /**
-   * Unique identifier for the topic subscription
+   * Unique identifier for the customer
    */
   id: string;
 
@@ -101,7 +123,7 @@ export interface CustomerCreateResponse {
   /**
    * The customer's billing address
    */
-  address?: CustomerCreateResponse.Address | null;
+  address?: CustomerAddress | null;
 
   /**
    * The customer's email address for receipts and notifications
@@ -119,187 +141,39 @@ export interface CustomerCreateResponse {
   phone?: string | null;
 }
 
-export namespace CustomerCreateResponse {
-  /**
-   * The customer's billing address
-   */
-  export interface Address {
-    /**
-     * 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;
-  }
-}
-
 /**
- * A billable customer. Represents the entity in your app that will be
- * charged—typically a user, organization, or project.
+ * The customer's billing address
  */
-export interface CustomerUpdateResponse {
+export interface CustomerAddress {
   /**
-   * Unique identifier for the topic subscription
+   * City name
    */
-  id: string;
+  city?: string | null;
 
   /**
-   * Timestamp when the customer was created
+   * Two-letter ISO country code
    */
-  created: string;
+  country?: string | null;
 
   /**
-   * The customer's billing address
+   * Street address line 1
    */
-  address?: CustomerUpdateResponse.Address | null;
+  line1?: string | null;
 
   /**
-   * The customer's email address for receipts and notifications
+   * Street address line 2 (apartment, suite, etc.)
    */
-  email?: string | null;
+  line2?: string | null;
 
   /**
-   * The customer's full name
+   * Postal or ZIP code
    */
-  name?: string | null;
+  postal_code?: string | null;
 
   /**
-   * The customer's phone number
+   * State, province, or region
    */
-  phone?: string | null;
-}
-
-export namespace CustomerUpdateResponse {
-  /**
-   * The customer's billing address
-   */
-  export interface Address {
-    /**
-     * 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;
-  }
-}
-
-/**
- * A billable customer. Represents the entity in your app that will be
- * charged—typically a user, organization, or project.
- */
-export interface CustomerListResponse {
-  /**
-   * Unique identifier for the topic subscription
-   */
-  id: string;
-
-  /**
-   * Timestamp when the customer was created
-   */
-  created: string;
-
-  /**
-   * The customer's billing address
-   */
-  address?: CustomerListResponse.Address | 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;
-}
-
-export namespace CustomerListResponse {
-  /**
-   * The customer's billing address
-   */
-  export interface Address {
-    /**
-     * 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;
-  }
+  state?: string | null;
 }
 
 /**
@@ -318,7 +192,7 @@ export interface CustomerBillingPortalResponse {
  */
 export interface CustomerGetResponse {
   /**
-   * Unique identifier for the topic subscription
+   * Unique identifier for the customer
    */
   id: string;
 
@@ -330,7 +204,13 @@ export interface CustomerGetResponse {
   /**
    * The customer's billing address
    */
-  address?: CustomerGetResponse.Address | null;
+  address?: CustomerAddress | null;
+
+  /**
+   * Current customer balance in cents (negative = credit available to apply to
+   * future invoices)
+   */
+  balance?: number;
 
   /**
    * The customer's email address for receipts and notifications
@@ -364,47 +244,12 @@ export interface CustomerGetResponse {
 }
 
 export namespace CustomerGetResponse {
-  /**
-   * The customer's billing address
-   */
-  export interface Address {
-    /**
-     * 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;
-  }
-
   /**
    * An invoice for a customer
    */
   export interface Invoice {
     /**
-     * Unique identifier for the topic subscription
+     * Unique identifier for the invoice
      */
     id: string;
 
@@ -489,7 +334,7 @@ export namespace CustomerGetResponse {
    */
   export interface PaymentMethod {
     /**
-     * Unique identifier for the topic subscription
+     * Unique identifier for the payment method
      */
     id: string;
 
@@ -546,7 +391,7 @@ export namespace CustomerGetResponse {
    */
   export interface Subscription {
     /**
-     * Unique identifier for the topic subscription
+     * Unique identifier for the subscription
      */
     id: string;
 
@@ -615,7 +460,7 @@ export namespace CustomerGetResponse {
      */
     export interface Product {
       /**
-       * Unique identifier for the topic subscription
+       * Unique identifier for the product
        */
       id: string;
 
@@ -630,7 +475,7 @@ export namespace CustomerGetResponse {
      */
     export interface Variant {
       /**
-       * Unique identifier for the topic subscription
+       * Unique identifier for the variant
        */
       id: string;
 
@@ -652,7 +497,7 @@ export interface CustomerCreateParams {
   /**
    * The customer's billing address
    */
-  address?: CustomerCreateParams.Address;
+  address?: CustomerAddress;
 
   /**
    * The customer's email address for receipts and notifications
@@ -670,48 +515,11 @@ export interface CustomerCreateParams {
   phone?: string;
 }
 
-export namespace CustomerCreateParams {
-  /**
-   * The customer's billing address
-   */
-  export interface Address {
-    /**
-     * 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;
-  }
-}
-
 export interface CustomerUpdateParams {
   /**
    * The customer's billing address
    */
-  address?: CustomerUpdateParams.Address;
+  address?: CustomerAddress;
 
   /**
    * The customer's email address for receipts and notifications
@@ -729,43 +537,6 @@ export interface CustomerUpdateParams {
   phone?: string;
 }
 
-export namespace CustomerUpdateParams {
-  /**
-   * The customer's billing address
-   */
-  export interface Address {
-    /**
-     * 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;
-  }
-}
-
 export interface CustomerListParams extends CursorIDPageParams {
   /**
    * Filter by creation date. Accepts an object with gt, gte, lt, lte operators using
@@ -826,17 +597,20 @@ export interface CustomerBillingPortalParams {
   return_url?: string;
 }
 
+Customers.BalanceTransactions = BalanceTransactions;
+
 export declare namespace Customers {
   export {
-    type CustomerCreateResponse as CustomerCreateResponse,
-    type CustomerUpdateResponse as CustomerUpdateResponse,
-    type CustomerListResponse as CustomerListResponse,
+    type Customer as Customer,
+    type CustomerAddress as CustomerAddress,
     type CustomerBillingPortalResponse as CustomerBillingPortalResponse,
     type CustomerGetResponse as CustomerGetResponse,
-    type CustomerListResponsesCursorIDPage as CustomerListResponsesCursorIDPage,
+    type CustomersCursorIDPage as CustomersCursorIDPage,
     type CustomerCreateParams as CustomerCreateParams,
     type CustomerUpdateParams as CustomerUpdateParams,
     type CustomerListParams as CustomerListParams,
     type CustomerBillingPortalParams as CustomerBillingPortalParams,
   };
+
+  export { BalanceTransactions as BalanceTransactions };
 }

package/src/resources/commerce/customers/index.ts

@@ -0,0 +1,15 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { BalanceTransactions } from './balance-transactions';
+export {
+  Customers,
+  type Customer,
+  type CustomerAddress,
+  type CustomerBillingPortalResponse,
+  type CustomerGetResponse,
+  type CustomerCreateParams,
+  type CustomerUpdateParams,
+  type CustomerListParams,
+  type CustomerBillingPortalParams,
+  type CustomersCursorIDPage,
+} from './customers';

package/src/resources/{beta.ts → commerce/customers.ts}

@@ -1,3 +1,3 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export * from './beta/index';
+export * from './customers/index';