qeai-sdk 2.0.0

package/dist/interfaces/orders/order-created.interface.d.ts

@@ -0,0 +1,46 @@
+import { StripeSessionResponse } from "../payments";
+import { CulqiSessionResponse } from "../payments/culqi-session-response.interface";
+import { OrderWithProducts } from "./order-with-products.interface";
+/**
+ * Order created interface.
+ *
+ * Represents the response structure after successfully creating an order.
+ * Includes the created order and process information.
+ *
+ * @since 2.0.0
+ */
+export interface OrderCreated {
+    /**
+     * The created order with all associated products.
+     */
+    order: OrderWithProducts;
+    /**
+     * Process or workflow information related to order creation, or a payment session
+     * payload if payment via an external provider is required.
+     *
+     * For DINE_IN mode:
+     *   - Returns a string representing the QR code on Base64 format.
+     * For DELIVERY or PICKUP modes:
+     *   - Returns the payload from the payment provider, which may include URLs or payment metadata.
+     *
+     * Stripe example:
+     *   {
+     *     url: "https://checkout.stripe.com/pay/...",
+     *     successUrl: "https://domain.com/success",
+     *     cancelUrl: "https://domain.com/cancel"
+     *   }
+     *
+     * Culqi example:
+     *   {
+     *     provider: "culqi",
+     *     orderId: "order-uuid",
+     *     transactionId: "txn-123",
+     *     receiptUrl: "https://culqi.com/receipt/...",
+     *     message: "Payment successful via Culqi"
+     *   }
+     *
+     * @example "data:image/png;base64,..."
+     * @example { url: "https://checkout.stripe.com/pay/..." }
+     */
+    process: string | CulqiSessionResponse | StripeSessionResponse;
+}

package/dist/interfaces/orders/order-created.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/orders/order-creation-strategy.interface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Order creation strategy interface.
+ *
+ * Defines the contract for order creation strategies using the Strategy pattern.
+ * Different strategies can handle different order types or business rules.
+ *
+ * @since 2.0.0
+ */
+export interface OrderCreationStrategy {
+    /**
+     * Processes an order creation request.
+     *
+     * @param orderData - The order data to process (structure depends on implementation)
+     * @returns Promise resolving to the created order or order result
+     */
+    processOrder(orderData: any): Promise<any>;
+}

package/dist/interfaces/orders/order-creation-strategy.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/orders/order-item.interface.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Order item interface.
+ *
+ * Represents a single line item in an order with product details,
+ * size variant, pricing, and optional notes.
+ *
+ * @since 2.0.0
+ */
+export interface OrderItem {
+    /**
+     * Unique identifier of the product.
+     *
+     * @example "550e8400-e29b-41d4-a716-446655440000"
+     */
+    productId: string;
+    /**
+     * Optional name of the size variant.
+     *
+     * @example "Large"
+     * @example "Medium"
+     */
+    sizeName?: string;
+    /**
+     * Optional price for the size variant.
+     *
+     * @example 12.99
+     */
+    sizePrice?: number;
+    /**
+     * Current status of the order item.
+     *
+     * @example "pending"
+     * @example "cooking"
+     * @example "ready"
+     */
+    itemStatus: string;
+    /**
+     * Optional notes or special instructions for this item.
+     *
+     * @example "No onions, extra cheese"
+     */
+    notes?: string;
+    /**
+     * Unit price for this item.
+     *
+     * @example 9.99
+     */
+    price: number;
+    /**
+     * Quantity of this item in the order.
+     *
+     * @example 2
+     */
+    quantity: number;
+    /**
+     * Product name.
+     *
+     * @example "Big Mac"
+     */
+    name: string;
+    /**
+     * Child items for this order item, used for combos or nested options.
+     * For example, a combo meal could have child items for a drink and side.
+     *
+     * @type {OrderItem[]}
+     * @default []
+     * @example [ { name: "Coke", quantity: 1, ... }, { name: "Fries", quantity: 1, ... } ]
+     */
+    childItems: OrderItem[];
+}

