feat(api): add accounting periods to spec

[tothandras]

Summary by CodeRabbit

• New Features
  • Added accounting periods management API: list periods, get a period by ID, and close the current open period.
  • AccountingPeriod model with lifecycle timestamps, sealing metadata, and status enum (open, closing, closed).
  • New request/response models for listing (filters, pagination), retrieving, and closing periods.
  • Registered accounting tag and new accounting endpoints under the API routes.

[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: 4eb12d01-5462-418b-a371-1bf2f445842e

📥 Commits

Reviewing files that changed from the base of the PR and between e459570 and 0b9b26b.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (2)

• api/spec/packages/aip/src/accounting/operations.tsp
• api/v3/api.gen.go

🚧 Files skipped from review as they are similar to previous changes (1)

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

---

📝 Walkthrough

Walkthrough

Adds accounting period types and enum, operation contracts (list/get/close) with filters and request models, registers accounting tag metadata and endpoint wiring in konnect/openmeter TypeSpec packages, imports accounting index, and adds stubbed server route handlers for the new endpoints.

Changes

Accounting Periods API

Layer / File(s)	Summary
Accounting period data models api/spec/packages/aip/src/accounting/period.tsp, api/spec/packages/aip/src/accounting/index.tsp	AccountingPeriodStatus enum (open, closing, closed) and AccountingPeriod model with immutable shared fields, lifecycle timestamps (start_at, end_at, closing_started_at, closed_at, sealed_at), and sealing metadata.
Accounting operations API contracts api/spec/packages/aip/src/accounting/operations.tsp	Adds ListAccountingPeriodsParamsFilter (deepObject filters), CloseAccountingPeriodRequest (required end_at, optional labels, name, description), and AccountingPeriodsOperations interface with close (POST /close), get (GET by ID), and list (GET with pagination/sort/filter).
API routing and tag metadata api/spec/packages/aip/src/shared/consts.tsp, api/spec/packages/aip/src/konnect.tsp, api/spec/packages/aip/src/openmeter.tsp	Introduces AccountingTag and AccountingDescription, imports accounting specs into konnect/openmeter, registers tag metadata, and defines AccountingPeriodsEndpoints at /openmeter/accounting/periods extending Accounting.AccountingPeriodsOperations.
Server route handler stubs api/v3/server/routes.go	Adds Server handler stubs: ListAccountingPeriods, GetAccountingPeriod, and CloseAccountingPeriod delegating to unimplemented placeholders.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

area/api, release-note/misc

Suggested reviewers

• turip
• 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 clearly and accurately summarizes the main change: adding accounting periods functionality to the API specification.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api-v3-closing

---

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

🧹 Nitpick comments (1)

api/spec/packages/aip/src/accounting/operations.tsp (1)

27-27: ⚡ Quick win

Type the status filter with the accounting status enum.

Using Common.StringFieldFilterExact makes status accept arbitrary strings in generated contracts. It’s better to use an enum-based filter shape so clients get strict typing for open|closing|closed.

As per coding guidelines, “The declared API should be accurate, in parity with the actual implementation, and easy to understand for the user.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api/spec/packages/aip/src/accounting/operations.tsp` at line 27, Replace the
loose string filter on the status property (currently declared as status?:
Common.StringFieldFilterExact) with a strict enum-based filter so generated
contracts only allow the accounting states; define or import an AccountStatus
enum with values "open" | "closing" | "closed" and change the type to use the
enum filter (for example Common.EnumFieldFilterExact<AccountStatus> or an
equivalent EnumFieldFilter type your Common library provides), and update any
imports/exports to reference AccountStatus so the operations.tsp status property
is strongly typed against that enum.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@api/spec/packages/aip/src/accounting/operations.tsp`:
- Around line 116-119: The `close` operation's return type is currently a
create-style response but should be a 200-style resource response; update the
declaration of close(`@body` body: CloseAccountingPeriodRequest) to return a
200-style response (e.g. replace Shared.CreateResponse<AccountingPeriod> with
Shared.ResourceResponse<AccountingPeriod> or your project's standard 200
resource response type) while keeping Common.ErrorResponses, so the signature
reads close(`@body` body: CloseAccountingPeriodRequest):
Shared.ResourceResponse<AccountingPeriod> | Common.ErrorResponses.
- Around line 107-109: Update the docs to use the deepObject-shaped query
example instead of the current flat example: replace the example
`filter[status]=open` with the deep-object form `filter[status][]=open` in the
comment/block so it matches the API’s deepObject filter handling (search for the
comment containing `Returns the period transitioned to \`closing\`` and the
`filter[status]=open` text and update it).

---

Nitpick comments:
In `@api/spec/packages/aip/src/accounting/operations.tsp`:
- Line 27: Replace the loose string filter on the status property (currently
declared as status?: Common.StringFieldFilterExact) with a strict enum-based
filter so generated contracts only allow the accounting states; define or import
an AccountStatus enum with values "open" | "closing" | "closed" and change the
type to use the enum filter (for example
Common.EnumFieldFilterExact<AccountStatus> or an equivalent EnumFieldFilter type
your Common library provides), and update any imports/exports to reference
AccountStatus so the operations.tsp status property is strongly typed against
that enum.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b0761e8d-8da3-49c4-a395-f379de953e87

📥 Commits

Reviewing files that changed from the base of the PR and between f67a8a1 and e459570.

⛔ 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/accounting/index.tsp
• api/spec/packages/aip/src/accounting/operations.tsp
• api/spec/packages/aip/src/accounting/period.tsp
• api/spec/packages/aip/src/konnect.tsp
• api/spec/packages/aip/src/openmeter.tsp
• api/spec/packages/aip/src/shared/consts.tsp
• api/v3/api.gen.go
• api/v3/server/routes.go