@stigg/typescript 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/resources/v1/customers/customers.ts

@@ -3,8 +3,17 @@
 import { APIResource } from '../../../core/resource';
 import * as PaymentMethodAPI from './payment-method';
 import { PaymentMethod, PaymentMethodAttachParams } from './payment-method';
-import * as UsageAPI from './usage';
-import { Usage, UsageRetrieveParams, UsageRetrieveResponse } from './usage';
+import * as PromotionalEntitlementsAPI from './promotional-entitlements';
+import {
+  PromotionalEntitlementCreateParams,
+  PromotionalEntitlementCreateResponse,
+  PromotionalEntitlementListParams,
+  PromotionalEntitlementListResponse,
+  PromotionalEntitlementListResponsesMyCursorIDPage,
+  PromotionalEntitlementRevokeParams,
+  PromotionalEntitlementRevokeResponse,
+  PromotionalEntitlements,
+} from './promotional-entitlements';
 import { APIPromise } from '../../../core/api-promise';
 import { MyCursorIDPage, type MyCursorIDPageParams, PagePromise } from '../../../core/pagination';
 import { RequestOptions } from '../../../internal/request-options';
@@ -12,31 +21,27 @@ import { path } from '../../../internal/utils/path';
 
 export class Customers extends APIResource {
   paymentMethod: PaymentMethodAPI.PaymentMethod = new PaymentMethodAPI.PaymentMethod(this._client);
-  usage: UsageAPI.Usage = new UsageAPI.Usage(this._client);
+  promotionalEntitlements: PromotionalEntitlementsAPI.PromotionalEntitlements =
+    new PromotionalEntitlementsAPI.PromotionalEntitlements(this._client);
 
   /**
-   * Create a new Customer
-   */
-  create(body: CustomerCreateParams, options?: RequestOptions): APIPromise<CustomerResponse> {
-    return this._client.post('/api/v1/customers', { body, ...options });
-  }
-
-  /**
-   * Get a single Customer by id
+   * Retrieves a customer by their unique identifier, including billing information
+   * and subscription status.
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.get(path`/api/v1/customers/${id}`, options);
   }
 
   /**
-   * Update an existing Customer
+   * Updates an existing customer's properties such as name, email, and billing
+   * information.
    */
   update(id: string, body: CustomerUpdateParams, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.patch(path`/api/v1/customers/${id}`, { body, ...options });
   }
 
   /**
-   * Get a list of Customers
+   * Retrieves a paginated list of customers in the environment.
    */
   list(
     query: CustomerListParams | null | undefined = {},
@@ -49,14 +54,46 @@ export class Customers extends APIResource {
   }
 
   /**
-   * Perform archive on a Customer
+   * Archives a customer, preventing new subscriptions. Optionally cancels existing
+   * subscriptions.
    */
   archive(id: string, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.post(path`/api/v1/customers/${id}/archive`, options);
   }
 
   /**
-   * Perform unarchive on a Customer
+   * Imports multiple customers in bulk. Used for migrating customer data from
+   * external systems.
+   */
+  import(body: CustomerImportParams, options?: RequestOptions): APIPromise<CustomerImportResponse> {
+    return this._client.post('/api/v1/customers/import', { body, ...options });
+  }
+
+  /**
+   * Retrieves a paginated list of resources within the same customer.
+   */
+  listResources(
+    id: string,
+    query: CustomerListResourcesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CustomerListResourcesResponsesMyCursorIDPage, CustomerListResourcesResponse> {
+    return this._client.getAPIList(
+      path`/api/v1/customers/${id}/resources`,
+      MyCursorIDPage<CustomerListResourcesResponse>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Creates a new customer and optionally provisions an initial subscription in a
+   * single operation.
+   */
+  provision(body: CustomerProvisionParams, options?: RequestOptions): APIPromise<CustomerResponse> {
+    return this._client.post('/api/v1/customers', { body, ...options });
+  }
+
+  /**
+   * Restores an archived customer, allowing them to create new subscriptions again.
    */
   unarchive(id: string, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.post(path`/api/v1/customers/${id}/unarchive`, options);
@@ -65,11 +102,22 @@ export class Customers extends APIResource {
 
 export type CustomerListResponsesMyCursorIDPage = MyCursorIDPage<CustomerListResponse>;
 
+export type CustomerListResourcesResponsesMyCursorIDPage = MyCursorIDPage<CustomerListResourcesResponse>;
+
+/**
+ * Response object
+ */
 export interface CustomerResponse {
+  /**
+   * A customer can be either an organization or an individual
+   */
   data: CustomerResponse.Data;
 }
 
 export namespace CustomerResponse {
+  /**
+   * A customer can be either an organization or an individual
+   */
   export interface Data {
     /**
      * Customer slug
@@ -91,6 +139,11 @@ export namespace CustomerResponse {
      */
     updatedAt: string;
 
+    /**
+     * The unique identifier for the entity in the billing provider
+     */
+    billingId?: string | null;
+
     /**
      * Customer level coupon
      */
@@ -153,6 +206,9 @@ export namespace CustomerResponse {
       type: 'CARD' | 'BANK' | 'CASH_APP';
     }
 
+    /**
+     * External billing or CRM integration link
+     */
     export interface Integration {
       /**
        * Integration details
@@ -182,6 +238,9 @@ export namespace CustomerResponse {
   }
 }
 
+/**
+ * A customer can be either an organization or an individual
+ */
 export interface CustomerListResponse {
   /**
    * Customer slug
@@ -203,6 +262,11 @@ export interface CustomerListResponse {
    */
   updatedAt: string;
 
+  /**
+   * The unique identifier for the entity in the billing provider
+   */
+  billingId?: string | null;
+
   /**
    * Customer level coupon
    */
@@ -265,6 +329,9 @@ export namespace CustomerListResponse {
     type: 'CARD' | 'BANK' | 'CASH_APP';
   }
 
+  /**
+   * External billing or CRM integration link
+   */
   export interface Integration {
     /**
      * Integration details
@@ -293,21 +360,58 @@ export namespace CustomerListResponse {
   }
 }
 
-export interface CustomerCreateParams {
+/**
+ * Response object
+ */
+export interface CustomerImportResponse {
   /**
-   * Customer slug
+   * List of newly created customer IDs from the import operation.
+   */
+  data: CustomerImportResponse.Data;
+}
+
+export namespace CustomerImportResponse {
+  /**
+   * List of newly created customer IDs from the import operation.
+   */
+  export interface Data {
+    /**
+     * Customer IDs created during import
+     */
+    newCustomers: Array<string>;
+  }
+}
+
+/**
+ * Resource object that belongs to a customer
+ */
+export interface CustomerListResourcesResponse {
+  /**
+   * Resource slug
    */
   id: string;
 
   /**
-   * Customer level coupon
+   * Timestamp of when the record was created
    */
-  couponId?: string | null;
+  createdAt: string;
 
   /**
-   * The default payment method details
+   * Timestamp of when the record was last updated
    */
-  defaultPaymentMethod?: CustomerCreateParams.DefaultPaymentMethod | null;
+  updatedAt: string;
+}
+
+export interface CustomerUpdateParams {
+  /**
+   * The unique identifier for the entity in the billing provider
+   */
+  billingId?: string | null;
+
+  /**
+   * Customer level coupon
+   */
+  couponId?: string | null;
 
   /**
    * The email of the customer
@@ -317,7 +421,7 @@ export interface CustomerCreateParams {
   /**
    * List of integrations
    */
-  integrations?: Array<CustomerCreateParams.Integration>;
+  integrations?: Array<CustomerUpdateParams.Integration>;
 
   /**
    * Additional metadata
@@ -330,37 +434,10 @@ export interface CustomerCreateParams {
   name?: string | null;
 }
 
-export namespace CustomerCreateParams {
+export namespace CustomerUpdateParams {
   /**
-   * The default payment method details
+   * External billing or CRM integration link
    */
-  export interface DefaultPaymentMethod {
-    /**
-     * The default payment method id
-     */
-    billingId: string | null;
-
-    /**
-     * The expiration month of the default payment method
-     */
-    cardExpiryMonth: number | null;
-
-    /**
-     * The expiration year of the default payment method
-     */
-    cardExpiryYear: number | null;
-
-    /**
-     * The last 4 digits of the default payment method
-     */
-    cardLast4Digits: string | null;
-
-    /**
-     * The default payment method type
-     */
-    type: 'CARD' | 'BANK' | 'CASH_APP';
-  }
-
   export interface Integration {
     /**
      * Integration details
@@ -389,12 +466,129 @@ export namespace CustomerCreateParams {
   }
 }
 
-export interface CustomerUpdateParams {
+export interface CustomerListParams extends MyCursorIDPageParams {
+  /**
+   * Filter by creation date using range operators: gt, gte, lt, lte
+   */
+  createdAt?: CustomerListParams.CreatedAt;
+
+  /**
+   * Filter by exact customer email address
+   */
+  email?: string;
+
+  /**
+   * Filter by exact customer name
+   */
+  name?: string;
+}
+
+export namespace CustomerListParams {
+  /**
+   * Filter by creation date using range operators: gt, gte, lt, lte
+   */
+  export interface CreatedAt {
+    /**
+     * Greater than the specified createdAt value
+     */
+    gt?: string;
+
+    /**
+     * Greater than or equal to the specified createdAt value
+     */
+    gte?: string;
+
+    /**
+     * Less than the specified createdAt value
+     */
+    lt?: string;
+
+    /**
+     * Less than or equal to the specified createdAt value
+     */
+    lte?: string;
+  }
+}
+
+export interface CustomerImportParams {
+  /**
+   * List of customer objects to import
+   */
+  customers: Array<CustomerImportParams.Customer>;
+
+  /**
+   * Integration details
+   */
+  integrationId?: string;
+}
+
+export namespace CustomerImportParams {
+  export interface Customer {
+    /**
+     * Customer slug
+     */
+    id: string;
+
+    /**
+     * The email of the customer
+     */
+    email: string | null;
+
+    /**
+     * The name of the customer
+     */
+    name: string | null;
+
+    /**
+     * Id in the billing provider
+     */
+    billingId?: string;
+
+    /**
+     * Additional metadata
+     */
+    metadata?: { [key: string]: string };
+
+    /**
+     * Billing provider payment method id
+     */
+    paymentMethodId?: string;
+
+    /**
+     * The unique identifier for the customer in Salesforce integration
+     */
+    salesforceId?: string;
+
+    /**
+     * Timestamp of when the record was last updated
+     */
+    updatedAt?: string;
+  }
+}
+
+export interface CustomerListResourcesParams extends MyCursorIDPageParams {}
+
+export interface CustomerProvisionParams {
+  /**
+   * Customer slug
+   */
+  id: string;
+
+  /**
+   * The unique identifier for the entity in the billing provider
+   */
+  billingId?: string | null;
+
   /**
    * Customer level coupon
    */
   couponId?: string | null;
 
+  /**
+   * The default payment method details
+   */
+  defaultPaymentMethod?: CustomerProvisionParams.DefaultPaymentMethod | null;
+
   /**
    * The email of the customer
    */
@@ -403,7 +597,7 @@ export interface CustomerUpdateParams {
   /**
    * List of integrations
    */
-  integrations?: Array<CustomerUpdateParams.Integration>;
+  integrations?: Array<CustomerProvisionParams.Integration>;
 
   /**
    * Additional metadata
@@ -416,7 +610,40 @@ export interface CustomerUpdateParams {
   name?: string | null;
 }
 
-export namespace CustomerUpdateParams {
+export namespace CustomerProvisionParams {
+  /**
+   * The default payment method details
+   */
+  export interface DefaultPaymentMethod {
+    /**
+     * The default payment method id
+     */
+    billingId: string | null;
+
+    /**
+     * The expiration month of the default payment method
+     */
+    cardExpiryMonth: number | null;
+
+    /**
+     * The expiration year of the default payment method
+     */
+    cardExpiryYear: number | null;
+
+    /**
+     * The last 4 digits of the default payment method
+     */
+    cardLast4Digits: string | null;
+
+    /**
+     * The default payment method type
+     */
+    type: 'CARD' | 'BANK' | 'CASH_APP';
+  }
+
+  /**
+   * External billing or CRM integration link
+   */
   export interface Integration {
     /**
      * Integration details
@@ -445,26 +672,34 @@ export namespace CustomerUpdateParams {
   }
 }
 
-export interface CustomerListParams extends MyCursorIDPageParams {}
-
 Customers.PaymentMethod = PaymentMethod;
-Customers.Usage = Usage;
+Customers.PromotionalEntitlements = PromotionalEntitlements;
 
 export declare namespace Customers {
   export {
     type CustomerResponse as CustomerResponse,
     type CustomerListResponse as CustomerListResponse,
+    type CustomerImportResponse as CustomerImportResponse,
+    type CustomerListResourcesResponse as CustomerListResourcesResponse,
     type CustomerListResponsesMyCursorIDPage as CustomerListResponsesMyCursorIDPage,
-    type CustomerCreateParams as CustomerCreateParams,
+    type CustomerListResourcesResponsesMyCursorIDPage as CustomerListResourcesResponsesMyCursorIDPage,
     type CustomerUpdateParams as CustomerUpdateParams,
     type CustomerListParams as CustomerListParams,
+    type CustomerImportParams as CustomerImportParams,
+    type CustomerListResourcesParams as CustomerListResourcesParams,
+    type CustomerProvisionParams as CustomerProvisionParams,
   };
 
   export { PaymentMethod as PaymentMethod, type PaymentMethodAttachParams as PaymentMethodAttachParams };
 
   export {
-    Usage as Usage,
-    type UsageRetrieveResponse as UsageRetrieveResponse,
-    type UsageRetrieveParams as UsageRetrieveParams,
+    PromotionalEntitlements as PromotionalEntitlements,
+    type PromotionalEntitlementCreateResponse as PromotionalEntitlementCreateResponse,
+    type PromotionalEntitlementListResponse as PromotionalEntitlementListResponse,
+    type PromotionalEntitlementRevokeResponse as PromotionalEntitlementRevokeResponse,
+    type PromotionalEntitlementListResponsesMyCursorIDPage as PromotionalEntitlementListResponsesMyCursorIDPage,
+    type PromotionalEntitlementCreateParams as PromotionalEntitlementCreateParams,
+    type PromotionalEntitlementListParams as PromotionalEntitlementListParams,
+    type PromotionalEntitlementRevokeParams as PromotionalEntitlementRevokeParams,
   };
 }

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

@@ -4,10 +4,24 @@ export {
   Customers,
   type CustomerResponse,
   type CustomerListResponse,
-  type CustomerCreateParams,
+  type CustomerImportResponse,
+  type CustomerListResourcesResponse,
   type CustomerUpdateParams,
   type CustomerListParams,
+  type CustomerImportParams,
+  type CustomerListResourcesParams,
+  type CustomerProvisionParams,
   type CustomerListResponsesMyCursorIDPage,
+  type CustomerListResourcesResponsesMyCursorIDPage,
 } from './customers';
 export { PaymentMethod, type PaymentMethodAttachParams } from './payment-method';
-export { Usage, type UsageRetrieveResponse, type UsageRetrieveParams } from './usage';
+export {
+  PromotionalEntitlements,
+  type PromotionalEntitlementCreateResponse,
+  type PromotionalEntitlementListResponse,
+  type PromotionalEntitlementRevokeResponse,
+  type PromotionalEntitlementCreateParams,
+  type PromotionalEntitlementListParams,
+  type PromotionalEntitlementRevokeParams,
+  type PromotionalEntitlementListResponsesMyCursorIDPage,
+} from './promotional-entitlements';

package/src/resources/v1/customers/payment-method.ts

@@ -6,9 +6,13 @@ import { APIPromise } from '../../../core/api-promise';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
+/**
+ * Operations related to customers
+ */
 export class PaymentMethod extends APIResource {
   /**
-   * Perform payment-method attachment on a Customer
+   * Attaches a payment method to a customer for billing. Required for paid
+   * subscriptions when integrated with a billing provider.
    */
   attach(
     id: string,
@@ -19,7 +23,8 @@ export class PaymentMethod extends APIResource {
   }
 
   /**
-   * Perform payment-method detachment on a Customer
+   * Removes the payment method from a customer. Ensure active paid subscriptions
+   * have an alternative payment method.
    */
   detach(id: string, options?: RequestOptions): APIPromise<CustomersAPI.CustomerResponse> {
     return this._client.delete(path`/api/v1/customers/${id}/payment-method`, options);
@@ -52,6 +57,9 @@ export interface PaymentMethodAttachParams {
     | 'OPEN_FGA'
     | 'APP_STORE';
 
+  /**
+   * Customers selected currency
+   */
   billingCurrency?:
     | 'usd'
     | 'aed'