sizebay-core-sdk 1.10.0-dev.2 → 1.10.0-dev.3

package/README.md

@@ -93,10 +93,10 @@ Fetch products similar to a reference.
 <!-- DOCGEN:params GetSimilarProductsParams -->
 | Field | Type | Required | Description |
 | ----- | ---- | :------: | ----------- |
-| `permalink` | string |  Yes  | Product permalink used as reference for similarity. |
-| `page` | number |  No  | Pagination: current page (optional). |
-| `perPage` | number |  No  | Pagination: number of items per page (optional). |
-| `similarityThreshold` | number |  No  | Minimum similarity threshold (0 to 1). Default value: 0.5 |
+| `permalink` | string |  Yes  | The URL permalink of the reference product for the similarity search. |
+| `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. |
@@ -111,11 +111,13 @@ Fetch products similar to a reference.
 
 <!-- DOCGEN:returns GetSimilarProductsResponse -->
 > **`GetSimilarProductsResponse`**
-> * `data`: `ProductDto[]` — Array of products that match the visual similarity criteria. Ordered by relevance/similarity score, with most similar items first.
-> * `page`: `number` — Current page number in the paginated result set. Used for navigation through large result sets.
-> * `perPage`: `number` — Number of items returned per page. Defines the size of each page in the pagination.
-> * `total`: `number` — Total number of products matching the similarity criteria. Across all pages, useful for calculating total pages.
-> * `invalidPersonaHash`: `boolean` — Indicates if the provided persona hash is invalid or expired. When true, What Fits Me filtering was requested but couldn't be applied.
+> * `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.
 <!-- /DOCGEN -->
 
 #### Example
@@ -145,8 +147,10 @@ Retrieve pairs of complementary products.
 <!-- DOCGEN:params GetComplementaryProductsParams -->
 | Field | Type | Required | Description |
 | ----- | ---- | :------: | ----------- |
-| `permalink` | string |  Yes  | URL of the reference product. |
-| `similarityThreshold` | number |  Yes  | Minimum similarity score (0-1) for results. Default value: 0.2 |
+| `permalink` | string |  Yes  | The URL permalink of the reference product.
+Its style, color, and category are used to find matching items. |
+| `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. |
@@ -161,9 +165,11 @@ Retrieve pairs of complementary products.
 
 <!-- DOCGEN:returns GetComplementaryProductsResponse -->
 > **`GetComplementaryProductsResponse`**
-> * `baseProduct`: `ProductDto` — The reference product used in the lookup.
-> * `complementary`: `ComplementaryPairDto[]` — List of recommended product pairs.
-> * `invalidPersonaHash`: `boolean` — Whether the persona hash is invalid.
+> * `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.
 <!-- /DOCGEN -->
 
 #### Example
@@ -199,7 +205,7 @@ Find visually similar items from an uploaded image.
 | `style` | string |  No  | Preferred style hint. |
 | `color` | string |  No  | Main color of interest. |
 | `productClass` | ProductClass |  No  | Target product class. |
-| `clothType` | string |  No  | Target cloth type. |
+| `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). |
@@ -242,16 +248,16 @@ Get products that complete a look from an image.
 <!-- DOCGEN:params GetComplementaryByImageBodyDto -->
 | Field | Type | Required | Description |
 | ----- | ---- | :------: | ----------- |
-| `similarityThreshold` | number |  Yes  | Minimum similarity score (0-1) for results. |
-| `baseClothType` | string |  Yes  | Type of the base product in the image. |
-| `targetClothType` | string |  Yes  | Type of complementary products to find. |
+| `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` | string |  No  | Target cloth type. |
+| `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. |
@@ -268,12 +274,12 @@ Get products that complete a look from an image.
 
 <!-- DOCGEN:returns GetComplementaryProductsByImageResponse -->
 > **`GetComplementaryProductsByImageResponse`**
