Sizebay Core SDK

A modular SDK for integrating Sizebay services into your application. Features environment-based endpoint management, async/await support, built-in retry logic, and full TypeScript definitions.

• Event tracking
• AI image recommendations (similar / complementary / sizing)
• Fashion looks (grouped looks with try-ons)
• Session & profile management
• Environment-aware endpoints (-dev / -prod)
• Full TypeScript typings

Table of Contents

1. Installation
2. Quick Start
3. Tracker Module
4. AI Image Service Module
5. Fashion Looks Module
6. Session Module
7. DTO Reference

Installation

Install via npm:

npm install sizebay-core-sdk

Quick Start

Create a client

import { createClient } from 'sizebay-core-sdk';

const client = createClient({ env: 'development' });
// env: 'development' | 'production' (default: 'development')

Tracker Module

track(eventName: string, payload: TrackData): Promise<TrackResponse>

Send an event to the API.

Parameters

| Parameter | Type | Required | Description | | ----------- | ----------- | :------: | ------------------------------- | | eventName | string | Yes | e.g. "ADD_TO_CART", "ORDER" | | payload | TrackData | Yes | See structure below |

Returns

TrackResponse

• statusCode: 201 — HTTP status code indicating success (201 Created).
• message: "Event successfully created." — Confirmation message.

Example

const payload = {
  sid: 'a0cf8559-926a-4a75-b4ca-7c4c13fed69c',
  tenantId: 123,
  sessionId: 456,
  permalink: 'https://www.example.com/2IC-7370',
  properties: { quantity: 1, device: 'APP', country: 'BR' },
};

const response = await client.track('ADD_TO_CART', payload);
console.log(response.statusCode, response.message);

AI Image Service Module

getSimilarProducts(params: GetSimilarProductsParams): Promise<GetSimilarProductsResponse>

Fetch products similar to a reference.

Parameters

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | permalink | string | No | The URL permalink of the reference product for the similarity search. | | productId | string | No | Product ID (either permalink or productId must be provided). | | page | number | No | The page number for pagination. | | perPage | number | No | The number of items to return per page. | | similarityThreshold | number | No | The minimum similarity score (0-1) for the results. | | tenantId | number | Yes | Tenant (client) ID. | | collectionName | string | Yes | Embeddings collection name (namespace). | | sid | string | Yes | Session identifier (sid) for the user. | | sizeSystem | string | Yes | Size system code (e.g., 'BR', 'EU', 'US'). | | locale | string | Yes | Locale for internationalized responses (language and region). | | currency | string | Yes | Currency code for pricing information in responses. | | filterByWhatFitsMe | boolean | No | Whether to apply What Fits Me logic. | | personaHash | string | No | Hash representing the user persona (required if WFM is enabled). |

Returns

GetSimilarProductsResponse

• data: ProductDto[] — An array of products that are visually similar to the reference item.The results are ordered by their similarity score.
• page: number — The current page number of the results.
• perPage: number — The number of items per page.
• total: number — The total number of similar products found.
• invalidPersonaHash: boolean — Indicates if the provided persona hash is invalid or expired,which may affect personalized results.

Example

const similarResponse = await client.getSimilarProducts({
  tenantId: 123,
  collectionName: 'clothing',
  sid: 'abc123',
  permalink: 'https://domain.com/product/xyz',
  sizeSystem: 'US',
  similarityThreshold: 0.5,
  page: 1,
  perPage: 10,
});
console.log(similarResponse.data, similarResponse.total);

getComplementaryProducts(params: GetComplementaryProductsParams): Promise<GetComplementaryProductsResponse>

Retrieve pairs of complementary products.

Parameters

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | permalink | string | No | The URL permalink of the reference product.Its style, color, and category are used to find matching items. | | productId | string | No | Product ID (either permalink or productId must be provided). | | similarityThreshold | number | Yes | The minimum similarity score (0-1) for recommended products.A higher value yields more similar items, while a lower value provides more variety. | | tenantId | number | Yes | Tenant (client) ID. | | collectionName | string | Yes | Embeddings collection name (namespace). | | sid | string | Yes | Session identifier (sid) for the user. | | sizeSystem | string | Yes | Size system code (e.g., 'BR', 'EU', 'US'). | | locale | string | Yes | Locale for internationalized responses (language and region). | | currency | string | Yes | Currency code for pricing information in responses. | | filterByWhatFitsMe | boolean | No | Whether to apply What Fits Me logic. | | personaHash | string | No | Hash representing the user persona (required if WFM is enabled). |

