@basedone/core 0.2.8 → 0.3.0

package/lib/abstraction/ratio.ts

@@ -0,0 +1,61 @@
+import type {
+  MultiverseMeta,
+  PerpDexClearinghouseState,
+  SpotBalance,
+} from "./types";
+
+/**
+ * Compute the unified account ratio for monitoring liquidation risk.
+ *
+ * The ratio represents cross maintenance margin used / available balance
+ * for the most leveraged collateral token. A higher ratio means closer
+ * to liquidation.
+ *
+ * @param multiverse - Map of DEX name to its metadata (index and collateral token)
+ * @param perpDexStates - Array of per-DEX clearinghouse states
+ * @param spotBalances - Array of spot balances per token
+ * @returns The maximum ratio across all collateral tokens (0 if no margin used)
+ */
+export function computeUnifiedAccountRatio(
+  multiverse: Record<string, MultiverseMeta>,
+  perpDexStates: PerpDexClearinghouseState[],
+  spotBalances: SpotBalance[],
+): number {
+  const indexToCollateralToken: Record<number, number> = {};
+  for (const meta of Object.values(multiverse)) {
+    indexToCollateralToken[meta.index] = meta.collateralToken;
+  }
+
+  const crossMarginByToken: Record<number, number> = {};
+  const isolatedMarginByToken: Record<number, number> = {};
+
+  for (let index = 0; index < perpDexStates.length; index++) {
+    const dex = perpDexStates[index];
+    const token = indexToCollateralToken[index];
+    if (dex === undefined || token === undefined) continue;
+
+    crossMarginByToken[token] =
+      (crossMarginByToken[token] ?? 0) +
+      dex.clearinghouseState.crossMaintenanceMarginUsed;
+
+    for (const ap of dex.clearinghouseState.assetPositions) {
+      if (ap.position.leverage.type === "isolated") {
+        isolatedMarginByToken[token] =
+          (isolatedMarginByToken[token] ?? 0) + ap.position.marginUsed;
+      }
+    }
+  }
+
+  let maxRatio = 0;
+  for (const [tokenStr, crossMargin] of Object.entries(crossMarginByToken)) {
+    const token = Number(tokenStr);
+    const spotTotal = spotBalances.find((b) => b.token === token)?.total ?? 0;
+    const isolatedMargin = isolatedMarginByToken[token] ?? 0;
+    const available = spotTotal - isolatedMargin;
+    if (available > 0) {
+      maxRatio = Math.max(maxRatio, crossMargin / available);
+    }
+  }
+
+  return maxRatio;
+}

package/lib/abstraction/types.ts

@@ -0,0 +1,73 @@
+/**
+ * User abstraction modes for controlling how spot and perps balances interact.
+ *
+ * - `disabled` (Standard): Separate perp and spot balances, separate DEX balances.
+ * - `unifiedAccount`: Single balance per asset collateralizing all cross margin positions.
+ * - `portfolioMargin`: Single portfolio unifying all eligible assets (pre-alpha).
+ * - `dexAbstraction`: Legacy mode (to be discontinued).
+ * - `default`: Server default (equivalent to standard/disabled for most users).
+ */
+export type UserAbstractionMode =
+  | "unifiedAccount"
+  | "portfolioMargin"
+  | "disabled"
+  | "default"
+  | "dexAbstraction";
+
+/**
+ * Shorthand codes used with agent-based abstraction setting.
+ * - `i` = disabled (standard)
+ * - `u` = unifiedAccount
+ * - `p` = portfolioMargin
+ */
+export type AgentAbstractionCode = "i" | "u" | "p";
+
+/**
+ * Settable abstraction modes (excludes read-only states like "default" and "dexAbstraction").
+ */
+export type SettableAbstractionMode =
+  | "disabled"
+  | "unifiedAccount"
+  | "portfolioMargin";
+
+export const ABSTRACTION_MODE_TO_AGENT_CODE: Record<
+  SettableAbstractionMode,
+  AgentAbstractionCode
+> = {
+  disabled: "i",
+  unifiedAccount: "u",
+  portfolioMargin: "p",
+};
+
+export const AGENT_CODE_TO_ABSTRACTION_MODE: Record<
+  AgentAbstractionCode,
+  SettableAbstractionMode
+> = {
+  i: "disabled",
+  u: "unifiedAccount",
+  p: "portfolioMargin",
+};
+
+export interface MultiverseMeta {
+  index: number;
+  collateralToken: number;
+}
+
+export interface PerpDexAssetPosition {
+  position: {
+    leverage: { type: string };
+    marginUsed: number;
+  };
+}
+
+export interface PerpDexClearinghouseState {
+  clearinghouseState: {
+    crossMaintenanceMarginUsed: number;
+    assetPositions: PerpDexAssetPosition[];
+  };
+}
+
+export interface SpotBalance {
+  token: number;
+  total: number;
+}

package/lib/constants/admin.ts

