@classytic/commerce-sdk 0.1.1 → 0.2.1

package/dist/inventory/types/warehouse.d.ts

@@ -0,0 +1,182 @@
+//#region src/inventory/types/warehouse.d.ts
+/**
+ * Warehouse Types — Node, Location, Audit
+ */
+interface WarehouseNode {
+  _id: string;
+  organizationId: string;
+  code: string;
+  name: string;
+  type: "warehouse" | "store" | "fulfillment_center" | "returns_center";
+  status: "active" | "inactive";
+  timezone?: string;
+  currency?: string;
+  address?: {
+    street?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+    coordinates?: {
+      lat: number;
+      lng: number;
+    };
+  };
+  capabilities?: string[];
+  isDefault?: boolean;
+  metadata?: Record<string, unknown>;
+  createdAt?: string;
+  updatedAt?: string;
+}
+interface CreateNodePayload {
+  code: string;
+  name: string;
+  type?: WarehouseNode["type"];
+  timezone?: string;
+  currency?: string;
+  address?: WarehouseNode["address"];
+  capabilities?: string[];
+  isDefault?: boolean;
+  metadata?: Record<string, unknown>;
+}
+interface UpdateNodePayload {
+  name?: string;
+  type?: WarehouseNode["type"];
+  status?: "active" | "inactive";
+  timezone?: string;
+  address?: WarehouseNode["address"];
+  capabilities?: string[];
+  metadata?: Record<string, unknown>;
+}
+interface LocationCoordinates {
+  zone?: string;
+  aisle?: number;
+  bay?: number;
+  level?: number;
+  bin?: string;
+}
+type LocationType = "storage" | "receiving" | "shipping" | "picking" | "packing" | "transit" | "returns" | "quality_hold" | "damaged" | "internal" | "production" | "view" | "vendor" | "customer" | "scrap" | "inventory_loss";
+interface WarehouseLocation {
+  _id: string;
+  organizationId: string;
+  nodeId: string;
+  parentLocationId?: string;
+  code: string;
+  name: string;
+  type: LocationType;
+  status: "active" | "inactive";
+  barcode?: string;
+  coordinates?: LocationCoordinates;
+  maxWeight?: number;
+  maxVolume?: number;
+  sortOrder?: number;
+  allowReservations?: boolean;
+  allowNegativeStock?: boolean;
+  metadata?: Record<string, unknown>;
+  createdAt?: string;
+  updatedAt?: string;
+}
+interface CreateLocationPayload {
+  nodeId: string;
+  parentLocationId?: string;
+  code: string;
+  name: string;
+  type?: LocationType;
+  barcode?: string;
+  coordinates?: LocationCoordinates;
+  maxWeight?: number;
+  maxVolume?: number;
+  sortOrder?: number;
+  allowReservations?: boolean;
+  allowNegativeStock?: boolean;
+  metadata?: Record<string, unknown>;
+}
+interface BulkCreateLocationPayload {
+  nodeId: string;
+  locations: Array<Omit<CreateLocationPayload, "nodeId"> & {
+    type?: string;
+  }>;
+}
+interface UpdateLocationPayload {
+  name?: string;
+  status?: "active" | "inactive";
+  barcode?: string;
+  coordinates?: LocationCoordinates;
+  maxWeight?: number;
+  maxVolume?: number;
+  sortOrder?: number;
+  parentLocationId?: string | null;
+  allowReservations?: boolean;
+  allowNegativeStock?: boolean;
+  metadata?: Record<string, unknown>;
+}
+interface WarehouseLayout {
+  nodeId: string;
+  totalLocations: number;
+  zones: Array<{
+    zone: string;
+    aisles: Array<{
+      aisle: number;
+      locations: WarehouseLocation[];
+    }>;
+  }>;
+}
+type AuditCountType = "full" | "cycle" | "spot";
+type AuditStatus = "draft" | "in_progress" | "pending_review" | "reconciled" | "done" | "cancelled";
+interface AuditSession {
+  _id: string;
+  organizationId: string;
+  countNumber: string;
+  countType: AuditCountType;
+  status: AuditStatus;
+  scope: {
+    nodeId?: string;
+    locationId?: string;
+    skuRefs?: string[];
+  };
+  freezePolicy?: "hard_freeze" | "soft_freeze" | "none";
+  lineCount?: number;
+  createdAt?: string;
+  updatedAt?: string;
+}
+interface AuditCountLine {
+  skuRef: string;
+  locationId: string;
+  lotId?: string;
+  serialCode?: string;
+  countedQuantity: number;
+  varianceReason?: string;
+}
+interface AuditVarianceLine {
+  skuRef: string;
+  locationId: string;
+  expected: number;
+  counted: number;
+  variance: number;
+  variancePercent: number;
+}
+interface AuditVarianceReport {
+  countId: string;
+  totalLines: number;
+  matchedLines: number;
+  varianceLines: number;
+  lines: AuditVarianceLine[];
+}
+interface AuditReconcileResult {
+  countId: string;
+  totalLines: number;
+  varianceLines: number;
+  autoApproved: number;
+  needsManualReview: number;
+}
+interface CreateAuditPayload {
+  countType: AuditCountType;
+  scope?: {
+    nodeId?: string;
+    locationId?: string;
+    skuRefs?: string[];
+  };
+  freezePolicy?: "hard_freeze" | "soft_freeze" | "none";
+}
+//#endregion
+export { AuditCountLine, AuditCountType, AuditReconcileResult, AuditSession, AuditStatus, AuditVarianceLine, AuditVarianceReport, BulkCreateLocationPayload, CreateAuditPayload, CreateLocationPayload, CreateNodePayload, LocationCoordinates, LocationType, UpdateLocationPayload, UpdateNodePayload, WarehouseLayout, WarehouseLocation, WarehouseNode };

