fix(api): v3 resource mixin required created_at and updated_at

[tothandras]

Summary by CodeRabbit

• Bug Fixes

  • Enhanced documentation for charge expansion parameters, including supported values like real_time_usage.

• New Features

  • Timestamp fields now required in API responses for improved data consistency.
  • Credit balance queries now support currency-based filtering.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR systematically migrates timestamp field handling across the API specification and implementation. Timestamp fields (created_at, updated_at) are made required in the TypeScript API spec, extension decorators are updated from PrivateExtension to InternalExtension across multiple operations, and Go handlers are refactored to use value-based timestamps instead of pointers, removing dependency on the lo helper library.

Changes

API Specification Timestamp & Extension Updates

Layer / File(s)	Summary
Data Shape Requirements api/spec/.../cost-basis.tsp, api/spec/.../currency.tsp, api/spec/.../prices.tsp, api/spec/.../shared/resource.tsp	Timestamp fields created_at and updated_at changed from optional (?:) to required (:) in CostBasis, CurrencyCustom, Price, and Resource models.
Operation Visibility & Stability api/spec/.../events/operations.tsp, api/spec/.../features/operations.tsp, api/spec/.../meters/operations.tsp, api/spec/.../productcatalog/operations.tsp, api/spec/.../tax/operations.tsp	Extension annotations updated from Shared.PrivateExtension to Shared.InternalExtension (and in one case Shared.UnstableExtension to Shared.InternalExtension) across 30+ operations to reflect API visibility policy.
API Contract & Documentation api/spec/.../customers/charges/operations.tsp, api/spec/.../customers/credits/operations.tsp, api/spec/.../productcatalog/plan.tsp	Expanded docstring for expand parameter, replaced feature filter field with currency field in credit balance request, and refactored pro-rating comment placement.

Go Handler Timestamp Type Alignment

Layer / File(s)	Summary
Conversion Layer Refactoring api/v3/handlers/{addons,apps,currencies,features,llmcost,plans,planaddons,subscriptions,taxcodes}/convert*.go	Removed pointer-wrapping conversions (lo.ToPtr(), &field) for timestamp assignments. CreatedAt/UpdatedAt now directly assign source values as time.Time instead of *time.Time.
Helper Function Updates api/v3/handlers/{billingprofiles,customers,meters,taxcodes}/convert.gen.go	Replaced timeTimeToPTimeTime(*time.Time) helper functions with new timeTimeToTimeTime(time.Time) returning value types. Internal time conversion logic now propagates non-pointer timestamps through the handler chain.
Dependency & Validation Cleanup api/v3/handlers/{apps,customers/credits,plans/planaddons}/convert.go, api/v3/handlers/customers/credits/get_balance.go	Removed github.com/samber/lo import from files no longer using pointer helpers. Deleted feature-based filter validation in credit balance handler and related error declarations.
Test Expectations api/v3/handlers/plans/convert_test.go	Updated assertions to expect scalar time.Time values for CreatedAt/UpdatedAt instead of dereferencing pointers; removed nil-checks for timestamp fields.

Sequence Diagram

sequenceDiagram
    participant Spec as API Spec<br/>(TypeScript)
    participant Handler as Go Handler<br/>(Conversion)
    participant API as API Response<br/>(v3)
    
    Spec->>Spec: Make created_at<br/>required field
    Spec->>Spec: Update extension<br/>PrivateExtension →<br/>InternalExtension
    
    Handler->>Handler: Remove lo.ToPtr()<br/>for timestamps
    Handler->>Handler: Replace pointer<br/>conversion helper
    
    Handler->>API: Assign time.Time<br/>directly (not *time.Time)
    API-->>Handler: ✓ Receive scalar<br/>timestamp values

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• openmeterio/openmeter#4281: Directly related — also updates extension annotations on API operations to InternalExtension across the same spec files.
• openmeterio/openmeter#4256: Modifies the same extension/visibility decorators on operation specs (features, events, meters, productcatalog).
• openmeterio/openmeter#4135: Overlaps with timestamp field conversion refactoring in the same api/v3/handlers conversion functions.

Suggested labels

api/spec, handlers/conversion, refactor, breaking-change

Suggested reviewers

• mark-vass-konghq
• chrisgacsal

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.71% 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 PR title clearly summarizes the main change: making created_at and updated_at required fields in the v3 resource mixin, which is reflected across the spec files and conversion handlers.
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 fix/v3-api-resources

---

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