@novha/anlia-core-lib 0.1.0

package/src/orders/domain/posDto/SquareOrder.ts

@@ -0,0 +1,346 @@
+/**
+ * Square POS order payload interfaces.
+ * Field names and types are derived directly from the Square Orders API v2.
+ * All monetary amounts are integers in the smallest currency unit (e.g. cents).
+ * @see https://developer.squareup.com/reference/square/orders-api
+ */
+
+// ─── Shared primitives ────────────────────────────────────────────────────────
+
+export interface SquareMoney {
+    /** Amount in the smallest currency unit (e.g. cents). */
+    amount: number;
+    currency: string;
+}
+
+export interface SquareAddress {
+    address_line_1?: string;
+    address_line_2?: string;
+    address_line_3?: string;
+    locality?: string;
+    sublocality?: string;
+    administrative_district_level_1?: string;
+    postal_code?: string;
+    country?: string;
+    first_name?: string;
+    last_name?: string;
+}
+
+// ─── Order totals ─────────────────────────────────────────────────────────────
+
+export interface SquareOrderMoneyAmounts {
+    total_money: SquareMoney;
+    tax_money: SquareMoney;
+    discount_money: SquareMoney;
+    tip_money: SquareMoney;
+    service_charge_money: SquareMoney;
+}
+
+// ─── Source ───────────────────────────────────────────────────────────────────
+
+export interface SquareOrderSource {
+    name?: string;
+}
+
+// ─── Taxes ────────────────────────────────────────────────────────────────────
+
+export interface SquareOrderLineItemAppliedTax {
+    uid: string;
+    tax_uid: string;
+    applied_money: SquareMoney;
+}
+
+export interface SquareOrderTax {
+    uid?: string;
+    catalog_object_id?: string;
+    catalog_version?: number;
+    name?: string;
+    /** "UNKNOWN_TAX" | "ADDITIVE" | "INCLUSIVE" */
+    type?: string;
+    percentage?: string;
+    metadata?: Record<string, string>;
+    applied_money?: SquareMoney;
+    /** "OTHER_TAX_SCOPE" | "LINE_ITEM" | "ORDER" */
+    scope?: string;
+}
+
+// ─── Discounts ────────────────────────────────────────────────────────────────
+
+export interface SquareOrderLineItemAppliedDiscount {
+    uid: string;
+    discount_uid: string;
+    applied_money: SquareMoney;
+}
+
+export interface SquareOrderDiscount {
+    uid?: string;
+    catalog_object_id?: string;
+    catalog_version?: number;
+    name?: string;
+    /** "UNKNOWN_DISCOUNT" | "FIXED_PERCENTAGE" | "FIXED_AMOUNT" | "VARIABLE_PERCENTAGE" | "VARIABLE_AMOUNT" */
+    type?: string;
+    percentage?: string;
+    amount_money?: SquareMoney;
+    applied_money?: SquareMoney;
+    metadata?: Record<string, string>;
+    /** "OTHER_DISCOUNT_SCOPE" | "LINE_ITEM" | "ORDER" */
+    scope?: string;
+    reward_ids?: string[];
+    pricing_rule_id?: string;
+}
+
+// ─── Service charges ──────────────────────────────────────────────────────────
+
+export interface SquareOrderLineItemAppliedServiceCharge {
+    uid: string;
+    service_charge_uid: string;
+    applied_money: SquareMoney;
+}
+
+export interface SquareOrderServiceCharge {
+    uid?: string;
+    name?: string;
+    catalog_object_id?: string;
+    catalog_version?: number;
+    percentage?: string;
+    amount_money?: SquareMoney;
+    applied_money?: SquareMoney;
+    total_money?: SquareMoney;
+    total_tax_money?: SquareMoney;
+    /** "SUBTOTAL_PHASE" | "TOTAL_PHASE" */
+    calculation_phase?: string;
+    taxable?: boolean;
+    applied_taxes?: SquareOrderLineItemAppliedTax[];
+    metadata?: Record<string, string>;
+    /** "AUTO_GRATUITY" | "CUSTOM" */
+    type?: string;
+    /** "LINE_ITEM_TREATMENT" | "APPORTIONED_TREATMENT" */
+    treatment_type?: string;
+    /** "OTHER_SERVICE_CHARGE_SCOPE" | "LINE_ITEM" | "ORDER" */
+    scope?: string;
+}
+
+// ─── Line item modifiers ──────────────────────────────────────────────────────
+
+export interface SquareOrderLineItemModifier {
+    uid?: string;
+    catalog_object_id?: string;
+    catalog_version?: number;
+    name?: string;
+    quantity?: string;
+    base_price_money?: SquareMoney;
+    total_price_money?: SquareMoney;
+    metadata?: Record<string, string>;
+}
+
+// ─── Line items ───────────────────────────────────────────────────────────────
+
+export interface SquareOrderLineItem {
+    uid?: string;
+    name?: string;
+    /** Quantity as a string, e.g. "1", "2.5". */
+    quantity: string;
+    quantity_unit?: {
+        measurement_unit?: { custom_unit?: { name: string }; area_unit?: string; length_unit?: string; volume_unit?: string; weight_unit?: string; generic_unit?: string; time_unit?: string; type?: string };
+        precision?: number;
+        catalog_object_id?: string;
+        catalog_version?: number;
+    };
+    note?: string;
+    catalog_object_id?: string;
+    catalog_version?: number;
+    variation_name?: string;
+    /** "ITEM" | "CUSTOM_AMOUNT" | "GIFT_CARD" */
+    item_type?: string;
+    metadata?: Record<string, string>;
+    modifiers?: SquareOrderLineItemModifier[];
+    applied_taxes?: SquareOrderLineItemAppliedTax[];
+    applied_discounts?: SquareOrderLineItemAppliedDiscount[];
+    applied_service_charges?: SquareOrderLineItemAppliedServiceCharge[];
+    base_price_money?: SquareMoney;
+    variation_total_price_money?: SquareMoney;
+    gross_sales_money?: SquareMoney;
+    total_tax_money?: SquareMoney;
+    total_discount_money?: SquareMoney;
+    total_service_charge_money?: SquareMoney;
+    total_money?: SquareMoney;
+}
+
+// ─── Fulfillment ──────────────────────────────────────────────────────────────
+
+export interface SquareOrderFulfillmentRecipient {
+    customer_id?: string;
+    display_name?: string;
+    email_address?: string;
+    phone_number?: string;
+    address?: SquareAddress;
+}
+
+export interface SquareOrderFulfillmentPickupDetails {
+    recipient?: SquareOrderFulfillmentRecipient;
+    expires_at?: string;
+    auto_complete_duration?: string;
+    /** "SCHEDULED" | "ASAP" */
+    schedule_type?: string;
+    pickup_at?: string;
+    pickup_window_duration?: string;
+    prep_time_duration?: string;
+    note?: string;
+    placed_at?: string;
+    accepted_at?: string;
+    rejected_at?: string;
+    ready_at?: string;
+    expired_at?: string;
+    picked_up_at?: string;
+    canceled_at?: string;
+    cancel_reason?: string;
+    is_curbside_pickup?: boolean;
+    curbside_pickup_details?: {
+        curbside_details?: string;
+        buyer_arrived_at?: string;
+    };
+}
+
+export interface SquareOrderFulfillmentDeliveryDetails {
+    recipient?: SquareOrderFulfillmentRecipient;
+    /** "PENDING" | "RESERVED" | "PREPARED" | "COMPLETED" | "CANCELED" | "FAILED" */
+    schedule_type?: string;
+    placed_at?: string;
+    deliver_at?: string;
+    prep_time_duration?: string;
+    delivery_window_duration?: string;
+    note?: string;
+    completed_at?: string;
+    in_progress_at?: string;
+    rejected_at?: string;
+    ready_at?: string;
+    delivered_at?: string;
+    canceled_at?: string;
+    cancel_reason?: string;
+    courier_pickup_at?: string;
+    courier_pickup_window_duration?: string;
+    is_no_contact_delivery?: boolean;
+    dropoff_notes?: string;
+    courier_provider_name?: string;
+    courier_support_phone_number?: string;
+    square_delivery_id?: string;
+    external_delivery_id?: string;
+    managed_delivery?: boolean;
+}
+
+export interface SquareOrderFulfillmentShipmentDetails {
+    recipient?: SquareOrderFulfillmentRecipient;
+    carrier?: string;
+    shipping_note?: string;
+    shipping_type?: string;
+    tracking_number?: string;
+    tracking_url?: string;
+    placed_at?: string;
+    in_progress_at?: string;
+    packaged_at?: string;
+    expected_shipped_at?: string;
+    shipped_at?: string;
+    canceled_at?: string;
+    cancel_reason?: string;
+    failed_at?: string;
+    failure_reason?: string;
+}
+
+export interface SquareOrderFulfillment {
+    uid?: string;
+    /** "PICKUP" | "SHIPMENT" | "DELIVERY" | "DIGITAL" */
+    type?: string;
+    /** "PROPOSED" | "RESERVED" | "PREPARED" | "COMPLETED" | "CANCELED" | "FAILED" */
+    state?: string;
+    /** "ALL" | "ENTRY_LIST" */
+    line_item_application?: string;
+    metadata?: Record<string, string>;
+    pickup_details?: SquareOrderFulfillmentPickupDetails;
+    shipment_details?: SquareOrderFulfillmentShipmentDetails;
+    delivery_details?: SquareOrderFulfillmentDeliveryDetails;
+}
+
+// ─── Returns (refunds) ────────────────────────────────────────────────────────
+
+export interface SquareOrderReturnLineItem {
+    uid?: string;
+    source_line_item_uid?: string;
+    name?: string;
+    quantity: string;
+    base_price_money?: SquareMoney;
+    variation_total_price_money?: SquareMoney;
+    gross_return_money?: SquareMoney;
+    total_tax_money?: SquareMoney;
+    total_discount_money?: SquareMoney;
+    total_service_charge_money?: SquareMoney;
+    total_money?: SquareMoney;
+    applied_taxes?: SquareOrderLineItemAppliedTax[];
+    applied_discounts?: SquareOrderLineItemAppliedDiscount[];
+}
+
+export interface SquareOrderReturn {
+    uid?: string;
+    source_order_id?: string;
+    return_line_items?: SquareOrderReturnLineItem[];
+    return_taxes?: SquareOrderTax[];
+    return_discounts?: SquareOrderDiscount[];
+    return_service_charges?: SquareOrderServiceCharge[];
+    return_amounts?: SquareOrderMoneyAmounts;
+}
+
+// ─── Order (top-level) ────────────────────────────────────────────────────────
+
+export interface SquareOrder {
+    id: string;
+    location_id: string;
+    reference_id?: string;
+    source?: SquareOrderSource;
+    customer_id?: string;
+    line_items?: SquareOrderLineItem[];
+    taxes?: SquareOrderTax[];
+    discounts?: SquareOrderDiscount[];
+    service_charges?: SquareOrderServiceCharge[];
+    fulfillments?: SquareOrderFulfillment[];
+    returns?: SquareOrderReturn[];
+    return_amounts?: SquareOrderMoneyAmounts;
+    net_amounts?: SquareOrderMoneyAmounts;
+    /** Rounding adjustment for cash transactions. */
+    rounding_adjustment?: { uid?: string; name?: string; amount_money?: SquareMoney };
+    tenders?: Array<{
+        id?: string;
+        location_id?: string;
+        transaction_id?: string;
+        created_at?: string;
+        note?: string;
+        amount_money?: SquareMoney;
+        tip_money?: SquareMoney;
+        processing_fee_money?: SquareMoney;
+        customer_id?: string;
+        /** "CARD" | "CASH" | "THIRD_PARTY_CARD" | "SQUARE_GIFT_CARD" | "NO_SALE" | "BANK_ACCOUNT" | "WALLET" | "BUY_NOW_PAY_LATER" | "SQUARE_ACCOUNT" | "OTHER" */
+        type?: string;
+        card_details?: {
+            /** "AUTHORIZED" | "CAPTURED" | "VOIDED" | "FAILED" */
+            status?: string;
+            card?: { card_brand?: string; last_4?: string; exp_month?: number; exp_year?: number; fingerprint?: string; card_type?: string; prepaid_type?: string; bin?: string };
+            entry_method?: string;
+        };
+        cash_details?: { buyer_tendered_money?: SquareMoney; change_back_money?: SquareMoney };
+    }>;
+    refunds?: Array<{ id: string; location_id: string; transaction_id?: string; tender_id: string; created_at?: string; reason: string; amount_money: SquareMoney; status: string; processing_fee_money?: SquareMoney }>;
+    metadata?: Record<string, string>;
+    /** "OPEN" | "COMPLETED" | "CANCELED" | "DRAFT" */
+    state?: string;
+    version?: number;
+    ticket_name?: string;
+    pricing_options?: { auto_apply_discounts?: boolean; auto_apply_taxes?: boolean };
+    rewards?: Array<{ id: string; reward_tier_id: string }>;
+    net_amount_due_money?: SquareMoney;
+    total_money?: SquareMoney;
+    total_tax_money?: SquareMoney;
+    total_discount_money?: SquareMoney;
+    total_tip_money?: SquareMoney;
+    total_service_charge_money?: SquareMoney;
+    created_at?: string;
+    updated_at?: string;
+    closed_at?: string;
+}

