fix(sdk): TypeSpec emitters (#4719)

Author: tothandras

api/spec/AGENTS.md

@@ -253,17 +253,38 @@ second time in a `snake_case` "wire" pass (`WireModeContext` in the emitter), ke
 the raw JSON wire name and made `z.strictObject`, so a wrong-shaped or
 leaked-camelCase wire field is **rejected, not silently stripped**. Open models
 (record spread, `emitsAsIntersection`, e.g. `baseError`) stay non-strict — strict
-would defeat the record arm that exists to accept them. Because the wire pass is the
-same emitter walk as the camelCase pass (parameterized by key-casing + strictness +
-a separate refkey namespace), the two are structurally identical except for casing,
-**by construction** — no runtime schema derivation. A failure throws
+would defeat the record arm that exists to accept them. The wire pass uses the same
+emitter walk as the camelCase pass (parameterized by direction + key-casing +
+strictness + a separate refkey namespace), but it must describe the value **after**
+transport encoding: date-time values are strings, SDK-coded query parameters use
+their declared transport type, and defaults are absent. A failure throws
 `ValidationError`, which `request()` surfaces as `Result.error` (request validation
 runs _inside_ the `request()` closure so it does not throw synchronously).
 **Enabling `validate` re-introduces exactly the rejection the default policy
 avoids**: a strict wire schema rejects additive/unknown server fields and unknown
 enum values. It is opt-in defense-in-depth, not the default, precisely because the
 default contract must not break on additive fields.
 
+Models decorated with `@useRef` still need a local TypeSpec shape that matches the
+referenced OpenAPI schema. The TypeScript and Go emitters walk the local TypeSpec
+AST; `@useRef` only changes the emitted OpenAPI reference and does not import the
+referenced schema's requiredness or nullability into language-specific SDKs.
+
+TypeSpec defaults belong only on public schemas. `toWire` reads the public schema to
+materialize required request defaults before wire validation; `…Wire` schemas must
+not use Zod `.default(...)`, because the same schema validates responses and a
+default wrapper would accept a required field the server omitted. The query
+parameter name `sort` is reserved: it must use `Common.SortQuery` directly (not an
+alias), enforced by the AIP `sort-query-type` linter rule. Both SDK emitters select
+the sort codec from that validated HTTP parameter name. The TypeScript emitter must
+validate the public property schema before encoding and the encoded value against
+the operation's wire schema afterward.
+Generated path-parameter schemas are part of the same boundary: in strict mode,
+map path values to their transport representation, validate the mapped object,
+then interpolate and URL-encode it. Preserve path binding names during mapping;
+unlike JSON object keys, they must not be snake-cased. Keep mapping conditional so
+`validate: false` retains its established runtime behavior.
+
 ### Documented types: generated from TypeSpec, verified against zod
 
 **zod schemas and TypeScript types are separate artifacts with one source.** Both
@@ -651,7 +672,9 @@ not "correct" them to mainline ky.
   wire; the SDK accepts a `{by, order}` object and `encodeSort` flattens it. `by` is
   a **camelCase** field name in the SDK and is `toSnakeCase`-translated to the wire
   field name (the server validates snake field names; see
-  `api/v3/handlers/.../convert.go`).
+  `api/v3/handlers/.../convert.go`). Every query parameter named `sort` must use
+  `Common.SortQuery` directly; the AIP `sort-query-type` rule protects the
+  name-based codec selection used by both SDK emitters.
 
 ## Tests
 

api/spec/Makefile

@@ -31,6 +31,7 @@ generate: ## Generate OpenAPI spec
 test: ## Run AIP TypeScript SDK and emitter tests
 	$(call print-target)
 	pnpm --frozen-lockfile install
+	pnpm --filter @openmeter/api-spec-aip run test
 	pnpm run test:sdk:coverage
 	pnpm --filter @openmeter/typespec-typescript run check
 

api/spec/packages/aip-client-javascript/src/funcs/addons.ts

@@ -4,7 +4,13 @@ import { type Client, http } from '../core.js'
 import { type Result, type RequestOptions } from '../lib/types.js'
 import { request } from '../lib/request.js'
 import { toURLSearchParams, encodeSort } from '../lib/encodings.js'
