@classytic/commerce-sdk 0.1.1

package/dist/coupon-CDzL4bJG.d.ts

@@ -0,0 +1,655 @@
+import { P as PaginatedResponse, A as ApiResponse, B as BaseApi, R as RequestOptions } from './api-factory-B_h4RKBm.js';
+
+/**
+ * Platform Config Types
+ *
+ * Mirrors `modules/platform/platform.model.js` (PlatformConfig singleton).
+ * Includes payment methods, checkout, logistics, VAT, and policies.
+ */
+type PaymentMethodType = "cash" | "mfs" | "bank_transfer" | "card";
+interface PaymentMethodConfig {
+    _id?: string;
+    type: PaymentMethodType;
+    name: string;
+    provider?: "bkash" | "nagad" | "rocket" | "upay";
+    walletNumber?: string;
+    walletName?: string;
+    bankName?: string;
+    accountNumber?: string;
+    accountName?: string;
+    branchName?: string;
+    routingNumber?: string;
+    cardTypes?: ("visa" | "mastercard" | "amex" | "unionpay" | "other")[];
+    note?: string;
+    isActive?: boolean;
+}
+interface PlatformVatCategoryRate {
+    category: string;
+    rate: number;
+    description?: string;
+}
+interface PlatformVatInvoiceConfig {
+    showVatBreakdown?: boolean;
+    prefix?: string;
+    startNumber?: number;
+    currentNumber?: number;
+    footerText?: string;
+}
+interface PlatformSupplementaryDutyConfig {
+    enabled?: boolean;
+    defaultRate?: number;
+}
+interface PlatformVatConfig {
+    isRegistered: boolean;
+    bin?: string;
+    registeredName?: string;
+    vatCircle?: string;
+    defaultRate: number;
+    pricesIncludeVat: boolean;
+    categoryRates?: PlatformVatCategoryRate[];
+    invoice?: PlatformVatInvoiceConfig;
+    supplementaryDuty?: PlatformSupplementaryDutyConfig;
+}
+interface DeliveryZone {
+    _id?: string;
+    name: string;
+    region: string;
+    price: number;
+    estimatedDays?: number;
+    isActive?: boolean;
+}
+interface CheckoutPickupBranch {
+    branchId?: string;
+    branchCode?: string;
+    branchName?: string;
+}
+type DeliveryFeeSource = "static" | "provider";
+interface CheckoutSettings {
+    allowStorePickup: boolean;
+    pickupBranches: CheckoutPickupBranch[];
+    deliveryFeeSource: DeliveryFeeSource;
+    freeDeliveryThreshold: number;
+    deliveryZones: DeliveryZone[];
+}
+interface LogisticsSettings {
+    defaultPickupStoreId?: number;
+    defaultPickupStoreName?: string;
+    defaultPickupAreaId?: number;
+    defaultPickupAreaName?: string;
+    webhookSecret?: string;
+    autoCreateShipment: boolean;
+    autoCreateOnStatus: string;
+}
+interface PlatformPolicies {
+    termsAndConditions?: string;
+    privacyPolicy?: string;
+    refundPolicy?: string;
+    shippingPolicy?: string;
+}
+type MembershipRoundingMode = "floor" | "round" | "ceil";
+interface MembershipTierConfig {
+    name: string;
+    minPoints: number;
+    pointsMultiplier: number;
+    discountPercent: number;
+    color?: string;
+}
+interface MembershipRedemptionConfig {
+    enabled: boolean;
+    minRedeemPoints: number;
+    minOrderAmount: number;
+    maxRedeemPercent: number;
+    pointsPerBdt: number;
+}
+interface MembershipConfig {
+    enabled: boolean;
+    pointsPerAmount: number;
+    amountPerPoint: number;
+    roundingMode: MembershipRoundingMode;
+    tiers: MembershipTierConfig[];
+    cardPrefix: string;
+    cardDigits: number;
+    redemption?: MembershipRedemptionConfig;
+}
+interface PlatformConfig {
+    _id: string;
+    platformName: string;
+    /** Flexible payment methods array */
+    paymentMethods: PaymentMethodConfig[];
+    checkout: CheckoutSettings;
+    logistics: LogisticsSettings;
+    vat: PlatformVatConfig;
+    membership?: MembershipConfig;
+    policies?: PlatformPolicies;
+    isSingleton: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface UpdatePlatformConfigPayload {
+    platformName?: string;
+    paymentMethods?: PaymentMethodConfig[];
+    checkout?: Partial<CheckoutSettings>;
+    logistics?: Partial<LogisticsSettings>;
+    vat?: Partial<PlatformVatConfig>;
+    membership?: Partial<MembershipConfig>;
+    policies?: Partial<PlatformPolicies>;
+}
+
+/**
+ * Branch Types
+ *
+ * Type definitions for store/warehouse locations.
+ * Separated from inventory types for better organization and single responsibility.
+ */
+type BranchType = 'store' | 'warehouse' | 'outlet' | 'franchise';
+/**
+ * Branch Hierarchy Role
+ * Determines the branch's position in the inventory flow hierarchy.
+ *
+ * - head_office: Central warehouse/HQ that receives purchases and distributes to sub-branches
+ * - sub_branch: Store/outlet that receives stock from head office
+ */
+type BranchRole = 'head_office' | 'sub_branch';
+interface BranchAddress {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+}
+/**
+ * Branch (Store/Warehouse Location)
+ *
+ * Represents a physical location for inventory tracking and POS operations.
+ * Every deployment must have at least one branch (default branch).
+ *
+ * Branch Hierarchy:
+ * - One branch must be designated as head_office (typically the default branch)
+ * - All other branches are sub_branch by default
+ * - Stock flows: Suppliers -> Head Office -> Sub-branches
+ */
+interface Branch {
+    _id: string;
+    /** URL-friendly slug (auto-generated from name) */
+    slug: string;
+    /** Unique branch code (e.g., "DHK-1", "CTG-MAIN") - uppercase, stable */
+    code: string;
+    /** Display name */
+    name: string;
+    /** Branch type (store, warehouse, outlet, franchise) */
+    type: BranchType;
+    /**
+     * Branch role in inventory hierarchy
+     * - head_office: Receives purchases, distributes to sub-branches
+     * - sub_branch: Receives stock from head office only
+     */
+    role: BranchRole;
+    /** Physical address */
+    address?: BranchAddress;
+    /** Contact phone */
+    phone?: string;
+    /** Contact email */
+    email?: string;
+    /** Operating hours (simple format, e.g., "10:00 AM - 10:00 PM") */
+    operatingHours?: string;
+    /** Whether this is the default branch (only one can be default) */
+    isDefault: boolean;
+    /** Whether this branch is active */
+    isActive: boolean;
+    /** Manager user ID reference */
+    manager?: string;
+    /** Admin notes (admin-only field) */
+    notes?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Create Branch Payload
+ */
+interface CreateBranchPayload {
+    code: string;
+    name: string;
+    type?: BranchType;
+    /** Branch hierarchy role (defaults to 'sub_branch') */
+    role?: BranchRole;
+    address?: BranchAddress;
+    phone?: string;
+    email?: string;
+    operatingHours?: string;
+    isDefault?: boolean;
+}
+/**
+ * Update Branch Payload
+ */
+interface UpdateBranchPayload extends Partial<CreateBranchPayload> {
+    isActive?: boolean;
+    notes?: string;
+}
+/**
+ * Branch Summary (for dropdowns, lists)
+ */
+interface BranchSummary {
+    _id: string;
+    code: string;
+    name: string;
+    role: BranchRole;
+    isDefault: boolean;
+}
+/**
+ * Check if branch is head office
+ */
+declare function isHeadOffice(branch: Branch | BranchSummary): boolean;
+/**
+ * Check if branch is sub-branch
+ */
+declare function isSubBranch(branch: Branch | BranchSummary): boolean;
+
+/**
+ * User Types for Admin Management
+ *
+ * Simple types for CRUD operations on users.
+ * Frontend uses standard BaseApi methods with these types.
+ */
+/** System-level roles (global permissions) */
+type UserRoleType = 'user' | 'admin' | 'superadmin' | 'finance-admin' | 'finance-manager' | 'store-manager' | 'store-staff' | 'warehouse-admin' | 'warehouse-staff';
+/** Branch-specific roles */
+type BranchRoleType = 'branch_manager' | 'inventory_staff' | 'cashier' | 'stock_receiver' | 'stock_requester' | 'viewer';
+/** User's branch assignment */
+interface UserBranchAssignment {
+    branchId: string;
+    branchCode?: string;
+    branchName?: string;
+    branchRole?: 'head_office' | 'sub_branch';
+    roles: BranchRoleType[];
+    isPrimary: boolean;
+}
+/** User document */
+interface User {
+    _id: string;
+    name: string;
+    email: string;
+    roles: UserRoleType[];
+    branches: UserBranchAssignment[];
+    isActive: boolean;
+    lastLoginAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Create user payload */
+interface CreateUserPayload {
+    name: string;
+    email: string;
+    password: string;
+    roles?: UserRoleType[];
+    branches?: Array<{
+        branchId: string;
+        roles?: BranchRoleType[];
+        isPrimary?: boolean;
+    }>;
+}
+/** Update user payload - just patch what you need */
+interface UpdateUserPayload {
+    name?: string;
+    email?: string;
+    roles?: UserRoleType[];
+    branches?: Array<{
+        branchId: string;
+        roles?: BranchRoleType[];
+        isPrimary?: boolean;
+    }>;
+    isActive?: boolean;
+}
+/** Query params for listing users */
+interface UserListParams {
+    page?: number;
+    limit?: number;
+    sort?: string;
+    name?: string;
+    'name[contains]'?: string;
+    email?: string;
+    roles?: UserRoleType;
+    'roles[in]'?: string;
+    'branches.branchId'?: string;
+    'branches.roles'?: BranchRoleType;
+    isActive?: boolean;
+}
+
+/**
+ * Coupon Types
+ *
+ * Type definitions for discount coupons and promotional codes.
+ */
+
+type DiscountType = 'percentage' | 'fixed';
+/**
+ * Discount coupon/promo code
+ */
+interface Coupon {
+    _id: string;
+    code: string;
+    discountType: DiscountType;
+    discountAmount: number;
+    minOrderAmount: number;
+    maxDiscountAmount?: number;
+    expiresAt: string;
+    usageLimit: number;
+    usedCount: number;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Coupon validation result
+ */
+interface CouponValidationResult {
+    valid: boolean;
+    coupon?: Coupon;
+    discountAmount?: number;
+    error?: string;
+    details?: {
+        codeExists?: boolean;
+        isActive?: boolean;
+        notExpired?: boolean;
+        meetsMinPurchase?: boolean;
+        withinUsageLimit?: boolean;
+    };
+}
+/**
+ * Apply coupon request
+ */
+interface ValidateCouponPayload {
+    orderAmount: number;
+}
+/**
+ * Create coupon request (admin)
+ */
+interface CreateCouponPayload {
+    code: string;
+    discountType: DiscountType;
+    discountAmount: number;
+    minOrderAmount?: number;
+    maxDiscountAmount?: number;
+    expiresAt: string;
+    usageLimit?: number;
+    isActive?: boolean;
+}
+/**
+ * Update coupon request (admin)
+ */
+type UpdateCouponPayload = Partial<CreateCouponPayload>;
+type CouponListResponse = PaginatedResponse<Coupon>;
+type CouponResponse = ApiResponse<Coupon>;
+type CouponValidationResponse = ApiResponse<CouponValidationResult>;
+/**
+ * Coupon usage record
+ */
+interface CouponUsage {
+    /** Usage record ID */
+    _id: string;
+    /** Coupon ID */
+    couponId: string;
+    /** Coupon code */
+    couponCode: string;
+    /** User who used it */
+    userId: string;
+    /** Order ID */
+    orderId: string;
+    /** Discount amount applied */
+    discountAmount: number;
+    /** Used timestamp */
+    usedAt: string;
+}
+
+/**
+ * Platform Configuration API
+ *
+ * Singleton platform configuration - stores all platform-wide settings.
+ *
+ * Endpoints:
+ * - GET  /api/v1/platform/config - Get platform config (supports field selection)
+ * - PATCH /api/v1/platform/config - Update platform config (admin only)
+ *
+ * Field Selection:
+ * - ?select=paymentMethods
+ * - ?select=checkout,vat
+ * - ?select=policies
+ */
+
+declare class PlatformConfigApi {
+    readonly baseUrl = "/api/v1/platform";
+    /**
+     * Get platform configuration
+     *
+     * @param options.token - Optional access token (public without, authenticated with)
+     * @param options.select - Optional field selection (e.g., "paymentMethods", "checkout,vat")
+     * @returns Platform configuration (full or selected fields)
+     *
+     * @example
+     * // Full config (public)
+     * const config = await platformConfigApi.getConfig({});
+     *
+     * // Selected fields (public)
+     * const config = await platformConfigApi.getConfig({ select: "paymentMethods" });
+     *
+     * // Authenticated (admin sees more fields)
+     * const config = await platformConfigApi.getConfig({ token, select: "checkout,vat" });
+     */
+    getConfig({ token, select, }?: {
+        token?: string | null;
+        select?: string | null;
+    }): Promise<ApiResponse<PlatformConfig>>;
+    /**
+     * Update platform configuration
+     *
+     * @param options.token - Admin access token (required)
+     * @param options.data - Configuration data to update (partial update)
+     * @returns Updated platform configuration
+     *
+     * @example
+     * // Update payment methods
+     * await platformConfigApi.updateConfig({
+     *   token,
+     *   data: {
+     *     paymentMethods: [
+     *       { type: 'cash', name: 'Cash on Delivery', isActive: true },
+     *       { type: 'mfs', provider: 'bkash', name: 'bKash', walletNumber: '01712345678' },
+     *     ]
+     *   }
+     * });
+     *
+     * // Update checkout settings
+     * await platformConfigApi.updateConfig({
+     *   token,
+     *   data: {
+     *     checkout: {
+     *       freeDeliveryThreshold: 2000,
+     *       deliveryZones: [
+     *         { name: 'Dhaka', region: 'dhaka', price: 60, estimatedDays: 2, isActive: true }
+     *       ]
+     *     }
+     *   }
+     * });
+     */
+    updateConfig({ token, data, }: {
+        token: string;
+        data: UpdatePlatformConfigPayload;
+    }): Promise<ApiResponse<PlatformConfig>>;
+    /**
+     * Get payment methods only
+     * Convenience method for checkout/POS
+     *
+     * @param options.token - Optional access token
+     * @returns Platform config with only paymentMethods field
+     */
+    getPaymentMethods({ token, }?: {
+        token?: string | null;
+    }): Promise<ApiResponse<Pick<PlatformConfig, "paymentMethods">>>;
+    /**
+     * Get checkout settings only
+     * Convenience method for checkout flow
+     *
+     * @param options.token - Optional access token
+     * @returns Platform config with only checkout field
+     */
+    getCheckoutSettings({ token, }?: {
+        token?: string | null;
+    }): Promise<ApiResponse<Pick<PlatformConfig, "checkout">>>;
+    /**
+     * Get delivery zones
+     * Convenience method for delivery selection
+     *
+     * @param options.token - Optional access token
+     * @returns Platform config with checkout.deliveryZones
+     */
+    getDeliveryZones({ token, }?: {
+        token?: string | null;
+    }): Promise<ApiResponse<Pick<PlatformConfig, "checkout">>>;
+    /**
+     * Get VAT configuration
+     * Convenience method for invoice/tax calculations
+     *
+     * @param options.token - Optional access token
+     * @returns Platform config with only vat field
+     */
+    getVatConfig({ token, }?: {
+        token?: string | null;
+    }): Promise<ApiResponse<Pick<PlatformConfig, "vat">>>;
+    /**
+     * Get membership configuration
+     * Convenience method for loyalty programs
+     *
+     * @param options.token - Optional access token
+     * @returns Platform config with only membership field
+     */
+    getMembershipConfig({ token, }?: {
+        token?: string | null;
+    }): Promise<ApiResponse<Pick<PlatformConfig, "membership">>>;
+}
+declare const platformConfigApi: PlatformConfigApi;
+
+declare const platformApi: PlatformConfigApi;
+declare const businessApi: PlatformConfigApi;
+
+/**
+ * Branch API - CRUD + Custom Endpoints
+ *
+ * Standard CRUD (inherited from BaseApi):
+ * - getAll({ token, params }) - list with filtering/pagination
+ * - getById({ token, id }) - get by ID
+ * - create({ token, data }) - create (admin only)
+ * - update({ token, id, data }) - update (admin only)
+ * - delete({ token, id }) - delete (admin only)
+ *
+ * Custom endpoints:
+ * - getByCode({ token, code }) - GET /branches/code/:code
+ * - getDefault({ token }) - GET /branches/default (auto-creates if none)
+ * - setDefault({ token, id }) - POST /branches/:id/set-default
+ *
+ * For active branches: getAll({ token, params: { isActive: true } })
+ */
+
+type FetchOptions$1 = Omit<RequestOptions, 'token' | 'organizationId'>;
+declare class BranchApi extends BaseApi<Branch, CreateBranchPayload, UpdateBranchPayload> {
+    constructor(config?: {});
+    /**
+     * Get branch by code
+     * GET /branches/code/:code
+     *
+     * @example
+     * branchApi.getByCode({ token, code: 'DHK-1' })
+     */
+    getByCode({ token, code, options, }: {
+        token: string;
+        code: string;
+        options?: FetchOptions$1;
+    }): Promise<ApiResponse<Branch>>;
+    /**
+     * Get default branch (auto-creates if none exists)
+     * GET /branches/default
+     *
+     * @example
+     * branchApi.getDefault({ token })
+     */
+    getDefault({ token, options, }: {
+        token: string;
+        options?: FetchOptions$1;
+    }): Promise<ApiResponse<Branch>>;
+    /**
+     * Set a branch as the default
+     * POST /branches/:id/set-default
+     *
+     * @example
+     * branchApi.setDefault({ token, id: '507f1f77bcf86cd799439011' })
+     */
+    setDefault({ token, id, options, }: {
+        token: string;
+        id: string;
+        options?: FetchOptions$1;
+    }): Promise<ApiResponse<Branch>>;
+}
+declare const branchApi: BranchApi;
+
+/**
+ * User API - Admin User Management (CRUD)
+ *
+ * Standard CRUD (inherited from BaseApi):
+ * - getAll({ token, params }) - list users with filtering/pagination
+ * - getById({ token, id }) - get user by ID
+ * - create({ token, data }) - create user (admin only)
+ * - update({ token, id, data }) - update user (admin only)
+ * - delete({ token, id }) - delete user (admin only)
+ *
+ * Query examples:
+ * - List all users: getAll({ token, params: { page: 1, limit: 10 } })
+ * - Filter by role: getAll({ token, params: { roles: 'admin' } })
+ * - Search by name: getAll({ token, params: { 'name[contains]': 'john' } })
+ * - Filter by branch: getAll({ token, params: { 'branches.branchId': 'branch_123' } })
+ * - Active users only: getAll({ token, params: { isActive: true } })
+ */
+
+declare class UserApi extends BaseApi<User, CreateUserPayload, UpdateUserPayload> {
+    constructor(config?: {});
+}
+declare const userApi: UserApi;
+
+/**
+ * Coupon API - CRUD + validate
+ *
+ * Standard CRUD (inherited from BaseApi):
+ * - getAll({ token, params }) - list coupons with filtering/pagination
+ * - getById({ token, id }) - get coupon by ID
+ * - create({ token, data }) - create coupon (admin only)
+ * - update({ token, id, data }) - update coupon (admin only)
+ * - delete({ token, id }) - delete coupon (admin only)
+ *
+ * Custom endpoints:
+ * - validateCoupon({ code, data }) - POST /coupons/validate/:code
+ */
+
+type FetchOptions = Omit<RequestOptions, "token" | "organizationId">;
+declare class CouponApi extends BaseApi<Coupon, CreateCouponPayload, UpdateCouponPayload> {
+    constructor(config?: {});
+    /**
+     * Validate coupon by code with order amount
+     * POST /coupons/validate/:code
+     *
+     * @example
+     * const result = await couponApi.validateCoupon({
+     *   code: 'SUMMER20',
+     *   data: { orderAmount: 1500 }
+     * });
+     *
+     * if (result.data?.valid) {
+     *   console.log('Discount:', result.data.discountAmount);
+     * }
+     */
+    validateCoupon({ code, data, options, }: {
+        code: string;
+        data: ValidateCouponPayload;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<CouponValidationResult>>;
+}
+declare const couponApi: CouponApi;
+
+export { type CheckoutPickupBranch as A, BranchApi as B, CouponApi as C, type DeliveryZone as D, type PlatformPolicies as E, type MembershipTierConfig as F, type MembershipRedemptionConfig as G, type MembershipConfig as H, type PlatformConfig as I, type UpdatePlatformConfigPayload as J, platformApi as K, type LogisticsSettings as L, type MembershipRoundingMode as M, businessApi as N, type DeliveryFeeSource as O, PlatformConfigApi as P, type CheckoutSettings as Q, type PlatformVatCategoryRate as R, type PlatformVatInvoiceConfig as S, type PlatformSupplementaryDutyConfig as T, UserApi as U, type ValidateCouponPayload as V, type PlatformVatConfig as W, type PaymentMethodConfig as X, type UserRoleType as Y, type User as Z, isSubBranch as a, branchApi as b, couponApi as c, type BranchType as d, type BranchRole as e, type BranchAddress as f, type Branch as g, type CreateBranchPayload as h, isHeadOffice as i, type UpdateBranchPayload as j, type BranchSummary as k, type BranchRoleType as l, type UserBranchAssignment as m, type CreateUserPayload as n, type UpdateUserPayload as o, platformConfigApi as p, type UserListParams as q, type Coupon as r, type CouponValidationResult as s, type CreateCouponPayload as t, userApi as u, type UpdateCouponPayload as v, type CouponListResponse as w, type CouponResponse as x, type CouponValidationResponse as y, type CouponUsage as z };