Apply production-ready Clay SDK patterns for TypeScript and Python. Use when implementing Clay integrations, refactoring SDK usage, or establishing team coding standards for Clay. Trigger with phrases like "clay SDK patterns", "clay best practices", "clay code patterns", "idiomatic clay".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill clay-sdk-patternsLoading…
Production-ready patterns for Clay integrations. Clay does not have an official SDK -- you interact via webhooks (inbound), HTTP API enrichment columns (outbound from Clay), and the Enterprise API (programmatic lookups). These patterns wrap those interfaces into reliable, reusable code.
clay-install-auth setup// src/clay/client.ts — typed wrapper for Clay webhook and Enterprise API
interface ClayConfig {
webhookUrl: string; // Table's webhook URL for inbound data
enterpriseApiKey?: string; // Enterprise API key (optional)
baseUrl?: string; // Default: https://api.clay.com
maxRetries?: number;
timeoutMs?: number;
}
class ClayClient {
private config: Required<ClayConfig>;
constructor(config: ClayConfig) {
this.config = {
baseUrl: 'https://api.clay.com',
maxRetries: 3,
timeoutMs: 30_000,
enterpriseApiKey: '',
...config,
};
}
/** Send a record to a Clay table via webhook */
async sendToTable(data: Record<string, unknown>): Promise<void> {
const res = await this.fetchWithRetry(this.config.webhookUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
if (!res.ok) {
throw new ClayWebhookError(`Webhook failed: ${res.status}`, res.status);
}
}
/** Send multiple records in sequence with rate limiting */
async sendBatch(rows: Record<string, unknown>[], delayMs = 200): Promise<BatchResult> {
const results: BatchResult = { sent: 0, failed: 0, errors: [] };
for (const row of rows) {
try {
await this.sendToTable(row);
results.sent++;
} catch (err) {
results.failed++;
results.errors.push({ row, error: (err as Error).message });
}
if (delayMs > 0) await new Promise(r => setTimeout(r, delayMs));
}
return results;
}
/** Enterprise API: Enrich a person by email (Enterprise plan only) */
async enrichPerson(email: string): Promise<PersonEnrichment> {
if (!this.config.enterpriseApiKey) {
throw new Error('Enterprise API key required for person enrichment');
}
const res = await this.fetchWithRetry(`${this.config.baseUrl}/v1/people/enrich`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.config.enterpriseApiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ email }),
});
return res.json();
}
/** Enterprise API: Enrich a company by domain (Enterprise plan only) */
async enrichCompany(domain: string): Promise<CompanyEnrichment> {
if (!this.config.enterpriseApiKey) {
throw new Error('Enterprise API key required for company enrichment');
}
const res = await this.fetchWithRetry(`${this.config.baseUrl}/v1/companies/enrich`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.config.enterpriseApiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ domain }),
});
return res.json();
}
private async fetchWithRetry(url: string, init: RequestInit): Promise<Response> {
for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
try {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
const res = await fetch(url, { ...init, signal: controller.signal });
clearTimeout(timeout);
if (res.status === 429) {
const retryAfter = parseInt(res.headers.get('Retry-After') || '5');
await new Promise(r => setTimeout(r, retryAfter * 1000));
continue;
}
return res;
} catch (err) {
if (attempt === this.config.maxRetries) throw err;
await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
}
}
throw new Error('Max retries exceeded');
}
}
// src/clay/types.ts
interface PersonEnrichment {
name?: string;
email?: string;
title?: string;
company?: string;
linkedin_url?: string;
location?: string;
}
interface CompanyEnrichment {
name?: string;
domain?: string;
industry?: string;
employee_count?: number;
linkedin_url?: string;
location?: string;
description?: string;
}
interface BatchResult {
sent: number;
failed: number;
errors: Array<{ row: Record<string, unknown>; error: string }>;
}
class ClayWebhookError extends Error {
constructor(message: string, public statusCode: number) {
super(message);
this.name = 'ClayWebhookError';
}
}
# clay_client.py — Python wrapper for Clay webhook and Enterprise API
import httpx
import asyncio
from dataclasses import dataclass, field
from typing import Any
@dataclass
class ClayClient:
webhook_url: str
enterprise_api_key: str = ""
base_url: str = "https://api.clay.com"
max_retries: int = 3
timeout: float = 30.0
async def send_to_table(self, data: dict[str, Any]) -> None:
"""Send a single record to a Clay table via webhook."""
async with httpx.AsyncClient(timeout=self.timeout) as client:
for attempt in range(self.max_retries + 1):
response = await client.post(
self.webhook_url,
json=data,
headers={"Content-Type": "application/json"},
)
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", "5"))
await asyncio.sleep(retry_after)
continue
response.raise_for_status()
return
raise Exception("Max retries exceeded")
async def send_batch(self, rows: list[dict], delay: float = 0.2) -> dict:
"""Send multiple records with rate limiting."""
results = {"sent": 0, "failed": 0, "errors": []}
for row in rows:
try:
await self.send_to_table(row)
results["sent"] += 1
except Exception as e:
results["failed"] += 1
results["errors"].append({"row": row, "error": str(e)})
await asyncio.sleep(delay)
return results
async def enrich_person(self, email: str) -> dict:
"""Enterprise API: Look up person data by email."""
async with httpx.AsyncClient(timeout=self.timeout) as client:
response = await client.post(
f"{self.base_url}/v1/people/enrich",
json={"email": email},
headers={"Authorization": f"Bearer {self.enterprise_api_key}"},
)
response.raise_for_status()
return response.json()
// src/clay/instance.ts — reuse a single client across your app
let instance: ClayClient | null = null;
export function getClayClient(): ClayClient {
if (!instance) {
instance = new ClayClient({
webhookUrl: process.env.CLAY_WEBHOOK_URL!,
enterpriseApiKey: process.env.CLAY_API_KEY,
});
}
return instance;
}
| Pattern | Use Case | Benefit |
|---|---|---|
| Retry with backoff | 429 rate limits, network errors | Automatic recovery |
| Batch with delay | Sending many rows | Respects Clay rate limits |
| Enterprise API guard | Missing API key | Clear error before API call |
| Timeout control | Slow webhook delivery | Prevents hung connections |
// Express handler for Clay HTTP API column callbacks
app.post('/api/clay/callback', (req, res) => {
// Respond 200 immediately (Clay expects fast response)
res.json({ ok: true });
// Process async
processEnrichedData(req.body).catch(console.error);
});
Apply patterns in clay-core-workflow-a for real-world lead enrichment.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).