@basedone/core 0.2.7 → 0.3.0

package/lib/ecommerce/utils/orderStateMachine.ts

@@ -0,0 +1,197 @@
+import { OrderStatus } from "../types/enums";
+
+/** Detect pickup / on-site-collection shipping methods (normalised matching) */
+export function isPickupOrder(
+  shippingMethod?: string | null,
+  shippingRateId?: string | null
+): boolean {
+  // Primary check: shippingRateId === "PICKUP" (from mobile app)
+  if (shippingRateId && shippingRateId.trim().toUpperCase() === "PICKUP") {
+    return true;
+  }
+
+  if (!shippingMethod) return false;
+  const normalized = shippingMethod
+    .trim()
+    .toLowerCase()
+    .replace(/[\s-]+/g, " ");
+  return (
+    normalized === "pickup" ||
+    normalized === "on site collection" ||
+    normalized === "onsite collection"
+  );
+}
+
+/**
+ * Canonical order status transitions.
+ *
+ * Buyer-protected escrow flow:
+ *   CREATED → PAYMENT_RESERVED → MERCHANT_ACCEPTED → SHIPPED → DELIVERED → SETTLED
+ *
+ * Cancellation is allowed from any non-terminal state except DELIVERED (already in settlement).
+ */
+export const ORDER_STATUS_TRANSITIONS: Partial<Record<OrderStatus, OrderStatus[]>> = {
+  [OrderStatus.CREATED]: [
+    OrderStatus.PAYMENT_RESERVED,
+    OrderStatus.MERCHANT_ACCEPTED,
+    OrderStatus.CANCELLED,
+  ],
+  [OrderStatus.PAYMENT_RESERVED]: [
+    OrderStatus.MERCHANT_ACCEPTED,
+    OrderStatus.CANCELLED,
+  ],
+  [OrderStatus.MERCHANT_ACCEPTED]: [
+    OrderStatus.SHIPPED,
+    OrderStatus.CANCELLED,
+  ],
+  // Backward compat for existing SETTLED orders created before escrow change
+  // Note: CANCELLED removed — settled orders have funds paid out, no clawback mechanism
+  [OrderStatus.SETTLED]: [OrderStatus.SHIPPED],
+  [OrderStatus.SHIPPED]: [OrderStatus.DELIVERED, OrderStatus.CANCELLED],
+  // Settlement triggered on delivery (buyer-protected escrow)
+  [OrderStatus.DELIVERED]: [OrderStatus.SETTLED],
+  // Terminal states
+  [OrderStatus.CANCELLED]: [],
+};
+
+/**
+ * Validate whether transitioning from `currentStatus` to `newStatus` is allowed.
+ *
+ * For pickup / on-site-collection orders, MERCHANT_ACCEPTED → DELIVERED and
+ * SETTLED → DELIVERED are permitted (skipping SHIPPED).
+ */
+export function validateStatusTransition(
+  currentStatus: string,
+  newStatus: string,
+  options?: {
+    shippingMethod?: string | null;
+    shippingRateId?: string | null;
+  }
+): { valid: boolean; error?: string } {
+  // Pickup orders can skip SHIPPED and go directly to DELIVERED
+  if (
+    isPickupOrder(options?.shippingMethod, options?.shippingRateId) &&
+    (currentStatus === OrderStatus.MERCHANT_ACCEPTED ||
+      currentStatus === OrderStatus.SETTLED) &&
+    newStatus === OrderStatus.DELIVERED
+  ) {
+    return { valid: true };
+  }
+
+  const allowed =
+    ORDER_STATUS_TRANSITIONS[currentStatus as OrderStatus] ?? [];
+  if (!allowed.includes(newStatus as OrderStatus)) {
+    if (allowed.length === 0) {
+      return {
+        valid: false,
+        error: `Cannot change status from ${currentStatus} — this is a final state`,
+      };
+    }
+    return {
+      valid: false,
+      error: `Cannot transition from ${currentStatus} to ${newStatus}. Allowed: ${allowed.join(", ")}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Return the list of statuses reachable from `currentStatus`.
+ * For pickup orders, DELIVERED is added when on MERCHANT_ACCEPTED or SETTLED.
+ */
+export function getNextStatuses(
+  currentStatus: string,
+  options?: {
+    shippingMethod?: string | null;
+    shippingRateId?: string | null;
+  }
+): string[] {
+  const base = [
+    ...(ORDER_STATUS_TRANSITIONS[currentStatus as OrderStatus] ?? []),
+  ];
+
+  if (
+    isPickupOrder(options?.shippingMethod, options?.shippingRateId) &&
+    (currentStatus === OrderStatus.MERCHANT_ACCEPTED ||
+      currentStatus === OrderStatus.SETTLED) &&
+    !base.includes(OrderStatus.DELIVERED)
+  ) {
+    base.push(OrderStatus.DELIVERED);
+  }
+
+  return base;
+}
+
+/** Human-readable label for a status. */
+export function getStatusLabel(status: string): string {
+  const labels: Record<string, string> = {
+    CREATED: "Created",
+    PAYMENT_RESERVED: "Payment Reserved",
+    MERCHANT_ACCEPTED: "Accepted",
+    SETTLED: "Completed (Paid)",
+    SHIPPED: "Shipped",
+    DELIVERED: "Delivered",
+    CANCELLED: "Cancelled",
+  };
+  return labels[status] || status;
+}
+
+/** UI colour key for a status. */
+export function getStatusColor(status: string): string {
+  const colors: Record<string, string> = {
+    CREATED: "gray",
+    PAYMENT_RESERVED: "blue",
+    MERCHANT_ACCEPTED: "purple",
+    SETTLED: "indigo",
+    SHIPPED: "yellow",
+    DELIVERED: "green",
+    CANCELLED: "red",
+  };
+  return colors[status] || "gray";
+}
+
+/** Whether the order can be cancelled from its current status. */
+export function canCancelOrder(currentStatus: string): boolean {
+  return (
+    ORDER_STATUS_TRANSITIONS[currentStatus as OrderStatus]?.includes(
+      OrderStatus.CANCELLED
+    ) ?? false
+  );
+}
+
+/** Whether tracking info is required for a status change. */
+export function requiresTrackingInfo(
+  newStatus: string,
+  options?: {
+    shippingMethod?: string | null;
+    shippingRateId?: string | null;
+  }
+): boolean {
+  if (newStatus !== OrderStatus.SHIPPED) return false;
+  return !isPickupOrder(options?.shippingMethod, options?.shippingRateId);
+}
+
+/** Whether a status change should trigger customer notification. */
+export function shouldNotifyCustomer(newStatus: string): boolean {
+  return [
+    OrderStatus.MERCHANT_ACCEPTED,
+    OrderStatus.SHIPPED,
+    OrderStatus.DELIVERED,
+    OrderStatus.CANCELLED,
+  ].includes(newStatus as OrderStatus);
+}
+
+/** Status progression percentage (for progress bars). */
+export function getStatusProgress(status: string): number {
+  const progressMap: Record<string, number> = {
+    CREATED: 10,
+    PAYMENT_RESERVED: 25,
+    MERCHANT_ACCEPTED: 40,
+    SETTLED: 50,
+    SHIPPED: 75,
+    DELIVERED: 100,
+    CANCELLED: 0,
+  };
+  return progressMap[status] || 0;
+}

package/lib/hip3/market-info.ts

@@ -1,4 +1,4 @@
-import { InfoClient, PerpsAssetCtx, MarginTables } from "@nktkas/hyperliquid";
+import { InfoClient, PerpsAssetCtx, MarginTables, PerpDex as LegacyPerpDex } from "@nktkas/hyperliquid";
 
 export interface PerpsMeta {
   collateralToken: number;
@@ -34,6 +34,10 @@ export interface PerpsUniverse {
   marginMode?: "strictIsolated" | "noCross";
 }
 
+export interface PerpDex extends LegacyPerpDex {
+  deployerFeeScale: string;
+}
+
 export type AllPerpsMeta = PerpsMeta[];
 
 export async function getAllPerpsMeta(

package/lib/hip3/utils.ts

@@ -102,6 +102,8 @@ const dexToCollateralTokenSymbol = {
   hyna: "USDE",
   flx: "USDH",
   vntl: "USDH",
+  km: "USDH",
+  cash: "USDT0",
 };
 
 export const isSpotSymbol = (coin: string | undefined) => {