improvement(api): simplify internal route declarations

Author: TheodoreSpeaks

.agents/skills/migrate-file-operation/SKILL.md

@@ -52,7 +52,7 @@ Keep responsibilities in these layers:
 1. Route/tool adapter: authenticate, construct a `Principal`, select the operation and rate policy, parse the surface contract, call the use case, and render the surface response.
 2. Application use case: load the canonical resource, compare any asserted workspace, authorize the operation, run the business operation, record semantic audit, and trigger shared domain notifications.
 3. Manager/repository: execute storage and database reads/writes. Accept canonical IDs and workspace scope, not credentials or principals.
-4. Presenter: return the contract success body only. Never return `NextResponse`, rate metadata, or errors.
+4. Presenter: return the contract success body only. Omit it when the use-case result already matches the contract. Never return `NextResponse`, rate metadata, or errors.
 
 Use this order for ordinary JSON routes:
 
@@ -147,9 +147,9 @@ Use `defineInternalJsonRoute` and explicitly declare:
 - `mapInput`
 - `useCase`
 - optional `onSuccess` only to preserve surface-specific behavior
-- `present`
+- `present` when the surface wire body differs from the use-case result
 
-Keep the existing internal success and error envelope. The builder owns `withRouteHandler`, authentication-before-parse ordering, response validation, and `NextResponse` creation.
+Keep the existing internal success and error envelope. Error policies project typed status/body descriptors rather than constructing responses. The builder owns `withRouteHandler`, authentication-before-parse ordering, response validation, and `NextResponse` creation.
 
 ### V2 JSON
 

.claude/commands/migrate-file-operation.md

@@ -51,7 +51,7 @@ Keep responsibilities in these layers:
 1. Route/tool adapter: authenticate, construct a `Principal`, select the operation and rate policy, parse the surface contract, call the use case, and render the surface response.
 2. Application use case: load the canonical resource, compare any asserted workspace, authorize the operation, run the business operation, record semantic audit, and trigger shared domain notifications.
 3. Manager/repository: execute storage and database reads/writes. Accept canonical IDs and workspace scope, not credentials or principals.
-4. Presenter: return the contract success body only. Never return `NextResponse`, rate metadata, or errors.
+4. Presenter: return the contract success body only. Omit it when the use-case result already matches the contract. Never return `NextResponse`, rate metadata, or errors.
 
 Use this order for ordinary JSON routes:
 
@@ -146,9 +146,9 @@ Use `defineInternalJsonRoute` and explicitly declare:
 - `mapInput`
 - `useCase`
 - optional `onSuccess` only to preserve surface-specific behavior
-- `present`
+- `present` when the surface wire body differs from the use-case result
 
-Keep the existing internal success and error envelope. The builder owns `withRouteHandler`, authentication-before-parse ordering, response validation, and `NextResponse` creation.
+Keep the existing internal success and error envelope. Error policies project typed status/body descriptors rather than constructing responses. The builder owns `withRouteHandler`, authentication-before-parse ordering, response validation, and `NextResponse` creation.
 
 ### V2 JSON
 

.cursor/commands/migrate-file-operation.md

@@ -47,7 +47,7 @@ Keep responsibilities in these layers:
 1. Route/tool adapter: authenticate, construct a `Principal`, select the operation and rate policy, parse the surface contract, call the use case, and render the surface response.
 2. Application use case: load the canonical resource, compare any asserted workspace, authorize the operation, run the business operation, record semantic audit, and trigger shared domain notifications.
 3. Manager/repository: execute storage and database reads/writes. Accept canonical IDs and workspace scope, not credentials or principals.
-4. Presenter: return the contract success body only. Never return `NextResponse`, rate metadata, or errors.
+4. Presenter: return the contract success body only. Omit it when the use-case result already matches the contract. Never return `NextResponse`, rate metadata, or errors.
 
 Use this order for ordinary JSON routes:
 
@@ -142,9 +142,9 @@ Use `defineInternalJsonRoute` and explicitly declare:
 - `mapInput`
 - `useCase`
 - optional `onSuccess` only to preserve surface-specific behavior
-- `present`
+- `present` when the surface wire body differs from the use-case result
 
-Keep the existing internal success and error envelope. The builder owns `withRouteHandler`, authentication-before-parse ordering, response validation, and `NextResponse` creation.
+Keep the existing internal success and error envelope. Error policies project typed status/body descriptors rather than constructing responses. The builder owns `withRouteHandler`, authentication-before-parse ordering, response validation, and `NextResponse` creation.
 
 ### V2 JSON
 