package/dist/logistics/api/index.d.ts

@@ -0,0 +1 @@
+import { LogisticsApi, logisticsApi } from "./logistics.js";

package/dist/logistics/api/logistics.d.ts

@@ -0,0 +1,260 @@
+import { ApiResponse, BaseApi, RequestOptions } from "../../core/api-factory.js";
+import { OrderShipping } from "../../sales/types/order.js";
+import { CancelShipmentPayload, CancelShipmentResult, CreateShipmentPayload, LogisticsConfig, PickupStore, ProviderCharges, ProviderName, TrackingResult, UpdateShipmentStatusPayload } from "../types/logistics.js";
+
+//#region src/logistics/api/logistics.d.ts
+type FetchOptions = Omit<RequestOptions, 'token' | 'organizationId'>;
+/**
+ * Logistics API
+ *
+ * Manages logistics utilities 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)
+ *
+ * Shipping Endpoints (Admin/Store Manager):
+ * - POST /orders/:id/shipping - Request shipping (manual or provider API)
+ * - PATCH /orders/:id/shipping - Update shipping status
+ * - GET /orders/:id/shipping - Get shipping info
+ * - GET /logistics/shipments/:id/track - Track shipment
+ * - 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<OrderShipping, 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[]>>;
+  /**
+   * Request shipping for an order (manual or provider API)
+   * POST /orders/:id/shipping
+   *
+   * This updates the order.shipping object and optionally triggers
+   * provider API shipment creation when useProviderApi=true.
+   *
+   * @example
+   * // Manual: Record tracking details
+   * const shipping = await logisticsApi.createShipment({
+   *   token,
+   *   orderId: order._id,
+   *   data: {
+   *     provider: "other",
+   *     trackingNumber: "COURIER123456",
+   *     trackingUrl: "https://courier-website.com/track/COURIER123456",
+   *   },
+   * });
+   *
+   * @example
+   * // Provider API: Create shipment with pickup store
+   * const { data: stores } = await logisticsApi.getPickupStores({ token });
+   * const shipping = await logisticsApi.createShipment({
+   *   token,
+   *   orderId: order._id,
+   *   data: {
+   *     provider: "redx",
+   *     useProviderApi: true,
+   *     pickupStoreId: stores[0].id,  // Select pickup location
+   *     weight: 500,                  // Parcel weight in grams
+   *     instructions: 'Handle with care',
+   *   },
+   * });
+   */
+  createShipment({
+    token,
+    orderId,
+    data,
+    options
+  }: {
+    token: string;
+    orderId: string;
+    data: CreateShipmentPayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<OrderShipping>>;
+  /**
+   * Get shipping info for an order
+   * GET /orders/:id/shipping
+   */
+  getShipment({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<OrderShipping | null>>;
+  /**
+   * Track shipment (fetch latest from provider)
+   * GET /logistics/shipments/:id/track
+   *
+   * @param id - Order ID or tracking number
+   */
+  trackShipment({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<TrackingResult>>;
+  /**
+   * Update shipping status for an order
+   * PATCH /orders/:id/shipping
+   */
+  updateShipmentStatus({
+    token,
+    id,
+    data,
+    options
+  }: {
+    token: string;
+    id: string;
+    data: UpdateShipmentStatusPayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<OrderShipping>>;
+  /**
+   * Cancel shipment
+   * POST /logistics/shipments/:id/cancel
+   *
+   * @param id - Order ID or tracking number
+   */
+  cancelShipment({
+    token,
+    id,
+    data,
+    options
+  }: {
+    token: string;
+    id: string;
+    data?: CancelShipmentPayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<CancelShipmentResult>>;
+  /**
+   * 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;
+//#endregion
+export { LogisticsApi, logisticsApi };

package/dist/logistics/api/logistics.js

@@ -0,0 +1,249 @@
+import { handleApiRequest } from "../../core/api-handler.js";
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/logistics/api/logistics.ts
+/**
+* Logistics API
+*
+* Manages logistics utilities 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)
+*
+* Shipping Endpoints (Admin/Store Manager):
+* - POST /orders/:id/shipping - Request shipping (manual or provider API)
+* - PATCH /orders/:id/shipping - Update shipping status
+* - GET /orders/:id/shipping - Get shipping info
+* - GET /logistics/shipments/:id/track - Track shipment
+* - 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
+*/
+var LogisticsApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("logistics", 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 }
+	*/
+	async calculateCharge({ deliveryAreaId, pickupAreaId, amount, weight, provider, options = {} }) {
+		if (!deliveryAreaId || amount === void 0) throw new Error("deliveryAreaId and amount are required");
+		const queryString = this.createQueryString({
+			deliveryAreaId,
+			pickupAreaId,
+			amount,
+			weight,
+			provider
+		});
+		return handleApiRequest("GET", `${this.baseUrl}/charge?${queryString}`, {
+			cache: "no-store",
+			...options
+		});
+	}
+	/**
+	* 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.
+	*/
+	async getConfig({ token, options = {} }) {
+		return handleApiRequest("GET", `${this.baseUrl}/config`, {
+			token,
+			cache: "no-store",
+			...options
+		});
+	}
+	/**
+	* 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
+	*   },
+	* });
+	*/
+	async getPickupStores({ token, provider, options = {} }) {
+		const queryString = provider ? `?provider=${provider}` : "";
+		return handleApiRequest("GET", `${this.baseUrl}/pickup-stores${queryString}`, {
+			token,
+			cache: "no-store",
+			...options
+		});
+	}
+	/**
+	* Request shipping for an order (manual or provider API)
+	* POST /orders/:id/shipping
+	*
+	* This updates the order.shipping object and optionally triggers
+	* provider API shipment creation when useProviderApi=true.
+	*
+	* @example
+	* // Manual: Record tracking details
+	* const shipping = await logisticsApi.createShipment({
+	*   token,
+	*   orderId: order._id,
+	*   data: {
+	*     provider: "other",
+	*     trackingNumber: "COURIER123456",
+	*     trackingUrl: "https://courier-website.com/track/COURIER123456",
+	*   },
+	* });
+	*
+	* @example
+	* // Provider API: Create shipment with pickup store
+	* const { data: stores } = await logisticsApi.getPickupStores({ token });
+	* const shipping = await logisticsApi.createShipment({
+	*   token,
+	*   orderId: order._id,
+	*   data: {
+	*     provider: "redx",
+	*     useProviderApi: true,
+	*     pickupStoreId: stores[0].id,  // Select pickup location
+	*     weight: 500,                  // Parcel weight in grams
+	*     instructions: 'Handle with care',
+	*   },
+	* });
+	*/
+	async createShipment({ token, orderId, data, options = {} }) {
+		if (!orderId) throw new Error("Order ID is required");
+		const response = await handleApiRequest("POST", `${this.config.basePath}/orders/${orderId}/shipping`, {
+			token,
+			body: data,
+			...options
+		});
+		const normalizedData = response.data && typeof response.data === "object" && "shipping" in response.data ? response.data.shipping : response.data;
+		return {
+			success: response.success,
+			message: response.message,
+			...normalizedData ? { data: normalizedData } : {}
+		};
+	}
+	/**
+	* Get shipping info for an order
+	* GET /orders/:id/shipping
+	*/
+	async getShipment({ token, id, options = {} }) {
+		if (!id) throw new Error("Order ID is required");
+		return handleApiRequest("GET", `${this.config.basePath}/orders/${id}/shipping`, {
+			token,
+			cache: "no-store",
+			...options
+		});
+	}
+	/**
+	* Track shipment (fetch latest from provider)
+	* GET /logistics/shipments/:id/track
+	*
+	* @param id - Order ID or tracking number
+	*/
+	async trackShipment({ token, id, options = {} }) {
+		if (!id) throw new Error("Shipment ID or tracking number is required");
+		return handleApiRequest("GET", `${this.baseUrl}/shipments/${id}/track`, {
+			token,
+			cache: "no-store",
+			...options
+		});
+	}
+	/**
+	* Update shipping status for an order
+	* PATCH /orders/:id/shipping
+	*/
+	async updateShipmentStatus({ token, id, data, options = {} }) {
+		if (!id) throw new Error("Order ID is required");
+		if (!data?.status) throw new Error("Status is required");
+		return handleApiRequest("PATCH", `${this.config.basePath}/orders/${id}/shipping`, {
+			token,
+			body: data,
+			...options
+		});
+	}
+	/**
+	* Cancel shipment
+	* POST /logistics/shipments/:id/cancel
+	*
+	* @param id - Order ID or tracking number
+	*/
+	async cancelShipment({ token, id, data, options = {} }) {
+		if (!id) throw new Error("Shipment ID or tracking number is required");
+		return handleApiRequest("POST", `${this.baseUrl}/shipments/${id}/cancel`, {
+			token,
+			body: data || {},
+			...options
+		});
+	}
+	/**
+	* Get circuit breaker status for all providers
+	* GET /logistics/health/circuit-status
+	*/
+	async getCircuitStatus({ token, options = {} }) {
+		return handleApiRequest("GET", `${this.baseUrl}/health/circuit-status`, {
+			token,
+			cache: "no-store",
+			...options
+		});
+	}
+	/**
+	* Reset circuit breaker for a provider
+	* POST /logistics/health/circuit-reset/:provider
+	*/
+	async resetProviderCircuit({ token, provider, options = {} }) {
+		if (!provider) throw new Error("Provider name is required");
+		return handleApiRequest("POST", `${this.baseUrl}/health/circuit-reset/${provider}`, {
+			token,
+			body: {},
+			...options
+		});
+	}
+};
+const logisticsApi = new LogisticsApi();
+
+//#endregion
+export { LogisticsApi, logisticsApi };

package/dist/logistics/hooks/index.d.ts

@@ -0,0 +1 @@
+import { LOGISTICS_KEYS, UseDeliveryChargeReturn, UseLogisticsActionsReturn, useCancelShipment, useCreateShipment, useDeliveryCharge, useDeliveryChargeCalculation, useLogisticsActions, usePickupStores, useShipment, useTrackShipment, useUpdateShipmentStatus } from "./logistics.js";