@checkleaked/trustpilot-api

Zero-dependency, fully typed TypeScript/JavaScript SDK for the CheckLeaked Trustpilot API on RapidAPI.

• Covers all 24 operations advertised by the RapidAPI MCP.
• Uses native fetch: Node 18+, Bun, Deno, edge runtimes, and modern browsers.
• Ships ESM, CommonJS, source maps, and TypeScript declarations.
• Built-in timeouts, cancellation, Retry-After-aware retries, and lifecycle hooks.
• Preserves each endpoint's real response shape instead of inventing one shared envelope.
• Includes downloadable MCP and OpenAPI request contracts.

Install

npm install @checkleaked/trustpilot-api

Quick start

import { createClient } from '@checkleaked/trustpilot-api';

const trustpilot = createClient({
  apiKey: process.env.RAPIDAPI_KEY!,
});

const result = await trustpilot.companies.search({
  query: 'google',
  page: 1,
  perPage: 10,
  sortBy: 'trustscore desc',
  country: 'US',
});

console.log(result.data.businessUnits);

The key can be omitted from createClient() when TRUSTPILOT_API_KEY, TRUSTPILOT_RAPIDAPI_KEY, or RAPIDAPI_KEY is set.

Common calls

// Full company profile
const profile = await trustpilot.companies.profile({
  domain: 'www.google.com',
  google: true,
});

// Reviews and review filtering
const page = await trustpilot.reviews.list({
  domain: 'www.google.com',
  page: 1,
});
const filtered = await trustpilot.reviews.filtered({
  domain: 'www.google.com',
  page: 1,
  stars: [1, 2],
  verified: true,
});

// Category discovery
const categories = await trustpilot.categories.all();
const electronics = await trustpilot.categories.companies({
  categoryId: 'electronics_technology',
  country: 'US',
  page: 1,
});

// Persisted dataset analytics
const stats = await trustpilot.insights.stats();
const companies = await trustpilot.insights.companies({
  q: 'amazon',
  country: 'US',
  hasEmail: true,
  minTrustScore: 3.5,
  page: 1,
  limit: 20,
});

// Sales leads
const leads = await trustpilot.leads.unclaimed({
  country: 'US',
  hasEmail: true,
  limit: 50,
});

API surface

Every method accepts optional trailing request controls: { signal, headers, timeoutMs, retries }.

| Namespace | Method | RapidAPI route | | ------------ | ----------------------------- | ---------------------------------------------------- | | reviews | list(params) | GET / | | reviews | filtered(params) | GET /trustpilot/feedbacks/filtered | | reviews | count(params) | GET /trustpilot/reviews/count | | companies | search(params) | GET /trustpilot/businessunits/search | | companies | profile(params) | GET /trustpilot/company/details | | companies | suggestions(params) | GET /trustpilot/suggestions | | companies | semanticSuggestions(params) | GET /trustpilot/businessunits/semantic-suggestions | | categories | search(params) | GET /trustpilot/categories/search | | categories | get(params) | GET /trustpilot/category/{categoryId} | | categories | companies(params) | GET /trustpilot/category/{categoryId}/companies | | categories | recent(params) | GET /trustpilot/category/{categoryId}/recent | | categories | newest(params) | GET /trustpilot/category/{categoryId}/newest | | categories | all(params?) | GET /trustpilot/categories/all | | consumers | reviews(params) | GET /trustpilot/consumer/{consumerId}/reviews | | insights | companies(params?) | GET /trustpilot/insights/companies | | insights | facets(params?) | GET /trustpilot/insights/companies/facets | | insights | stats() | GET /trustpilot/insights/stats | | insights | topCompanies(params?) | GET /trustpilot/insights/companies/top | | insights | recentlyUpdated(params?) | GET /trustpilot/insights/companies/recent | | leads | list(params?) | GET /trustpilot/data/leads | | leads | unclaimed(params?) | GET /trustpilot/data/leads/unclaimed | | leads | weakReply(params?) | GET /trustpilot/data/leads/weak-reply | | google | businessReviews(query) | GET /business/reviews | | health | check() | GET /trustpilot/health |

The MCP catalogue currently misspells the recently-updated limit query parameter as limi. The SDK intentionally sends the server's real limit parameter.

Response shapes

The API has several response families:

• New live routes generally return { data, statusCode, endpoint? }.
• reviews.list() returns the Trustpilot company/review page model directly.
• Insights and lead routes return native stats or pagination objects.
• health.check() returns the health report directly.

Methods therefore return the actual wire response. For example, companies.search() returns CompanySearchResponse, so results are under response.data.businessUnits; insights.stats() returns DatasetStatsResponse directly.

Errors, retries, and cancellation

All failures throw TrustpilotApiError.

import { TrustpilotApiError } from '@checkleaked/trustpilot-api';

try {
  await trustpilot.companies.profile({ domain: 'example.com' });
} catch (error) {
  if (error instanceof TrustpilotApiError) {
    console.error(error.status, error.code, error.body);
    console.error(error.isRateLimit, error.isTimeout, error.isServerError);
  }
}

HTTP 429, 5xx, timeouts, and network failures are retried by default. Retry-After is honored. Caller cancellation is never retried.

const controller = new AbortController();
const request = trustpilot.reviews.list(
  { domain: 'example.com', page: 1 },
  { signal: controller.signal, timeoutMs: 10_000, retries: 1 },
);
controller.abort();
await request;

Configuration

const trustpilot = createClient({
  apiKey: '...',
  baseUrl: 'https://trustpilot4.p.rapidapi.com',
  host: 'trustpilot4.p.rapidapi.com',
  timeoutMs: 30_000,
  retries: 2,
  retryDelayMs: 500,
  headers: { 'x-client-id': 'my-app' },
  fetch: globalThis.fetch,
  debug: true,
  onRequest: ({ method, url }) => console.log(method, url),
  onResponse: ({ status, durationMs }) => console.log(status, durationMs),
  onRetry: ({ attempt, delayMs }) => console.log(attempt, delayMs),
});

Request-hook headers redact API keys, authorization, and cookies.

For a direct compatible proxy, override baseUrl and set host: false.

MCP and OpenAPI docs

The RapidAPI MCP exposes complete request/tool schemas through tools/list, but currently does not publish response schemas. The RapidAPI proxy also returns 404 for common /openapi.json, /swagger.json, and /docs paths.

This package includes:

• mcp-tools.json: the downloaded MCP tool catalogue.
• openapi.json: an OpenAPI 3.1 request contract generated from that catalogue.
• Curated TypeScript response types based on live API responses and the server source contracts.

Refresh the docs without storing a key in the repository:

TRUSTPILOT_API_KEY=your_key npm run docs:mcp

PowerShell:

$env:TRUSTPILOT_API_KEY = 'your_key'
npm run docs:mcp
Remove-Item Env:TRUSTPILOT_API_KEY

The JSON documents are exported as @checkleaked/trustpilot-api/openapi.json and @checkleaked/trustpilot-api/mcp-tools.json.

Development

npm run docs:mcp
npm run typecheck
npm test
npm run build
npm pack --dry-run

Publishing

The first public release requires an npm account with permission to publish under the @checkleaked scope:

npm login
npm whoami
npm run prepublishOnly
npm publish --access public

After the first release, GitHub releases can publish automatically through .github/workflows/publish.yml. Add an npm automation token to the repository:

gh secret set NPM_TOKEN --repo eduair94/trustpilot-api-sdk

Then create a GitHub release whose tag matches the package version, such as v1.0.1. The workflow verifies that the tag and package.json version match, runs the complete prepublish checks, and publishes with npm provenance.

License

MIT © Eduardo Airaudo