improvement(repo): consolidation of boundary helpers + better unknown usage

Author: icecrasher321

.agents/skills/add-integration/SKILL.md

@@ -615,7 +615,7 @@ export type {Service}UploadResponse = z.output<typeof {service}UploadResponseSch
 import { createLogger } from '@sim/logger'
 import { NextResponse, type NextRequest } from 'next/server'
 import { {service}UploadContract } from '@/lib/api/contracts/{service}-tools'
-import { parseRequest, validationErrorResponseFromError } from '@/lib/api/server'
+import { parseRequest } from '@/lib/api/server'
 import { checkInternalAuth } from '@/lib/auth/hybrid'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
@@ -633,12 +633,9 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     return NextResponse.json({ success: false, error: 'Unauthorized' }, { status: 401 })
   }
 
-  let data
-  try {
-    ;({ body: data } = await parseRequest({service}UploadContract, request))
-  } catch (error) {
-    return validationErrorResponseFromError(error)
-  }
+  const parsed = await parseRequest({service}UploadContract, request, {})
+  if (!parsed.success) return parsed.response
+  const data = parsed.data.body
 
   let fileBuffer: Buffer
   let fileName: string

.cursor/rules/sim-architecture.mdc

@@ -61,9 +61,9 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 
 - Each contract is built with `defineRouteContract({ method, path, params?, query?, body?, headers?, response: { mode: 'json', schema } })` and exports both schemas and named TypeScript type aliases (e.g., `export type CreateFolderBody = z.input<typeof createFolderBodySchema>`).
 - Shared identifier schemas live in `apps/sim/lib/api/contracts/primitives.ts`.
-- Routes validate via canonical helpers in `apps/sim/lib/api/server/validation.ts` (`parseRequest`, `validateSchema`, `validationErrorResponse`, `getValidationErrorMessage`, `isZodError`). Routes never `import { z } from 'zod'` and never use `instanceof z.ZodError`.
+- Routes validate via canonical helpers in `apps/sim/lib/api/server/validation.ts` (`parseRequest`, `validationErrorResponse`, `getValidationErrorMessage`, `isZodError`). Routes never `import { z } from 'zod'` and never use `instanceof z.ZodError`.
 - Clients call `requestJson(contract, ...)` from `apps/sim/lib/api/client/request.ts`; hooks import named type aliases from contracts, never `z.input/z.output`.
 - Routes under `apps/sim/app/api/v1/**` use `apps/sim/app/api/v1/middleware.ts` for shared auth, rate-limit, and workspace access. Compose contract validation inside that middleware.
 - `bun run check:api-validation` enforces this policy and must pass on PRs.
 
-`bun run check:api-validation:strict` is the strict CI gate and additionally fails on annotations with empty reasons. Two per-line opt-out forms are recognized: `// boundary-raw-fetch: <reason>` (placed immediately above a legitimate raw `fetch(` call in `apps/sim/hooks/queries/**` or `apps/sim/hooks/selectors/**` for stream/binary/multipart/signed-URL/OAuth-redirect/external-origin cases) and `// double-cast-allowed: <reason>` (placed immediately above an `as unknown as X` cast outside test files). The reason must be non-empty. Whole-file allowlists for routes that legitimately import Zod for non-boundary reasons go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.
+`bun run check:api-validation:strict` is the strict CI gate and additionally fails on annotations with empty reasons. Four per-line opt-out forms are recognized: `// boundary-raw-fetch: <reason>` (placed immediately above a legitimate raw `fetch(` call in `apps/sim/hooks/queries/**` or `apps/sim/hooks/selectors/**` for stream/binary/multipart/signed-URL/OAuth-redirect/external-origin cases), `// double-cast-allowed: <reason>` (placed immediately above an `as unknown as X` cast outside test files), `// boundary-raw-json: <reason>` (placed immediately above a raw `await request.json()` / `await req.json()` read in a route handler that cannot go through `parseRequest` — JSON-RPC envelopes, tolerant `.catch(() => ({}))` parses), and `// untyped-response: <reason>` (placed immediately above a `schema: z.unknown()` response declaration in a contract file when the response body is genuinely opaque). The reason must be non-empty. Whole-file allowlists for routes that legitimately import Zod for non-boundary reasons go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.

AGENTS.md

@@ -130,10 +130,12 @@ Domain validators that are not HTTP boundaries — tools, blocks, triggers, conn
 
 ### Boundary annotations
 
