---

name: attio-sdk-patterns description: >- Build a typed Attio REST client with tenant-aware tokens, endpoint-specific pagination, structured errors, bounded retries, and contract tests while distinguishing it from the Attio App SDK. Use when creating or refactoring Attio integration code. Trigger with "Attio SDK", "Attio client wrapper", or "typed Attio API". argument-hint: "[repository-path] [language-or-runtime]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit version: 1.8.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags:

• saas
• attio
• sdk model: inherit effort: high compatibility: Designed for Claude Code

---

Attio Typed Client Patterns

Overview

This skill designs a small REST client around the endpoints an application actually uses. It does not conflate a server-side REST wrapper with Attio's attio App SDK for in-product apps.

Prerequisites

• Runtime, package manager, and existing HTTP conventions
• Exact endpoints, methods, scopes, and response shapes
• Tenancy and credential model
• Existing tests and error-handling policy

Tool Discipline

Use Read, Glob, and Grep to inspect clients, types, dependency policy, and tests. Use WebFetch only for official Attio REST, OpenAPI, and App SDK documentation. Use Write or Edit after the target abstraction and endpoint contracts are confirmed.

Current Contract

• Attio REST requests use the https://api.attio.com/v2 base URL and endpoint-specific scopes.
• Pagination is endpoint-specific: some operations use limit and offset, while others return a cursor such as pagination.next_cursor.
• The Attio App SDK package attio serves apps running inside Attio and is not a universal REST client replacement.
• Generated types can start from the official OpenAPI document, but application-level validation and tests still own runtime safety.

Authentication

Inject a token provider that resolves the authorized workspace at request time. Do not place a global production token in source, client constructors, snapshots, fixtures, or logs.

Instructions

1. Inventory call sites and group the smallest useful endpoint surface.
2. Reverify each method, path, scope, body, response, and paginator in official documentation.
3. Define typed request and response boundaries with runtime validation for external data.
4. Centralize base URL, authorization, timeouts, redaction, request IDs, and structured error translation.
5. Implement separate offset and cursor iterators; bind each endpoint explicitly to the correct strategy.
6. Retry only eligible transient failures, respecting rate limits and mutation idempotency.
7. Add fixture, pagination-termination, error, redaction, and tenant-isolation tests.

Approval Boundaries

Do not replace an established client, add a generated dependency, or migrate production call sites without owner approval and compatibility evidence.

Output

Return the endpoint inventory, client interface, pagination mapping, error taxonomy, auth boundary, test evidence, migration plan, and rollback point.

Error Handling

Condition	Response
Endpoint contract is ambiguous	Stop and recheck the official endpoint reference.
Runtime payload fails validation	Return a typed contract error and preserve redacted evidence.
Pagination repeats a page	Abort at the loop guard and record the endpoint strategy.
Tenant token does not match context	Reject before sending the request.

Examples

Input:

runtime=TypeScript; endpoints=record query and task create; tenancy=multi-workspace

Expected handoff:

client=typed REST wrapper; pagination=endpoint mapped; tenant-tests=pass

Resources

• Skill-specific official documentation
• OpenAPI specification
• Pagination
• App SDK overview