persona-sdk-patternsDesign a typed Persona REST adapter that preserves JSON:API envelopes, request evidence, and compatible additions. Use when building a reusable client. Trigger with: "wrap Persona API", "type Persona responses", "Persona SDK pattern".
Independent GitHub snapshot · Automated classification · Original documentation governs
name: persona-sdk-patterns description: >- Design a typed Persona REST adapter that preserves JSON:API envelopes, request evidence, and compatible additions. Use when building a reusable client. Trigger with: "wrap Persona API", "type Persona responses", "Persona SDK pattern". allowed-tools: Read, Grep, Write, Edit version: 2.0.0 argument-hint: '[language-and-endpoints]' model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:
Keep transport, Persona resource envelopes, and domain decisions separate. The adapter should preserve raw identifiers and metadata, tolerate new resources and fields, and expose explicit mutation evidence rather than flattening every response into a brittle model.
Centralize the API base, bearer header, dated version, timeouts, request IDs, and safe telemetry. Do not retry mutations blindly.
Represent data, type, id, attributes, relationships, included, meta, links, and structured errors before adding endpoint-specific views.
Treat unknown fields, resource types, event types, and array order changes as data to preserve or ignore safely, not parse failures.
Require an operation ID and Idempotency-Key for POST commands. Queries may use bounded retries; commands reconcile observed state after ambiguity.
Return status, request ID, rate and quota headers, resource ID, and a redacted envelope hash. Keep customer attributes behind the domain privacy boundary.
Cover errors, pagination, unknown fields, multiple verification types, session metadata, throttling, and ambiguous POST outcomes.
Inject the environment-scoped bearer key at the transport boundary and pin Persona-Version per request. Callers must never pass raw credentials or select an arbitrary host.
Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.
Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.
A TypeScript adapter returns PersonaEnvelope<Inquiry> plus a redacted request receipt. An unknown relationship is retained in the raw envelope while the domain mapper continues using the fields it understands.
| Failure | Response |
|---|---|
| Unknown type or field | Preserve or ignore it safely and surface a compatibility metric; do not reject a compatible API addition. |
| Timeout after POST | Read the resource or operation evidence before considering a replay with the same parameters. |
| Malformed error envelope | Return transport status and a redacted body hash while protecting PII. |
Verify the result against the linked first-party evidence, the pinned API version, redacted contract fixtures, an expected failure path, and the documented rollback or manual-disposition path. A successful request is not proof of a successful identity decision.