@stigg/typescript 0.1.0-alpha.3 → 0.1.0-alpha.7

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

@@ -3,8 +3,14 @@
 import { APIResource } from '../../../core/resource';
 import * as PaymentMethodAPI from './payment-method';
 import { PaymentMethod, PaymentMethodAttachParams } from './payment-method';
-import * as UsageAPI from './usage';
-import { Usage } from './usage';
+import * as PromotionalEntitlementsAPI from './promotional-entitlements';
+import {
+  PromotionalEntitlementGrantParams,
+  PromotionalEntitlementGrantResponse,
+  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 +18,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);
 
   /**
-   * Provision 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 a 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 +51,46 @@ export class Customers extends APIResource {
   }
 
   /**
-   * Archive 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);
   }
 
   /**
-   * Unarchive 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 });
+  }
+
+  /**
+   * Get a list of customerresources
+   */
+  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,6 +99,8 @@ export class Customers extends APIResource {
 
 export type CustomerListResponsesMyCursorIDPage = MyCursorIDPage<CustomerListResponse>;
 
+export type CustomerListResourcesResponsesMyCursorIDPage = MyCursorIDPage<CustomerListResourcesResponse>;
+
 /**
  * Response object
  */
@@ -311,21 +347,53 @@ 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 {
+  /**
+   * Customer level coupon
+   */
+  couponId?: string | null;
 
   /**
    * The email of the customer
@@ -335,7 +403,7 @@ export interface CustomerCreateParams {
   /**
    * List of integrations
    */
-  integrations?: Array<CustomerCreateParams.Integration>;
+  integrations?: Array<CustomerUpdateParams.Integration>;
 
   /**
    * Additional metadata
@@ -348,74 +416,141 @@ 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 {
+  export interface Integration {
     /**
-     * The default payment method id
+     * Integration details
      */
-    billingId: string | null;
+    id: string;
 
     /**
-     * The expiration month of the default payment method
+     * Synced entity id
      */
-    cardExpiryMonth: number | null;
+    syncedEntityId: string | null;
 
     /**
-     * The expiration year of the default payment method
+     * The vendor identifier of integration
      */
-    cardExpiryYear: number | null;
+    vendorIdentifier:
+      | 'AUTH0'
+      | 'ZUORA'
+      | 'STRIPE'
+      | 'HUBSPOT'
+      | 'AWS_MARKETPLACE'
+      | 'SNOWFLAKE'
+      | 'SALESFORCE'
+      | 'BIG_QUERY'
+      | 'OPEN_FGA'
+      | 'APP_STORE';
+  }
+}
 
+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 {
     /**
-     * The last 4 digits of the default payment method
+     * Greater than the specified createdAt value
      */
-    cardLast4Digits: string | null;
+    gt?: string;
 
     /**
-     * The default payment method type
+     * Greater than or equal to the specified createdAt value
      */
-    type: 'CARD' | 'BANK' | 'CASH_APP';
+    gte?: string;
+
+    /**
+     * Less than the specified createdAt value
+     */
+    lt?: string;
+
+    /**
+     * Less than or equal to the specified createdAt value
+     */
+    lte?: string;
   }
+}
 
+export interface CustomerImportParams {
   /**
-   * External billing or CRM integration link
+   * List of customer objects to import
    */
-  export interface Integration {
+  customers: Array<CustomerImportParams.Customer>;
+}
+
+export namespace CustomerImportParams {
+  export interface Customer {
     /**
-     * Integration details
+     * Customer slug
      */
     id: string;
 
     /**
-     * Synced entity id
+     * The email of the customer
      */
-    syncedEntityId: string | null;
+    email: string | null;
 
     /**
-     * The vendor identifier of integration
+     * The name of the customer
      */
-    vendorIdentifier:
-      | 'AUTH0'
-      | 'ZUORA'
-      | 'STRIPE'
-      | 'HUBSPOT'
-      | 'AWS_MARKETPLACE'
-      | 'SNOWFLAKE'
-      | 'SALESFORCE'
-      | 'BIG_QUERY'
-      | 'OPEN_FGA'
-      | 'APP_STORE';
+    name: string | null;
+
+    /**
+     * Additional metadata
+     */
+    metadata?: { [key: string]: string };
+
+    /**
+     * Billing provider payment method id
+     */
+    paymentMethodId?: string;
+
+    /**
+     * Timestamp of when the record was last updated
+     */
+    updatedAt?: string;
   }
 }
 
-export interface CustomerUpdateParams {
+export interface CustomerListResourcesParams extends MyCursorIDPageParams {}
+
+export interface CustomerProvisionParams {
+  /**
+   * Customer slug
+   */
+  id: string;
+
   /**
    * Customer level coupon
    */
   couponId?: string | null;
 
+  /**
+   * The default payment method details
+   */
+  defaultPaymentMethod?: CustomerProvisionParams.DefaultPaymentMethod | null;
+
   /**
    * The email of the customer
    */
@@ -424,7 +559,7 @@ export interface CustomerUpdateParams {
   /**
    * List of integrations
    */
-  integrations?: Array<CustomerUpdateParams.Integration>;
+  integrations?: Array<CustomerProvisionParams.Integration>;
 
   /**
    * Additional metadata
@@ -437,7 +572,37 @@ 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
    */
@@ -469,22 +634,31 @@ 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 };
+  export {
+    PromotionalEntitlements as PromotionalEntitlements,
+    type PromotionalEntitlementGrantResponse as PromotionalEntitlementGrantResponse,
+    type PromotionalEntitlementRevokeResponse as PromotionalEntitlementRevokeResponse,
+    type PromotionalEntitlementGrantParams as PromotionalEntitlementGrantParams,
+    type PromotionalEntitlementRevokeParams as PromotionalEntitlementRevokeParams,
+  };
 }

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

@@ -4,10 +4,21 @@ 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 } from './usage';
+export {
+  PromotionalEntitlements,
+  type PromotionalEntitlementGrantResponse,
+  type PromotionalEntitlementRevokeResponse,
+  type PromotionalEntitlementGrantParams,
+  type PromotionalEntitlementRevokeParams,
+} from './promotional-entitlements';

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

@@ -8,7 +8,8 @@ import { path } from '../../../internal/utils/path';
 
 export class PaymentMethod extends APIResource {
   /**
-   * Attach payment method
+   * Attaches a payment method to a customer for billing. Required for paid
+   * subscriptions when integrated with a billing provider.
    */
   attach(
     id: string,
@@ -19,7 +20,8 @@ export class PaymentMethod extends APIResource {
   }
 
   /**
-   * Detach payment method
+   * 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);