feat: v3 invoice api actions (#4671)

Author: borosr

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

@@ -425,12 +425,16 @@ they can change or be removed without notice or semver consideration.
 
 ### Internal Invoices
 
-| Method                            | HTTP                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
-| --------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `client.internal.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.internal.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.                                                                                                                                                                                                                                                                     |
-| `client.internal.invoices.update` | `PUT /openmeter/billing/invoices/{invoiceId}`    | Update a billing invoice. Only the mutable fields of the invoice can be edited: description, labels, supplier, customer, workflow settings, and top-level lines. Top-level lines are matched by `id`; lines without an `id` are created, and existing lines omitted from `lines` are deleted. Detailed (child) lines are always computed and cannot be edited directly. Only invoices in draft status can be updated. |
-| `client.internal.invoices.delete` | `DELETE /openmeter/billing/invoices/{invoiceId}` | Delete a billing invoice. Only standard invoices in draft status can be deleted. Deleting an invoice will also delete all associated line items and workflow configuration.                                                                                                                                                                                                                                           |
+| Method                                        | HTTP                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
+| --------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.internal.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.internal.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.                                                                                                                                                                                                                                                                     |
+| `client.internal.invoices.update`             | `PUT /openmeter/billing/invoices/{invoiceId}`                      | Update a billing invoice. Only the mutable fields of the invoice can be edited: description, labels, supplier, customer, workflow settings, and top-level lines. Top-level lines are matched by `id`; lines without an `id` are created, and existing lines omitted from `lines` are deleted. Detailed (child) lines are always computed and cannot be edited directly. Only invoices in draft status can be updated. |
+| `client.internal.invoices.delete`             | `DELETE /openmeter/billing/invoices/{invoiceId}`                   | Delete a billing invoice. Only standard invoices in draft status can be deleted. Deleting an invoice will also delete all associated line items and workflow configuration.                                                                                                                                                                                                                                           |
+| `client.internal.invoices.advance`            | `POST /openmeter/billing/invoices/{invoiceId}/advance`             | Advance a billing invoice. Advances the invoice to the next workflow state. The next state is determined by the invoice's current status and workflow configuration. Only invoices in draft or issued status can be advanced.                                                                                                                                                                                         |
+| `client.internal.invoices.approve`            | `POST /openmeter/billing/invoices/{invoiceId}/approve`             | Approve a billing invoice. This call instantly sends the invoice to the customer using the configured billing profile app. This call is valid in two invoice statuses: - draft: the invoice will be sent to the customer, the invoice state becomes issued - manual_approval_needed: the invoice will be sent to the customer, the invoice state becomes issued                                                       |
+| `client.internal.invoices.retry`              | `POST /openmeter/billing/invoices/{invoiceId}/retry`               | Retry sending a billing invoice. Retry advancing the invoice after a failed attempt. The action can be called when the invoice's statusDetails' actions field contain the "retry" action.                                                                                                                                                                                                                             |
+| `client.internal.invoices.snapshotQuantities` | `POST /openmeter/billing/invoices/{invoiceId}/snapshot-quantities` | Snapshot quantities for usage-based line items. This call will snapshot the quantities for all usage based line items in the invoice. This call is only valid in draft.waiting_for_collection status, where the collection period can be skipped using this action.                                                                                                                                                   |
 
 ### Internal Currencies
 

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

@@ -15,6 +15,14 @@ import type {
   UpdateInvoiceResponse,
   DeleteInvoiceRequest,
   DeleteInvoiceResponse,
+  AdvanceInvoiceRequest,
+  AdvanceInvoiceResponse,
+  ApproveInvoiceRequest,
+  ApproveInvoiceResponse,
+  RetryInvoiceRequest,
+  RetryInvoiceResponse,
+  SnapshotQuantitiesInvoiceRequest,
+  SnapshotQuantitiesInvoiceResponse,
 } from '../models/operations/invoices.js'
 
 /**
@@ -158,3 +166,152 @@ export function deleteInvoice(
     await http(client).delete(path, options)
   })
 }
+
+/**
+ * Advance billing invoice's next status
+ *
+ * Advance a billing invoice.
+ *
+ * Advances the invoice to the next workflow state. The next state is determined by
+ * the invoice's current status and workflow configuration. Only invoices in draft
+ * or issued status can be advanced.
+ *
+ * POST /openmeter/billing/invoices/{invoiceId}/advance
+ */
+export function advanceInvoice(
+  client: Client,
+  req: AdvanceInvoiceRequest,
+  options?: RequestOptions,
+): Promise<Result<AdvanceInvoiceResponse>> {
+  return request(() => {
+    const path = `openmeter/billing/invoices/${(() => {
+      if (req.invoiceId === undefined) {
+        throw new Error('missing path parameter: invoiceId')
+      }
+      return encodeURIComponent(String(req.invoiceId))
+    })()}/advance`
+    return http(client)
+      .post(path, options)
+      .json()
+      .then((data) => {
+        if (client._options.validate) {
+          assertValid(schemas.advanceInvoiceResponseWire, data)
+        }
+        return fromWire(data, schemas.advanceInvoiceResponse)
+      })
+  })
+}
+
+/**
+ * Send the invoice to the customer
+ *
+ * Approve a billing invoice.
+ *
+ * This call instantly sends the invoice to the customer using the configured
+ * billing profile app.
+ *
+ * This call is valid in two invoice statuses:
+ *
+ * - draft: the invoice will be sent to the customer, the invoice state becomes
+ * issued
+ * - manual_approval_needed: the invoice will be sent to the customer, the invoice
+ * state becomes issued
+ *
+ * POST /openmeter/billing/invoices/{invoiceId}/approve
+ */
+export function approveInvoice(
+  client: Client,
+  req: ApproveInvoiceRequest,
+  options?: RequestOptions,
+): Promise<Result<ApproveInvoiceResponse>> {
+  return request(() => {
+    const path = `openmeter/billing/invoices/${(() => {
+      if (req.invoiceId === undefined) {
+        throw new Error('missing path parameter: invoiceId')
+      }
+      return encodeURIComponent(String(req.invoiceId))
+    })()}/approve`
+    return http(client)
+      .post(path, options)
+      .json()
+      .then((data) => {
+        if (client._options.validate) {
+          assertValid(schemas.approveInvoiceResponseWire, data)
+        }
+        return fromWire(data, schemas.approveInvoiceResponse)
+      })
+  })
+}
+
+/**
+ * Retry advancing the invoice after a failed attempt
+ *
+ * Retry sending a billing invoice.
+ *
+ * Retry advancing the invoice after a failed attempt.
+ *
+ * The action can be called when the invoice's statusDetails' actions field contain
+ * the "retry" action.
+ *
+ * POST /openmeter/billing/invoices/{invoiceId}/retry
+ */
+export function retryInvoice(
+  client: Client,
+  req: RetryInvoiceRequest,
+  options?: RequestOptions,
+): Promise<Result<RetryInvoiceResponse>> {
+  return request(() => {
+    const path = `openmeter/billing/invoices/${(() => {
+      if (req.invoiceId === undefined) {
+        throw new Error('missing path parameter: invoiceId')
+      }
+      return encodeURIComponent(String(req.invoiceId))
+    })()}/retry`
+    return http(client)
+      .post(path, options)
+      .json()
+      .then((data) => {
+        if (client._options.validate) {
+          assertValid(schemas.retryInvoiceResponseWire, data)
+        }
+        return fromWire(data, schemas.retryInvoiceResponse)
+      })
+  })
+}
+
+/**
+ * Snapshot quantities for usage based line items
+ *
+ * Snapshot quantities for usage-based line items.
+ *
+ * This call will snapshot the quantities for all usage based line items in the
+ * invoice.
+ *
+ * This call is only valid in draft.waiting_for_collection status, where the
+ * collection period can be skipped using this action.
+ *
+ * POST /openmeter/billing/invoices/{invoiceId}/snapshot-quantities
+ */
+export function snapshotQuantitiesInvoice(
+  client: Client,
+  req: SnapshotQuantitiesInvoiceRequest,
+  options?: RequestOptions,
+): Promise<Result<SnapshotQuantitiesInvoiceResponse>> {
+  return request(() => {
+    const path = `openmeter/billing/invoices/${(() => {
+      if (req.invoiceId === undefined) {
+        throw new Error('missing path parameter: invoiceId')
+      }
+      return encodeURIComponent(String(req.invoiceId))
+    })()}/snapshot-quantities`
+    return http(client)
+      .post(path, options)
+      .json()
+      .then((data) => {
+        if (client._options.validate) {
+          assertValid(schemas.snapshotQuantitiesInvoiceResponseWire, data)
+        }
+        return fromWire(data, schemas.snapshotQuantitiesInvoiceResponse)
+      })
+  })
+}

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

@@ -55,3 +55,23 @@ export type DeleteInvoiceRequest = {
   invoiceId: string
 }
 export type DeleteInvoiceResponse = void
+
+export type AdvanceInvoiceRequest = {
+  invoiceId: string
+}
+export type AdvanceInvoiceResponse = Invoice
+
+export type ApproveInvoiceRequest = {
+  invoiceId: string
+}
+export type ApproveInvoiceResponse = Invoice
+
+export type RetryInvoiceRequest = {
+  invoiceId: string
+}
+export type RetryInvoiceResponse = Invoice
+
+export type SnapshotQuantitiesInvoiceRequest = {
+  invoiceId: string
+}
+export type SnapshotQuantitiesInvoiceResponse = Invoice

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

@@ -6149,6 +6149,30 @@ export const deleteInvoicePathParams = z.object({
   invoiceId: ulid,
 })
 
+export const advanceInvoicePathParams = z.object({
+  invoiceId: ulid,
+})
+
+export const advanceInvoiceResponse = invoice
+
+export const approveInvoicePathParams = z.object({
+  invoiceId: ulid,
+})
+
+export const approveInvoiceResponse = invoice
+
+export const retryInvoicePathParams = z.object({
+  invoiceId: ulid,
+})
+
+export const retryInvoiceResponse = invoice
+
+export const snapshotQuantitiesInvoicePathParams = z.object({
+  invoiceId: ulid,
+})
+
+export const snapshotQuantitiesInvoiceResponse = invoice
+
 export const createTaxCodeBody = createTaxCodeRequest
 
 export const createTaxCodeResponse = taxCode
@@ -12711,6 +12735,30 @@ export const deleteInvoicePathParamsWire = z.object({
   invoiceId: ulidWire,
 })
 
+export const advanceInvoicePathParamsWire = z.object({
+  invoiceId: ulidWire,
+})
+
+export const advanceInvoiceResponseWire = invoiceWire
+
+export const approveInvoicePathParamsWire = z.object({
+  invoiceId: ulidWire,
+})
+
+export const approveInvoiceResponseWire = invoiceWire
+
+export const retryInvoicePathParamsWire = z.object({
+  invoiceId: ulidWire,
+})
+
+export const retryInvoiceResponseWire = invoiceWire
+
+export const snapshotQuantitiesInvoicePathParamsWire = z.object({
+  invoiceId: ulidWire,
+})
+
+export const snapshotQuantitiesInvoiceResponseWire = invoiceWire
+
 export const createTaxCodeBodyWire = createTaxCodeRequestWire
 
 export const createTaxCodeResponseWire = taxCodeWire

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

@@ -9,6 +9,10 @@ import {
   getInvoice,
   updateInvoice,
   deleteInvoice,
+  advanceInvoice,
+  approveInvoice,
+  retryInvoice,
+  snapshotQuantitiesInvoice,
 } from '../funcs/invoices.js'
 import {
   listCurrencies,
@@ -30,6 +34,14 @@ import type {
   UpdateInvoiceResponse,
   DeleteInvoiceRequest,
   DeleteInvoiceResponse,
+  AdvanceInvoiceRequest,
+  AdvanceInvoiceResponse,
+  ApproveInvoiceRequest,
+  ApproveInvoiceResponse,
+  RetryInvoiceRequest,
+  RetryInvoiceResponse,
+  SnapshotQuantitiesInvoiceRequest,
+  SnapshotQuantitiesInvoiceResponse,
 } from '../models/operations/invoices.js'
 import type {
   ListCurrenciesRequest,
@@ -192,6 +204,89 @@ export class InternalInvoices {
   ): Promise<DeleteInvoiceResponse> {
     return unwrap(await deleteInvoice(this._client, request, options))
   }
+
+  /**
+   * Advance billing invoice's next status
+   *
+   * Advance a billing invoice.
+   *
+   * Advances the invoice to the next workflow state. The next state is determined by
+   * the invoice's current status and workflow configuration. Only invoices in draft
+   * or issued status can be advanced.
+   *
+   * POST /openmeter/billing/invoices/{invoiceId}/advance
+   */
+  async advance(
+    request: AdvanceInvoiceRequest,
+    options?: RequestOptions,
+  ): Promise<AdvanceInvoiceResponse> {
+    return unwrap(await advanceInvoice(this._client, request, options))
+  }
+
+  /**
+   * Send the invoice to the customer
+   *
+   * Approve a billing invoice.
+   *
+   * This call instantly sends the invoice to the customer using the configured
+   * billing profile app.
+   *
+   * This call is valid in two invoice statuses:
+   *
+   * - draft: the invoice will be sent to the customer, the invoice state becomes
+   * issued
+   * - manual_approval_needed: the invoice will be sent to the customer, the invoice
+   * state becomes issued
+   *
+   * POST /openmeter/billing/invoices/{invoiceId}/approve
+   */
+  async approve(
+    request: ApproveInvoiceRequest,
+    options?: RequestOptions,
+  ): Promise<ApproveInvoiceResponse> {
+    return unwrap(await approveInvoice(this._client, request, options))
+  }
+
+  /**
+   * Retry advancing the invoice after a failed attempt
+   *
+   * Retry sending a billing invoice.
+   *
+   * Retry advancing the invoice after a failed attempt.
+   *
+   * The action can be called when the invoice's statusDetails' actions field contain
+   * the "retry" action.
+   *
+   * POST /openmeter/billing/invoices/{invoiceId}/retry
+   */
+  async retry(
+    request: RetryInvoiceRequest,
+    options?: RequestOptions,
+  ): Promise<RetryInvoiceResponse> {
+    return unwrap(await retryInvoice(this._client, request, options))
+  }
+
+  /**
+   * Snapshot quantities for usage based line items
+   *
+   * Snapshot quantities for usage-based line items.
+   *
+   * This call will snapshot the quantities for all usage based line items in the
+   * invoice.
+   *
+   * This call is only valid in draft.waiting_for_collection status, where the
+   * collection period can be skipped using this action.
+   *
+   * POST /openmeter/billing/invoices/{invoiceId}/snapshot-quantities
+   */
+  async snapshotQuantities(
+    request: SnapshotQuantitiesInvoiceRequest,
+    options?: RequestOptions,
+  ): Promise<SnapshotQuantitiesInvoiceResponse> {
+    return unwrap(
+      await snapshotQuantitiesInvoice(this._client, request, options),
+    )
+  }
 }
 
 export class InternalCurrencies {