chore(api): refactor names and patch typespec

[tothandras]

Summary by CodeRabbit

• New Features

  • Added app mappings support to tax codes for enhanced configuration tracking.

• Updates

  • Standardized tax code reference structure across billing and credit configurations for consistency.
  • Restructured credit grant model with typed, organized components for improved usability.
  • Clarified subscription sorting documentation regarding default ascending order behavior.

[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: 0fa2b121-351b-40fc-ac38-fba50aad051b

📥 Commits

Reviewing files that changed from the base of the PR and between ccae3b8 and bef0336.

⛔ Files ignored due to path filters (4)

• api/spec/patches/@typespec__compiler.patch is excluded by !api/spec/patches/**
• api/spec/patches/@typespec__openapi3.patch is excluded by !api/spec/patches/**
• api/spec/pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
• api/v3/openapi.yaml is excluded by !**/openapi.yaml

📒 Files selected for processing (10)

• api/spec/packages/aip/lib/rules/friendly-name.js
• api/spec/packages/aip/src/billing/tax.tsp
• api/spec/packages/aip/src/customers/credits/grant.tsp
• api/spec/packages/aip/src/subscriptions/operations.tsp
• api/spec/packages/aip/src/tax/codes.tsp
• api/v3/api.gen.go
• api/v3/handlers/billingprofiles/convert.go
• api/v3/handlers/customers/charges/convert.go
• api/v3/handlers/customers/charges/convert_test.go
• api/v3/handlers/customers/credits/convert.go

💤 Files with no reviewable changes (1)

• api/spec/packages/aip/src/tax/codes.tsp

---

📝 Walkthrough

Walkthrough

This PR consolidates a tax code reference type migration and credit grant schema extraction. The main change swaps BillingTaxCodeReference for Shared.ResourceReference<Tax.TaxCode> across API specs and Go handlers, while extracting inline object shapes from CreditGrant into dedicated models. Additionally, the friendly-name detection rule is refactored to use a shared helper, and subscription operation docs are clarified.

Changes

Tax Code Reference Migration and Credit Grant Schema Refactoring

Layer / File(s)	Summary
Tax Code Reference Schema Migration api/spec/packages/aip/src/tax/codes.tsp, api/spec/packages/aip/src/billing/tax.tsp, api/spec/packages/aip/src/customers/credits/grant.tsp	Schema definitions migrate from BillingTaxCodeReference to Shared.ResourceReference<Tax.TaxCode> across billing and credit grant configs. The tax codes spec adds TaxCodeAppMapping with lifecycle visibility and removes the now-obsolete BillingTaxCodeReference type.
Credit Grant Schema Extraction api/spec/packages/aip/src/customers/credits/grant.tsp	Inline purchase, invoice, and filters object shapes are extracted into dedicated models CreditGrantPurchase, CreditGrantInvoiceReference, and CreditGrantFilters. The purchase field now references the new model instead of an inline object.
Billing & Charge Handlers Tax Code Conversion api/v3/handlers/billingprofiles/convert.go, api/v3/handlers/customers/charges/convert.go, api/v3/handlers/customers/charges/convert_test.go	Go handlers update tax code reference handling to use api.TaxCodeReference instead of api.BillingTaxCodeReference. Test expectations are updated to match the new reference type construction across both billing profile and charge conversion paths.
Credit Grant Conversion Refactoring api/v3/handlers/customers/credits/convert.go	toAPICreditGrantPurchase now returns api.BillingCreditGrantPurchase for invoice and external settlement paths (promotional still returns nil). Tax config conversion switches to api.TaxCodeReference, and the tax config input parameter is updated to accept *api.CreateCreditGrantTaxConfig.

Friendly Name Rule Refactoring

Layer / File(s)	Summary
Friendly Name Detection Refactoring api/spec/packages/aip/lib/rules/friendly-name.js	The friendly-name detection is centralized: all node handlers (interface, model, enum, union) now use the shared getFriendlyName(context.program, node) helper instead of locally checking node.decorators for '$friendlyName'.

Documentation & Notes

• api/spec/packages/aip/src/subscriptions/operations.tsp (range_b6acdb406e31): The list-subscriptions operation's sort parameter documentation is updated to clarify that the asc suffix is optional with ascending as default, and desc specifies descending order.

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly Related PRs

• openmeterio/openmeter#4158: Modifies credit grant conversion in api/v3/handlers/customers/credits/convert.go, refactoring purchase/tax-code handling with similar TaxCodeReference-based conversion updates.
• openmeterio/openmeter#4320: Adds organization default tax-code handlers that also translate tax references via api.TaxCodeReference as part of the same API reference migration.
• openmeterio/openmeter#4263: Modifies the customers/charges tax-code conversion path and introduces mapping of TaxCodeID into API tax-code references.

Suggested Labels

area/api

Suggested Reviewers

• turip

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is vague and overly broad, using generic terms like 'refactor names and patch' without clearly conveying the specific changes made across multiple API specifications and implementations.	Consider a more specific title like 'refactor tax code references across billing and credits APIs' or 'consolidate tax code reference types in API specs' to better reflect the primary changes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 chore/api-review

---

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