@trustrails/sdk 0.4.10 → 0.6.0

package/README.md

@@ -58,19 +58,20 @@ new TrustRails({ apiKey: string, baseUrl?: string })
 
 ##### `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.
+Search for products. With `lite: true` the products are trimmed (`SearchResponse<LiteProduct>`). Search results leave out `specs` and `delivery_time`, but carry every known `attributes` spec, so compare specs from the search results (a missing name is unknown, `conflicting` means retailers disagree). Call `product(id)` only for your final 1-3 picks, and only for what search lacks: the retailer's description (processor, GPU, ports, weight, battery; if it doesn't give a detail, it isn't listed), or every retailer's offer and buy link (search carries only the best offer's `purchase_url`, cheapest in stock). State the value of a `confirmed` or `inferred` attribute; only `conflicting` or a missing name needs a caveat. See [What each call returns](#what-each-call-returns).
 
 **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.query?: string` - Refinement terms only — model lines, series, variants, model numbers (e.g. `'neo'`, `'ultra'`, `'oled'`, `'WH-1000XM5'`). Never put category names here (`query='tablet'` → use `category='Tablets'`). Never put brand names or prices — use filters. Omit entirely when browsing a category or brand. Query words must appear in the title, except words naming the category (`'router'` in Networking) and bare numbers or specs (`'4070'`, `'16GB'`), which are ignored when finding products and only rank them: put a model number with its prefix (`'RTX 4070'`, not `'4070'`) and check each title for it.
+- `options.brand?: string` - Filter by brand name (exact match, case-insensitive), e.g. 'Sony', 'HP', 'Anker'
+- `options.category?: string` - Filter by product category. Use only these exact values: Laptops, Desktops, Tablets, Phones, TVs, Monitors, Headphones, Speakers, Cameras, Keyboards, Mice, Printers, Networking, Storage, Gaming, Wearables, Drones, Audio, Cables & Chargers. 'Smartphones' is not valid (use 'Phones'), nor is 'Televisions' (use 'TVs')
 - `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.constraints?: Constraints` - Hard spec requirements, checked per product against its `attributes`, e.g. `{ memory_gb: { gte: 24 }, storage_gb: { gte: 1000 }, screen_in: { eq: 15 } }`. Operators: `eq`, `gte`, `lte`; a range is `{ gte, lte }`. Names and units: `memory_gb` (RAM, GB), `storage_gb` (GB, 1TB = 1000), `screen_in` (inches), `resolution_p` (pixels high: 4K = 2160, QHD = 1440, Full HD = 1080), `refresh_hz` (Hz), `power_w` (W), `wifi_gen` (Wi-Fi generation: 6, 6E = 6.5, 7). On every operator, storage matches within 3% (1TB = 1000–1024GB, so `gte 1024` accepts a 1TB drive but not 960GB) and screen size within 0.5 inch; a whole-number screen size N also covers up to N+1 on `eq` and `lte` (`eq 13` accepts 13.6", `lte 15` accepts 15.6"); other specs exactly. Each product then has `constraint_status` per name: `matched` (a retailer's title states a value that meets it), or `unverified` (not known to meet it, never treat as a match: in `attributes[name]`, `conflicting` means retailers disagree and missing means unknown). Products whose stated value fails are left out and counted in `excluded_by_constraints`. Wins over the same spec written in `query`, where only a spec that says what it is counts (`24GB RAM`, `1TB`; a bare `24GB` does not) and means at least, except screen size. A plain `16GB` or `65W` is `gte`; use `eq` only when the user says exactly, and for screen size. Always pass a `category` or `brand` with constraints. A bad request (unknown name or operator, negative value, a combination nothing can meet such as `gte` above `lte`, or constraints with no category, brand or search words) throws a `TrustRailsError` with `statusCode` 400; the message naming the valid values is in `error.response`, the raw JSON body.
+- `options.lite?: boolean` - Return trimmed product objects (`LiteProduct`) with only essential fields (id, title, brand, price, currency, availability, image_url, purchase_url, offer_count), every known `attributes` spec as `status` and value without `sources`, and, with constraints, `constraint_status`
 - `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)
+- `options.sort?: string` - Sort order: `'relevance'` (default), `'price_asc'` (in stock first, then cheapest), `'price_desc'` (in stock first, then most expensive). With constraints, matched products still come first.
 
-**Returns:** Promise resolving to `SearchResponse` containing `products` array and `total` count.
+**Returns:** Promise resolving to `SearchResponse` containing `products` array and `total` count, plus `constraints` (as applied), `excluded_by_constraints` and `unverified_total` whenever constraints applied, whether passed or written in `query`. With constraints, `total` counts the products that match every constraint and `unverified_total` the unverified products that passed the other filters (only some may be in `products`). `candidates_truncated: true` means the first 2,000 candidates in the chosen sort order were checked and more exist: add a brand or category, or a narrower query, and search again. If the search was already narrowed, the results may be incomplete.
 
 **Example — brand + category only (query omitted):**
 ```typescript
@@ -93,18 +94,29 @@ const results = await trustrails.search({
 });
 ```
 
+**Example — spec constraints:**
+```typescript
+// MacBooks whose titles state 24GB+ RAM and 1TB+ storage come back as 'matched'
+const results = await trustrails.search({
+  brand: 'Apple',
+  category: 'Laptops',
+  maxPrice: 2000,
+  constraints: { memory_gb: { gte: 24 }, storage_gb: { gte: 1000 } },
+});
+```
+
 **Lite mode (faster responses, smaller payloads):**
 ```typescript
 const results = await trustrails.search({
   brand: 'Anker',
   category: 'Cables & Chargers',
-  lite: true  // Returns only: id, title, brand, price, availability, image_url, purchase_url
+  lite: true  // Returns id, title, brand, price, currency, availability, image_url, purchase_url, offer_count and attributes (without sources)
 });
 ```
 
 ##### `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.
+Get full details for a single product. Returns `attributes`: structured specs read from retailer titles, each with its `status` and the retailers behind it (see `Product`). Also returns `specs.description` (the retailer's own prose, for processor, ports, graphics and anything `attributes` does not cover), availability, delivery time, and all retailer offers with per-retailer pricing. `specs.description` can describe another configuration or a maximum ("up to 32GB"), so it never overrides or fills in an attribute: a spec missing from `attributes` is unknown. Accepts canonical product IDs or original retailer offer IDs. Use this after `search()` only for your final 1-3 picks, and only for what search lacks (the description's details, or every offer and buy link): `search()` already carries `attributes` to compare specs.
 
 **Parameters:**
 - `id: string` - The product ID
