fix(cbinsights): reject malformed input instead of silently rescoping a billed query

CB Insights is metered, so a filter that fails to parse must fail the request —
dropping it does not narrow the result, it charges for a query the caller never
asked for.

- reject an unrecognized boolean rather than dropping it, which had been
  widening a VC-backed firmographics search
- reject a non-numeric limit instead of falling back to the endpoint default
- reject non-text filter entries instead of stringifying them to "[object Object]"
- accept only asc/desc for sort direction; a typo had returned the bottom of a
  metered result set as though it were the top
- treat a whitespace-only numeric bound as unset, not as zero
- drop `totalHits`/`totalHitsRelation` from list business relationships; that
  endpoint reports no total, so both were permanently null
- trim `nextPageToken`, matching the id fields

Also moves the token cache onto `lru-cache` per the in-process caching rule,
replacing hand-rolled TTL arithmetic and a manual prune.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/cbinsights.mdx

@@ -489,8 +489,6 @@ Retrieve partnerships, client/vendor relationships, and licensing activity for u
 | --------- | ---- | ----------- |
 | `orgs` | json | Organizations as \[\{orgId, businessRelationships\}\] |
 | `nextPageToken` | string | Token for the next page, or null when there are no more results |
-| `totalHits` | number | Total number of matching records |
-| `totalHitsRelation` | string | Whether totalHits is exact \('eq'\) or a floor \('gte', used above 10,000\) |
 
 ### CB Insights List Management and Board
 

apps/sim/tools/cbinsights/cbinsights.test.ts

@@ -6,6 +6,7 @@ import { cbinsightsChatTool } from '@/tools/cbinsights/chat'
 import { cbinsightsGetOrgFundingsTool } from '@/tools/cbinsights/get_org_fundings'
 import { cbinsightsGetOrgOutlookTool } from '@/tools/cbinsights/get_org_outlook'
 import { cbinsightsGetScoutingReportTool } from '@/tools/cbinsights/get_scouting_report'
+import { cbinsightsListBusinessRelationshipsTool } from '@/tools/cbinsights/list_business_relationships'
 import { cbinsightsListFundingsTool } from '@/tools/cbinsights/list_fundings'
 import { cbinsightsLookupOrganizationsTool } from '@/tools/cbinsights/lookup_organizations'
 import { cbinsightsRagTool } from '@/tools/cbinsights/rag'
@@ -268,6 +269,110 @@ describe('cbinsights request building', () => {
     expect(JSON.parse(String(calls[2].init.body)).sectorIds).toEqual([1, 2])
   })
 
