feat: add workflow apps and add a better description to service period

Author: borosr

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

@@ -116,6 +116,7 @@ export type {
   SubscriptionReference,
   AddonReference,
   AppReference,
+  InvoiceWorkflowAppReference,
   ChargeReference,
   CurrencyFiat,
   FeatureReference,
@@ -218,6 +219,7 @@ export type {
   PlanAddon,
   CreatePlanAddonRequest,
   ProfileAppReferences,
+  InvoiceWorkflowAppsReferences,
   ListEventsParamsFilter,
   ResourceFilters,
   FieldFilters,
@@ -272,14 +274,14 @@ export type {
   Supplier,
   AppStripeCreateCheckoutSessionRequestOptions,
   TaxCodePagePaginatedResponse,
-  InvoiceWorkflowSettings,
   InvoiceDetailedLine,
   CurrencyPagePaginatedResponse,
   GovernanceQueryResult,
   Feature,
   CreateFeatureRequest,
   UpdateFeatureRequest,
   CreditGrantPagePaginatedResponse,
+  InvoiceWorkflowSettings,
   BadRequest,
   InvoiceBase,
   CustomerStripeCreateCheckoutSessionRequest,
@@ -345,9 +347,9 @@ export type {
   IngestedEventPaginatedResponseInput,
   MeterQueryRequestInput,
   AppStripeCreateCheckoutSessionRequestOptionsInput,
-  InvoiceWorkflowSettingsInput,
   InvoiceDetailedLineInput,
   CreditGrantPagePaginatedResponseInput,
+  InvoiceWorkflowSettingsInput,
   BadRequestInput,
   CustomerStripeCreateCheckoutSessionRequestInput,
   WorkflowCollectionSettingsInput,

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

@@ -1579,6 +1579,15 @@ export const appReference = z
   })
   .describe('App reference.')
 
+export const invoiceWorkflowAppReference = z
+  .object({
+    id: ulid,
+  })
+
+  .describe(
+    'BillingInvoiceWorkflowAppReference Can be used as a short reference to an app if the full app object is not needed.',
+  )
+
 export const chargeReference = z
   .object({
     id: ulid,
@@ -3277,6 +3286,17 @@ export const profileAppReferences = z
   })
   .describe('References to the applications used by a billing profile.')
 
+export const invoiceWorkflowAppsReferences = z
+  .object({
+    tax: invoiceWorkflowAppReference,
+    invoicing: invoiceWorkflowAppReference,
+    payment: invoiceWorkflowAppReference,
+  })
+
+  .describe(
+    'BillingProfileAppReferences represents the references (id, type) to the apps used by a billing profile',
+  )
+
 export const listEventsParamsFilter = z
   .object({
     id: stringFieldFilter.optional(),
@@ -4091,6 +4111,13 @@ export const planAddonPagePaginatedResponse = z
   })
   .describe('Page paginated response.')
 
+export const invoiceWorkflowAppsOrReferences = z
+  .union([invoiceWorkflowAppsReferences])
+
+  .describe(
+    "Union of either the full app references or just the IDs of the apps used for this invoice's workflow. The `apps` field on `BillingInvoiceWorkflowSettings` is a union because the invoice may have been created before the app references were available. In that case only the IDs are returned, and the full references can be retrieved via separate API calls.",
+  )
+
 export const ingestedEventPaginatedResponse = z
   .object({
     data: z.array(ingestedEvent),
@@ -4260,16 +4287,6 @@ export const taxCodePagePaginatedResponse = z
   })
   .describe('Page paginated response.')
 
-export const invoiceWorkflowSettings = z
-  .object({
-    source_billing_profile: profileReference,
-    workflow: invoiceWorkflow,
-  })
-
-  .describe(
-    'Snapshot of the billing workflow configuration captured at invoice creation.',
-  )
-
 export const invoiceDetailedLine = z
   .object({
     id: ulid,
@@ -4420,6 +4437,17 @@ export const creditGrantPagePaginatedResponse = z
   })
   .describe('Page paginated response.')
 
+export const invoiceWorkflowSettings = z
+  .object({
+    apps: invoiceWorkflowAppsOrReferences.optional(),
+    source_billing_profile: profileReference,
+    workflow: invoiceWorkflow,
+  })
+
+  .describe(
+    'Snapshot of the billing workflow configuration captured at invoice creation.',
+  )
+
 export const badRequest = z
   .intersection(
     baseError,

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

@@ -659,6 +659,12 @@ export interface AppReference {
   id: string
 }
 
+/** BillingInvoiceWorkflowAppReference Can be used as a short reference to an app if the full app object is not needed. */
+export interface InvoiceWorkflowAppReference {
+  /** The ID of the app. */
+  id: string
+}
+
 /** Reference to a charge associated with an invoice line. */
 export interface ChargeReference {
   /** Unique identifier for the charge. */
@@ -2036,6 +2042,16 @@ export interface ProfileAppReferences {
   payment: AppReference
 }
 
+/** BillingProfileAppReferences represents the references (id, type) to the apps used by a billing profile */
+export interface InvoiceWorkflowAppsReferences {
+  /** The tax app used for this workflow */
+  tax: InvoiceWorkflowAppReference
+  /** The invoicing app used for this workflow */
+  invoicing: InvoiceWorkflowAppReference
+  /** The payment app used for this workflow */
+  payment: InvoiceWorkflowAppReference
+}
+
 /** Filter options for listing ingested events. */
 export interface ListEventsParamsFilter {
   /** Filter events by ID. */
@@ -2828,14 +2844,6 @@ export interface TaxCodePagePaginatedResponse {
   meta: PaginatedMeta
 }
 
-/** Snapshot of the billing workflow configuration captured at invoice creation. */
-export interface InvoiceWorkflowSettings {
-  /** The billing profile that was the source of this workflow snapshot. */
-  source_billing_profile: ProfileReference
-  /** The workflow configuration that was active when the invoice was created. Only the fields that are meaningful at the per-invoice level are included: invoicing behaviour (auto-advance, draft period) and payment settings (collection method, due date). Profile-wide settings such as collection alignment, progressive billing, and tax policy are omitted. */
-  workflow: InvoiceWorkflow
-}
-
 /** A detailed (child) sub-line belonging to a parent invoice line. Detailed lines represent the individual flat-fee components that make up a usage-based parent line after quantity snapshotting. */
 export interface InvoiceDetailedLine {
   id: string
@@ -2933,6 +2941,16 @@ export interface CreditGrantPagePaginatedResponse {
   meta: PaginatedMeta
 }
 
+/** Snapshot of the billing workflow configuration captured at invoice creation. */
+export interface InvoiceWorkflowSettings {
+  /** The apps that will be used to orchestrate the invoice's workflow. */
+  apps?: InvoiceWorkflowAppsReferences
+  /** The billing profile that was the source of this workflow snapshot. */
+  source_billing_profile: ProfileReference
+  /** The workflow configuration that was active when the invoice was created. Only the fields that are meaningful at the per-invoice level are included: invoicing behaviour (auto-advance, draft period) and payment settings (collection method, due date). Profile-wide settings such as collection alignment, progressive billing, and tax policy are omitted. */
+  workflow: InvoiceWorkflow
+}
+
 /** Bad Request. */
 export interface BadRequest extends BaseError {
   /** The list of parameters that failed validation. */
@@ -3241,7 +3259,7 @@ export interface InvoiceStandardLine {
   type: 'standard_line'
   /** Indicates whether this line item's lifecycle is controlled by OpenMeter or manually overridden by the API user. */
   lifecycle_controller: 'system' | 'manual'
-  /** The service period covered by this line item. */
+  /** The service period covered by this invoice, spanning the earliest line start to the latest line end across all of its lines. For an invoice with no lines the period is empty, which means `from` will be equal to `to`. */
   service_period: ClosedPeriod
   /** Aggregated financial totals for the line item. */
   totals: Totals
@@ -3874,13 +3892,6 @@ export interface AppStripeCreateCheckoutSessionRequestOptionsInput {
   tax_id_collection?: AppStripeCreateCheckoutSessionTaxIdCollectionInput
 }
 
-export interface InvoiceWorkflowSettingsInput {
-  /** The billing profile that was the source of this workflow snapshot. */
-  source_billing_profile: ProfileReference
-  /** The workflow configuration that was active when the invoice was created. Only the fields that are meaningful at the per-invoice level are included: invoicing behaviour (auto-advance, draft period) and payment settings (collection method, due date). Profile-wide settings such as collection alignment, progressive billing, and tax policy are omitted. */
-  workflow: InvoiceWorkflowInput
-}
-
 export interface InvoiceDetailedLineInput {
   id: string
   /** Display name of the resource. Between 1 and 256 characters. */
@@ -3917,6 +3928,15 @@ export interface CreditGrantPagePaginatedResponseInput {
   meta: PaginatedMeta
 }
 
+export interface InvoiceWorkflowSettingsInput {
+  /** The apps that will be used to orchestrate the invoice's workflow. */
+  apps?: InvoiceWorkflowAppsReferences
+  /** The billing profile that was the source of this workflow snapshot. */
+  source_billing_profile: ProfileReference
+  /** The workflow configuration that was active when the invoice was created. Only the fields that are meaningful at the per-invoice level are included: invoicing behaviour (auto-advance, draft period) and payment settings (collection method, due date). Profile-wide settings such as collection alignment, progressive billing, and tax policy are omitted. */
+  workflow: InvoiceWorkflowInput
+}
+
 export interface BadRequestInput extends BaseErrorInput {
   /** The list of parameters that failed validation. */
   invalid_parameters: (
@@ -4002,7 +4022,7 @@ export interface InvoiceStandardLineInput {
   type: 'standard_line'
   /** Indicates whether this line item's lifecycle is controlled by OpenMeter or manually overridden by the API user. */
   lifecycle_controller: 'system' | 'manual'
-  /** The service period covered by this line item. */
+  /** The service period covered by this invoice, spanning the earliest line start to the latest line end across all of its lines. For an invoice with no lines the period is empty, which means `from` will be equal to `to`. */
   service_period: ClosedPeriod
   /** Aggregated financial totals for the line item. */
   totals: Totals

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

@@ -365,6 +365,13 @@ model Supplier {
  */
 @friendlyName("BillingInvoiceWorkflowSettings")
 model InvoiceWorkflowSettings {
+  /**
+   * The apps that will be used to orchestrate the invoice's workflow.
+   */
+  @visibility(Lifecycle.Read)
+  @summary("Application that generated the invoice")
+  apps?: InvoiceWorkflowAppsOrReferences;
+
   /**
    * The billing profile that was the source of this workflow snapshot.
    */
@@ -385,6 +392,58 @@ model InvoiceWorkflowSettings {
   workflow: BillingInvoiceWorkflow;
 }
 
+/**
+ * Union of either the full app references or just the IDs of the apps used for
+ * this invoice's workflow.
+ *
+ * The `apps` field on `BillingInvoiceWorkflowSettings` is a union because the
+ * invoice may have been created before the app references were available. In that
+ * case only the IDs are returned, and the full references can be retrieved via
+ * separate API calls.
+ */
+@friendlyName("BillingInvoiceWorkflowAppsOrReferences")
+union InvoiceWorkflowAppsOrReferences {
+  references: InvoiceWorkflowAppsReferences,
+}
+
+/**
+ * BillingProfileAppReferences represents the references (id, type) to the apps
+ * used by a billing profile
+ */
+@friendlyName("BillingInvoiceWorkflowAppsReferences")
+model InvoiceWorkflowAppsReferences {
+  /**
+   * The tax app used for this workflow
+   */
+  @visibility(Lifecycle.Read)
+  tax: InvoiceWorkflowAppReference;
+
+  /**
+   * The invoicing app used for this workflow
+   */
+  @visibility(Lifecycle.Read)
+  invoicing: InvoiceWorkflowAppReference;
+
+  /**
+   * The payment app used for this workflow
+   */
+  @visibility(Lifecycle.Read)
+  payment: InvoiceWorkflowAppReference;
+}
+
+/**
+ * BillingInvoiceWorkflowAppReference
+ *
+ * Can be used as a short reference to an app if the full app object is not needed.
+ */
+@friendlyName("BillingInvoiceWorkflowAppReference")
+model InvoiceWorkflowAppReference {
+  /**
+   * The ID of the app.
+   */
+  id: Shared.ULID;
+}
+
 /**
  * Invoice-level snapshot of the workflow configuration.
  *
@@ -630,7 +689,11 @@ model InvoiceStandardLine {
   lifecycle_controller: Shared.LifecycleController;
 
   /**
-   * The service period covered by this line item.
+   * The service period covered by this invoice, spanning the earliest line start to
+   * the latest line end across all of its lines.
+   *
+   * For an invoice with no lines the period is empty, which means `from` will be
+   * equal to `to`.
    */
   @visibility(Lifecycle.Read)
   @summary("Service period")