package/dist/interfaces/orders/order-item.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/orders/order-with-products.interface.d.ts

@@ -0,0 +1,34 @@
+import { OrderItem } from "./order-item.interface";
+import { Order } from "./order.interface";
+/**
+ * Represents a complete restaurant order with its associated products.
+ *
+ * Extends the base Order interface by including the full details of each
+ * ordered item (with product reference and relevant metadata).
+ * This interface is commonly used when fetching order information that requires
+ * itemized product details, for example in admin dashboards, kitchen systems,
+ * or customer order history queries.
+ *
+ * @extends Order
+ * @since 2.0.0
+ */
+export interface OrderWithProducts extends Order {
+    /**
+     * List of all items belonging to this order, each including
+     * detailed product information and order-specific item data.
+     *
+     * @type {OrderItem[]}
+     * @example [
+     *    {
+     *      productId: "prod-uuid-1",
+     *      name: "Traditional Pizza",
+     *      quantity: 2,
+     *      price: 12.99,
+     *      notes: "No onions",
+     *      // ...
+     *    },
+     *    // More items...
+     * ]
+     */
+    OrderItem: OrderItem[];
+}

package/dist/interfaces/orders/order-with-products.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/orders/order.interface.d.ts

@@ -0,0 +1,114 @@
+import { OrderStatus } from '../../enums';
+import { OrderMode } from '../../types';
+/**
+ * Represents a restaurant order within the QeHay system.
+ * Each order includes its metadata, payment information, state, and fulfillment mode.
+ * Depending on the type of order (DINE_IN, DELIVERY, or PICKUP), some fields may be null or unused.
+ *
+ * @since 2.0.0
+ */
+export interface Order {
+    /**
+     * Unique identifier of the order.
+     *
+     * @example "550e8400-e29b-41d4-a716-446655440000"
+     */
+    id: string;
+    /**
+     * Indicates the mode in which the order is placed: DINE_IN, PICKUP, or DELIVERY.
+     *
+     * @example "DELIVERY"
+     */
+    type: OrderMode;
+    /**
+     * Current status of the order, following QeHay's workflow enumeration.
+     *
+     * @example OrderStatus.CONFIRMED
+     * @example OrderStatus.COOKING
+     */
+    status: OrderStatus;
+    /**
+     * Total amount to be paid for the order, including all applicable taxes and discounts.
+     *
+     * @example 29.99
+     */
+    totalAmount: number;
+    /**
+     * Total number of individual items in the order.
+     *
+     * @example 3
+     */
+    totalItems: number;
+    /**
+     * Flag indicating if the order has been paid.
+     *
+     * @example true
+     * @example false
+     */
+    paid: boolean;
+    /**
+     * Timestamp reflecting when the payment for this order was completed.
+     * If the order is unpaid, this value is null.
+     *
+     * @example "2024-01-15T18:30:00Z"
+     * @example null
+     */
+    paidAt?: Date;
+    /**
+     * Payment transaction or charge identifier from the payment provider (if paid).
+     * May be null if the order is unpaid or if the payment method does not provide an external reference.
+     *
+     * @example "ch_1234567890abcdef"
+     * @example null
+     */
+    paymentChargeId?: string;
+    /**
+     * For dine-in orders, this indicates the table number assigned.
+     * For pickup or delivery orders, this will be null.
+     *
+     * @example "Table 5"
+     * @example null
+     */
+    tableNumber?: string;
+    /**
+     * For pickup orders, this indicates the scheduled pick-up time.
+     * For dine-in or delivery orders, this field will be null.
+     *
+     * @example "2024-01-15T18:30:00Z"
+     * @example null
+     */
+    pickupTime?: Date;
+    /**
+     * For delivery orders, this contains the delivery address.
+     * For dine-in or pickup, this will be null.
+     *
+     * @example "123 Main St, Downtown"
+     * @example null
+     */
+    deliveryAddress?: string;
+    /**
+     * Unique identifier of the customer who placed the order.
+     *
+     * @example "550e8400-e29b-41d4-a716-446655440000"
+     */
+    customerId: string;
+    /**
+     * Identifier for the selected payment method.
+     * Can reference either a saved method or a one-time use token depending on the payment provider.
+     *
+     * @example "payment-method-uuid-123"
+     */
+    paymentMethodId: string;
+    /**
+     * Timestamp for when the order was created in the system.
+     *
+     * @example "2024-01-15T10:30:00Z"
+     */
+    createdAt: Date;
+    /**
+     * Last updated timestamp for the order record.
+     *
+     * @example "2024-01-15T11:00:00Z"
+     */
+    updatedAt: Date;
+}

