AGENT SKILL

attio-sdk-patterns

Production-ready patterns for the Attio REST API: typed client, retry with backoff, pagination iterators, and multi-tenant factory. Trigger: "attio SDK patterns", "attio best practices", "attio client wrapper", "idiomatic attio", "attio TypeScript patterns".

License 许可
MIT
最近更新
2026-07-13
Stars
★ 1
Forks
0

01 前言 Front Matter

name
attio-sdk-patterns
tags
[ "saas", "crm", "attio" ]
author
Jeremy Longshore <jeremy@intentsolutions.io>
license
MIT
version
1.0.0
description
Production-ready patterns for the Attio REST API: typed client, retry with backoff, pagination iterators, and multi-tenant factory. Trigger: "attio SDK patterns", "attio best practices", "attio client wrapper", "idiomatic attio", "attio TypeScript patterns".
allowed-tools
Read, Write, Edit
compatible-with
claude-code

03 SKILL.md 正文

Attio SDK Patterns

Overview

There is no official Attio Node.js SDK. The API is a clean REST/JSON interface at https://api.attio.com/v2. These patterns wrap fetch into a production-grade typed client with retry, pagination, and error normalization.

Prerequisites

  • Node.js 18+ (native fetch)
  • TypeScript 5+
  • Completed attio-install-auth

Instructions

Pattern 1: Typed Client with Error Normalization

// src/attio/client.ts
const ATTIO_BASE = "https://api.attio.com/v2";

export class AttioApiError extends Error {
  constructor(
    public statusCode: number,
    public type: string,
    public code: string,
    message: string
  ) {
    super(message);
    this.name = "AttioApiError";
  }

  get retryable(): boolean {
    return this.statusCode === 429 || this.statusCode >= 500;
  }
}

export class AttioClient {
  constructor(private apiKey: string) {}

  async request<T>(
    method: string,
    path: string,
    body?: Record<string, unknown>
  ): Promise<T> {
    const res = await fetch(`${ATTIO_BASE}${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        "Content-Type": "application/json",
      },
      body: body ? JSON.stringify(body) : undefined,
    });

    if (!res.ok) {
      const err = await res.json().catch(() => ({}));
      throw new AttioApiError(
        res.status,
        err.type || "unknown",
        err.code || "unknown",
        err.message || `HTTP ${res.status}`
      );
    }

    return res.json() as Promise<T>;
  }

  // Convenience methods for common HTTP verbs
  get<T>(path: string) { return this.request<T>("GET", path); }
  post<T>(path: string, body: Record<string, unknown>) { return this.request<T>("POST", path, body); }
  patch<T>(path: string, body: Record<string, unknown>) { return this.request<T>("PATCH", path, body); }
  put<T>(path: string, body: Record<string, unknown>) { return this.request<T>("PUT", path, body); }
  delete<T>(path: string) { return this.request<T>("DELETE", path); }
}

Pattern 2: Retry with Exponential Backoff

// src/attio/retry.ts
export async function withRetry<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 4, baseMs: 1000, maxMs: 30000 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (attempt === config.maxRetries) throw err;

      // Only retry on rate limits (429) and server errors (5xx)
      if (err instanceof AttioApiError && !err.retryable) throw err;

      const delay = Math.min(
        config.baseMs * Math.pow(2, attempt) + Math.random() * 500,
        config.maxMs
      );
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw new Error("Unreachable");
}

// Usage
const people = await withRetry(() =>
  client.post("/objects/people/records/query", { limit: 50 })
);

Pattern 3: Cursor-Based Pagination Iterator

Attio uses cursor-based pagination. The initial request omits offset; responses include pagination.next_cursor.

// src/attio/paginate.ts
export async function* paginate<T>(
  client: AttioClient,
  path: string,
  body: Record<string, unknown> = {},
  pageSize = 100
): AsyncGenerator<T> {
  let offset = 0;
  let hasMore = true;

  while (hasMore) {
    const res = await withRetry(() =>
      client.post<{ data: T[] }>(path, {
        ...body,
        limit: pageSize,
        offset,
      })
    );

    for (const item of res.data) {
      yield item;
    }

    hasMore = res.data.length === pageSize;
    offset += pageSize;
  }
}

// Usage: iterate all companies
for await (const company of paginate(client, "/objects/companies/records/query")) {
  console.log(company);
}

Pattern 4: Singleton with Lazy Init

// src/attio/singleton.ts
let _client: AttioClient | null = null;

export function getClient(): AttioClient {
  if (!_client) {
    const key = process.env.ATTIO_API_KEY;
    if (!key) throw new Error("ATTIO_API_KEY not set");
    _client = new AttioClient(key);
  }
  return _client;
}

Pattern 5: Multi-Tenant Factory

// src/attio/factory.ts
const tenantClients = new Map<string, AttioClient>();

export function getClientForTenant(tenantId: string): AttioClient {
  if (!tenantClients.has(tenantId)) {
    const key = getTenantApiKey(tenantId); // from DB or secrets manager
    tenantClients.set(tenantId, new AttioClient(key));
  }
  return tenantClients.get(tenantId)!;
}

Pattern 6: Response Validation with Zod

import { z } from "zod";

const AttioPersonSchema = z.object({
  id: z.object({
    object_id: z.string(),
    record_id: z.string(),
  }),
  created_at: z.string(),
  values: z.object({
    name: z.array(z.object({
      first_name: z.string().nullable(),
      last_name: z.string().nullable(),
      full_name: z.string().nullable(),
    })),
    email_addresses: z.array(z.object({
      email_address: z.string(),
    })),
  }).passthrough(),
});

// Validated fetch
const raw = await client.post("/objects/people/records/query", { limit: 1 });
const person = AttioPersonSchema.parse(raw.data[0]);

Error Handling

Pattern When to Use Benefit
AttioApiError class All API calls Typed error with retryable flag
withRetry wrapper Any mutating or critical read Auto-retry on 429/5xx
Zod validation Parsing API responses Catches schema drift at runtime
Multi-tenant factory SaaS with per-customer tokens Isolates credentials

Resources

Next Steps

Apply these patterns in attio-core-workflow-a (records CRUD) and attio-core-workflow-b (lists and entries).

04 同仓库更多 Skills

jukeyman
jukeyman/jukeyman-skills

zustand-store-creator

Create zustand store creator operations. Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like "zustand store creator", "zustand creator", "zustand".

★ 1
jukeyman
jukeyman/jukeyman-skills

zero-trust-config-helper

Configure with zero trust config helper operations. Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like "zero trust config helper", "zero helper", "zero".

★ 1
jukeyman
jukeyman/jukeyman-skills

zapier-integration-helper

Assist with zapier integration helper operations. Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like "zapier integration helper", "zapier helper", "zapier".

★ 1
jukeyman
jukeyman/jukeyman-skills

yaml-config-validator

Validate yaml config validator operations. Auto-activating skill for DevOps Basics. Triggers on: yaml config validator, yaml config validator Part of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like "yaml config validator", "yaml validator", "yaml".

★ 1
jukeyman
jukeyman/jukeyman-skills

xvary-stock-research

Thesis-driven equity analysis from public SEC EDGAR and market data; /analyze, /score, /compare workflows with bundled Python tools (Claude Code, Cursor, Codex).

★ 1
jukeyman
jukeyman/jukeyman-skills

xss-vulnerability-scanner

Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals. Triggers on: xss vulnerability scanner, xss vulnerability scanner Part of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like "xss vulnerability scanner", "xss scanner", "xss".

★ 1