-> * `baseProduct`: `ProductDto` — Main product found from image.
-> * `complementary`: `ProductDto[]` — Complementary products recommended.
-> * `page`: `number` — Pagination - current page.
-> * `perPage`: `number` — Pagination - per page.
-> * `total`: `number` — Pagination - total results.
-> * `invalidPersonaHash`: `boolean` — Whether the persona hash is invalid.
+> * `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.
 <!-- /DOCGEN -->
 
 #### Example
@@ -309,8 +315,8 @@ Fetches or reuses session context.
 
 <!-- DOCGEN:returns SessionContext -->
 > **`SessionContext`**
-> * `sid`: `string` — Session identifier (catalog user ID) used for subsequent API calls. This value should be passed as the 'sid' parameter in tracking and recommendation requests.
-> * `sessionId`: `number` — Unique numeric identifier for this session instance. Used internally by Sizebay for session management and analytics.
+> * `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.
 <!-- /DOCGEN -->
 
 #### Example
@@ -336,20 +342,34 @@ Sends user profile data. Uses cached `sid` if not provided.
 <!-- DOCGEN:params 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. |
+| `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. |
+| `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. |
 <!-- /DOCGEN -->
 
 #### Example
@@ -385,24 +405,25 @@ await client.sendProfile(profilePayload);
 <!-- DOCGEN:params ProductDto -->
 | Field | Type | Required | Description |
 | ----- | ---- | :------: | ----------- |
-| `id` | string |  Yes  | Unique product identifier from the e-commerce platform (e.g., Shopify product ID). |
-| `title` | string |  Yes  | Product display name or title as shown in the store. |
-| `productType` | string |  Yes  | Hierarchical product category path using standardized format. |
-| `link` | string |  Yes  | Complete URL to the product page in the e-commerce store. |
-| `imageLink` | string |  Yes  | URL of the main product image used for AI analysis and display. |
-| `gender` | string |  Yes  | Target gender for the product using standardized values. |
-| `availability` | string |  Yes  | Current stock availability status of the product. |
-| `productHash` | string |  Yes  | SHA-256 hash used for product identification, caching, and deduplication in Sizebay's systems. |
-| `price` | string |  Yes  | Product price including currency code in the format "value CURRENCY". |
-| `salePrice` | string |  Yes  | Sale or discounted price including currency code. Same format as regular price. |
-| `itemGroupId` | string |  Yes  | Identifier used to group product variations (different sizes/colors of the same item). Often matches the main product ID when no variations exist. |
-| `brand` | string |  Yes  | Product brand name in uppercase format. |
-| `color` | string |  Yes  | Product color specification - can be a color name or internal color code. |
-| `style` | string |  Yes  | Product style identifier or description used for categorization and filtering. |
-| `gtin` | string |  Yes  | Global Trade Item Number - unique product identifier for retail tracking. Often matches the product ID in e-commerce platforms. |
-| `additionalImageLinks` | string[] |  Yes  | Array of additional product image URLs for comprehensive visual analysis. Listed in order of priority/relevance for AI processing. |
-| `suitableSizes` | SuitableSizeDto[] |  No  | Size recommendations with comfort scores generated by Sizebay's What Fits Me technology. Only populated when What Fits Me filtering is enabled and user profile is available. |
-| `clothType` | string |  No  | Standardized clothing type classification used for size table matching and recommendations. |
+| `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. |
 <!-- /DOCGEN -->
 
 #### `TrackData`
@@ -410,10 +431,10 @@ await client.sendProfile(profilePayload);
 <!-- DOCGEN:params TrackData -->
 | Field | Type | Required | Description |
 | ----- | ---- | :------: | ----------- |
-| `sid` | string |  Yes  | Session identifier obtained from Sizebay's session service. This is the catalog user ID returned by the session endpoint. |
-| `tenantId` | number |  Yes  | Unique identifier for the client/tenant using Sizebay's services. Each e-commerce partner has their own tenant ID. |
-| `properties` | Record<string, JSONValue> |  Yes  | Flexible key-value map containing event-specific data and context. Can include product information, user actions, custom metrics, etc. |
-| `permalink` | string |  No  | URL of the product page associated with this event. Required for product-related events like "RECOMMENDATION_DONE", "ADD_TO_CART". Optional for general tracking events. |
+| `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. |
 <!-- /DOCGEN -->
 
 ### `SuitableSizeDto`
@@ -421,9 +442,14 @@ await client.sendProfile(profilePayload);
 <!-- DOCGEN:params 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: - 0.0 = Very uncomfortable fit - 0.5 = Adequate fit - 1.0 = Perfect comfortable fit |
