orb-billing 5.48.0 → 5.76.0

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

@@ -10,6 +10,18 @@ export class ExternalLicenses extends APIResource {
    * license ID.
    *
    * Date range defaults to the current billing period if not specified.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.licenses.externalLicenses.getUsage(
+   *     'external_license_id',
+   *     {
+   *       license_type_id: 'license_type_id',
+   *       subscription_id: 'subscription_id',
+   *     },
+   *   );
+   * ```
    */
   getUsage(
     externalLicenseId: string,
@@ -125,7 +137,7 @@ export interface ExternalLicenseGetUsageParams {
    * How to group the results. Valid values: 'license', 'day'. Can be combined (e.g.,
    * 'license,day').
    */
-  group_by?: Array<string> | null;
+  group_by?: string | null;
 
   /**
    * Maximum number of rows in the response data (default 20, max 100).

package/src/resources/licenses/licenses.ts

@@ -30,6 +30,15 @@ export class Licenses extends APIResource {
    * 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.
+   *
+   * @example
+   * ```ts
+   * const license = await client.licenses.create({
+   *   external_license_id: 'external_license_id',
+   *   license_type_id: 'license_type_id',
+   *   subscription_id: 'subscription_id',
+   * });
+   * ```
    */
   create(body: LicenseCreateParams, options?: Core.RequestOptions): Core.APIPromise<LicenseCreateResponse> {
     return this._client.post('/licenses', { body, ...options });
@@ -37,6 +46,13 @@ export class Licenses extends APIResource {
 
   /**
    * This endpoint is used to fetch a license given an identifier.
+   *
+   * @example
+   * ```ts
+   * const license = await client.licenses.retrieve(
+   *   'license_id',
+   * );
+   * ```
    */
   retrieve(licenseId: string, options?: Core.RequestOptions): Core.APIPromise<LicenseRetrieveResponse> {
     return this._client.get(`/licenses/${licenseId}`, options);
@@ -44,6 +60,16 @@ export class Licenses extends APIResource {
 
   /**
    * This endpoint returns a list of all licenses for a subscription.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const licenseListResponse of client.licenses.list(
+   *   { subscription_id: 'subscription_id' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: LicenseListParams,
@@ -58,6 +84,13 @@ export class Licenses extends APIResource {
    * 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.
+   *
+   * @example
+   * ```ts
+   * const response = await client.licenses.deactivate(
+   *   'license_id',
+   * );
+   * ```
    */
   deactivate(
     licenseId: string,
@@ -69,6 +102,17 @@ export class Licenses extends APIResource {
 
   /**
    * This endpoint is used to fetch a license given an external license identifier.
+   *
+   * @example
+   * ```ts
+   * const response = await client.licenses.retrieveByExternalId(
+   *   'external_license_id',
+   *   {
+   *     license_type_id: 'license_type_id',
+   *     subscription_id: 'subscription_id',
+   *   },
+   * );
+   * ```
    */
   retrieveByExternalId(
     externalLicenseId: string,

package/src/resources/licenses/usage.ts

@@ -11,6 +11,14 @@ export class Usage extends APIResource {
    * 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,
@@ -23,6 +31,13 @@ export class Usage extends APIResource {
    * Returns usage and remaining credits for a specific license over a date range.
    *
    * 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,
@@ -226,7 +241,7 @@ export interface UsageGetAllUsageParams {
    * How to group the results. Valid values: 'license', 'day'. Can be combined (e.g.,
    * 'license,day').
    */
-  group_by?: Array<string> | null;
+  group_by?: string | null;
 
   /**
    * Maximum number of rows in the response data (default 20, max 100).
@@ -256,7 +271,7 @@ export interface UsageGetUsageParams {
    * How to group the results. Valid values: 'license', 'day'. Can be combined (e.g.,
    * 'license,day').
    */
-  group_by?: Array<string> | null;
+  group_by?: string | null;
 
   /**
    * Maximum number of rows in the response data (default 20, max 100).

package/src/resources/metrics.ts

@@ -15,6 +15,16 @@ export class Metrics extends APIResource {
    * This endpoint is used to create a [metric](/core-concepts###metric) using a SQL
    * string. See [SQL support](/extensibility/advanced-metrics#sql-support) for a
    * description of constructing SQL queries with examples.
+   *
+   * @example
+   * ```ts
+   * const billableMetric = await client.metrics.create({
+   *   description: 'Sum of bytes downloaded in fast mode',
+   *   item_id: 'item_id',
+   *   name: 'Bytes downloaded',
+   *   sql: "SELECT sum(bytes_downloaded) FROM events WHERE download_speed = 'fast'",
+   * });
+   * ```
    */
   create(body: MetricCreateParams, options?: Core.RequestOptions): Core.APIPromise<BillableMetric> {
     return this._client.post('/metrics', { body, ...options });
@@ -24,6 +34,13 @@ export class Metrics extends APIResource {
    * This endpoint allows you to update the `metadata` property on a metric. If you
    * pass `null` for the metadata value, it will clear any existing metadata for that
    * invoice.
+   *
+   * @example
+   * ```ts
+   * const billableMetric = await client.metrics.update(
+   *   'metric_id',
+   * );
+   * ```
    */
   update(
     metricId: string,
@@ -34,9 +51,16 @@ export class Metrics extends APIResource {
   }
 
   /**
-   * This endpoint is used to fetch [metric](/core-concepts##metric) details given a
-   * metric identifier. It returns information about the metrics including its name,
-   * description, and item.
+   * This endpoint is used to list [metrics](/core-concepts#metric). It returns
+   * information about the metrics including its name, description, and item.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const billableMetric of client.metrics.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: MetricListParams,
@@ -54,8 +78,16 @@ export class Metrics extends APIResource {
   }
 
   /**
-   * This endpoint is used to list [metrics](/core-concepts#metric). It returns
-   * information about the metrics including its name, description, and item.
+   * This endpoint is used to fetch [metric](/core-concepts#metric) details given a
+   * metric identifier. It returns information about the metrics including its name,
+   * description, and item.
+   *
+   * @example
+   * ```ts
+   * const billableMetric = await client.metrics.fetch(
+   *   'metric_id',
+   * );
+   * ```
    */
   fetch(metricId: string, options?: Core.RequestOptions): Core.APIPromise<BillableMetric> {
     return this._client.get(`/metrics/${metricId}`, options);
@@ -91,6 +123,12 @@ export interface BillableMetric {
 
   name: string;
 
+  /**
+   * The SQL definition of the metric. For metrics defined via configuration rather
+   * than SQL, this is a derived SQL representation.
+   */
+  sql: string;
+
   status: 'active' | 'draft' | 'archived';
 
   parameter_definitions?: Array<{ [key: string]: unknown }> | null;

package/src/resources/plans/external-plan-id.ts

@@ -11,8 +11,8 @@ import * as PlansAPI from './plans';
  */
 export class ExternalPlanID extends APIResource {
   /**
-   * This endpoint can be used to update the `external_plan_id`, and `metadata` of an
-   * existing plan.
+   * This endpoint can be used to update the `external_plan_id`, `description`, and
+   * `metadata` of an existing plan.
    *
    * Other fields on a plan are currently immutable.
    */
@@ -48,6 +48,11 @@ export class ExternalPlanID extends APIResource {
 }
 
 export interface ExternalPlanIDUpdateParams {
+  /**
+   * An optional user-defined description of the plan.
+   */
+  description?: string | null;
+
   /**
    * An optional user-defined ID for this plan resource, used throughout the system
    * as an alias for this Plan. Use this field to identify a plan by an existing

package/src/resources/plans/migrations.ts

@@ -66,32 +66,74 @@ export class Migrations extends APIResource {
 export class MigrationListResponsesPage extends Page<MigrationListResponse> {}
 
 export interface MigrationRetrieveResponse {
+  /**
+   * Unique identifier for this plan version change.
+   */
   id: string;
 
+  /**
+   * When the migration takes effect. Can be a specific date/time, or 'end_of_term'
+   * when scheduled to be at the end of the current billing period.
+   */
   effective_time: (string & {}) | (string & {}) | 'end_of_term' | null;
 
+  /**
+   * The ID of the plan being migrated.
+   */
   plan_id: string;
 
+  /**
+   * Current status of the migration: 'not_started', 'in_progress', 'completed',
+   * 'action_needed', or 'canceled'.
+   */
   status: 'not_started' | 'in_progress' | 'completed' | 'action_needed' | 'canceled';
 }
 
 export interface MigrationListResponse {
+  /**
+   * Unique identifier for this plan version change.
+   */
   id: string;
 
+  /**
+   * When the migration takes effect. Can be a specific date/time, or 'end_of_term'
+   * when scheduled to be at the end of the current billing period.
+   */
   effective_time: (string & {}) | (string & {}) | 'end_of_term' | null;
 
+  /**
+   * The ID of the plan being migrated.
+   */
   plan_id: string;
 
+  /**
+   * Current status of the migration: 'not_started', 'in_progress', 'completed',
+   * 'action_needed', or 'canceled'.
+   */
   status: 'not_started' | 'in_progress' | 'completed' | 'action_needed' | 'canceled';
 }
 
 export interface MigrationCancelResponse {
+  /**
+   * Unique identifier for this plan version change.
+   */
   id: string;
 
+  /**
+   * When the migration takes effect. Can be a specific date/time, or 'end_of_term'
+   * when scheduled to be at the end of the current billing period.
+   */
   effective_time: (string & {}) | (string & {}) | 'end_of_term' | null;
 
+  /**
+   * The ID of the plan being migrated.
+   */
   plan_id: string;
 
+  /**
+   * Current status of the migration: 'not_started', 'in_progress', 'completed',
+   * 'action_needed', or 'canceled'.
+   */
   status: 'not_started' | 'in_progress' | 'completed' | 'action_needed' | 'canceled';
 }