+  /*
+   * The sibling of the numeric bound. `parseBooleanParam` used to return
+   * undefined for anything it did not recognize, so a model answering "yes"
+   * dropped the restriction entirely and widened the search — the same failure,
+   * on a filter the caller explicitly set.
+   */
+  it.each(['yes', '1', 'TRUE ish', 0])(
+    'rejects the unrecognized boolean %j rather than dropping the filter',
+    async (entry) => {
+      mockFetch([AUTH_OK])
+      await expect(
+        cbinsightsSearchFirmographicsTool.directExecution!({
+          ...CREDS,
+          keyword: 'fintech',
+          vcBacked: entry,
+        } as never)
+      ).rejects.toThrow(/"vcBacked" must be true or false/)
+      expect(calls).toHaveLength(0)
+    }
+  )
+
+  it.each([
+    ['true', true],
+    ['FALSE', false],
+    [true, true],
+    [false, false],
+  ])('still accepts the boolean form %j a dropdown emits', async (entry, expected) => {
+    mockFetch([AUTH_OK, { body: { orgs: [] } }])
+    await cbinsightsSearchFirmographicsTool.directExecution!({
+      ...CREDS,
+      keyword: 'fintech',
+      vcBacked: entry,
+    } as never)
+    expect(JSON.parse(String(calls[1].init.body)).vcBacked).toBe(expected)
+  })
+
+  it('treats the dropdown\'s "Any" option as no filter at all', async () => {
+    mockFetch([AUTH_OK, { body: { orgs: [] } }])
+    await cbinsightsSearchFirmographicsTool.directExecution!({
+      ...CREDS,
+      keyword: 'fintech',
+      vcBacked: '',
+    } as never)
+    expect(JSON.parse(String(calls[1].init.body))).toEqual({ keyword: 'fintech' })
+  })
+
+  /*
+   * A mistyped direction used to fold into `desc`, handing back the bottom of a
+   * metered result set as though it were the top.
+   */
+  it('rejects a sort direction that is neither asc nor desc', async () => {
+    mockFetch([AUTH_OK])
+    await expect(
+      cbinsightsSearchFirmographicsTool.directExecution!({
+        ...CREDS,
+        keyword: 'fintech',
+        sortField: 'mosaicOverall',
+        sortDirection: 'ascending',
+      } as never)
+    ).rejects.toThrow(/"sortDirection" must be "asc" or "desc"/)
+    expect(calls).toHaveLength(0)
+  })
+
+  /*
+   * `limit` is the last silent-drop path: falling back to the endpoint default
+   * returns a different page than the caller asked for, and still bills for it.
+   */
+  it('rejects a mistyped limit rather than falling back to the endpoint default', async () => {
+    mockFetch([AUTH_OK])
+    await expect(
+      cbinsightsLookupOrganizationsTool.directExecution!({
+        ...CREDS,
+        names: 'a',
+        limit: 'twenty',
+      } as never)
+    ).rejects.toThrow(/"limit" must be a number/)
+    expect(calls).toHaveLength(0)
+  })
+
+  /*
+   * A block-to-block reference can hand over an object. Stringifying it searched
+   * for the literal "[object Object]" and reported success on zero matches.
+   */
+  it('rejects a non-text entry in a free-text filter rather than stringifying it', async () => {
+    mockFetch([AUTH_OK])
+    await expect(
+      cbinsightsLookupOrganizationsTool.directExecution!({
+        ...CREDS,
+        names: [{ name: 'CB Insights' }],
+      } as never)
+    ).rejects.toThrow(/"names" must contain only text values/)
+    expect(calls).toHaveLength(0)
+  })
+
+  it('treats a whitespace-only numeric bound as unset, not as zero', async () => {
+    mockFetch([AUTH_OK, { body: { orgs: [] } }])
+    await cbinsightsSearchFirmographicsTool.directExecution!({
+      ...CREDS,
+      keyword: 'fintech',
+      minCurrentHeadcount: '   ',
+    } as never)
+    expect(JSON.parse(String(calls[1].init.body))).toEqual({ keyword: 'fintech' })
+  })
+
   it('rejects a mistyped numeric bound rather than dropping it', async () => {
     mockFetch([AUTH_OK])
     await expect(
@@ -469,6 +574,24 @@ describe('cbinsights response mapping', () => {
     })
   })
 
+  /*
+   * Business relationships is the one paged endpoint whose documented response
+   * carries no total, so the tool must not manufacture a permanently-null
+   * `totalHits` alongside the real token.
+   */
+  it('reports only the fields the business-relationships endpoint documents', async () => {
+    mockFetch([AUTH_OK, { body: { orgs: [{ orgId: 1 }], nextPageToken: 'tok' } }])
+
+    const result = await cbinsightsListBusinessRelationshipsTool.directExecution!({
+      ...CREDS,
+      orgIds: '1',
+    } as never)
+
+    expect(result.output).toEqual({ orgs: [{ orgId: 1 }], nextPageToken: 'tok' })
+    expect(cbinsightsListBusinessRelationshipsTool.outputs).not.toHaveProperty('totalHits')
+    expect(cbinsightsListBusinessRelationshipsTool.outputs).not.toHaveProperty('totalHitsRelation')
+  })
+
   it('renames the API chatID to the block-facing chatId', async () => {
     mockFetch([
       AUTH_OK,

apps/sim/tools/cbinsights/get_org_fundings.ts

@@ -71,7 +71,7 @@ export const cbinsightsGetOrgFundingsTool: ToolConfig<CbInsightsOrgFundingsParam
         path: `/v2/organizations/${orgId}/financialtransactions/fundings`,
         body: compactBody({
           limit: clampLimit(params.limit),
-          nextPageToken: params.nextPageToken,
+          nextPageToken: params.nextPageToken?.trim(),
         }),
       },
       (data) => ({

apps/sim/tools/cbinsights/get_org_investments.ts

@@ -73,7 +73,7 @@ export const cbinsightsGetOrgInvestmentsTool: ToolConfig<
         path: `/v2/organizations/${orgId}/financialtransactions/investments`,
         body: compactBody({
           limit: clampLimit(params.limit),
-          nextPageToken: params.nextPageToken,
+          nextPageToken: params.nextPageToken?.trim(),
         }),
       },
       (data) => ({ investments: asArray(data.investments), ...pageInfo(data) }),

apps/sim/tools/cbinsights/list_business_relationships.ts

@@ -1,9 +1,12 @@
-import type { CbInsightsListResponse, CbInsightsOrgListParams } from '@/tools/cbinsights/types'
+import type {
+  CbInsightsOrgListParams,
+  CbInsightsPagedOrgListResponse,
+} from '@/tools/cbinsights/types'
 import {
   asArray,
+  asString,
   cbInsightsRequest,
   compactBody,
-  pageInfo,
   requireOrgIds,
 } from '@/tools/cbinsights/utils'
 import type { ToolConfig } from '@/tools/types'
@@ -14,7 +17,7 @@ interface CbInsightsListBusinessRelationshipsParams extends CbInsightsOrgListPar
 
 export const cbinsightsListBusinessRelationshipsTool: ToolConfig<
   CbInsightsListBusinessRelationshipsParams,
-  CbInsightsListResponse
+  CbInsightsPagedOrgListResponse
 > = {
   id: 'cbinsights_list_business_relationships',
   name: 'CB Insights List Business Relationships',
@@ -58,10 +61,10 @@ export const cbinsightsListBusinessRelationshipsTool: ToolConfig<
         path: '/v2/businessrelationships',
         body: compactBody({
           orgIds: requireOrgIds(params.orgIds),
-          nextPageToken: params.nextPageToken,
+          nextPageToken: params.nextPageToken?.trim(),
         }),
       },
-      (data) => ({ orgs: asArray(data.orgs), ...pageInfo(data) }),
+      (data) => ({ orgs: asArray(data.orgs), nextPageToken: asString(data.nextPageToken) }),
       signal
     ),
 
@@ -70,20 +73,15 @@ export const cbinsightsListBusinessRelationshipsTool: ToolConfig<
       type: 'json',
       description: 'Organizations as [{orgId, businessRelationships}]',
     },
+    /*
+     * This is the one paged endpoint that reports no total: the documented
+     * response carries `orgs` and `nextPageToken` only, so declaring `totalHits`
+     * here would promise a field that is always null.
+     */
     nextPageToken: {
       type: 'string',
       nullable: true,
       description: 'Token for the next page, or null when there are no more results',
     },
-    totalHits: {
-      type: 'number',
-      nullable: true,
-      description: 'Total number of matching records',
-    },
-    totalHitsRelation: {
-      type: 'string',
-      nullable: true,
-      description: "Whether totalHits is exact ('eq') or a floor ('gte', used above 10,000)",
-    },
   },
 }

apps/sim/tools/cbinsights/list_fundings.ts

@@ -72,7 +72,7 @@ export const cbinsightsListFundingsTool: ToolConfig<
         body: compactBody({
           orgIds: requireOrgIds(params.orgIds),
           limit: clampLimit(params.limit),
-          nextPageToken: params.nextPageToken,
+          nextPageToken: params.nextPageToken?.trim(),
         }),
       },
       (data) => ({ orgs: asArray(data.orgs), ...pageInfo(data) }),

