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

import { APIResource } from '../../core/resource';
import * as Shared from '../shared';
import { APIPromise } from '../../core/api-promise';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class Usage extends APIResource {
  /**
   * Returns usage and remaining credits for all licenses of a given type on a
   * subscription.
   *
   * Date range defaults to the current billing period if not specified.
   *
   * @example
   * ```ts
   * const response = await client.licenses.usage.getAllUsage({
   *   license_type_id: 'license_type_id',
   *   subscription_id: 'subscription_id',
   * });
   * ```
   */
  getAllUsage(query: UsageGetAllUsageParams, options?: RequestOptions): APIPromise<UsageGetAllUsageResponse> {
    return this._client.get('/licenses/usage', { query, ...options });
  }

  /**
   * Returns usage and remaining credits for a specific license over a date range.
   *
   * Resolves the license by ID regardless of whether it is currently active, unlike
   * the external-license-ID variant, which only resolves a currently active license.
   *
   * Date range defaults to the current billing period if not specified.
   *
   * @example
   * ```ts
   * const response = await client.licenses.usage.getUsage(
   *   'license_id',
   * );
   * ```
   */
  getUsage(
    licenseID: string,
    query: UsageGetUsageParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<UsageGetUsageResponse> {
    return this._client.get(path`/licenses/${licenseID}/usage`, { query, ...options });
  }
}

export interface UsageGetAllUsageResponse {
  data: Array<UsageGetAllUsageResponse.Data>;

  pagination_metadata: Shared.PaginationMetadata;
}

export namespace UsageGetAllUsageResponse {
  /**
   * The LicenseUsage resource represents usage and remaining credits for a license
   * over a date range.
   *
   * When grouped by 'day' only, license_id and external_license_id will be null as
   * the data is aggregated across all licenses.
   */
  export interface Data {
    /**
     * The total credits allocated to this license for the period.
     */
    allocated_credits: number;

    /**
     * The credits consumed by this license for the period.
     */
    consumed_credits: number;

    /**
     * The end date of the usage period.
     */
    end_date: string;

    /**
     * The unique identifier for the license type.
     */
    license_type_id: string;

    /**
     * The pricing unit for the credits (e.g., 'credits').
     */
    pricing_unit: string;

    /**
     * The remaining credits available for this license (allocated - consumed).
     */
    remaining_credits: number;

    /**
     * The start date of the usage period.
     */
    start_date: string;

    /**
     * The unique identifier for the subscription.
     */
    subscription_id: string;

    /**
     * Credits consumed while the license was active (eligible for individual
     * allocation deduction).
     */
    allocation_eligible_credits?: number | null;

    /**
     * The external identifier for the license. Null when grouped by day only.
     */
    external_license_id?: string | null;

    /**
     * The unique identifier for the license. Null when grouped by day only.
     */
    license_id?: string | null;

    /**
     * Credits consumed while the license was inactive (draws from shared pool, not
     * individual allocation).
     */
    shared_pool_credits?: number | null;
  }
}

export interface UsageGetUsageResponse {
  data: Array<UsageGetUsageResponse.Data>;

  pagination_metadata: Shared.PaginationMetadata;
}

export namespace UsageGetUsageResponse {
  /**
   * The LicenseUsage resource represents usage and remaining credits for a license
   * over a date range.
   *
   * When grouped by 'day' only, license_id and external_license_id will be null as
   * the data is aggregated across all licenses.
   */
  export interface Data {
    /**
     * The total credits allocated to this license for the period.
     */
    allocated_credits: number;

    /**
     * The credits consumed by this license for the period.
     */
    consumed_credits: number;

    /**
     * The end date of the usage period.
     */
    end_date: string;

    /**
     * The unique identifier for the license type.
     */
    license_type_id: string;

    /**
     * The pricing unit for the credits (e.g., 'credits').
     */
    pricing_unit: string;

    /**
     * The remaining credits available for this license (allocated - consumed).
     */
    remaining_credits: number;

    /**
     * The start date of the usage period.
     */
    start_date: string;

    /**
     * The unique identifier for the subscription.
     */
    subscription_id: string;

    /**
     * Credits consumed while the license was active (eligible for individual
     * allocation deduction).
     */
    allocation_eligible_credits?: number | null;

    /**
     * The external identifier for the license. Null when grouped by day only.
     */
    external_license_id?: string | null;

    /**
     * The unique identifier for the license. Null when grouped by day only.
     */
    license_id?: string | null;

    /**
     * Credits consumed while the license was inactive (draws from shared pool, not
     * individual allocation).
     */
    shared_pool_credits?: number | null;
  }
}

export interface UsageGetAllUsageParams {
  /**
   * The license type ID to filter licenses by.
   */
  license_type_id: string;

  /**
   * The subscription ID to get license usage for.
   */
  subscription_id: string;

  /**
   * Pagination cursor from a previous request.
   */
  cursor?: string | null;

  /**
   * End date for the usage period (YYYY-MM-DD). Defaults to end of current billing
   * period.
   */
  end_date?: string | null;

  /**
   * How to group the results. Valid values: 'license', 'day'. Can be combined (e.g.,
   * 'license,day').
   */
  group_by?: string | null;

  /**
   * Maximum number of rows in the response data (default 20, max 100).
   */
  limit?: number;

  /**
   * Start date for the usage period (YYYY-MM-DD). Defaults to start of current
   * billing period.
   */
  start_date?: string | null;
}

export interface UsageGetUsageParams {
  /**
   * Pagination cursor from a previous request.
   */
  cursor?: string | null;

  /**
   * End date for the usage period (YYYY-MM-DD). Defaults to end of current billing
   * period.
   */
  end_date?: string | null;

  /**
   * How to group the results. Valid values: 'license', 'day'. Can be combined (e.g.,
   * 'license,day').
   */
  group_by?: string | null;

  /**
   * Maximum number of rows in the response data (default 20, max 100).
   */
  limit?: number;

  /**
   * Start date for the usage period (YYYY-MM-DD). Defaults to start of current
   * billing period.
   */
  start_date?: string | null;
}

export declare namespace Usage {
  export {
    type UsageGetAllUsageResponse as UsageGetAllUsageResponse,
    type UsageGetUsageResponse as UsageGetUsageResponse,
    type UsageGetAllUsageParams as UsageGetAllUsageParams,
    type UsageGetUsageParams as UsageGetUsageParams,
  };
}