feat(api): filter credit grants by key

[tothandras]

Summary by CodeRabbit

• New Features

  • Credit grants now include a readable key value in API responses.
  • Credit grants can be filtered by key when listing results.
  • Create and list flows now consistently support key-based lookup across the customer credits experience.

• Bug Fixes

  • Key values are now returned reliably on single credit grant fetches and in list results.
  • Invalid key filters are rejected with a clear bad-request response.

[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: 9674c1b4-b2c1-4ac4-9bdc-672bd29d77fe

📥 Commits

Reviewing files that changed from the base of the PR and between 9c90d9b and 34e30c2.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (14)

• 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/credits/grant.tsp
• api/spec/packages/aip/src/customers/credits/operations.tsp
• api/v3/api.gen.go
• api/v3/handlers/customers/credits/convert.go
• api/v3/handlers/customers/credits/convert_test.go
• api/v3/handlers/customers/credits/list_grants.go
• e2e/customer_credits_v3_test.go
• e2e/v3helpers_test.go
• openmeter/billing/charges/creditpurchase/adapter.go
• openmeter/billing/charges/creditpurchase/adapter/charge.go
• openmeter/billing/creditgrant/service.go
• openmeter/billing/creditgrant/service/service.go

---

📝 Walkthrough

Walkthrough

CreditGrant.key visibility is extended from create-only to read+create in the TypeSpec definition. The key field is now mapped in the API conversion layer and exposed in list/get responses. A new filter[key] query parameter is wired through the handler, service, and DB adapter layers. JS client schemas and types are updated accordingly, and e2e tests cover the full read and filter behavior.

Changes

Credit Grant Key Read & Filter

Layer / File(s)	Summary
API spec and JS client contracts api/spec/packages/aip/src/customers/credits/grant.tsp, api/spec/packages/aip/src/customers/credits/operations.tsp, api/spec/packages/aip-client-javascript/src/models/schemas.ts, api/spec/packages/aip-client-javascript/src/models/types.ts	CreditGrant.key visibility updated to include read; ListCreditGrantsParamsFilter gains an optional key filter; JS Zod schemas and TypeScript interfaces updated to match.
Service and adapter ListInput Key field openmeter/billing/creditgrant/service.go, openmeter/billing/charges/creditpurchase/adapter.go, openmeter/billing/charges/creditpurchase/adapter/charge.go, openmeter/billing/creditgrant/service/service.go	Key *filter.FilterString added to ListInput and ListChargesInput with validation; List propagates it to ListChargesInput; DB query applies filter.ApplyToQuery against FieldKey.
Handler conversion and filter parsing api/v3/handlers/customers/credits/convert.go, api/v3/handlers/customers/credits/list_grants.go, api/v3/handlers/customers/credits/convert_test.go	toAPIBillingCreditGrant maps charge.Intent.Key to the API response Key; list handler parses filter[key] via filters.FromAPIFilterString and returns 400 on failure; unit tests cover both key-present and key-absent cases.
E2E tests and v3 client helpers e2e/v3helpers_test.go, e2e/customer_credits_v3_test.go	GetCreditGrant and ListCreditGrants helpers added to v3Client; new e2e test covers key echoing on create/get and correct filter[key] list semantics including empty result on non-matching key.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• openmeterio/openmeter#4158: Introduced toAPIBillingCreditGrant in the same conversion file that this PR extends to map the Key field.
• openmeterio/openmeter#4592: Added the initial key field to CreditGrant in the TypeSpec and JS models; this PR extends that by making the field readable and filterable.

Suggested labels

area/api, area/billing

Suggested reviewers

• turip
• chrisgacsal

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% 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 clearly matches the main change: adding key-based filtering for credit grants 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/credit-grant-key

---

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 idempotency-key reads and filtering for credit grants. The main changes are:

• Exposes key on credit grant read models.
• Adds filter[key] to the list credit grants API shape.
• Wires the key filter through the v3 handler, service, and adapter query.
• Adds tests for key exposure and exact key filtering.

Confidence Score: 4/5

The key filtering path needs a small fix before merging.

• Exact object filters such as filter[key][eq] are wired through the stack.
• Scalar filters allowed by the API shape can return too many grants.
• Key exposure itself follows the new response model and persisted field.

api/v3/handlers/customers/credits/list_grants.go

Important Files Changed

Filename	Overview
api/spec/packages/aip/src/customers/credits/grant.tsp	Makes the credit grant key visible on read responses as well as create inputs.
api/spec/packages/aip/src/customers/credits/operations.tsp	Adds a key string field filter to the list credit grants request.
api/v3/handlers/customers/credits/list_grants.go	Parses and forwards the new key filter, but scalar filter input can be interpreted too broadly.
api/v3/handlers/customers/credits/convert.go	Maps the persisted credit grant key into API read responses.
openmeter/billing/creditgrant/service.go	Adds the key filter to credit grant list input and validation.
openmeter/billing/creditgrant/service/service.go	Forwards the credit grant key filter to the credit purchase list query.
openmeter/billing/charges/creditpurchase/adapter.go	Adds the key filter to the credit purchase list adapter input.
openmeter/billing/charges/creditpurchase/adapter/charge.go	Applies the key filter to the credit purchase key column.

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
api/v3/handlers/customers/credits/list_grants.go:85-95
**Scalar Key Filter Broadens Results**

When a client sends the generated scalar form `filter[key]=welcome-bonus`, this path forwards the parsed string filter as an existence check instead of an equality check. The list endpoint can then return every keyed grant for the customer, not just the grant with that key.

_{Reviews (1): Last reviewed commit: "feat(api): filter credit grants by key" | Re-trigger Greptile}