Extend api contracts with route contract

packages/app/api-contracts/src/HttpStatusCodes.ts

@@ -62,3 +62,5 @@ export type HttpStatusCode =
   | 508
   | 510
   | 511
+
+export type SuccessfulHttpStatusCode = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226

packages/app/api-contracts/src/index.ts

@@ -4,6 +4,8 @@ export * from './contractBuilder.ts'
 export * from './HttpStatusCodes.ts'
 export * from './pathUtils.ts'
 export * from './rest/restContractBuilder.ts'
+export * from './route-contract/defineRouteContract.ts'
+export * from './route-contract/inferTypes.ts'
 // Dual-mode (hybrid) contracts
 export * from './sse/dualModeContracts.ts'
 // Contract builders

packages/app/api-contracts/src/route-contract/defineRouteContract.spec.ts

@@ -0,0 +1,20 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import { z } from 'zod/v4'
+import { defineRouteContract } from './defineRouteContract.ts'
+import type { InferSuccessSchema } from './inferTypes.ts'
+
+describe('defineRouteContract', () => {
+  it('preserves responseSchemasByStatusCode for success schema inference', () => {
+    const schema200 = z.object({ name: z.string() })
+    const route = defineRouteContract({
+      method: 'get',
+      pathResolver: () => '/users',
+      responseSchemasByStatusCode: {
+        200: schema200,
+      },
+    })
+
+    type SuccessSchema = InferSuccessSchema<typeof route.responseSchemasByStatusCode>
+    expectTypeOf<SuccessSchema>().toEqualTypeOf<typeof schema200>()
+  })
+})

