@hellena-sdk/hellena 1.0.7 → 1.0.9

package/README.md

@@ -197,7 +197,8 @@ Consulta [Pagamentos](docs/payments.md) para os parâmetros e o formato de respo
 | `hellena.product` | Listar, pesquisar e consultar produtos. |
 | `hellena.order` | Criar encomendas, renovar o ID de transação, calcular portes e descontos de cupões. |
 | `hellena.comment` | Consultar, criar, atualizar e eliminar comentários. |
-| `hellena.rating` | Consultar resumos e avaliações, criar ou eliminar avaliações. |
+| `hellena.rating` | Consultar resumos completos, listar, criar e eliminar avaliações. |
+| `hellena.category` | Listar categorias e consultar os produtos associados a cada categoria. |
 | `hellena.payment` | Consultar métodos de pagamento e criar pagamentos WiPay suportados. |
 | `hellena.organization` | Consultar informações da organização e links sociais. |
 | `hellena.sendRestRequest()` | Fazer pedidos REST a endpoints que ainda não têm método dedicado. |
@@ -275,7 +276,8 @@ A documentação detalhada e os exemplos por recurso estão em [`docs/README.md`
 | [Produtos](docs/products.md) | Listagem, pesquisa e detalhe |
 | [Encomendas](docs/orders.md) | Checkout, entrega, cupões e transações |
 | [Comentários](docs/comments.md) | Consulta e gestão de comentários |
-| [Avaliações](docs/ratings.md) | Resumos e gestão de avaliações |
+| [Avaliações](docs/ratings.md) | Resumos, distribuição por estrelas e gestão de avaliações |
+| [Categorias](docs/categories.md) | Listagem de categorias e produtos associados |
 | [Pagamentos](docs/payments.md) | Métodos de pagamento e WiPay |
 | [Organização](docs/organization.md) | Dados da organização e links sociais |
 | [REST, GraphQL e erros](docs/rest-graphql-errors.md) | Transporte genérico e tratamento de erros |

package/dist/main.d.ts

@@ -6,6 +6,7 @@ export declare class HellenaClient extends HellenaConnect {
     readonly comment: import("./resources/comment/comment.feature").CommentFeature;
     readonly rating: import("./resources/rating/rating.feature").RatingFeature;
     readonly payment: import("./resources/payment/payment.feature").PaymentFeature;
+    readonly category: import("./resources/category/category.feature").CategoryFeature;
     constructor(apiKey: string, options?: HellenaClientOptions);
 }
 export { HellenaAPIError, type HellenaClientOptions, type HellenaRequestOptions } from "./core/HellenaConnect";
@@ -15,3 +16,4 @@ export * from "./resources/comment/dto/comment.dto";
 export * from "./resources/rating/dto/rating.dto";
 export * from "./resources/payment/dto/payment.dto";
 export * from "./resources/organization/dto/organization.dto";
+export * from "./resources/category/dto/category.dto";

package/dist/main.js

@@ -153,15 +153,38 @@ class ProductService {
     this.connect = connect;
   }
   getAllProducts(params = {}) {
-    return this.connect.sendRestRequest("products/all", { query: { page: params.page, limit: params.limit } });
+    return this.connect.sendRestRequest("products/all", { query: this.toQuery(params) });
   }
   searchProducts(params) {
-    const { ref, ...pagination } = params;
-    return this.connect.sendRestRequest("products/search", { query: { ref, ...pagination } });
+    const { ref, ...filters } = params;
+    return this.connect.sendRestRequest("products/search", {
+      query: { ...this.toQuery(filters), ...ref ? { ref } : {} }
+    });
   }
   getProductById(id) {
     return this.connect.sendRestRequest(`products/${encodeURIComponent(id)}`);
   }
+  toQuery(params) {
+    const list = (value) => Array.isArray(value) ? value.join(",") : value;
+    return {
+      page: params.page,
+      limit: params.limit,
+      q: params.q,
+      category: params.category,
+      color: list(params.color),
+      brand: params.brand,
+      model: list(params.model),
+      material: list(params.material),
+      size: list(params.size),
+      tags: list(params.tags),
+      gender: list(params.gender),
+      minPrice: params.minPrice,
+      maxPrice: params.maxPrice,
+      inStock: params.inStock,
+      sortBy: params.sortBy,
+      sortOrder: params.sortOrder
+    };
+  }
 }
 
 // src/resources/product/product.feature.ts
