@classytic/commerce-sdk 0.1.1

package/dist/pos-BCqkx2-K.d.ts

@@ -0,0 +1,527 @@
+import { e as Product, b as ProductVariant } from './product-p09zXkXB.js';
+import { P as PaginatedResponse, A as ApiResponse, B as BaseApi, R as RequestOptions } from './api-factory-B_h4RKBm.js';
+import { b as Order, l as CreateOrderPayload, U as UpdateStatusPayload, F as FulfillOrderPayload, R as RefundOrderPayload, h as OrderShipping, o as RequestShippingPayload, p as UpdateShippingPayload } from './order-B3dCvHgK.js';
+import { a as PosProductsResponse, g as PosLookupResponse, l as PosOrderPayload, ac as CreateAdjustmentPayload, ad as BulkAdjustmentPayload } from './inventory-B5pssqRx.js';
+
+/**
+ * Cart Types
+ *
+ * Type definitions for shopping cart matching the backend cart schema.
+ */
+
+/**
+ * Cart Item (Backend Response Format)
+ * Represents a single item in the shopping cart as returned by API
+ */
+interface CartItem {
+    /** Cart item ID (for update/remove operations via PATCH/DELETE /cart/items/:itemId) */
+    _id: string;
+    /** Product reference (fully populated Product object from backend) */
+    product: Product;
+    /**
+     * Variant SKU (optional)
+     * - null/undefined for simple products
+     * - Required for variant products (e.g., "TSHIRT-M-RED")
+     * - Must match a valid variant.sku from product.variants[]
+     */
+    variantSku?: string | null;
+    /** Quantity of this item (minimum: 1) */
+    quantity: number;
+}
+/**
+ * Shopping Cart
+ * Represents a user's shopping cart
+ */
+interface Cart {
+    /** Cart ID */
+    _id: string;
+    /** User/Customer ID */
+    user: string;
+    /** Cart items */
+    items: CartItem[];
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+}
+/**
+ * Populated Cart Item
+ * Cart item with fully populated product for display
+ */
+interface PopulatedCartItem {
+    /** Fully populated product */
+    product: Product;
+    /** Variant SKU */
+    variantSku?: string | null;
+    /** Quantity */
+    quantity: number;
+    /** Resolved variant (if variantSku is provided) */
+    variant?: ProductVariant;
+    /** Final price (basePrice + variant.priceModifier) */
+    finalPrice: number;
+    /** Line total (finalPrice * quantity) */
+    lineTotal: number;
+}
+/**
+ * Cart Summary
+ * Complete cart with computed totals
+ */
+interface CartSummary {
+    /** Populated cart items with derived fields */
+    items: PopulatedCartItem[];
+    /** Total item count (sum of all quantities) */
+    itemCount: number;
+    /** Subtotal (sum of all line totals) */
+    subtotal: number;
+}
+/**
+ * Add Item Payload
+ * Data required to add an item to cart via POST /api/v1/cart/items
+ */
+interface AddCartItemPayload {
+    /** Product ID (required) */
+    productId: string;
+    /**
+     * Variant SKU (required for variant products, omit for simple products)
+     * - For simple products: omit this field
+     * - For variant products: must match a valid variant.sku from product.variants[]
+     */
+    variantSku?: string | null;
+    /** Quantity to add (minimum: 1, required) */
+    quantity: number;
+}
+/** Alias for AddCartItemPayload (for consistency with hooks) */
+type AddToCartPayload = AddCartItemPayload;
+/**
+ * Update Item Payload
+ * Data required to update cart item quantity
+ */
+interface UpdateCartItemPayload {
+    /** Cart item ID */
+    itemId: string;
+    /** New quantity (minimum: 1) */
+    quantity: number;
+}
+/**
+ * Remove Item Payload
+ * Data required to remove an item from cart
+ */
+interface RemoveCartItemPayload {
+    /** Cart item ID */
+    itemId: string;
+}
+/**
+ * Cart API Response
+ */
+interface CartResponse {
+    success: boolean;
+    data: Cart;
+}
+/**
+ * @deprecated Use the new variant system instead
+ * Legacy type for old variation system - kept for backwards compatibility
+ */
+interface CartItemVariation {
+    name: string;
+    option: {
+        value: string;
+        priceModifier: number;
+    };
+}
+
+/**
+ * Customer Types
+ *
+ * Matches backend `modules/customer/customer.model.js`.
+ * Customer is the profile entity (addresses, phone, etc.) linked to auth `User` via `userId`.
+ */
+
+type CustomerGender = 'male' | 'female' | 'other' | 'prefer-not-to-say';
+type CustomerTier = 'bronze' | 'silver' | 'gold' | 'platinum';
+/**
+ * Customer Address
+ *
+ * Stores user's saved addresses with area info for delivery.
+ */
+interface CustomerAddress {
+    _id?: string;
+    recipientName?: string;
+    /** Contact phone for delivery */
+    recipientPhone?: string;
+    label?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    division?: string;
+    postalCode?: string;
+    country?: string;
+    /** @deprecated Use recipientPhone instead */
+    phone?: string;
+    isDefault?: boolean;
+    /** Area internalId from @classytic/bd-areas */
+    areaId?: number;
+    /** Area name for display */
+    areaName?: string;
+    /** Delivery zone (1-6) for pricing tier */
+    zoneId?: number;
+    /** Provider-specific area IDs for logistics */
+    providerAreaIds?: {
+        redx?: number;
+        pathao?: number;
+    };
+}
+interface CustomerStats {
+    orders?: {
+        total?: number;
+        completed?: number;
+        cancelled?: number;
+        refunded?: number;
+    };
+    revenue?: {
+        total?: number;
+        lifetime?: number;
+    };
+    firstOrderDate?: string;
+    lastOrderDate?: string;
+    /**
+     * Some deployments may include subscription stats; keep optional to avoid breaking.
+     */
+    subscriptions?: {
+        active?: number;
+        cancelled?: number;
+    };
+}
+interface CustomerMembership {
+    cardId: string;
+    isActive: boolean;
+    enrolledAt?: string;
+    points?: {
+        current?: number;
+        lifetime?: number;
+        redeemed?: number;
+    };
+    tier?: string;
+    tierOverride?: string;
+    tierOverrideReason?: string;
+    tierOverrideBy?: string;
+}
+interface Customer {
+    _id: string;
+    id?: string;
+    userId?: string;
+    name: string;
+    phone: string;
+    email?: string;
+    dateOfBirth?: string;
+    gender?: CustomerGender;
+    addresses?: CustomerAddress[];
+    stats?: CustomerStats;
+    tags?: string[];
+    notes?: string;
+    isActive?: boolean;
+    membership?: CustomerMembership | null;
+    defaultAddress?: CustomerAddress | null;
+    tier?: CustomerTier;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface CustomerPayload {
+    name?: string;
+    phone?: string;
+    email?: string;
+    dateOfBirth?: string;
+    gender?: CustomerGender;
+    addresses?: CustomerAddress[];
+    tags?: string[];
+    notes?: string;
+    isActive?: boolean;
+}
+interface CustomerQueryParams {
+    page?: number;
+    limit?: number;
+    after?: string;
+    sort?: string | Record<string, 1 | -1 | 'asc' | 'desc'>;
+    name?: string;
+    phone?: string;
+    email?: string;
+    userId?: string;
+    populate?: 'userId' | Array<'userId'> | string | string[];
+    [key: string]: unknown;
+}
+type CustomerListResponse = PaginatedResponse<Customer>;
+type CustomerResponse = ApiResponse<Customer>;
+
+/**
+ * Cart API Client
+ *
+ * **Authentication:** Required for all endpoints (use Bearer token)
+ *
+ * **Base URL:** `/api/v1/cart`
+ *
+ * **Endpoints:**
+ * - `GET /api/v1/cart` - Get current user's cart (auto-creates if doesn't exist)
+ * - `POST /api/v1/cart/items` - Add item to cart (productId + quantity + optional variantSku)
+ * - `PATCH /api/v1/cart/items/:itemId` - Update cart item quantity
+ * - `DELETE /api/v1/cart/items/:itemId` - Remove item from cart
+ * - `DELETE /api/v1/cart` - Clear all items from cart
+ *
+ * **Response Format:** All endpoints return `{ success: true, data: Cart }`
+ */
+
+declare const cartApi: {
+    /**
+     * Get current user's cart
+     * GET /api/v1/cart
+     *
+     * Auto-creates cart if it doesn't exist for the user.
+     * Returns cart with fully populated product details.
+     *
+     * @param token - User authentication token
+     * @returns Cart with items array
+     */
+    getCart: (token: string) => Promise<Cart>;
+    /**
+     * Add item to cart
+     * POST /api/v1/cart/items
+     *
+     * @param token - User authentication token
+     * @param data - Product ID, quantity, and optional variant SKU
+     * @returns Updated cart
+     */
+    addToCart: (token: string, data: AddCartItemPayload) => Promise<Cart>;
+    /**
+     * Update cart item quantity
+     * PATCH /api/v1/cart/items/:itemId
+     *
+     * @param token - User authentication token
+     * @param itemId - Cart item ID (from cart.items[]._id)
+     * @param quantity - New quantity (minimum: 1)
+     * @returns Updated cart
+     */
+    updateCartItem: (token: string, itemId: string, quantity: number) => Promise<Cart>;
+    /**
+     * Remove item from cart
+     * DELETE /api/v1/cart/items/:itemId
+     *
+     * @param token - User authentication token
+     * @param itemId - Cart item ID (from cart.items[]._id)
+     * @returns Updated cart
+     */
+    removeCartItem: (token: string, itemId: string) => Promise<Cart>;
+    /**
+     * Clear all items from cart
+     * DELETE /api/v1/cart
+     *
+     * @param token - User authentication token
+     * @returns Empty cart
+     */
+    clearCart: (token: string) => Promise<Cart>;
+};
+
+declare class OrderApi extends BaseApi<Order, CreateOrderPayload, Partial<Order>> {
+    /**
+     * Checkout - create order from cart
+     * POST /api/v1/orders
+     */
+    checkout: ({ token, organizationId, data }: {
+        token: string;
+        organizationId?: string | null;
+        data: CreateOrderPayload;
+    }) => Promise<ApiResponse<Order>>;
+    /** Get my orders */
+    getMyOrders: ({ token, params }: {
+        token: string;
+        params?: Record<string, unknown>;
+    }) => Promise<Order[]>;
+    /** Get my order detail */
+    getMyOrder: ({ token, id }: {
+        token: string;
+        id: string;
+    }) => Promise<Order>;
+    /** Cancel order */
+    cancel: ({ token, id, reason, refund }: {
+        token: string;
+        id: string;
+        reason?: string;
+        refund?: boolean;
+    }) => Promise<Order>;
+    /** Request cancellation (awaits admin review) */
+    requestCancellation: ({ token, id, reason }: {
+        token: string;
+        id: string;
+        reason?: string;
+    }) => Promise<Order>;
+    /** Update order status */
+    updateStatus: ({ token, organizationId, id, data }: {
+        token: string;
+        organizationId?: string | null;
+        id: string;
+        data: UpdateStatusPayload;
+    }) => Promise<Order>;
+    /**
+     * Fulfill order (ship)
+     * - Decrements inventory from branch
+     * - recordCogs: true -> also creates COGS expense transaction
+     */
+    fulfill: ({ token, organizationId, id, data }: {
+        token: string;
+        organizationId?: string | null;
+        id: string;
+        data?: FulfillOrderPayload;
+    }) => Promise<Order>;
+    /** Refund order */
+    refund: ({ token, organizationId, id, data }: {
+        token: string;
+        organizationId?: string | null;
+        id: string;
+        data?: RefundOrderPayload;
+    }) => Promise<Order>;
+    /** Get shipping info */
+    getShipping: ({ token, id }: {
+        token: string;
+        id: string;
+    }) => Promise<OrderShipping>;
+    /** Request shipping pickup */
+    requestShipping: ({ token, organizationId, id, data }: {
+        token: string;
+        organizationId?: string | null;
+        id: string;
+        data: RequestShippingPayload;
+    }) => Promise<OrderShipping>;
+    /** Update shipping status */
+    updateShipping: ({ token, organizationId, id, data }: {
+        token: string;
+        organizationId?: string | null;
+        id: string;
+        data: UpdateShippingPayload;
+    }) => Promise<OrderShipping>;
+}
+declare const orderApi: OrderApi;
+
+/**
+ * Customer API - CRUD + helper endpoint
+ *
+ * Standard CRUD (inherited from BaseApi):
+ * - getAll({ token, params }) - list with filtering/search/pagination
+ * - getById({ token, id }) - get by ID
+ * - update({ token, id, data }) - update (admin/staff rules apply)
+ * - delete({ token, id }) - delete (admin only)
+ *
+ * Notes:
+ * - Customers may be auto-created by backend workflows; some environments may not expose create.
+ *
+ * Extra endpoint:
+ * - getMe({ token }) - current user's customer profile
+ */
+
+type FetchOptions = Omit<RequestOptions, 'token' | 'organizationId'>;
+declare class CustomerApi extends BaseApi<Customer, CustomerPayload, CustomerPayload> {
+    constructor(config?: {});
+    /**
+     * Get current user's customer profile
+     * GET /customers/me
+     */
+    getMe({ token, options, }: {
+        token: string;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<Customer>>;
+    /**
+     * Membership actions
+     * POST /customers/:id/membership
+     */
+    membershipAction({ token, id, data, }: {
+        token: string;
+        id: string;
+        data: {
+            action: 'enroll' | 'deactivate' | 'reactivate' | 'adjust';
+            points?: number;
+            reason?: string;
+            type?: 'bonus' | 'correction' | 'manual_redemption' | 'redemption' | 'expiry';
+        };
+    }): Promise<ApiResponse<Customer>>;
+}
+declare const customerApi: CustomerApi;
+
+/**
+ * POS API Client
+ *
+ * Follows BaseApi pattern: all methods accept { token, ...params/data }
+ */
+
+declare class PosApi extends BaseApi {
+    /**
+     * Browse products with branch-specific stock
+     * GET /api/v1/pos/products
+     */
+    getProducts(options: {
+        token: string;
+        branchId?: string;
+        /** Filter by category slug (matches both parent and child categories) */
+        category?: string;
+        search?: string;
+        inStockOnly?: boolean;
+        lowStockOnly?: boolean;
+        sort?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<PosProductsResponse>;
+    /**
+     * Fast Lookup by Barcode/SKU
+     * GET /api/v1/pos/lookup
+     */
+    lookup(options: {
+        token: string;
+        code: string;
+        branchId?: string;
+    }): Promise<PosLookupResponse>;
+    /**
+     * Create POS Order
+     * POST /api/v1/pos/orders
+     */
+    createOrder(options: {
+        token: string;
+        data: PosOrderPayload;
+    }): Promise<unknown>;
+    /**
+     * Get Receipt Data
+     * GET /api/v1/pos/orders/:orderId/receipt
+     */
+    getReceipt(options: {
+        token: string;
+        orderId: string;
+    }): Promise<unknown>;
+    /**
+     * Adjust Stock (Quick Adjustment from POS)
+     * POST /api/v1/pos/stock/adjust
+     */
+    adjustStock(options: {
+        token: string;
+        data: CreateAdjustmentPayload;
+    }): Promise<unknown>;
+    /**
+     * Set stock level directly (POS adjustment alias)
+     * POST /api/v1/pos/stock/adjust
+     */
+    setStock(options: {
+        token: string;
+        productId: string;
+        data: {
+            quantity: number;
+            branchId?: string;
+            variantSku?: string;
+            reason?: string;
+            notes?: string;
+        };
+    }): Promise<unknown>;
+    /**
+     * Bulk adjustments (POS adjustment alias)
+     * POST /api/v1/pos/stock/adjust
+     */
+    bulkAdjust(options: {
+        token: string;
+        data: BulkAdjustmentPayload;
+    }): Promise<unknown>;
+}
+declare const posApi: PosApi;
+
+export { type AddCartItemPayload as A, type Cart as C, type PopulatedCartItem as P, type RemoveCartItemPayload as R, type UpdateCartItemPayload as U, type CartItem as a, type CartSummary as b, type AddToCartPayload as c, type CartResponse as d, type CartItemVariation as e, type Customer as f, type CustomerAddress as g, type CustomerStats as h, type CustomerMembership as i, type CustomerPayload as j, type CustomerQueryParams as k, type CustomerListResponse as l, type CustomerResponse as m, type CustomerGender as n, type CustomerTier as o, cartApi as p, orderApi as q, customerApi as r, CustomerApi as s, posApi as t };