-A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes two annotation forms:
+A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes four annotation forms:
 
 - `// boundary-raw-fetch: <reason>` — placed on the line directly above a raw `fetch(` call inside `apps/sim/hooks/queries/**` or `apps/sim/hooks/selectors/**`. Use only for documented exceptions: streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, and external-origin requests
 - `// double-cast-allowed: <reason>` — placed on the line directly above an `as unknown as X` cast outside test files
+- `// boundary-raw-json: <reason>` — placed on the line directly above a raw `await request.json()` / `await req.json()` read in a route handler. Use only when the body is a JSON-RPC envelope, a tolerant `.catch(() => ({}))` parse, or otherwise cannot go through `parseRequest`
+- `// untyped-response: <reason>` — placed on the line directly above a `schema: z.unknown()` response declaration in a contract file. Use only when the response body is genuinely opaque (user-supplied data, third-party passthrough)
 
 Placement rule: the annotation must immediately precede the call or cast. Up to three non-empty preceding comment lines are tolerated, so additional context comments above the annotation are fine. The reason must be non-empty after trimming — annotations with empty reasons fail strict mode (`annotationsMissingReason`).
 
@@ -155,8 +157,7 @@ const provider = config as unknown as LegacyProvider
 
 Routes never `import { z } from 'zod'` and never define route-local boundary schemas. They consume the contract from `@/lib/api/contracts/**` and validate with canonical helpers from `@/lib/api/server`:
 
-- `parseRequest(contract, request, context)` — fully contract-bound routes; parses params, query, body, and headers in one call
-- `validateSchema(schema, data)` — for ad-hoc validation against a contract schema or primitive
+- `parseRequest(contract, request, context, options?)` — fully contract-bound routes; parses params, query, body, and headers in one call. Pass `{}` for `context` on routes without route params, or the route's `context` argument when route params exist. Returns a discriminated union; check `parsed.success` and return `parsed.response` on failure
 - `validationErrorResponse(error)` and `getValidationErrorMessage(error, fallback)` — produce 400 responses from a `ZodError`
 - `validationErrorResponseFromError(error)` — when handling unknown caught errors that may or may not be a `ZodError`
 - `isZodError(error)` — type guard. Routes never use `instanceof z.ZodError`
@@ -168,19 +169,17 @@ import { createLogger } from '@sim/logger'
 import type { NextRequest } from 'next/server'
 import { NextResponse } from 'next/server'
 import { createFolderContract } from '@/lib/api/contracts/folders'
-import { parseRequest, validationErrorResponseFromError } from '@/lib/api/server'
+import { parseRequest } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 
 const logger = createLogger('FoldersAPI')
 
 export const POST = withRouteHandler(async (request: NextRequest) => {
-  try {
-    const { body } = await parseRequest(createFolderContract, request)
-    logger.info('Creating folder', { workspaceId: body.workspaceId })
-    return NextResponse.json({ ok: true })
-  } catch (error) {
-    return validationErrorResponseFromError(error)
-  }
+  const parsed = await parseRequest(createFolderContract, request, {})
+  if (!parsed.success) return parsed.response
+  const { body } = parsed.data
+  logger.info('Creating folder', { workspaceId: body.workspaceId })
+  return NextResponse.json({ ok: true })
 })
 ```
 

CLAUDE.md

@@ -109,10 +109,12 @@ Domain validators that are not HTTP boundaries — tools, blocks, triggers, conn
 
 ### Boundary annotations
 
-A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes two annotation forms:
+A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes four annotation forms:
 
 - `// boundary-raw-fetch: <reason>` — placed on the line directly above a raw `fetch(` call inside `apps/sim/hooks/queries/**` or `apps/sim/hooks/selectors/**`. Use only for documented exceptions: streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, and external-origin requests
 - `// double-cast-allowed: <reason>` — placed on the line directly above an `as unknown as X` cast outside test files
+- `// boundary-raw-json: <reason>` — placed on the line directly above a raw `await request.json()` / `await req.json()` read in a route handler. Use only when the body is a JSON-RPC envelope, a tolerant `.catch(() => ({}))` parse, or otherwise cannot go through `parseRequest`
+- `// untyped-response: <reason>` — placed on the line directly above a `schema: z.unknown()` response declaration in a contract file. Use only when the response body is genuinely opaque (user-supplied data, third-party passthrough)
 
 Placement rule: the annotation must immediately precede the call or cast. Up to three non-empty preceding comment lines are tolerated, so additional context comments above the annotation are fine. The reason must be non-empty after trimming — annotations with empty reasons fail strict mode (`annotationsMissingReason`).
 
