fix(spec): typespec typescript emitter internal handling

[tothandras]

Summary by CodeRabbit

• New Features
  • Added internal invoice operations for listing, retrieving, updating, and deleting invoices.
  • Added internal governance access queries with pagination support.
  • Expanded the SDK with invoice models, request types, and response schemas.
  • Private operations are now available through the internal SDK surface.
• Documentation
  • Added documentation for internal invoice and governance operations.
  • Clarified internal operation visibility and union type generation rules.

Greptile Summary

This PR changes how the TypeScript SDK emitter handles private operations. The main changes are:

• Routes x-private operations into the internal SDK surface.
• Regenerates the JS client with internal invoice and governance calls.
• Adds invoice union aliases and updated exported operation types.
• Updates docs and tests for the new internal operation behavior.

Confidence Score: 4/5

The private-operation export path needs a fix before merging.

• The new invoice and governance runtime functions match the existing generated request patterns.
• The changed collection path also places private operations in the public standalone funcs export.
• That makes destructive invoice calls reachable outside the documented internal facade.

api/spec/packages/typespec-typescript/src/ZodOperations.tsx and the funcs export generation path

Security Review

Formerly omitted private invoice and governance operations now become reachable through the public standalone funcs export, including invoice update and delete calls.

Important Files Changed

Filename	Overview
api/spec/packages/typespec-typescript/src/ZodOperations.tsx	Changes private operation collection so private calls are generated as internal operations, with a public funcs exposure issue.
api/spec/packages/aip-client-javascript/src/sdk/internal.ts	Adds internal invoice and governance facades that follow existing wrapper and pagination patterns.
api/spec/packages/aip-client-javascript/src/funcs/invoices.ts	Adds generated invoice request functions with path, query, body, response, and void-delete handling.
api/spec/packages/aip-client-javascript/src/funcs/governance.ts	Adds the generated governance query function with separate request body and cursor-page query handling.
api/spec/packages/aip-client-javascript/src/models/types.ts	Adds newly reachable invoice and update-invoice aliases and updates invoice response/input types to use them.

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/spec/packages/typespec-typescript/src/ZodOperations.tsx:119
**Private Funcs Stay Public**

When this filter stops dropping `x-private` operations, those operations enter the same generated funcs barrel as public calls. The package root exports that barrel, so callers can import `funcs.deleteInvoice`, `funcs.updateInvoice`, or `funcs.queryGovernanceAccess` directly instead of using the documented `client.internal.*` quarantine, making formerly omitted private and destructive endpoints part of the public standalone API surface.

_{Reviews (1): Last reviewed commit: "fix(spec): typespec typescript emitter i..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used (3)

• Context used - CLAUDE.md (source)
• Context used - AGENTS.md (source)
• Context used - api/spec/AGENTS.md (source)

[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: 2996d783-3e4c-448a-9647-3343860d052c

📥 Commits

Reviewing files that changed from the base of the PR and between 1d51ec7 and 9975fcb.

📒 Files selected for processing (14)

• AGENTS.md
• api/spec/AGENTS.md
• api/spec/packages/aip-client-javascript/README.md
• api/spec/packages/aip-client-javascript/src/funcs/governance.ts
• api/spec/packages/aip-client-javascript/src/funcs/index.ts
• api/spec/packages/aip-client-javascript/src/funcs/invoices.ts
• api/spec/packages/aip-client-javascript/src/index.ts
• api/spec/packages/aip-client-javascript/src/models/operations/governance.ts
• api/spec/packages/aip-client-javascript/src/models/operations/invoices.ts
• api/spec/packages/aip-client-javascript/src/models/schemas.ts
• api/spec/packages/aip-client-javascript/src/models/types.ts
• api/spec/packages/aip-client-javascript/src/sdk/internal.ts
• api/spec/packages/typespec-typescript/src/ZodOperations.tsx
• api/spec/packages/typespec-typescript/test/internal-surface.test.ts

---

📝 Walkthrough

Walkthrough

The TypeSpec generator now emits x-private operations under client.internal.*. The generated JavaScript SDK adds invoice and governance contracts, request functions, internal wrappers, schemas, exports, and documentation.

Changes

Internal operation routing

Layer / File(s)	Summary
Private operation audience routing AGENTS.md, api/spec/AGENTS.md, api/spec/packages/typespec-typescript/src/ZodOperations.tsx, api/spec/packages/typespec-typescript/test/internal-surface.test.ts	x-private operations are emitted on internal facades, excluded from public facades, and covered by updated reachability guidance and tests.

Generated SDK contracts

Layer / File(s)	Summary
Generated invoice and governance contracts api/spec/packages/aip-client-javascript/src/models/operations/*, api/spec/packages/aip-client-javascript/src/models/schemas.ts, api/spec/packages/aip-client-javascript/src/models/types.ts, api/spec/packages/aip-client-javascript/src/index.ts	Invoice and governance request/response types, validation schemas, shared aliases, and package exports are added.

Generated operations and wrappers

Layer / File(s)	Summary
Generated operations and internal wrappers api/spec/packages/aip-client-javascript/src/funcs/*, api/spec/packages/aip-client-javascript/src/sdk/internal.ts	Invoice CRUD/list operations and governance access queries call the HTTP client; internal wrappers expose these methods, including paginated invoice iteration.

Documentation

Layer / File(s)	Summary
Internal SDK documentation api/spec/packages/aip-client-javascript/README.md	Internal invoice and governance operations are added to the README table of contents and reference documentation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant InternalClient
  participant GeneratedFunction
  participant HTTPService
  InternalClient->>GeneratedFunction: invoke invoice or governance method
  GeneratedFunction->>HTTPService: send encoded HTTP request
  HTTPService-->>GeneratedFunction: return JSON response
  GeneratedFunction-->>InternalClient: validate and decode typed result

Loading

Possibly related PRs

• openmeterio/openmeter#4329: Adds the governance operation and models that this SDK change generates wrappers for.
• openmeterio/openmeter#4541: Overlaps with invoice client operation and model wiring.
• openmeterio/openmeter#4658: Directly relates to routing x-private operations to client.internal.*.

Suggested reviewers: chrisgacsal, turip

🚥 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 matches the main change: updating the TypeSpec TypeScript emitter’s internal handling for x-private/x-internal operations.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 fix/typespec-typescript-emitter-internal

---

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

[borosr]

lgtm