chore: WIP

Author: tothandras

api/spec/AGENTS.md

@@ -32,6 +32,7 @@ it.
   (schemas, runtime, per-namespace surface, barrel) plus the conformance tests.
 
 ### How the emitter is structured
+
 - `emitter.tsx` — `$onEmit`: emits `schemas.ts` (Alloy components, the original
   path), the static runtime files, and the per-namespace surface files, all as
   sibling `<ts.SourceFile>` children of one `<Output>`.
@@ -49,6 +50,7 @@ it.
   documented call paths and routes always match the emitted client.
 
 ### Grouping (reproduce this)
+
 The `OpenMeter` service surfaces every operation through an `*Endpoints`
 interface that `extends` the resource's interface in its **source** namespace
 (e.g. `OpenMeter.PlansEndpoints extends ProductCatalog.PlanOperations`). The op
@@ -64,6 +66,7 @@ a display string like "Metering Events" → stutter) or by `op.namespace` (alway
 `OpenMeter`).
 
 ### Nested sub-clients (reproduce this)
+
 The SDK nests sub-clients (`customers.charges.list()`,
 `customers.credits.grants.list()`) from the **source namespace chain** below the
 group's top namespace. Walking `sourceInterfaces[0].namespace` up to the global
@@ -92,12 +95,13 @@ segments, so `create-credit-grant` under `credits.grants` → `create`.
 **OpenAPI invariance is the hard gate** for any `.tsp` change: regenerate and
 confirm the `output/definitions/.../*.yaml` hashes are unchanged. Namespace
 nesting of operation interfaces is OpenAPI-neutral (paths/tags/operationIds are
-explicit); moving a *model* is not. Watch for namespace collisions — nesting
+explicit); moving a _model_ is not. Watch for namespace collisions — nesting
 `Customers.Billing` shadows the global `Billing` namespace for unqualified refs
 in `Customers`-scoped files; alias around it (`Common.BillingRoot`) rather than
 renaming.
 
 ### Naming rules (reproduce these)
+
 - **func name** = full camelCase operationId: `get-meter` → `getMeter`.
 - **facade method** = operationId with the group's resource noun(s) and the
   cross-cutting `metering` qualifier stripped: `get-meter` → `get`;
@@ -121,12 +125,12 @@ renaming.
 
 ## Commands
 
-| Task | Command |
-|------|---------|
-| Build the emitter | `pnpm --filter @openmeter/typespec-typescript run build` |
-| Regenerate SDK from TypeSpec | `pnpm --filter @openmeter/api-spec-aip run generate` |
-| Run the SDK conformance tests | `pnpm run test:sdk` |
-| Install / refresh lockfile | `pnpm install --config.confirmModulesPurge=false` |
+| Task                          | Command                                                  |
+| ----------------------------- | -------------------------------------------------------- |
+| Build the emitter             | `pnpm --filter @openmeter/typespec-typescript run build` |
+| Regenerate SDK from TypeSpec  | `pnpm --filter @openmeter/api-spec-aip run generate`     |
+| Run the SDK conformance tests | `pnpm run test:sdk`                                      |
+| Install / refresh lockfile    | `pnpm install --config.confirmModulesPurge=false`        |
 
 The emitter is bound by **package name** (`@openmeter/typespec-typescript`) in
 `packages/aip/tspconfig.yaml` (both the `emit:` list and the `options:` key). The
@@ -140,22 +144,26 @@ exact shape the generator must reproduce. Its tests are the conformance target 
 the generated SDK is "done" when it passes them.
 
 ### Casing: wire-native, no transformation
+
 The AIP API is **snake_case end to end** (enforced by the AIP casing lint rule).
 Request/response bodies are snake_case in TypeSpec, OpenAPI, and the emitted zod
 schemas alike. There is **no snake↔camel transform layer** — the JS object shape
 is the wire shape. Do not add `.transform()` or case-converting middleware.
 
 ### No runtime validation of responses