@@ -136,8 +138,7 @@ Every API route handler must be wrapped with `withRouteHandler`. This sets up `A
 
 Routes never `import { z } from 'zod'` and never define route-local boundary schemas. They consume the contract from `@/lib/api/contracts/**` and validate with canonical helpers from `@/lib/api/server`:
 
-- `parseRequest(contract, request, context)` — fully contract-bound routes; parses params, query, body, and headers in one call
-- `validateSchema(schema, data)` — for ad-hoc validation against a contract schema or primitive
+- `parseRequest(contract, request, context, options?)` — fully contract-bound routes; parses params, query, body, and headers in one call. Pass `{}` for `context` on routes without route params, or the route's `context` argument when route params exist. Returns a discriminated union; check `parsed.success` and return `parsed.response` on failure
 - `validationErrorResponse(error)` and `getValidationErrorMessage(error, fallback)` — produce 400 responses from a `ZodError`
 - `validationErrorResponseFromError(error)` — when handling unknown caught errors that may or may not be a `ZodError`
 - `isZodError(error)` — type guard. Routes never use `instanceof z.ZodError`
@@ -149,19 +150,17 @@ import { createLogger } from '@sim/logger'
 import type { NextRequest } from 'next/server'
 import { NextResponse } from 'next/server'
 import { createFolderContract } from '@/lib/api/contracts/folders'
-import { parseRequest, validationErrorResponseFromError } from '@/lib/api/server'
+import { parseRequest } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 
 const logger = createLogger('FoldersAPI')
 
 export const POST = withRouteHandler(async (request: NextRequest) => {
-  try {
-    const { body } = await parseRequest(createFolderContract, request)
-    logger.info('Creating folder', { workspaceId: body.workspaceId })
-    return NextResponse.json({ ok: true })
-  } catch (error) {
-    return validationErrorResponseFromError(error)
-  }
+ const parsed = await parseRequest(createFolderContract, request, {})
+ if (!parsed.success) return parsed.response
+ const { body } = parsed.data
+ logger.info('Creating folder', { workspaceId: body.workspaceId })
+ return NextResponse.json({ ok: true })
 })
 ```
 

apps/sim/AGENTS.md

@@ -81,10 +81,12 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 
 ### Boundary annotations
 
-A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes two annotation forms:
+A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes four annotation forms:
 
 - `// boundary-raw-fetch: <reason>` — placed on the line directly above a raw `fetch(` call inside `apps/sim/hooks/queries/**` or `apps/sim/hooks/selectors/**`. Use only for documented exceptions: streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, and external-origin requests.
 - `// double-cast-allowed: <reason>` — placed on the line directly above an `as unknown as X` cast outside test files.
+- `// boundary-raw-json: <reason>` — placed on the line directly above a raw `await request.json()` / `await req.json()` read in a route handler. Use only when the body is a JSON-RPC envelope, a tolerant `.catch(() => ({}))` parse, or otherwise cannot go through `parseRequest`.
+- `// untyped-response: <reason>` — placed on the line directly above a `schema: z.unknown()` response declaration in a contract file. Use only when the response body is genuinely opaque (user-supplied data, third-party passthrough).
 
 Placement rule: the annotation must immediately precede the call or cast. Up to three non-empty preceding comment lines are tolerated, so additional context comments above the annotation are fine. The reason must be non-empty after trimming — annotations with empty reasons fail strict mode (`annotationsMissingReason`).
 
@@ -106,8 +108,7 @@ const provider = config as unknown as LegacyProvider
 
 Routes never `import { z } from 'zod'` and never define route-local boundary schemas. They consume the contract from `@/lib/api/contracts/**` and validate with canonical helpers from `@/lib/api/server`:
 
-- `parseRequest(contract, request, context)` — fully contract-bound routes; parses params, query, body, and headers in one call.
-- `validateSchema(schema, data)` — for ad-hoc validation against a contract schema or primitive.
+- `parseRequest(contract, request, context, options?)` — fully contract-bound routes; parses params, query, body, and headers in one call. Pass `{}` for `context` on routes without route params, or the route's `context` argument when route params exist. Returns a discriminated union; check `parsed.success` and return `parsed.response` on failure.
 - `validationErrorResponse(error)` and `getValidationErrorMessage(error, fallback)` — produce 400 responses from a `ZodError`.
 - `validationErrorResponseFromError(error)` — when handling unknown caught errors that may or may not be a `ZodError`.
 - `isZodError(error)` — type guard. Routes never use `instanceof z.ZodError`.
@@ -119,19 +120,17 @@ import { createLogger } from '@sim/logger'
 import type { NextRequest } from 'next/server'
 import { NextResponse } from 'next/server'
 import { createFolderContract } from '@/lib/api/contracts/folders'
-import { parseRequest, validationErrorResponseFromError } from '@/lib/api/server'
+import { parseRequest } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 
 const logger = createLogger('FoldersAPI')
 
 export const POST = withRouteHandler(async (request: NextRequest) => {
-  try {
-    const { body } = await parseRequest(createFolderContract, request)
-    logger.info('Creating folder', { workspaceId: body.workspaceId })
-    return NextResponse.json({ ok: true })
-  } catch (error) {
-    return validationErrorResponseFromError(error)
-  }
+  const parsed = await parseRequest(createFolderContract, request, {})
+  if (!parsed.success) return parsed.response
+  const { body } = parsed.data
+  logger.info('Creating folder', { workspaceId: body.workspaceId })
+  return NextResponse.json({ ok: true })
 })
 ```
 

apps/sim/app/(landing)/components/contact/contact-form.tsx

@@ -7,14 +7,14 @@ import { useMutation } from '@tanstack/react-query'
 import Link from 'next/link'
 import { Combobox, Input, Textarea } from '@/components/emcn'
 import { Check } from '@/components/emcn/icons'
-import { flattenFieldErrors } from '@/lib/api/contracts/primitives'
-import { getEnv } from '@/lib/core/config/env'
-import { captureClientEvent } from '@/lib/posthog/client'
 import {
   CONTACT_TOPIC_OPTIONS,
   type ContactRequestPayload,
   contactRequestSchema,
-} from '@/app/(landing)/components/contact/consts'
+} from '@/lib/api/contracts/contact'
+import { flattenFieldErrors } from '@/lib/api/contracts/primitives'
+import { getEnv } from '@/lib/core/config/env'
+import { captureClientEvent } from '@/lib/posthog/client'
 import { LandingField } from '@/app/(landing)/components/forms/landing-field'
 
 type ContactField = keyof ContactRequestPayload

apps/sim/app/(landing)/components/demo-request/demo-request-modal.tsx

@@ -14,13 +14,13 @@ import {
   Textarea,
 } from '@/components/emcn'
 import { Check } from '@/components/emcn/icons'
-import { flattenFieldErrors } from '@/lib/api/contracts/primitives'
-import { captureClientEvent } from '@/lib/posthog/client'
 import {
   DEMO_REQUEST_COMPANY_SIZE_OPTIONS,
   type DemoRequestPayload,
   demoRequestSchema,
-} from '@/app/(landing)/components/demo-request/consts'
+} from '@/lib/api/contracts/demo-requests'
+import { flattenFieldErrors } from '@/lib/api/contracts/primitives'
+import { captureClientEvent } from '@/lib/posthog/client'
 import { LandingField } from '@/app/(landing)/components/forms/landing-field'
 
 interface DemoRequestModalProps {

apps/sim/app/api/academy/certificates/route.ts

@@ -6,8 +6,8 @@ import { and, eq } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
 import { getCourseById } from '@/lib/academy/content'
 import type { CertificateMetadata } from '@/lib/academy/types'
-import { issueAcademyCertificateBodySchema } from '@/lib/api/contracts'
-import { validateSchema } from '@/lib/api/server'
+import { issueAcademyCertificateContract } from '@/lib/api/contracts'
+import { parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import type { TokenBucketConfig } from '@/lib/core/rate-limiter'
 import { RateLimiter } from '@/lib/core/rate-limiter'
@@ -43,11 +43,10 @@ export const POST = withRouteHandler(async (req: NextRequest) => {
       return NextResponse.json({ error: 'Too many requests' }, { status: 429 })
     }
 
-    const body = await req.json()
-    const parsed = validateSchema(issueAcademyCertificateBodySchema, body)
+    const parsed = await parseRequest(issueAcademyCertificateContract, req, {})
     if (!parsed.success) return parsed.response
 
-    const { courseId, completedLessonIds } = parsed.data
+    const { courseId, completedLessonIds } = parsed.data.body
 
     const course = getCourseById(courseId)
     if (!course) {