feat(api): point-in-time real-time usage on charge listings

api/spec/packages/aip-client-javascript/src/funcs/charges.ts

@@ -35,6 +35,7 @@ export function listCharges(
         page: req.page,
         sort: encodeSort(req.sort, toSnakeCase),
         filter: req.filter,
+        asOf: req.asOf,
         expand: req.expand,
       },
       schemas.listChargesQueryParams,

api/spec/packages/aip-client-javascript/src/funcs/customers.ts

@@ -1546,6 +1546,7 @@ export function listCustomerCharges(
         page: req.page,
         sort: encodeSort(req.sort, toSnakeCase),
         filter: req.filter,
+        asOf: req.asOf,
         expand: req.expand,
       },
       schemas.listCustomerChargesQueryParams,

api/spec/packages/aip-client-javascript/src/models/operations/charges.ts

@@ -39,6 +39,23 @@ export interface ListChargesQuery {
    * window query.
    */
   filter?: ListChargesParamsFilter
+  /**
+   * Evaluate `expand=real_time_usage` as of this time instead of now. Requires the
+   * `real_time_usage` expand and must not be in the future.
+   *
+   * Usage and `totals.realtime` count only events stored before `as_of`, and minimum
+   * commitments apply only when the service period has ended by `as_of`. Everything
+   * else is read as it is now: the price, service periods, status, the customer's
+   * subjects, and the feature's meter and filters. A re-run returns the same usage
+   * only while those are unchanged. Realizations are current too, so a usage-based
+   * charge's outstanding realization reports `usage` as zero.
+   *
+   * Charges created after `as_of` are included. Charges deleted after `as_of` are
+   * left out unless `filter[status]` selects `deleted`. Events become readable
+   * shortly after they are stored, so a cutoff from the last few minutes can still
+   * change on a re-run.
+   */
+  asOf?: Date
   /**
    * Expand full objects for referenced entities.
    *

api/spec/packages/aip-client-javascript/src/models/operations/customers.ts

@@ -357,6 +357,23 @@ export interface ListCustomerChargesQuery {
    * window query.
    */
   filter?: ListCustomerChargesParamsFilter
+  /**
+   * Evaluate `expand=real_time_usage` as of this time instead of now. Requires the
+   * `real_time_usage` expand and must not be in the future.
+   *
+   * Usage and `totals.realtime` count only events stored before `as_of`, and minimum
+   * commitments apply only when the service period has ended by `as_of`. Everything
+   * else is read as it is now: the price, service periods, status, the customer's
+   * subjects, and the feature's meter and filters. A re-run returns the same usage
+   * only while those are unchanged. Realizations are current too, so a usage-based
+   * charge's outstanding realization reports `usage` as zero.
+   *
+   * Charges created after `as_of` are included. Charges deleted after `as_of` are
+   * left out unless `filter[status]` selects `deleted`. Events become readable
+   * shortly after they are stored, so a cutoff from the last few minutes can still
+   * change on a re-run.
+   */
+  asOf?: Date
   /**
    * Expand full objects for referenced entities.
    *

api/spec/packages/aip-client-javascript/src/models/schemas.ts

@@ -8975,6 +8975,7 @@ export const listCustomerChargesQueryParams = z.object({
     .describe('Determines which page of the collection to retrieve.'),
   sort: sortQuery.optional(),
   filter: listCustomerChargesParamsFilter.optional(),
+  asOf: dateTime.optional(),
   expand: z
     .array(chargesExpand)
     .optional()
@@ -9328,6 +9329,7 @@ export const listChargesQueryParams = z.object({
     .describe('Determines which page of the collection to retrieve.'),
   sort: sortQuery.optional(),
   filter: listChargesParamsFilter.optional(),
+  asOf: dateTime.optional(),
   expand: z
     .array(chargesExpand)
     .optional()
@@ -18866,6 +18868,7 @@ export const listCustomerChargesQueryParamsWire = z.object({
       'Sort charges returned in the response. Supported sort attributes are: - `id` - `created_at` - `service_period.from` - `billing_period.from`',
     ),
   filter: listCustomerChargesParamsFilterWire.optional(),
+  as_of: dateTimeWire.optional(),
   expand: z
     .array(chargesExpandWire)
     .optional()
@@ -19257,6 +19260,7 @@ export const listChargesQueryParamsWire = z.object({
       'Sort charges returned in the response. Supported sort attributes are: - `id` - `created_at` - `service_period.from` - `billing_period.from`',
     ),
   filter: listChargesParamsFilterWire.optional(),
+  as_of: dateTimeWire.optional(),
   expand: z
     .array(chargesExpandWire)
     .optional()

api/spec/packages/aip/src/charges/operations.tsp

@@ -71,6 +71,25 @@ interface ChargesOperations {
     @query(#{ style: "deepObject", explode: true })
     filter?: ListChargesParamsFilter,
 
+    /**
+     * Evaluate `expand=real_time_usage` as of this time instead of now. Requires the
+     * `real_time_usage` expand and must not be in the future.
+     *
+     * Usage and `totals.realtime` count only events stored before `as_of`, and minimum
+     * commitments apply only when the service period has ended by `as_of`. Everything
+     * else is read as it is now: the price, service periods, status, the customer's
+     * subjects, and the feature's meter and filters. A re-run returns the same usage
+     * only while those are unchanged. Realizations are current too, so a usage-based
+     * charge's outstanding realization reports `usage` as zero.
+     *
+     * Charges created after `as_of` are included. Charges deleted after `as_of` are
+     * left out unless `filter[status]` selects `deleted`. Events become readable
+     * shortly after they are stored, so a cutoff from the last few minutes can still
+     * change on a re-run.
+     */
+    @query
+    as_of?: Shared.DateTime,
+
     /**
      * Expand full objects for referenced entities.
      *

api/spec/packages/aip/src/customers/charges/operations.tsp

@@ -126,6 +126,25 @@ namespace Charges {
       @query(#{ style: "deepObject", explode: true })
       filter?: ListCustomerChargesParamsFilter,
 
+      /**
+       * Evaluate `expand=real_time_usage` as of this time instead of now. Requires the
+       * `real_time_usage` expand and must not be in the future.
+       *
+       * Usage and `totals.realtime` count only events stored before `as_of`, and minimum
+       * commitments apply only when the service period has ended by `as_of`. Everything
+       * else is read as it is now: the price, service periods, status, the customer's
+       * subjects, and the feature's meter and filters. A re-run returns the same usage
+       * only while those are unchanged. Realizations are current too, so a usage-based
+       * charge's outstanding realization reports `usage` as zero.
+       *
+       * Charges created after `as_of` are included. Charges deleted after `as_of` are
+       * left out unless `filter[status]` selects `deleted`. Events become readable
+       * shortly after they are stored, so a cutoff from the last few minutes can still
+       * change on a re-run.
+       */
+      @query
+      as_of?: Shared.DateTime,
+
       /**
        * Expand full objects for referenced entities.
        *