@trustrails/sdk 0.4.6 → 0.4.9

package/README.md

@@ -18,11 +18,10 @@ const trustrails = new TrustRails('your-api-key');
 
 // Search for products with filters
 const results = await trustrails.search({
-  query: 'laptop',
   brand: 'HP',
+  category: 'Laptops',
   minPrice: 400,
   maxPrice: 600,
-  category: 'Laptops'
 });
 
 console.log(`Found ${results.total} products`);
@@ -62,41 +61,50 @@ new TrustRails({ apiKey: string, baseUrl?: string })
 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` - Search query string (searches title, brand, category)
+- `options.query?: string` - Refinement terms after brand and category are extracted: model lines, series names, variants, or model numbers (e.g. `'neo'`, `'ultra'`, `'oled'`, `'WH-1000XM5'`). Omit entirely if brand + category fully describe what you want. Never put brand 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 (reduces payload by ~80%)
+- `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:**
+**Example — brand + category only (query omitted):**
 ```typescript
 const results = await trustrails.search({
-  query: 'laptop',
   brand: 'HP',
+  category: 'Laptops',
   minPrice: 400,
   maxPrice: 1000,
-  category: 'Laptops',
   sort: 'price_asc'
 });
 ```
 
+**Example — with model line in query:**
+```typescript
+// '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):**
 ```typescript
 const results = await trustrails.search({
-  query: 'wireless mouse',
-  maxPrice: 50,
+  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, full description, stock level, delivery time, and retailer source. Use this after `search()` to get detailed specs for comparison or recommendations.
+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
@@ -115,8 +123,8 @@ const product = await trustrails.product('prod_123');
 ```typescript
 interface Product {
   id: string;
+  ean?: string;
   title: string;
-  description?: string;
   brand?: string;
   price: number;
   currency: string;
@@ -127,13 +135,31 @@ interface Product {
   category: string;
   product_type: "product" | "accessory";
   specs: {
-    [key: string]: any;
+    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;
 }
 ```
 

package/dist/index.d.mts

@@ -2,13 +2,29 @@
  * Product availability status
  */
 type Availability = "in_stock" | "low_stock" | "out_of_stock";
+/**
+ * Per-retailer offer for a product
+ */
+interface Offer {
+    id: string;
+    source: string;
+    title: string;
+    price: number;
+    currency: string;
+    availability: Availability;
+    stock: number;
+    delivery_time: string;
+    purchase_url: string;
+    image_url?: string;
+    last_updated: string;
+}
 /**
  * Product information returned by TrustRails API
  */
 interface Product {
     id: string;
+    ean?: string;
     title: string;
-    description?: string;
     brand?: string;
     price: number;
     currency: string;
@@ -19,16 +35,19 @@ interface Product {
     category: string;
     product_type: 'product' | 'accessory';
     specs: {
-        raw_category?: string;
+        description?: string;
         model_number?: string;
         dimensions?: string;
-        [key: string]: any;
     };
     provenance: {
         source: string;
         last_updated: string;
     };
     purchase_url: string;
+    /** Number of retailer offers available for this product */
+    offer_count?: number;
+    /** Per-retailer offers sorted by price (full mode / getProduct only) */
+    offers?: Offer[];
 }
 /**
  * Options for searching products

package/dist/index.d.ts

@@ -2,13 +2,29 @@
  * Product availability status
  */
 type Availability = "in_stock" | "low_stock" | "out_of_stock";
+/**
+ * Per-retailer offer for a product
+ */
+interface Offer {
+    id: string;
+    source: string;
+    title: string;
+    price: number;
+    currency: string;
+    availability: Availability;
+    stock: number;
+    delivery_time: string;
+    purchase_url: string;
+    image_url?: string;
+    last_updated: string;
+}
 /**
  * Product information returned by TrustRails API
  */
 interface Product {
     id: string;
+    ean?: string;
     title: string;
-    description?: string;
     brand?: string;
     price: number;
     currency: string;
@@ -19,16 +35,19 @@ interface Product {
     category: string;
     product_type: 'product' | 'accessory';
     specs: {
-        raw_category?: string;
+        description?: string;
         model_number?: string;
         dimensions?: string;
-        [key: string]: any;
     };
     provenance: {
         source: string;
         last_updated: string;
     };
     purchase_url: string;
+    /** Number of retailer offers available for this product */
+    offer_count?: number;
+    /** Per-retailer offers sorted by price (full mode / getProduct only) */
+    offers?: Offer[];
 }
 /**
  * Options for searching products

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trustrails/sdk",
-  "version": "0.4.6",
+  "version": "0.4.9",
   "description": "Official TypeScript SDK for TrustRails API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",