feat(persona): add Persona identity verification integration

[waleedlatif1]

Summary

• Add Persona (withpersona.com) identity verification integration: 17 tools covering inquiries (create, get, list, approve, decline, one-time link, print PDF), accounts (create, get, list, CSV bulk import), cases (list, get), reports (create watchlist/adverse-media/PEP, get), verifications (get), and documents (get)
• File handling follows the standard patterns: CSV import goes through an internal contract-bound route (/api/tools/persona/import-accounts) with checkInternalAuth → parseRequest → verifyFileAccess → downloadFileFromStorage, and the block uses the file-upload basic/advanced canonical-param pattern with normalizeFileInput; inquiry PDF download returns a stored execution file
• Persona block with operation dropdown, conditional subBlocks, wand configs for JSON fields and timestamps, BlockMeta with 8 templates and 6 skills, and the Persona logo icon (white block background)
• API requests pin Persona-Version: 2025-12-08 and map JSON:API kebab-case resources to flat camelCase outputs with typed output properties; validated against Persona's official OpenAPI spec
• Generated docs page with manual intro content

Type of Change

• New feature

Testing

Typecheck, biome, and check:api-validation pass; request builders and response transforms for all 17 tools exercised against fixtures derived from Persona's OpenAPI spec

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Jun 11, 2026 6:15pm

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

PR Summary

High Risk
Large security/compliance surface: workflows can approve/decline verifications, run watchlist screening, redact PII, and bulk-import user data via authenticated file handling and user-supplied API keys.

Overview
Adds a Persona identity-verification integration so workflows and agents can call Persona with an API key: inquiries (lifecycle, links, PDF, redact), accounts (CRUD, CSV bulk import), cases, screening reports, verifications, documents, and inquiry templates.

Implementation follows existing integration patterns: 26persona_* tools in the tool registry, shared utils (pinned Persona-Version: 2025-12-08, JSON:API → flat outputs), a Persona workflow block with an operation dropdown and conditional fields, integrations.json + block registry, and docs (persona.mdx, nav, PersonaIcon). CSV import uses an internal /api/tools/persona/import-accounts route (checkInternalAuth, file access checks, base64 upload to Persona); inquiry PDFs return execution files.

^{Reviewed by Cursor Bugbot for commit ca6853d. Configure here.}

[greptile-apps]

Greptile Summary

Adds a full Persona identity-verification integration: 26 tools covering the inquiry lifecycle (create/get/list/update/approve/decline/review/resume/expire/redact), account management (create/get/list/update/import/redact), cases, screening reports (watchlist/adverse-media/PEP), verifications, documents, and inquiry templates. A shared parsePersonaResponse helper guards all tools against non-2xx responses, and print_inquiry_pdf correctly branches on response.ok before the binary read.

• Tools & block: 26 tools with typed params/outputs registered in tools/registry.ts; the Persona block in blocks/blocks/persona.ts wires all operations via a single dropdown with conditional subBlocks, numeric coercions, and a BlockMeta with 8 templates and 6 skills.
• CSV import route: app/api/tools/persona/import-accounts/route.ts enforces internal auth, contract validation, file-ownership assertion, and storage download before forwarding the base64-encoded CSV to Persona — consistent with the project's file-handling conventions.
• Docs: Generated page at apps/docs/content/docs/en/integrations/persona.mdx with manual intro content and integration metadata.

Confidence Score: 5/5

Safe to merge. The integration is self-contained new code with no changes to existing tool paths. All direct-API tools route through the shared parsePersonaResponse guard, the CSV import route enforces auth and file-ownership checks, and print_inquiry_pdf branches correctly on response.ok before the binary read.

Every tool either uses the shared parsePersonaResponse helper (which throws on non-2xx before any mapping) or has its own response.ok guard. The generate_inquiry_link and resume_inquiry tools throw explicitly when expected meta fields are absent. The create_report validation guard letting a middle-name-only query through is a minor quality nit that won't break callers. No existing code is modified, and the new route follows the established internal-auth + file-access pattern correctly.

