fix(crunchbase): honor card paging limits and cursor exclusivity

- Cap a card page at the documented 100-item maximum instead of Search's
  1000, which the shared Limit field made easy to carry over
- Always request the card's identifier so a narrowed cardFieldIds cannot
  return a full page with a null cursor and stall a paging loop
- Reject the mutually-exclusive afterId/beforeId pair on the card and
  deleted-entity endpoints, not just on search
- Report an unexpected card shape as empty rather than wrapping the
  envelope as a one-row page

Author: waleedlatif1

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

@@ -293,9 +293,9 @@ Page through one related-entity card of a Crunchbase entity — an investor's in
 | `collection` | string | Yes | Collection the entity belongs to. One of: acquisitions, addresses, categories, category_groups, degrees, event_appearances, events, funding_rounds, funds, investments, ipos, jobs, market_insights, micro_categories, organizations, ownerships, people. |
 | `entityId` | string | Yes | Entity permalink or UUID |
 | `cardId` | string | Yes | Card to page through, e.g. "participated_investments" on a person, "founders" on an organization, or "investors" on a funding round. Valid ids differ per collection. |
-| `cardFieldIds` | json | No | Fields to return on each card item, e.g. \["identifier","announced_on","money_raised"\] |
+| `cardFieldIds` | json | No | Fields to return on each card item, e.g. \["identifier","announced_on","money_raised"\]. The identifier is always requested alongside these, because the next-page cursor is read from it. |
 | `cardOrder` | string | No | Sort expression for the card, e.g. "funding_round_money_raised desc" |
-| `limit` | number | No | Card items to return per page |
+| `limit` | number | No | Card items to return per page, 1-100 |
 | `afterId` | string | No | UUID of the last card item on the current page, to fetch the next page |
 | `beforeId` | string | No | UUID of the first card item on the current page, to fetch the previous page |
 

apps/sim/blocks/blocks/crunchbase.ts

