exa-sdk-patterns

name	exa-sdk-patterns
description	Apply production-ready exa-js SDK patterns with type safety, singletons, and wrappers. 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", "exa wrapper".
allowed-tools	Read, Write, Edit
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
compatible-with	claude-code, codex, openclaw
tags	["saas","exa","typescript","patterns"]

Exa SDK Patterns

Overview

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.

Prerequisites

• exa-js installed and EXA_API_KEY configured
• TypeScript project with strict mode
• Familiarity with async/await and error handling

Instructions

Step 1: Client Singleton

// 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;
}

Step 2: Typed Search Wrapper

// src/exa/search.ts
import Exa from "exa-js";
import { getExa } from "./client";

interface ExaSearchOptions {
  type?: "auto" |  |  |  |  |  | ;
  ?: ;
  ?: [];
  ?: [];
  ?: ;
  ?: ;
  ?:  |  |  |  |  |  | ;
  ?: [];
  ?: [];
}

  {
  ?:  | { ?: ; ?:  };
  ?:  | { ?: ; ?:  };
  ?:  | { ?:  };
  ?:  |  |  | ;
  ?: ;
  ?: ;
  ?:  | [];
}

   () {
   exa = ();
   exa.(query, {
    : opts. ?? ,
    : opts. ?? ,
    ...opts,
  });
}

   () {
   exa = ();
   exa.(query, {
    : searchOpts. ?? ,
    : searchOpts. ?? ,
    ...searchOpts,
    ...contentOpts,
  });
}