Apply production-ready Exa SDK patterns for TypeScript and Python. Use when implementing Exa integrations, refactoring SDK usage, or establishing team coding standards for Exa. Trigger with phrases like "exa SDK patterns", "exa best practices", "exa code patterns", "idiomatic exa".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill exa-sdk-patternsLoading…
Production-ready patterns for the exa-js SDK. Covers client singletons, typed wrappers, error handling, retry logic, and response validation for real Exa API methods.
exa-js installed and EXA_API_KEY configured// src/exa/client.ts
import Exa from "exa-js";
let instance: Exa | null = null;
export function getExa(): Exa {
if (!instance) {
const apiKey = process.env.EXA_API_KEY;
if (!apiKey) {
throw new Error("EXA_API_KEY not set. Get one at https://dashboard.exa.ai");
}
instance = new Exa(apiKey);
}
return instance;
}
// src/exa/search.ts
import Exa from "exa-js";
import { getExa } from "./client";
interface ExaSearchOptions {
type?: "auto" | "neural" | "keyword" | "fast" | "instant" | "deep" | "deep-reasoning";
numResults?: number;
includeDomains?: string[];
excludeDomains?: string[];
startPublishedDate?: string;
endPublishedDate?: string;
category?: "company" | "research paper" | "news" | "tweet" | "personal site" | "financial report" | "people";
includeText?: string[];
excludeText?: string[];
}
interface ExaContentsOptions {
text?: boolean | { maxCharacters?: number; includeHtmlTags?: boolean };
highlights?: boolean | { maxCharacters?: number; query?: string };
summary?: boolean | { query?: string };
livecrawl?: "always" | "preferred" | "fallback" | "never";
livecrawlTimeout?: number;
subpages?: number;
subpageTarget?: string | string[];
}
export async function exaSearch(query: string, opts: ExaSearchOptions = {}) {
const exa = getExa();
return exa.search(query, {
type: opts.type ?? "auto",
numResults: opts.numResults ?? 10,
...opts,
});
}
export async function exaSearchWithContents(
query: string,
searchOpts: ExaSearchOptions = {},
contentOpts: ExaContentsOptions = {}
) {
const exa = getExa();
return exa.searchAndContents(query, {
type: searchOpts.type ?? "auto",
numResults: searchOpts.numResults ?? 10,
...searchOpts,
...contentOpts,
});
}
// src/exa/safe.ts
interface ExaResult<T> {
data: T | null;
error: ExaError | null;
}
interface ExaError {
status: number;
message: string;
tag?: string;
requestId?: string;
retryable: boolean;
}
function classifyError(err: any): ExaError {
const status = err.status || err.response?.status || 500;
const retryable = status === 429 || status >= 500;
return {
status,
message: err.message || "Unknown error",
tag: err.error_tag || err.tag,
requestId: err.requestId || err.request_id,
retryable,
};
}
export async function safeExaCall<T>(
operation: () => Promise<T>
): Promise<ExaResult<T>> {
try {
const data = await operation();
return { data, error: null };
} catch (err: any) {
const error = classifyError(err);
console.error(`[Exa Error] ${error.status}: ${error.message}`, {
tag: error.tag,
requestId: error.requestId,
retryable: error.retryable,
});
return { data: null, error };
}
}
// Usage:
// const { data, error } = await safeExaCall(() =>
// exa.searchAndContents("query", { numResults: 5, text: true })
// );
// src/exa/retry.ts
export async function withRetry<T>(
operation: () => Promise<T>,
config = { maxRetries: 3, baseDelayMs: 1000, maxDelayMs: 30000 }
): Promise<T> {
for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
try {
return await operation();
} catch (err: any) {
const status = err.status || err.response?.status || 0;
// Only retry on rate limits (429) and server errors (5xx)
if (status !== 429 && (status < 500 || status >= 600)) throw err;
if (attempt === config.maxRetries) throw err;
const delay = Math.min(
config.baseDelayMs * Math.pow(2, attempt) + Math.random() * 500,
config.maxDelayMs
);
console.log(`[Exa] Retry ${attempt + 1}/${config.maxRetries} in ${delay.toFixed(0)}ms`);
await new Promise(r => setTimeout(r, delay));
}
}
throw new Error("Unreachable");
}
// Usage:
// const results = await withRetry(() =>
// exa.searchAndContents("query", { numResults: 5, text: true })
// );
// src/exa/validate.ts
import { z } from "zod";
const ExaResultSchema = z.object({
url: z.string().url(),
title: z.string().nullable(),
score: z.number(),
publishedDate: z.string().nullable().optional(),
text: z.string().optional(),
highlights: z.array(z.string()).optional(),
summary: z.string().optional(),
});
const ExaSearchResponseSchema = z.object({
results: z.array(ExaResultSchema),
autopromptString: z.string().optional(),
});
export function validateSearchResponse(response: unknown) {
return ExaSearchResponseSchema.parse(response);
}
| Pattern | Use Case | Benefit |
|---|---|---|
| Singleton | All API calls | Single client instance, consistent config |
| Safe wrapper | Non-critical searches | Prevents uncaught exceptions |
| Retry logic | Rate limits and 5xx | Automatic recovery from transient failures |
| Zod validation | Response processing | Catches unexpected API response changes |
| Typed options | IDE support | Autocomplete and compile-time checks |
const clients = new Map<string, Exa>();
export function getExaForTenant(tenantId: string): Exa {
if (!clients.has(tenantId)) {
const apiKey = getTenantApiKey(tenantId); // from your config/vault
clients.set(tenantId, new Exa(apiKey));
}
return clients.get(tenantId)!;
}
async function resilientSearch(query: string) {
return safeExaCall(() =>
withRetry(() =>
exaSearchWithContents(
query,
{ type: "neural", numResults: 5 },
{ text: { maxCharacters: 2000 }, highlights: true }
)
)
);
}
Apply patterns in exa-core-workflow-a for real-world search usage.
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).