apps/sim/app/api/workspaces/[id]/files/[fileId]/compiled-check/route.ts

@@ -1,42 +1,23 @@
-import { NextResponse } from 'next/server'
 import { workspaceFileCompiledCheckContract } from '@/lib/api/contracts/workspace-files'
 import {
   defineInternalJsonRoute,
   internalRateLimits,
   internalSessionAuth,
 } from '@/lib/api/server/routes'
-import { internalPlainFileErrorPolicy } from '@/lib/workspace-files/api'
-import {
-  CompiledCheckTooLargeError,
-  CompiledCheckUnsupportedError,
-  compiledCheckWorkspaceFile,
-} from '@/lib/workspace-files/application/compiled-check-workspace-file'
+import { internalFileErrorPolicies } from '@/lib/workspace-files/api'
+import { compiledCheckWorkspaceFile } from '@/lib/workspace-files/application/compiled-check-workspace-file'
 
 export const dynamic = 'force-dynamic'
 export const runtime = 'nodejs'
 
-const compiledCheckErrorPolicy = {
-  ...internalPlainFileErrorPolicy,
-  render(error: unknown) {
-    if (error instanceof CompiledCheckUnsupportedError) {
-      return NextResponse.json({ error: error.message }, { status: 422 })
-    }
-    if (error instanceof CompiledCheckTooLargeError) {
-      return NextResponse.json({ error: error.message }, { status: 413 })
-    }
-    return internalPlainFileErrorPolicy.render(error)
-  },
-}
-
 export const GET = defineInternalJsonRoute({
   contract: workspaceFileCompiledCheckContract,
   auth: internalSessionAuth,
   operation: compiledCheckWorkspaceFile.operation,
   rateLimit: internalRateLimits.none({
     reason: 'Preserve existing internal compiled-check behavior',
   }),
-  errorPolicy: compiledCheckErrorPolicy,
+  errorPolicy: internalFileErrorPolicies.compiledCheck,
   mapInput: ({ params }) => ({ fileId: params.fileId, assertedWorkspaceId: params.id }),
   useCase: compiledCheckWorkspaceFile,
-  present: (result) => result,
 })

apps/sim/app/api/workspaces/[id]/files/[fileId]/content/route.ts

@@ -4,7 +4,7 @@ import {
   internalRateLimits,
   internalSessionAuth,
 } from '@/lib/api/server/routes'
-import { internalFileErrorPolicy } from '@/lib/workspace-files/api'
+import { internalFileErrorPolicies, internalFilePresenters } from '@/lib/workspace-files/api'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { updateWorkspaceFileContent } from '@/lib/workspace-files/application/update-workspace-file-content'
 import { MAX_WORKSPACE_FILE_INLINE_BODY_BYTES } from '@/lib/workspace-files/orchestration'