packages/app/api-contracts/src/route-contract/defineRouteContract.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod/v4'
+import type { InferSchemaOutput, RoutePathResolver } from '../apiContracts.ts'
+import type { HttpStatusCode } from '../HttpStatusCodes.ts'
+
+export const ContractNoBody = Symbol.for('ContractNoBody');
+export type ContractNoBodyType = typeof ContractNoBody;
+
+export const ContractNonJsonResponse = Symbol.for('ContractNonJsonResponse');
+export type ContractNonJsonResponseType = typeof ContractNonJsonResponse;
+
+export type RouteContractResponse = ContractNoBodyType | ContractNonJsonResponseType | z.Schema
+
+export type ResponseSchemasByStatusCode = Partial<
+    Record<HttpStatusCode, RouteContractResponse>
+>;
+
+type CommonRouteContract<PathParamsSchema extends z.Schema | undefined> = {
+  pathResolver: RoutePathResolver<InferSchemaOutput<PathParamsSchema>>
+  requestPathParamsSchema?: z.Schema
+  requestQuerySchema?: z.Schema
+  requestHeaderSchema?: z.Schema
+  responseHeaderSchema?: z.Schema
+  responseSchemasByStatusCode?: ResponseSchemasByStatusCode
+
+  metadata?: Record<string, unknown>
+  summary?: string
+  description?: string
+  tags?: readonly string[]
+}
+
+/**
+ * Configuration for building a GET route.
+ */
+export type GetRouteContract<PathParamsSchema extends z.Schema | undefined> =
+  CommonRouteContract<PathParamsSchema> & {
+    method: 'get'
+    requestBodySchema?: never
+  }
+
+/**
+ * Configuration for building a DELETE route.
+ */
+export type DeleteRouteContract<PathParamsSchema extends z.Schema | undefined> =
+  CommonRouteContract<PathParamsSchema> & {
+    method: 'delete'
+    requestBodySchema?: never
+  }
+
+/**
+ * Configuration for building a payload route (POST, PUT, PATCH).
+ */
+export type PayloadRouteContract<PathParamsSchema extends z.Schema | undefined> =
+  CommonRouteContract<PathParamsSchema> & {
+    method: 'post' | 'put' | 'patch'
+    requestBodySchema: z.Schema| ContractNoBodyType
+  }
+
+export type RouteContract<PathParamsSchema extends z.Schema | undefined> =
+  | GetRouteContract<PathParamsSchema>
+  | DeleteRouteContract<PathParamsSchema>
+  | PayloadRouteContract<PathParamsSchema>
+
+/** * Helper to prevent extra keys.
+ * If T has keys not in U, it forces an error.
+ */
+type Exactly<T, U> = T & {
+  [K in keyof T]: K extends keyof U ? T[K] : never
+}
+
+export const defineRouteContract = <
+  PathParamsSchema extends z.Schema | undefined,
+  const Contract extends RouteContract<PathParamsSchema>,
+>(
+  route: Exactly<Contract, RouteContract<PathParamsSchema>> & {
+    requestPathParamsSchema?: PathParamsSchema
+  },
+): Contract => route
+
+export const mapRouteContractToPath = (routeConfig: RouteContract<any>): string => {
+  if (!routeConfig.requestPathParamsSchema) {
+    return routeConfig.pathResolver(undefined)
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: cannot infer zod object with typed shape here
+  const shape = (routeConfig.requestPathParamsSchema as any).shape
+  const resolverParams: Record<string, string> = {}
+  for (const key of Object.keys(shape)) {
+    resolverParams[key] = `:${key}`
+  }
+
+  return routeConfig.pathResolver(resolverParams)
+}
+
+export const describeRouteContract = (routeConfig: RouteContract<any>): string => {
+  return `${routeConfig.method.toUpperCase()} ${mapRouteContractToPath(routeConfig)}`
+}
+
+const SUCCESSFUL_STATUS_CODES = [200, 201, 202, 203, 204, 205, 206, 207, 208, 226] as const
+
+export const getSuccessResponseSchema = (routeConfig: RouteContract<any>): z.Schema | null => {
+  const { responseSchemasByStatusCode } = routeConfig
+  if (!responseSchemasByStatusCode) {
+      return null
+  }
+
+  const schemas: z.Schema[] = []
+
+  for (const code of SUCCESSFUL_STATUS_CODES) {
+    const value = responseSchemasByStatusCode[code]
+
+      if (!value) {
+          continue
+      }
+
+      if (typeof value === 'symbol') {
+          schemas.push(z.never())
+      } else {
+          schemas.push(value)
+      }
+  }
+
+  if (schemas.length === 0) {
+      return null
+  }
+  if (schemas.length > 1) {
+      return z.union(schemas)
+  }
+  return schemas.at(0) ?? null
+}
+
+
+export const getIsEmptyResponseExpected = (routeConfig: RouteContract<any>): boolean => {
+    const { responseSchemasByStatusCode } = routeConfig
+    if (!responseSchemasByStatusCode) {
+        return true
+    }
+
+    let isEmptyResponseExpected = true
+
+    for (const code of SUCCESSFUL_STATUS_CODES) {
+        const value = responseSchemasByStatusCode[code]
+
+        if (value && typeof value !== 'symbol') {
+            isEmptyResponseExpected = false
+            break
+        }
+    }
+
+    return isEmptyResponseExpected
+}

packages/app/api-contracts/src/route-contract/inferTypes.spec.ts

@@ -0,0 +1,69 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import { z } from 'zod/v4'
+import type { InferSuccessResponse, InferSuccessSchema } from './inferTypes.ts'
+
+describe('InferSuccessSchema', () => {
+  it('extracts undefined when responseSchemasByStatusCode is undefined', () => {
+    type Result = InferSuccessSchema<undefined>
+    expectTypeOf<Result>().toEqualTypeOf<undefined>()
+  })
+
+  it('extracts never when no success response schemas are defined', () => {
+    const schema404 = z.object({ message: z.string() })
+
+    const schemaByStatusCode = {
+      404: schema404,
+    } as const
+    type Result = InferSuccessSchema<typeof schemaByStatusCode>
+
+    expectTypeOf<Result>().toEqualTypeOf<never>()
+  })
+
+  it('extracts the union of success response schemas', () => {
+    const schema200 = z.object({ name: z.string() })
+    const schema201 = z.object({ id: z.string() })
+    const schema404 = z.object({ message: z.string() })
+
+    const schemaByStatusCode = {
+      200: schema200,
+      201: schema201,
+      404: schema404,
+    } as const
+    type Result = InferSuccessSchema<typeof schemaByStatusCode>
+
+    expectTypeOf<Result>().toEqualTypeOf<typeof schema200 | typeof schema201>()
+  })
+})
+
+describe('InferSuccessResponse', () => {
+  it('extracts undefined when responseSchemasByStatusCode is undefined', () => {
+    type Result = InferSuccessResponse<undefined>
+    expectTypeOf<Result>().toEqualTypeOf<undefined>()
+  })
+
+  it('extracts never when no success response schemas are defined', () => {
+    const schema404 = z.object({ message: z.string() })
+
+    const schemaByStatusCode = {
+      404: schema404,
+    } as const
+    type Result = InferSuccessResponse<typeof schemaByStatusCode>
+
+    expectTypeOf<Result>().toEqualTypeOf<never>()
+  })
+
+  it('extracts the union of success response schemas', () => {
+    const schema200 = z.object({ name: z.string() })
+    const schema201 = z.object({ id: z.string() })
+    const schema404 = z.object({ message: z.string() })
+
+    const schemaByStatusCode = {
+      200: schema200,
+      201: schema201,
+      404: schema404,
+    } as const
+    type Result = InferSuccessResponse<typeof schemaByStatusCode>
+
+    expectTypeOf<Result>().toEqualTypeOf<{ name: string } | { id: string }>()
+  })
+})

packages/app/api-contracts/src/route-contract/inferTypes.ts

@@ -0,0 +1,34 @@
+import type { z } from 'zod/v4'
+import type { SuccessfulHttpStatusCode } from '../HttpStatusCodes.ts'
+import type { ResponseSchemasByStatusCode } from './defineRouteContract.ts'
+
+type InferSchemaOutput<T extends z.ZodSchema | undefined> = T extends z.ZodSchema
+  ? z.output<T>
+  : undefined
+
+/** Maps ContractNoBodyType and ContractNonJsonResponseType to undefined, preserving z.Schema as-is. */
+type ToZodSchema<T> = T extends z.Schema ? T : undefined
+
+type ValueOf<
+  ObjectType,
+  ValueType extends keyof ObjectType = keyof ObjectType,
+> = ObjectType[ValueType]
+
+/**
+ * Infers the union of all success response Zod schemas from a responseSchemaByStatusCode map.
+ * ContractNoBody entries are mapped to undefined.
+ */
+export type InferSuccessSchema<
+  T extends ResponseSchemasByStatusCode | undefined,
+> =
+  T extends ResponseSchemasByStatusCode
+    ? ToZodSchema<ValueOf<T, Extract<keyof T, SuccessfulHttpStatusCode>>>
+    : undefined
+
+/**
+ * Infers the union of TypeScript output types of all success response schemas
+ * from a responseSchemasByStatusCode map.
+ */
+export type InferSuccessResponse<
+  T extends ResponseSchemasByStatusCode | undefined,
+> = InferSchemaOutput<InferSuccessSchema<T>>