apps/sim/tools/cbinsights/list_investments.ts

@@ -72,7 +72,7 @@ export const cbinsightsListInvestmentsTool: ToolConfig<
         body: compactBody({
           orgIds: requireOrgIds(params.orgIds),
           limit: clampLimit(params.limit),
-          nextPageToken: params.nextPageToken,
+          nextPageToken: params.nextPageToken?.trim(),
         }),
       },
       (data) => ({ orgs: asArray(data.orgs), ...pageInfo(data) }),

apps/sim/tools/cbinsights/list_portfolio_exits.ts

@@ -72,7 +72,7 @@ export const cbinsightsListPortfolioExitsTool: ToolConfig<
         body: compactBody({
           orgIds: requireOrgIds(params.orgIds),
           limit: clampLimit(params.limit),
-          nextPageToken: params.nextPageToken,
+          nextPageToken: params.nextPageToken?.trim(),
         }),
       },
       (data) => ({ orgs: asArray(data.orgs), ...pageInfo(data) }),

apps/sim/tools/cbinsights/lookup_organizations.ts

@@ -105,7 +105,7 @@ export const cbinsightsLookupOrganizationsTool: ToolConfig<
           urls,
           profileUrl,
           limit: clampLimit(params.limit),
-          nextPageToken: params.nextPageToken,
+          nextPageToken: params.nextPageToken?.trim(),
         }),
       },
       (data) => ({ orgs: asArray(data.orgs), ...pageInfo(data) }),

