sizebay-core-sdk 1.2.1 → 1.3.0-dev.1

package/README.md

@@ -51,11 +51,11 @@ Sends an event to the designated API endpoint, returning a standardized response
 
 | Property    | Type                          | Required | Description                                                           |
 |-------------|-------------------------------|----------|-----------------------------------------------------------------------|
-| **sid**     | `string`                      | Yes      | Unique session identifier.                                            |
+| **sid**     | `string`                      | Yes      | Unique user identifier.                                            |
 | **tenantId**| `number`                      | Yes      | Identifier of the tenant (client) sending the event.                  |
-| **sessionId**| `number`                     | Yes      | Internal session identifier.                                          |
-| **permalink**| `string` (optional)          | No       | Product URL associated with the event. When the event is linked to product (e.g., ADD_TO_CART RECOMMENDATION_DONE), it is required.                              |
 | **properties**| `Record<string, JSONValue>` | Yes      | Object containing additional properties as key-value pairs.           |
+| **sessionId**| `number`                     | No       | Sizebay session identifier.                                          |
+| **permalink**| `string` (optional)          | No       | Product URL associated with the event. When the event is linked to product (e.g., ADD_TO_CART RECOMMENDATION_DONE), it is required.                              |
 
 **Returns**
 
@@ -123,32 +123,46 @@ async function trackEvent() {
 trackEvent();
 ```
 
-## AI Image Service Module
+Thought for a couple of seconds
 
-### `getSimilarProducts(params: GetSimilarProductsParams): Promise<GetSimilarProductsResponse>`
 
-Fetches similar products based on the given parameters, returning a paginated result.
+Segue a documentação atualizada com os parâmetros `filterByWhatFitsMe`, `personaHash` e o campo de resposta `suitableSizes`.
 
-#### Parameters
+---
 
-| Parameter        | Type                           | Required | Description                                                                              |
-|------------------|--------------------------------|:--------:|------------------------------------------------------------------------------------------|
-| `tenantId`       | `number`                       | **Yes**  | The tenant ID that initiated the request.                                               |
-| `collectionName` | `string`                       | **Yes**  | The name of the relevant product collection.                                            |
-| `sessionId`      | `number`                       | **Yes**  | The session ID, typically required for internal event tracking.                         |
-| `permalink`      | `string`                       | **Yes**  | A permanent link representing the main product.                                         |
-| `page`           | `number` (optional)            | No       | Page number for pagination.                                                             |
-| `perPage`        | `number` (optional)            | No       | Number of items per page.                                                               |
+Thought for a couple of seconds
 
-#### Returns
 
-**`Promise<GetSimilarProductsResponse>`**  
-An object containing:
+Here’s a cleaned-up, fully English version with consistent terminology, corrected typos, and improved clarity:
 
-- `data`: An array of `Product` objects.
-- `page`: The current page number.
-- `perPage`: The number of items per page.
-- `total`: The total number of items available.
+---
+
+## AI Image Service Module
+
+### `getSimilarProducts(params: GetSimilarProductsParams): Promise<GetSimilarProductsResponse>`
+
+Fetch similar products based on the given parameters, returning a paginated result and—when requested—size recommendations.
+
+#### Parameters
+
+| Parameter            | Type      | Required | Description                                                                  |
+| -------------------- | --------- | :------: | ---------------------------------------------------------------------------- |
+| `tenantId`           | `number`  |  **Yes** | Tenant ID initiating the request.                                            |
+| `collectionName`     | `string`  |  **Yes** | Name of the product collection.                                              |
+| `sessionId`          | `number`  |  **Yes** | Session ID for internal event tracking.                                      |
+| `permalink`          | `string`  |  **Yes** | Permanent link (URL) of the main product.                                    |
+| `page`               | `number`  |    No    | Page number (pagination).                                                    |
+| `perPage`            | `number`  |    No    | Number of items per page.                                                    |
+| `filterByWhatFitsMe` | `boolean` |    No    | If `true`, apply “What Fits Me” size filter. Defaults to `false`.            |
+| `personaHash`        | `string`  |  Cond.\* | Persona hash from Size & Fit; **required** when `filterByWhatFitsMe = true`. |
+
+> **Returns:** `Promise<GetSimilarProductsResponse>`
+>
+> * `data`: `Product[]` — Array of product objects.
+> * `page`: `number` — Current page.
+> * `perPage`: `number` — Items per page.
+> * `total`: `number` — Total available items.
+> * `suitableSizes?`: `SuitableSizeDto[]` — Size recommendations (only if `filterByWhatFitsMe = true`).
 
 #### Example
 
@@ -157,48 +171,51 @@ import { GetSimilarProductsParams } from 'sizebay-core-sdk';
 
 const params: GetSimilarProductsParams = {
   tenantId: 123,
-  permalink: 'https://example.com/product',
   collectionName: 'summer-collection',
   sessionId: 456,
+  permalink: 'https://example.com/product',
   page: 1,
   perPage: 10,
+  filterByWhatFitsMe: true,
+  personaHash: '6b4f2e8b-0bb2-43d1-8bea-7f6d1c5d5a71',
 };
 
-async function fetchSimilarProducts() {
+async function fetchSimilar() {
   try {
     const response = await client.getSimilarProducts(params);
-    console.log('Similar products:', response.data);
-  } catch (error: any) {
-    console.error('Error fetching similar products:', error.message);
+    console.log('Products:', response.data);
+    if (response.suitableSizes) {
+      console.log('Recommended sizes:', response.suitableSizes);
+    }
+  } catch (err: any) {
+    console.error('Error:', err.message);
   }
 }
 
-fetchSimilarProducts();
+fetchSimilar();
 ```
 
 ---
 
-### `GetRecommendedSizeByProducts(payload: GetRecommendedSizeByProductsParams): Promise<GetRecommendedSizeByProductsResponse[]>`
+### `getRecommendedSizeByProducts(payload: GetRecommendedSizeByProductsParams): Promise<GetRecommendedSizeByProductsResponse[]>`
 
-Retrieves the recommended sizes for one or more products based on the provided parameters.
+Retrieve recommended sizes for multiple products.
 
 #### Parameters
 
-| Parameter    | Type                    | Required | Description                                                                                                    |
-|-------------:|-------------------------|:--------:|----------------------------------------------------------------------------------------------------------------|
-| `tenantId`   | `number`               | **Yes**  | The tenant ID that initiated the request.                                                                      |
-| `sid`        | `string` (optional)    | No       | The session ID for internal events, if needed.                                                                 |
-| `sizeSystem` | `string`               | **Yes**  | The size system (e.g., 'BR', 'US', 'EU').                                                                      |
-| `permalinks` | `string[]`             | **Yes**  | A list of product permalinks for which size recommendations are requested.                                     |
-
-#### Returns
+| Parameter    | Type       | Required | Description                                      |
+| ------------ | ---------- | :------: | ------------------------------------------------ |
+| `tenantId`   | `number`   |  **Yes** | Tenant ID initiating the request.                |
+| `sid`        | `string`   |    No    | Session ID for internal events.                  |
+| `sizeSystem` | `string`   |  **Yes** | Size system code (e.g., `'BR'`, `'US'`, `'EU'`). |
+| `permalinks` | `string[]` |  **Yes** | Array of product permalinks.                     |
 
-**`Promise<GetRecommendedSizeByProductsResponse[]>`**  
-An array of objects, each containing:
-
-- `id`: The internal identifier for the product.
-- `permalink`: The product permalink from the request.
-- `recommendedSize`: The recommended size (`string`) or `null` if no recommendation is available.
+> **Returns:** `Promise<GetRecommendedSizeByProductsResponse[]>`
+> Each item includes:
+>
+> * `id`: `string` — Internal product identifier.
+> * `permalink`: `string` — Product’s permalink.
+> * `recommendedSize`: `string \| null` — The suggested size or `null` if unavailable.
 
 #### Example
 
@@ -215,46 +232,43 @@ const payload: GetRecommendedSizeByProductsParams = {
   ],
 };
 
