TrustRails TypeScript SDK

Official TypeScript/JavaScript client library for the TrustRails API.

Installation

npm install @trustrails/sdk

Quick Start

import TrustRails from '@trustrails/sdk';

// Initialize the SDK (baseUrl defaults to production)
const trustrails = new TrustRails('your-api-key');

// Search for products with filters
const results = await trustrails.search({
  brand: 'HP',
  category: 'Laptops',
  minPrice: 400,
  maxPrice: 600,
});

console.log(`Found ${results.total} products`);
results.products.forEach(product => {
  console.log(`${product.title} - £${product.price}`);
});

// Get a specific product
const product = await trustrails.product('product-id');
console.log(product);

API Reference

TrustRails

Constructor

new TrustRails(apiKey: string)

Or use a config object for custom baseUrl:

new TrustRails({ apiKey: string, baseUrl?: string })

Parameters:

• apiKey - Your TrustRails API key
• baseUrl (optional) - Custom base URL (defaults to https://trustrails.app)

Methods

search(options?: SearchOptions): Promise<SearchResponse>

Search for products. Returns summary data (title, price, availability, category). For full technical specs, call product(id) with the product ID.

Parameters:

• options.query?: string - Refinement terms after brand and category are extracted: model lines, series, variants, technology descriptors, or model numbers (e.g. 'neo', 'ultra', 'oled', 'WH-1000XM5'). Omit entirely if brand + category fully describe what you want. Never put brand names, product family names, or prices here — use filters.
• options.brand?: string - Filter by brand name (e.g., 'Sony', 'HP', 'Anker')
• options.category?: string - Filter by product category (e.g., 'Laptops', 'Headphones')
• options.minPrice?: number - Minimum price filter in GBP
• options.maxPrice?: number - Maximum price filter in GBP
• options.lite?: boolean - Return trimmed product objects with only essential fields including offer_count (reduces payload by ~80%)
• options.limit?: number - Maximum number of results (default: 50, max: 100)
• options.sort?: string - Sort order: 'relevance' (default), 'price_asc' (cheapest first), 'price_desc' (most expensive first)

Returns: Promise resolving to SearchResponse containing products array and total count.

Example — brand + category only (query omitted):

const results = await trustrails.search({
  brand: 'HP',
  category: 'Laptops',
  minPrice: 400,
  maxPrice: 1000,
  sort: 'price_asc'
});

Example — with model line in query:

// 'neo', 'ultra', 'oled' etc. go in query — they refine within brand/category
const results = await trustrails.search({
  brand: 'Samsung',
  category: 'TVs',
  query: 'qled',
});

Lite mode (faster responses, smaller payloads):

const results = await trustrails.search({
  brand: 'Anker',
  category: 'Cables & Chargers',
  lite: true  // Returns only: id, title, brand, price, availability, image_url, purchase_url
});

product(id: string): Promise<Product>

Get full details for a single product. Returns complete technical specifications including specs.description (full prose spec text with processor, RAM, storage, display, etc.), stock level, delivery time, and all retailer offers with per-retailer pricing. Accepts canonical product IDs or original retailer offer IDs. Use this after search() to get detailed specs for comparison or recommendations.

Parameters:

• id: string - The product ID

Returns: Promise resolving to Product object with all fields populated

Example:

const product = await trustrails.product('prod_123');

Types

Product

interface Product {
  id: string;
  ean?: string;
  title: string;
  brand?: string;
  price: number;
  currency: string;
  availability: "in_stock" | "low_stock" | "out_of_stock";
  stock: number;
  delivery_time: string;
  image_url?: string;
  category: string;
  product_type: "product" | "accessory";
  specs: {
    description?: string;  // Full prose spec text — always check this for technical details
    model_number?: string;
    dimensions?: string;
  };
  provenance: {
    source: string;
    last_updated: string;
  };
  purchase_url: string;
  offer_count?: number;  // number of retailer offers (when >1, call product() to compare prices)
  offers?: Offer[];      // per-retailer offers sorted by price (returned by product())
}

interface Offer {
  id: string;
  source: string;
  title: string;
  price: number;
  currency: string;
  availability: "in_stock" | "low_stock" | "out_of_stock";
  stock: number;
  delivery_time: string;
  purchase_url: string;
  image_url?: string;
  last_updated: string;
}

SearchOptions

interface SearchOptions {
  query?: string;
  brand?: string;
  category?: string;
  minPrice?: number;
  maxPrice?: number;
  lite?: boolean;
  limit?: number;
  sort?: 'relevance' | 'price_asc' | 'price_desc';
}

SearchResponse

interface SearchResponse {
  products: Product[];
  total: number;
}

Error Handling

The SDK throws TrustRailsError for API-related errors:

import TrustRails, { TrustRailsError } from '@trustrails/sdk';

const trustrails = new TrustRails('your-api-key');

try {
  const product = await trustrails.product('invalid-id');
} catch (error) {
  if (error instanceof TrustRailsError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status Code: ${error.statusCode}`);
  }
}

License

MIT