@basedone/core 0.2.8 → 0.3.1

package/lib/ecommerce/types/responses.ts

@@ -286,6 +286,10 @@ export interface ValidateDiscountResponse {
     /** Discount amount */
     discountAmount: number;
   };
+  /** Merchant ID the discount belongs to */
+  merchantId?: string;
+  /** Merchant name the discount belongs to */
+  merchantName?: string | null;
   /** Subtotal */
   subtotal?: number;
   /** Total */
@@ -1325,6 +1329,30 @@ export interface CashAccountBalanceResponse {
   currency: string;
 }
 
+// ============================================================================
+// Customer Notification Responses
+// ============================================================================
+
+export interface CustomerNotification {
+  id: string;
+  type: string;
+  title: string;
+  message: string;
+  metadata: Record<string, any> | null;
+  isRead: boolean;
+  createdAt: string;
+}
+
+export interface CustomerNotificationsResponse {
+  notifications: CustomerNotification[];
+  stats: { unread: number };
+  pagination: { total: number; limit: number; offset: number; hasMore: boolean };
+}
+
+export interface MarkNotificationsReadResponse {
+  updated: number;
+}
+
 export interface DeliveryAddressResponse {
   name: string;
   phoneNumber: string;

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,5 +1,14 @@
 import { InfoClient, PerpsAssetCtx, MarginTables, PerpDex as LegacyPerpDex } from "@nktkas/hyperliquid";
 
+/** Payload entries from Hyperliquid `info` → `{ type: "perpConciseAnnotations" }`. */
+export interface PerpConciseAnnotationMeta {
+  category?: string;
+  displayName?: string;
+  keywords?: string[];
+}
+
+export type PerpConciseAnnotations = [string, PerpConciseAnnotationMeta][];
+
 export interface PerpsMeta {
   collateralToken: number;
   /** Trading universes available for perpetual trading. */
@@ -32,6 +41,10 @@ export interface PerpsUniverse {
   growthMode?: "enabled";
   /** Margin mode for the universe. */
   marginMode?: "strictIsolated" | "noCross";
+  /** From `perpConciseAnnotations` when present (search/display). */
+  category?: string;
+  displayName?: string;
+  keywords?: string[];
 }
 
 export interface PerpDex extends LegacyPerpDex {
@@ -40,10 +53,60 @@ export interface PerpDex extends LegacyPerpDex {
 
 export type AllPerpsMeta = PerpsMeta[];
 
+export async function getPerpConciseAnnotations(
+  infoClient: InfoClient,
+): Promise<PerpConciseAnnotations> {
+  return infoClient.transport.request<PerpConciseAnnotations>("info", {
+    type: "perpConciseAnnotations",
+  });
+}
+
+/**
+ * Merges `perpConciseAnnotations` into each universe row by matching `name`.
+ */
+export function enrichAllPerpsMetaWithAnnotations(
+  metas: AllPerpsMeta,
+  annotations: PerpConciseAnnotations,
+): AllPerpsMeta {
+  const map = new Map<string, PerpConciseAnnotationMeta>(annotations);
+
+  return metas.map((meta) => ({
+    ...meta,
+    universe: meta.universe.map((u) => {
+      const ann = map.get(u.name);
+      if (!ann) return u;
+
+      return {
+        ...u,
+        ...(ann.category != null && ann.category !== ""
+          ? { category: ann.category }
+          : {}),
+        ...(ann.displayName != null && ann.displayName !== ""
+          ? { displayName: ann.displayName }
+          : {}),
+        ...(ann.keywords != null && ann.keywords.length > 0
+          ? { keywords: ann.keywords }
+          : {}),
+      };
+    }),
+  }));
+}
+
 export async function getAllPerpsMeta(
   infoClient: InfoClient,
 ): Promise<AllPerpsMeta> {
-  return infoClient.transport.request<AllPerpsMeta>("info", {
-    type: "allPerpMetas",
-  });
+  const [metas, annotations] = await Promise.all([
+    infoClient.transport.request<AllPerpsMeta>("info", {
+      type: "allPerpMetas",
+    }),
+    getPerpConciseAnnotations(infoClient).catch((): PerpConciseAnnotations => {
+      return [];
+    }),
+  ]);
+
+  if (!annotations.length) {
+    return metas;
+  }
+
+  return enrichAllPerpsMetaWithAnnotations(metas, annotations);
 }

package/lib/instrument/client.ts

@@ -17,6 +17,10 @@ export interface PerpsInstrument extends BaseInstrument {
   collateralTokenSymbol: string;
   dex?: string; // HIP3 dex name (e.g., "xyz" for "xyz:MSTR")
   collateralTokenIndex?: number;
+  /** From merged `perpConciseAnnotations` (display/search). */
+  category?: string;
+  displayName?: string;
+  keywords?: string[];
 }
 
 // Spot-specific types (metadata only - no asset context data)
@@ -280,6 +284,9 @@ export class InstrumentClient {
           isDelisted: info.isDelisted,
           dex: AssetIdUtils.extractDexName(info.name),
           collateralTokenIndex: perpMeta.collateralToken,
+          category: info.category,
+          displayName: info.displayName,
+          keywords: info.keywords,
         };
 
         this.addInstrument(instrument);

package/lib/meta/types.ts

@@ -33,4 +33,8 @@ export interface PerpsUniverse {
   growthMode?: "enabled";
   /** Margin mode for the universe. */
   marginMode?: "strictIsolated" | "noCross";
+  /** From Hyperliquid `perpConciseAnnotations` when merged into meta. */
+  category?: string;
+  displayName?: string;
+  keywords?: string[];
 }

package/lib/types.ts

@@ -0,0 +1,29 @@
+import { UserAbstractionMode } from "./abstraction";
+
+export interface PerpDexState {
+    totalVaultEquity: number;
+    perpsAtOpenInterestCap?: Array<string>;
+    leadingVaults?: Array<LeadingVault>;
+  }
+
+
+// Additional undocumented fields in WebData3 will be removed on a future update
+export interface WsWebData3 {
+    userState: {
+      abstraction: UserAbstractionMode;
+      agentAddress: string | null;
+      agentValidUntil: number | null;
+      serverTime: number;
+      cumLedger: number;
+      isVault: boolean;
+      user: string;
+      optOutOfSpotDusting?: boolean;
+      dexAbstractionEnabled?: boolean;
+    };
+    perpDexStates: Array<PerpDexState>;
+  }
+  
+ export interface LeadingVault {
+    address: string;
+    name: string;
+  }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basedone/core",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "description": "Core utilities for Based One",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -63,4 +63,4 @@
       "optional": true
     }
   }
-}
+}