-async function fetchRecommendedSizes() {
+async function fetchSizes() {
   try {
-    const response = await client.GetRecommendedSizeByProducts(payload);
-    response.forEach((item) => {
-      console.log(`Product ID: ${item.id}, Recommended Size: ${item.recommendedSize}`);
+    const recommendations = await client.getRecommendedSizeByProducts(payload);
+    recommendations.forEach(({ id, recommendedSize }) => {
+      console.log(`Product ${id}: ${recommendedSize}`);
     });
-  } catch (error: any) {
-    console.error('Error fetching recommended product sizes:', error.message);
+  } catch (err: any) {
+    console.error('Error:', err.message);
   }
 }
 
-fetchRecommendedSizes();
-``` 
----
+fetchSizes();
+```
 
 ---
 
 ### `getComplementaryProducts(params: GetComplementaryProductsParams): Promise<GetComplementaryProductsResponse>`
 
-Fetches complementary product recommendation pairs based on the given parameters.
+Fetch complementary product pairs, optionally filtered by size.
 
 #### Parameters
 
-| Parameter        | Type     | Required | Description                                                        |
-|------------------|----------|:--------:|--------------------------------------------------------------------|
-| `tenantId`       | `string` | **Yes**  | The tenant ID that initiated the request.                          |
-| `collectionName` | `string` | **Yes**  | The Qdrant collection name where embeddings are stored.           |
-| `sessionId`      | `string` | **Yes**  | The session ID for internal event tracking.                       |
-| `permalink`      | `string` | **Yes**  | A permanent link representing the base product.                   |
-
-
-#### Returns
-
-**`Promise<GetComplementaryProductsResponse>`**  
-An object containing:
-
-- `baseProduct`: The original product used as the seed for recommendations (`ProductResponseDto`).
-- `complementary`: An array of recommendation pairs (`ComplementaryPairDto[]`), each with:
-  - `first`: The first complementary product.
-  - `secondary`: The second complementary product.
+| Parameter            | Type      | Required | Description                                                                  |
+| -------------------- | --------- | :------: | ---------------------------------------------------------------------------- |
+| `tenantId`           | `string`  |  **Yes** | Tenant ID initiating the request.                                            |
+| `collectionName`     | `string`  |  **Yes** | Qdrant collection name for embeddings.                                       |
+| `sessionId`          | `string`  |  **Yes** | Session ID for event tracking.                                               |
+| `permalink`          | `string`  |  **Yes** | Permanent link (URL) of the base product.                                    |
+| `limit`              | `number`  |    No    | Maximum number of complementary pairs.                                       |
+| `filterByWhatFitsMe` | `boolean` |    No    | If `true`, apply “What Fits Me” size filter. Defaults to `false`.            |
+| `personaHash`        | `string`  |  Cond.\* | Persona hash from Size & Fit; **required** when `filterByWhatFitsMe = true`. |
+
+> **Returns:** `Promise<GetComplementaryProductsResponse>`
+>
+> * `baseProduct`: `ProductDto` — Seed product.
+> * `complementary`: `ComplementaryPairDto[]` — Array of pairs (`first` & `secondary`).
+> * `suitableSizes?`: `SuitableSizeDto[]` — Size recommendations when filtering by persona.
 
 #### Example
 
@@ -265,23 +279,64 @@ const params: GetComplementaryProductsParams = {
   tenantId: '123',
   collectionName: 'summer-collection',
   sessionId: 'abc-session-456',
-  permalink: 'https://example.com/product/base-1'
+  permalink: 'https://example.com/product/base-1',
+  limit: 5,
+  filterByWhatFitsMe: true,
+  personaHash: '6b4f2e8b-0bb2-43d1-8bea-7f6d1c5d5a71',
 };
 
-async function fetchComplementaryPairs() {
+async function fetchPairs() {
   try {
     const response = await client.getComplementaryProducts(params);
-    console.log('Base product:', response.baseProduct);
+    console.log('Base:', response.baseProduct);
     response.complementary.forEach(({ first, secondary }) => {
-      console.log(`Pair: ${first.title} ↔ ${secondary.title}`);
+      console.log(`${first.title} ↔ ${secondary.title}`);
     });
-  } catch (error: any) {
-    console.error('Error fetching complementary products:', error.message);
+    if (response.suitableSizes) {
+      console.log('Size recommendations:', response.suitableSizes);
+    }
+  } catch (err: any) {
+    console.error('Error:', err.message);
   }
 }
 
-fetchComplementaryPairs();
+fetchPairs();
 ```
+
+---
+
+## DTO Definitions
+
+### `Product` / `ProductDto`
+
+| Field                  | Type                | Description                                 |
+| ---------------------- | ------------------- | ------------------------------------------- |
+| `id`                   | `string`            | Unique product identifier.                  |
+| `title`                | `string`            | Product title.                              |
+| `productType`          | `string`            | Product category/type.                      |
+| `link`                 | `string`            | Product page URL.                           |
+| `imageLink`            | `string`            | Main image URL.                             |
+| `gender`               | `string`            | Gender segment (`"male"`, `"female"`, etc). |
+| `availability`         | `string`            | Stock status (e.g., `"in stock"`).          |
+| `productHash`          | `string`            | Hash for deduplication.                     |
+| `price`                | `string`            | Formatted price (e.g., `"29.99 USD"`).      |
+| `salePrice?`           | `string`            | Promotional price, if applicable.           |
+| `itemGroupId`          | `string`            | Variant group ID.                           |
+| `brand`                | `string`            | Brand name.                                 |
+| `color`                | `string`            | Color description.                          |
+| `gtin`                 | `string`            | Global Trade Item Number.                   |
+| `additionalImageLinks` | `string[]`          | Other image URLs.                           |
+| `suitableSizes?`       | `SuitableSizeDto[]` | Size recommendations (when filtering).      |
+
+
+### `SuitableSizeDto`
+
+| Field         | Type      | Description                                                             |
+| ------------- | --------- | ----------------------------------------------------------------------- |
+| `size`        | `string`  | The recommended size label (e.g., `"S"`, `"M"`, `"L"`).                 |
+| `comfortable` | `number`  | A comfort score (0–1) indicating how well this size fits the persona.  |
+| `value?`      | `number`  | Optional secondary metric (e.g., normalized preference or confidence).  |
+
 ---
 
 ## Session Module

package/dist/types/ai-image-service.types.d.ts

@@ -5,8 +5,25 @@ export interface GetSimilarProductsParams {
     permalink: string;
     page?: number;
     perPage?: number;
+    filterByWhatFitsMe?: boolean;
+    personaHash?: string;
 }
-export interface Product {
+export interface GetComplementaryProductsParams {
+    tenantId: string;
+    collectionName: string;
+    sessionId: string;
+    permalink: string;
+    limit?: number;
+    filterByWhatFitsMe?: boolean;
+    personaHash?: string;
+}
+export interface GetRecommendedSizeByProductsParams {
+    tenantId: number;
+    sid?: string;
+    sizeSystem: string;
+    permalinks: string[];
+}
+export interface ProductDto {
     id: string;
     title: string;
     productType: string;
@@ -22,52 +39,28 @@ export interface Product {
     color: string;
     gtin: string;
     additionalImageLinks: string[];
+    suitableSizes?: Array<{
+        size: string;
+        comfortable: number;
+        value?: number;
+    }>;
 }
 export interface GetSimilarProductsResponse {
-    data: Product[];
+    data: ProductDto[];
     page: number;
     perPage: number;
     total: number;
 }
-export interface GetRecommendedSizeByProductsParams {
-    tenantId: number;
-    sid?: string;
-    sizeSystem: string;
-    permalinks: string[];
-}
 export interface GetRecommendedSizeByProductsResponse {
     id: string;
     permalink: string;
     recommendedSize: string | null;
 }
-export interface ProductComplementaryResponseDto {
-    id: string;
-    tenantId: number;
-    title: string;
-    productType: string;
-    link: string;
-    imageLink: string;
-    gender: string;
-    availability: string;
-    productHash: string;
-    price: string;
-    itemGroupId: string;
-    brand: string;
-    color: string;
-    gtin: string;
-    additionalImageLinks: string[];
-}
-export interface GetComplementaryProductsParams {
-    tenantId: string;
-    collectionName: string;
-    sessionId: string;
-    permalink: string;
-}
 export interface ComplementaryPairDto {
-    first: ProductComplementaryResponseDto;
-    secondary: ProductComplementaryResponseDto;
+    first: ProductDto;
+    secondary: ProductDto;
 }
 export interface GetComplementaryProductsResponse {
-    baseProduct: ProductComplementaryResponseDto;
+    baseProduct: ProductDto;
     complementary: ComplementaryPairDto[];
 }

package/dist/types/event.types.d.ts

@@ -4,9 +4,9 @@ export type JSONValue = string | number | boolean | null | JSONValue[] | {
 export interface TrackData {
     sid: string;
     tenantId: number;
-    sessionId: number;
-    permalink?: string;
     properties: Record<string, JSONValue>;
+    sessionId?: number;
+    permalink?: string;
 }
 export interface DataEventPayload extends TrackData {
     eventName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sizebay-core-sdk",
-  "version": "1.2.1",
+  "version": "1.3.0-dev.1",
   "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",