-| `value` | boolean |  No  | Boolean indicator of whether this size is considered suitable for the user. Based on comfort threshold and fit analysis algorithms. |
+| `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:
+- 0.0 = Very uncomfortable fit
+- 0.5 = Adequate fit
+- 1.0 = Perfect comfortable fit |
+| `value` | boolean |  No  | Boolean indicator of whether this size is considered suitable for the user.
+Based on comfort threshold and fit analysis algorithms. |
 <!-- /DOCGEN -->
 
 ### `ComplementaryPairDto`
@@ -431,6 +457,33 @@ await client.sendProfile(profilePayload);
 <!-- DOCGEN:params ComplementaryPairDto -->
 | Field | Type | Required | Description |
 | ----- | ---- | :------: | ----------- |
-| `first` | ProductDto |  Yes  | Primary product in the complementary relationship. This is typically the base item that the user is viewing or interested in. |
-| `secondary` | ProductDto |  No  | Secondary product that complements the first item. May be null if no suitable complementary item is found. |
-<!-- /DOCGEN -->
+| `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. |
+<!-- /DOCGEN -->
+
+### `ClothType`
+
+Standardized clothing type enum for categorization and filtering:
+
+```typescript
+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
+```

package/dist/types/ai-image/base/base-image-search.dto.d.ts

@@ -1,5 +1,6 @@
 import { BaseSearchParams } from './base-search.dto';
 import { ProductClass } from '../../common/product-class.type';
+import { ClothType } from '../../common/cloth-type.type';
 export interface BaseImageSearchParams extends BaseSearchParams {
     image: string;
     ageRange?: string;
@@ -7,7 +8,7 @@ export interface BaseImageSearchParams extends BaseSearchParams {
     style?: string;
     color?: string;
     productClass?: ProductClass;
-    clothType?: string;
+    clothType?: ClothType;
     page?: number;
     perPage?: number;
     similarityThreshold?: number;

package/dist/types/ai-image/params/get-complementary-by-image.dto.d.ts

@@ -1,6 +1,7 @@
 import { BaseImageSearchParams } from '../base/base-image-search.dto';
+import { ClothType } from '../../common/cloth-type.type';
 export interface GetComplementaryByImageBodyDto extends BaseImageSearchParams {
     similarityThreshold: number;
-    baseClothType: string;
-    targetClothType: string;
+    baseClothType: ClothType;
+    targetClothType: ClothType;
 }

package/dist/types/common/cloth-type.type.d.ts

@@ -1,13 +1,13 @@
 export declare const ClothType: {
-    TOP: string;
-    BOTTOM: string;
-    SHOE_ACCESSORY: string;
-    FULL_BODY: string;
-    UNDERWEAR_FULL_BODY: string;
-    UNDERWEAR_BOTTOM: string;
-    UNDERWEAR_TOP: string;
-    WETSUIT_FULL_BODY: string;
-    WETSUIT_BOTTOM: string;
-    WETSUIT_TOP: string;
+    readonly TOP: "TOP";
+    readonly BOTTOM: "BOTTOM";
+    readonly SHOE_ACCESSORY: "SHOE_ACCESSORY";
+    readonly FULL_BODY: "FULL_BODY";
+    readonly UNDERWEAR_FULL_BODY: "UNDERWEAR_FULL_BODY";
+    readonly UNDERWEAR_BOTTOM: "UNDERWEAR_BOTTOM";
+    readonly UNDERWEAR_TOP: "UNDERWEAR_TOP";
+    readonly WETSUIT_FULL_BODY: "WETSUIT_FULL_BODY";
+    readonly WETSUIT_BOTTOM: "WETSUIT_BOTTOM";
+    readonly WETSUIT_TOP: "WETSUIT_TOP";
 };
 export type ClothType = (typeof ClothType)[keyof typeof ClothType];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sizebay-core-sdk",
-  "version": "1.10.0-dev.2",
+  "version": "1.10.0-dev.3",
   "description": "A SDK designed for integrating multiple services (such as event tracking, AI services, etc.) into your application.",
   "main": "dist/sizebay-core-sdk.umd.js",
   "module": "dist/sizebay-core-sdk.es.js",