package/dist/interfaces/orders/order.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/orders/responses/change-order-status-response.interface.d.ts

@@ -0,0 +1,5 @@
+import { ApiResponse } from "../../common";
+import { Order } from "../order.interface";
+export interface ChangeOrderStatusInterface extends ApiResponse {
+    data: Order;
+}

package/dist/interfaces/orders/responses/change-order-status-response.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/orders/responses/create-order-response.interface.d.ts

@@ -0,0 +1,7 @@
+import { ApiResponse } from "../../common";
+import { OrderCreated } from "../order-created.interface";
+export interface CreateOrderResponse extends ApiResponse {
+    data: CreateOrderData;
+}
+export interface CreateOrderData extends OrderCreated {
+}

package/dist/interfaces/orders/responses/create-order-response.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/orders/responses/index.d.ts

@@ -0,0 +1,4 @@
+export * from './change-order-status-response.interface';
+export * from './orders-list-response.interface';
+export * from './order-with-products-response.interface';
+export * from './create-order-response.interface';

package/dist/interfaces/orders/responses/index.js

@@ -0,0 +1,4 @@
+export * from './change-order-status-response.interface';
+export * from './orders-list-response.interface';
+export * from './order-with-products-response.interface';
+export * from './create-order-response.interface';

package/dist/interfaces/orders/responses/order-with-products-response.interface.d.ts

@@ -0,0 +1,5 @@
+import { ApiResponse } from "../../common";
+import { OrderWithProducts } from "../order-with-products.interface";
+export interface OrderWithProductsResponse extends ApiResponse {
+    data: OrderWithProducts;
+}

package/dist/interfaces/orders/responses/order-with-products-response.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/orders/responses/orders-list-response.interface.d.ts

@@ -0,0 +1,6 @@
+import { ApiResponse } from "../../common";
+import { PaginationResponse } from "../../common/api-pagination-response.interface";
+import { Order } from "../order.interface";
+export interface OrdersListResponse extends ApiResponse {
+    data: PaginationResponse<Order>;
+}

package/dist/interfaces/orders/responses/orders-list-response.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/payments/audit-storage-strategy.interface.d.ts

@@ -0,0 +1,19 @@
+import { PaymentAuditData } from './payment-audit-data.interface';
+/**
+ * Audit storage strategy interface.
+ *
+ * Defines the contract for audit storage strategies using the Strategy pattern.
+ * Different implementations handle different storage systems
+ * (e.g., DynamoDB, S3, local file system).
+ *
+ * @since 2.0.0
+ */
+export interface AuditStorageStrategy {
+    /**
+     * Stores payment audit data using the specific strategy.
+     *
+     * @param auditData - The audit data to store (format depends on storage type)
+     * @returns Promise resolving to true if storage was successful, false otherwise
+     */
+    store(auditData: PaymentAuditData): Promise<boolean>;
+}

package/dist/interfaces/payments/audit-storage-strategy.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/payments/culqi-session-response.interface.d.ts

@@ -0,0 +1,7 @@
+export interface CulqiSessionResponse {
+    provider: string;
+    orderId: string;
+    transactionId: string;
+    receiptUrl: string;
+    message: string;
+}

