Products

Reference for the ProductsService class in the Tybrite SDK.

The ProductsService class (accessed via client.products) is the core discovery engine. It provides high-performance access to your catalog with advanced filtering, hierarchical variant structures, and a unified media gallery system.

Validation & Rate Limits: Product IDs are validated as UUIDs at the gateway router — malformed IDs return 400 immediately without hitting downstream workers. All endpoints are rate-limited (publishable key: 1,000 req/hr per IP; secret key: 10,000 req/hr per key).

Response Structure Tiers

To optimize performance across different device types, the service implements three response tiers:

Tier	Endpoint	Structure	Use Case
Tier 1: Catalog	listProducts	Flat: Root-level default variant data.	Homepages, Category Grids, Search.
Tier 2: PDP (Multi)	getProduct	Hierarchical: Root metadata + variants array.	Detail pages where users select options.
Tier 3: PDP (Simple)	getProduct	Flat: Full detail without variants array.	Single-variant products (no selection needed).

---

Catalog Discovery

listProducts

Retrieve a paginated list of products. This method returns flat structures (no variants array) to keep payloads small.

• ⚡ Performance: 50-70% smaller than detail endpoints.
• 🖼️ Thumbnails: Use thumbnail_url for fast rendering in lists without iterating arrays.
• 🛒 Quick Add: Includes default variant data (price, stock, sku) at root level.
• 🔍 Intelligence: Use the has_variants flag to determine if the UI should show “View Options”.
• ⏩ Pagination: Uses cursor-based navigation for stable, high-performance scrolling.

const { products, pagination } = await client.products.listProducts({
  search: 'Sony',
  limit: 20,
  fields: 'name,price,stock,has_variants,product_slug,thumbnail_url'
});

// For subsequent pages, pass the cursor from the previous response:
// const next = await client.products.listProducts({ limit: 20, cursor: pagination.next_cursor });

console.log(`Has more: ${pagination.has_more}`);
if (pagination.next_cursor) {
  // Use pagination.next_cursor for the subsequent request
}

---

getProduct

Retrieve complete details for a single item. This method handles Multi-Variant products by returning a hierarchical structure that eliminates data redundancy and supports variant-aware media.

• Product-Level: Shared metadata at the root (name, brand, media gallery).
• Aggregate Data: total_stock (sum of all variants) and price_range (min/max using selling_price).
• Variants Array: Clean array containing variant-specific attributes (color, size, SKU) and isolated media for that specific variation.

const product = await client.products.getProduct({
  id: 'sony-wh-1000xm4-uuid',
  fields: 'name,thumbnail_url,media,price_range,total_stock,variants.sku,variants.media'
});

if (product.has_variants) {
  console.log(`Variants available: ${product.variant_count}`);
  console.log(`Price Range: ${product.price_range.min} - ${product.price_range.max}`);
  
  // Access variant-specific media (e.g., if user selects 'Grey' color)
  const greyVariant = product.variants.find(v => v.variant_attributes.color === 'Grey');
  console.log(`Grey variation images: ${greyVariant.media.length}`);
}

---

getProductBySlug

Retrieve a product using its SEO-friendly slug. Identical to getProduct in response structure but optimized for PDP routing.

const product = await client.products.getProductBySlug({
  slug: 'sony-wh-1000xm4-a089d',
  fields: 'seo_title,seo_description,thumbnail_url,media,price_range,variants.*'
});

---

📸 Media Gallery System

The media system supports a fully-functional, variant-aware gallery.

Root-Level Media

• thumbnail_url: Represents the primary image for the product. Perfect for simple grids.
• media: An array of objects containing all base-level images and videos.

Variant Media

Each variant in the variants[] array can have its own media array. This allows you to show specific images when a user selects a particular variation (e.g., rotating the gallery to show the “Midnight Blue” model).

Media Object Structure:

Field	Type	Description
id	uuid	Unique identifier for the media item.
url	string	Full CDN URL for the asset.
type	string	image or video.
position	number	Explicit sort order (starting from 0).
alt_text	string	Accessibility text.
is_primary	boolean	Whether this is the main image (used for thumbnail_url).

---

🎨 Advanced Field Filtering

Tybrite supports powerful field selection to minimize bandwidth.

Root-Level Filtering

Exclude large metadata objects by selecting only top-level fields.

fields=product_id,name,brand,thumbnail_url,total_stock,price_range,variants

Nested Array Filtering

Use dot notation to select specific fields within nested arrays.

# Get only the SKU and specific media for each variant
fields=name,variants.sku,variants.media,variants.variant_attributes

Supported Fields for Filtering:

• Core: product_id, name, sku, description, thumbnail_url, media
• Pricing: price, selling_price, sale_price, price_range
• Inventory: stock, total_stock, threshold
• Variants: variants.sku, variants.selling_price, variants.media, variants.variant_attributes

---

Product Specifications

getProductSpecifications

Retrieve structured technical specifications.

const { id, specification_data } = await client.products.getProductSpecifications({ 
  id: 'product-uuid'
});

---

Collections

Manage curated groups of products.

// List all active collections
const { collections } = await client.products.listProductCollections({ 
  showOnHomepage: 'true',
  limit: 20
});

// Get items in a specific collection
const { items, pagination: itemPagination } = await client.products.getProductCollectionItems({ 
  id: 'flash-sale-uuid',
  limit: 10
});

---

Response Codes

All product endpoints are GET and accept both publishable and secret keys.

Code	Meaning
200	Success.
400	Invalid request — malformed UUID, invalid slug, or unrecognized field in the fields parameter.
401	Invalid or missing API key.
404	Product, collection, or specification not found (single-resource endpoints only). List endpoints return 200 with an empty array.
429	Rate limit exceeded (1,000/hr per IP for pk_; 10,000/hr per key for sk_).
500	Internal server error.