Returns

GetComplementaryProductsResponse

• baseProduct: ProductDto — The reference product used to generate recommendations.This is the item that corresponds to the permalink from the request.
• complementary: ComplementaryPairDto[] — A list of recommended pairs of products that are complementary to the base product.
• invalidPersonaHash: boolean — Indicates if the provided persona hash is invalid or has expired.If true, personalization may be affected.

Example

const compResponse = await client.getComplementaryProducts({
  tenantId: 123,
  collectionName: 'clothing',
  sid: 'abc123',
  permalink: 'https://domain.com/product/xyz',
  sizeSystem: 'US',
  similarityThreshold: 0.2,
});
console.log(compResponse.baseProduct, compResponse.complementary);

Image Search Services

searchSimilarByImage(payload: GetSimilarByImageBodyDto): Promise<GetSimilarProductsResponse>

Find visually similar items from an uploaded image.

Payload

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | image | string | Yes | Base64-encoded image data. | | ageRange | string | No | Target age range. | | gender | string | No | User gender (optional). | | style | string | No | Preferred style hint. | | color | string | No | Main color of interest. | | productClass | ProductClass | No | Target product class. | | clothType | ClothType | No | Target cloth type for filtering results. | | page | number | No | Current page number. | | perPage | number | No | Number of results per page. | | similarityThreshold | number | No | Similarity threshold for matching (0-1). | | tenantId | number | Yes | Tenant (client) ID. | | collectionName | string | Yes | Embeddings collection name (namespace). | | sid | string | Yes | Session identifier (sid) for the user. | | sizeSystem | string | Yes | Size system code (e.g., 'BR', 'EU', 'US'). | | locale | string | Yes | Locale for internationalized responses (language and region). | | currency | string | Yes | Currency code for pricing information in responses. | | filterByWhatFitsMe | boolean | No | Whether to apply What Fits Me logic. | | personaHash | string | No | Hash representing the user persona (required if WFM is enabled). |

Returns

Example

const imgSimilar = await client.searchSimilarByImage({
  image: 'data:image/png;base64,...',
  tenantId: 123,
  collectionName: 'clothing',
  sid: 'abc123',
  sizeSystem: 'US',
});
console.log(imgSimilar.data);

searchComplementaryByImage(payload: GetComplementaryByImageBodyDto): Promise<GetComplementaryProductsByImageResponse>

Get products that complete a look from an image.

Payload

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | similarityThreshold | number | Yes | The minimum similarity score (0-1) for recommended products. | | baseClothType | ClothType | Yes | The type of product identified in the reference image. | | targetClothType | ClothType | Yes | The desired type of complementary products to be recommended. | | image | string | Yes | Base64-encoded image data. | | ageRange | string | No | Target age range. | | gender | string | No | User gender (optional). | | style | string | No | Preferred style hint. | | color | string | No | Main color of interest. | | productClass | ProductClass | No | Target product class. | | clothType | ClothType | No | Target cloth type for filtering results. | | page | number | No | Current page number. | | perPage | number | No | Number of results per page. | | tenantId | number | Yes | Tenant (client) ID. | | collectionName | string | Yes | Embeddings collection name (namespace). | | sid | string | Yes | Session identifier (sid) for the user. | | sizeSystem | string | Yes | Size system code (e.g., 'BR', 'EU', 'US'). | | locale | string | Yes | Locale for internationalized responses (language and region). | | currency | string | Yes | Currency code for pricing information in responses. | | filterByWhatFitsMe | boolean | No | Whether to apply What Fits Me logic. | | personaHash | string | No | Hash representing the user persona (required if WFM is enabled). |

Returns

GetComplementaryProductsByImageResponse

• baseProduct: ProductDto — The product identified in the reference image.
• complementary: ProductDto[] — A list of recommended products that are complementary to the base product.
• page: number — The current page number of the results.
• perPage: number — The number of items per page.
• total: number — The total number of complementary products found.
• invalidPersonaHash: boolean — Indicates if the provided persona hash is invalid or has expired.

Example

const imgComp = await client.searchComplementaryByImage({
  image: 'data:image/png;base64,...',
  tenantId: 123,
  collectionName: 'clothing',
  sid: 'abc123',
  sizeSystem: 'US',
  similarityThreshold: 0.5,
  baseClothType: ClothType.TOP,
  targetClothType: ClothType.BOTTOM,
});
console.log(imgComp.baseProduct, imgComp.complementary);