package/dist/interfaces/payments/culqi-session-response.interface.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,17 @@
+/**
+ * Payment interfaces.
+ *
+ * This module exports interfaces used for payment processing,
+ * payment provider integration, and audit logging in the Payments microservice.
+ *
+ * @since 2.0.0
+ */
+export * from "./payment-session-item.interface";
+export * from "./payment-method-config.interface";
+export * from "./payment-provider.interface";
+export * from "./payment-succeeded-payload.interface";
+export * from "./stripe-session-response.interface";
+export * from "./culqi-session-response.interface";
+export * from "./payment-audit-data.interface";
+export * from "./audit-storage-strategy.interface";
+export * from "./responses/payment-callback-response.interface";

package/dist/interfaces/payments/index.js

@@ -0,0 +1,18 @@
+/**
+ * Payment interfaces.
+ *
+ * This module exports interfaces used for payment processing,
+ * payment provider integration, and audit logging in the Payments microservice.
+ *
+ * @since 2.0.0
+ */
+export * from "./payment-session-item.interface";
+export * from "./payment-method-config.interface";
+export * from "./payment-provider.interface";
+export * from "./payment-succeeded-payload.interface";
+export * from "./stripe-session-response.interface";
+export * from "./culqi-session-response.interface";
+export * from "./payment-audit-data.interface";
+export * from "./audit-storage-strategy.interface";
+// Responses
+export * from "./responses/payment-callback-response.interface";

package/dist/interfaces/payments/payment-audit-data.interface.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Payment audit data interface.
+ *
+ * Represents audit data for payment transactions and operations.
+ * Used for logging, monitoring, and compliance purposes.
+ * This data is stored in audit storage systems (e.g., DynamoDB, S3).
+ *
+ * @since 2.0.0
+ */
+export interface PaymentAuditData {
+    /**
+     * Unique transaction identifier.
+     *
+     * @example "txn_1234567890abcdef"
+     */
+    transactionId: string;
+    /**
+     * Unique identifier of the order associated with this transaction.
+     *
+     * @example "550e8400-e29b-41d4-a716-446655440000"
+     */
+    orderId: string;
+    /**
+     * Payment provider name.
+     *
+     * @example "stripe"
+     * @example "paypal"
+     */
+    provider: string;
+    /**
+     * API endpoint that was called.
+     *
+     * @example "/v1/payment_intents"
+     */
+    endpoint: string;
+    /**
+     * HTTP method used.
+     *
+     * @example "POST"
+     * @example "GET"
+     */
+    method: string;
+    /**
+     * HTTP status code of the response.
+     *
+     * @example 200
+     * @example 400
+     * @example 500
+     */
+    statusCode: number;
+    /**
+     * Status of the transaction.
+     *
+     * @example "succeeded"
+     * @example "failed"
+     * @example "pending"
+     */
+    status: string;
+    /**
+     * Duration of the operation in milliseconds.
+     *
+     * @example 1250
+     */
+    durationMs: number;
+    /**
+     * Optional IP address of the client.
+     *
+     * @example "192.168.1.1"
+     */
+    ipAddress?: string;
+    /**
+     * Optional request body sent to the provider.
+     * May be omitted for sensitive data.
+     */
+    requestBody?: Record<string, any>;
+    /**
+     * Optional response body received from the provider.
+     * May be omitted for sensitive data.
+     */
+    responseBody?: Record<string, any>;
+}

