Context7 Platform -- Up-to-date docs for AI agents
import type {
Context7Config,
GetContextOptions,
SearchLibraryOptions,
SearchOptions,
Library,
Documentation,
SearchResponse,
} from "@commands/types";
import { Context7Error } from "@error";
import { HttpClient } from "@http";
import type { AuthTokenProvider } from "@http";
import { SearchLibraryCommand, GetContextCommand, SearchCommand } from "@commands/index";
const DEFAULT_BASE_URL = "https://context7.com/api";
const API_KEY_PREFIX = "ctx7sk";
type Credential =
{ kind: "apiKey"; value: string } | { kind: "authToken"; value: string | AuthTokenProvider };
export type * from "@commands/types";
export type {
AuthTokenProvider,
CacheSetting,
Context7Fetch,
Context7ResponseMetadata,
RateLimitMetadata,
RetryConfig,
} from "@http";
export * from "@error";
export class Context7 {
private readonly httpClient: HttpClient;
constructor(config: Context7Config = {}) {
const credential = resolveCredential(config);
if (credential.kind === "apiKey" && !credential.value.startsWith(API_KEY_PREFIX)) {
console.warn(`API key should start with '${API_KEY_PREFIX}'`);
}
this.httpClient = new HttpClient({
baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
headers: {
...withoutAuthorizationHeader(config.headers),
},
authToken: credential.value,
retry: config.retry,
cache: config.cache ?? "no-store",
timeout: config.timeout,
signal: config.signal,
keepAlive: config.keepAlive,
fetch: config.fetch,
onResponse: config.onResponse,
});
}
/**
* Search for libraries matching the given query as JSON (array of Library objects)
*/
async searchLibrary(
query: string,
libraryName: string,
options?: SearchLibraryOptions & { type?: "json" }
): Promise<Library[]>;
/**
* Search for libraries matching the given query as plain text
*/
async searchLibrary(
query: string,
libraryName: string,
options: SearchLibraryOptions & { type: "txt" }
): Promise<string>;
/**
* Search for libraries with options whose response type is determined at runtime
*/
async searchLibrary(
query: string,
libraryName: string,
options?: SearchLibraryOptions
): Promise<Library[] | string>;
/**
* Search for libraries matching the given query
* @param query The user's question or task (used for relevance ranking)
* @param libraryName The library name to search for
* @param options Response format options
* @returns Array of matching libraries (json) or formatted text (txt)
*/
async searchLibrary(
query: string,
libraryName: string,
options?: SearchLibraryOptions
): Promise<Library[] | string> {
const command = new SearchLibraryCommand(query, libraryName, options);
return command.exec(this.httpClient);
}
/**
* Get documentation context for a library as JSON (array of documentation snippets)
*/
async getContext(
query: string,
libraryId: string,
options?: GetContextOptions & { type?: "json" }
): Promise<Documentation[]>;
/**
* Get documentation context for a library as plain text
*/
async getContext(
query: string,
libraryId: string,
options: GetContextOptions & { type: "txt" }
): Promise<string>;
/**
* Get documentation context with options whose response type is determined at runtime
*/
async getContext(
query: string,
libraryId: string,
options?: GetContextOptions
): Promise<Documentation[] | string>;
/**
* Get documentation context for a library
* @param query The user's question or task
* @param libraryId Context7 library ID (e.g., "/react/react")
* @param options Response format options
* @returns Documentation as Documentation[] (json, default) or string (txt)
*/
async getContext(
query: string,
libraryId: string,
options?: GetContextOptions
): Promise<Documentation[] | string> {
const command = new GetContextCommand(query, libraryId, options);
return command.exec(this.httpClient);
}
/**
* Search documentation as structured snippets
*/
async search(query: string, options?: SearchOptions & { type?: "json" }): Promise<SearchResponse>;
/**
* Search documentation as plain text
*/
async search(query: string, options: SearchOptions & { type: "txt" }): Promise<string>;
/**
* Search documentation with options whose response type is determined at runtime
*/
async search(query: string, options?: SearchOptions): Promise<SearchResponse | string>;
/**
* Search documentation without resolving a library first
* @param query The user's question or task
* @param options Library, version, language, response format, and request options
* @returns SearchResponse by default, or formatted text when type is "txt"
* @throws Context7Error with status 404 when no documentation matches
*/
async search(query: string, options?: SearchOptions): Promise<SearchResponse | string> {
const command = new SearchCommand(query, options);
return command.exec(this.httpClient);
}
}
function resolveCredential(config: Context7Config): Credential {
if (config.apiKey) return { kind: "apiKey", value: config.apiKey };
if (config.authToken) return { kind: "authToken", value: config.authToken };
const environmentApiKey = getEnvironmentApiKey();
if (environmentApiKey) return { kind: "apiKey", value: environmentApiKey };
throw new Context7Error(
"Authentication is required. Pass apiKey or authToken, or set CONTEXT7_API_KEY."
);
}
function getEnvironmentApiKey(): string | undefined {
return typeof process === "undefined" ? undefined : process.env?.CONTEXT7_API_KEY;
}
function withoutAuthorizationHeader(headers?: Record<string, string>): Record<string, string> {
return Object.fromEntries(
Object.entries(headers ?? {}).filter(([name]) => name.toLowerCase() !== "authorization")
);
}