@@ -19,7 +19,7 @@ export const PUT = defineInternalJsonRoute({
   rateLimit: internalRateLimits.none({
     reason: 'Preserve existing internal content-update behavior',
   }),
-  errorPolicy: internalFileErrorPolicy,
+  errorPolicy: internalFileErrorPolicies.default,
   parseOptions: { maxBodyBytes: MAX_WORKSPACE_FILE_INLINE_BODY_BYTES },
   beforeParse: async ({ principal, params }) => {
     if (typeof params.fileId === 'string') {
@@ -33,5 +33,5 @@ export const PUT = defineInternalJsonRoute({
     encoding: body.encoding === 'base64' ? ('base64' as const) : ('utf-8' as const),
   }),
   useCase: updateWorkspaceFileContent,
-  present: ({ file }) => ({ success: true, file: { ...file, folderId: file.folderId ?? null } }),
+  present: internalFilePresenters.successFile,
 })

apps/sim/app/api/workspaces/[id]/files/[fileId]/csv-preview/route.ts

@@ -1,10 +1,7 @@
 import { createLogger } from '@sim/logger'
 import { getWorkspaceCsvPreviewContract } from '@/lib/api/contracts/workspace-file-table'
 import { defineInternalJsonRoute, internalRateLimits } from '@/lib/api/server/routes'
-import {
-  internalPlainFileErrorPolicy,
-  internalSessionOrServiceAuth,
-} from '@/lib/workspace-files/api'
+import { internalFileErrorPolicies, internalSessionOrServiceAuth } from '@/lib/workspace-files/api'
 import { csvPreviewWorkspaceFile } from '@/lib/workspace-files/application/csv-preview-workspace-file'
 
 const logger = createLogger('WorkspaceCsvPreviewAPI')
@@ -17,18 +14,17 @@ export const GET = defineInternalJsonRoute({
   auth: internalSessionOrServiceAuth,
   operation: csvPreviewWorkspaceFile.operation,
   rateLimit: internalRateLimits.none({ reason: 'Preserve existing internal CSV preview behavior' }),
-  errorPolicy: internalPlainFileErrorPolicy,
+  errorPolicy: internalFileErrorPolicies.plain,
   mapInput: ({ params, query }) => ({
     fileId: params.fileId,
     assertedWorkspaceId: params.id,
     key: query.key,
   }),
   useCase: csvPreviewWorkspaceFile,
-  present: (result) => {
+  onSuccess: ({ result }) => {
     logger.info('CSV preview served', {
       rows: result.rows.length,
       truncated: result.truncated,
     })
-    return result
   },
 })

apps/sim/app/api/workspaces/[id]/files/[fileId]/dimensions/route.ts

@@ -4,7 +4,7 @@ import {
   internalRateLimits,
   internalSessionAuth,
 } from '@/lib/api/server/routes'
-import { internalFileErrorPolicy } from '@/lib/workspace-files/api'
+import { internalFileErrorPolicies } from '@/lib/workspace-files/api'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { updateWorkspaceFileDimensionsOperation } from '@/lib/workspace-files/application/update-workspace-file-dimensions'
 
@@ -13,7 +13,7 @@ export const PATCH = defineInternalJsonRoute({
   auth: internalSessionAuth,
   operation: fileOperations.updateMetadata,
   rateLimit: internalRateLimits.none({ reason: 'Preserve existing internal dimensions behavior' }),
-  errorPolicy: internalFileErrorPolicy,
+  errorPolicy: internalFileErrorPolicies.default,
   mapInput: ({ params, body }) => ({
     fileId: params.fileId,
     assertedWorkspaceId: params.id,
@@ -22,5 +22,4 @@ export const PATCH = defineInternalJsonRoute({
     height: body.height,
   }),
   useCase: updateWorkspaceFileDimensionsOperation,
-  present: ({ success }) => ({ success }),
 })

apps/sim/app/api/workspaces/[id]/files/[fileId]/download/route.ts

@@ -1,60 +1,30 @@
-import { createLogger } from '@sim/logger'
-import { NextResponse } from 'next/server'
 import { downloadWorkspaceFileUrlContract } from '@/lib/api/contracts/workspace-files'
 import {
   defineInternalJsonRoute,
   internalRateLimits,
   internalSessionAuth,
 } from '@/lib/api/server/routes'
-import { getBaseUrl } from '@/lib/core/utils/urls'
-import { captureServerEvent } from '@/lib/posthog/server'
-import { internalFileErrorPolicy } from '@/lib/workspace-files/api'
+import {
+  internalFileAnalytics,
+  internalFileErrorPolicies,
+  internalFilePresenters,
+} from '@/lib/workspace-files/api'
 import { downloadWorkspaceFile } from '@/lib/workspace-files/application/download-workspace-file'
 
 export const dynamic = 'force-dynamic'
 
-const logger = createLogger('WorkspaceFileDownloadAPI')
-
-const downloadErrorPolicy = {
-  render(error: unknown) {
-    const typed = internalFileErrorPolicy.render(error)
-    if (typed) return typed
-    logger.error('Failed to generate workspace file download URL', { error })
-    return NextResponse.json(
-      { success: false, error: 'Failed to generate download URL' },
-      { status: 500 }
-    )
-  },
-}
-
 /** POST /api/workspaces/[id]/files/[fileId]/download — Create an authenticated serve URL. */
 export const POST = defineInternalJsonRoute({
   contract: downloadWorkspaceFileUrlContract,
   auth: internalSessionAuth,
   operation: downloadWorkspaceFile.operation,
   rateLimit: internalRateLimits.none({ reason: 'Preserve existing internal download behavior' }),
-  errorPolicy: downloadErrorPolicy,
+  errorPolicy: internalFileErrorPolicies.downloadUrl,
   mapInput: ({ params }) => ({
     fileId: params.fileId,
     assertedWorkspaceId: params.id,
   }),
   useCase: downloadWorkspaceFile,
-  onSuccess: ({ principal, result }) => {
-    captureServerEvent(
-      principal.userId,
-      'file_downloaded',
-      { workspace_id: result.file.workspaceId, is_bulk: false, file_count: 1 },
-      { groups: { workspace: result.file.workspaceId } }
-    )
-  },
-  present: ({ file }) => {
-    const baseUrl = getBaseUrl()
-    return {
-      success: true as const,
-      downloadUrl: `${baseUrl}/api/files/serve/${encodeURIComponent(file.key)}?context=workspace`,
-      viewerUrl: `${baseUrl}/workspace/${file.workspaceId}/files/${file.id}`,
-      fileName: file.name,
-      expiresIn: null,
-    }
-  },
+  onSuccess: internalFileAnalytics.downloaded,
+  present: internalFilePresenters.downloadUrl,
 })

apps/sim/app/api/workspaces/[id]/files/[fileId]/restore/route.ts

@@ -1,10 +1,11 @@
 import { restoreWorkspaceFileContract } from '@/lib/api/contracts/workspace-files'
 import {
   defineInternalJsonRoute,
+  internalJsonPresenters,
   internalRateLimits,
   internalSessionAuth,
 } from '@/lib/api/server/routes'
-import { internalFileErrorPolicy } from '@/lib/workspace-files/api'
+import { internalFileErrorPolicies } from '@/lib/workspace-files/api'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { restoreWorkspaceFileOperation } from '@/lib/workspace-files/application/restore-workspace-file'
 
@@ -13,8 +14,8 @@ export const POST = defineInternalJsonRoute({
   auth: internalSessionAuth,
   operation: fileOperations.restore,
   rateLimit: internalRateLimits.none({ reason: 'Preserve existing internal restore behavior' }),
-  errorPolicy: internalFileErrorPolicy,
+  errorPolicy: internalFileErrorPolicies.default,
   mapInput: ({ params }) => ({ fileId: params.fileId, assertedWorkspaceId: params.id }),
   useCase: restoreWorkspaceFileOperation,
-  present: ({ restored }) => ({ success: restored }),
+  present: internalJsonPresenters.successFrom('restored'),
 })

apps/sim/app/api/workspaces/[id]/files/[fileId]/route.ts

@@ -4,11 +4,15 @@ import {
 } from '@/lib/api/contracts/workspace-files'
 import {
   defineInternalJsonRoute,
+  internalJsonPresenters,
   internalRateLimits,
   internalSessionAuth,
 } from '@/lib/api/server/routes'
-import { captureServerEvent } from '@/lib/posthog/server'
-import { internalFileErrorPolicy } from '@/lib/workspace-files/api'
+import {
+  internalFileAnalytics,
+  internalFileErrorPolicies,
+  internalFilePresenters,
+} from '@/lib/workspace-files/api'
 import { deleteWorkspaceFileOperation } from '@/lib/workspace-files/application/delete-workspace-file'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { renameWorkspaceFile } from '@/lib/workspace-files/application/rename-workspace-file'
@@ -24,22 +28,15 @@ export const PATCH = defineInternalJsonRoute({
   auth: internalSessionAuth,
   operation: fileOperations.rename,
   rateLimit: internalRateLimits.none({ reason: 'Preserve existing internal rename behavior' }),
-  errorPolicy: internalFileErrorPolicy,
+  errorPolicy: internalFileErrorPolicies.default,
   mapInput: ({ params, body }) => ({
     fileId: params.fileId,
     assertedWorkspaceId: params.id,
     name: body.name,
   }),
   useCase: renameWorkspaceFile,
-  onSuccess: ({ principal, result }) => {
-    captureServerEvent(
-      principal.userId,
-      'file_renamed',
-      { workspace_id: result.file.workspaceId },
-      { groups: { workspace: result.file.workspaceId } }
-    )
-  },
-  present: ({ file }) => ({ success: true, file: { ...file, folderId: file.folderId ?? null } }),
+  onSuccess: internalFileAnalytics.renamed,
+  present: internalFilePresenters.successFile,
 })
 
 /**
@@ -51,16 +48,9 @@ export const DELETE = defineInternalJsonRoute({
   auth: internalSessionAuth,
   operation: fileOperations.delete,
   rateLimit: internalRateLimits.none({ reason: 'Preserve existing internal delete behavior' }),
-  errorPolicy: internalFileErrorPolicy,
+  errorPolicy: internalFileErrorPolicies.default,
   mapInput: ({ params }) => ({ fileId: params.fileId, assertedWorkspaceId: params.id }),
   useCase: deleteWorkspaceFileOperation,
-  onSuccess: ({ principal, result }) => {
-    captureServerEvent(
-      principal.userId,
-      'file_deleted',
-      { workspace_id: result.workspaceId },
-      { groups: { workspace: result.workspaceId } }
-    )
-  },
-  present: ({ deleted }) => ({ success: deleted }),
+  onSuccess: internalFileAnalytics.deleted,
+  present: internalJsonPresenters.successFrom('deleted'),
 })