-import { toWire, fromWire, assertValid, toSnakeCase } from '../lib/wire.js'
+import {
+  toWire,
+  toPathWire,
+  fromWire,
+  assertValid,
+  toSnakeCase,
+} from '../lib/wire.js'
 import * as schemas from '../models/schemas.js'
 import type {
   ListAddonsRequest,
@@ -36,6 +42,9 @@ export function listAddons(
   options?: RequestOptions,
 ): Promise<Result<ListAddonsResponse>> {
   return request(() => {
+    if (client._options.validate && req.sort !== undefined) {
+      assertValid(schemas.listAddonsQueryParams.shape.sort, req.sort)
+    }
     const query = toWire(
       {
         page: req.page,
@@ -102,11 +111,20 @@ export function updateAddon(
   options?: RequestOptions,
 ): Promise<Result<UpdateAddonResponse>> {
   return request(() => {
+    const pathParamsInput = {
+      addonId: req.addonId,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.updateAddonPathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.updateAddonPathParamsWire, pathParams)
+    }
     const path = `openmeter/addons/${(() => {
-      if (req.addonId === undefined) {
+      if (pathParams.addonId === undefined) {
         throw new Error('missing path parameter: addonId')
       }
-      return encodeURIComponent(String(req.addonId))
+      return encodeURIComponent(String(pathParams.addonId))
     })()}`
     const body = toWire(req.body, schemas.updateAddonBody)
     if (client._options.validate) {
@@ -137,11 +155,20 @@ export function getAddon(
   options?: RequestOptions,
 ): Promise<Result<GetAddonResponse>> {
   return request(() => {
+    const pathParamsInput = {
+      addonId: req.addonId,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.getAddonPathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.getAddonPathParamsWire, pathParams)
+    }
     const path = `openmeter/addons/${(() => {
-      if (req.addonId === undefined) {
+      if (pathParams.addonId === undefined) {
         throw new Error('missing path parameter: addonId')
       }
-      return encodeURIComponent(String(req.addonId))
+      return encodeURIComponent(String(pathParams.addonId))
     })()}`
     return http(client)
       .get(path, options)
@@ -168,11 +195,20 @@ export function deleteAddon(
   options?: RequestOptions,
 ): Promise<Result<DeleteAddonResponse>> {
   return request(async () => {
+    const pathParamsInput = {
+      addonId: req.addonId,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.deleteAddonPathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.deleteAddonPathParamsWire, pathParams)
+    }
     const path = `openmeter/addons/${(() => {
-      if (req.addonId === undefined) {
+      if (pathParams.addonId === undefined) {
         throw new Error('missing path parameter: addonId')
       }
-      return encodeURIComponent(String(req.addonId))
+      return encodeURIComponent(String(pathParams.addonId))
     })()}`
     await http(client).delete(path, options)
   })
@@ -191,11 +227,20 @@ export function archiveAddon(
   options?: RequestOptions,
 ): Promise<Result<ArchiveAddonResponse>> {
   return request(() => {
+    const pathParamsInput = {
+      addonId: req.addonId,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.archiveAddonPathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.archiveAddonPathParamsWire, pathParams)
+    }
     const path = `openmeter/addons/${(() => {
-      if (req.addonId === undefined) {
+      if (pathParams.addonId === undefined) {
         throw new Error('missing path parameter: addonId')
       }
-      return encodeURIComponent(String(req.addonId))
+      return encodeURIComponent(String(pathParams.addonId))
     })()}/archive`
     return http(client)
       .post(path, options)
@@ -222,11 +267,20 @@ export function publishAddon(
   options?: RequestOptions,
 ): Promise<Result<PublishAddonResponse>> {
   return request(() => {
+    const pathParamsInput = {
+      addonId: req.addonId,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.publishAddonPathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.publishAddonPathParamsWire, pathParams)
+    }
     const path = `openmeter/addons/${(() => {
-      if (req.addonId === undefined) {
+      if (pathParams.addonId === undefined) {
         throw new Error('missing path parameter: addonId')
       }
-      return encodeURIComponent(String(req.addonId))
+      return encodeURIComponent(String(pathParams.addonId))
     })()}/publish`
     return http(client)
       .post(path, options)

api/spec/packages/aip-client-javascript/src/funcs/apps.ts

@@ -3,8 +3,8 @@
 import { type Client, http } from '../core.js'
 import { type Result, type RequestOptions } from '../lib/types.js'
 import { request } from '../lib/request.js'
-import { toURLSearchParams, encodeSort } from '../lib/encodings.js'
-import { toWire, fromWire, assertValid } from '../lib/wire.js'
+import { toURLSearchParams } from '../lib/encodings.js'
+import { toWire, toPathWire, fromWire, assertValid } from '../lib/wire.js'
 import * as schemas from '../models/schemas.js'
 import type {
   ListAppsRequest,
@@ -61,11 +61,20 @@ export function getApp(
   options?: RequestOptions,
 ): Promise<Result<GetAppResponse>> {
   return request(() => {
+    const pathParamsInput = {
+      appId: req.appId,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.getAppPathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.getAppPathParamsWire, pathParams)
+    }
     const path = `openmeter/apps/${(() => {
-      if (req.appId === undefined) {
+      if (pathParams.appId === undefined) {
         throw new Error('missing path parameter: appId')
       }
-      return encodeURIComponent(String(req.appId))
+      return encodeURIComponent(String(pathParams.appId))
     })()}`
     return http(client)
       .get(path, options)

api/spec/packages/aip-client-javascript/src/funcs/billing.ts

@@ -3,8 +3,8 @@
 import { type Client, http } from '../core.js'
 import { type Result, type RequestOptions } from '../lib/types.js'
 import { request } from '../lib/request.js'
-import { toURLSearchParams, encodeSort } from '../lib/encodings.js'
-import { toWire, fromWire, assertValid } from '../lib/wire.js'
+import { toURLSearchParams } from '../lib/encodings.js'
+import { toWire, toPathWire, fromWire, assertValid } from '../lib/wire.js'
 import * as schemas from '../models/schemas.js'
 import type {
   ListBillingProfilesRequest,
@@ -101,11 +101,20 @@ export function getBillingProfile(
   options?: RequestOptions,
 ): Promise<Result<GetBillingProfileResponse>> {
   return request(() => {
+    const pathParamsInput = {
+      id: req.id,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.getBillingProfilePathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.getBillingProfilePathParamsWire, pathParams)
+    }
     const path = `openmeter/profiles/${(() => {
-      if (req.id === undefined) {
+      if (pathParams.id === undefined) {
         throw new Error('missing path parameter: id')
       }
-      return encodeURIComponent(String(req.id))
+      return encodeURIComponent(String(pathParams.id))
     })()}`
     return http(client)
       .get(path, options)
@@ -132,11 +141,20 @@ export function updateBillingProfile(
   options?: RequestOptions,
 ): Promise<Result<UpdateBillingProfileResponse>> {
   return request(() => {
+    const pathParamsInput = {
+      id: req.id,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.updateBillingProfilePathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.updateBillingProfilePathParamsWire, pathParams)
+    }
     const path = `openmeter/profiles/${(() => {
-      if (req.id === undefined) {
+      if (pathParams.id === undefined) {
         throw new Error('missing path parameter: id')
       }
-      return encodeURIComponent(String(req.id))
+      return encodeURIComponent(String(pathParams.id))
     })()}`
     const body = toWire(req.body, schemas.updateBillingProfileBody)
     if (client._options.validate) {
@@ -173,11 +191,20 @@ export function deleteBillingProfile(
   options?: RequestOptions,
 ): Promise<Result<DeleteBillingProfileResponse>> {
   return request(async () => {
+    const pathParamsInput = {
+      id: req.id,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.deleteBillingProfilePathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.deleteBillingProfilePathParamsWire, pathParams)
+    }
     const path = `openmeter/profiles/${(() => {
-      if (req.id === undefined) {
+      if (pathParams.id === undefined) {
         throw new Error('missing path parameter: id')
       }
-      return encodeURIComponent(String(req.id))
+      return encodeURIComponent(String(pathParams.id))
     })()}`
     await http(client).delete(path, options)
   })

api/spec/packages/aip-client-javascript/src/funcs/currencies.ts

@@ -4,7 +4,13 @@ import { type Client, http } from '../core.js'
 import { type Result, type RequestOptions } from '../lib/types.js'
 import { request } from '../lib/request.js'
 import { toURLSearchParams, encodeSort } from '../lib/encodings.js'
-import { toWire, fromWire, assertValid, toSnakeCase } from '../lib/wire.js'
+import {
+  toWire,
+  toPathWire,
+  fromWire,
+  assertValid,
+  toSnakeCase,
+} from '../lib/wire.js'
 import * as schemas from '../models/schemas.js'
 import type {
   ListCurrenciesRequest,
@@ -30,6 +36,9 @@ export function listCurrencies(
   options?: RequestOptions,
 ): Promise<Result<ListCurrenciesResponse>> {
   return request(() => {
+    if (client._options.validate && req.sort !== undefined) {
+      assertValid(schemas.listCurrenciesQueryParams.shape.sort, req.sort)
+    }
     const query = toWire(
       {
         page: req.page,
@@ -98,11 +107,20 @@ export function listCostBases(
   options?: RequestOptions,
 ): Promise<Result<ListCostBasesResponse>> {
   return request(() => {
+    const pathParamsInput = {
+      currencyId: req.currencyId,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.listCostBasesPathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.listCostBasesPathParamsWire, pathParams)
+    }
     const path = `openmeter/currencies/custom/${(() => {
-      if (req.currencyId === undefined) {
+      if (pathParams.currencyId === undefined) {
         throw new Error('missing path parameter: currencyId')
       }
-      return encodeURIComponent(String(req.currencyId))
+      return encodeURIComponent(String(pathParams.currencyId))
     })()}/cost-bases`
     const query = toWire(
       {
@@ -140,11 +158,20 @@ export function createCostBasis(
   options?: RequestOptions,
 ): Promise<Result<CreateCostBasisResponse>> {
   return request(() => {
+    const pathParamsInput = {
+      currencyId: req.currencyId,
+    }
+    const pathParams = client._options.validate
+      ? toPathWire(pathParamsInput, schemas.createCostBasisPathParams)
+      : pathParamsInput
+    if (client._options.validate) {
+      assertValid(schemas.createCostBasisPathParamsWire, pathParams)
+    }
     const path = `openmeter/currencies/custom/${(() => {
-      if (req.currencyId === undefined) {
+      if (pathParams.currencyId === undefined) {
         throw new Error('missing path parameter: currencyId')
       }
-      return encodeURIComponent(String(req.currencyId))
+      return encodeURIComponent(String(pathParams.currencyId))
     })()}/cost-bases`
     const body = toWire(req.body, schemas.createCostBasisBody)
     if (client._options.validate) {