@@ -116,6 +128,16 @@ Get full details for a single product. Returns complete technical specifications
 const product = await trustrails.product('prod_123');
 ```
 
+### What each call returns
+
+| Call | Returns |
+|------|---------|
+| `search({ lite: true })` (what agents should always set) | id, title, brand, price, currency, availability, image_url, purchase_url, offer_count, every known `attributes` spec as `{ status, value }` (or `{ status, values }` when conflicting) without sources, and `constraint_status` when constrained |
+| `search()` | the lite fields plus ean, category, product_type, provenance and every attribute with its `sources` |
+| `product(id)` | everything: `specs.description` and dimensions, `offers`, `delivery_time` |
+
+A product with no `attributes` key has none of these seven specs known.
+
 ## Types
 
 ### `Product`
@@ -128,14 +150,13 @@ interface Product {
   brand?: string;
   price: number;
   currency: string;
-  availability: "in_stock" | "low_stock" | "out_of_stock";
-  stock: number;
-  delivery_time: string;
+  availability: "in_stock" | "low_stock" | "out_of_stock" | "unknown";
+  delivery_time?: string;  // product() only
   image_url?: string;
   category: string;
   product_type: "product" | "accessory";
-  specs: {
-    description?: string;  // Full prose spec text — always check this for technical details
+  specs?: {  // product() only
+    description?: string;  // Retailer prose; never overrides attributes
     model_number?: string;
     dimensions?: string;
   };
@@ -144,8 +165,10 @@ interface Product {
     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())
+  attributes?: Attributes;  // structured specs (search results and product()), absent when none is known, see below
+  constraint_status?: Partial<Record<ConstraintName, "matched" | "unverified">>;  // only when constraints applied
+  offer_count?: number;  // number of retailer offers (when >1, call product() for your final picks to compare prices)
+  offers?: Offer[];      // per-retailer offers, in stock first then cheapest (returned by product())
 }
 
 interface Offer {
@@ -154,8 +177,8 @@ interface Offer {
   title: string;
   price: number;
   currency: string;
-  availability: "in_stock" | "low_stock" | "out_of_stock";
-  stock: number;
+  availability: "in_stock" | "low_stock" | "out_of_stock" | "unknown";
+  stock: number | null;  // unit count only when the retailer supplies one
   delivery_time: string;
   purchase_url: string;
   image_url?: string;
@@ -163,6 +186,55 @@ interface Offer {
 }
 ```
 
+### `Attributes`
+
+Structured specs read from retailer titles, by name. A name nobody states is absent (unknown).
+
+- `confirmed`: two or more retailers state the same value.
+- `inferred`: one retailer's title states it.
+- `conflicting`: retailers state different values; none is picked, so any constraint on it is `unverified`. A retailer can appear under two values, so check `offers[].title`.
+
+```typescript
+type Attributes = Partial<Record<ConstraintName, Attribute>>;
+
+type Attribute =
+  | { status: "confirmed" | "inferred"; value: number; sources: { retailer: string; field: "title" }[] }
+  | { status: "conflicting"; values: { value: number; sources: { retailer: string; field: "title" }[] }[] };
+
+// An attribute without its sources, as a lite search result carries it
+type LiteAttribute =
+  | { status: "confirmed" | "inferred"; value: number }
+  | { status: "conflicting"; values: { value: number }[] };
+
+type LiteAttributes = Partial<Record<ConstraintName, LiteAttribute>>;
+
+// memory_gb (RAM, GB), storage_gb (GB, 1TB = 1000), screen_in (inches), resolution_p (pixels high: 4K = 2160),
+// refresh_hz (Hz), power_w (W), wifi_gen (Wi-Fi generation: 6, 6E = 6.5, 7)
+type ConstraintName = "memory_gb" | "storage_gb" | "screen_in" | "resolution_p" | "refresh_hz" | "power_w" | "wifi_gen";
+
+type Constraints = Partial<Record<ConstraintName, { eq?: number; gte?: number; lte?: number }>>;
+```
+
+### `LiteProduct`
+
+A product in a `lite: true` search.
+
+```typescript
+interface LiteProduct {
+  id: string;
+  title: string;
+  brand?: string;
+  price: number;
+  currency: string;
+  availability: "in_stock" | "low_stock" | "out_of_stock" | "unknown";
+  image_url?: string;
+  purchase_url: string;
+  offer_count: number;
+  constraint_status?: Partial<Record<ConstraintName, "matched" | "unverified">>;  // only when constraints applied
+  attributes?: LiteAttributes;  // every known spec, without sources; absent when none is known
+}
+```
+
 ### `SearchOptions`
 
 ```typescript
@@ -172,6 +244,7 @@ interface SearchOptions {
   category?: string;
   minPrice?: number;
   maxPrice?: number;
+  constraints?: Constraints;
   lite?: boolean;
   limit?: number;
   sort?: 'relevance' | 'price_asc' | 'price_desc';
@@ -181,9 +254,13 @@ interface SearchOptions {
 ### `SearchResponse`
 
 ```typescript
