fix(plaid): align integration with staging patterns

Author: Bill Leoutsakos

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

@@ -4,7 +4,22 @@ import { AuthMode, IntegrationType } from '@/blocks/types'
 import type { PlaidResponse } from '@/tools/plaid/types'
 import { toPlaidOptionalBoolean, toPlaidOptionalNumber } from '@/tools/plaid/utils'
 
-const ACCOUNT_FILTER_OPERATIONS = ['get_accounts', 'get_balances', 'get_identity', 'get_auth']
+type PlaidOperation =
+  | 'sync_transactions'
+  | 'get_accounts'
+  | 'get_balances'
+  | 'get_identity'
+  | 'get_auth'
+  | 'get_item'
+  | 'search_institutions'
+  | 'get_institution'
+
+const ACCOUNT_FILTER_OPERATIONS = [
+  'get_accounts',
+  'get_balances',
+  'get_identity',
+  'get_auth',
+] satisfies PlaidOperation[]
 
 export const PlaidBlock: BlockConfig<PlaidResponse> = {
   type: 'plaid',
@@ -107,7 +122,7 @@ export const PlaidBlock: BlockConfig<PlaidResponse> = {
       serviceId: 'plaid',
       canonicalParamId: 'institutionId',
       placeholder: 'Search Plaid institutions',
-      dependsOn: ['credential'],
+      dependsOn: ['credential', 'countryCodes'],
       mode: 'basic',
       condition: {
         field: 'operation',
@@ -142,7 +157,10 @@ export const PlaidBlock: BlockConfig<PlaidResponse> = {
       type: 'short-input',
       placeholder: 'Comma-separated, defaults to US',
       mode: 'advanced',
-      condition: { field: 'operation', value: ['search_institutions', 'get_institution'] },
+      condition: {
+        field: 'operation',
+        value: ['search_institutions', 'get_institution'] satisfies PlaidOperation[],
+      },
     },
     {
       id: 'products',
@@ -399,7 +417,7 @@ export const PlaidBlockMeta = {
       icon: PlaidIcon,
       title: 'Plaid ACH payment setup',
       prompt:
-        'Build a workflow that checks account verification status, fetches account and routing numbers for an eligible linked Plaid Item, and passes them directly to the payment step without storing the numbers.',
+        'Build a workflow that checks account verification status, fetches account and routing numbers only for an eligible linked Plaid Item, passes them directly to an approved non-Plaid-partner payment processor, and never logs or persists the numbers.',
       modules: ['workflows'],
       category: 'operations',
       tags: ['automation'],

apps/sim/blocks/blocks/plaid.ts

@@ -91,6 +91,56 @@ describe('Plaid selectors', () => {
     })
   })
 
+  it('normalizes selected countries into requests and isolates them in the query key', async () => {
+    const countryArgs = args({
+      key: 'plaid.institutions',
+      search: 'bank',
+      context: {
+        workspaceId: 'workspace-1',
+        plaidCredentialId: 'credential-1',
+        countryCodes: ' ca, gb ',
+      },
+    })
+    mockRequestJson.mockResolvedValue({ options: [] })
+
+    expect(institutions.getQueryKey(countryArgs)).toContain('CA,GB')
+    await institutions.fetchList?.(countryArgs)
+    await institutions.fetchById?.({ ...countryArgs, search: undefined, detailId: 'ins-1' })
+    expect(mockRequestJson).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ body: expect.objectContaining({ country_codes: ['CA', 'GB'] }) })
+    )
+    expect(mockRequestJson).toHaveBeenLastCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        body: expect.objectContaining({
+          kind: 'institution_detail',
+          institution_id: 'ins-1',
+          country_codes: ['CA', 'GB'],
+        }),
+      })
+    )
+  })
+
+  it('defaults countries to US and rejects malformed country codes', async () => {
+    expect(institutions.getQueryKey(args({ key: 'plaid.institutions', search: 'bank' }))).toContain(
+      'US'
+    )
+    await expect(
+      institutions.fetchList?.(
+        args({
+          key: 'plaid.institutions',
+          search: 'bank',
+          context: {
+            workspaceId: 'workspace-1',
+            plaidCredentialId: 'credential-1',
+            countryCodes: 'ZZ',
+          },
+        })
+      )
+    ).rejects.toThrow('countryCodes contains unsupported Plaid country code: ZZ')
+  })
+
   it('does not issue an unbounded institution search', async () => {
     await expect(
       institutions.fetchList?.(args({ key: 'plaid.institutions', search: '   ' }))

apps/sim/hooks/selectors/providers/plaid/selectors.test.ts

@@ -8,6 +8,7 @@ import type {
   SelectorOption,
   SelectorQueryArgs,
 } from '@/hooks/selectors/types'
+import { parsePlaidCountryCodes } from '@/tools/plaid/utils'
 
 type PlaidSelectorKey = Extract<SelectorKey, 'plaid.accounts' | 'plaid.institutions'>
 
@@ -29,6 +30,15 @@ async function fetchAccountOptions(args: SelectorQueryArgs): Promise<SelectorOpt
   return data.options
 }
 
+function plaidCountryQueryKey(value: string | undefined): string {
+  const normalized = value
+    ?.split(',')
+    .map((code) => code.trim().toUpperCase())
+    .filter(Boolean)
+    .join(',')
+  return normalized || 'US'
+}
+
 export const plaidSelectors = {
   'plaid.accounts': {
     key: 'plaid.accounts',
@@ -57,6 +67,7 @@ export const plaidSelectors = {
       'plaid.institutions',
       context.workspaceId ?? 'none',
       context.plaidCredentialId ?? 'none',
+      plaidCountryQueryKey(context.countryCodes),
       search ?? 'none',
       detailId ?? 'none',
     ],
@@ -73,7 +84,7 @@ export const plaidSelectors = {
           kind: 'institution_search',
           ...scope,
           query,
-          country_codes: ['US'],
+          country_codes: parsePlaidCountryCodes(context.countryCodes),
         },
         signal,
       })
@@ -87,7 +98,7 @@ export const plaidSelectors = {
           kind: 'institution_detail',
           ...scope,
           institution_id: detailId.trim(),
-          country_codes: ['US'],
+          country_codes: parsePlaidCountryCodes(context.countryCodes),
         },
         signal,
       })

