feat: add invoice v3 list endpoint (#4613)

Author: borosr

api/spec/packages/aip-client-javascript/README.md

@@ -194,9 +194,10 @@ The full call path, HTTP route, and a short description are listed below.
 
 ### Invoices
 
-| Method                | HTTP                                          | Description                                                                                                                                       |
-| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `client.invoices.get` | `GET /openmeter/billing/invoices/{invoiceId}` | Get a billing invoice by ID. Returns the full invoice resource including line items, status details, totals, and workflow configuration snapshot. |
+| Method                 | HTTP                                          | Description                                                                                                                                                                                           |
+| ---------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.invoices.list` | `GET /openmeter/billing/invoices`             | List billing invoices. Returns a page of invoices. Gathering invoices are never included. Use `filter` to narrow by status, customer, dates, or service period start. Use `sort` to control ordering. |
+| `client.invoices.get`  | `GET /openmeter/billing/invoices/{invoiceId}` | Get a billing invoice by ID. Returns the full invoice resource including line items, status details, totals, and workflow configuration snapshot.                                                     |
 
 ### Tax
 

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

@@ -3,10 +3,29 @@ import { type Result, type RequestOptions } from '../lib/types.js'
 import { request } from '../lib/request.js'
 import { encodePath, toURLSearchParams, encodeSort } from '../lib/encodings.js'
 import type {
+  ListInvoicesRequest,
+  ListInvoicesResponse,
   GetInvoiceRequest,
   GetInvoiceResponse,
 } from '../models/operations/invoices.js'
 
+export function listInvoices(
+  client: Client,
+  req: ListInvoicesRequest = {},
+  options?: RequestOptions,
+): Promise<Result<ListInvoicesResponse>> {
+  const searchParams = toURLSearchParams({
+    page: req.page,
+    sort: encodeSort(req.sort),
+    filter: req.filter,
+  })
+  return request(() =>
+    http(client)
+      .get('openmeter/billing/invoices', { ...options, searchParams })
+      .json<ListInvoicesResponse>(),
+  )
+}
+
 export function getInvoice(
   client: Client,
   req: GetInvoiceRequest,

api/spec/packages/aip-client-javascript/src/index.ts

@@ -220,6 +220,7 @@ export type {
   ProfileAppReferences,
   InvoiceWorkflowAppsReferences,
   ListEventsParamsFilter,
+  ListInvoicesParamsFilter,
   ResourceFilters,
   FieldFilters,
   IngestedEvent,
@@ -314,6 +315,7 @@ export type {
   SubscriptionAddonPagePaginatedResponse,
   PlanPagePaginatedResponse,
   InvoiceStandard,
+  InvoicePagePaginatedResponse,
   SortQueryInput,
   BaseErrorInput,
   WorkflowPaymentSendInvoiceSettingsInput,
@@ -375,4 +377,5 @@ export type {
   SubscriptionAddonPagePaginatedResponseInput,
   PlanPagePaginatedResponseInput,
   InvoiceStandardInput,
+  InvoicePagePaginatedResponseInput,
 } from './models/types.js'

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

@@ -1,5 +1,39 @@
 import { z } from 'zod'
 import * as schemas from '../schemas.js'
+import type {
+  InvoicePagePaginatedResponse,
+  ListInvoicesParamsFilter,
+  SortQueryInput,
+} from '../types.js'
+
+export interface ListInvoicesQuery {
+  /** Determines which page of the collection to retrieve. */
+  page?: { size?: number; number?: number }
+  /**
+   * Sort invoices returned in the response. Supported sort attributes:
+   *
+   * - `issued_at`
+   * - `created_at` (default)
+   * - `service_period_start`
+   *
+   * The `asc` suffix is optional as the default sort order is ascending. The `desc`
+   * suffix is used to specify a descending order.
+   */
+  sort?: SortQueryInput
+  /**
+   * Filter invoices returned in the response.
+   *
+   * Examples:
+   *
+   * - `filter[status][oeq]=draft,issued`
+   * - `filter[customer_id]=01KPDB8K...`
+   * - `filter[issued_at][gte]=2024-01-01T00:00:00Z`
+   */
+  filter?: ListInvoicesParamsFilter
+}
+
+export type ListInvoicesRequest = ListInvoicesQuery
+export type ListInvoicesResponse = InvoicePagePaginatedResponse
 
 export type GetInvoiceRequest = {
   invoiceId: string

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

@@ -3278,6 +3278,16 @@ export const listEventsParamsFilter = z
   })
   .describe('Filter options for listing ingested events.')
 
+export const listInvoicesParamsFilter = z
+  .object({
+    status: stringFieldFilterExact.optional(),
+    customer_id: ulidFieldFilter.optional(),
+    issued_at: dateTimeFieldFilter.optional(),
+    service_period_start: dateTimeFieldFilter.optional(),
+    created_at: dateTimeFieldFilter.optional(),
+  })
+  .describe('Filter options for listing invoices.')
+
 export const resourceFilters = z
   .object({
     name: stringFieldFilter.optional(),
@@ -5227,6 +5237,13 @@ export const invoice = z
     'An invoice issued to a customer. The `type` field determines the concrete variant: - `standard`: a standard invoice for charges owed.',
   )
 
+export const invoicePagePaginatedResponse = z
+  .object({
+    data: z.array(invoice),
+    meta: paginatedMeta,
+  })
+  .describe('Page paginated response.')
+
 export const listMeteringEventsQueryParams = z.object({
   page: cursorPaginationQueryPage.optional(),
   filter: listEventsParamsFilter.optional(),
@@ -5669,6 +5686,27 @@ export const deleteBillingProfilePathParams = z.object({
   id: ulid,
 })
 
+export const listInvoicesQueryParams = z.object({
+  page: z
+    .object({
+      size: z.coerce
+        .number()
+        .int()
+        .optional()
+        .describe('The number of items to include per page.'),
+      number: z.coerce.number().int().optional().describe('The page number.'),
+    })
+    .optional()
+    .describe('Determines which page of the collection to retrieve.'),
+  sort: sortQuery.optional(),
+  filter: listInvoicesParamsFilter.optional(),
+})
+
+export const listInvoicesResponse = z.object({
+  data: z.array(invoice),
+  meta: paginatedMeta,
+})
+
 export const getInvoicePathParams = z.object({
   invoiceId: ulid,
 })

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

@@ -2823,6 +2823,26 @@ export interface ListEventsParamsFilter {
     | { eq?: string; lt?: string; lte?: string; gt?: string; gte?: string }
 }
 
+/** Filter options for listing invoices. */
+export interface ListInvoicesParamsFilter {
+  /** Filter by invoice status. */
+  status?: string | { eq?: string; oeq?: string[]; neq?: string }
+  /** Filter by customer ID. */
+  customer_id?: string | { eq?: string; oeq?: string[]; neq?: string }
+  /** Filter by the time the invoice was issued. */
+  issued_at?:
+    | string
+    | { eq?: string; lt?: string; lte?: string; gt?: string; gte?: string }
+  /** Filter by service period start. */
+  service_period_start?:
+    | string
+    | { eq?: string; lt?: string; lte?: string; gt?: string; gte?: string }
+  /** Filter by invoice creation time. */
+  created_at?:
+    | string
+    | { eq?: string; lt?: string; lte?: string; gt?: string; gte?: string }
+}
+
 /** Resource filters. */
 export interface ResourceFilters {
   name?:
@@ -5110,6 +5130,12 @@ export interface InvoiceStandard {
   lines?: InvoiceStandardLine[]
 }
 
+/** Page paginated response. */
+export interface InvoicePagePaginatedResponse {
+  data: InvoiceStandard[]
+  meta: PaginatedMeta
+}
+
 export interface SortQueryInput {
   /** The attribute to sort by. */
   by: string
@@ -6405,3 +6431,8 @@ export interface InvoiceStandardInput {
    */
   lines?: InvoiceStandardLineInput[]
 }
+
+export interface InvoicePagePaginatedResponseInput {
+  data: InvoiceStandardInput[]
+  meta: PaginatedMeta
+}

api/spec/packages/aip-client-javascript/src/sdk/invoices.ts

@@ -1,14 +1,23 @@
 import { type Client } from '../core.js'
 import { unwrap, type RequestOptions } from '../lib/types.js'
-import { getInvoice } from '../funcs/invoices.js'
+import { listInvoices, getInvoice } from '../funcs/invoices.js'
 import type {
+  ListInvoicesRequest,
+  ListInvoicesResponse,
   GetInvoiceRequest,
   GetInvoiceResponse,
 } from '../models/operations/invoices.js'
 
 export class Invoices {
   constructor(private readonly _client: Client) {}
 
+  async list(
+    request?: ListInvoicesRequest,
+    options?: RequestOptions,
+  ): Promise<ListInvoicesResponse> {
+    return unwrap(await listInvoices(this._client, request, options))
+  }
+
   async get(
     request: GetInvoiceRequest,
     options?: RequestOptions,

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

@@ -14,10 +14,88 @@ using TypeSpec.OpenAPI;
 
 namespace Invoices;
 
+/**
+ * Filter options for listing invoices.
+ */
+@friendlyName("ListInvoicesParamsFilter")
+model ListInvoicesParamsFilter {
+  /**
+   * Filter by invoice status.
+   */
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  status?: Common.StringFieldFilterExact;
+
+  /**
+   * Filter by customer ID.
+   */
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  customer_id?: Common.ULIDFieldFilter;
+
+  /**
+   * Filter by the time the invoice was issued.
+   */
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  issued_at?: Common.DateTimeFieldFilter;
+
+  /**
+   * Filter by service period start.
+   */
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  service_period_start?: Common.DateTimeFieldFilter;
+
+  /**
+   * Filter by invoice creation time.
+   */
+  #suppress "@openmeter/api-spec-aip/doc-decorator" "filter field"
+  created_at?: Common.DateTimeFieldFilter;
+}
+
 /**
  * Operations for managing billing invoices.
  */
 interface InvoicesOperations {
+  /**
+   * List billing invoices.
+   *
+   * Returns a page of invoices. Gathering invoices are never included. Use `filter`
+   * to narrow by status, customer, dates, or service period start. Use `sort` to
+   * control ordering.
+   */
+  @extension(Shared.UnstableExtension, true)
+  @extension(Shared.InternalExtension, true)
+  @extension(Shared.PrivateExtension, true)
+  @get
+  @operationId("list-invoices")
+  @summary("List billing invoices")
+  list(
+    ...Common.PagePaginationQuery,
+
+    /**
+     * Sort invoices returned in the response. Supported sort attributes:
+     *
+     * - `issued_at`
+     * - `created_at` (default)
+     * - `service_period_start`
+     *
+     * The `asc` suffix is optional as the default sort order is ascending. The `desc`
+     * suffix is used to specify a descending order.
+     */
+    @query(#{ name: "sort" })
+    sort?: Common.SortQuery,
+
+    /**
+     * Filter invoices returned in the response.
+     *
+     * Examples:
+     *
+     * - `filter[status][oeq]=draft,issued`
+     * - `filter[customer_id]=01KPDB8K...`
+     * - `filter[issued_at][gte]=2024-01-01T00:00:00Z`
+     */
+    @query(#{ style: "deepObject", explode: true })
+    filter?: ListInvoicesParamsFilter,
+  ): Shared.PagePaginatedResponse<Invoice> | Common.ErrorResponses;
+
   /**
    * Get a billing invoice by ID.
    *