chore: invocing fixes

[turip]

Overview

Two changes:

• The detailed line type was not properly set in the schema (the detailed string was used previously in the actual response)
• Deprecate detailed line's invoiceAt field, as that is always the same as the parent line's

Notes for reviewer

Summary by CodeRabbit

• Bug Fixes

  • Corrected invoice line status enumeration value for consistency.

• API Enhancements

  • Improved invoice line API schemas with expanded documentation, detailed examples, and comprehensive validation rules.
  • Deprecated invoiceAt field on invoice lines.
  • Extended notification event and entitlement payload schemas with richer data representation.
  • Enhanced parameter and response schemas across multiple endpoints.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request updates API schemas across specification, OpenAPI documentation, and generated TypeScript types to refine invoice line handling, introduce new invoice management capabilities, and enrich notification event payloads. Key changes include renaming an InvoiceLineStatus enum value from 'detail' to 'detailed', adding a deprecated invoiceAt field to invoice line schemas, introducing new invoice-related request/response models, and expanding response schemas with additional fields, descriptions, and example values.

Changes

Cohort / File(s)	Summary
Invoice Specification Updates api/spec/src/billing/invoices/invoice.tsp	Updated InvoiceLineStatus enum to change 'detail' to 'detailed'; modified InvoiceDetailedLine to exclude additional base properties and added deprecated invoiceAt field.
OpenAPI Schema Definitions api/openapi.cloud.yaml, api/openapi.yaml	Added deprecated invoiceAt property to InvoiceLine and InvoiceDetailedLine schemas with datetime format and descriptions; introduced new invoice management schemas including InvoicePendingLineCreate, InvoiceSimulationInput, and related models for enhanced invoice lifecycle management.
Generated TypeScript Types api/client/javascript/src/client/schemas.ts	Updated enum string literals to match specification changes; extended notification event payload schemas with additional fields and detailed descriptions; enriched response schemas with detailed format annotations, examples, and status codes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

The changes span multiple file types and layers (specification, OpenAPI, generated types) with a mix of enum updates, deprecations, and new schema introductions. While some patterns repeat across files, each schema adjustment requires separate reasoning to verify correctness and backward compatibility.

Possibly related PRs

• fix: updating gathering invoices with split lines #2918 — Updates runtime behavior for InvoiceLineStatus::Split, directly related to the InvoiceLineStatus enum member change from 'detail' to 'detailed'.
• feat: invoice discounts api v2 #2576 — Modifies the same invoice specification file (api/spec/src/billing/invoices/invoice.tsp) and related invoice line schemas.
• fix: populate invoice at #2783 — Handles the invoiceAt timestamp field backfill and population, complementing the schema-level deprecation and definition changes introduced here.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "chore: invocing fixes" is related to the changeset and refers to genuine invoice-related modifications. The changes include fixing the InvoiceLineStatus enum (changing 'detail' to 'detailed'), deprecating the invoiceAt field in InvoiceDetailedLine, and expanding invoice schema definitions across multiple files. While the title is somewhat generic and doesn't capture the specific nature of the fixes, it correctly identifies the primary domain of the changes. Additionally, there is a minor typo in the title ("invocing" instead of "invoicing") that should be corrected.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/invoicing-fixes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

api/spec/src/billing/invoices/invoice.tsp (1)

765-772: Consider making the deprecated invoiceAt field optional.

The deprecation strategy is implemented correctly with a clear message directing users to the parent line's invoiceAt field. However, the field is still required (no ? operator), which is unusual for deprecated fields and may cause confusion during the transition period.

Consider making the field optional to signal its deprecated status more clearly:

  /**
   * The time this line item should be invoiced.
   */
  #deprecated "Use invoiceAt from the parent line instead, this field will be removed in the future versions of the API"
  @visibility(Lifecycle.Read, Lifecycle.Create, Lifecycle.Update)
- invoiceAt: DateTime;
+ invoiceAt?: DateTime;

Alternatively, if the field must remain required for backward compatibility, consider documenting this requirement in the deprecation notice.

api/client/javascript/src/client/schemas.ts (1)

6404-6404: Docstring has typos.

Please fix the wording to something like “Subscriptions are the references to the subscriptions that this line is related to.” Right now it reads “Subscription are … subscritpions.”

api/openapi.cloud.yaml (1)

18082-18087: Mark invoiceAt as read-only.

We’re deprecating this field because it’s always derived from the parent line, so clients shouldn’t be sending it back. Without readOnly: true, the spec still advertises it as writable. Flag it read-only to match the actual behavior and avoid client confusion.

         invoiceAt:
           type: string
           format: date-time
           description: The time this line item should be invoiced.
           example: '2023-01-01T01:01:01.001Z'
           deprecated: true
+          readOnly: true

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 594f2d6 and 43ac147.

📒 Files selected for processing (4)

• api/client/javascript/src/client/schemas.ts (2 hunks)
• api/openapi.cloud.yaml (2 hunks)
• api/openapi.yaml (2 hunks)
• api/spec/src/billing/invoices/invoice.tsp (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)

• GitHub Check: Artifacts / Benthos Collector Container image
• GitHub Check: Artifacts / Container image
• GitHub Check: Code Generators
• GitHub Check: Migration Checks
• GitHub Check: Lint
• GitHub Check: Test
• GitHub Check: Build
• GitHub Check: Repository Scan
• GitHub Check: Analyze (go)

🔇 Additional comments (5)

api/spec/src/billing/invoices/invoice.tsp (2)

765-772: LGTM! Clear deprecation strategy.

The approach of omitting invoiceAt from the base properties and then re-introducing it as a deprecated field is a good pattern for managing the deprecation lifecycle. The deprecation message clearly guides users to use the parent line's invoiceAt instead and sets expectations for future removal.

---

477-477: Confirm removal of the old 'detail' enum value and update migration/docs

• Run a targeted search for any use of the old literal, e.g.:

  rg -nP "InvoiceLineStatus\.(detail|detailed)" -g '*.ts' -g '*.go' -g '*.py'

• Verify client-SDKs, examples, tests and OpenAPI samples no longer reference 'detail'
• Add release-note entry for this breaking change and include any DB-migration steps to handle existing records

api/openapi.yaml (2)

18565-18570: Good call on deprecating invoiceAt.

Exposing it once at the base line level while marking it deprecated keeps clients aware without encouraging new usage. Implementation looks correct.

---

19241-19245: Enum rename matches the actual status token.

Switching to detailed brings the schema in sync with produced values and unblocks client codegen.

api/openapi.cloud.yaml (1)

18567-18571: Verify ‘detailed’ enum in API responses. Ensure the backend emits and accepts the detailed status literal—sample your staging or production API (e.g., curl -sS https://api.staging.openmeter.io/invoices | jq -r '.[].status') to confirm.