fix(api): make resource cleanup and metadata consistent

Author: TheodoreSpeaks

apps/docs/openapi-v2-tables.json

@@ -270,7 +270,7 @@
       "delete": {
         "operationId": "deleteTable",
         "summary": "Delete Table",
-        "description": "Delete a table. Returns the id of the deleted table.",
+        "description": "Delete a table. Returns the id and an explicit deletion confirmation.",
         "tags": ["Tables"],
         "x-codeSamples": [
           {
@@ -333,7 +333,7 @@
       "patch": {
         "operationId": "updateTable",
         "summary": "Update Table",
-        "description": "Rename a table and/or move it between folders. Provide at least one of `name` or `folderPath`. Each field is applied independently, so one request can rename and move at once, and the response reflects every applied change.\n\nBoth fields need workspace write.\n\n**Lock flags are read-only here.** A table's `locks` are returned on the table resource and enforced on every write (a locked verb returns 423), but they cannot be changed through the API — a write-level key must not be able to clear the guard placed there to stop it. Changing a lock is a first-party workspace-admin action. A request carrying `locks` is rejected with 400 rather than silently ignored.\n\n**Partial-success semantics.** The two operations commit independently, so this endpoint is not atomic. Everything that can be *rejected* — the body shape, folder existence — is validated before the first write, so a rejected request changes nothing. If a genuine fault (a lost race, the table deleted mid-request, a database error) fails the later operation after the earlier one has committed, the response is an error whose `error.details.applied` lists the operations that are nevertheless live (`\"name\"`, `\"folderPath\"`). The field is absent when nothing was applied, so its presence always means \"these changes took effect despite the error\" — re-read the table to confirm before retrying.",
+        "description": "Rename a table, edit its description, and/or move it between folders. Provide at least one of `name`, `description`, or `folderPath`. Each field is applied independently, so one request can combine changes and the response reflects every applied change.\n\nAll three fields need workspace write.\n\n**Lock flags are read-only here.** A table's `locks` are returned on the table resource and enforced on every write (a locked verb returns 423), but they cannot be changed through the API — a write-level key must not be able to clear the guard placed there to stop it. Changing a lock is a first-party workspace-admin action. A request carrying `locks` is rejected with 400 rather than silently ignored.\n\n**Partial-success semantics.** The operations commit independently, so this endpoint is not atomic. Everything that can be *rejected* — the body shape, folder existence — is validated before the first write, so a rejected request changes nothing. If a genuine fault (a lost race, the table deleted mid-request, a database error) fails a later operation after an earlier one has committed, the response is an error whose `error.details.applied` lists the operations that are nevertheless live (`\"name\"`, `\"description\"`, `\"folderPath\"`). The field is absent when nothing was applied, so its presence always means \"these changes took effect despite the error\" — re-read the table to confirm before retrying.",
         "tags": ["Tables"],
         "x-codeSamples": [
           {
@@ -4976,11 +4976,16 @@
         "properties": {
           "data": {
             "type": "object",
-            "required": ["id"],
+            "required": ["id", "deleted"],
             "properties": {
               "id": {
                 "type": "string",
                 "description": "The id of the deleted table."
+              },
+              "deleted": {
+                "type": "boolean",
+                "const": true,
+                "description": "Confirms the table was deleted."
               }
             }
           }
@@ -5301,7 +5306,7 @@
       },
       "UpdateTableBody": {
         "type": "object",
-        "description": "Rename and/or move a table. Every field beyond `workspaceId` is optional, but at least one must be present. Lock flags are read-only on this API and are not accepted here.",
+        "description": "Rename, edit the description, and/or move a table. Every field beyond `workspaceId` is optional, but at least one must be present. Lock flags are read-only on this API and are not accepted here.",
         "required": ["workspaceId"],
         "properties": {
           "workspaceId": {
@@ -5314,6 +5319,11 @@
             "minLength": 1,
             "description": "New table name."
           },
+          "description": {
+            "type": ["string", "null"],
+            "maxLength": 500,
+            "description": "New table description, or null to clear it."
+          },
           "folderPath": {
             "type": "string",
             "description": "Canonical containing-folder path. `/` is the workspace root."

apps/sim/app/api/v2/tables/[tableId]/route.test.ts

@@ -15,6 +15,7 @@ const {
   mockCheckAccess,
   mockPerformDeleteTable,
   mockPerformRenameTable,
+  mockPerformUpdateTableDescription,
   mockPerformMoveTableToFolder,
   mockPerformUpdateTableLocks,
   mockRecordAudit,
@@ -28,6 +29,7 @@ const {
   mockCheckAccess: vi.fn(),
   mockPerformDeleteTable: vi.fn(),
   mockPerformRenameTable: vi.fn(),
+  mockPerformUpdateTableDescription: vi.fn(),
   mockPerformMoveTableToFolder: vi.fn(),
   mockPerformUpdateTableLocks: vi.fn(),
   mockRecordAudit: vi.fn(),
@@ -76,6 +78,7 @@ vi.mock('@/lib/workspaces/permissions/utils', () => ({
 vi.mock('@/lib/table/orchestration', () => ({
   performDeleteTable: mockPerformDeleteTable,
   performRenameTable: mockPerformRenameTable,
+  performUpdateTableDescription: mockPerformUpdateTableDescription,
   performMoveTableToFolder: mockPerformMoveTableToFolder,
   performUpdateTableLocks: mockPerformUpdateTableLocks,
 }))
@@ -158,6 +161,7 @@ describe('DELETE /api/v2/tables/[tableId]', () => {
     expect(mockPerformDeleteTable).toHaveBeenCalledWith(
       expect.objectContaining({ table: TABLE, userId: 'user-1' })
     )
+    expect((await res.json()).data).toEqual({ id: 'table-1', deleted: true })
     // The route no longer audits: doing so out here fired TABLE_DELETED even
     // when the delete was a no-op on an already-archived table.
     expect(mockRecordAudit).not.toHaveBeenCalled()
@@ -206,6 +210,27 @@ describe('PATCH /api/v2/tables/[tableId]', () => {
     expect(mockPerformUpdateTableLocks).not.toHaveBeenCalled()
   })
 
+  it('updates and clears the table description through orchestration', async () => {
+    mockPerformUpdateTableDescription.mockResolvedValue({ success: true })
+
+    const updateResponse = await callPatch({ workspaceId: 'ws-1', description: 'Finance data' })
+
+    expect(updateResponse.status).toBe(200)
+    expect(mockPerformUpdateTableDescription).toHaveBeenCalledWith(
+      expect.objectContaining({
+        table: TABLE,
+        description: 'Finance data',
+        userId: 'user-1',
+      })
+    )
+
+    const clearResponse = await callPatch({ workspaceId: 'ws-1', description: null })
+    expect(clearResponse.status).toBe(200)
+    expect(mockPerformUpdateTableDescription).toHaveBeenLastCalledWith(
+      expect.objectContaining({ description: null })
+    )
+  })
+
   it('surfaces a running import so an async job is observable, not just startable', async () => {
     // `POST /import-async` and `POST /job/cancel` let a caller start and stop an
     // import; without this the table never reports that it is running, so there

apps/sim/app/api/v2/tables/[tableId]/route.ts

@@ -17,6 +17,7 @@ import {
   performDeleteTable,
   performMoveTableToFolder,
   performRenameTable,
+  performUpdateTableDescription,
 } from '@/lib/table/orchestration'
 import { checkAccess } from '@/app/api/table/utils'
 import { checkRateLimit, resolveWorkspaceScope } from '@/app/api/v1/middleware'
@@ -45,7 +46,7 @@ const logger = createLogger('V2TableDetailAPI')
  * means "these changes are live despite the error".
  */
 function appliedDetails(
-  applied: readonly ('name' | 'folderPath')[]
+  applied: readonly ('name' | 'description' | 'folderPath')[]
 ): { applied: readonly string[] } | undefined {
   return applied.length > 0 ? { applied } : undefined
 }
@@ -124,7 +125,7 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: Tabl
    * archived. Reporting a bare 500 there tells the caller nothing landed, and
    * it retries into a duplicate-name conflict or a repeated move.
    */
-  const applied: ('name' | 'folderPath')[] = []
+  const applied: ('name' | 'description' | 'folderPath')[] = []
 
   try {
     const rateLimit = await checkRateLimit(request, 'table-detail')
@@ -180,6 +181,18 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: Tabl
       else failure = { outcome, fallback: 'Failed to rename table' }
     }
 
+    if (!failure && validated.description !== undefined) {
+      const outcome = await performUpdateTableDescription({
+        table,
+        description: validated.description,
+        userId,
+        requestId,
+        request,
+      })
+      if (outcome.success) applied.push('description')
+      else failure = { outcome, fallback: 'Failed to update table description' }
+    }
+
     if (!failure && validated.folderPath !== undefined) {
       const outcome = await performMoveTableToFolder({
         table,
@@ -272,7 +285,7 @@ export const DELETE = withRouteHandler(async (request: NextRequest, context: Tab
       return v2TableOrchestrationError(outcome, 'Failed to delete table')
     }
 
-    return v2Data({ id: tableId }, { rateLimit })
+    return v2Data({ id: tableId, deleted: true }, { rateLimit })
   } catch (error) {
     const lockError = v2TableLockError(error)
     if (lockError) return lockError

apps/sim/lib/api/contracts/v2/tables.ts

@@ -150,7 +150,7 @@ export type V2ApiRow = z.output<typeof v2ApiRowSchema>
 export const v2TableDataSchema = z.object({ table: v2ApiTableSchema })
 export type V2TableData = z.output<typeof v2TableDataSchema>
 
-export const v2DeleteTableDataSchema = z.object({ id: z.string() })
+export const v2DeleteTableDataSchema = z.object({ id: z.string(), deleted: z.literal(true) })
 export type V2DeleteTableData = z.output<typeof v2DeleteTableDataSchema>
 
 /** The table's full column list after a column mutation. */
@@ -279,8 +279,9 @@ export const v2GetTableContract = defineRouteContract({
 
 /**
  * Table update. Every field is optional but at least one must be present:
- * `name` renames and `folderPath` moves the table. Omission leaves placement
- * untouched; `/` moves it to the workspace root.
+ * `name` renames, `description` edits metadata, and `folderPath` moves the
+ * table. Omission leaves placement untouched; `/` moves it to the workspace
+ * root.
  *
  * `locks` is deliberately **not** accepted here, which is why this body is
  * declared rather than reusing the first-party `updateTableBodySchema`. The
@@ -294,14 +295,19 @@ export const v2UpdateTableBodySchema = z
   .object({
     workspaceId: workspaceIdSchema,
     name: tableNameSchema.optional(),
+    description: v1CreateTableBodySchema.shape.description.nullable(),
     folderPath: v2FolderPathInputSchema.optional(),
   })
   .strict()
   .superRefine((body, ctx) => {
-    if (body.name === undefined && body.folderPath === undefined) {
+    if (
+      body.name === undefined &&
+      body.description === undefined &&
+      body.folderPath === undefined
+    ) {
       ctx.addIssue({
         code: 'custom',
-        message: 'Provide a new name or folder',
+        message: 'Provide a new name, description, or folder',
         path: ['name'],
       })
     }

apps/sim/lib/folders/orchestration.test.ts

@@ -172,6 +172,8 @@ describe('createFolder', () => {
         name: 'Reports',
         workspaceId: 'ws-1',
         parentId: null,
+        createdAt: expect.any(Date),
+        updatedAt: expect.any(Date),
       })
     )
   })
@@ -352,8 +354,49 @@ describe('path-owned folder mutations', () => {
 
     expect(result).toMatchObject({ success: true, path: '/Reports/Q1' })
     expect(dbChainMockFns.values).toHaveBeenCalledWith(
-      expect.objectContaining({ name: 'Q1', parentId: 'parent-1' })
+      expect.objectContaining({
+        name: 'Q1',
+        parentId: 'parent-1',
+        createdAt: expect.any(Date),
+        updatedAt: expect.any(Date),
+      })
+    )
+  })
+
+  it('releases the folder transaction before running the domain delete cascade', async () => {
+    const source = folderRow({ id: 'folder-1', name: 'Reports' })
+    mockLoadActiveFolderPathIndex.mockResolvedValue({
+      rowById: new Map([['folder-1', source]]),
+      pathById: new Map([['folder-1', '/Reports']]),
+      idByPath: new Map([['/Reports', 'folder-1']]),
+    })
+    queueTableRows(schemaMock.folder, [{ deletedAt: null }])
+
+    let inFolderTransaction = false
+    dbChainMockFns.transaction.mockImplementationOnce(
+      async (operation: (tx: unknown) => Promise<unknown>) => {
+        inFolderTransaction = true
+        try {
+          return await operation(dbChainMock.db)
+        } finally {
+          inFolderTransaction = false
+        }
+      }
     )
+    mockArchiveFolderCascade.mockImplementationOnce(async () => {
+      expect(inFolderTransaction).toBe(false)
+      return { folders: 1, children: 0 }
+    })
+
+    const result = await deleteFolderByPath({
+      resourceType: 'table',
+      workspaceId: 'ws-1',
+      userId: 'user-1',
+      path: '/Reports',
+      recursive: true,
+    })
+
+    expect(result).toMatchObject({ success: true, path: '/Reports' })
   })
 
   it('rejects relocating a folder beneath its own descendant before writing', async () => {