package/dist/interfaces/payments/payment-audit-data.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/payments/payment-method-config.interface.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Payment method configuration interface.
+ *
+ * Represents payment method configuration stored in DynamoDB.
+ * Contains credentials, settings, and metadata for payment providers
+ * configured for specific restaurants or chains.
+ *
+ * @since 2.0.0
+ */
+export interface PaymentMethodConfig {
+    /**
+     * Primary key (Partition Key) in DynamoDB.
+     * Typically a compound key like restaurantId#paymentMethodId.
+     *
+     * @example "restaurant-123#payment-method-456"
+     */
+    PK: string;
+    /**
+     * Sort key in DynamoDB.
+     * Used for additional querying capabilities.
+     *
+     * @example "CONFIG"
+     */
+    SK: string;
+    /**
+     * Configuration settings for the payment method.
+     * Key-value pairs of configuration options.
+     *
+     * @example { "testMode": "true", "timeout": "30000" }
+     */
+    configs: Record<string, string>;
+    /**
+     * Credentials for the payment provider.
+     * Contains sensitive information like API keys.
+     *
+     * @example { "apiKey": "sk_test_...", "secretKey": "..." }
+     */
+    credentials: Record<string, string>;
+    /**
+     * Currency code for payments.
+     * Should follow ISO 4217 format.
+     *
+     * @example "PEN"
+     * @example "USD"
+     */
+    currency: string;
+    /**
+     * Whether this payment method is enabled.
+     *
+     * @example true
+     * @example false
+     */
+    enabled: boolean;
+    /**
+     * Unique identifier of the payment method.
+     *
+     * @example "payment-method-uuid-123"
+     */
+    paymentMethodId: string;
+    /**
+     * Unique identifier of the restaurant.
+     *
+     * @example "restaurant-uuid-123"
+     */
+    restaurantId: string;
+    /**
+     * Provider key/identifier.
+     * Identifies which payment provider this configuration is for.
+     *
+     * @example "stripe"
+     * @example "paypal"
+     */
+    providerKey: string;
+    /**
+     * Date and time when the configuration was created.
+     *
+     * @example "2024-01-15T10:30:00Z"
+     */
+    createdAt: Date;
+    /**
+     * Date and time when the configuration was last updated.
+     *
+     * @example "2024-01-15T11:00:00Z"
+     */
+    updatedAt: Date;
+}

package/dist/interfaces/payments/payment-method-config.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/payments/payment-provider.interface.d.ts

@@ -0,0 +1,27 @@
+import { PaymentSessionDto } from '../../dtos/payments/payment-session.dto';
+import { WebhookDataDto } from '../../dtos/payments/webhook-data.dto';
+/**
+ * Payment provider interface.
+ *
+ * Defines the contract for payment providers using the Strategy pattern.
+ * Different implementations handle different payment providers
+ * (e.g., Stripe, PayPal, local payment methods).
+ *
+ * @since 2.0.0
+ */
+export interface PaymentProvider {
+    /**
+     * Creates a payment session with the payment provider.
+     *
+     * @param paymentSessionDto - Payment session data including order details
+     * @returns Promise resolving to payment session response (structure depends on provider)
+     */
+    createPaymentSession(paymentSessionDto: PaymentSessionDto): Promise<any>;
+    /**
+     * Handles webhook events from the payment provider.
+     *
+     * @param requestData - Webhook data including raw body, signature, and headers
+     * @returns Promise resolving to processed webhook result
+     */
+    handleWebhook(requestData: WebhookDataDto): Promise<any>;
+}

package/dist/interfaces/payments/payment-provider.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/payments/payment-session-item.interface.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Payment session item interface.
+ *
+ * Represents a flattened payment session item used internally by payment providers.
+ * This interface is used when sending item data to external payment providers
+ * (e.g., Stripe) in a simplified format.
+ *
+ * @since 2.0.0
+ */
+export interface PaymentSessionItem {
+    /**
+     * Product/item name.
+     *
+     * @example "Big Mac"
+     * @example "Large Coke"
+     */
+    name: string;
+    /**
+     * Unit price for this item.
+     *
+     * @example 9.99
+     */
+    price: number;
+    /**
+     * Quantity of this item.
+     *
+     * @example 2
+     */
+    quantity: number;
+}

package/dist/interfaces/payments/payment-session-item.interface.js

@@ -0,0 +1 @@
+export {};