@@ -303,7 +303,7 @@ export const CrunchbaseBlock: BlockConfig<CrunchbaseResponse> = {
       title: 'Limit',
       type: 'short-input',
       mode: 'advanced',
-      placeholder: 'Search: 1-1000 (default 100). Autocomplete: 1-25 (default 10)',
+      placeholder: 'Search: 1-1000 (default 100). Card: 1-100. Autocomplete: 1-25 (default 10)',
       condition: { field: 'operation', value: LIMITED_OPERATIONS },
     },
     {

apps/sim/tools/crunchbase/crunchbase.test.ts

@@ -137,6 +137,56 @@ describe('crunchbase request building', () => {
     expect(url).toContain('after_id=cursor-1')
   })
 
+  it('caps a card page at the documented 100-item maximum', () => {
+    const url = buildUrl(crunchbaseGetEntityCardTool, {
+      apiKey: 'k',
+      collection: 'organizations',
+      entityId: 'sequoia-capital',
+      cardId: 'participated_investments',
+      limit: 1000,
+    })
+    /* Substring-matching "limit=100" would also pass on "limit=1000" — the exact
+       parameter value is the only assertion that can actually fail here. */
+    expect(new URL(url).searchParams.get('limit')).toBe('100')
+  })
+
+  it('keeps the cursor field when cardFieldIds would have dropped it', () => {
+    const narrowed = buildUrl(crunchbaseGetEntityCardTool, {
+      apiKey: 'k',
+      collection: 'organizations',
+      entityId: 'sequoia-capital',
+      cardId: 'participated_investments',
+      cardFieldIds: '["announced_on"]',
+    })
+    expect(narrowed).toContain('card_field_ids=announced_on%2Cidentifier')
+
+    const alreadyPresent = buildUrl(crunchbaseGetEntityCardTool, {
+      apiKey: 'k',
+      collection: 'organizations',
+      entityId: 'sequoia-capital',
+      cardId: 'participated_investments',
+      cardFieldIds: '["uuid","announced_on"]',
+    })
+    expect(alreadyPresent).toContain('card_field_ids=uuid%2Cannounced_on')
+  })
+
+  it('rejects both cursors on every paged endpoint, not just search', () => {
+    expect(() =>
+      buildUrl(crunchbaseGetEntityCardTool, {
+        apiKey: 'k',
+        collection: 'organizations',
+        entityId: 'sequoia-capital',
+        cardId: 'founders',
+        afterId: 'a',
+        beforeId: 'b',
+      })
+    ).toThrow(/either "afterId" or "beforeId"/)
+
+    expect(() =>
+      buildUrl(crunchbaseListDeletedEntitiesTool, { apiKey: 'k', afterId: 'a', beforeId: 'b' })
+    ).toThrow(/either "afterId" or "beforeId"/)
+  })
+
   it('scopes the deleted feed by path when one collection is chosen', () => {
     expect(
       buildUrl(crunchbaseListDeletedEntitiesTool, { apiKey: 'k', collection: 'organizations' })
@@ -268,6 +318,21 @@ describe('crunchbase response mapping', () => {
     expect(result.output.nextAfterId).toBe('p1')
   })
 
+  it('reports an undocumented card shape as empty rather than inventing a row', async () => {
+    const result = await crunchbaseGetEntityCardTool.transformResponse!(
+      jsonResponse({ cards: { founders: { items: [{ uuid: 'p1' }], paging: {} } } }),
+      {
+        apiKey: 'k',
+        collection: 'organizations',
+        entityId: 'tesla-motors',
+        cardId: 'founders',
+      } as never
+    )
+
+    expect(result.output.items).toEqual([])
+    expect(result.output.nextAfterId).toBeNull()
+  })
+
   it('passes the fields-metadata CSV through verbatim', async () => {
     const csv = 'collection_id,field_id,type\norganizations,name,text\n'
     const result = await crunchbaseGetFieldsMetadataTool.transformResponse!(

apps/sim/tools/crunchbase/get_entity_card.ts

@@ -1,14 +1,15 @@
 import type { CrunchbaseProperties } from '@/tools/crunchbase/types'
 import {
   assertCollection,
+  assertSingleCursor,
+  CARD_LIMIT_MAX,
   CRUNCHBASE_API_BASE,
   CRUNCHBASE_CARD_COLLECTIONS,
   clampLimit,
   crunchbaseError,
   crunchbaseHeaders,
   parseIdListParam,
   readJson,
-  SEARCH_LIMIT_MAX,
 } from '@/tools/crunchbase/utils'
 import { ErrorExtractorId } from '@/tools/error-extractors'
 import type { ToolConfig, ToolResponse } from '@/tools/types'
@@ -33,6 +34,20 @@ interface CrunchbaseGetEntityCardResponse extends ToolResponse {
   }
 }
 
+/**
+ * Guarantees the page carries the field its cursor is read from.
+ *
+ * `nextAfterId` comes off the last item's `uuid` / `identifier.uuid`, so a caller
+ * narrowing `card_field_ids` to, say, `["announced_on"]` would get a full page
+ * and a null cursor — and a paging loop would stop after the first page with
+ * rows still unread.
+ */
+function withCursorField(cardFieldIds: string[] | undefined): string[] | undefined {
+  if (!cardFieldIds?.length) return cardFieldIds
+  if (cardFieldIds.includes('identifier') || cardFieldIds.includes('uuid')) return cardFieldIds
+  return [...cardFieldIds, 'identifier']
+}
+
 export const crunchbaseGetEntityCardTool: ToolConfig<
   CrunchbaseGetEntityCardParams,
   CrunchbaseGetEntityCardResponse
@@ -76,7 +91,7 @@ export const crunchbaseGetEntityCardTool: ToolConfig<
       required: false,
       visibility: 'user-or-llm',
       description:
-        'Fields to return on each card item, e.g. ["identifier","announced_on","money_raised"]',
+        'Fields to return on each card item, e.g. ["identifier","announced_on","money_raised"]. The identifier is always requested alongside these, because the next-page cursor is read from it.',
     },
     cardOrder: {
       type: 'string',
@@ -88,7 +103,7 @@ export const crunchbaseGetEntityCardTool: ToolConfig<
       type: 'number',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Card items to return per page',
+      description: 'Card items to return per page, 1-100',
     },
     afterId: {
       type: 'string',
@@ -116,11 +131,13 @@ export const crunchbaseGetEntityCardTool: ToolConfig<
       const cardId = params.cardId?.trim()
       if (!cardId) throw new Error('Crunchbase "cardId" is required')
 
+      assertSingleCursor(params.afterId, params.beforeId)
+
       const search = new URLSearchParams()
-      const cardFieldIds = parseIdListParam(params.cardFieldIds, 'cardFieldIds')
+      const cardFieldIds = withCursorField(parseIdListParam(params.cardFieldIds, 'cardFieldIds'))
       if (cardFieldIds?.length) search.set('card_field_ids', cardFieldIds.join(','))
       if (params.cardOrder) search.set('order', params.cardOrder)
-      const limit = clampLimit(params.limit, SEARCH_LIMIT_MAX)
+      const limit = clampLimit(params.limit, CARD_LIMIT_MAX)
       if (limit !== undefined) search.set('limit', String(limit))
       if (params.afterId) search.set('after_id', params.afterId)
       if (params.beforeId) search.set('before_id', params.beforeId)
@@ -144,11 +161,11 @@ export const crunchbaseGetEntityCardTool: ToolConfig<
        requested card id rather than at the top level — keyed by the same trimmed
        id the URL used, or a pasted " founders " would read back as empty. */
     const card = data.cards?.[params?.cardId?.trim() ?? '']
-    const items = Array.isArray(card)
-      ? (card as CrunchbaseProperties[])
-      : card && typeof card === 'object'
-        ? [card as CrunchbaseProperties]
-        : []
+
+    /* Every card this endpoint serves is typed as an array of entities. Wrapping
+       a non-array as a single item would invent a one-row page out of a shape we
+       do not understand, so an unexpected value reports as empty instead. */
+    const items = Array.isArray(card) ? (card as CrunchbaseProperties[]) : []
     /* A card item carries its uuid at the top level only when `card_field_ids`
        asked for it; otherwise the identifier object is the one place it lives. */
     const last = items[items.length - 1]

apps/sim/tools/crunchbase/list_deleted_entities.ts

@@ -3,6 +3,7 @@ import {
   appendCsvParam,
   assertCollection,
   assertCollections,
+  assertSingleCursor,
   CRUNCHBASE_API_BASE,
   CRUNCHBASE_DELETED_COLLECTIONS,
   clampLimit,
@@ -97,6 +98,8 @@ export const crunchbaseListDeletedEntitiesTool: ToolConfig<
 
   request: {
     url: (params) => {
+      assertSingleCursor(params.afterId, params.beforeId)
+
       const search = new URLSearchParams()
       const scoped = params.collection?.trim()
 

apps/sim/tools/crunchbase/utils.ts

@@ -292,6 +292,28 @@ export function parseIdListParam(value: unknown, paramName: string): string[] |
   return parsed?.map((entry) => String(entry))
 }
 
+/**
+ * `limit` bound for a single card page.
+ *
+ * A card returns at most 100 items, and the Limit subblock is shared with Search
+ * (max 1000), so a value carried over from a search would otherwise go out on
+ * the wire and be rejected.
+ */
+export const CARD_LIMIT_MAX = 100
+
+/**
+ * Rejects the cursor pair Crunchbase documents as mutually exclusive.
+ *
+ * `after_id` "may not be provided simultaneously with before_id" on every paged
+ * endpoint, and the block shares one After ID / Before ID pair across searches,
+ * card pages, and the deleted feed — so a leftover value really can arrive here.
+ */
+export function assertSingleCursor(afterId?: string, beforeId?: string): void {
+  if (afterId && beforeId) {
+    throw new Error('Crunchbase accepts either "afterId" or "beforeId", not both')
+  }
+}
+
 /** Coerces a numeric param and clamps it into the endpoint's documented range. */
 export function clampLimit(value: unknown, max: number, fallback?: number): number | undefined {
   if (value === undefined || value === null || value === '') return fallback
@@ -457,9 +479,7 @@ export function buildSearchBody(
   const order = normalizeOrder(params.order)
   const limit = clampLimit(params.limit, SEARCH_LIMIT_MAX, SEARCH_LIMIT_DEFAULT)
 
-  if (params.afterId && params.beforeId) {
-    throw new Error('Crunchbase accepts either "afterId" or "beforeId", not both')
-  }
+  assertSingleCursor(params.afterId, params.beforeId)
 
   const resolvedFieldIds = fieldIds?.length ? fieldIds : [...(defaultFieldIds ?? [])]
   if (resolvedFieldIds.length === 0) {