Fashion Looks Module

getGroupedLooks(params: GetGroupedLooksParams): Promise<GroupedLooksListResponse>

Get grouped looks with optional filters and pagination (Public endpoint).

Parameters

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | tenantId | number | Yes | Tenant ID (required). | | limit | number | No | Maximum number of looks to return per page (1-100).Use smaller values for faster responses, larger for comprehensive results. | | offset | number | No | Number of looks to skip before returning results.Use with limit to implement pagination: page 2 = offset 50 (if limit is 50). | | order | SortOrder | No | Sort order by creation date.Use 'desc' to show newest looks first, 'asc' for oldest first. | | permalink | string | No | Filter by product permalink.Find all looks that include this specific product. Useful for showingstyling suggestions when a user views a product page. | | gender | Gender | No | Filter by target gender.Show only looks designed for MALE or FEMALE audiences. | | ageGroup | AgeGroup | No | Filter by target age group.Show only looks appropriate for the specified age range. | | style | Style | No | Filter by style category.Show only looks matching the desired style (casual, formal, party, etc.). | | collection | Collection | No | Filter by seasonal collection.Show only looks from a specific season (spring, summer, fall, winter). | | status | GroupedLookStatus | No | Filter by active status.Use 'enabled' to show only active looks, 'disabled' for inactive ones. |

Returns

GroupedLooksListResponse

• data: GroupedLookResponseDto[] — Fashion looks for the current page.Display these looks to users. Each look contains styled outfits with try-on images.
• total: number — Total number of looks matching your filters across all pages.Use this to show "Showing X of Y looks" or calculate total pages.
• pagination: PaginationInfo — Pagination information for navigating between pages.Use this to implement pagination controls in your UI.

Example

const looks = await client.getGroupedLooks({
  tenantId: 1,
  limit: 50,
  gender: 'FEMALE',
  style: 'casual',
  collection: 'summer',
});
console.log(looks.data, looks.total);

getGroupedLookById(id: string, tenantId: number): Promise<GroupedLookResponseDto>

Get a specific grouped look by ID (Public endpoint).

Parameters

| Parameter | Type | Required | Description | | ----------- | ------ | :------: | -------------------------- | | id | string | Yes | Grouped look UUID | | tenantId | number | Yes | Tenant ID |

Returns

GroupedLookResponseDto

• id: string — Unique identifier for this fashion look (UUID).Use this to fetch the look again or reference it in other operations.
• tenantId: number — Tenant ID that owns this look.
• gender: Gender — Target gender for this look (MALE or FEMALE).Use to filter or categorize looks by target audience.
• ageGroup: AgeGroup — Target age group for this look.Use to show age-appropriate looks to users.
• style: Style — Style category of this look.Use to filter looks by style preference or display style tags.
• collection: Collection — Seasonal collection this look belongs to.Use to show seasonal looks or filter by collection.
• rate: number — Quality rating of this look (0-5).Higher ratings indicate better quality. Use to sort or filter by quality.
• status: GroupedLookStatus — Current status of this look.Only show 'enabled' looks to users, hide 'disabled' ones.
• timestamp: string — When this look was created (ISO 8601 format).Use to sort by date or show "new" looks.
• tryons: TryonGroup[] — All virtual try-on images organized by body type and skin tone.Iterate through this to display all try-on variations. Each group representsa body type, and each group contains try-ons for different skin tones.
• feedback: GroupedLookFeedbackResponseDto — User feedback for this look, if any has been submitted.Use to display feedback or quality metrics to users.

Example

const look = await client.getGroupedLookById('uuid-here', 1);
console.log(look.id, look.style, look.tryons);

Session Module

Retrieves and caches session context:

• sid (string): Catalog user ID returned by session endpoint
• sessionId (number): Numeric session identifier

getSessionInfo(): Promise<SessionContext>

Fetches or reuses session context.

Returns

SessionContext

• sid: string — The session identifier (sid) used in subsequent API calls for tracking and recommendations.
• sessionId: number — A unique numeric identifier for the session instance, used for internal analytics.

Example

const { sid, sessionId } = await client.getSessionInfo();
console.log('SID:', sid, 'sessionId:', sessionId);

sendProfile(payload: SessionProfilePayload, sid?: string): Promise<void>

Sends user profile data. Uses cached sid if not provided.

Parameters

