qeai-sdk 2.0.0 → 2.0.2

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';
-import { PaginationDto } from '../common/pagination.dto';
+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';
-import { PaginationDto } from '../common/pagination.dto';
+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;
+}

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

@@ -0,0 +1,81 @@
+export class CreatePaymentAuditDynamoDto {
+    /**
+     * Unique identifier for the audited transaction.
+     * Should be globally unique per transaction.
+     *
+     * @example "txn_123abc456"
+     */
+    transactionId;
+    /**
+     * ISO 8601 timestamp indicating when the payment event occurred.
+     *
+     * @example "2024-06-01T12:00:00.000Z"
+     */
+    timestamp;
+    /**
+     * Unique identifier of the related order.
+     *
+     * @example "order_789xyz"
+     */
+    orderId;
+    /**
+     * Name of the payment provider (e.g., "stripe", "culqi").
+     *
+     * @example "stripe"
+     */
+    provider;
+    /**
+     * Name or path of the API endpoint called (e.g., "/charges").
+     *
+     * @example "/charges"
+     */
+    endpoint;
+    /**
+     * HTTP method used for the audited request.
+     *
+     * @example "POST"
+     */
+    method;
+    /**
+     * HTTP response status code from the provider (e.g., 200, 500).
+     *
+     * @example 200
+     */
+    statusCode;
+    /**
+     * Status of the operation/audit (e.g., "success", "error").
+     *
+     * @example "success"
+     */
+    status;
+    /**
+     * Processing time for the audited action, in milliseconds.
+     *
+     * @example 845
+     */
+    durationMs;
+    /**
+     * (Optional) IP address from which the request originated.
+     *
+     * @example "192.168.0.1"
+     */
+    ipAddress;
+    /**
+     * 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;
+    /**
+     * ISO 8601 timestamp indicating when the audit record was created.
+     *
+     * @example "2024-06-01T12:01:00.000Z"
+     */
+    createdAt;
+    /**
+     * ISO 8601 timestamp indicating the last update to the audit record.
+     *
+     * @example "2024-06-01T12:05:30.000Z"
+     */
+    updatedAt;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * DTO for storing payment audit records in S3.
+ *
+ * Encapsulates all relevant information of a payment transaction
+ * to be stored in S3 for logging, compliance, and traceability.
+ *
+ * Follows Clean Code, SOLID, and best practices for maintainability and extensibility.
+ *
+ * @since 2.0.0
+ */
+export declare class CreatePaymentAudiS3tDto {
+    /**
+     * Unique identifier for the audited transaction.
+     * Should be globally unique per transaction.
+     *
+     * @example "txn_123abc456"
+     */
+    transactionId: string;
+    /**
+     * Unique identifier of the associated order.
+     *
+     * @example "order_789xyz"
+     */
+    orderId: string;
+    /**
+     * Name of the payment provider (e.g., "stripe", "culqi").
+     *
+     * @example "stripe"
+     */
+    provider: string;
+    /**
+     * API endpoint called during the payment operation (e.g., "/charges").
+     *
+     * @example "/charges"
+     */
+    endpoint: string;
+    /**
+     * HTTP method used (e.g., "POST", "GET").
+     *
+     * @example "POST"
+     */
+    method: string;
+    /**
+     * HTTP response status code from the provider (e.g., 200, 500).
+     *
+     * @example 200
+     */
+    statusCode: number;
+    /**
+     * Status of the audited operation (e.g., "success", "error").
+     *
+     * @example "success"
+     */
+    status: string;
+    /**
+     * Total execution time of the audited operation, in milliseconds.
+     *
+     * @example 523
+     */
+    durationMs: number;
+    /**
+     * (Optional) IP address from which the request originated.
+     *
+     * @example "192.168.1.10"
+     */
+    ipAddress?: string;
+    /**
+     * Payload sent in the audited request.
+     * Must be a serializable object.
+     *
+     * @example { amount: 19.99, currency: "PEN" }
+     */
+    requestBody: Record<string, any>;
+    /**
+     * Payload received in the audited response.
+     * Must be a serializable object.
+     *
+     * @example { providerResponse: ..., result: ... }
+     */
+    responseBody: Record<string, any>;
+}

package/dist/dtos/payments/create-payment-audit-s3.dto.js

@@ -0,0 +1,81 @@
+/**
+ * DTO for storing payment audit records in S3.
+ *
+ * Encapsulates all relevant information of a payment transaction
+ * to be stored in S3 for logging, compliance, and traceability.
+ *
+ * Follows Clean Code, SOLID, and best practices for maintainability and extensibility.
+ *
+ * @since 2.0.0
+ */
+export class CreatePaymentAudiS3tDto {
+    /**
+     * Unique identifier for the audited transaction.
+     * Should be globally unique per transaction.
+     *
+     * @example "txn_123abc456"
+     */
+    transactionId;
+    /**
+     * Unique identifier of the associated order.
+     *
+     * @example "order_789xyz"
+     */
+    orderId;
+    /**
+     * Name of the payment provider (e.g., "stripe", "culqi").
+     *
+     * @example "stripe"
+     */
+    provider;
+    /**
+     * API endpoint called during the payment operation (e.g., "/charges").
+     *
+     * @example "/charges"
+     */
+    endpoint;
+    /**
+     * HTTP method used (e.g., "POST", "GET").
+     *
+     * @example "POST"
+     */
+    method;
+    /**
+     * HTTP response status code from the provider (e.g., 200, 500).
+     *
+     * @example 200
+     */
+    statusCode;
+    /**
+     * Status of the audited operation (e.g., "success", "error").
+     *
+     * @example "success"
+     */
+    status;
+    /**
+     * Total execution time of the audited operation, in milliseconds.
+     *
+     * @example 523
+     */
+    durationMs;
+    /**
+     * (Optional) IP address from which the request originated.
+     *
+     * @example "192.168.1.10"
+     */
+    ipAddress;
+    /**
+     * Payload sent in the audited request.
+     * Must be a serializable object.
+     *
+     * @example { amount: 19.99, currency: "PEN" }
+     */
+    requestBody;
+    /**
+     * Payload received in the audited response.
+     * Must be a serializable object.
+     *
+     * @example { providerResponse: ..., result: ... }
+     */
+    responseBody;
+}

package/dist/dtos/payments/index.d.ts

@@ -6,6 +6,8 @@
  *
  * @since 2.0.0
  */
-export * from './payment-session.dto';
-export * from './payment-session-item.dto';
-export * from './webhook-data.dto';
+export * from './payment-session.dto.js';
+export * from './payment-session-item.dto.js';
+export * from './webhook-data.dto.js';
+export * from './create-payment-audit-dynamo.dto.js';
+export * from './create-payment-audit-s3.dto.js';

package/dist/dtos/payments/index.js

@@ -6,6 +6,8 @@
  *
  * @since 2.0.0
  */
-export * from './payment-session.dto';
-export * from './payment-session-item.dto';
-export * from './webhook-data.dto';
+export * from './payment-session.dto.js';
+export * from './payment-session-item.dto.js';
+export * from './webhook-data.dto.js';
+export * from './create-payment-audit-dynamo.dto.js';
+export * from './create-payment-audit-s3.dto.js';