@usehercules/sdk 1.7.0 → 1.8.0

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

@@ -0,0 +1,532 @@
+// 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<CustomerCreateResponse> {
+    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.
+   */
+  update(
+    customerID: string,
+    body: CustomerUpdateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<CustomerUpdateResponse> {
+    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.
+   */
+  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]),
+    });
+  }
+
+  /**
+   * 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/commerce/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<CustomerGetResponse> {
+    return this._client.get(path`/v1/commerce/customers/${customerID}`, options);
+  }
+}
+
+export type CustomerListResponsesCursorIDPage = CursorIDPage<CustomerListResponse>;
+
+/**
+ * A billable customer. Represents the entity in your app that will be
+ * charged—typically a user, organization, or project.
+ */
+export interface CustomerCreateResponse {
+  /**
+   * Unique identifier for the topic subscription
+   */
+  id: string;
+
+  /**
+   * Timestamp when the customer was created
+   */
+  created: string;
+
+  /**
+   * The customer's billing address
+   */
+  address?: CustomerCreateResponse.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 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.
+ */
+export interface CustomerUpdateResponse {
+  /**
+   * Unique identifier for the topic subscription
+   */
+  id: string;
+
+  /**
+   * Timestamp when the customer was created
+   */
+  created: string;
+
+  /**
+   * The customer's billing address
+   */
+  address?: CustomerUpdateResponse.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 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;
+  }
+}
+
+/**
+ * Response containing the billing portal URL
+ */
+export interface CustomerBillingPortalResponse {
+  /**
+   * URL to redirect the customer to for the billing portal
+   */
+  url: string;
+}
+
+/**
+ * A billable customer. Represents the entity in your app that will be
+ * charged—typically a user, organization, or project.
+ */
+export interface CustomerGetResponse {
+  /**
+   * Unique identifier for the topic subscription
+   */
+  id: string;
+
+  /**
+   * Timestamp when the customer was created
+   */
+  created: string;
+
+  /**
+   * The customer's billing address
+   */
+  address?: CustomerGetResponse.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 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;
+  }
+}
+
+export interface CustomerCreateParams {
+  /**
+   * Optional custom ID for the customer. If not provided, one will be generated.
+   */
+  id?: string;
+
+  /**
+   * The customer's billing address
+   */
+  address?: CustomerCreateParams.Address;
+
+  /**
+   * 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 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;
+
+  /**
+   * 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 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 {}
+
+export interface CustomerBillingPortalParams {
+  /**
+   * URL to redirect the customer to after they exit the billing portal
+   */
+  return_url?: string;
+}
+
+export declare namespace Customers {
+  export {
+    type CustomerCreateResponse as CustomerCreateResponse,
+    type CustomerUpdateResponse as CustomerUpdateResponse,
+    type CustomerListResponse as CustomerListResponse,
+    type CustomerBillingPortalResponse as CustomerBillingPortalResponse,
+    type CustomerGetResponse as CustomerGetResponse,
+    type CustomerListResponsesCursorIDPage as CustomerListResponsesCursorIDPage,
+    type CustomerCreateParams as CustomerCreateParams,
+    type CustomerUpdateParams as CustomerUpdateParams,
+    type CustomerListParams as CustomerListParams,
+    type CustomerBillingPortalParams as CustomerBillingPortalParams,
+  };
+}

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

@@ -0,0 +1,47 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Commerce,
+  type CommerceCancelResponse,
+  type CommerceCheckResponse,
+  type CommerceCheckoutResponse,
+  type CommerceCancelParams,
+  type CommerceCheckParams,
+  type CommerceCheckoutParams,
+} from './commerce';
+export {
+  Coupons,
+  type CouponCreateResponse,
+  type CouponUpdateResponse,
+  type CouponListResponse,
+  type CouponGetResponse,
+  type CouponCreateParams,
+  type CouponUpdateParams,
+  type CouponListParams,
+  type CouponListResponsesCursorIDPage,
+} from './coupons';
+export {
+  Customers,
+  type CustomerCreateResponse,
+  type CustomerUpdateResponse,
+  type CustomerListResponse,
+  type CustomerBillingPortalResponse,
+  type CustomerGetResponse,
+  type CustomerCreateParams,
+  type CustomerUpdateParams,
+  type CustomerListParams,
+  type CustomerBillingPortalParams,
+  type CustomerListResponsesCursorIDPage,
+} from './customers';
+export {
+  Products,
+  type ProductCreateResponse,
+  type ProductUpdateResponse,
+  type ProductListResponse,
+  type ProductArchiveResponse,
+  type ProductGetResponse,
+  type ProductCreateParams,
+  type ProductUpdateParams,
+  type ProductListParams,
+  type ProductListResponsesCursorIDPage,
+} from './products/index';

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

@@ -0,0 +1,37 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Products,
+  type ProductCreateResponse,
+  type ProductUpdateResponse,
+  type ProductListResponse,
+  type ProductArchiveResponse,
+  type ProductGetResponse,
+  type ProductCreateParams,
+  type ProductUpdateParams,
+  type ProductListParams,
+  type ProductListResponsesCursorIDPage,
+} from './products';
+export {
+  Resources,
+  type ResourceListResponse,
+  type ResourceAttachResponse,
+  type ResourceListParams,
+  type ResourceAttachParams,
+  type ResourceRemoveParams,
+  type ResourceListResponsesCursorIDPage,
+} from './resources';
+export {
+  Variants,
+  type VariantCreateResponse,
+  type VariantUpdateResponse,
+  type VariantListResponse,
+  type VariantArchiveResponse,
+  type VariantGetResponse,
+  type VariantCreateParams,
+  type VariantUpdateParams,
+  type VariantListParams,
+  type VariantArchiveParams,
+  type VariantGetParams,
+  type VariantListResponsesCursorIDPage,
+} from './variants';