@classytic/commerce-sdk 0.1.0

package/dist/logistics/index.d.ts

@@ -0,0 +1,226 @@
+import { m as PickupStore, P as ProviderName, d as ProviderCharges, j as Shipment, k as TrackingResult, C as CreateShipmentPayload } from '../logistics-V8a9lUN3.js';
+export { A as Area, q as CalculateChargeParams, p as CancelShipmentPayload, t as CheckoutSettings, r as DeliveryFeeSource, u as DeliveryMethod, v as DeliveryOption, b as District, D as Division, L as LogisticsApi, o as LogisticsConfig, c as LogisticsProvider, s as PickupBranchInfo, a as ProviderAreaIds, n as ProviderConfig, h as ShipmentCashCollection, g as ShipmentDelivery, e as ShipmentParcel, f as ShipmentPickup, S as ShipmentStatus, i as ShipmentTimelineEvent, T as TrackingData, U as UpdateShipmentStatusPayload, l as logisticsApi } from '../logistics-V8a9lUN3.js';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import '../api-factory-B_h4RKBm.js';
+
+declare const LOGISTICS_KEYS: {
+    all: readonly ["logistics"];
+    pickupStores: (provider?: string) => readonly ["logistics", "pickup-stores", string | undefined];
+    shipment: (id: string) => readonly ["logistics", "shipment", string];
+    tracking: (id: string) => readonly ["logistics", "tracking", string];
+    charge: (params: {
+        deliveryAreaId: number;
+        amount: number;
+        weight?: number;
+    }) => readonly ["logistics", "charge", {
+        deliveryAreaId: number;
+        amount: number;
+        weight?: number;
+    }];
+    config: () => readonly ["logistics", "config"];
+};
+interface QueryOptions {
+    enabled?: boolean;
+    staleTime?: number;
+    refetchInterval?: number | false;
+}
+interface ChargeParams {
+    deliveryAreaId: number;
+    pickupAreaId?: number;
+    amount: number;
+    weight?: number;
+    provider?: ProviderName;
+}
+interface UseDeliveryChargeParams {
+    deliveryAreaId: number | null | undefined;
+    amount: number;
+    weight?: number;
+    enabled?: boolean;
+}
+interface UseDeliveryChargeReturn {
+    charges: ProviderCharges | null;
+    deliveryCharge: number;
+    codCharge: number;
+    totalCharge: number;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+interface UseLogisticsActionsReturn {
+    createShipment: (data: CreateShipmentPayload) => Promise<Shipment | undefined>;
+    isCreatingShipment: boolean;
+    cancelShipment: (params: {
+        shipmentId: string;
+        reason?: string;
+    }) => Promise<Shipment | undefined>;
+    isCancellingShipment: boolean;
+    updateShipmentStatus: (params: {
+        shipmentId: string;
+        status: string;
+        message?: string;
+    }) => Promise<Shipment | undefined>;
+    isUpdatingStatus: boolean;
+    isLoading: boolean;
+}
+/**
+ * Fetch pickup stores from logistics provider
+ *
+ * @param token - Auth token (admin required)
+ * @param provider - Optional provider filter
+ * @param options - Query options
+ *
+ * @example
+ * ```tsx
+ * function PickupStoreSelect() {
+ *   const { data: stores, isLoading } = usePickupStores(token);
+ *
+ *   return (
+ *     <Select>
+ *       {stores?.map(store => (
+ *         <SelectItem key={store.id} value={store.id.toString()}>
+ *           {store.name} - {store.areaName}
+ *         </SelectItem>
+ *       ))}
+ *     </Select>
+ *   );
+ * }
+ * ```
+ */
+declare function usePickupStores(token: string, provider?: string, options?: QueryOptions): _tanstack_react_query.UseQueryResult<PickupStore[], Error>;
+/**
+ * Calculate delivery charge via provider API
+ *
+ * @param token - Auth token (optional for public)
+ * @param params - Charge calculation parameters
+ * @param options - Query options
+ *
+ * @example
+ * ```tsx
+ * const { data: charges } = useDeliveryChargeCalculation(token, {
+ *   deliveryAreaId: 1206,
+ *   amount: isCOD ? cartTotal : 0,
+ * });
+ * ```
+ */
+declare function useDeliveryChargeCalculation(token: string | null, params: ChargeParams | null, options?: QueryOptions): _tanstack_react_query.UseQueryResult<ProviderCharges, Error>;
+/**
+ * Convenience hook for delivery charge with extracted values
+ *
+ * @param params - Delivery charge parameters
+ *
+ * @example
+ * ```tsx
+ * function CheckoutDelivery({ areaId, subtotal, isCOD }) {
+ *   const { deliveryCharge, isLoading } = useDeliveryCharge({
+ *     deliveryAreaId: areaId,
+ *     amount: isCOD ? subtotal : 0,
+ *   });
+ *
+ *   return (
+ *     <p>Delivery: {isLoading ? "..." : `৳${deliveryCharge}`}</p>
+ *   );
+ * }
+ * ```
+ */
+declare function useDeliveryCharge({ deliveryAreaId, amount, weight, enabled, }: UseDeliveryChargeParams): UseDeliveryChargeReturn;
+/**
+ * Get shipment by ID
+ *
+ * @param token - Auth token
+ * @param shipmentId - Shipment ID
+ * @param options - Query options
+ */
+declare function useShipment(token: string, shipmentId: string | null, options?: QueryOptions): _tanstack_react_query.UseQueryResult<Shipment, Error>;
+/**
+ * Track shipment - fetches latest status from provider
+ *
+ * @param token - Auth token
+ * @param shipmentId - Shipment ID
+ * @param options - Query options (supports refetchInterval for auto-refresh)
+ *
+ * @example
+ * ```tsx
+ * function ShipmentTracker({ shipmentId }) {
+ *   const { data, isLoading } = useTrackShipment(token, shipmentId, {
+ *     refetchInterval: 5 * 60 * 1000, // Auto-refresh every 5 minutes
+ *   });
+ *
+ *   return (
+ *     <Timeline events={data?.tracking?.timeline || []} />
+ *   );
+ * }
+ * ```
+ */
+declare function useTrackShipment(token: string, shipmentId: string | null, options?: QueryOptions): _tanstack_react_query.UseQueryResult<TrackingResult, Error>;
+/**
+ * Create shipment mutation
+ *
+ * @param token - Auth token
+ *
+ * @example
+ * ```tsx
+ * function CreateShipmentButton({ order }) {
+ *   const { mutate, isPending } = useCreateShipment(token);
+ *
+ *   return (
+ *     <Button
+ *       onClick={() => mutate({ orderId: order._id })}
+ *       disabled={isPending}
+ *     >
+ *       Create Shipment
+ *     </Button>
+ *   );
+ * }
+ * ```
+ */
+declare function useCreateShipment(token: string): _tanstack_react_query.UseMutationResult<Shipment | undefined, Error, CreateShipmentPayload, unknown>;
+/**
+ * Cancel shipment mutation
+ *
+ * @param token - Auth token
+ */
+declare function useCancelShipment(token: string): _tanstack_react_query.UseMutationResult<Shipment | undefined, Error, {
+    shipmentId: string;
+    reason?: string;
+}, unknown>;
+/**
+ * Update shipment status mutation
+ *
+ * @param token - Auth token
+ */
+declare function useUpdateShipmentStatus(token: string): _tanstack_react_query.UseMutationResult<Shipment | undefined, Error, {
+    shipmentId: string;
+    status: string;
+    message?: string;
+}, unknown>;
+/**
+ * Combined hook for all logistics mutations
+ *
+ * @param token - Auth token
+ *
+ * @example
+ * ```tsx
+ * function ShipmentActions({ order }) {
+ *   const {
+ *     createShipment,
+ *     cancelShipment,
+ *     isLoading,
+ *   } = useLogisticsActions(token);
+ *
+ *   return (
+ *     <>
+ *       <Button onClick={() => createShipment({ orderId: order._id })}>
+ *         Create Shipment
+ *       </Button>
+ *       <Button onClick={() => cancelShipment({ shipmentId: order.shipment._id })}>
+ *         Cancel
+ *       </Button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useLogisticsActions(token: string): UseLogisticsActionsReturn;
+
+export { CreateShipmentPayload, LOGISTICS_KEYS, PickupStore, ProviderCharges, ProviderName, Shipment, TrackingResult, type UseDeliveryChargeReturn, type UseLogisticsActionsReturn, useCancelShipment, useCreateShipment, useDeliveryCharge, useDeliveryChargeCalculation, useLogisticsActions, usePickupStores, useShipment, useTrackShipment, useUpdateShipmentStatus };

package/dist/logistics/index.js

@@ -0,0 +1,7 @@
+"use client";
+export { LOGISTICS_KEYS, LogisticsApi, logisticsApi, useCancelShipment, useCreateShipment, useDeliveryCharge, useDeliveryChargeCalculation, useLogisticsActions, usePickupStores, useShipment, useTrackShipment, useUpdateShipmentStatus } from '../chunk-5L6EXDGH.js';
+import '../chunk-I5TIKUIQ.js';
+import '../chunk-U3XT35GZ.js';
+import '../chunk-VR36QVX2.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/logistics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/logistics-V8a9lUN3.d.ts

@@ -0,0 +1,428 @@
+import { B as BaseApi, R as RequestOptions, A as ApiResponse } from './api-factory-B_h4RKBm.js';
+
+/**
+ * Logistics Types
+ *
+ * Types for logistics API responses (shipments, tracking, charges).
+ * For area data types, install @classytic/bd-areas:
+ *
+ * ```typescript
+ * import type { Area, Division, District, ProviderAreaIds } from '@classytic/bd-areas';
+ * import { searchAreas, getAreasByDistrict } from '@classytic/bd-areas';
+ * ```
+ */
+type ProviderName = 'redx' | 'pathao' | 'steadfast' | 'paperfly';
+interface ProviderAreaIds {
+    redx?: number;
+    pathao?: number;
+    steadfast?: number;
+    paperfly?: number;
+}
+interface Area {
+    internalId: number;
+    name: string;
+    districtId: number;
+    districtName: string;
+    divisionId: number;
+    divisionName: string;
+    postCode?: string;
+    providerAreaIds?: ProviderAreaIds;
+}
+interface Division {
+    id: number;
+    name: string;
+    nameBn?: string;
+}
+interface District {
+    id: number;
+    divisionId: number;
+    name: string;
+    nameBn?: string;
+}
+type ShipmentStatus = 'pending' | 'pickup-requested' | 'picked-up' | 'in-transit' | 'out-for-delivery' | 'delivered' | 'failed-attempt' | 'returning' | 'returned' | 'cancelled';
+type LogisticsProvider = 'redx' | 'pathao' | 'steadfast' | 'paperfly' | 'sundarban' | 'manual';
+/**
+ * Response from GET /logistics/charge
+ *
+ * Use deliveryCharge for customer-facing price.
+ * codCharge is the provider's fee for cash collection (not charged to customer).
+ */
+interface ProviderCharges {
+    /** Base delivery charge from provider */
+    deliveryCharge: number;
+    /** COD charge (provider's fee, not customer-facing) */
+    codCharge: number;
+    /** Total charge (deliveryCharge + codCharge) */
+    totalCharge: number;
+    /** Currency code (default: BDT) */
+    currency?: string;
+}
+interface ShipmentParcel {
+    weight?: number;
+    value?: number;
+    itemCount?: number;
+}
+interface ShipmentPickup {
+    storeId?: number;
+    storeName?: string;
+    scheduledAt?: string;
+    pickedUpAt?: string;
+}
+interface ShipmentDelivery {
+    customerName: string;
+    customerPhone: string;
+    address: string;
+    areaId?: number;
+    areaName?: string;
+}
+interface ShipmentCashCollection {
+    amount: number;
+    collected?: boolean;
+    collectedAt?: string;
+}
+interface ShipmentTimelineEvent {
+    status: ShipmentStatus;
+    message?: string;
+    messageLocal?: string;
+    timestamp: string;
+    raw?: Record<string, unknown>;
+}
+interface Shipment {
+    _id: string;
+    order: string;
+    provider: LogisticsProvider;
+    trackingId: string;
+    providerOrderId?: string;
+    status: ShipmentStatus;
+    providerStatus?: string;
+    parcel: ShipmentParcel;
+    pickup: ShipmentPickup;
+    delivery: ShipmentDelivery;
+    cashCollection: ShipmentCashCollection;
+    charges: ProviderCharges;
+    merchantInvoiceId?: string;
+    timeline: ShipmentTimelineEvent[];
+    lastWebhookAt?: string;
+    webhookCount: number;
+    cancelledBy?: string;
+    cancelReason?: string;
+    createdBy?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TrackingData {
+    trackingId: string;
+    status: ShipmentStatus;
+    providerStatus?: string;
+    currentLocation?: string;
+    estimatedDelivery?: string;
+    timeline: ShipmentTimelineEvent[];
+}
+interface TrackingResult {
+    shipment: Shipment;
+    tracking: TrackingData;
+}
+/**
+ * Pickup store from RedX API
+ * Admin creates these via RedX dashboard
+ * Used for: selecting pickup location when creating shipments
+ */
+interface PickupStore {
+    /** RedX store ID */
+    id: number;
+    /** Store name */
+    name: string;
+    /** Store address */
+    address?: string;
+    /** Contact phone */
+    phone?: string;
+    /** Area ID (RedX area) - used for charge calculation */
+    areaId?: number;
+    /** Area name */
+    areaName?: string;
+    /** Creation date */
+    createdAt?: string;
+}
+interface ProviderConfig {
+    provider: LogisticsProvider;
+    apiUrl?: string;
+    apiKey?: string;
+    isActive: boolean;
+    isDefault?: boolean;
+    settings?: Record<string, unknown>;
+}
+interface LogisticsConfig {
+    _id: string;
+    defaultProvider: LogisticsProvider;
+    providers: ProviderConfig[];
+    supportedProviders: LogisticsProvider[];
+}
+interface CreateShipmentPayload {
+    orderId: string;
+    provider?: LogisticsProvider;
+    deliveryAreaId?: number;
+    deliveryAreaName?: string;
+    providerAreaId?: number;
+    pickupStoreId?: number;
+    pickupAreaId?: number;
+    weight?: number;
+    /** COD amount to collect on delivery (0 for prepaid orders) */
+    codAmount?: number;
+    instructions?: string;
+}
+interface UpdateShipmentStatusPayload {
+    status: ShipmentStatus;
+    message?: string;
+    messageLocal?: string;
+}
+interface CancelShipmentPayload {
+    reason?: string;
+}
+interface CalculateChargeParams {
+    /** Delivery area internalId from bd-areas */
+    deliveryAreaId: number;
+    /** COD amount in BDT (use 0 for prepaid) */
+    amount: number;
+    /** Parcel weight in grams (default: 500g) */
+    weight?: number;
+    /** Pickup area internalId (optional - auto-fetched from merchant's RedX pickup store) */
+    pickupAreaId?: number;
+    /** Specific provider (optional - uses default provider if not specified) */
+    provider?: ProviderName;
+}
+type DeliveryFeeSource = 'static' | 'provider';
+/**
+ * Branch info for store pickup
+ */
+interface PickupBranchInfo {
+    branchId: string;
+    branchCode: string;
+    branchName: string;
+}
+/**
+ * Checkout settings from platform config
+ */
+interface CheckoutSettings {
+    /** Enable store pickup option */
+    allowStorePickup: boolean;
+    /** Branches available for pickup (empty = all active) */
+    pickupBranches: PickupBranchInfo[];
+    /** Fee source: 'static' (from zones) or 'provider' (from RedX API) */
+    deliveryFeeSource: DeliveryFeeSource;
+    /** Minimum order for free delivery (0 = disabled) */
+    freeDeliveryThreshold: number;
+}
+type DeliveryMethod = 'standard' | 'express' | 'pickup';
+/**
+ * Delivery option for checkout UI
+ */
+interface DeliveryOption {
+    method: DeliveryMethod;
+    label: string;
+    price: number;
+    estimatedDays?: string;
+    /** For pickup: branch info */
+    pickupBranch?: PickupBranchInfo;
+}
+
+type FetchOptions = Omit<RequestOptions, 'token' | 'organizationId'>;
+/**
+ * Logistics API
+ *
+ * Manages shipments and delivery charge calculation.
+ *
+ * NOTE: For area data (divisions, districts, areas), use @classytic/bd-areas directly:
+ * ```typescript
+ * import { searchAreas, getAreasByDistrict, getArea } from '@classytic/bd-areas';
+ * ```
+ *
+ * Public Endpoints:
+ * - GET /logistics/charge - Calculate delivery charge via provider (RedX)
+ *
+ * Shipment Endpoints (Admin/Store Manager):
+ * - POST /logistics/shipments - Create shipment
+ * - GET /logistics/shipments/:id - Get shipment
+ * - GET /logistics/shipments/:id/track - Track shipment
+ * - PATCH /logistics/shipments/:id/status - Update status manually
+ * - POST /logistics/shipments/:id/cancel - Cancel shipment
+ *
+ * Admin Endpoints:
+ * - GET /logistics/config - Get config (read-only)
+ * - GET /logistics/pickup-stores - List pickup stores
+ * - GET /logistics/health/circuit-status - Get circuit breaker status
+ * - POST /logistics/health/circuit-reset/:provider - Reset circuit breaker
+ */
+declare class LogisticsApi extends BaseApi<Shipment, CreateShipmentPayload> {
+    constructor(config?: {});
+    /**
+     * Calculate delivery charge via provider API (e.g., RedX)
+     * GET /logistics/charge
+     *
+     * Use this to get real-time delivery charges from the logistics provider
+     * before creating an order.
+     *
+     * @param deliveryAreaId - Area internalId from @classytic/bd-areas
+     * @param amount - COD amount in BDT (use 0 for prepaid orders)
+     * @param weight - Parcel weight in grams (default: 500g)
+     *
+     * @example
+     * import { searchAreas } from '@classytic/bd-areas';
+     *
+     * // 1. User selects area
+     * const areas = searchAreas('mohamm');
+     * const selectedArea = areas[0]; // { internalId: 1206, name: 'Mohammadpur', ... }
+     *
+     * // 2. Calculate delivery charge
+     * const { data } = await logisticsApi.calculateCharge({
+     *   deliveryAreaId: selectedArea.internalId,
+     *   amount: isCOD ? cartTotal : 0,
+     * });
+     * // { deliveryCharge: 60, codCharge: 15, totalCharge: 75 }
+     */
+    calculateCharge({ deliveryAreaId, pickupAreaId, amount, weight, provider, options, }: {
+        deliveryAreaId: number;
+        pickupAreaId?: number;
+        amount: number;
+        weight?: number;
+        provider?: ProviderName;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<ProviderCharges>>;
+    /**
+     * Get logistics configuration (read-only from .env)
+     * GET /logistics/config
+     *
+     * NOTE: Configuration is managed via environment variables.
+     * To change settings, update .env file and restart server.
+     */
+    getConfig({ token, options, }: {
+        token: string;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<LogisticsConfig>>;
+    /**
+     * Get pickup stores from RedX API
+     * GET /logistics/pickup-stores
+     *
+     * Pickup stores are created by admin in RedX dashboard.
+     * Use this to list available pickup locations when creating shipments.
+     *
+     * @example
+     * // Admin: List pickup stores for shipment creation
+     * const { data: stores } = await logisticsApi.getPickupStores({ token });
+     *
+     * // Display in dropdown for admin to select
+     * stores.forEach(store => {
+     *   console.log(`${store.name} - ${store.areaName} (ID: ${store.id})`);
+     * });
+     *
+     * // Use selected store when creating shipment
+     * await logisticsApi.createShipment({
+     *   token,
+     *   data: {
+     *     orderId: order._id,
+     *     pickupStoreId: selectedStore.id,  // From dropdown
+     *   },
+     * });
+     */
+    getPickupStores({ token, provider, options, }: {
+        token: string;
+        provider?: string;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<PickupStore[]>>;
+    /**
+     * Create shipment for an order via RedX API
+     * POST /logistics/shipments
+     *
+     * This creates a parcel in RedX and updates the order with tracking info.
+     *
+     * @example
+     * // Basic: Create shipment with default pickup store
+     * const shipment = await logisticsApi.createShipment({
+     *   token,
+     *   data: { orderId: order._id },
+     * });
+     *
+     * @example
+     * // With specific pickup store (from getPickupStores)
+     * const { data: stores } = await logisticsApi.getPickupStores({ token });
+     * const shipment = await logisticsApi.createShipment({
+     *   token,
+     *   data: {
+     *     orderId: order._id,
+     *     pickupStoreId: stores[0].id,  // Select pickup location
+     *     weight: 500,                   // Parcel weight in grams
+     *     instructions: 'Handle with care',
+     *   },
+     * });
+     *
+     * // Response includes tracking ID
+     * console.log(`Tracking: ${shipment.data.trackingId}`);
+     */
+    createShipment({ token, data, options, }: {
+        token: string;
+        data: CreateShipmentPayload;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<Shipment>>;
+    /**
+     * Get shipment by ID
+     * GET /logistics/shipments/:id
+     */
+    getShipment({ token, id, options, }: {
+        token: string;
+        id: string;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<Shipment>>;
+    /**
+     * Track shipment (fetch latest from provider)
+     * GET /logistics/shipments/:id/track
+     */
+    trackShipment({ token, id, options, }: {
+        token: string;
+        id: string;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<TrackingResult>>;
+    /**
+     * Update shipment status manually
+     * PATCH /logistics/shipments/:id/status
+     */
+    updateShipmentStatus({ token, id, data, options, }: {
+        token: string;
+        id: string;
+        data: UpdateShipmentStatusPayload;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<Shipment>>;
+    /**
+     * Cancel shipment
+     * POST /logistics/shipments/:id/cancel
+     */
+    cancelShipment({ token, id, data, options, }: {
+        token: string;
+        id: string;
+        data?: CancelShipmentPayload;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<Shipment>>;
+    /**
+     * Get circuit breaker status for all providers
+     * GET /logistics/health/circuit-status
+     */
+    getCircuitStatus({ token, options, }: {
+        token: string;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<Record<string, {
+        state: string;
+        failureCount: number;
+    }>>>;
+    /**
+     * Reset circuit breaker for a provider
+     * POST /logistics/health/circuit-reset/:provider
+     */
+    resetProviderCircuit({ token, provider, options, }: {
+        token: string;
+        provider: string;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<{
+        message: string;
+    }>>;
+}
+declare const logisticsApi: LogisticsApi;
+
+export { type Area as A, type CreateShipmentPayload as C, type Division as D, LogisticsApi as L, type ProviderName as P, type ShipmentStatus as S, type TrackingData as T, type UpdateShipmentStatusPayload as U, type ProviderAreaIds as a, type District as b, type LogisticsProvider as c, type ProviderCharges as d, type ShipmentParcel as e, type ShipmentPickup as f, type ShipmentDelivery as g, type ShipmentCashCollection as h, type ShipmentTimelineEvent as i, type Shipment as j, type TrackingResult as k, logisticsApi as l, type PickupStore as m, type ProviderConfig as n, type LogisticsConfig as o, type CancelShipmentPayload as p, type CalculateChargeParams as q, type DeliveryFeeSource as r, type PickupBranchInfo as s, type CheckoutSettings as t, type DeliveryMethod as u, type DeliveryOption as v };