Official JavaScript/TypeScript SDK for the Quercle API - AI-powered web search and fetching
npm install @quercle/sdkOfficial JavaScript/TypeScript SDK for the Quercle API - AI-powered web search and URL fetching.
``bash`
npm install @quercle/sdkor
bun add @quercle/sdkor
yarn add @quercle/sdk
`typescript
import { QuercleClient } from "@quercle/sdk";
// Create a client (uses QUERCLE_API_KEY env var by default)
const client = new QuercleClient();
// Or provide API key directly
const client = new QuercleClient({ apiKey: "qk_..." });
// Fetch and analyze a URL
const result = await client.fetch(
"https://example.com/article",
"Summarize the main points in bullet points"
);
console.log(result);
// Search the web
const answer = await client.search("What is TypeScript?");
console.log(answer);
`
`typescript
const client = new QuercleClient({
// API key (falls back to QUERCLE_API_KEY env var)
apiKey: "qk_...",
// Request timeout in ms (optional, defaults to 120000)
timeout: 120000,
});
`
`typescript
import { createClient } from "@quercle/sdk";
// Uses QUERCLE_API_KEY environment variable
const client = createClient();
const result = await client.fetch("https://example.com", "Extract the title");
`
Fetch a web page and analyze its content using AI.
Parameters:
- url (string): The URL to fetch and analyzeprompt
- (string): Instructions for how to analyze the page content
Returns: Promise - AI-processed analysis of the page content
`typescript`
const summary = await client.fetch(
"https://example.com/article",
"Summarize this article in 3 bullet points"
);
Search the web and get AI-synthesized answers with citations.
Parameters:
- query (string): The search queryoptions
- (optional):allowedDomains
- (string[]): Only include results from these domains (supports wildcards)blockedDomains
- (string[]): Exclude results from these domains (supports wildcards)
Returns: Promise - AI-synthesized answer with source citations
`typescript
// Basic search
const answer = await client.search("What is TypeScript?");
// Search with domain filtering
const filtered = await client.search("Python best practices", {
allowedDomains: [".edu", ".gov"],
blockedDomains: ["*.example.org"],
});
`
The SDK throws specific error types for different failure modes:
`typescript
import {
QuercleClient,
QuercleError,
AuthenticationError,
InsufficientCreditsError,
TimeoutError,
} from "@quercle/sdk";
const client = new QuercleClient({ apiKey: "qk_..." });
try {
const result = await client.search("query");
} catch (error) {
if (error instanceof AuthenticationError) {
// Invalid or missing API key (401)
console.error("Authentication failed:", error.message);
} else if (error instanceof InsufficientCreditsError) {
// Account has no credits (402)
console.error("Out of credits:", error.message);
} else if (error instanceof TimeoutError) {
// Request timed out (504)
console.error("Request timed out:", error.message);
} else if (error instanceof QuercleError) {
// Other API errors
console.error(API error (${error.statusCode}):, error.message);`
}
}
| Error Class | Status Code | Description |
|-------------|-------------|-------------|
| AuthenticationError | 401 | Invalid or missing API key |InsufficientCreditsError
| | 402 | Account has insufficient credits |TimeoutError
| | 504 | Request timed out |QuercleError
| | Various | Base error class for all SDK errors |
All errors include:
- message: Human-readable error messagestatusCode
- : HTTP status codedetail
- : Additional error details from the API (if available)
The SDK exports tool definitions and Zod schemas for easy integration with AI frameworks like Vercel AI SDK, LangChain, etc.
`typescript`
import {
QuercleClient,
// Tool descriptions
TOOL_DESCRIPTIONS,
FIELD_DESCRIPTIONS,
// Zod schemas
searchToolSchema,
fetchToolSchema,
// Complete tool definitions
searchToolDefinition,
fetchToolDefinition,
} from "@quercle/sdk";
`typescript
import { tool } from "ai";
import { QuercleClient, TOOL_DESCRIPTIONS, searchToolSchema } from "@quercle/sdk";
const client = new QuercleClient();
const searchTool = tool({
description: TOOL_DESCRIPTIONS.SEARCH,
parameters: searchToolSchema,
execute: async ({ query, allowed_domains, blocked_domains }) => {
return client.search(query, {
allowedDomains: allowed_domains,
blockedDomains: blocked_domains,
});
},
});
`
| Export | Description |
|--------|-------------|
| TOOL_DESCRIPTIONS.SEARCH | Description for the search tool |TOOL_DESCRIPTIONS.FETCH
| | Description for the fetch tool |FIELD_DESCRIPTIONS.*
| | Descriptions for individual fields |searchToolSchema
| | Zod schema for search parameters |fetchToolSchema
| | Zod schema for fetch parameters |searchToolDefinition
| | Complete tool definition (name, description, schema) |fetchToolDefinition
| | Complete tool definition (name, description, schema) |
The SDK is written in TypeScript and exports all types:
`typescript``
import type {
QuercleConfig,
SearchOptions,
FetchResponse,
SearchResponse,
} from "@quercle/sdk";
- Node.js 18+
- TypeScript 5+ (if using TypeScript)
MIT