orb-billing 5.43.0 → 5.45.0

package/src/resources/license-types.ts

@@ -0,0 +1,163 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../resource';
+import { isRequestOptions } from '../core';
+import * as Core from '../core';
+import { Page, type PageParams } from '../pagination';
+
+/**
+ * The LicenseType resource represents a type of license that can be assigned to users.
+ * License types are used during billing by grouping metrics on the configured grouping key.
+ */
+export class LicenseTypes extends APIResource {
+  /**
+   * This endpoint is used to create a new license type.
+   *
+   * License types are used to group licenses and define billing behavior. Each
+   * license type has a name and a grouping key that determines how metrics are
+   * aggregated for billing purposes.
+   */
+  create(
+    body: LicenseTypeCreateParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<LicenseTypeCreateResponse> {
+    return this._client.post('/license_types', { body, ...options });
+  }
+
+  /**
+   * This endpoint returns a license type identified by its license_type_id.
+   *
+   * Use this endpoint to retrieve details about a specific license type, including
+   * its name and grouping key.
+   */
+  retrieve(
+    licenseTypeId: string,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<LicenseTypeRetrieveResponse> {
+    return this._client.get(`/license_types/${licenseTypeId}`, options);
+  }
+
+  /**
+   * This endpoint returns a list of all license types configured for the account,
+   * ordered in ascending order by creation time.
+   *
+   * License types are used to group licenses and define billing behavior. Each
+   * license type has a name and a grouping key that determines how metrics are
+   * aggregated for billing purposes.
+   */
+  list(
+    query?: LicenseTypeListParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<LicenseTypeListResponsesPage, LicenseTypeListResponse>;
+  list(
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<LicenseTypeListResponsesPage, LicenseTypeListResponse>;
+  list(
+    query: LicenseTypeListParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<LicenseTypeListResponsesPage, LicenseTypeListResponse> {
+    if (isRequestOptions(query)) {
+      return this.list({}, query);
+    }
+    return this._client.getAPIList('/license_types', LicenseTypeListResponsesPage, { query, ...options });
+  }
+}
+
+export class LicenseTypeListResponsesPage extends Page<LicenseTypeListResponse> {}
+
+/**
+ * The LicenseType resource represents a type of license that can be assigned to
+ * users. License types are used during billing by grouping metrics on the
+ * configured grouping key.
+ */
+export interface LicenseTypeCreateResponse {
+  /**
+   * The Orb-assigned unique identifier for the license type.
+   */
+  id: string;
+
+  /**
+   * The key used for grouping licenses of this type. This is typically a user
+   * identifier field.
+   */
+  grouping_key: string;
+
+  /**
+   * The name of the license type.
+   */
+  name: string;
+}
+
+/**
+ * The LicenseType resource represents a type of license that can be assigned to
+ * users. License types are used during billing by grouping metrics on the
+ * configured grouping key.
+ */
+export interface LicenseTypeRetrieveResponse {
+  /**
+   * The Orb-assigned unique identifier for the license type.
+   */
+  id: string;
+
+  /**
+   * The key used for grouping licenses of this type. This is typically a user
+   * identifier field.
+   */
+  grouping_key: string;
+
+  /**
+   * The name of the license type.
+   */
+  name: string;
+}
+
+/**
+ * The LicenseType resource represents a type of license that can be assigned to
+ * users. License types are used during billing by grouping metrics on the
+ * configured grouping key.
+ */
+export interface LicenseTypeListResponse {
+  /**
+   * The Orb-assigned unique identifier for the license type.
+   */
+  id: string;
+
+  /**
+   * The key used for grouping licenses of this type. This is typically a user
+   * identifier field.
+   */
+  grouping_key: string;
+
+  /**
+   * The name of the license type.
+   */
+  name: string;
+}
+
+export interface LicenseTypeCreateParams {
+  /**
+   * The key used for grouping licenses of this type. This is typically a user
+   * identifier field.
+   */
+  grouping_key: string;
+
+  /**
+   * The name of the license type.
+   */
+  name: string;
+}
+
+export interface LicenseTypeListParams extends PageParams {}
+
+LicenseTypes.LicenseTypeListResponsesPage = LicenseTypeListResponsesPage;
+
+export declare namespace LicenseTypes {
+  export {
+    type LicenseTypeCreateResponse as LicenseTypeCreateResponse,
+    type LicenseTypeRetrieveResponse as LicenseTypeRetrieveResponse,
+    type LicenseTypeListResponse as LicenseTypeListResponse,
+    LicenseTypeListResponsesPage as LicenseTypeListResponsesPage,
+    type LicenseTypeCreateParams as LicenseTypeCreateParams,
+    type LicenseTypeListParams as LicenseTypeListParams,
+  };
+}

package/src/resources/licenses/external-licenses.ts

@@ -0,0 +1,147 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../resource';
+import * as Core from '../../core';
+import * as Shared from '../shared';
+
+export class ExternalLicenses extends APIResource {
+  /**
+   * Returns usage and remaining credits for a license identified by its external
+   * license ID.
+   *
+   * Date range defaults to the current billing period if not specified.
+   */
+  getUsage(
+    externalLicenseId: string,
+    query: ExternalLicenseGetUsageParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<ExternalLicenseGetUsageResponse> {
+    return this._client.get(`/licenses/external_licenses/${externalLicenseId}/usage`, { query, ...options });
+  }
+}
+
+export interface ExternalLicenseGetUsageResponse {
+  data: Array<ExternalLicenseGetUsageResponse.Data>;
+
+  pagination_metadata: Shared.PaginationMetadata;
+}
+
+export namespace ExternalLicenseGetUsageResponse {
+  /**
+   * 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 ExternalLicenseGetUsageParams {
+  /**
+   * 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?: Array<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 ExternalLicenses {
+  export {
+    type ExternalLicenseGetUsageResponse as ExternalLicenseGetUsageResponse,
+    type ExternalLicenseGetUsageParams as ExternalLicenseGetUsageParams,
+  };
+}

package/src/resources/licenses/index.ts

@@ -0,0 +1,27 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  ExternalLicenses,
+  type ExternalLicenseGetUsageResponse,
+  type ExternalLicenseGetUsageParams,
+} from './external-licenses';
+export {
+  LicenseListResponsesPage,
+  Licenses,
+  type LicenseCreateResponse,
+  type LicenseRetrieveResponse,
+  type LicenseListResponse,
+  type LicenseDeactivateResponse,
+  type LicenseRetrieveByExternalIDResponse,
+  type LicenseCreateParams,
+  type LicenseListParams,
+  type LicenseDeactivateParams,
+  type LicenseRetrieveByExternalIDParams,
+} from './licenses';
+export {
+  Usage,
+  type UsageGetAllUsageResponse,
+  type UsageGetUsageResponse,
+  type UsageGetAllUsageParams,
+  type UsageGetUsageParams,
+} from './usage';

package/src/resources/licenses/licenses.ts

@@ -0,0 +1,248 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../resource';
+import * as Core from '../../core';
+import * as ExternalLicensesAPI from './external-licenses';
+import {
+  ExternalLicenseGetUsageParams,
+  ExternalLicenseGetUsageResponse,
+  ExternalLicenses,
+} from './external-licenses';
+import * as UsageAPI from './usage';
+import {
+  Usage,
+  UsageGetAllUsageParams,
+  UsageGetAllUsageResponse,
+  UsageGetUsageParams,
+  UsageGetUsageResponse,
+} from './usage';
+import { Page, type PageParams } from '../../pagination';
+
+export class Licenses extends APIResource {
+  externalLicenses: ExternalLicensesAPI.ExternalLicenses = new ExternalLicensesAPI.ExternalLicenses(
+    this._client,
+  );
+  usage: UsageAPI.Usage = new UsageAPI.Usage(this._client);
+
+  /**
+   * This endpoint is used to create a new license for a user.
+   *
+   * If a start date is provided, the license will be activated at the **start** of
+   * the specified date in the customer's timezone. Otherwise, the activation time
+   * will default to the **start** of the current day in the customer's timezone.
+   */
+  create(body: LicenseCreateParams, options?: Core.RequestOptions): Core.APIPromise<LicenseCreateResponse> {
+    return this._client.post('/licenses', { body, ...options });
+  }
+
+  /**
+   * This endpoint is used to fetch a license given an identifier.
+   */
+  retrieve(licenseId: string, options?: Core.RequestOptions): Core.APIPromise<LicenseRetrieveResponse> {
+    return this._client.get(`/licenses/${licenseId}`, options);
+  }
+
+  /**
+   * This endpoint returns a list of all licenses for a subscription.
+   */
+  list(
+    query: LicenseListParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<LicenseListResponsesPage, LicenseListResponse> {
+    return this._client.getAPIList('/licenses', LicenseListResponsesPage, { query, ...options });
+  }
+
+  /**
+   * This endpoint is used to deactivate an existing license.
+   *
+   * If an end date is provided, the license will be deactivated at the **start** of
+   * the specified date in the customer's timezone. Otherwise, the deactivation time
+   * will default to the **end** of the current day in the customer's timezone.
+   */
+  deactivate(
+    licenseId: string,
+    body: LicenseDeactivateParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<LicenseDeactivateResponse> {
+    return this._client.post(`/licenses/${licenseId}/deactivate`, { body, ...options });
+  }
+
+  /**
+   * This endpoint is used to fetch a license given an external license identifier.
+   */
+  retrieveByExternalId(
+    externalLicenseId: string,
+    query: LicenseRetrieveByExternalIDParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<LicenseRetrieveByExternalIDResponse> {
+    return this._client.get(`/licenses/external_license_id/${externalLicenseId}`, { query, ...options });
+  }
+}
+
+export class LicenseListResponsesPage extends Page<LicenseListResponse> {}
+
+export interface LicenseCreateResponse {
+  id: string;
+
+  end_date: string | null;
+
+  external_license_id: string;
+
+  license_type_id: string;
+
+  start_date: string;
+
+  status: 'active' | 'inactive';
+
+  subscription_id: string;
+}
+
+export interface LicenseRetrieveResponse {
+  id: string;
+
+  end_date: string | null;
+
+  external_license_id: string;
+
+  license_type_id: string;
+
+  start_date: string;
+
+  status: 'active' | 'inactive';
+
+  subscription_id: string;
+}
+
+export interface LicenseListResponse {
+  id: string;
+
+  end_date: string | null;
+
+  external_license_id: string;
+
+  license_type_id: string;
+
+  start_date: string;
+
+  status: 'active' | 'inactive';
+
+  subscription_id: string;
+}
+
+export interface LicenseDeactivateResponse {
+  id: string;
+
+  end_date: string | null;
+
+  external_license_id: string;
+
+  license_type_id: string;
+
+  start_date: string;
+
+  status: 'active' | 'inactive';
+
+  subscription_id: string;
+}
+
+export interface LicenseRetrieveByExternalIDResponse {
+  id: string;
+
+  end_date: string | null;
+
+  external_license_id: string;
+
+  license_type_id: string;
+
+  start_date: string;
+
+  status: 'active' | 'inactive';
+
+  subscription_id: string;
+}
+
+export interface LicenseCreateParams {
+  /**
+   * The external identifier for the license.
+   */
+  external_license_id: string;
+
+  license_type_id: string;
+
+  subscription_id: string;
+
+  /**
+   * The end date of the license. If not provided, the license will remain active
+   * until deactivated.
+   */
+  end_date?: string | null;
+
+  /**
+   * The start date of the license. If not provided, defaults to start of day today
+   * in the customer's timezone.
+   */
+  start_date?: string | null;
+}
+
+export interface LicenseListParams extends PageParams {
+  subscription_id: string;
+
+  external_license_id?: string | null;
+
+  license_type_id?: string | null;
+
+  status?: 'active' | 'inactive' | null;
+}
+
+export interface LicenseDeactivateParams {
+  /**
+   * The date to deactivate the license. If not provided, defaults to end of day
+   * today in the customer's timezone.
+   */
+  end_date?: string | null;
+}
+
+export interface LicenseRetrieveByExternalIDParams {
+  /**
+   * The ID of the license type to fetch the license for.
+   */
+  license_type_id: string;
+
+  /**
+   * The ID of the subscription to fetch the license for.
+   */
+  subscription_id: string;
+}
+
+Licenses.LicenseListResponsesPage = LicenseListResponsesPage;
+Licenses.ExternalLicenses = ExternalLicenses;
+Licenses.Usage = Usage;
+
+export declare namespace Licenses {
+  export {
+    type LicenseCreateResponse as LicenseCreateResponse,
+    type LicenseRetrieveResponse as LicenseRetrieveResponse,
+    type LicenseListResponse as LicenseListResponse,
+    type LicenseDeactivateResponse as LicenseDeactivateResponse,
+    type LicenseRetrieveByExternalIDResponse as LicenseRetrieveByExternalIDResponse,
+    LicenseListResponsesPage as LicenseListResponsesPage,
+    type LicenseCreateParams as LicenseCreateParams,
+    type LicenseListParams as LicenseListParams,
+    type LicenseDeactivateParams as LicenseDeactivateParams,
+    type LicenseRetrieveByExternalIDParams as LicenseRetrieveByExternalIDParams,
+  };
+
+  export {
+    ExternalLicenses as ExternalLicenses,
+    type ExternalLicenseGetUsageResponse as ExternalLicenseGetUsageResponse,
+    type ExternalLicenseGetUsageParams as ExternalLicenseGetUsageParams,
+  };
+
+  export {
+    Usage as Usage,
+    type UsageGetAllUsageResponse as UsageGetAllUsageResponse,
+    type UsageGetUsageResponse as UsageGetUsageResponse,
+    type UsageGetAllUsageParams as UsageGetAllUsageParams,
+    type UsageGetUsageParams as UsageGetUsageParams,
+  };
+}