+
 Responses are typed via ky's `.json<T>()`, never `schema.parse()`. Validating
 responses turns additive (non-breaking) API fields into client breakage. zod is
 retained only for type derivation (`z.input`/`z.output`) and the one
 `baseError.safeParse` in the error path. Request bodies are likewise not parsed
 (the server owns defaults and validation).
 
 ### Documented types: generated from TypeSpec, verified against zod
+
 **zod schemas and TypeScript types are separate artifacts with one source.** Both
 are generated from the same TypeSpec, but neither is derived from the other at the
 type level:
+
 - `models/schemas.ts` — zod schemas (runtime validation in the error path, query/
   path coercion). The runtime artifact.
 - `models/types.ts` — concrete TypeScript interfaces (the public surface that
@@ -174,6 +182,7 @@ TypeSpec directly gives clean concrete types (`id: string`,
 the TypeSpec `@doc`, decoupled from zod.
 
 `tsTypeOf` leaf mapping (must match `zodBaseSchemaParts` or the guard fails):
+
 - scalars → `string` / `number` / `boolean`; **int64/uint64 → `bigint`** (zod uses
   `z.coerce.bigint()`); everything else numeric → `number`.
 - **dates/times/durations → `string`** (wire-native; RFC 3339, never `Date`).
@@ -184,6 +193,7 @@ the TypeSpec `@doc`, decoupled from zod.
   union: `(A | B)[]`); open records → `Record<string, V>`.
 
 Structural rules the interface emitter follows:
+
 - **Optionality follows OUTPUT**: a defaulted field is optional-in / required-out,
   so `prop.optional && prop.defaultValue === undefined` decides the `?`.
 - **No-wire-prop models alias** to their mapped structure
@@ -193,14 +203,14 @@ Structural rules the interface emitter follows:
 - **`extends`** the base interface when the model has a `baseModel`, so inherited
   fields/docs propagate (`BadRequest extends BaseError`).
 - **Open records** (`...Record<…>`) get an index signature (`[key: string]: V`).
-- **Unions stay on `z.output`** at the *response* layer (e.g. `GetAppResponse`) — a
+- **Unions stay on `z.output`** at the _response_ layer (e.g. `GetAppResponse`) — a
   discriminated union has no single interface, so wiring it to one would be wrong.
 
 **Conformance guard (the oracle).** Every emitted type — both `interface`s **and**
 the no-wire-prop `type` aliases — is paired with a mutual-assignability check in
 `models/types.assert.ts`
 (`[X] extends [z.output<…>] ? [z.output<…>] extends [X] ? true : {__error}`). This
-is the *only* place `types.ts` and `schemas.ts` meet: it proves the directly-walked
+is the _only_ place `types.ts` and `schemas.ts` meet: it proves the directly-walked
 TS type is type-equivalent to the zod schema, turning any divergence (wrong leaf,
 wrong optionality, header leak, open-record gap) into a **build error**. `tsc` is
 the oracle. The alias branch must guard too: unlike a former `z.output` alias
@@ -227,6 +237,7 @@ clean `prop?: T` output-shaped optionality (defaulted fields required, no
 depend on `.describe()` surviving into the runtime schemas.
 
 ### Factoring: what the generator emits, and how often
+
 - **ONCE** (shared runtime in `lib/` + `core.ts`): the base `Client`/transport
   (one `ky.create`), the `request()` envelope, `Result`/`ok`/`err`/`unwrap`,
   the curated `RequestOptions`, the encoders (`encodePath`, `toURLSearchParams`,
@@ -242,6 +253,7 @@ depend on `.describe()` surviving into the runtime schemas.
   functions, so the funcs modules stay free of type declarations and guards.
 
 ### Void responses must not call `.json()`
+
 The 10 operations whose `Response` is `void` (`!op.hasResponse` — every
 `delete*` plus `events.ingest`, which return `204 No Content` / `202 Accepted`
 with an empty body) terminate with `request(async () => { await http(client).<verb>(…) })`,
@@ -264,9 +276,11 @@ directly in `tests/` and is not re-emitted by `generate` — do not delete it
 expecting a regen to restore it.
 
 ### Request types: direct TS, input-variant interfaces
+
 Request/response types are direct TS, not `z.input`/`z.output`, and live in
 `models/operations/<ns>.ts` (re-exported from the barrel under their existing
 public names). The split mirrors the model types:
+
 - **Response** → the documented output interface (or `void`, or the one
   `z.output` union `GetAppResponse`).
 - **Request body** → the body model's interface, or its **`…Input` variant**
@@ -293,6 +307,7 @@ public names). The split mirrors the model types:
   identically, so widening only the request **type** is sufficient.
 
 Two traps the generator handles:
+
 - **Name collision**: the op request type `<Base>Request` collides with a body
   model interface of the same name (e.g. `CreateMeterRequest`). The body is
   imported under a `<Name>Body` alias so the local request declaration owns the
@@ -311,6 +326,7 @@ too-strict request type (refing the output `X` where `XInput` was needed) still
 satisfies the one-directional `[X] extends [z.input]`, so the shipped guards
 can't catch picking the wrong variant or `computeDivergentModels` under-marking.
 Two independent checks close this:
+
 - The 20 conformance tests construct real requests (end-to-end).
 - **Coverage probe** (the authoritative recipe — do NOT use a regex reachability
   tracer; it false-matches identifiers inside `.regex(/…/)` and `.describe()`):
@@ -320,11 +336,13 @@ Two independent checks close this:
   compiled by tsc; zero failures = every request-reachable model is covered.
 
 ### Dual surface
+
 Every operation exists twice: a standalone func in `funcs/` returning
 `Result<T>` (tree-shakeable, non-throwing) and a thin method on the namespace
 façade in `sdk/` that `unwrap`s and throws. Both call the same func.
 
 ### README
+
 `readme.ts` emits the package `README.md` at the package root (`emitter-output-dir`
 is the package root, so non-`src/` paths land there; `package.json`/`tests/`
 survive because `writeOutput` only writes listed paths). It is built from the
@@ -352,11 +370,13 @@ is already red for both subtrees), so do not pre-align tables in the emitter or
 single out the README in `.prettierignore`.
 
 ### RequestOptions is curated
+
 `RequestOptions = Pick<Options, 'signal' | 'headers' | 'timeout' | 'retry'>`.
 Do not widen it to the full ky `Options` — exposing `searchParams`/`json`/`hooks`/
 `fetch`/`prefix` per call lets callers clobber transport internals.
 
 ### Errors
+
 `toError` maps ky failures to the domain `HTTPError` (RFC7807 `problem+json`,
 charset-tolerant Content-Type match; status-only fallback otherwise). `Result`'s
 error type stays `Error` — the ky fork also throws `TimeoutError`/`NetworkError`,
@@ -365,6 +385,7 @@ so narrowing to `HTTPError` would be unsound. Callers narrow with
 field-level validation errors are reachable via `getField('invalid_parameters')`.
 
 ### Server URL templating
+
 `baseUrl` is **required** (no default). It may be a `ServerList` template with
 `{region}`/`{port}` variables resolved via `encodePath(baseUrl, serverVariables)`,
 a concrete URL, or a `URL` object. `region` is typed to the enumerated `Regions`.
@@ -375,12 +396,15 @@ user-supplied `prefix` cannot redirect requests; the auth hook is appended
 **after** user `beforeRequest` hooks so SDK auth wins.
 
 ### ky is a fork — preserve its option names
+
 The vendored `ky` uses `baseUrl`/`prefix`/`totalTimeout`/`retryOnTimeout` (not
 mainline ky's `prefixUrl`). The emitter's runtime must use the fork's names; do
 not "correct" them to mainline ky.
 
 ## Query serialization (verified against the server)
+
 `api/v3/filters/parse.go` is the source of truth for filter encoding:
+
 - deep objects: `page[size]`, `filter[key][eq]` (bracketed)
 - scalar `filter[key]=v` is shorthand for `filter[key][eq]=v`
 - array operands (`oeq`/`ocontains`) are **comma-joined into one param**; the
@@ -389,6 +413,7 @@ not "correct" them to mainline ky.
   `encodeSort` flattens `{by, order}` to that form.
 
 ## Tests
+
 The conformance tests (Vitest + `@fetch-mock/vitest`, matching the legacy SDK's
 stack) are embedded in `runtime-templates.ts` and emitted into the generated
 SDK. They are the generator's spec: it is "done" when these tests pass against

api/spec/packages/aip-client-javascript/src/models/schemas.ts

@@ -3,19 +3,19 @@ import { z } from "zod";
 export const labels = z
   .record(z.string(), z.string())
 
-    .describe("Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with \"kong\", \"konnect\", \"mesh\", \"kic\", or \"\_\".");
+    .describe("Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with \"kong\", \"konnect\", \"mesh\", \"kic\", or \"\\_\".");
 
 export const currencyCode = z
   .string()
   .min(3)
   .max(3)
-  .regex(/^[A-Z]{3}$/)
+  .regex(new RegExp("^[A-Z]{3}$"))
 
     .describe("Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience.");
 
 export const numeric = z
   .string()
-  .regex(/^\-?[0-9]+(\.[0-9]+)?$/)
+  .regex(new RegExp("^\\-?[0-9]+(\\.[0-9]+)?$"))
   .describe("Numeric represents an arbitrary precision number.");
 
 export const cursorPaginationQueryPage = z
@@ -96,7 +96,7 @@ export const stringFieldFilter = z
 
 export const ulid = z
   .string()
-  .regex(/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/)
+  .regex(new RegExp("^[0-7][0-9A-HJKMNP-TV-Z]{25}$"))
   .describe("ULID (Universally Unique Lexicographically Sortable Identifier).");
 
 export const dateTime = z
@@ -223,7 +223,7 @@ export const resourceKey = z
   .string()
   .min(1)
   .max(64)
-  .regex(/^[a-z0-9]+(?:_[a-z0-9]+)*$/)
+  .regex(new RegExp("^[a-z0-9]+(?:_[a-z0-9]+)*$"))
   .describe("A key is a unique string that is used to identify a resource.");
 
 export const meterAggregation = z
@@ -321,7 +321,7 @@ export const countryCode = z
   .string()
   .min(2)
   .max(2)
-  .regex(/^[A-Z]{2}$/)
+  .regex(new RegExp("^[A-Z]{2}$"))
 
     .describe("[ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 country code. Custom two-letter country codes are also supported for convenience.");
 
@@ -435,7 +435,7 @@ export const entitlementType = z
 export const createLabels = z
   .record(z.string(), z.string())
 
-    .describe("Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with \"kong\", \"konnect\", \"mesh\", \"kic\", or \"\_\".");
+    .describe("Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with \"kong\", \"konnect\", \"mesh\", \"kic\", or \"\\_\".");
 
 export const creditFundingMethod = z
   .enum(["none", "invoice", "external"])
@@ -455,7 +455,7 @@ export const taxBehavior = z
 export const iso8601Duration = z
   .string()
 
-    .regex(/^P(?:\d+(?:\.\d+)?Y)?(?:\d+(?:\.\d+)?M)?(?:\d+(?:\.\d+)?W)?(?:\d+(?:\.\d+)?D)?(?:T(?:\d+(?:\.\d+)?H)?(?:\d+(?:\.\d+)?M)?(?:\d+(?:\.\d+)?S)?)?$/)
+    .regex(new RegExp("^P(?:\\d+(?:\\.\\d+)?Y)?(?:\\d+(?:\\.\\d+)?M)?(?:\\d+(?:\\.\\d+)?W)?(?:\\d+(?:\\.\\d+)?D)?(?:T(?:\\d+(?:\\.\\d+)?H)?(?:\\d+(?:\\.\\d+)?M)?(?:\\d+(?:\\.\\d+)?S)?)?$"))
 
     .describe("[ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string.");
 
@@ -526,7 +526,7 @@ export const taxConfigStripe = z
   .object({
     code: z
       .string()
-      .regex(/^txcd_\d{8}$/)
+      .regex(new RegExp("^txcd_\\d{8}$"))
       .describe("Product [tax code](https://docs.stripe.com/tax/tax-codes)."),
   })
   .describe("The tax config for Stripe.");

api/spec/packages/aip-client-javascript/tests/void-responses.spec.ts

@@ -31,8 +31,20 @@ describe('void operations do not parse the response body', () => {
   it('resolves ingest of a batch of events (array body)', async () => {
     fetchMock.route('*', { status: 202, body: '' })
     const result = await funcs.ingestMeteringEvents(client(), [
-      { specversion: '1.0', id: 'evt-1', source: 'test', type: 'request', subject: 'customer-1' },
-      { specversion: '1.0', id: 'evt-2', source: 'test', type: 'request', subject: 'customer-2' },
+      {
+        specversion: '1.0',
+        id: 'evt-1',
+        source: 'test',
+        type: 'request',
+        subject: 'customer-1',
+      },
+      {
+        specversion: '1.0',
+        id: 'evt-2',
+        source: 'test',
+        type: 'request',
+        subject: 'customer-2',
+      },
     ])
     expect(result.ok).toBe(true)
     expect(result.value).toBeUndefined()

api/spec/packages/typespec-typescript/scripts/gen-runtime-templates.mjs

@@ -64,4 +64,6 @@ export const RUNTIME_TEMPLATES: Record<string, string> = Object.fromEntries(
 `
 
 writeFileSync(join(here, '../src/runtime-templates.ts'), out)
-console.log(`Wrote src/runtime-templates.ts (${entries.split('\n').length} files)`)
+console.log(
+  `Wrote src/runtime-templates.ts (${entries.split('\n').length} files)`,
+)

api/spec/packages/typespec-typescript/src/readme.ts

@@ -37,10 +37,7 @@ function summaryCell(op: SdkOperation): string {
 }
 
 function operationsTable(getter: string, ops: SdkOperation[]): string {
-  const header = [
-    '| Method | HTTP | Description |',
-    '| --- | --- | --- |',
-  ]
+  const header = ['| Method | HTTP | Description |', '| --- | --- | --- |']
   const rows = ops.map((op) => {
     const call = `\`client.${callPath(getter, op)}\``
     const http = `\`${op.verb.toUpperCase()} ${op.path}\``
@@ -113,7 +110,7 @@ function initialization(packageName: string): string {
     '',
     'const client = new OpenMeter({',
     "  baseUrl: 'https://openmeter.cloud/api/v3',",
-    "  apiKey: process.env.OPENMETER_API_KEY,",
+    '  apiKey: process.env.OPENMETER_API_KEY,',
     '})',
     '```',
     '',
@@ -126,7 +123,7 @@ function initialization(packageName: string): string {
     'const client = new OpenMeter({',
     '  baseUrl: ServerList[0],',
     "  serverVariables: { region: 'eu' },",
-    "  apiKey: process.env.OPENMETER_API_KEY,",
+    '  apiKey: process.env.OPENMETER_API_KEY,',
     '})',
     '```',
     '',
@@ -147,7 +144,7 @@ function usage(packageName: string): string {
     '',
     'const client = new OpenMeter({',
     "  baseUrl: 'https://openmeter.cloud/api/v3',",
-    "  apiKey: process.env.OPENMETER_API_KEY,",
+    '  apiKey: process.env.OPENMETER_API_KEY,',
     '})',
     '',
     'const meter = await client.meters.create({',
@@ -192,7 +189,7 @@ function errorHandling(packageName: string): string {
     '',
     'const client = new OpenMeter({',
     "  baseUrl: 'https://openmeter.cloud/api/v3',",
-    "  apiKey: process.env.OPENMETER_API_KEY,",
+    '  apiKey: process.env.OPENMETER_API_KEY,',
     '})',
     '',
     'try {',
@@ -218,7 +215,7 @@ function standaloneFunctions(packageName: string): string {
     '',
     'const client = new Client({',
     "  baseUrl: 'https://openmeter.cloud/api/v3',",
-    "  apiKey: process.env.OPENMETER_API_KEY,",
+    '  apiKey: process.env.OPENMETER_API_KEY,',
     '})',
     '',
     'const result = await funcs.listMeters(client)',