package/src/orders/index.ts

@@ -0,0 +1,7 @@
+export * from "./domain/Order";
+export * from "./domain/OrderItem";
+export * from "./domain/Enums";
+export * from "./ioc";
+export * from "./OrderModule";
+export * from "./domain/posDto/SquareOrder";
+export { SquareOrderServiceImpl as SquareOrderService } from "./services/square/SquareOrderServiceImpl";

package/src/orders/ioc/index.ts

@@ -0,0 +1,3 @@
+export const OrderSymbols = {
+	SquareOrderService: Symbol('SquareOrderService'),
+};

package/src/orders/services/square/SquareOrderService.ts

@@ -0,0 +1,27 @@
+import { IOrder } from "../../domain/Order";
+import { IOrderItem } from "../../domain/OrderItem";
+import { OrderStatus } from "../../domain/Enums";
+import { SquareOrder } from "../../domain/posDto/SquareOrder";
+
+export const SQUARE_ORDER_SERVICE = Symbol("SQUARE_ORDER_SERVICE");
+
+export interface ISquareOrderService {
+    // ─── Order lifecycle ──────────────────────────────────────────────────────
+    createOrder(order: SquareOrder): Promise<IOrder>;
+    updateOrder(orderId: string, restaurantId: string, before: Partial<IOrder>, after: Partial<IOrder>): Promise<void>;
+    submitOrder(orderId: string, restaurantId: string, submittedBy?: string): Promise<void>;
+    confirmOrder(orderId: string, restaurantId: string, confirmedBy?: string): Promise<void>;
+    rejectOrder(orderId: string, restaurantId: string, reason?: string, rejectedBy?: string): Promise<void>;
+    cancelOrder(orderId: string, restaurantId: string, previousStatus: OrderStatus, reason?: string, cancelledBy?: string): Promise<void>;
+    completeOrder(orderId: string, restaurantId: string, completedBy?: string): Promise<void>;
+    reopenOrder(orderId: string, restaurantId: string, previousStatus: OrderStatus, reason?: string, reopenedBy?: string): Promise<void>;
+    closeOrder(orderId: string, restaurantId: string, closedBy?: string): Promise<void>;
+
+    // ─── Order items ──────────────────────────────────────────────────────────
+    addOrderItem(orderId: string, restaurantId: string, item: IOrderItem, addedBy?: string): Promise<void>;
+    updateOrderItem(orderId: string, restaurantId: string, before: Partial<IOrderItem>, after: Partial<IOrderItem>, updatedBy?: string): Promise<void>;
+    removeOrderItem(orderId: string, restaurantId: string, itemId: string, reason?: string, removedBy?: string): Promise<void>;
+    markOrderItemPrepared(orderId: string, restaurantId: string, itemId: string, preparedBy?: string): Promise<void>;
+    markOrderItemServed(orderId: string, restaurantId: string, itemId: string, servedBy?: string): Promise<void>;
+    voidOrderItem(orderId: string, restaurantId: string, itemId: string, reason?: string, voidedBy?: string): Promise<void>;
+}