@@ -171,13 +194,33 @@ class ProductFeature {
     this.service = service;
   }
   listProducts(params = {}) {
+    this.validatePriceRange(params);
     return this.service.getAllProducts(params);
   }
-  searchProducts(params) {
+  filterProducts(filters = {}) {
+    return this.listProducts(filters);
+  }
+  searchProducts(params = {}) {
+    this.validatePriceRange(params);
     return this.service.searchProducts(params);
   }
   getProductByIdOrSlug(id) {
-    return this.service.getProductById(id);
+    if (!id?.trim()) {
+      throw new Error("O ID ou slug do produto é obrigatório.");
+    }
+    return this.service.getProductById(id.trim());
+  }
+  validatePriceRange(params) {
+    const { minPrice, maxPrice } = params;
+    if (minPrice !== undefined && (!Number.isFinite(minPrice) || minPrice < 0)) {
+      throw new Error("minPrice deve ser um número maior ou igual a zero.");
+    }
+    if (maxPrice !== undefined && (!Number.isFinite(maxPrice) || maxPrice < 0)) {
+      throw new Error("maxPrice deve ser um número maior ou igual a zero.");
+    }
+    if (minPrice !== undefined && maxPrice !== undefined && minPrice > maxPrice) {
+      throw new Error("minPrice não pode ser superior a maxPrice.");
+    }
   }
 }
 