-interface SearchResponse {
-  products: Product[];
-  total: number;
+interface SearchResponse<P = Product> {   // SearchResponse<LiteProduct> when lite: true
+  products: P[];
+  total: number;                       // with constraints: the products that match every constraint
+  constraints?: Constraints;           // as applied, when constraints applied
+  excluded_by_constraints?: number;    // products left out because their stated value fails a constraint
+  unverified_total?: number;           // with constraints: the unverified products that passed the other filters; only some may be in products
+  candidates_truncated?: boolean;      // true when the first 2,000 candidates were checked and more exist
 }
 ```
 

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 /**
  * Product availability status
  */
-type Availability = "in_stock" | "low_stock" | "out_of_stock";
+type Availability = "in_stock" | "low_stock" | "out_of_stock" | "unknown";
 /**
  * Per-retailer offer for a product
  */
@@ -12,12 +12,73 @@ interface Offer {
     price: number;
     currency: string;
     availability: Availability;
-    stock: number;
+    stock: number | null;
     delivery_time: string;
     purchase_url: string;
     image_url?: string;
     last_updated: string;
 }
+/**
+ * Where a stated value came from
+ */
+interface AttributeSource {
+    retailer: string;
+    field: 'title';
+}
+/**
+ * One structured spec of a product, with the evidence for it
+ */
+type Attribute = {
+    status: 'confirmed' | 'inferred';
+    value: number;
+    sources: AttributeSource[];
+} | {
+    status: 'conflicting';
+    values: Array<{
+        value: number;
+        sources: AttributeSource[];
+    }>;
+};
+/**
+ * An attribute without its sources, as a lite search result carries it
+ */
+type LiteAttribute = {
+    status: 'confirmed' | 'inferred';
+    value: number;
+} | {
+    status: 'conflicting';
+    values: Array<{
+        value: number;
+    }>;
+};
+/**
+ * Structured specs of a product, by name
+ */
+type Attributes = Partial<Record<ConstraintName, Attribute>>;
+/**
+ * Structured specs of a lite search result, by name
+ */
+type LiteAttributes = Partial<Record<ConstraintName, LiteAttribute>>;
+/**
+ * Spec names for `constraints` and `attributes`
+ */
+type ConstraintName = 'memory_gb' | 'storage_gb' | 'screen_in' | 'resolution_p' | 'refresh_hz' | 'power_w' | 'wifi_gen';
+/**
+ * Operators for one spec
+ */
+interface ConstraintOps {
+    eq?: number;
+    gte?: number;
+    lte?: number;
+}
+/**
+ * Hard spec requirements
+ */
+type Constraints = Partial<Record<ConstraintName, ConstraintOps>>;
+/**
+ * Whether a product meets one constraint
+ */
+type ConstraintStatus = 'matched' | 'unverified';
 /**
  * Product information returned by TrustRails API
  */
@@ -29,12 +90,13 @@ interface Product {
     price: number;
     currency: string;
     availability: Availability;
-    stock: number;
-    delivery_time: string;
+    /** Product detail only: absent from search results */
+    delivery_time?: string;
     image_url?: string;
     category: string;
     product_type: 'product' | 'accessory';
-    specs: {
+    /** Product detail only: absent from search results */
+    specs?: {
         description?: string;
         model_number?: string;
         dimensions?: string;
@@ -44,11 +106,33 @@ interface Product {
         last_updated: string;
     };
     purchase_url: string;
+    /** Structured specs read from retailer titles: absent when none is known */
+    attributes?: Attributes;
+    /** Per-constraint result (only in searches with constraints) */
+    constraint_status?: Partial<Record<ConstraintName, ConstraintStatus>>;
     /** Number of retailer offers available for this product */
     offer_count?: number;
-    /** Per-retailer offers sorted by price (full mode / getProduct only) */
+    /** Per-retailer offers, in stock first then cheapest (product() only) */
     offers?: Offer[];
 }
+/**
+ * Trimmed product returned by a lite search
+ */
+interface LiteProduct {
+    id: string;
+    title: string;
+    brand?: string;
+    price: number;
+    currency: string;
+    availability: Availability;
+    image_url?: string;
+    purchase_url: string;
+    offer_count: number;
+    /** Per-constraint result (only in searches with constraints) */
+    constraint_status?: Partial<Record<ConstraintName, ConstraintStatus>>;
+    /** Every known spec, without sources: absent when none is known */
+    attributes?: LiteAttributes;
+}
 /**
  * Options for searching products
  */
@@ -58,19 +142,30 @@ interface SearchOptions {
     maxPrice?: number;
     brand?: string;
     category?: string;
-    /** Return trimmed product objects with only essential fields. Reduces payload size by ~80%. */
+    /** Hard spec requirements checked against each product's attributes */
+    constraints?: Constraints;
+    /** Return trimmed product objects (see LiteProduct) with only essential fields. */
     lite?: boolean;
     /** Maximum number of products to return (default 50, max 100) */
     limit?: number;
-    /** Sort order: 'relevance' (default), 'price_asc' (cheapest first), 'price_desc' (most expensive first) */
+    /** Sort order: 'relevance' (default), 'price_asc' (in stock first, then cheapest), 'price_desc' (in stock first, then most expensive) */
     sort?: 'relevance' | 'price_asc' | 'price_desc';
 }
 /**
  * Response from product search endpoint
  */
-interface SearchResponse {
-    products: Product[];
+interface SearchResponse<P = Product> {
+    products: P[];
+    /** With constraints: the products with every constraint matched */
     total: number;
+    /** The constraints applied */
+    constraints?: Constraints;
+    /** Products left out for failing a constraint */
+    excluded_by_constraints?: number;
+    /** With constraints: the unverified products that passed the other filters; only some may be in products */
+    unverified_total?: number;
+    /** True when the first 2,000 candidates in the sort order were checked and more exist */
+    candidates_truncated?: boolean;
 }
 /**
  * Configuration options for TrustRails client
@@ -105,8 +200,8 @@ declare class TrustRails {
      */
     constructor(config: TrustRailsConfig);
     /**
-     * Search for products. Returns summary data (title, price, availability, category).
-     * For full technical specs, call product(id) with the product ID.
+     * Search for products. With `lite: true` the products are trimmed (see LiteProduct).
+     * Search results carry every known `attributes` spec (with sources unless lite); for the retailer's description and every offer, call product(id).
      *
      * @param options - Search parameters
      * @returns Promise resolving to search results
@@ -118,15 +213,22 @@ declare class TrustRails {
      *   brand: 'Anker',
      *   minPrice: 20,
      *   maxPrice: 50,
-     *   category: 'Chargers'
+     *   category: 'Cables & Chargers'
      * });
      * ```
      */
-    search(options?: SearchOptions): Promise<SearchResponse>;
+    search(options: SearchOptions & {
+        lite: true;
+    }): Promise<SearchResponse<LiteProduct>>;
+    search(options?: SearchOptions & {
+        lite?: false;
+    }): Promise<SearchResponse>;
+    search(options: SearchOptions): Promise<SearchResponse<Product | LiteProduct>>;
     /**
      * Get full details for a single product. Returns complete specs, description,
-     * stock level, delivery time, and retailer source. Use after search() for
-     * detailed comparison or recommendations.
+     * availability, delivery time, and every retailer offer. Use after search() for
+     * your final 1-3 picks, and only for what search() lacks (the description's details, every offer):
+     * compare specs from the attributes search() already returns.
      *
      * @param id - The product ID
      * @returns Promise resolving to complete product details
@@ -148,4 +250,4 @@ declare class TrustRailsError extends Error {
     constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
 }
 
-export { type Product, type SearchOptions, type SearchResponse, TrustRails, type TrustRailsConfig, TrustRailsError, TrustRails as default };
+export { type Attribute, type AttributeSource, type Attributes, type ConstraintName, type ConstraintOps, type ConstraintStatus, type Constraints, type LiteAttribute, type LiteAttributes, type LiteProduct, type Product, type SearchOptions, type SearchResponse, TrustRails, type TrustRailsConfig, TrustRailsError, TrustRails as default };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Product availability status
  */
-type Availability = "in_stock" | "low_stock" | "out_of_stock";
+type Availability = "in_stock" | "low_stock" | "out_of_stock" | "unknown";
 /**
  * Per-retailer offer for a product
  */
@@ -12,12 +12,73 @@ interface Offer {
     price: number;
     currency: string;
     availability: Availability;
-    stock: number;
+    stock: number | null;
     delivery_time: string;
     purchase_url: string;
     image_url?: string;
     last_updated: string;
 }
+/**
+ * Where a stated value came from
+ */
+interface AttributeSource {
+    retailer: string;
+    field: 'title';
+}
+/**
+ * One structured spec of a product, with the evidence for it
+ */
+type Attribute = {
+    status: 'confirmed' | 'inferred';
+    value: number;
+    sources: AttributeSource[];
+} | {
+    status: 'conflicting';
+    values: Array<{
+        value: number;
+        sources: AttributeSource[];
+    }>;
+};
+/**
+ * An attribute without its sources, as a lite search result carries it
+ */
+type LiteAttribute = {
+    status: 'confirmed' | 'inferred';
+    value: number;
+} | {
+    status: 'conflicting';
+    values: Array<{
+        value: number;
+    }>;
+};
+/**
+ * Structured specs of a product, by name
+ */
+type Attributes = Partial<Record<ConstraintName, Attribute>>;
+/**
+ * Structured specs of a lite search result, by name
+ */
+type LiteAttributes = Partial<Record<ConstraintName, LiteAttribute>>;
+/**
+ * Spec names for `constraints` and `attributes`
+ */
+type ConstraintName = 'memory_gb' | 'storage_gb' | 'screen_in' | 'resolution_p' | 'refresh_hz' | 'power_w' | 'wifi_gen';
+/**
+ * Operators for one spec
+ */
+interface ConstraintOps {
+    eq?: number;
+    gte?: number;
+    lte?: number;
+}
+/**
+ * Hard spec requirements
+ */
+type Constraints = Partial<Record<ConstraintName, ConstraintOps>>;
+/**
+ * Whether a product meets one constraint
+ */
+type ConstraintStatus = 'matched' | 'unverified';
 /**
  * Product information returned by TrustRails API
  */
@@ -29,12 +90,13 @@ interface Product {
     price: number;
     currency: string;
     availability: Availability;
-    stock: number;
-    delivery_time: string;
+    /** Product detail only: absent from search results */
+    delivery_time?: string;
     image_url?: string;
     category: string;
     product_type: 'product' | 'accessory';
-    specs: {
+    /** Product detail only: absent from search results */
+    specs?: {
         description?: string;
         model_number?: string;
         dimensions?: string;
@@ -44,11 +106,33 @@ interface Product {
         last_updated: string;
     };
     purchase_url: string;
+    /** Structured specs read from retailer titles: absent when none is known */
+    attributes?: Attributes;
+    /** Per-constraint result (only in searches with constraints) */
+    constraint_status?: Partial<Record<ConstraintName, ConstraintStatus>>;
     /** Number of retailer offers available for this product */
     offer_count?: number;
-    /** Per-retailer offers sorted by price (full mode / getProduct only) */
+    /** Per-retailer offers, in stock first then cheapest (product() only) */
     offers?: Offer[];
 }
+/**
+ * Trimmed product returned by a lite search
+ */
+interface LiteProduct {
+    id: string;
+    title: string;
+    brand?: string;
+    price: number;
+    currency: string;
+    availability: Availability;
+    image_url?: string;
+    purchase_url: string;
+    offer_count: number;
+    /** Per-constraint result (only in searches with constraints) */
+    constraint_status?: Partial<Record<ConstraintName, ConstraintStatus>>;
+    /** Every known spec, without sources: absent when none is known */
+    attributes?: LiteAttributes;
+}
 /**
  * Options for searching products
  */
@@ -58,19 +142,30 @@ interface SearchOptions {
     maxPrice?: number;
     brand?: string;
     category?: string;
-    /** Return trimmed product objects with only essential fields. Reduces payload size by ~80%. */
+    /** Hard spec requirements checked against each product's attributes */
+    constraints?: Constraints;
+    /** Return trimmed product objects (see LiteProduct) with only essential fields. */
     lite?: boolean;
     /** Maximum number of products to return (default 50, max 100) */
     limit?: number;
-    /** Sort order: 'relevance' (default), 'price_asc' (cheapest first), 'price_desc' (most expensive first) */
+    /** Sort order: 'relevance' (default), 'price_asc' (in stock first, then cheapest), 'price_desc' (in stock first, then most expensive) */
     sort?: 'relevance' | 'price_asc' | 'price_desc';
 }
 /**
  * Response from product search endpoint
  */
-interface SearchResponse {
-    products: Product[];
+interface SearchResponse<P = Product> {
+    products: P[];
+    /** With constraints: the products with every constraint matched */
     total: number;
+    /** The constraints applied */
+    constraints?: Constraints;
+    /** Products left out for failing a constraint */
+    excluded_by_constraints?: number;
+    /** With constraints: the unverified products that passed the other filters; only some may be in products */
+    unverified_total?: number;
+    /** True when the first 2,000 candidates in the sort order were checked and more exist */
+    candidates_truncated?: boolean;
 }
 /**
  * Configuration options for TrustRails client
@@ -105,8 +200,8 @@ declare class TrustRails {
      */
     constructor(config: TrustRailsConfig);
     /**
-     * Search for products. Returns summary data (title, price, availability, category).
-     * For full technical specs, call product(id) with the product ID.
+     * Search for products. With `lite: true` the products are trimmed (see LiteProduct).
+     * Search results carry every known `attributes` spec (with sources unless lite); for the retailer's description and every offer, call product(id).
      *
      * @param options - Search parameters
      * @returns Promise resolving to search results
@@ -118,15 +213,22 @@ declare class TrustRails {
      *   brand: 'Anker',
      *   minPrice: 20,
      *   maxPrice: 50,
-     *   category: 'Chargers'
+     *   category: 'Cables & Chargers'
      * });
      * ```
      */
-    search(options?: SearchOptions): Promise<SearchResponse>;
+    search(options: SearchOptions & {
+        lite: true;
+    }): Promise<SearchResponse<LiteProduct>>;
+    search(options?: SearchOptions & {
+        lite?: false;
+    }): Promise<SearchResponse>;
+    search(options: SearchOptions): Promise<SearchResponse<Product | LiteProduct>>;
     /**
      * Get full details for a single product. Returns complete specs, description,
-     * stock level, delivery time, and retailer source. Use after search() for
-     * detailed comparison or recommendations.
+     * availability, delivery time, and every retailer offer. Use after search() for
+     * your final 1-3 picks, and only for what search() lacks (the description's details, every offer):
+     * compare specs from the attributes search() already returns.
      *
      * @param id - The product ID
      * @returns Promise resolving to complete product details
@@ -148,4 +250,4 @@ declare class TrustRailsError extends Error {
     constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
 }
 
-export { type Product, type SearchOptions, type SearchResponse, TrustRails, type TrustRailsConfig, TrustRailsError, TrustRails as default };
+export { type Attribute, type AttributeSource, type Attributes, type ConstraintName, type ConstraintOps, type ConstraintStatus, type Constraints, type LiteAttribute, type LiteAttributes, type LiteProduct, type Product, type SearchOptions, type SearchResponse, TrustRails, type TrustRailsConfig, TrustRailsError, TrustRails as default };

package/dist/index.js

@@ -33,24 +33,6 @@ var TrustRails = class {
       throw new Error("apiKey is required");
     }
   }
-  /**
-   * Search for products. Returns summary data (title, price, availability, category).
-   * For full technical specs, call product(id) with the product ID.
-   *
-   * @param options - Search parameters
-   * @returns Promise resolving to search results
-   *
-   * @example
-   * ```typescript
-   * const results = await client.search({
-   *   query: 'USB-C charger',
-   *   brand: 'Anker',
-   *   minPrice: 20,
-   *   maxPrice: 50,
-   *   category: 'Chargers'
-   * });
-   * ```
-   */
   async search(options = {}) {
     const url = new URL(`${this.baseUrl}/api/search`);
     if (options.query) {
@@ -68,6 +50,9 @@ var TrustRails = class {
     if (options.category) {
       url.searchParams.set("category", options.category);
     }
+    if (options.constraints) {
+      url.searchParams.set("constraints", JSON.stringify(options.constraints));
+    }
     if (options.lite) {
       url.searchParams.set("lite", "true");
     }
@@ -105,8 +90,9 @@ var TrustRails = class {
   }
   /**
    * Get full details for a single product. Returns complete specs, description,
-   * stock level, delivery time, and retailer source. Use after search() for
-   * detailed comparison or recommendations.
+   * availability, delivery time, and every retailer offer. Use after search() for
+   * your final 1-3 picks, and only for what search() lacks (the description's details, every offer):
+   * compare specs from the attributes search() already returns.
    *
    * @param id - The product ID
    * @returns Promise resolving to complete product details

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Custom error class for TrustRails API errors\n */\nexport class TrustRailsError extends Error {\n  constructor(\n    message: string,\n    public statusCode?: number,\n    public response?: any\n  ) {\n    super(message);\n    this.name = 'TrustRailsError';\n\n    // Maintains proper stack trace for where our error was thrown (only available on V8)\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, TrustRailsError);\n    }\n  }\n}\n","import { TrustRailsError } from './errors';\nimport type { Product, SearchOptions, SearchResponse, TrustRailsConfig } from './types';\n\nconst DEFAULT_BASE_URL = 'https://trustrails.app';\n\n/**\n * TrustRails SDK\n *\n * @example\n * ```typescript\n * const trustrails = new TrustRails('your-api-key');\n * const results = await trustrails.search({ query: 'laptop', maxPrice: 1000 });\n * ```\n */\nexport class TrustRails {\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n\n  /**\n   * Creates a new TrustRails SDK instance\n   *\n   * @param apiKey - Your TrustRails API key\n   */\n  constructor(apiKey: string);\n  /**\n   * Creates a new TrustRails SDK instance with custom configuration\n   *\n   * @param config - Configuration object with apiKey and optional baseUrl\n   */\n  constructor(config: TrustRailsConfig);\n  constructor(apiKeyOrConfig: string | TrustRailsConfig) {\n    if (typeof apiKeyOrConfig === 'string') {\n      this.apiKey = apiKeyOrConfig;\n      this.baseUrl = DEFAULT_BASE_URL;\n    } else {\n      this.apiKey = apiKeyOrConfig.apiKey;\n      this.baseUrl = apiKeyOrConfig.baseUrl || DEFAULT_BASE_URL;\n    }\n\n    // Clean up baseUrl - remove trailing slash\n    if (this.baseUrl.endsWith('/')) {\n      this.baseUrl = this.baseUrl.slice(0, -1);\n    }\n\n    if (!this.apiKey) {\n      throw new Error('apiKey is required');\n    }\n  }\n\n  /**\n   * Search for products. Returns summary data (title, price, availability, category).\n   * For full technical specs, call product(id) with the product ID.\n   *\n   * @param options - Search parameters\n   * @returns Promise resolving to search results\n   *\n   * @example\n   * ```typescript\n   * const results = await client.search({\n   *   query: 'USB-C charger',\n   *   brand: 'Anker',\n   *   minPrice: 20,\n   *   maxPrice: 50,\n   *   category: 'Chargers'\n   * });\n   * ```\n   */\n  async search(options: SearchOptions = {}): Promise<SearchResponse> {\n    const url = new URL(`${this.baseUrl}/api/search`);\n\n    if (options.query) {\n      url.searchParams.set('query', options.query);\n    }\n\n    if (options.minPrice) {\n      url.searchParams.set('min_price', options.minPrice.toString());\n    }\n\n    if (options.maxPrice) {\n      url.searchParams.set('max_price', options.maxPrice.toString());\n    }\n\n    if (options.brand) {\n      url.searchParams.set('brand', options.brand);\n    }\n\n    if (options.category) {\n      url.searchParams.set('category', options.category);\n    }\n\n    if (options.lite) {\n      url.searchParams.set('lite', 'true');\n    }\n\n    if (options.limit) {\n      url.searchParams.set('limit', options.limit.toString());\n    }\n\n    if (options.sort) {\n      url.searchParams.set('sort', options.sort);\n    }\n\n    try {\n      const response = await fetch(url.toString(), {\n        method: 'GET',\n        headers: {\n          'Authorization': `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n      });\n\n      if (!response.ok) {\n        throw new TrustRailsError(\n          `Search failed: ${response.statusText}`,\n          response.status,\n          await response.text()\n        );\n      }\n\n      const data = await response.json() as SearchResponse;\n      return data;\n    } catch (error) {\n      if (error instanceof TrustRailsError) {\n        throw error;\n      }\n      throw new TrustRailsError(\n        `Network error: ${error instanceof Error ? error.message : 'Unknown error'}`\n      );\n    }\n  }\n\n  /**\n   * Get full details for a single product. Returns complete specs, description,\n   * stock level, delivery time, and retailer source. Use after search() for\n   * detailed comparison or recommendations.\n   *\n   * @param id - The product ID\n   * @returns Promise resolving to complete product details\n   *\n   * @example\n   * ```typescript\n   * const product = await client.product('prod_123');\n   * ```\n   */\n  async product(id: string): Promise<Product> {\n    if (!id) {\n      throw new Error('Product ID is required');\n    }\n\n    const url = `${this.baseUrl}/api/product/${encodeURIComponent(id)}`;\n\n    try {\n      const response = await fetch(url, {\n        method: 'GET',\n        headers: {\n          'Authorization': `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n      });\n\n      if (!response.ok) {\n        if (response.status === 404) {\n          throw new TrustRailsError(`Product not found: ${id}`, 404);\n        }\n        throw new TrustRailsError(\n          `Get product failed: ${response.statusText}`,\n          response.status,\n          await response.text()\n        );\n      }\n\n      const product = await response.json() as Product;\n      return product;\n    } catch (error) {\n      if (error instanceof TrustRailsError) {\n        throw error;\n      }\n      throw new TrustRailsError(\n        `Network error: ${error instanceof Error ? error.message : 'Unknown error'}`\n      );\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Custom error class for TrustRails API errors\n */\nexport class TrustRailsError extends Error {\n  constructor(\n    message: string,\n    public statusCode?: number,\n    public response?: any\n  ) {\n    super(message);\n    this.name = 'TrustRailsError';\n\n    // Maintains proper stack trace for where our error was thrown (only available on V8)\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, TrustRailsError);\n    }\n  }\n}\n","import { TrustRailsError } from './errors';\nimport type { LiteProduct, Product, SearchOptions, SearchResponse, TrustRailsConfig } from './types';\n\nconst DEFAULT_BASE_URL = 'https://trustrails.app';\n\n/**\n * TrustRails SDK\n *\n * @example\n * ```typescript\n * const trustrails = new TrustRails('your-api-key');\n * const results = await trustrails.search({ query: 'laptop', maxPrice: 1000 });\n * ```\n */\nexport class TrustRails {\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n\n  /**\n   * Creates a new TrustRails SDK instance\n   *\n   * @param apiKey - Your TrustRails API key\n   */\n  constructor(apiKey: string);\n  /**\n   * Creates a new TrustRails SDK instance with custom configuration\n   *\n   * @param config - Configuration object with apiKey and optional baseUrl\n   */\n  constructor(config: TrustRailsConfig);\n  constructor(apiKeyOrConfig: string | TrustRailsConfig) {\n    if (typeof apiKeyOrConfig === 'string') {\n      this.apiKey = apiKeyOrConfig;\n      this.baseUrl = DEFAULT_BASE_URL;\n    } else {\n      this.apiKey = apiKeyOrConfig.apiKey;\n      this.baseUrl = apiKeyOrConfig.baseUrl || DEFAULT_BASE_URL;\n    }\n\n    // Clean up baseUrl - remove trailing slash\n    if (this.baseUrl.endsWith('/')) {\n      this.baseUrl = this.baseUrl.slice(0, -1);\n    }\n\n    if (!this.apiKey) {\n      throw new Error('apiKey is required');\n    }\n  }\n\n  /**\n   * Search for products. With `lite: true` the products are trimmed (see LiteProduct).\n   * Search results carry every known `attributes` spec (with sources unless lite); for the retailer's description and every offer, call product(id).\n   *\n   * @param options - Search parameters\n   * @returns Promise resolving to search results\n   *\n   * @example\n   * ```typescript\n   * const results = await client.search({\n   *   query: 'USB-C charger',\n   *   brand: 'Anker',\n   *   minPrice: 20,\n   *   maxPrice: 50,\n   *   category: 'Cables & Chargers'\n   * });\n   * ```\n   */\n  search(options: SearchOptions & { lite: true }): Promise<SearchResponse<LiteProduct>>;\n  search(options?: SearchOptions & { lite?: false }): Promise<SearchResponse>;\n  search(options: SearchOptions): Promise<SearchResponse<Product | LiteProduct>>;\n  async search(options: SearchOptions = {}): Promise<SearchResponse<Product | LiteProduct>> {\n    const url = new URL(`${this.baseUrl}/api/search`);\n\n    if (options.query) {\n      url.searchParams.set('query', options.query);\n    }\n\n    if (options.minPrice) {\n      url.searchParams.set('min_price', options.minPrice.toString());\n    }\n\n    if (options.maxPrice) {\n      url.searchParams.set('max_price', options.maxPrice.toString());\n    }\n\n    if (options.brand) {\n      url.searchParams.set('brand', options.brand);\n    }\n\n    if (options.category) {\n      url.searchParams.set('category', options.category);\n    }\n\n    if (options.constraints) {\n      url.searchParams.set('constraints', JSON.stringify(options.constraints));\n    }\n\n    if (options.lite) {\n      url.searchParams.set('lite', 'true');\n    }\n\n    if (options.limit) {\n      url.searchParams.set('limit', options.limit.toString());\n    }\n\n    if (options.sort) {\n      url.searchParams.set('sort', options.sort);\n    }\n\n    try {\n      const response = await fetch(url.toString(), {\n        method: 'GET',\n        headers: {\n          'Authorization': `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n      });\n\n      if (!response.ok) {\n        throw new TrustRailsError(\n          `Search failed: ${response.statusText}`,\n          response.status,\n          await response.text()\n        );\n      }\n\n      const data = await response.json() as SearchResponse<Product | LiteProduct>;\n      return data;\n    } catch (error) {\n      if (error instanceof TrustRailsError) {\n        throw error;\n      }\n      throw new TrustRailsError(\n        `Network error: ${error instanceof Error ? error.message : 'Unknown error'}`\n      );\n    }\n  }\n\n  /**\n   * Get full details for a single product. Returns complete specs, description,\n   * availability, delivery time, and every retailer offer. Use after search() for\n   * your final 1-3 picks, and only for what search() lacks (the description's details, every offer):\n   * compare specs from the attributes search() already returns.\n   *\n   * @param id - The product ID\n   * @returns Promise resolving to complete product details\n   *\n   * @example\n   * ```typescript\n   * const product = await client.product('prod_123');\n   * ```\n   */\n  async product(id: string): Promise<Product> {\n    if (!id) {\n      throw new Error('Product ID is required');\n    }\n\n    const url = `${this.baseUrl}/api/product/${encodeURIComponent(id)}`;\n\n    try {\n      const response = await fetch(url, {\n        method: 'GET',\n        headers: {\n          'Authorization': `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n      });\n\n      if (!response.ok) {\n        if (response.status === 404) {\n          throw new TrustRailsError(`Product not found: ${id}`, 404);\n        }\n        throw new TrustRailsError(\n          `Get product failed: ${response.statusText}`,\n          response.status,\n          await response.text()\n        );\n      }\n\n      const product = await response.json() as Product;\n      return product;\n    } catch (error) {\n      if (error instanceof TrustRailsError) {\n        throw error;\n      }\n      throw new TrustRailsError(\n        `Network error: ${error instanceof Error ? error.message : 'Unknown error'}`\n      );\n    }\n  }\n}\n"]}

package/dist/index.mjs

@@ -29,24 +29,6 @@ var TrustRails = class {
       throw new Error("apiKey is required");
     }
   }
-  /**
-   * Search for products. Returns summary data (title, price, availability, category).
-   * For full technical specs, call product(id) with the product ID.
-   *
-   * @param options - Search parameters
-   * @returns Promise resolving to search results
-   *
-   * @example
-   * ```typescript
-   * const results = await client.search({
-   *   query: 'USB-C charger',
-   *   brand: 'Anker',
-   *   minPrice: 20,
-   *   maxPrice: 50,
-   *   category: 'Chargers'
-   * });
-   * ```
-   */
   async search(options = {}) {
     const url = new URL(`${this.baseUrl}/api/search`);
     if (options.query) {
@@ -64,6 +46,9 @@ var TrustRails = class {
     if (options.category) {
       url.searchParams.set("category", options.category);
     }
+    if (options.constraints) {
+      url.searchParams.set("constraints", JSON.stringify(options.constraints));
+    }
     if (options.lite) {
       url.searchParams.set("lite", "true");
     }
@@ -101,8 +86,9 @@ var TrustRails = class {
   }
   /**
    * Get full details for a single product. Returns complete specs, description,
-   * stock level, delivery time, and retailer source. Use after search() for
-   * detailed comparison or recommendations.
+   * availability, delivery time, and every retailer offer. Use after search() for
+   * your final 1-3 picks, and only for what search() lacks (the description's details, every offer):
+   * compare specs from the attributes search() already returns.
    *
    * @param id - The product ID
    * @returns Promise resolving to complete product details

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Custom error class for TrustRails API errors\n */\nexport class TrustRailsError extends Error {\n  constructor(\n    message: string,\n    public statusCode?: number,\n    public response?: any\n  ) {\n    super(message);\n    this.name = 'TrustRailsError';\n\n    // Maintains proper stack trace for where our error was thrown (only available on V8)\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, TrustRailsError);\n    }\n  }\n}\n","import { TrustRailsError } from './errors';\nimport type { Product, SearchOptions, SearchResponse, TrustRailsConfig } from './types';\n\nconst DEFAULT_BASE_URL = 'https://trustrails.app';\n\n/**\n * TrustRails SDK\n *\n * @example\n * ```typescript\n * const trustrails = new TrustRails('your-api-key');\n * const results = await trustrails.search({ query: 'laptop', maxPrice: 1000 });\n * ```\n */\nexport class TrustRails {\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n\n  /**\n   * Creates a new TrustRails SDK instance\n   *\n   * @param apiKey - Your TrustRails API key\n   */\n  constructor(apiKey: string);\n  /**\n   * Creates a new TrustRails SDK instance with custom configuration\n   *\n   * @param config - Configuration object with apiKey and optional baseUrl\n   */\n  constructor(config: TrustRailsConfig);\n  constructor(apiKeyOrConfig: string | TrustRailsConfig) {\n    if (typeof apiKeyOrConfig === 'string') {\n      this.apiKey = apiKeyOrConfig;\n      this.baseUrl = DEFAULT_BASE_URL;\n    } else {\n      this.apiKey = apiKeyOrConfig.apiKey;\n      this.baseUrl = apiKeyOrConfig.baseUrl || DEFAULT_BASE_URL;\n    }\n\n    // Clean up baseUrl - remove trailing slash\n    if (this.baseUrl.endsWith('/')) {\n      this.baseUrl = this.baseUrl.slice(0, -1);\n    }\n\n    if (!this.apiKey) {\n      throw new Error('apiKey is required');\n    }\n  }\n\n  /**\n   * Search for products. Returns summary data (title, price, availability, category).\n   * For full technical specs, call product(id) with the product ID.\n   *\n   * @param options - Search parameters\n   * @returns Promise resolving to search results\n   *\n   * @example\n   * ```typescript\n   * const results = await client.search({\n   *   query: 'USB-C charger',\n   *   brand: 'Anker',\n   *   minPrice: 20,\n   *   maxPrice: 50,\n   *   category: 'Chargers'\n   * });\n   * ```\n   */\n  async search(options: SearchOptions = {}): Promise<SearchResponse> {\n    const url = new URL(`${this.baseUrl}/api/search`);\n\n    if (options.query) {\n      url.searchParams.set('query', options.query);\n    }\n\n    if (options.minPrice) {\n      url.searchParams.set('min_price', options.minPrice.toString());\n    }\n\n    if (options.maxPrice) {\n      url.searchParams.set('max_price', options.maxPrice.toString());\n    }\n\n    if (options.brand) {\n      url.searchParams.set('brand', options.brand);\n    }\n\n    if (options.category) {\n      url.searchParams.set('category', options.category);\n    }\n\n    if (options.lite) {\n      url.searchParams.set('lite', 'true');\n    }\n\n    if (options.limit) {\n      url.searchParams.set('limit', options.limit.toString());\n    }\n\n    if (options.sort) {\n      url.searchParams.set('sort', options.sort);\n    }\n\n    try {\n      const response = await fetch(url.toString(), {\n        method: 'GET',\n        headers: {\n          'Authorization': `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n      });\n\n      if (!response.ok) {\n        throw new TrustRailsError(\n          `Search failed: ${response.statusText}`,\n          response.status,\n          await response.text()\n        );\n      }\n\n      const data = await response.json() as SearchResponse;\n      return data;\n    } catch (error) {\n      if (error instanceof TrustRailsError) {\n        throw error;\n      }\n      throw new TrustRailsError(\n        `Network error: ${error instanceof Error ? error.message : 'Unknown error'}`\n      );\n    }\n  }\n\n  /**\n   * Get full details for a single product. Returns complete specs, description,\n   * stock level, delivery time, and retailer source. Use after search() for\n   * detailed comparison or recommendations.\n   *\n   * @param id - The product ID\n   * @returns Promise resolving to complete product details\n   *\n   * @example\n   * ```typescript\n   * const product = await client.product('prod_123');\n   * ```\n   */\n  async product(id: string): Promise<Product> {\n    if (!id) {\n      throw new Error('Product ID is required');\n    }\n\n    const url = `${this.baseUrl}/api/product/${encodeURIComponent(id)}`;\n\n    try {\n      const response = await fetch(url, {\n        method: 'GET',\n        headers: {\n          'Authorization': `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n      });\n\n      if (!response.ok) {\n        if (response.status === 404) {\n          throw new TrustRailsError(`Product not found: ${id}`, 404);\n        }\n        throw new TrustRailsError(\n          `Get product failed: ${response.statusText}`,\n          response.status,\n          await response.text()\n        );\n      }\n\n      const product = await response.json() as Product;\n      return product;\n    } catch (error) {\n      if (error instanceof TrustRailsError) {\n        throw error;\n      }\n      throw new TrustRailsError(\n        `Network error: ${error instanceof Error ? error.message : 'Unknown error'}`\n      );\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Custom error class for TrustRails API errors\n */\nexport class TrustRailsError extends Error {\n  constructor(\n    message: string,\n    public statusCode?: number,\n    public response?: any\n  ) {\n    super(message);\n    this.name = 'TrustRailsError';\n\n    // Maintains proper stack trace for where our error was thrown (only available on V8)\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, TrustRailsError);\n    }\n  }\n}\n","import { TrustRailsError } from './errors';\nimport type { LiteProduct, Product, SearchOptions, SearchResponse, TrustRailsConfig } from './types';\n\nconst DEFAULT_BASE_URL = 'https://trustrails.app';\n\n/**\n * TrustRails SDK\n *\n * @example\n * ```typescript\n * const trustrails = new TrustRails('your-api-key');\n * const results = await trustrails.search({ query: 'laptop', maxPrice: 1000 });\n * ```\n */\nexport class TrustRails {\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n\n  /**\n   * Creates a new TrustRails SDK instance\n   *\n   * @param apiKey - Your TrustRails API key\n   */\n  constructor(apiKey: string);\n  /**\n   * Creates a new TrustRails SDK instance with custom configuration\n   *\n   * @param config - Configuration object with apiKey and optional baseUrl\n   */\n  constructor(config: TrustRailsConfig);\n  constructor(apiKeyOrConfig: string | TrustRailsConfig) {\n    if (typeof apiKeyOrConfig === 'string') {\n      this.apiKey = apiKeyOrConfig;\n      this.baseUrl = DEFAULT_BASE_URL;\n    } else {\n      this.apiKey = apiKeyOrConfig.apiKey;\n      this.baseUrl = apiKeyOrConfig.baseUrl || DEFAULT_BASE_URL;\n    }\n\n    // Clean up baseUrl - remove trailing slash\n    if (this.baseUrl.endsWith('/')) {\n      this.baseUrl = this.baseUrl.slice(0, -1);\n    }\n\n    if (!this.apiKey) {\n      throw new Error('apiKey is required');\n    }\n  }\n\n  /**\n   * Search for products. With `lite: true` the products are trimmed (see LiteProduct).\n   * Search results carry every known `attributes` spec (with sources unless lite); for the retailer's description and every offer, call product(id).\n   *\n   * @param options - Search parameters\n   * @returns Promise resolving to search results\n   *\n   * @example\n   * ```typescript\n   * const results = await client.search({\n   *   query: 'USB-C charger',\n   *   brand: 'Anker',\n   *   minPrice: 20,\n   *   maxPrice: 50,\n   *   category: 'Cables & Chargers'\n   * });\n   * ```\n   */\n  search(options: SearchOptions & { lite: true }): Promise<SearchResponse<LiteProduct>>;\n  search(options?: SearchOptions & { lite?: false }): Promise<SearchResponse>;\n  search(options: SearchOptions): Promise<SearchResponse<Product | LiteProduct>>;\n  async search(options: SearchOptions = {}): Promise<SearchResponse<Product | LiteProduct>> {\n    const url = new URL(`${this.baseUrl}/api/search`);\n\n    if (options.query) {\n      url.searchParams.set('query', options.query);\n    }\n\n    if (options.minPrice) {\n      url.searchParams.set('min_price', options.minPrice.toString());\n    }\n\n    if (options.maxPrice) {\n      url.searchParams.set('max_price', options.maxPrice.toString());\n    }\n\n    if (options.brand) {\n      url.searchParams.set('brand', options.brand);\n    }\n\n    if (options.category) {\n      url.searchParams.set('category', options.category);\n    }\n\n    if (options.constraints) {\n      url.searchParams.set('constraints', JSON.stringify(options.constraints));\n    }\n\n    if (options.lite) {\n      url.searchParams.set('lite', 'true');\n    }\n\n    if (options.limit) {\n      url.searchParams.set('limit', options.limit.toString());\n    }\n\n    if (options.sort) {\n      url.searchParams.set('sort', options.sort);\n    }\n\n    try {\n      const response = await fetch(url.toString(), {\n        method: 'GET',\n        headers: {\n          'Authorization': `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n      });\n\n      if (!response.ok) {\n        throw new TrustRailsError(\n          `Search failed: ${response.statusText}`,\n          response.status,\n          await response.text()\n        );\n      }\n\n      const data = await response.json() as SearchResponse<Product | LiteProduct>;\n      return data;\n    } catch (error) {\n      if (error instanceof TrustRailsError) {\n        throw error;\n      }\n      throw new TrustRailsError(\n        `Network error: ${error instanceof Error ? error.message : 'Unknown error'}`\n      );\n    }\n  }\n\n  /**\n   * Get full details for a single product. Returns complete specs, description,\n   * availability, delivery time, and every retailer offer. Use after search() for\n   * your final 1-3 picks, and only for what search() lacks (the description's details, every offer):\n   * compare specs from the attributes search() already returns.\n   *\n   * @param id - The product ID\n   * @returns Promise resolving to complete product details\n   *\n   * @example\n   * ```typescript\n   * const product = await client.product('prod_123');\n   * ```\n   */\n  async product(id: string): Promise<Product> {\n    if (!id) {\n      throw new Error('Product ID is required');\n    }\n\n    const url = `${this.baseUrl}/api/product/${encodeURIComponent(id)}`;\n\n    try {\n      const response = await fetch(url, {\n        method: 'GET',\n        headers: {\n          'Authorization': `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n      });\n\n      if (!response.ok) {\n        if (response.status === 404) {\n          throw new TrustRailsError(`Product not found: ${id}`, 404);\n        }\n        throw new TrustRailsError(\n          `Get product failed: ${response.statusText}`,\n          response.status,\n          await response.text()\n        );\n      }\n\n      const product = await response.json() as Product;\n      return product;\n    } catch (error) {\n      if (error instanceof TrustRailsError) {\n        throw error;\n      }\n      throw new TrustRailsError(\n        `Network error: ${error instanceof Error ? error.message : 'Unknown error'}`\n      );\n    }\n  }\n}\n"]}

package/package.json

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