feat(api): add app endpoints to v3 api

[gergely-kurucz-konghq]

Summary by CodeRabbit

• New Features

  • GetApp endpoint to fetch app details
  • ListApps endpoint with pagination to browse apps

• Bug Fixes / Reliability

  • Improved error handling and validation during API mappings and conversions

• Infrastructure

  • App service integrated into the v3 API server and routed into request handling

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds v3 app endpoints (ListApps, GetApp), wires AppService into the v3 server, and implements conversion/mapping code to translate internal app types and marketplace listings into v3 API representations with explicit error propagation.

Changes

Cohort / File(s)	Summary
Conversion layer api/v3/handlers/apps/convert.go, api/v3/handlers/apps/convert.gen.go	New and updated converters: error-aware enum conversion (ConvertAppTypeToV3Api), listing conversion (ConvertMarketplaceListingToV3Api), batch converter (ConvertAppsToBillingApps), metadata→labels, and paginated response mapping. MapAppToAPI implements per-type mappings (Stripe, Sandbox, CustomInvoicing) with validation and error returns.
Handler interface & wiring api/v3/handlers/apps/handler.go	Adds Handler interface, concrete handler struct, and New constructor to encapsulate namespace resolution, app service, and handler options.
Endpoint handlers api/v3/handlers/apps/list_app.go, api/v3/handlers/apps/get_app.go	Implements ListApps (pagination arg parsing, validation, service call, conversion, response) and GetApp (namespace resolve, path ID, service call, conversion). Uses typed HTTP transport plumbing and JSON response encoder.
Server integration & routes api/v3/server/server.go, api/v3/server/routes.go, openmeter/server/server.go	Adds AppService to server Config, initializes appsHandler in server creation, validates AppService presence, and routes ListApps/GetApp to the new handler.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant ListAppsHandler
    participant AppService
    participant Converter
    Client->>ListAppsHandler: GET /apps?page=&size=
    ListAppsHandler->>ListAppsHandler: resolve namespace, validate page
    ListAppsHandler->>AppService: ListApps(namespace, page)
    AppService-->>ListAppsHandler: ([]app.App, PageMeta)
    ListAppsHandler->>Converter: ConvertAppsToBillingApps(apps)
    loop per app
        Converter->>Converter: MapAppToAPI(app)
        Converter->>Converter: ConvertAppTypeToV3Api(type)
        Converter->>Converter: ConvertMetadataToLabels(metadata)
    end
    Converter-->>ListAppsHandler: []v3.BillingApp
    ListAppsHandler->>Converter: ConvertToListAppResponse(paginated)
    Converter-->>ListAppsHandler: v3.AppPagePaginatedResponse
    ListAppsHandler-->>Client: 200 OK (paginated apps)

Loading

sequenceDiagram
    participant Client
    participant GetAppHandler
    participant AppService
    participant Converter
    Client->>GetAppHandler: GET /apps/{appId}
    GetAppHandler->>GetAppHandler: resolve namespace, extract appId
    GetAppHandler->>AppService: GetApp(namespace, appId)
    AppService-->>GetAppHandler: app.App
    GetAppHandler->>Converter: MapAppToAPI(app)
    Converter->>Converter: ConvertAppTypeToV3Api(type)
    Converter->>Converter: ConvertMetadataToLabels(metadata)
    Converter-->>GetAppHandler: v3.BillingApp
    GetAppHandler-->>Client: 200 OK (single app)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: skaffold custom invoicing #2678 — touches app-to-API conversion surface and enum/app-type handling, overlapping MapAppToAPI and marketplace listing conversions.

Suggested labels

area/apps, area/api

Suggested reviewers

• chrisgacsal
• tothandras

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding app endpoints to the v3 API, which matches the core work across all modified files.

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

✨ 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 feat/api-v3-apps-handlers

---

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: 3

🤖 Fix all issues with AI agents

In `@api/v3/handlers/apps/convert.gen.go`:
- Around line 13-27: ConvertAppTypeToV3Api currently panics on unknown
app.AppType in the switch default; replace that panic with a safe fallback or an
explicit error return: either map the default case to a safe enum like
v3.BillingAppTypeUnknown/v3.BillingAppTypeUnspecified (modify the default branch
of ConvertAppTypeToV3Api to assign that value) or change ConvertAppTypeToV3Api’s
signature to return (v3.BillingAppType, error) and return a typed error from the
default branch, then update callers to handle the error accordingly.

In `@api/v3/handlers/apps/convert.go`:
- Around line 17-27: The converter currently uses the goverter `@panic` behavior
for app.AppType (ConvertAppTypeToV3Api) which will crash on unknown enum values;
change the conversion to error-returning behavior instead: update
ConvertAppTypeToV3Api to return (apiv3.BillingAppType, error) (or return a safe
“unknown” value plus error) and regenerate the converters so the mapping no
longer panics, then update all call sites that use ConvertAppTypeToV3Api to
handle the returned error (or handle the unknown fallback) in request paths to
avoid crashing on future enum additions.

In `@api/v3/handlers/apps/mapper.go`:
- Around line 22-49: The switch branches perform unchecked type assertions
(e.g., item.(appstripeentityapp.App), item.(appsandbox.App),
item.(appcustominvoicing.App)) which can panic if concrete type differs; update
each branch (the Stripe, Sandbox, and CustomInvoicing cases) to use the
two-value form (v, ok := item.(Type)) and, if !ok, return a clear error instead
of asserting, then continue to call
mapStripeAppToAPI/mapSandboxAppToAPI/mapCustomInvoicingAppToAPI and the
respective api.BillingApp methods (FromBillingAppStripe, FromBillingAppSandbox,
FromBillingAppExternalInvoicing) only when ok is true.

🧹 Nitpick comments (1)

api/v3/handlers/apps/list_app.go (1)

66-71: Add app ID to mapping errors for easier debugging.
If a single item fails to map, including the app ID speeds up triage.

💡 Suggested tweak

-			apiAppItem, err := MapAppToAPI(item)
-			if err != nil {
-				return ListAppsResponse{}, fmt.Errorf("failed to map app to apiv3: %w", err)
-			}
+			apiAppItem, err := MapAppToAPI(item)
+			if err != nil {
+				return ListAppsResponse{}, fmt.Errorf("failed to map app %s to apiv3: %w", item.GetID(), err)
+			}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@api/v3/handlers/apps/convert.go`:
- Around line 109-125: In mapSandboxAppToAPI, populate the missing Description
and Labels fields on the returned api.BillingAppSandbox to match other mappers:
set Description to a pointer of sandboxApp.GetDescription() (e.g.,
lo.ToPtr(sandboxApp.GetDescription())) and set Labels to the metadata from
sandboxApp.GetMetadata() (or convert it the same way
mapStripeAppToAPI/mapCustomInvoicingAppToAPI do) so the sandbox mapping is
consistent with other app types.

🧹 Nitpick comments (1)

api/v3/handlers/apps/convert.go (1)

127-156: Looks good overall!

Minor observation: the conditional check for metadata (lines 151-153) is good defensive coding. Just noting that mapCustomInvoicingAppToAPI always calls ConvertMetadataToLabels without the nil check - the converter handles nil fine, but the inconsistency might confuse future readers.