No files require special attention. create_report.ts has a minor validation gap (accepting nameMiddle alone as a sufficient search term) but it does not break callers.

Important Files Changed

Filename	Overview
apps/sim/tools/persona/utils.ts	Shared helpers: parsePersonaResponse (guards response.ok before mapping), extractPersonaErrorMessage, asResource/asResourceList, buildPersonaHeaders, parseJsonObjectParam, parseStringArrayParam, getNextCursor, and all map* + OUTPUT_PROPERTIES exports. Well-structured and consistent.
apps/sim/tools/persona/create_report.ts	Creates watchlist/adverse-media/PEP report. Validates reportTemplateId and type. "At least one name" guard includes name-middle alone, which produces a misleading error message and a near-useless Persona query.
apps/sim/app/api/tools/persona/import-accounts/route.ts	Internal route for CSV bulk import: checks internal auth, parses contract, asserts file ownership, downloads from storage, base64-encodes, and posts to Persona. response.ok guard and error extraction correctly applied.
apps/sim/blocks/blocks/persona.ts	Full block definition with 26 operations, conditional subBlocks, numeric/file coercions in params(), BlockMeta with 8 templates and 6 skills. Patterns consistent with codebase conventions.
apps/sim/tools/persona/print_inquiry_pdf.ts	Downloads PDF via GET with Accept: application/pdf. Correctly guards response.ok before binary read; on failure reads body as text, JSON-parses, and throws Persona error title.
apps/sim/tools/persona/generate_inquiry_link.ts	Generates one-time link. Throws if primary link is missing; falls back to full link when short link is absent. expiresInSeconds validated as positive integer.
apps/sim/tools/persona/resume_inquiry.ts	Resumes inquiry and extracts sessionToken. Throws if token is missing. Correct parsePersonaResponse usage.
apps/sim/lib/api/contracts/tools/persona.ts	Zod contract for the import-accounts route. apiKey min(1) and RawFileInputSchema validation are correct; response schema matches the importer type.
apps/sim/tools/persona/create_inquiry.ts	Creates inquiry with template ID prefix routing (itmpl_/itmplv_/tmpl_). referenceId correctly placed in body meta for auto-account creation. parsePersonaResponse and validation guards are correct.
apps/sim/tools/persona/import_accounts.ts	File-upload tool that delegates to the internal /api/tools/persona/import-accounts route. Uses standard pattern: body sends apiKey+file, transformResponse checks data.success and propagates the error message.
apps/sim/tools/registry.ts	All 26 Persona tools registered alphabetically under the persona namespace. No naming or order issues detected.

Sequence Diagram

sequenceDiagram
participant User as User / Workflow
participant Block as Persona Block
participant ToolExec as Tool Executor
participant ImportRoute as /api/tools/persona/import-accounts
participant Storage as File Storage
participant PersonaAPI as Persona API
User->>Block: Trigger operation (e.g. create_inquiry)
Block->>ToolExec: params(operation, apiKey, …)
alt Direct API tool (24 tools)
ToolExec->>PersonaAPI: "fetch(url, {headers: buildPersonaHeaders(apiKey), …})"
PersonaAPI-->>ToolExec: JSON:API response
ToolExec->>ToolExec: parsePersonaResponse() — ok? map resource : throw
ToolExec-->>Block: "{success: true, output: {inquiry/account/…}}"
else import_accounts (CSV)
ToolExec->>ImportRoute: "POST /api/tools/persona/import-accounts {apiKey, file}"
ImportRoute->>ImportRoute: checkInternalAuth + parseRequest + assertToolFileAccess
ImportRoute->>Storage: downloadFileFromStorage(userFile)
Storage-->>ImportRoute: Buffer
ImportRoute->>PersonaAPI: "POST /importer/accounts {data: base64 CSV}"
PersonaAPI-->>ImportRoute: "{data: importer resource}"
ImportRoute-->>ToolExec: "{success: true, output: {importer}}"
ToolExec-->>Block: "{success: true, output: {importer}}"
else print_inquiry_pdf
ToolExec->>PersonaAPI: "GET /inquiries/{id}/print Accept: application/pdf"
PersonaAPI-->>ToolExec: PDF bytes (or error JSON)
ToolExec->>ToolExec: ok? base64(arrayBuffer) : parse error + throw
ToolExec-->>Block: "{success: true, output: {file}}"
end

