fix(tools): render Ashby object-shaped API errors readably

Ashby documents two error shapes and uses both. The `errors` array form
carries `{ message, parameter }` objects, which stringified to
'[object Object]' and hid the real cause - including the 403 a key gets
when it lacks a module permission.

Also extracts the custom field value shape into a shared constant and
mapper so the read and write paths agree on one definition.

Author: mzxchandra

apps/sim/tools/ashby/types.ts

@@ -31,7 +31,7 @@ export interface AshbyCustomField {
   id: string | null
   title: string
   isPrivate: boolean
-  valueLabel: string | null
+  valueLabel: string | string[] | null
   value: unknown
 }
 
@@ -122,6 +122,7 @@ export interface AshbySearchCandidatesParams extends AshbyBaseParams {
 export interface AshbyListJobsParams extends AshbyBaseParams {
   cursor?: string
   perPage?: number
+  syncToken?: string
   status?: string
   createdAfter?: string
   openedAfter?: string
@@ -266,6 +267,7 @@ export interface AshbyListJobsResponse extends ToolResponse {
     jobs: AshbyJob[]
     moreDataAvailable: boolean
     nextCursor: string | null
+    syncToken: string | null
   }
 }
 

apps/sim/tools/ashby/utils.test.ts

@@ -0,0 +1,55 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { ashbyErrorMessage } from '@/tools/ashby/utils'
+
+describe('ashbyErrorMessage', () => {
+  it('reads the message out of the documented { message, parameter } entries', () => {
+    // This is the shape Ashby's OpenAPI definition declares, and the one a 403
+    // for a missing module permission arrives in. Stringifying the entry
+    // directly yields '[object Object]' and hides the real cause.
+    expect(
+      ashbyErrorMessage(
+        { success: false, errors: [{ message: 'missing_endpoint_permission' }] },
+        'fallback'
+      )
+    ).toBe('missing_endpoint_permission')
+  })
+
+  it('names the offending parameter when Ashby supplies one', () => {
+    expect(
+      ashbyErrorMessage(
+        { success: false, errors: [{ message: 'Invalid value', parameter: 'fieldValue' }] },
+        'fallback'
+      )
+    ).toBe('Invalid value (fieldValue)')
+  })
+
+  it('joins multiple errors', () => {
+    expect(
+      ashbyErrorMessage(
+        { success: false, errors: [{ message: 'a' }, { message: 'b' }] },
+        'fallback'
+      )
+    ).toBe('a; b')
+  })
+
+  it('still handles the plain string array form', () => {
+    expect(ashbyErrorMessage({ success: false, errors: ['boom'] }, 'fallback')).toBe('boom')
+  })
+
+  it('prefers errorInfo.message, the other documented shape', () => {
+    expect(
+      ashbyErrorMessage({ success: false, errorInfo: { message: 'rate limited' } }, 'fallback')
+    ).toBe('rate limited')
+  })
+
+  it('falls back when the entries carry no usable message', () => {
+    expect(ashbyErrorMessage({ success: false, errors: [{ parameter: 'x' }] }, 'fallback')).toBe(
+      'fallback'
+    )
+    expect(ashbyErrorMessage({ success: false, errors: [] }, 'fallback')).toBe('fallback')
+    expect(ashbyErrorMessage(null, 'fallback')).toBe('fallback')
+  })
+})

apps/sim/tools/ashby/utils.ts

@@ -31,15 +31,32 @@ export function ashbyAuthHeaders(apiKey: string): Record<string, string> {
 
 /**
  * Extract a human-readable error message from an Ashby error response. Ashby
- * returns errors as either `errorInfo.message` or an `errors` string array.
+ * documents two shapes and uses both: `errorInfo.message`, and an `errors`
+ * array whose entries are either plain strings or `{ message, parameter }`
+ * objects. An object entry stringifies to `[object Object]` unless its message
+ * is read explicitly, which is the form a 403 for a missing module permission
+ * arrives in.
  */
 export function ashbyErrorMessage(data: unknown, fallback: string): string {
   if (!data || typeof data !== 'object') return fallback
   const d = data as Unknown
   const info = d.errorInfo as Unknown | undefined
   if (info && typeof info.message === 'string' && info.message) return info.message
   if (Array.isArray(d.errors) && d.errors.length > 0) {
-    return d.errors.map((e) => String(e)).join('; ')
+    const messages = d.errors
+      .map((e) => {
+        if (typeof e === 'string') return e
+        if (e && typeof e === 'object') {
+          const entry = e as Unknown
+          const message = typeof entry.message === 'string' ? entry.message : ''
+          const parameter = typeof entry.parameter === 'string' ? entry.parameter : ''
+          if (message && parameter) return `${message} (${parameter})`
+          if (message) return message
+        }
+        return ''
+      })
+      .filter(Boolean)
+    if (messages.length > 0) return messages.join('; ')
   }
   return fallback
 }
@@ -59,18 +76,25 @@ function mapContactArray(raw: unknown): AshbyContactInfo[] {
   return raw.map((c) => mapContact(c)).filter((c): c is AshbyContactInfo => c !== null)
 }
 
+/**
+ * Map a single custom field value as returned on an object. Ashby returns
+ * `valueLabel` as a string for ValueSelect fields and an array of strings for
+ * MultiValueSelect, and omits it entirely for every other field type.
+ */
+export function mapCustomFieldOnObject(raw: unknown): AshbyCustomField {
+  const cf = (raw ?? {}) as Unknown
+  return {
+    id: (cf.id as string) ?? null,
+    title: (cf.title as string) ?? '',
+    isPrivate: (cf.isPrivate as boolean) ?? false,
+    valueLabel: (cf.valueLabel as string | string[]) ?? null,
+    value: cf.value ?? null,
+  }
+}
+
 function mapCustomFields(raw: unknown): AshbyCustomField[] {
   if (!Array.isArray(raw)) return []
-  return raw.map((f) => {
-    const cf = f as Unknown
-    return {
-      id: (cf.id as string) ?? null,
-      title: (cf.title as string) ?? '',
-      isPrivate: (cf.isPrivate as boolean) ?? false,
-      valueLabel: (cf.valueLabel as string) ?? null,
-      value: cf.value ?? null,
-    }
-  })
+  return raw.map(mapCustomFieldOnObject)
 }
 
 function mapFileHandle(raw: unknown): AshbyFileHandle | null {
@@ -373,18 +397,30 @@ export const CONTACT_INFO_OUTPUT = {
   },
 } as const satisfies OutputProperty
 
+/**
+ * Shape of a custom field as it exists on an Application, Candidate, Job, or
+ * Opening - the value, not the field definition. Shared by every tool that
+ * reads or writes custom field values.
+ */
+export const CUSTOM_FIELD_ON_OBJECT_OUTPUT = {
+  id: { type: 'string', description: 'Custom field UUID' },
+  title: { type: 'string', description: 'Field title' },
+  isPrivate: { type: 'boolean', description: 'Whether the field is private' },
+  valueLabel: {
+    type: 'string',
+    description:
+      'Human-readable value label, present only for ValueSelect and MultiValueSelect fields. MultiValueSelect returns an array of labels.',
+    optional: true,
+  },
+  value: { type: 'string', description: 'Raw field value (type depends on fieldType)' },
+} as const satisfies Record<string, OutputProperty>
+
 export const CUSTOM_FIELDS_OUTPUT = {
   type: 'array',
   description: 'Custom field values',
   items: {
     type: 'object',
-    properties: {
-      id: { type: 'string', description: 'Custom field UUID' },
-      title: { type: 'string', description: 'Field title' },
-      isPrivate: { type: 'boolean', description: 'Whether the field is private' },
-      valueLabel: { type: 'string', description: 'Human-readable value label', optional: true },
-      value: { type: 'string', description: 'Raw field value (type depends on fieldType)' },
-    },
+    properties: CUSTOM_FIELD_ON_OBJECT_OUTPUT,
   },
 } as const satisfies OutputProperty