feat(api): expose charge system intent

[turip]

Summary

Adds a system_intent read model to v3 customer charge responses for charges whose customer-facing intent is manually overridden while the original lifecycle controller remains system-owned.

Behavior

• Top-level charge fields continue to represent the effective customer-facing intent.
• system_intent is returned only when a manual override shadows a system lifecycle-controller intent.
• Freshly created manually managed charges do not receive system_intent, because there is no shadowed system intent.
• The shadowed system intent includes the overridable fields and optional deleted_at, so API consumers can see background system updates even while a manual override is active.

Validation

• make gen-api
• make generate
• make etoe

Summary by CodeRabbit

• New Features
  • Charge responses now expose additional optional “system intent” details when a manual override is active (for both flat-fee and usage-based charges).
• Bug Fixes
  • Updated charge conversion so the new system-intent fields are derived correctly (and omit them when not applicable).
• Tests
  • Expanded billing invoice override and unit test coverage to validate system-intent amounts and ensure SystemIntent remains absent in scenarios where no override applies.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c159854c-f791-4b44-9976-dc05525afcb1

📥 Commits

Reviewing files that changed from the base of the PR and between 781b54b and 3491ce4.

⛔ Files ignored due to path filters (1)

• api/v3/openapi.yaml is excluded by !**/openapi.yaml

📒 Files selected for processing (8)

• api/spec/packages/aip-client-javascript/src/index.ts
• api/spec/packages/aip-client-javascript/src/models/schemas.ts
• api/spec/packages/aip-client-javascript/src/models/types.ts
• api/spec/packages/aip/src/customers/charges/charges.tsp
• api/v3/api.gen.go
• api/v3/handlers/customers/charges/convert.go
• api/v3/handlers/customers/charges/convert_test.go
• e2e/billinginvoice_override_test.go

✅ Files skipped from review due to trivial changes (1)

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

🚧 Files skipped from review as they are similar to previous changes (5)

• api/spec/packages/aip-client-javascript/src/index.ts
• api/spec/packages/aip/src/customers/charges/charges.tsp
• e2e/billinginvoice_override_test.go
• api/spec/packages/aip-client-javascript/src/models/schemas.ts
• api/v3/handlers/customers/charges/convert.go

---

📝 Walkthrough

Walkthrough

Adds system_intent models and fields for flat-fee and usage-based charges across the API spec, generated TypeScript/Zod outputs, Go conversion logic, and e2e coverage. The converters now populate these fields when an override exists, and tests validate the mapped values and nil cases.

Changes

System Intent for Charge Overrides

Layer / File(s)	Summary
TypeSpec model definitions and charge field additions api/spec/packages/aip/src/customers/charges/charges.tsp	Defines ChargeFlatFeeSystemIntent and ChargeUsageBasedSystemIntent, and adds optional system_intent fields to ChargeFlatFee and ChargeUsageBased with Lifecycle.Read visibility.
Generated TypeScript interfaces api/spec/packages/aip-client-javascript/src/models/types.ts, api/spec/packages/aip-client-javascript/src/index.ts	Adds the two new system-intent interfaces, extends ChargeFlatFee/ChargeUsageBased with optional system_intent, and updates the export order and pagination response placement.
Generated Zod schemas api/spec/packages/aip-client-javascript/src/models/schemas.ts	Adds chargeFlatFeeSystemIntent and chargeUsageBasedSystemIntent, extends chargeFlatFee/chargeUsageBased with optional system_intent, and moves related charge exports.
Go charge-to-API converters api/v3/handlers/customers/charges/convert.go, api/v3/handlers/customers/charges/convert_test.go	Adds helpers to build system-intent payloads, wires them into both charge converters, and adds a unit test for the usage-based price conversion error path.
E2E test assertions e2e/billinginvoice_override_test.go	Captures system amounts from pre-edit lines, adds SystemIntent assertions for updated/deleted flat-fee charges, and checks nil SystemIntent for kept/created flat-fees and usage-based charges.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• openmeterio/openmeter#4556: Shares the same flat-fee and usage-based override intent data path that this PR exposes through system_intent.
• openmeterio/openmeter#4571: Touches the same api/v3/handlers/customers/charges/convert.go flow for flat-fee and usage-based charge conversion.
• openmeterio/openmeter#4586: Adds and validates the override/delete semantics that this PR maps into system_intent.deleted_at.

Suggested labels: release-note/feature, kind/feature

Suggested reviewers: tothandras, mark-vass-konghq

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: exposing charge system intent in the API.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/charge-patch-source-routing

---

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.}

[greptile-apps]

Greptile Summary

This PR adds a system-owned intent view to customer charge responses. The main changes are:

• New system_intent models for flat-fee and usage-based charges.
• Go conversion logic that maps shadowed system intents onto v3 charge responses.
• Generated OpenAPI and TypeScript SDK updates for the new response fields.
• Override tests covering when system_intent should appear or stay absent.

Confidence Score: 4/5

This is close, but the charge conversion behavior still needs follow-up before merging.

• The new response field is wired through the API and generated clients.
• Flat-fee override coverage checks the expected presence and absence of system_intent.
• The usage-based conversion path can still reject a readable charge when the shadowed system price cannot be mapped to the v3 price shape.

api/v3/handlers/customers/charges/convert.go

Important Files Changed

Filename	Overview
api/v3/handlers/customers/charges/convert.go	Adds system intent conversion for flat-fee and usage-based charge responses.
api/v3/handlers/customers/charges/convert_test.go	Adds coverage around usage-based system intent conversion with unsupported base prices.
e2e/billinginvoice_override_test.go	Extends invoice override coverage for flat-fee charge system intent responses.
api/spec/packages/aip/src/customers/charges/charges.tsp	Defines the new charge system intent response models in the API spec.

_{Reviews (2): Last reviewed commit: "fix(api): remove immutable system intent..." | Re-trigger Greptile}