feat(spec): V3 visibility and summary updates

[tothandras]

Summary by CodeRabbit

• New Features

  • Product catalog API is now available with dedicated endpoints for managing and configuring plans, addons, and plan-specific addon offerings.

• Documentation

  • Improved operation documentation descriptions and summaries for greater clarity.
  • Updated API operation stability and availability classifications to accurately reflect current maturity levels and recommended usage patterns for client integrations.

[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: 72be66bc-5390-4f80-86d8-7db4b7f72b7d

📥 Commits

Reviewing files that changed from the base of the PR and between f3eec6f and 4a4fbdb.

⛔ 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/src/customers/charges/operations.tsp
• api/spec/packages/aip/src/customers/credits/operations.tsp
• api/spec/packages/aip/src/events/operations.tsp
• api/spec/packages/aip/src/features/operations.tsp
• api/spec/packages/aip/src/konnect.tsp
• api/spec/packages/aip/src/meters/operations.tsp
• api/spec/packages/aip/src/productcatalog/operations.tsp
• api/v3/api.gen.go

💤 Files with no reviewable changes (1)

• api/spec/packages/aip/src/meters/operations.tsp

---

📝 Walkthrough

Walkthrough

API specification updates across multiple TypeSpec files and generated Go code: adding extension metadata (Private, Unstable, Internal) to customer charge and credit operations; removing Private extension from feature, meter, and product catalog operations; introducing new product catalog endpoints for plans and addons under /openmeter path; updating OpenAPI summary text for clarity.

Changes

Cohort / File(s)	Summary
Customer Operations Extensions api/spec/packages/aip/src/customers/charges/operations.tsp, api/spec/packages/aip/src/customers/credits/operations.tsp	Added @extension decorators marking operations as Private, Unstable, and/or Internal for customer charge and credit-related endpoints.
Events Operations api/spec/packages/aip/src/events/operations.tsp	Annotated the list-metering-events operation with Unstable and Internal extension decorators.
Feature & Meter Operations api/spec/packages/aip/src/features/operations.tsp, api/spec/packages/aip/src/meters/operations.tsp	Removed Private extension decorators from feature operations (list, create, get, update, delete) and meter operations (update, query, queryCsv). Simplified OpenAPI summary strings for feature operations.
Product Catalog Operations api/spec/packages/aip/src/productcatalog/operations.tsp	Removed Private extension decorators from plan, addon, and plan-addon operations; shortened OpenAPI summary text for improved brevity.
API Endpoints api/spec/packages/aip/src/konnect.tsp	Added three new product catalog endpoint interfaces (PlansEndpoints, AddonsEndpoints, PlanAddonEndpoints) under /openmeter routes with ProductCatalogTag metadata.
Generated Go Code api/v3/api.gen.go	Updated embedded swagger spec and simplified doc comments in ServerInterface and Unimplemented handler methods to match API specification changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(api): resolve TypeSpec AIP compiler warnings #4079 — Updates the embedded swagger spec payload in the generated Go file to reflect OpenAPI documentation changes.
• fix(api): v3 meter query path #4205 — Refactors meter query operations in the specification, overlapping with the Private extension removal from meters in this PR.
• feat: implement external payment endpoints #4158 — Implements API handlers for customer credit operations that are now marked with Private/Unstable/Internal extensions in this PR.

Suggested labels

area/api

Suggested reviewers

• turip
• borosr
• gergely-kurucz-konghq

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main changes: visibility updates (extension decorators for Private/Unstable/Internal) and summary text refinements across multiple API specification files.
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-v3-change-endpoint-visibilities

---

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

_{Review rate limit: 6/8 reviews remaining, refill in 13 minutes and 14 seconds.}

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