| Field | Type | Required | Description | | --------- | --------------------- | :------: | ------------------------------------ | | payload | SessionProfilePayload | Yes | Profile details | | sid | string | No | Catalog user ID (defaults to cached) |

SessionProfilePayload

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | name | string | Yes | Internal profile identifier or display name for the user.Typically used for analytics and user identification within Sizebay's system. | | skinType | number | Yes | Skin tone classification used for color matching and style recommendations.Numerical value representing different skin tone categories. | | footShape | string | Yes | Foot shape classification for footwear recommendations.Used to provide better shoe fit analysis when available. | | gender | string | Yes | User's gender for size system selection and fit calculations.Uses single character format as defined by Sizebay's standards. | | age | string | Yes | User's age for age-appropriate sizing and recommendations.Stored as string to accommodate various age formats. | | is3dFeel | boolean | Yes | Feature flag indicating if advanced 3D fit visualization is enabled.Affects the level of detail in size recommendations and fit analysis. | | weight | string | Yes | User's body weight in the unit system specified by isMetric.Used for comprehensive fit analysis and size calculations. | | height | string | Yes | User's height in the unit system specified by isMetric.Critical measurement for accurate size recommendations. | | measures | { insoleLength: number; poundWeight: number | null; } | Yes | Additional precise body measurements for enhanced fit accuracy. | | product | string | Yes | Product context or identifier related to the current profiling session.Can link the profile to a specific product being viewed. | | isMetric | boolean | Yes | Unit system preference for all measurements and recommendations.- true: Metric system (cm, kg)- false: Imperial system (inches, lbs) | | bodyShapeChest | number | Yes | Chest/bust body shape index for clothing fit analysis.Numerical value representing body proportions in the chest area. | | bodyShapeHip | number | Yes | Hip body shape index for lower body clothing fit analysis.Numerical value representing body proportions in the hip area. | | bodyShapeWaist | number | Yes | Waist body shape index for torso fit analysis.Numerical value representing body proportions in the waist area. |

Example

const profilePayload: SessionProfilePayload = {
  userId: 'abc123',
  name: 'szb-profile-no-name',
  skinType: 0,
  footShape: null,
  gender: 'F',
  age: '25',
  is3dFeel: true,
  weight: '80',
  height: '180',
  measures: { insoleLength: 0, poundWeight: null },
  product: null,
  isMetric: false,
  bodyShapeChest: 0,
  bodyShapeWaist: 0,
  bodyShapeHip: 0,
};

await client.sendProfile(profilePayload);

DTO Reference

ProductDto

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | id | string | Yes | Unique identifier for the product from the e-commerce platform. | | title | string | Yes | The display name or title of the product. | | productType | string | Yes | The product's category, often in a hierarchical format. | | link | string | Yes | The direct URL to the product's page. | | imageLink | string | Yes | The URL for the main product image. | | gender | string | Yes | The target gender for the product. | | availability | string | Yes | The current stock availability of the product. | | productHash | string | Yes | A SHA-256 hash for internal identification and caching. | | price | string | Yes | The product's price, including the currency. | | salePrice | string | Yes | The product's sale price, if applicable. | | itemGroupId | string | Yes | An identifier for grouping product variants (e.g., by color or size). | | brand | string | Yes | The brand of the product. | | color | string | Yes | The color of the product. | | style | string | Yes | The style classification of the product. | | gtin | string | Yes | The Global Trade Item Number (GTIN) for the product. | | additionalImageLinks | string[] | Yes | A list of additional image URLs for the product. | | suitableSizes | SuitableSizeDto[] | No | Size recommendations from Sizebay's What Fits Me feature, including comfort scores.This is populated when personalized sizing is available. | | clothType | ClothType | No | The standardized clothing type, used for recommendations and size chart matching. | | catalogTableCode | number | No | The id of the modeling table of the product |

TrackData

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | sid | string | Yes | The session identifier from Sizebay's session service, representing the user. | | tenantId | number | Yes | The unique identifier for the tenant (client). | | properties | Record<string, JSONValue> | Yes | A key-value map for event-specific data. | | permalink | string | No | The URL of the product page associated with the event, if applicable. |

SuitableSizeDto

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | size | string | Yes | Size label as defined in the product catalog (e.g., "M", "42", "8-10").Uses the same format as the store's size system. | | comfortable | number | Yes | AI-calculated comfort score ranging from 0 to 1, where a lower value indicates a better fit:- 0.0 = Perfect, comfortable fit- 0.5 = Adequate, but potentially tight/loose fit- 1.0 = Very uncomfortable fit | | value | boolean | No | Boolean indicator of whether this size is considered suitable for the user.Based on comfort threshold and fit analysis algorithms. |