apps/sim/hooks/selectors/providers/plaid/selectors.ts

@@ -109,6 +109,7 @@ export interface SelectorContext {
   workflowId?: string
   oauthCredential?: string
   plaidCredentialId?: string
+  countryCodes?: string
   serviceId?: string
   domain?: string
   teamId?: string

apps/sim/hooks/selectors/types.ts

@@ -152,6 +152,15 @@ describe('buildSelectorContextFromBlock', () => {
     ).toBe('advanced-team')
   })
 
+  it('exposes Plaid country codes to the institution selector', () => {
+    const ctx = buildSelectorContextFromBlock('plaid', {
+      operation: { id: 'operation', type: 'dropdown', value: 'search_institutions' },
+      countryCodes: { id: 'countryCodes', type: 'short-input', value: 'US,CA' },
+    })
+
+    expect(ctx.countryCodes).toBe('US,CA')
+  })
+
   it('should ignore subblock keys not in SELECTOR_CONTEXT_FIELDS', () => {
     const ctx = buildSelectorContextFromBlock('knowledge', {
       operation: { id: 'operation', type: 'dropdown', value: 'search' },

apps/sim/lib/workflows/subblocks/context.test.ts

@@ -15,6 +15,7 @@ import {
 export const SELECTOR_CONTEXT_FIELDS = new Set<keyof SelectorContext>([
   'oauthCredential',
   'plaidCredentialId',
+  'countryCodes',
   'domain',
   'teamId',
   'projectId',

apps/sim/lib/workflows/subblocks/context.ts

@@ -1,9 +1,9 @@
 import { ErrorExtractorId } from '@/tools/error-extractors'
 import type { PlaidGetAccountsParams, PlaidGetAccountsResponse } from '@/tools/plaid/types'
+import { PLAID_ACCOUNT_OUTPUT_PROPERTIES } from '@/tools/plaid/types'
 import {
   buildPlaidInternalBody,
   mapPlaidAccount,
-  plaidAccountOutputProperties,
   plaidBaseParamFields,
   plaidRecord,
   requirePlaidArrayField,
@@ -45,7 +45,7 @@ export const plaidGetAccountsTool: ToolConfig<PlaidGetAccountsParams, PlaidGetAc
 
   transformResponse: async (response) => {
     const data = await plaidRecord(response, 'accounts')
-    const accounts = requirePlaidArrayField(data, 'accounts', 'accounts.accounts')
+    const accounts = requirePlaidArrayField(data, 'accounts', 'accounts.accounts', 500)
     const mapped = accounts.map((account, index) =>
       mapPlaidAccount(account, `accounts.accounts[${index}]`)
     )
@@ -62,7 +62,7 @@ export const plaidGetAccountsTool: ToolConfig<PlaidGetAccountsParams, PlaidGetAc
     accounts: {
       type: 'array',
       description: 'Accounts linked to the Item',
-      items: { type: 'object', properties: plaidAccountOutputProperties },
+      items: { type: 'object', properties: PLAID_ACCOUNT_OUTPUT_PROPERTIES },
     },
     count: { type: 'number', description: 'Number of accounts returned' },
   },

apps/sim/tools/plaid/get_accounts.ts

@@ -1,12 +1,14 @@
 import { ErrorExtractorId } from '@/tools/error-extractors'
 import type { PlaidGetAuthParams, PlaidGetAuthResponse } from '@/tools/plaid/types'
+import {
+  PLAID_ACCOUNT_OUTPUT_PROPERTIES,
+  PLAID_NUMBERS_OUTPUT_PROPERTIES,
+} from '@/tools/plaid/types'
 import {
   buildPlaidInternalBody,
   mapPlaidAccount,
   mapPlaidNumbers,
-  plaidAccountOutputProperties,
   plaidBaseParamFields,
-  plaidNumbersOutputProperties,
   plaidRecord,
   requirePlaidArrayField,
   splitPlaidList,
@@ -47,7 +49,7 @@ export const plaidGetAuthTool: ToolConfig<PlaidGetAuthParams, PlaidGetAuthRespon
 
   transformResponse: async (response) => {
     const data = await plaidRecord(response, 'auth')
-    const accounts = requirePlaidArrayField(data, 'accounts', 'auth.accounts')
+    const accounts = requirePlaidArrayField(data, 'accounts', 'auth.accounts', 500)
     return {
       success: true,
       output: {
@@ -63,12 +65,12 @@ export const plaidGetAuthTool: ToolConfig<PlaidGetAuthParams, PlaidGetAuthRespon
     accounts: {
       type: 'array',
       description: 'Depository accounts on the Item',
-      items: { type: 'object', properties: plaidAccountOutputProperties },
+      items: { type: 'object', properties: PLAID_ACCOUNT_OUTPUT_PROPERTIES },
     },
     numbers: {
       type: 'object',
       description: 'Account and routing numbers grouped by scheme',
-      properties: plaidNumbersOutputProperties,
+      properties: PLAID_NUMBERS_OUTPUT_PROPERTIES,
     },
   },
 }

apps/sim/tools/plaid/get_auth.ts

@@ -1,9 +1,9 @@
 import { ErrorExtractorId } from '@/tools/error-extractors'
 import type { PlaidGetBalancesParams, PlaidGetBalancesResponse } from '@/tools/plaid/types'
+import { PLAID_ACCOUNT_OUTPUT_PROPERTIES } from '@/tools/plaid/types'
 import {
   buildPlaidInternalBody,
   mapPlaidAccount,
-  plaidAccountOutputProperties,
   plaidBaseParamFields,
   plaidRecord,
   requirePlaidArrayField,
@@ -55,7 +55,7 @@ export const plaidGetBalancesTool: ToolConfig<PlaidGetBalancesParams, PlaidGetBa
 
   transformResponse: async (response) => {
     const data = await plaidRecord(response, 'balances')
-    const accounts = requirePlaidArrayField(data, 'accounts', 'balances.accounts')
+    const accounts = requirePlaidArrayField(data, 'accounts', 'balances.accounts', 500)
     const mapped = accounts.map((account, index) =>
       mapPlaidAccount(account, `balances.accounts[${index}]`)
     )
@@ -72,7 +72,7 @@ export const plaidGetBalancesTool: ToolConfig<PlaidGetBalancesParams, PlaidGetBa
     accounts: {
       type: 'array',
       description: 'Accounts with refreshed real-time balances',
-      items: { type: 'object', properties: plaidAccountOutputProperties },
+      items: { type: 'object', properties: PLAID_ACCOUNT_OUTPUT_PROPERTIES },
     },
     count: { type: 'number', description: 'Number of accounts returned' },
   },