// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as MiscAPI from '../misc';
import * as PaymentsAPI from '../payments';
import * as CustomerPortalAPI from './customer-portal';
import { CustomerPortal, CustomerPortalCreateParams } from './customer-portal';
import * as EntitlementsAPI from '../entitlements/entitlements';
import * as GrantsAPI from '../entitlements/grants';
import { EntitlementGrantsDefaultPageNumberPagination } from '../entitlements/grants';
import * as WalletsAPI from './wallets/wallets';
import { CustomerWallet, WalletListResponse, Wallets } from './wallets/wallets';
import { APIPromise } from '../../core/api-promise';
import {
  DefaultPageNumberPagination,
  type DefaultPageNumberPaginationParams,
  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 {
  customerPortal: CustomerPortalAPI.CustomerPortal = new CustomerPortalAPI.CustomerPortal(this._client);
  wallets: WalletsAPI.Wallets = new WalletsAPI.Wallets(this._client);

  /**
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const customer of client.customers.list()) {
   *   // ...
   * }
   * ```
   */
  list(
    query: CustomerListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<CustomersDefaultPageNumberPagination, Customer> {
    return this._client.getAPIList('/customers', DefaultPageNumberPagination<Customer>, {
      query,
      ...options,
    });
  }

  /**
   * @example
   * ```ts
   * const customer = await client.customers.retrieve(
   *   'cus_TV52uJWWXt2yIoBBxpjaa',
   * );
   * ```
   */
  retrieve(customerID: string, options?: RequestOptions): APIPromise<Customer> {
    return this._client.get(path`/customers/${customerID}`, options);
  }

  /**
   * @example
   * ```ts
   * const customer = await client.customers.create({
   *   email: 'email',
   *   name: 'name',
   * });
   * ```
   */
  create(body: CustomerCreateParams, options?: RequestOptions): APIPromise<Customer> {
    return this._client.post('/customers', { body, ...options });
  }

  /**
   * @example
   * ```ts
   * const customer = await client.customers.update(
   *   'cus_TV52uJWWXt2yIoBBxpjaa',
   * );
   * ```
   */
  update(customerID: string, body: CustomerUpdateParams, options?: RequestOptions): APIPromise<Customer> {
    return this._client.patch(path`/customers/${customerID}`, { body, ...options });
  }

  /**
   * @example
   * ```ts
   * const response =
   *   await client.customers.retrievePaymentMethods(
   *     'cus_TV52uJWWXt2yIoBBxpjaa',
   *   );
   * ```
   */
  retrievePaymentMethods(
    customerID: string,
    options?: RequestOptions,
  ): APIPromise<CustomerRetrievePaymentMethodsResponse> {
    return this._client.get(path`/customers/${customerID}/payment-methods`, options);
  }

  /**
   * List all credit entitlements for a customer with their current balances
   *
   * @example
   * ```ts
   * const response =
   *   await client.customers.listCreditEntitlements(
   *     'cus_TV52uJWWXt2yIoBBxpjaa',
   *   );
   * ```
   */
  listCreditEntitlements(
    customerID: string,
    options?: RequestOptions,
  ): APIPromise<CustomerListCreditEntitlementsResponse> {
    return this._client.get(path`/customers/${customerID}/credit-entitlements`, options);
  }

  /**
   * @example
   * ```ts
   * await client.customers.deletePaymentMethod(
   *   'payment_method_id',
   *   { customer_id: 'cus_TV52uJWWXt2yIoBBxpjaa' },
   * );
   * ```
   */
  deletePaymentMethod(
    paymentMethodID: string,
    params: CustomerDeletePaymentMethodParams,
    options?: RequestOptions,
  ): APIPromise<void> {
    const { customer_id } = params;
    return this._client.delete(path`/customers/${customer_id}/payment-methods/${paymentMethodID}`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }

  /**
   * List all entitlement grants delivered (or in flight) to a customer.
   *
   * @example
   * ```ts
   * const response = await client.customers.listEntitlements(
   *   'cus_TV52uJWWXt2yIoBBxpjaa',
   * );
   * ```
   */
  listEntitlements(
    customerID: string,
    options?: RequestOptions,
  ): APIPromise<CustomerListEntitlementsResponse> {
    return this._client.get(path`/customers/${customerID}/entitlements`, options);
  }

  /**
   * List all of a customer's entitlement grants across every entitlement. One row
   * per grant.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const entitlementGrant of client.customers.listEntitlementGrants(
   *   'cus_TV52uJWWXt2yIoBBxpjaa',
   * )) {
   *   // ...
   * }
   * ```
   */
  listEntitlementGrants(
    customerID: string,
    query: CustomerListEntitlementGrantsParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<EntitlementGrantsDefaultPageNumberPagination, GrantsAPI.EntitlementGrant> {
    return this._client.getAPIList(
      path`/customers/${customerID}/entitlement-grants`,
      DefaultPageNumberPagination<GrantsAPI.EntitlementGrant>,
      { query, ...options },
    );
  }
}

export type CustomersDefaultPageNumberPagination = DefaultPageNumberPagination<Customer>;

export interface Customer {
  business_id: string;

  created_at: string;

  customer_id: string;

  email: string;

  name: string;

  /**
   * Additional metadata for the customer
   */
  metadata?: MiscAPI.Metadata;

  phone_number?: string | null;
}

export interface CustomerPortalSession {
  link: string;
}

export interface CustomerListCreditEntitlementsResponse {
  items: Array<CustomerListCreditEntitlementsResponse.Item>;
}

export namespace CustomerListCreditEntitlementsResponse {
  /**
   * A credit entitlement with the customer's current balance
   */
  export interface Item {
    /**
     * Customer's current remaining credit balance
     */
    balance: string;

    /**
     * Credit entitlement ID
     */
    credit_entitlement_id: string;

    /**
     * Name of the credit entitlement
     */
    name: string;

    /**
     * Customer's current overage balance
     */
    overage: string;

    /**
     * Unit label (e.g. "API Calls", "Tokens")
     */
    unit: string;

    /**
     * Description of the credit entitlement
     */
    description?: string | null;
  }
}

export interface CustomerListEntitlementsResponse {
  items: Array<CustomerListEntitlementsResponse.Item>;
}

export namespace CustomerListEntitlementsResponse {
  export interface Item {
    created_at: string;

    /**
     * The entitlement this grant belongs to.
     */
    entitlement_id: string;

    entitlement_name: string;

    /**
     * Grant id (the per-customer row in `entitlement_grants`).
     */
    grant_id: string;

    integration_type: EntitlementsAPI.EntitlementIntegrationType;

    status: 'pending' | 'delivered' | 'failed' | 'revoked';

    updated_at: string;

    delivered_at?: string | null;

    entitlement_description?: string | null;

    revoked_at?: string | null;
  }
}

export interface CustomerRetrievePaymentMethodsResponse {
  items: Array<CustomerRetrievePaymentMethodsResponse.Item>;
}

export namespace CustomerRetrievePaymentMethodsResponse {
  export interface Item {
    payment_method:
      | 'card'
      | 'card_redirect'
      | 'pay_later'
      | 'wallet'
      | 'bank_redirect'
      | 'bank_transfer'
      | 'crypto'
      | 'bank_debit'
      | 'reward'
      | 'real_time_payment'
      | 'upi'
      | 'voucher'
      | 'gift_card'
      | 'open_banking'
      | 'mobile_payment';

    payment_method_id: string;

    card?: Item.Card | null;

    last_used_at?: string | null;

    /**
     * All supported payment method types.
     *
     * Used for disabled-payment-methods filtering and validation.
     */
    payment_method_type?: PaymentsAPI.PaymentMethodTypes | null;

    recurring_enabled?: boolean | null;
  }

  export namespace Item {
    export interface Card {
      card_holder_name?: string | null;

      /**
       * ISO country code alpha2 variant
       */
      card_issuing_country?: MiscAPI.CountryCode | null;

      card_network?: string | null;

      card_type?: string | null;

      expiry_month?: string | null;

      expiry_year?: string | null;

      last4_digits?: string | null;
    }
  }
}

export interface CustomerListParams extends DefaultPageNumberPaginationParams {
  /**
   * Filter customers created on or after this timestamp
   */
  created_at_gte?: string;

  /**
   * Filter customers created on or before this timestamp
   */
  created_at_lte?: string;

  /**
   * Filter by customer email
   */
  email?: string;

  /**
   * Filter by customer name (partial match, case-insensitive)
   */
  name?: string;
}

export interface CustomerCreateParams {
  email: string;

  name: string;

  /**
   * Additional metadata for the customer
   */
  metadata?: MiscAPI.Metadata;

  phone_number?: string | null;
}

export interface CustomerUpdateParams {
  email?: string | null;

  /**
   * Additional metadata for the customer
   */
  metadata?: MiscAPI.Metadata | null;

  name?: string | null;

  phone_number?: string | null;
}

export interface CustomerDeletePaymentMethodParams {
  /**
   * Customer Id
   */
  customer_id: string;
}

export interface CustomerListEntitlementGrantsParams extends DefaultPageNumberPaginationParams {
  /**
   * Filter by integration type (e.g. `feature_flag`)
   */
  integration_type?:
    | 'discord'
    | 'telegram'
    | 'github'
    | 'figma'
    | 'framer'
    | 'notion'
    | 'digital_files'
    | 'license_key'
    | 'feature_flag';

  /**
   * Filter by grant status
   */
  status?: 'Pending' | 'Delivered' | 'Failed' | 'Revoked';
}

Customers.CustomerPortal = CustomerPortal;
Customers.Wallets = Wallets;

export declare namespace Customers {
  export {
    type Customer as Customer,
    type CustomerPortalSession as CustomerPortalSession,
    type CustomerListCreditEntitlementsResponse as CustomerListCreditEntitlementsResponse,
    type CustomerListEntitlementsResponse as CustomerListEntitlementsResponse,
    type CustomerRetrievePaymentMethodsResponse as CustomerRetrievePaymentMethodsResponse,
    type CustomersDefaultPageNumberPagination as CustomersDefaultPageNumberPagination,
    type CustomerListParams as CustomerListParams,
    type CustomerCreateParams as CustomerCreateParams,
    type CustomerUpdateParams as CustomerUpdateParams,
    type CustomerDeletePaymentMethodParams as CustomerDeletePaymentMethodParams,
    type CustomerListEntitlementGrantsParams as CustomerListEntitlementGrantsParams,
  };

  export { CustomerPortal as CustomerPortal, type CustomerPortalCreateParams as CustomerPortalCreateParams };

  export {
    Wallets as Wallets,
    type CustomerWallet as CustomerWallet,
    type WalletListResponse as WalletListResponse,
  };
}

export { type EntitlementGrantsDefaultPageNumberPagination };