apps/sim/tools/cbinsights/search_firmographics.ts

@@ -53,6 +53,23 @@ interface CbInsightsFirmographicsParams extends CbInsightsAuthParams {
   nextPageToken?: string
 }
 
+/**
+ * Reads the sort direction, defaulting to the API's own `desc` when unset.
+ *
+ * A value that is neither is rejected rather than folded into the default: a
+ * mistyped `"ascending"` would silently reverse the page and hand back the
+ * bottom of the result set as though it were the top, on a metered search.
+ */
+function sortDirection(value: unknown): 'asc' | 'desc' {
+  if (value === undefined || value === null) return 'desc'
+  const normalized = String(value).trim().toLowerCase()
+  if (normalized === '') return 'desc'
+  if (normalized === 'asc' || normalized === 'desc') return normalized
+  throw new Error(
+    `CB Insights "sortDirection" must be "asc" or "desc" (received "${String(value)}")`
+  )
+}
+
 export const cbinsightsSearchFirmographicsTool: ToolConfig<
   CbInsightsFirmographicsParams,
   CbInsightsListResponse
@@ -358,7 +375,7 @@ export const cbinsightsSearchFirmographicsTool: ToolConfig<
       ),
       minLastFundingDate: params.minLastFundingDate?.trim(),
       maxLastFundingDate: params.maxLastFundingDate?.trim(),
-      vcBacked: parseBooleanParam(params.vcBacked),
+      vcBacked: parseBooleanParam(params.vcBacked, 'vcBacked'),
     })
 
     /*
@@ -375,18 +392,15 @@ export const cbinsightsSearchFirmographicsTool: ToolConfig<
       ...filters,
       ...compactBody({
         limit: clampLimit(params.limit),
-        nextPageToken: params.nextPageToken,
+        nextPageToken: params.nextPageToken?.trim(),
       }),
     }
 
     /* The API takes one sort object; the block exposes it as two plain fields
        so neither has to be typed as JSON. */
     const sortField = params.sortField?.trim()
     if (sortField) {
-      body.sort = {
-        field: sortField,
-        direction: params.sortDirection === 'asc' ? 'asc' : 'desc',
-      }
+      body.sort = { field: sortField, direction: sortDirection(params.sortDirection) }
     }
 
     return cbInsightsRequest<{