sizebay-core-sdk 1.11.0-dev.1 → 1.11.0-dev.2

package/README.md

@@ -296,6 +296,133 @@ console.log(imgComp.baseProduct, imgComp.complementary);
 
 ---
 
+## Permalink Search Services
+
+### `searchSimilarByPermalink(payload: GetSimilarByPermalinkBodyDto): Promise<GetSimilarProductsResponse>`
+
+Find visually similar items from a product permalink or productId using AI-powered image analysis.
+
+#### Payload
+
+<!-- DOCGEN:params GetSimilarByPermalinkBodyDto -->
+| 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). |
+| `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). |
+<!-- /DOCGEN -->
+
+#### Returns
+
+<!-- DOCGEN:returns GetSimilarProductsResponse -->
+> **`GetSimilarProductsResponse`**
+> * `data`: `ProductDto[]` — An array of products that are visually similar to the reference item.<br>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,<br>which may affect personalized results.
+<!-- /DOCGEN -->
+
+#### Example
+
+```typescript
+const similarProducts = await client.searchSimilarByPermalink({
+  tenantId: 123,
+  collectionName: "products",
+  sid: "session123",
+  sizeSystem: "BR",
+  locale: "pt-BR",
+  currency: "BRL",
+  permalink: "https://example.com/products/red-dress-456",
+  similarityThreshold: 0.7,
+  page: 1,
+  perPage: 10,
+  style: "Casual",
+  color: "red"
+});
+console.log(similarProducts.data);
+```
+
+### `searchComplementaryByPermalink(payload: GetComplementaryByPermalinkBodyDto): Promise<GetComplementaryProductsResponse>`
+
+Find complementary products from a product permalink or productId using AI-powered analysis.
+
+#### Payload
+
+<!-- DOCGEN:params GetComplementaryByPermalinkBodyDto -->
+| Field | Type | Required | Description |
+| ----- | ---- | :------: | ----------- |
+| `permalink` | string |  No  | The URL permalink of the reference product. |
+| `productId` | string |  No  | Product ID (either permalink or productId must be provided). |
+| `similarityThreshold` | number |  Yes  | The minimum similarity score (0-1) for recommended products.<br>A higher value yields more similar items, while a lower value provides more variety. |
+| `baseClothType` | ClothType |  No  | Base cloth type for the reference product. |
+| `targetClothType` | ClothType |  No  | Target cloth type for complementary products. |
+| `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. |
+| `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). |
+<!-- /DOCGEN -->
+
+#### Returns
+
+<!-- DOCGEN:returns GetComplementaryProductsResponse -->
+> **`GetComplementaryProductsResponse`**
+> * `baseProduct`: `ProductDto` — The reference product used to generate recommendations.<br>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.<br>If true, personalization may be affected.
+<!-- /DOCGEN -->
+
+#### Example
+
+```typescript
+const complementaryProducts = await client.searchComplementaryByPermalink({
+  tenantId: 123,
+  collectionName: "products",
+  sid: "session123",
+  sizeSystem: "BR",
+  locale: "pt-BR",
+  currency: "BRL",
+  productId: "12345",
+  similarityThreshold: 0.3,
+  baseClothType: ClothType.BOTTOM,
+  targetClothType: ClothType.TOP,
+  page: 1,
+  perPage: 10,
+  style: "Casual",
+  color: "blue"
+});
+console.log(complementaryProducts.baseProduct, complementaryProducts.complementary);
+```
+
+---
+
 ## Session Module
 
 Retrieves and caches session context:

package/package.json

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