@@ -0,0 +1,30 @@
+// Super admin Privy user IDs — single source of truth for all apps
+export const ADMINS = [
+  "did:privy:cmc3hycnb00pljs0m1z010geq",
+  "did:privy:cmc8w2ddl01rdju0nylb6rp1v",
+  "did:privy:cmc3oftiz005fjx0msox3xgey",
+  "did:privy:cmcbx7i4400q8l90mawdymaag",
+  "did:privy:cmctbwphs00vzjz0m3la3zm4c",
+  "did:privy:cmcblrplb009ol70mia13winn",
+  "did:privy:cmcmizpxm02xfju0oc81alfy0",
+  "did:privy:cmcd2bvft00w3l90ljeyb4wn6",
+  "did:privy:cmc4y13ka0119kv0nckvgla1u",
+  "did:privy:cmc8qc36g00c1l70nnutuscue",
+  "did:privy:cmc8f1tf9019zlh0myjpi420p",
+  "did:privy:cmc6bturg002ql80mhzqr1d76",
+  "did:privy:cmc8uyr4t01kljo0mk3unzjl3",
+  "did:privy:cmcke9v7h00yijy0o2a41nhms",
+  "did:privy:cmgfcjt2y0024kz0cpymoqbmp",
+  "did:privy:cmeqj8tsi01k6la0c3s7gsl6w", // elroy
+  "did:privy:cmiwrno1i00cdl70c5ro13eyp", // adele
+  "did:privy:cmkc0jyy200abji0d42a0syil", // matthew
+  "did:privy:cmlgc2zjk005vjo0cct10trdl", // adele
+];
+
+// Global admin wallet addresses
+export const ADMIN_WALLETS: string[] = [
+  "0x0c7582A67B8B6AD04Ea404A6C2A06aAc9E0d4e7c",
+  "0xDec587aDD20A6447fF0b29D70E95b10b197b1283",
+  "0x3e83987019c4CE29680401b72F8b18A2dE3f8fe6",
+  "0x5446A5Bc711170d5197DE33D8C193487794f30C0",
+];

package/lib/ecommerce/client/customer.ts

@@ -68,6 +68,8 @@ import type {
   GetExpiringGemsResponse,
   CashAccountBalanceResponse,
   DeliveryAddressResponse,
+  CustomerNotificationsResponse,
+  MarkNotificationsReadResponse,
 } from "../types";
 
 /**
@@ -1110,4 +1112,44 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   async getDeliveryAddress(): Promise<DeliveryAddressResponse> {
     return this.get("/api/basedpay/delivery-address");
   }
+
+  /**
+   * Get user's Hyperliquid USDC balance (perp withdrawable)
+   *
+   * Returns the USDC balance available for escrow deposits via usdSend.
+   *
+   * @returns Balance response with amount and currency
+   */
+  async getUsdcBalance(): Promise<CashAccountBalanceResponse> {
+    return this.get("/api/marketplace/usdc-balance");
+  }
+
+  // ============================================================================
+  // Notifications API
+  // ============================================================================
+
+  /**
+   * List notifications for the authenticated customer
+   *
+   * @param params - Query parameters for filtering and pagination
+   * @returns Paginated list of notifications with unread count
+   */
+  async listNotifications(params?: {
+    limit?: number;
+    offset?: number;
+    unreadOnly?: boolean;
+  }): Promise<CustomerNotificationsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/notifications${queryString}`);
+  }
+
+  /**
+   * Mark notifications as read
+   *
+   * @param ids - Specific notification IDs to mark as read. If omitted, marks all as read.
+   * @returns Count of updated notifications
+   */
+  async markNotificationsAsRead(ids?: string[]): Promise<MarkNotificationsReadResponse> {
+    return this.patch("/api/marketplace/notifications/read", { ids });
+  }
 }

package/lib/ecommerce/index.ts

@@ -46,6 +46,20 @@ export {
   calculateFinalPrice,
 } from "./utils/helpers";
 
+// Export order state machine
+export {
+  ORDER_STATUS_TRANSITIONS,
+  validateStatusTransition,
+  getNextStatuses,
+  isPickupOrder,
+  getStatusLabel,
+  getStatusColor,
+  canCancelOrder,
+  requiresTrackingInfo,
+  shouldNotifyCustomer,
+  getStatusProgress,
+} from "./utils/orderStateMachine";
+
 // Export client config type
 export type { EcommerceClientConfig } from "./client/base";
 

package/lib/ecommerce/types/entities.ts

@@ -357,6 +357,20 @@ export interface Order extends BaseEntity {
   };
   /** Order events */
   events?: OrderEvent[];
+  /** Expected ship date */
+  expectedShipDate?: string | null;
+  /** Estimated delivery date */
+  estimatedDeliveryDate?: string | null;
+  /** Estimated delivery days */
+  estimatedDeliveryDays?: number | null;
+  /** Auto-complete deadline */
+  autoCompleteDeadline?: string | null;
+  /** Customer confirmed receipt timestamp */
+  customerConfirmedAt?: string | null;
+  /** Auto-completed timestamp */
+  autoCompletedAt?: string | null;
+  /** Status transition timestamps */
+  statusTransitions?: Record<string, string> | null;
 }
 
 /**

package/lib/ecommerce/types/enums.ts

@@ -22,6 +22,8 @@ export enum OrderStatus {
   DELIVERED = "DELIVERED",
   /** Order has been cancelled */
   CANCELLED = "CANCELLED",
+  /** Payment settled / escrow released to merchant */
+  SETTLED = "SETTLED",
   /** Order is confirmed (legacy status) */
   CONFIRMED = "CONFIRMED",
   /** Order is completed (legacy status) */
@@ -286,8 +288,10 @@ export enum ProductSortBy {
   PRICE_ASC = "price_asc",
   /** Sort by price (high to low) */
   PRICE_DESC = "price_desc",
-  /** Sort by popularity */
+  /** Sort by popularity (views) */
   POPULAR = "popular",
+  /** Sort by best selling (sold quantity) */
+  BEST_SELLING = "best_selling",
   /** Sort by featured status */
   FEATURED = "featured",
   /** Sort by proximity to user location (requires lat/lng) */

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/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.0",
   "description": "Core utilities for Based One",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",