@@ -292,8 +335,11 @@ class RatingFeature {
   constructor(service) {
     this.service = service;
   }
-  getProductRatingSummary(stockId) {
-    return this.service.summary(stockId);
+  getProductRatingSummary(stockId, params = {}) {
+    return this.service.summary(stockId, params);
+  }
+  listProductRatings(params) {
+    return this.service.findMany(params);
   }
   getCustomerProductRating(params) {
     return this.service.findOne(params);
@@ -312,17 +358,21 @@ class RatingService {
   constructor(connect) {
     this.connect = connect;
   }
-  summary(stockId) {
-    return this.connect.sendRestRequest(`ratings/products/${encodeURIComponent(stockId)}/summary`);
+  summary(stockId, params = {}) {
+    return this.connect.sendRestRequest(`rating/products/${encodeURIComponent(stockId)}/summary`, { query: params });
+  }
+  findMany(params) {
+    const { stockId, ...pagination } = params;
+    return this.connect.sendRestRequest(`rating/products/${encodeURIComponent(stockId)}/ratings`, { query: pagination });
   }
   findOne(params) {
-    return this.connect.sendRestRequest(`ratings/products/${encodeURIComponent(params.stockId)}`, { query: { customerId: params.customerId } });
+    return this.connect.sendRestRequest(`rating/products/${encodeURIComponent(params.stockId)}`, { query: { customerId: params.customerId } });
   }
   create(data) {
-    return this.connect.sendRestRequest("ratings", { method: "POST", body: data });
+    return this.connect.sendRestRequest("rating", { method: "POST", body: data });
   }
   delete(id) {
-    return this.connect.sendRestRequest(`ratings/${encodeURIComponent(id)}`, { method: "DELETE" });
+    return this.connect.sendRestRequest(`rating/${encodeURIComponent(id)}`, { method: "DELETE" });
   }
 }
 
@@ -364,6 +414,42 @@ function PaymentModel(connect) {
   return new PaymentFeature(new PaymentService(connect));
 }
 
+// src/resources/category/category.feature.ts
+class CategoryFeature {
+  service;
+  constructor(service) {
+    this.service = service;
+  }
+  listCategories(params = {}) {
+    return this.service.findMany(params);
+  }
+  getCategoryByRef(params) {
+    return this.service.findOne(params);
+  }
+}
+
+// src/resources/category/service/category.ser.ts
+class CategoryService {
+  connect;
+  constructor(connect) {
+    this.connect = connect;
+  }
+  findMany(params = {}) {
+    return this.connect.sendRestRequest("category", {
+      query: { page: params.page, limit: params.limit, search: params.search }
+    });
+  }
+  findOne(params) {
+    const { ref, ...pagination } = params;
+    return this.connect.sendRestRequest(`category/${encodeURIComponent(ref)}`, { query: pagination });
+  }
+}
+
+// src/resources/category/category.model.ts
+function CategoryModel(connect) {
+  return new CategoryFeature(new CategoryService(connect));
+}
+
 // src/main.ts
 class HellenaClient extends HellenaConnect {
   product = ProductModel(this);
@@ -372,6 +458,7 @@ class HellenaClient extends HellenaConnect {
   comment = CommentModel(this);
   rating = RatingModel(this);
   payment = PaymentModel(this);
+  category = CategoryModel(this);
   constructor(apiKey, options = {}) {
     super(apiKey, options);
   }

package/dist/resources/category/category.feature.d.ts

@@ -0,0 +1,10 @@
+import type { CategoryListParams, CategoryProductsParams, CategoryWithProductsDTO, PaginatedCategoriesDTO } from "./dto/category.dto";
+import type { CategoryService } from "./service/category.ser";
+export declare class CategoryFeature {
+    private readonly service;
+    constructor(service: CategoryService);
+    /** Lista as categorias da organização com paginação e pesquisa opcional. */
+    listCategories(params?: CategoryListParams): Promise<PaginatedCategoriesDTO>;
+    /** Obtém uma categoria pelo ID ou identificador e os respetivos produtos paginados. */
+    getCategoryByRef(params: CategoryProductsParams): Promise<CategoryWithProductsDTO>;
+}

package/dist/resources/category/category.model.d.ts

@@ -0,0 +1,3 @@
+import type { HellenaConnect } from "../../core/HellenaConnect";
+import { CategoryFeature } from "./category.feature";
+export declare function CategoryModel(connect: HellenaConnect): CategoryFeature;

package/dist/resources/category/dto/category.dto.d.ts

@@ -0,0 +1,26 @@
+import type { PaginatedResponse, ProductDTO, PaginationMeta } from "../../product/dto/product.dto";
+export interface CategoryDTO {
+    id: string;
+    name: string;
+    category: string;
+    icon?: string | null;
+    image?: string | null;
+    organizationId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface CategoryListParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+}
+export interface CategoryProductsParams {
+    ref: string;
+    page?: number;
+    limit?: number;
+}
+export interface CategoryWithProductsDTO extends CategoryDTO {
+    products: ProductDTO[];
+    meta: PaginationMeta;
+}
+export type PaginatedCategoriesDTO = PaginatedResponse<CategoryDTO>;

package/dist/resources/category/service/category.ser.d.ts

@@ -0,0 +1,8 @@
+import type { HellenaConnect } from "../../../core/HellenaConnect";
+import type { CategoryListParams, CategoryProductsParams, CategoryWithProductsDTO, PaginatedCategoriesDTO } from "../dto/category.dto";
+export declare class CategoryService {
+    private readonly connect;
+    constructor(connect: HellenaConnect);
+    findMany(params?: CategoryListParams): Promise<PaginatedCategoriesDTO>;
+    findOne(params: CategoryProductsParams): Promise<CategoryWithProductsDTO>;
+}

package/dist/resources/product/dto/product.dto.d.ts

@@ -3,6 +3,7 @@ export interface PriceDTO {
     quantity: number;
     price: number;
     priceType?: string;
+    isPromotion?: boolean;
 }
 export interface ProductVariantDTO {
     id: string;
@@ -19,7 +20,7 @@ export interface ProductVariantDTO {
 }
 export interface ProductDTO {
     id: string;
-    slug?: string;
+    slug?: string | null;
     barcode: string | null;
     name: string;
     category: string | null;
@@ -30,13 +31,18 @@ export interface ProductDTO {
     image_sides: string[] | null;
     color: string[] | null;
     brand: string | null;
+    model?: string[] | null;
     material: string[] | null;
     size: string[] | null;
     tags: string[] | null;
+    gender?: string[] | null;
     prices: PriceDTO[];
     unit: string | null;
     unitsPerBox?: number | null;
     quantity: number;
+    averageRating?: number;
+    ratingCount?: number;
+    commentsCount?: number;
     variants?: ProductVariantDTO[];
 }
 export interface PaginationMeta {
@@ -54,7 +60,21 @@ export interface PaginatedResponse<T> {
 export interface ProductListParams {
     page?: number;
     limit?: number;
+    q?: string;
+    category?: string;
+    color?: string | string[];
+    brand?: string;
+    model?: string | string[];
+    material?: string | string[];
+    size?: string | string[];
+    tags?: string | string[];
+    gender?: string | string[];
+    minPrice?: number;
+    maxPrice?: number;
+    inStock?: boolean;
+    sortBy?: "createdAt" | "updatedAt" | "name";
+    sortOrder?: "asc" | "desc";
 }
 export interface ProductSearchParams extends ProductListParams {
-    ref: string;
+    ref?: string;
 }

package/dist/resources/product/product.feature.d.ts

@@ -3,10 +3,30 @@ import type { ProductService } from "./service/product.ser";
 export declare class ProductFeature {
     private readonly service;
     constructor(service: ProductService);
-    /** Lista produtos com paginação. */
+    /**
+     * Lista produtos com paginação e filtros combináveis.
+     *
+     * Filtros suportados:
+     * - q: pesquisa textual;
+     * - minPrice / maxPrice: intervalo de preços;
+     * - category, brand: categoria e marca;
+     * - color, model, material, size, tags e gender: valor único ou lista;
+     * - inStock: disponibilidade em stock;
+     * - sortBy / sortOrder: ordenação dos resultados.
+     */
     listProducts(params?: ProductListParams): Promise<PaginatedResponse<ProductDTO>>;
-    /** Pesquisa produtos por ID, slug, nome, código de barras, categoria, marca ou descrição. */
-    searchProducts(params: ProductSearchParams): Promise<PaginatedResponse<ProductDTO>>;
+    /**
+     * Filtra produtos sem exigir um termo de pesquisa.
+     * É um método explícito equivalente a listProducts, útil para interfaces de catálogo.
+     */
+    filterProducts(filters?: ProductListParams): Promise<PaginatedResponse<ProductDTO>>;
+    /**
+     * Pesquisa produtos por texto (ref ou q) e combina a pesquisa com os restantes filtros.
+     * Aceita os mesmos filtros de listProducts, incluindo intervalo de preço, categoria,
+     * cor, marca, modelo, material, tamanho, tags, género e disponibilidade.
+     */
+    searchProducts(params?: ProductSearchParams): Promise<PaginatedResponse<ProductDTO>>;
     /** Obtém os detalhes de um produto através do ID ou slug. */
     getProductByIdOrSlug(id: string): Promise<ProductDTO>;
+    private validatePriceRange;
 }

package/dist/resources/product/service/product.ser.d.ts

@@ -6,4 +6,5 @@ export declare class ProductService {
     getAllProducts(params?: ProductListParams): Promise<PaginatedResponse<ProductDTO>>;
     searchProducts(params: ProductSearchParams): Promise<PaginatedResponse<ProductDTO>>;
     getProductById(id: string): Promise<ProductDTO>;
+    private toQuery;
 }

package/dist/resources/rating/dto/rating.dto.d.ts

@@ -1,3 +1,4 @@
+import type { PaginatedResponse } from "../../product/dto/product.dto";
 export interface RatingDTO {
     id: string;
     stockId: string;
@@ -17,9 +18,35 @@ export interface AddRatingDTO {
     customerName?: string;
     customerEmail?: string;
 }
-export interface RatingSummaryDTO {
-    stockId: string;
+export interface RatingProductDTO {
+    id: string;
+    name: string;
+    slug?: string | null;
+    image?: string | null;
+    brand?: string | null;
+    category?: string | null;
+    averageRating?: number;
+    ratingCount?: number;
+    commentsCount?: number;
+}
+export interface RatingDistributionDTO {
+    score: 1 | 2 | 3 | 4 | 5;
+    count: number;
+    percentage: number;
+}
+export interface RatingSummaryStatsDTO {
     averageRating: number;
-    ratingCount: number;
+    totalRatings: number;
+    totalScore: number;
+    minScore: number | null;
+    maxScore: number | null;
     commentsCount: number;
+    distribution: RatingDistributionDTO[];
+    ratingLabel: string;
+}
+export interface RatingSummaryDTO {
+    product: RatingProductDTO;
+    summary: RatingSummaryStatsDTO;
+    ratings: PaginatedResponse<RatingDTO>;
 }
+export type PaginatedRatingsDTO = PaginatedResponse<RatingDTO>;

package/dist/resources/rating/rating.feature.d.ts

@@ -1,19 +1,29 @@
-import type { AddRatingDTO, RatingDTO, RatingSummaryDTO } from "./dto/rating.dto";
+import type { AddRatingDTO, PaginatedRatingsDTO, RatingDTO, RatingSummaryDTO } from "./dto/rating.dto";
 import type { RatingService } from "./service/rating.ser";
 export declare class RatingFeature {
     private readonly service;
     constructor(service: RatingService);
-    /** Obtém a classificação média e as contagens de avaliações/comentários de um produto. */
-    getProductRatingSummary(stockId: string): Promise<RatingSummaryDTO>;
+    /** Obtém a média, distribuição por estrelas, comentários e avaliações recentes de um produto. */
+    getProductRatingSummary(stockId: string, params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<RatingSummaryDTO>;
+    /** Lista as avaliações de um produto com paginação. */
+    listProductRatings(params: {
+        stockId: string;
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedRatingsDTO>;
     /** Obtém a avaliação de um cliente para um produto, se existir. */
     getCustomerProductRating(params: {
         stockId: string;
         customerId: string;
     }): Promise<RatingDTO | null>;
-    /** Regista uma avaliação de produto. */
+    /** Regista ou atualiza a avaliação de um cliente. */
     createProductRating(data: AddRatingDTO): Promise<RatingDTO>;
     /** Elimina uma avaliação pelo seu identificador. */
     deleteProductRating(id: string): Promise<{
         success: boolean;
+        id?: string;
     }>;
 }

package/dist/resources/rating/service/rating.ser.d.ts

@@ -1,9 +1,17 @@
 import type { HellenaConnect } from "../../../core/HellenaConnect";
-import type { AddRatingDTO, RatingDTO, RatingSummaryDTO } from "../dto/rating.dto";
+import type { AddRatingDTO, PaginatedRatingsDTO, RatingDTO, RatingSummaryDTO } from "../dto/rating.dto";
 export declare class RatingService {
     private readonly connect;
     constructor(connect: HellenaConnect);
-    summary(stockId: string): Promise<RatingSummaryDTO>;
+    summary(stockId: string, params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<RatingSummaryDTO>;
+    findMany(params: {
+        stockId: string;
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedRatingsDTO>;
     findOne(params: {
         stockId: string;
         customerId: string;
@@ -11,5 +19,6 @@ export declare class RatingService {
     create(data: AddRatingDTO): Promise<RatingDTO>;
     delete(id: string): Promise<{
         success: boolean;
+        id?: string;
     }>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellena-sdk/hellena",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Official JavaScript SDK for the Hellena API",
   "license": "ISC",
   "author": "",