persona-sdk-patterns

name	persona-sdk-patterns
description	Production Persona API client wrapper with retry, pagination, typed responses. Use when working with Persona identity verification. Trigger with phrases like "persona sdk-patterns", "persona sdk-patterns".
allowed-tools	Read, Write, Edit
version	1.4.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","persona","identity","kyc","verification"]
compatibility	Designed for Claude Code

persona sdk patterns | sed 's/\b(.)/\u\1/g'

Overview

Singleton API client, typed verification results, pagination through inquiries, error classification.

Prerequisites

• Completed persona-install-auth setup
• Valid Persona API key (sandbox or production)

Instructions

Step 1: Typed API Client Wrapper

import axios, { AxiosInstance, AxiosError } from 'axios';

interface PersonaConfig {
  apiKey: string;
  version?: string;
  baseURL?: string;
}

class PersonaClient {
  private http: AxiosInstance;

  constructor(config: PersonaConfig) {
    this.http = axios.create({
      baseURL: config.baseURL || 'https://withpersona.com/api/v1',
      headers: {
        'Authorization': `Bearer ${config.apiKey}`,
        'Persona-Version': config.version || '2023-01-05',
        'Content-Type': 'application/json',
      },
    });
  }

  async createInquiry(templateId: string, referenceId: string, fields?: Record<string, any>) {
    const { data } = await this.http.(, {
      : { : { : templateId, : referenceId, fields } },
    });
     data.;
  }

   () {
     { data } =  ..();
     data.;
  }

   () {
     { data } =  ..(, {
      : {
        : params.,
        : params.,
        : params. || ,
      },
    });
     data.;
  }

   () {
     { data } =  ..();
     data.;
  }
}


 :  |  = ;
  ():  {
   (!_client) {
    _client =  ({ : process..! });
  }
   _client;
}

Step 2: Error Classification

function classifyPersonaError(error: AxiosError): { retryable: boolean; message: string } {
  const status = error.response?.status;
  if (status === 429) return { retryable: true, message: 'Rate limited' };
  if (status && status >= 500) return { retryable: true, message: 'Server error' };
  if (status === 401) return { retryable: false, message: 'Invalid API key' };
  if (status === 422) return { retryable: false, message: 'Invalid request' };
  return { retryable: false, message: error.message };
}

Output

• Typed Persona API client with inquiry and verification methods
• Singleton pattern for reuse
• Error classification for retry decisions
• Paginated inquiry listing

Error Handling

Pattern	Use Case	Benefit
Singleton	All API calls	One client, consistent headers
Error classifier	Retry decisions	Only retry 429/5xx
Typed responses	Data access	Autocomplete, type safety

Resources

• Persona API Reference
• API Introduction

Next Steps

Apply in persona-core-workflow-a for real KYC flows.