qeai-sdk 2.0.1 → 2.0.2

package/dist/dtos/orders/create-order.dto.js

@@ -8,65 +8,75 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 import { Type } from 'class-transformer';
-import { IsArray, ArrayMinSize, ValidateNested, IsEnum, IsString, IsOptional, MinLength, IsMongoId, IsNotEmpty, IsDateString, } from 'class-validator';
+import { IsArray, ArrayMinSize, ValidateNested, IsString, IsOptional, MinLength, IsMongoId, IsNotEmpty, IsDateString, IsIn, } from 'class-validator';
 import { OrderItemDto } from './order-item.dto.js';
-import { OrderType } from '../../enums/order-type.enum.js';
+import { ORDER_MODES } from '../../types/order-mode.type.js';
 /**
- * DTO for creating a new order.
+ * Data Transfer Object for creating a new order in QeHay.
  *
- * Used by the Orders microservice to create new orders with items,
- * order type, and optional delivery/pickup information.
- * Validates the order structure and required fields based on order type.
+ * This DTO defines the structure, validation and documentation for the data needed to create a restaurant order.
+ * It supports all main QeHay order flows (DINE_IN, PICKUP, DELIVERY) and enforces minimum business rules at field level.
+ *
+ * Each property is validated and documented for clear API contracts and seamless integration with client apps.
  *
  * @since 2.0.0
  */
 export class CreateOrderDto {
     /**
-     * Array of items in the order.
-     * Must contain at least one item.
-     * Each item is validated as an OrderItemDto.
+     * List of items included in the order.
+     * - Must contain at least one item.
+     * - Each element is validated as OrderItemDto.
      *
-     * @example [{ productId: "...", quantity: 2, price: 19.98 }]
+     * @type {OrderItemDto[]}
+     * @example [{ "productId": "651cb9...", "quantity": 2, "price": 19.98 }]
      */
     items;
     /**
-     * Type of order (DINE_IN, PICKUP, or DELIVERY).
-     * Determines the fulfillment flow and required fields.
+     * Type of order (DINE_IN, PICKUP, DELIVERY).
+     * This determines the flow and required additional fields.
      *
-     * @example OrderType.DELIVERY
+     * @type {OrderMode}
+     * @example "DELIVERY"
      */
     mode;
     /**
-     * Optional table identifier for dine-in orders.
-     * Must be at least 2 characters long if provided.
+     * Table identifier for dine-in orders.
+     * - Required for DINE_IN orders.
+     * - Ignored for PICKUP and DELIVERY.
+     * - Must be at least 2 characters if provided.
      *
+     * @type {string}
      * @example "Table 5"
      */
     tableId;
     /**
-     * Optional delivery address for delivery orders.
+     * Delivery address, required when mode is DELIVERY.
      *
+     * @type {string}
      * @example "123 Main St, Downtown"
      */
     deliveryAddress;
     /**
-     * Optional pickup time for pickup orders.
-     * Must be a valid ISO date string if provided.
+     * Scheduled pickup time for pickup orders, as a valid ISO 8601 string.
+     * Only relevant for PICKUP mode.
      *
+     * @type {string}
      * @example "2024-01-15T18:30:00Z"
      */
     pickupTime;
     /**
-     * Payment method identifier.
-     * Required for orders that require payment before confirmation.
+     * Identifier of the payment method selected by the customer.
+     * - Required for orders requiring pre-payment (typically DELIVERY and PICKUP).
      *
+     * @type {string}
      * @example "payment-method-uuid-123"
      */
     paymentMethodId;
     /**
-     * Optional user identifier who created the order.
-     * Must be a valid MongoDB ObjectId if provided.
+     * User identifier (MongoDB ObjectId) of the customer who created the order.
+     * - Required. Used for user traceability and order ownership.
      *
+     * @type {string}
      * @example "507f1f77bcf86cd799439011"
      */
     userId;
@@ -79,33 +89,35 @@ __decorate([
     __metadata("design:type", Array)
 ], CreateOrderDto.prototype, "items", void 0);
 __decorate([
-    IsEnum(OrderType, { message: 'Order type must be DINE_IN, PICKUP, or DELIVERY' }),
+    IsIn(ORDER_MODES, { message: 'Order type must be DINE_IN, PICKUP, or DELIVERY' }),
+    IsString({ message: 'Order mode must be a string' }),
+    IsNotEmpty({ message: 'Order mode is required' }),
     __metadata("design:type", String)
 ], CreateOrderDto.prototype, "mode", void 0);
 __decorate([
-    IsString(),
-    MinLength(2),
+    IsString({ message: 'tableId must be a string' }),
+    MinLength(2, { message: 'tableId must be at least 2 characters' }),
     IsOptional(),
     __metadata("design:type", String)
 ], CreateOrderDto.prototype, "tableId", void 0);
 __decorate([
-    IsString(),
+    IsString({ message: 'Delivery address must be a string' }),
     IsOptional(),
     __metadata("design:type", String)
 ], CreateOrderDto.prototype, "deliveryAddress", void 0);
 __decorate([
-    IsDateString(),
+    IsDateString({}, { message: 'pickupTime must be a valid ISO date string' }),
     IsOptional(),
     __metadata("design:type", String)
 ], CreateOrderDto.prototype, "pickupTime", void 0);
 __decorate([
-    IsString(),
+    IsString({ message: 'paymentMethodId must be a string' }),
     IsNotEmpty({ message: 'Payment method ID is required' }),
     __metadata("design:type", String)
 ], CreateOrderDto.prototype, "paymentMethodId", void 0);
 __decorate([
-    IsString(),
-    IsMongoId(),
-    IsOptional(),
+    IsString({ message: 'userId must be a string' }),
+    IsMongoId({ message: 'userId must be a valid MongoDB ObjectId' }),
+    IsNotEmpty({ message: 'userId is required' }),
     __metadata("design:type", String)
 ], CreateOrderDto.prototype, "userId", void 0);

package/dist/dtos/orders/order-item.dto.d.ts

@@ -1,65 +1,82 @@
 /**
- * DTO for order item information.
+ * Data Transfer Object representing a single item within an order.
  *
- * Represents a single item in an order with its product details,
- * size (if applicable), quantity, price, and optional notes or child items.
- * Supports nested items for complex order structures (e.g., combo meals).
+ * Used by QeHay to structure each item the customer wishes to order, including the product, quantity, pricing, variant size,
+ * optional notes, and possible nested (child) items such as combos.
  *
+ * All properties are validated and documented to ensure data integrity and improve maintainability.
+ *
+ * @class OrderItemDto
  * @since 2.0.0
  */
 export declare class OrderItemDto {
     /**
-     * Unique identifier of the product.
-     * Must be a valid UUID.
+     * Unique identifier for the product.
+     * Required.
+     * Must be a valid UUID v4.
      *
+     * @type {string}
      * @example "550e8400-e29b-41d4-a716-446655440000"
      */
     productId: string;
     /**
-     * Optional unique identifier of the product size variant.
-     * Must be a valid UUID if provided.
+     * Optional unique identifier for the product size (variant).
+     * Only set when the selected product has multiple sizes/variants.
+     * Must be a valid UUID v4 if provided.
      *
+     * @type {string}
      * @example "660e8400-e29b-41d4-a716-446655440001"
      */
     productSizeId?: string;
     /**
-     * Optional name of the size variant.
+     * Optional name or label for the product size/variant.
+     * Useful for displaying selected size in the client.
      *
+     * @type {string}
      * @example "Large"
      */
     sizeName?: string;
     /**
-     * Optional price for the size variant.
-     * Must be a positive number if provided.
+     * Optional additional price for the selected size/variant.
+     * If specified, must be a positive number.
      *
+     * @type {number}
      * @example 12.99
      */
     sizePrice?: number;
     /**
-     * Quantity of this item in the order.
-     * Must be a positive number.
+     * Quantity of the ordered product (how many units the customer wants).
+     * Required.
+     * Must be a positive number (greater than zero).
      *
+     * @type {number}
      * @example 2
      */
     quantity: number;
     /**
-     * Unit price for this item.
+     * Unit price for this item (for one product or one variant, without multiplying by quantity).
+     * Required.
      * Must be a positive number.
      *
+     * @type {number}
      * @example 9.99
      */
     price: number;
     /**
-     * Optional notes or special instructions for this item.
+     * Optional notes or special instructions for this item (i.e. "No onions", "Add extra cheese").
+     * Useful for customizations or clarifications by the customer.
+     * Minimum length: 5 characters. Maximum: 200.
      *
+     * @type {string}
      * @example "No onions, extra cheese"
      */
     notes?: string;
     /**
-     * Optional array of child items (for nested structures like combo meals).
-     * Each child item is validated as an OrderItemDto.
+     * Optional array of nested child items (for combos, extras, etc).
+     * Each child item must also be a valid OrderItemDto instance, supporting recursive order nesting.
      *
-     * @example [{ productId: "...", quantity: 1, price: 5.99 }]
+     * @type {OrderItemDto[]}
+     * @example [{ "productId": "...", "quantity": 1, "price": 5.99 }]
      */
     childItems?: OrderItemDto[];
 }

package/dist/dtos/orders/order-item.dto.js

@@ -8,111 +8,133 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 import { Type } from 'class-transformer';
-import { IsArray, IsNumber, IsOptional, IsPositive, IsString, IsUUID, ValidateNested, } from 'class-validator';
+import { IsArray, IsNotEmpty, IsNumber, IsOptional, IsPositive, IsString, IsUUID, MaxLength, MinLength, ValidateNested, } from 'class-validator';
 /**
- * DTO for order item information.
+ * Data Transfer Object representing a single item within an order.
  *
- * Represents a single item in an order with its product details,
- * size (if applicable), quantity, price, and optional notes or child items.
- * Supports nested items for complex order structures (e.g., combo meals).
+ * Used by QeHay to structure each item the customer wishes to order, including the product, quantity, pricing, variant size,
+ * optional notes, and possible nested (child) items such as combos.
  *
+ * All properties are validated and documented to ensure data integrity and improve maintainability.
+ *
+ * @class OrderItemDto
  * @since 2.0.0
  */
 export class OrderItemDto {
     /**
-     * Unique identifier of the product.
-     * Must be a valid UUID.
+     * Unique identifier for the product.
+     * Required.
+     * Must be a valid UUID v4.
      *
+     * @type {string}
      * @example "550e8400-e29b-41d4-a716-446655440000"
      */
     productId;
     /**
-     * Optional unique identifier of the product size variant.
-     * Must be a valid UUID if provided.
+     * Optional unique identifier for the product size (variant).
+     * Only set when the selected product has multiple sizes/variants.
+     * Must be a valid UUID v4 if provided.
      *
+     * @type {string}
      * @example "660e8400-e29b-41d4-a716-446655440001"
      */
     productSizeId;
     /**
-     * Optional name of the size variant.
+     * Optional name or label for the product size/variant.
+     * Useful for displaying selected size in the client.
      *
+     * @type {string}
      * @example "Large"
      */
     sizeName;
     /**
-     * Optional price for the size variant.
-     * Must be a positive number if provided.
+     * Optional additional price for the selected size/variant.
+     * If specified, must be a positive number.
      *
+     * @type {number}
      * @example 12.99
      */
     sizePrice;
     /**
-     * Quantity of this item in the order.
-     * Must be a positive number.
+     * Quantity of the ordered product (how many units the customer wants).
+     * Required.
+     * Must be a positive number (greater than zero).
      *
+     * @type {number}
      * @example 2
      */
     quantity;
     /**
-     * Unit price for this item.
+     * Unit price for this item (for one product or one variant, without multiplying by quantity).
+     * Required.
      * Must be a positive number.
      *
+     * @type {number}
      * @example 9.99
      */
     price;
     /**
-     * Optional notes or special instructions for this item.
+     * Optional notes or special instructions for this item (i.e. "No onions", "Add extra cheese").
+     * Useful for customizations or clarifications by the customer.
+     * Minimum length: 5 characters. Maximum: 200.
      *
+     * @type {string}
      * @example "No onions, extra cheese"
      */
     notes;
     /**
-     * Optional array of child items (for nested structures like combo meals).
-     * Each child item is validated as an OrderItemDto.
+     * Optional array of nested child items (for combos, extras, etc).
+     * Each child item must also be a valid OrderItemDto instance, supporting recursive order nesting.
      *
-     * @example [{ productId: "...", quantity: 1, price: 5.99 }]
+     * @type {OrderItemDto[]}
+     * @example [{ "productId": "...", "quantity": 1, "price": 5.99 }]
      */
     childItems;
 }
 __decorate([
-    IsString(),
-    IsUUID(),
+    IsString({ message: "productId must be a string" }),
+    IsUUID('4', { message: "productId must be a valid UUID v4" }),
+    IsNotEmpty({ message: "productId is required" }),
     __metadata("design:type", String)
 ], OrderItemDto.prototype, "productId", void 0);
 __decorate([
-    IsString(),
+    IsString({ message: "productSizeId must be a string" }),
     IsOptional(),
-    IsUUID(),
+    IsUUID('4', { message: "productSizeId must be a valid UUID v4" }),
     __metadata("design:type", String)
 ], OrderItemDto.prototype, "productSizeId", void 0);
 __decorate([
-    IsString(),
+    IsString({ message: "sizeName must be a string" }),
     IsOptional(),
     __metadata("design:type", String)
 ], OrderItemDto.prototype, "sizeName", void 0);
 __decorate([
-    IsNumber(),
+    IsNumber({}, { message: "sizePrice must be a number" }),
     IsOptional(),
-    IsPositive(),
+    IsPositive({ message: "sizePrice must be a positive number" }),
     __metadata("design:type", Number)
 ], OrderItemDto.prototype, "sizePrice", void 0);
 __decorate([
-    IsNumber(),
-    IsPositive(),
+    IsNumber({}, { message: "quantity must be a number" }),
+    IsPositive({ message: "quantity must be a positive number" }),
+    IsNotEmpty({ message: "quantity is required" }),
     __metadata("design:type", Number)
 ], OrderItemDto.prototype, "quantity", void 0);
 __decorate([
-    IsNumber(),
-    IsPositive(),
+    IsNumber({}, { message: "price must be a number" }),
+    IsPositive({ message: "price must be a positive number" }),
+    IsNotEmpty({ message: "price is required" }),
     __metadata("design:type", Number)
 ], OrderItemDto.prototype, "price", void 0);
 __decorate([
-    IsString(),
+    IsString({ message: "notes must be a string" }),
     IsOptional(),
+    MinLength(5, { message: "notes must be at least 5 characters" }),
+    MaxLength(200, { message: "notes must be at most 200 characters" }),
     __metadata("design:type", String)
 ], OrderItemDto.prototype, "notes", void 0);
 __decorate([
-    IsArray(),
+    IsArray({ message: "childItems must be an array" }),
     IsOptional(),
     ValidateNested({ each: true }),
     Type(() => OrderItemDto),

package/dist/dtos/orders/order-pagination.dto.d.ts

@@ -1,5 +1,5 @@
-import { OrderStatus } from '../../enums/order-status.enum.js';
 import { PaginationDto } from '../common/pagination.dto.js';
+import type { OrderStatus } from '../../types/order-status.type.js';
 /**
  * DTO for paginated order queries with optional status filter.
  *

package/dist/dtos/orders/order-pagination.dto.js

@@ -7,9 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { IsEnum, IsOptional } from 'class-validator';
-import { OrderStatus } from '../../enums/order-status.enum.js';
+import { IsIn, IsOptional } from 'class-validator';
 import { PaginationDto } from '../common/pagination.dto.js';
+import { ORDER_STATUS } from '../../types/order-status.type.js';
 /**
  * DTO for paginated order queries with optional status filter.
  *
@@ -29,6 +29,6 @@ export class OrderPaginationDto extends PaginationDto {
 }
 __decorate([
     IsOptional(),
-    IsEnum(OrderStatus, { message: 'Status must be a valid order status' }),
+    IsIn(ORDER_STATUS, { message: 'Status must be a valid order status' }),
     __metadata("design:type", String)
 ], OrderPaginationDto.prototype, "status", void 0);

package/dist/dtos/orders/paid-order.dto.d.ts

@@ -1,29 +1,37 @@
 /**
- * DTO for paid order information.
+ * Data Transfer Object for paid order information in QeHay.
  *
- * Represents order payment confirmation data after a successful payment.
- * Used by the Orders microservice to update order payment status.
+ * This DTO is used to communicate the result of a successful payment for an order.
+ * It encapsulates all data needed to mark an order as paid and link it to the relevant payment evidence.
+ * Used by the Orders microservice (and related systems) to update order payment status and retain payment tracing information.
  *
+ * Each property is validated and clearly documented to guarantee interoperability and support audits.
+ *
+ * @class PaidOrderDto
  * @since 2.0.0
  */
 export declare class PaidOrderDto {
     /**
-     * Payment charge identifier from the payment provider.
+     * Payment charge identifier provided by the payment gateway or provider.
+     * This value links the QeHay order to the payment platform transaction.
      *
+     * @type {string}
      * @example "ch_1234567890abcdef"
      */
     paymentChargeId: string;
     /**
-     * Unique identifier of the paid order.
-     * Must be a valid UUID.
+     * Unique identifier (UUID v4) of the paid order within QeHay.
+     * Used to reference and update the order entity.
      *
+     * @type {string}
      * @example "550e8400-e29b-41d4-a716-446655440000"
      */
     orderId: string;
     /**
-     * URL to the payment receipt.
-     * Must be a valid URL format.
+     * Direct URL of the payment receipt generated by the payment platform.
+     * This allows for audit, download, or viewing of payment proof by users or admins.
      *
+     * @type {string}
      * @example "https://payments.example.com/receipts/receipt_123456"
      */
     receiptUrl: string;

package/dist/dtos/orders/paid-order.dto.js

@@ -7,48 +7,59 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { IsString, IsUrl, IsUUID } from 'class-validator';
+import { IsNotEmpty, IsString, IsUrl, IsUUID } from "class-validator";
 /**
- * DTO for paid order information.
+ * Data Transfer Object for paid order information in QeHay.
  *
- * Represents order payment confirmation data after a successful payment.
- * Used by the Orders microservice to update order payment status.
+ * This DTO is used to communicate the result of a successful payment for an order.
+ * It encapsulates all data needed to mark an order as paid and link it to the relevant payment evidence.
+ * Used by the Orders microservice (and related systems) to update order payment status and retain payment tracing information.
  *
+ * Each property is validated and clearly documented to guarantee interoperability and support audits.
+ *
+ * @class PaidOrderDto
  * @since 2.0.0
  */
 export class PaidOrderDto {
     /**
-     * Payment charge identifier from the payment provider.
+     * Payment charge identifier provided by the payment gateway or provider.
+     * This value links the QeHay order to the payment platform transaction.
      *
+     * @type {string}
      * @example "ch_1234567890abcdef"
      */
     paymentChargeId;
     /**
-     * Unique identifier of the paid order.
-     * Must be a valid UUID.
+     * Unique identifier (UUID v4) of the paid order within QeHay.
+     * Used to reference and update the order entity.
      *
+     * @type {string}
      * @example "550e8400-e29b-41d4-a716-446655440000"
      */
     orderId;
     /**
-     * URL to the payment receipt.
-     * Must be a valid URL format.
+     * Direct URL of the payment receipt generated by the payment platform.
+     * This allows for audit, download, or viewing of payment proof by users or admins.
      *
+     * @type {string}
      * @example "https://payments.example.com/receipts/receipt_123456"
      */
     receiptUrl;
 }
 __decorate([
-    IsString(),
+    IsString({ message: "paymentChargeId must be a string" }),
+    IsNotEmpty({ message: "paymentChargeId is required" }),
     __metadata("design:type", String)
 ], PaidOrderDto.prototype, "paymentChargeId", void 0);
 __decorate([
-    IsString(),
-    IsUUID(),
+    IsString({ message: "orderId must be a string" }),
+    IsUUID("4", { message: "orderId must be a valid UUID v4" }),
+    IsNotEmpty({ message: "orderId is required" }),
     __metadata("design:type", String)
 ], PaidOrderDto.prototype, "orderId", void 0);
 __decorate([
-    IsString(),
-    IsUrl(),
+    IsString({ message: "receiptUrl must be a string" }),
+    IsUrl({}, { message: "receiptUrl must be a valid URL" }),
+    IsNotEmpty({ message: "receiptUrl is required" }),
     __metadata("design:type", String)
 ], PaidOrderDto.prototype, "receiptUrl", void 0);

package/dist/dtos/payments/create-payment-audit-dynamo.dto.d.ts

@@ -0,0 +1,81 @@
+export declare class CreatePaymentAuditDynamoDto {
+    /**
+     * Unique identifier for the audited transaction.
+     * Should be globally unique per transaction.
+     *
+     * @example "txn_123abc456"
+     */
+    transactionId: string;
+    /**
+     * ISO 8601 timestamp indicating when the payment event occurred.
+     *
+     * @example "2024-06-01T12:00:00.000Z"
+     */
+    timestamp: string;
+    /**
+     * Unique identifier of the related order.
+     *
+     * @example "order_789xyz"
+     */
+    orderId: string;
+    /**
+     * Name of the payment provider (e.g., "stripe", "culqi").
+     *
+     * @example "stripe"
+     */
+    provider: string;
+    /**
+     * Name or path of the API endpoint called (e.g., "/charges").
+     *
+     * @example "/charges"
+     */
+    endpoint: string;
+    /**
+     * HTTP method used for the audited request.
+     *
+     * @example "POST"
+     */
+    method: string;
+    /**
+     * HTTP response status code from the provider (e.g., 200, 500).
+     *
+     * @example 200
+     */
+    statusCode: number;
+    /**
+     * Status of the operation/audit (e.g., "success", "error").
+     *
+     * @example "success"
+     */
+    status: string;
+    /**
+     * Processing time for the audited action, in milliseconds.
+     *
+     * @example 845
+     */
+    durationMs: number;
+    /**
+     * (Optional) IP address from which the request originated.
+     *
+     * @example "192.168.0.1"
+     */
+    ipAddress?: string;
+    /**
+     * URL of the external log or audit file, if available (e.g., S3 presigned url).
+     *
+     * @example "https://s3.amazonaws.com/bucket/audit/txn_123.json"
+     */
+    logUrl: string;
+    /**
+     * ISO 8601 timestamp indicating when the audit record was created.
+     *
+     * @example "2024-06-01T12:01:00.000Z"
+     */
+    createdAt: string;
+    /**
+     * ISO 8601 timestamp indicating the last update to the audit record.
+     *
+     * @example "2024-06-01T12:05:30.000Z"
+     */
+    updatedAt: string;
+}