Loading

_{Reviews (8): Last reviewed commit: "improvement(persona): require session to..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[greptile-apps]

Greptile Summary

This PR adds a comprehensive Persona (withpersona.com) identity verification integration with 17 tools covering inquiries, accounts, cases, reports, verifications, and documents. The implementation follows established codebase patterns: internal-routed CSV import with auth/file-access checks, file-upload canonical subBlock pairs for the block UI, JSON:API response mapping to flat camelCase types, and a pinned Persona-Version header.

• 17 tools registered and wired to a single multi-operation PersonaBlock with per-operation conditional subBlocks, wand configs, and a complete BlockMeta with 8 templates and 6 skills.
• File import routes through /api/tools/persona/import-accounts with checkInternalAuth, verifyFileAccess, and downloadFileFromStorage following the standard internal-route contract pattern.
• Response mappers in utils.ts convert JSON:API resource objects to flat typed structs; print_inquiry_pdf handles binary PDF responses and returns an execution-file object.

Confidence Score: 3/5

Safe to merge after fixing the two broken-response paths in generate_inquiry_link.ts and print_inquiry_pdf.ts; all other tools and the import route are well-structured.

The one-time link generator silently delivers an empty string when Persona does not return a link, and the PDF printer wraps non-2xx Persona error bodies into a fake successful file output — both produce wrong data on normal error paths. All 15 other tools and the import route follow established patterns correctly.

apps/sim/tools/persona/generate_inquiry_link.ts and apps/sim/tools/persona/print_inquiry_pdf.ts need attention; all other files look solid.

Important Files Changed

Filename	Overview
apps/sim/tools/persona/generate_inquiry_link.ts	Generates a one-time link for inquiries; silently falls back to empty string if the link is absent from the API response meta, risking silent broken-link delivery to end users.
apps/sim/tools/persona/print_inquiry_pdf.ts	Downloads inquiry PDF and returns base64-encoded execution file. Does not check response.ok before consuming the body, so a non-2xx response from Persona will be decoded as a PDF and silently returned as a broken file.
apps/sim/app/api/tools/persona/import-accounts/route.ts	Internal route for CSV bulk import; correctly chains checkInternalAuth → verifyFileAccess → downloadFileFromStorage.
apps/sim/blocks/blocks/persona.ts	Full block definition with 17 operation dropdown options, per-operation conditional subBlocks, canonical file-upload pair, wand configs, and BlockMeta with 8 templates and 6 skills.
apps/sim/tools/persona/create_report.ts	Creates watchlist/adverse-media/PEP reports with per-type country-code field key mapping. Correctly validates that at least one name field is present before submitting.
apps/sim/tools/persona/utils.ts	Shared utilities: JSON:API mappers, output property constants, header builder, and pagination cursor extractor. Well-typed and defensive throughout.
apps/sim/lib/api/contracts/tools/persona.ts	Zod contract for the import-accounts internal route; validates apiKey min-length and delegates file schema to RawFileInputSchema.
apps/sim/tools/persona/types.ts	All Persona domain types and param/response interfaces; cleanly typed with no use of any.
apps/sim/tools/registry.ts	All 17 Persona tools registered alphabetically in the global tool registry.
apps/sim/tools/persona/create_inquiry.ts	Creates inquiries with proper template-ID prefix routing and optional JSON field pre-fill; referenceId for auto-account-creation passed in meta.

_{Reviews (2): Last reviewed commit: "feat(persona): complete API coverage — i..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit b082119. Configure here.}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ca6853d. Configure here.}

[waleedlatif1]

@greptile review