chore: import upstream snapshot with attribution

apps/sim/tools/persona/utils.ts

@@ -0,0 +1,523 @@
+import type {
+  PersonaAccount,
+  PersonaCase,
+  PersonaDocument,
+  PersonaImporter,
+  PersonaInquiry,
+  PersonaInquiryTemplate,
+  PersonaReport,
+  PersonaVerification,
+} from '@/tools/persona/types'
+import type { OutputProperty } from '@/tools/types'
+
+export const PERSONA_API_BASE = 'https://api.withpersona.com/api/v1'
+
+/**
+ * Persona API version pinned for this integration so responses keep a stable
+ * shape regardless of the organization's dashboard default.
+ */
+export const PERSONA_API_VERSION = '2025-12-08'
+
+/**
+ * Raw JSON:API resource object returned by the Persona API.
+ */
+export interface PersonaResourceData {
+  type?: string
+  id?: string
+  attributes?: Record<string, unknown>
+  relationships?: Record<string, unknown>
+}
+
+/**
+ * Top-level JSON:API envelope returned by the Persona API.
+ */
+export interface PersonaApiEnvelope {
+  data?: unknown
+  links?: unknown
+  meta?: Record<string, unknown>
+}
+
+/**
+ * Extracts a human-readable message from a Persona JSON:API error body.
+ */
+export function extractPersonaErrorMessage(body: unknown, fallback: string): string {
+  if (body !== null && typeof body === 'object') {
+    const errors = (body as Record<string, unknown>).errors
+    if (Array.isArray(errors) && errors.length > 0) {
+      const first = errors[0]
+      if (first !== null && typeof first === 'object') {
+        const title = (first as Record<string, unknown>).title
+        if (typeof title === 'string' && title.length > 0) {
+          return title
+        }
+      }
+    }
+  }
+  return fallback
+}
+
+/**
+ * Reads a Persona JSON response, throwing a descriptive error for non-2xx
+ * responses using the JSON:API error format.
+ */
+export async function parsePersonaResponse(response: Response): Promise<PersonaApiEnvelope> {
+  const body: unknown = await response.json().catch(() => null)
+  if (!response.ok) {
+    throw new Error(
+      extractPersonaErrorMessage(
+        body,
+        `Persona API error: ${response.status} ${response.statusText}`
+      )
+    )
+  }
+  return body !== null && typeof body === 'object' ? (body as PersonaApiEnvelope) : {}
+}
+
+/**
+ * Narrows an unknown JSON:API `data` value to a single resource object.
+ */
+export function asResource(value: unknown): PersonaResourceData {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as PersonaResourceData)
+    : {}
+}
+
+/**
+ * Narrows an unknown JSON:API `data` value to a list of resource objects.
+ */
+export function asResourceList(value: unknown): PersonaResourceData[] {
+  return Array.isArray(value) ? value.map(asResource) : []
+}
+
+/**
+ * Builds the standard headers for Persona API requests.
+ */
+export function buildPersonaHeaders(apiKey: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    'Persona-Version': PERSONA_API_VERSION,
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+  }
+}
+
+/**
+ * Parses a JSON object param that may arrive as an object or a JSON string.
+ * Throws a descriptive error when the value is not a JSON object.
+ */
+export function parseJsonObjectParam(
+  value: Record<string, unknown> | string | undefined,
+  label: string
+): Record<string, unknown> | undefined {
+  if (value === undefined || value === '') return undefined
+  let parsed: unknown = value
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value)
+    } catch {
+      throw new Error(`${label} must be a valid JSON object`)
+    }
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object of key-value pairs`)
+  }
+  return parsed as Record<string, unknown>
+}
+
+/**
+ * Parses a string array param that may arrive as an array or a JSON string.
+ * Throws a descriptive error when the value is not an array of strings.
+ */
+export function parseStringArrayParam(
+  value: string[] | string | undefined,
+  label: string
+): string[] | undefined {
+  if (value === undefined || value === '') return undefined
+  let parsed: unknown = value
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value)
+    } catch {
+      throw new Error(`${label} must be a valid JSON array of strings`)
+    }
+  }
+  if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === 'string')) {
+    throw new Error(`${label} must be a JSON array of strings`)
+  }
+  return parsed
+}
+
+function getString(attrs: Record<string, unknown>, key: string): string | null {
+  const value = attrs[key]
+  return typeof value === 'string' ? value : null
+}
+
+function getBoolean(attrs: Record<string, unknown>, key: string): boolean | null {
+  const value = attrs[key]
+  return typeof value === 'boolean' ? value : null
+}
+
+function getNumber(attrs: Record<string, unknown>, key: string, fallback: number): number {
+  const value = attrs[key]
+  return typeof value === 'number' ? value : fallback
+}
+
+function getStringArray(attrs: Record<string, unknown>, key: string): string[] {
+  const value = attrs[key]
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string')
+    : []
+}
+
+function getObject(attrs: Record<string, unknown>, key: string): Record<string, unknown> | null {
+  const value = attrs[key]
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+/**
+ * Extracts the `page[after]` cursor from a JSON:API `links.next` URL.
+ */
+export function getNextCursor(links: unknown): string | null {
+  if (links === null || typeof links !== 'object') return null
+  const next = (links as Record<string, unknown>).next
+  if (typeof next !== 'string' || next.length === 0) return null
+  const queryIndex = next.indexOf('?')
+  if (queryIndex === -1) return null
+  const searchParams = new URLSearchParams(next.slice(queryIndex + 1))
+  return searchParams.get('page[after]')
+}
+
+/**
+ * Maps a raw Persona Inquiry resource to its flattened representation.
+ */
+export function mapInquiry(data: PersonaResourceData): PersonaInquiry {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    status: getString(attrs, 'status'),
+    referenceId: getString(attrs, 'reference-id'),
+    note: getString(attrs, 'note'),
+    tags: getStringArray(attrs, 'tags'),
+    fields: getObject(attrs, 'fields'),
+    createdAt: getString(attrs, 'created-at'),
+    startedAt: getString(attrs, 'started-at'),
+    completedAt: getString(attrs, 'completed-at'),
+    failedAt: getString(attrs, 'failed-at'),
+    expiredAt: getString(attrs, 'expired-at'),
+    decisionedAt: getString(attrs, 'decisioned-at'),
+  }
+}
+
+/**
+ * Maps a raw Persona Account resource to its flattened representation.
+ */
+export function mapAccount(data: PersonaResourceData): PersonaAccount {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    referenceId: getString(attrs, 'reference-id'),
+    accountTypeName: getString(attrs, 'account-type-name'),
+    accountStatus: getString(attrs, 'account-status'),
+    tags: getStringArray(attrs, 'tags'),
+    fields: getObject(attrs, 'fields'),
+    createdAt: getString(attrs, 'created-at'),
+    updatedAt: getString(attrs, 'updated-at'),
+  }
+}
+
+/**
+ * Maps a raw Persona Case resource to its flattened representation.
+ */
+export function mapCase(data: PersonaResourceData): PersonaCase {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    status: getString(attrs, 'status'),
+    name: getString(attrs, 'name'),
+    resolution: getString(attrs, 'resolution'),
+    assigneeId: getString(attrs, 'assignee-id'),
+    tags: getStringArray(attrs, 'tags'),
+    fields: getObject(attrs, 'fields'),
+    createdAt: getString(attrs, 'created-at'),
+    assignedAt: getString(attrs, 'assigned-at'),
+    resolvedAt: getString(attrs, 'resolved-at'),
+  }
+}
+
+/**
+ * Maps a raw Persona Report resource to its flattened representation.
+ */
+export function mapReport(data: PersonaResourceData): PersonaReport {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    type: data.type ?? '',
+    status: getString(attrs, 'status'),
+    hasMatch: getBoolean(attrs, 'has-match'),
+    tags: getStringArray(attrs, 'tags'),
+    createdAt: getString(attrs, 'created-at'),
+    completedAt: getString(attrs, 'completed-at'),
+    attributes: attrs,
+  }
+}
+
+/**
+ * Maps a raw Persona Verification resource to its flattened representation.
+ */
+export function mapVerification(data: PersonaResourceData): PersonaVerification {
+  const attrs = data.attributes ?? {}
+  const checks = attrs.checks
+  return {
+    id: data.id ?? '',
+    type: data.type ?? '',
+    status: getString(attrs, 'status'),
+    checks: Array.isArray(checks)
+      ? checks.filter(
+          (check): check is Record<string, unknown> => check !== null && typeof check === 'object'
+        )
+      : [],
+    countryCode: getString(attrs, 'country-code'),
+    createdAt: getString(attrs, 'created-at'),
+    submittedAt: getString(attrs, 'submitted-at'),
+    completedAt: getString(attrs, 'completed-at'),
+    attributes: attrs,
+  }
+}
+
+/**
+ * Maps a raw Persona Document resource to its flattened representation.
+ */
+export function mapDocument(data: PersonaResourceData): PersonaDocument {
+  const attrs = data.attributes ?? {}
+  const files = attrs.files
+  return {
+    id: data.id ?? '',
+    type: data.type ?? '',
+    status: getString(attrs, 'status'),
+    kind: getString(attrs, 'kind'),
+    files: Array.isArray(files)
+      ? files
+          .filter(
+            (file): file is Record<string, unknown> => file !== null && typeof file === 'object'
+          )
+          .map((file) => ({
+            filename: typeof file.filename === 'string' ? file.filename : null,
+            url: typeof file.url === 'string' ? file.url : null,
+            byteSize: typeof file['byte-size'] === 'number' ? file['byte-size'] : null,
+          }))
+      : [],
+    createdAt: getString(attrs, 'created-at'),
+    processedAt: getString(attrs, 'processed-at'),
+    attributes: attrs,
+  }
+}
+
+/**
+ * Maps a raw Persona Inquiry Template resource to its flattened representation.
+ */
+export function mapInquiryTemplate(data: PersonaResourceData): PersonaInquiryTemplate {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    name: getString(attrs, 'name'),
+    status: getString(attrs, 'status'),
+  }
+}
+
+/**
+ * Maps a raw Persona Account Importer resource to its flattened representation.
+ */
+export function mapImporter(data: PersonaResourceData): PersonaImporter {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    status: getString(attrs, 'status'),
+    successfulCount: getNumber(attrs, 'successful-count', 0),
+    errorCount: getNumber(attrs, 'error-count', 0),
+    duplicateCount: getNumber(attrs, 'duplicate-count', 0),
+    createdAt: getString(attrs, 'created-at'),
+    completedAt: getString(attrs, 'completed-at'),
+  }
+}
+
+export const INQUIRY_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Inquiry ID (starts with inq_)' },
+  status: {
+    type: 'string',
+    description:
+      'Inquiry status (created, pending, completed, failed, expired, needs_review, approved, declined)',
+    nullable: true,
+  },
+  referenceId: {
+    type: 'string',
+    description: 'Reference ID linking the inquiry to an entity in your user model',
+    nullable: true,
+  },
+  note: { type: 'string', description: 'Free-form note on the inquiry', nullable: true },
+  tags: {
+    type: 'array',
+    description: 'Tags associated with the inquiry',
+    items: { type: 'string' },
+  },
+  fields: {
+    type: 'json',
+    description: 'Field name to field value pairs collected by the inquiry template',
+    nullable: true,
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  startedAt: { type: 'string', description: 'ISO 8601 start timestamp', nullable: true },
+  completedAt: { type: 'string', description: 'ISO 8601 completion timestamp', nullable: true },
+  failedAt: { type: 'string', description: 'ISO 8601 failure timestamp', nullable: true },
+  expiredAt: { type: 'string', description: 'ISO 8601 expiration timestamp', nullable: true },
+  decisionedAt: { type: 'string', description: 'ISO 8601 decision timestamp', nullable: true },
+}
+
+export const ACCOUNT_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Account ID (starts with act_)' },
+  referenceId: {
+    type: 'string',
+    description: 'Reference ID linking the account to an entity in your user model',
+    nullable: true,
+  },
+  accountTypeName: { type: 'string', description: 'Name of the account type', nullable: true },
+  accountStatus: { type: 'string', description: 'Status set on the account', nullable: true },
+  tags: {
+    type: 'array',
+    description: 'Tags associated with the account',
+    items: { type: 'string' },
+  },
+  fields: {
+    type: 'json',
+    description: 'Field name to field value pairs defined by the account type',
+    nullable: true,
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  updatedAt: { type: 'string', description: 'ISO 8601 last update timestamp', nullable: true },
+}
+
+export const CASE_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Case ID (starts with case_)' },
+  status: { type: 'string', description: 'Case status', nullable: true },
+  name: { type: 'string', description: 'Case name', nullable: true },
+  resolution: { type: 'string', description: 'Case resolution', nullable: true },
+  assigneeId: { type: 'string', description: 'ID of the assigned reviewer', nullable: true },
+  tags: { type: 'array', description: 'Tags associated with the case', items: { type: 'string' } },
+  fields: {
+    type: 'json',
+    description: 'Field name to field value pairs defined by the case template',
+    nullable: true,
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  assignedAt: { type: 'string', description: 'ISO 8601 assignment timestamp', nullable: true },
+  resolvedAt: { type: 'string', description: 'ISO 8601 resolution timestamp', nullable: true },
+}
+
+export const REPORT_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Report ID (starts with rep_)' },
+  type: { type: 'string', description: 'Report type (e.g. report/watchlist)' },
+  status: {
+    type: 'string',
+    description: 'Report status (pending, ready, errored)',
+    nullable: true,
+  },
+  hasMatch: {
+    type: 'boolean',
+    description: 'Whether the report found at least one match',
+    nullable: true,
+    optional: true,
+  },
+  tags: {
+    type: 'array',
+    description: 'Tags associated with the report',
+    items: { type: 'string' },
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  completedAt: { type: 'string', description: 'ISO 8601 completion timestamp', nullable: true },
+  attributes: {
+    type: 'json',
+    description: 'Full report attributes, which vary by report type',
+  },
+}
+
+export const VERIFICATION_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Verification ID (starts with ver_)' },
+  type: { type: 'string', description: 'Verification type (e.g. verification/government-id)' },
+  status: {
+    type: 'string',
+    description:
+      'Verification status (initiated, submitted, passed, failed, requires_retry, canceled)',
+    nullable: true,
+  },
+  checks: {
+    type: 'array',
+    description: 'Individual checks run as part of the verification',
+    items: { type: 'object' },
+  },
+  countryCode: { type: 'string', description: 'ISO 3166-1 alpha-2 country code', nullable: true },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  submittedAt: { type: 'string', description: 'ISO 8601 submission timestamp', nullable: true },
+  completedAt: { type: 'string', description: 'ISO 8601 completion timestamp', nullable: true },
+  attributes: {
+    type: 'json',
+    description: 'Full verification attributes, which vary by verification type',
+  },
+}
+
+export const DOCUMENT_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Document ID (starts with doc_)' },
+  type: { type: 'string', description: 'Document type (e.g. document/government-id)' },
+  status: {
+    type: 'string',
+    description: 'Document status (initiated, submitted, processed, errored)',
+    nullable: true,
+  },
+  kind: { type: 'string', description: 'Kind of document collected', nullable: true },
+  files: {
+    type: 'array',
+    description: 'Files uploaded to the document, with Persona-hosted download URLs',
+    items: {
+      type: 'object',
+      properties: {
+        filename: { type: 'string', description: 'Original file name', nullable: true },
+        url: {
+          type: 'string',
+          description: 'Persona-hosted file URL (requires API key to download)',
+          nullable: true,
+        },
+        byteSize: { type: 'number', description: 'File size in bytes', nullable: true },
+      },
+    },
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  processedAt: { type: 'string', description: 'ISO 8601 processing timestamp', nullable: true },
+  attributes: {
+    type: 'json',
+    description: 'Full document attributes, which vary by document type',
+  },
+}
+
+export const INQUIRY_TEMPLATE_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Inquiry template ID (starts with itmpl_)' },
+  name: { type: 'string', description: 'Name of the inquiry template', nullable: true },
+  status: {
+    type: 'string',
+    description: 'Inquiry template status (active, inactive)',
+    nullable: true,
+  },
+}
+
+export const IMPORTER_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Importer ID (starts with mprt_)' },
+  status: {
+    type: 'string',
+    description: 'Importer status (pending, ready, errored)',
+    nullable: true,
+  },
+  successfulCount: { type: 'number', description: 'Number of rows imported successfully' },
+  errorCount: { type: 'number', description: 'Number of rows that failed to import' },
+  duplicateCount: { type: 'number', description: 'Number of duplicate rows skipped' },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  completedAt: { type: 'string', description: 'ISO 8601 completion timestamp', nullable: true },
+}