ComplementaryPairDto

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | first | ProductDto | Yes | First recommended product that complements the base product sent in the request.This product is selected based on style compatibility and fashion rules. | | secondary | ProductDto | No | Second recommended product that complements the base product sent in the request.May be null if no suitable second complementary item is found. |

ClothType

Standardized clothing type enum for categorization and filtering:

export const ClothType = {
  TOP: 'TOP',
  BOTTOM: 'BOTTOM',
  SHOE_ACCESSORY: 'SHOE_ACCESSORY',
  FULL_BODY: 'FULL_BODY',
  UNDERWEAR_FULL_BODY: 'UNDERWEAR_FULL_BODY',
  UNDERWEAR_BOTTOM: 'UNDERWEAR_BOTTOM',
  UNDERWEAR_TOP: 'UNDERWEAR_TOP',
  WETSUIT_FULL_BODY: 'WETSUIT_FULL_BODY',
  WETSUIT_BOTTOM: 'WETSUIT_BOTTOM',
  WETSUIT_TOP: 'WETSUIT_TOP',
} as const;

// Usage examples:
ClothType.TOP         // For shirts, blouses, jackets
ClothType.BOTTOM      // For pants, skirts, shorts
ClothType.FULL_BODY   // For dresses, jumpsuits
ClothType.SHOE_ACCESSORY // For shoes, accessories

GroupedLookResponseDto

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | id | string | Yes | Unique identifier for this fashion look (UUID).Use this to fetch the look again or reference it in other operations. | | tenantId | number | Yes | Tenant ID that owns this look. | | gender | Gender | Yes | Target gender for this look (MALE or FEMALE).Use to filter or categorize looks by target audience. | | ageGroup | AgeGroup | Yes | Target age group for this look.Use to show age-appropriate looks to users. | | style | Style | Yes | Style category of this look.Use to filter looks by style preference or display style tags. | | collection | Collection | Yes | Seasonal collection this look belongs to.Use to show seasonal looks or filter by collection. | | rate | number | Yes | Quality rating of this look (0-5).Higher ratings indicate better quality. Use to sort or filter by quality. | | status | GroupedLookStatus | Yes | Current status of this look.Only show 'enabled' looks to users, hide 'disabled' ones. | | timestamp | string | Yes | When this look was created (ISO 8601 format).Use to sort by date or show "new" looks. | | tryons | TryonGroup[] | Yes | All virtual try-on images organized by body type and skin tone.Iterate through this to display all try-on variations. Each group representsa body type, and each group contains try-ons for different skin tones. | | feedback | GroupedLookFeedbackResponseDto | No | User feedback for this look, if any has been submitted.Use to display feedback or quality metrics to users. |

GroupedLooksListResponse

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | data | GroupedLookResponseDto[] | Yes | Fashion looks for the current page.Display these looks to users. Each look contains styled outfits with try-on images. | | total | number | Yes | Total number of looks matching your filters across all pages.Use this to show "Showing X of Y looks" or calculate total pages. | | pagination | PaginationInfo | Yes | Pagination information for navigating between pages.Use this to implement pagination controls in your UI. |

PaginationInfo

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | limit | number | Yes | Number of looks returned in this page.Matches the limit parameter you sent in the request. | | offset | number | Yes | Number of looks skipped to reach this page.Matches the offset parameter you sent in the request. | | hasNext | boolean | Yes | Whether there are more looks available after this page.Use this to show/hide "Next" button or load more functionality. | | hasPrevious | boolean | Yes | Whether there are looks before this page.Use this to show/hide "Previous" button. |

TryonGroup

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | bmi | string | Yes | Body type identifier (e.g., 'slim', 'regular', 'plus'). | | skinTones | TryonDetails[] | Yes | Try-on images for different skin tones within this body type.Iterate through these to show all skin tone variations for the same body type. |

TryonDetails

| Field | Type | Required | Description | | ----- | ---- | :------: | ----------- | | skinTone | string | Yes | Skin tone identifier (e.g., 'light', 'brown', 'dark'). | | tryonDetails | Record<string, any> | Yes | Try-on image data including URL and rendering metadata.Contains the actual image URL and other properties needed to display the try-on. |