@basedone/core 0.2.2 → 0.2.4

package/lib/ecommerce/types/entities.ts

@@ -789,3 +789,97 @@ export interface FlashSale {
   items: FlashSaleItem[];
 }
 
+// ============================================
+// SHIPPING ENTITIES
+// ============================================
+
+/**
+ * Merchant shipping settings entity
+ */
+export interface MerchantShippingSettings extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Default handling fee in USDC */
+  defaultHandlingFee: number;
+  /** Default processing time in days */
+  defaultProcessingDays: number;
+  /** Default product weight in kg */
+  defaultWeightKg: number;
+  /** Free shipping enabled globally */
+  freeShippingEnabled: boolean;
+  /** Free shipping threshold in USDC */
+  freeShippingThreshold: number | null;
+  /** Show estimated delivery to customers */
+  showEstimatedDelivery: boolean;
+}
+
+/**
+ * Shipping zone entity
+ */
+export interface ShippingZone extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Zone name */
+  name: string;
+  /** Country codes (ISO 2-letter codes) */
+  countries: string[];
+  /** Is default zone for unlisted countries */
+  isDefault: boolean;
+  /** Is zone active */
+  isActive: boolean;
+  /** Priority (higher = checked first) */
+  priority: number;
+  /** Number of rates in this zone */
+  rateCount?: number;
+  /** Associated shipping rates */
+  rates?: ShippingRate[];
+}
+
+/**
+ * Shipping rate entity
+ */
+export interface ShippingRate extends BaseEntity {
+  /** Zone ID */
+  zoneId: string;
+  /** Zone name (for display) */
+  zoneName?: string;
+  /** Merchant ID */
+  merchantId: string;
+  /** Rate name (e.g., "Standard", "Express") */
+  name: string;
+  /** Base shipping rate in USDC */
+  baseRate: number;
+  /** Per kg rate in USDC */
+  perKgRate: number;
+  /** Minimum weight in kg */
+  minWeightKg: number | null;
+  /** Maximum weight in kg */
+  maxWeightKg: number | null;
+  /** Minimum delivery days */
+  minDeliveryDays: number | null;
+  /** Maximum delivery days */
+  maxDeliveryDays: number | null;
+  /** Free shipping above this amount */
+  freeAboveAmount: number | null;
+  /** Is rate active */
+  isActive: boolean;
+  /** Sort order */
+  sortOrder: number;
+}
+
+/**
+ * Shipping option (calculated for checkout)
+ */
+export interface ShippingOption {
+  /** Rate ID */
+  id: string;
+  /** Rate name */
+  name: string;
+  /** Calculated cost in USDC */
+  cost: number;
+  /** Estimated delivery string */
+  estimatedDelivery: string;
+  /** Zone name */
+  zoneName: string;
+}
+

package/lib/ecommerce/types/enums.ts

@@ -32,8 +32,12 @@ export enum OrderStatus {
  * Payment method enum
  */
 export enum PaymentMethod {
-  /** USDC payment via Hyperliquid escrow */
+  /** USDC payment via Hyperliquid SpotTransfer */
   USDC_ESCROW = "USDC_ESCROW",
+  /** BasedPay external ledger payment */
+  BASEDPAY = "BASEDPAY",
+  /** Stripe card payment */
+  STRIPE = "STRIPE",
   /** Points-based payment */
   POINTS = "POINTS",
 }
@@ -254,6 +258,8 @@ export enum ProductSortBy {
   POPULAR = "popular",
   /** Sort by featured status */
   FEATURED = "featured",
+  /** Sort by proximity to user location (requires lat/lng) */
+  NEARBY = "nearby",
 }
 
 /**

package/lib/ecommerce/types/requests.ts

@@ -54,6 +54,12 @@ export interface ListProductsParams extends PaginationParams {
   sortBy?: ProductSortBy;
   /** Filter by active status */
   isActive?: boolean;
+  /** Filter by destination country (ISO 2-letter code) - only show products from merchants that ship here */
+  country?: string;
+  /** User latitude for proximity sorting (used with sortBy=nearby) */
+  lat?: number;
+  /** User longitude for proximity sorting (used with sortBy=nearby) */
+  lng?: number;
 }
 
 /**
@@ -144,6 +150,14 @@ export interface CreateOrderRequest {
   couponCode?: string;
   /** Idempotency key */
   idempotencyKey?: string;
+  /** Selected shipping method name (e.g., "Standard", "Express") */
+  shippingMethod?: string;
+  /** Calculated shipping cost in USDC */
+  shippingCost?: number;
+  /** Shipping zone name for reference */
+  shippingZone?: string;
+  /** Estimated delivery time (e.g., "5-7 business days") */
+  estimatedDelivery?: string;
 }
 
 /**
@@ -602,3 +616,140 @@ export interface ListFollowingParams extends PaginationParams {
   sortBy?: "recent" | "name";
 }
 
+// ============================================
+// SHIPPING REQUESTS
+// ============================================
+
+/**
+ * Update shipping settings request
+ */
+export interface UpdateShippingSettingsRequest {
+  /** Default handling fee in USDC */
+  defaultHandlingFee?: number;
+  /** Default processing time in days */
+  defaultProcessingDays?: number;
+  /** Default product weight in kg */
+  defaultWeightKg?: number;
+  /** Free shipping enabled globally */
+  freeShippingEnabled?: boolean;
+  /** Free shipping threshold in USDC */
+  freeShippingThreshold?: number | null;
+  /** Show estimated delivery to customers */
+  showEstimatedDelivery?: boolean;
+}
+
+/**
+ * Create shipping zone request
+ */
+export interface CreateShippingZoneRequest {
+  /** Zone name */
+  name: string;
+  /** Country codes (ISO 2-letter codes) */
+  countries: string[];
+  /** Is default zone for unlisted countries */
+  isDefault?: boolean;
+  /** Is zone active */
+  isActive?: boolean;
+  /** Priority (higher = checked first) */
+  priority?: number;
+}
+
+/**
+ * Update shipping zone request
+ */
+export interface UpdateShippingZoneRequest extends Partial<CreateShippingZoneRequest> {}
+
+/**
+ * Create shipping rate request
+ */
+export interface CreateShippingRateRequest {
+  /** Zone ID */
+  zoneId: string;
+  /** Rate name (e.g., "Standard", "Express") */
+  name: string;
+  /** Base shipping rate in USDC */
+  baseRate: number;
+  /** Per kg rate in USDC */
+  perKgRate?: number;
+  /** Minimum weight in kg */
+  minWeightKg?: number | null;
+  /** Maximum weight in kg */
+  maxWeightKg?: number | null;
+  /** Minimum delivery days */
+  minDeliveryDays?: number | null;
+  /** Maximum delivery days */
+  maxDeliveryDays?: number | null;
+  /** Free shipping above this amount */
+  freeAboveAmount?: number | null;
+  /** Is rate active */
+  isActive?: boolean;
+  /** Sort order */
+  sortOrder?: number;
+}
+
+/**
+ * Update shipping rate request
+ */
+export interface UpdateShippingRateRequest extends Partial<Omit<CreateShippingRateRequest, "zoneId">> {}
+
+/**
+ * Calculate shipping options request
+ */
+export interface CalculateShippingRequest {
+  /** Merchant ID */
+  merchantId: string;
+  /** Cart items */
+  cartItems: CartItem[];
+  /** Destination country code (ISO 2-letter) */
+  destinationCountry: string;
+  /** Order subtotal in USDC */
+  orderSubtotal: number;
+}
+
+// ============================================================================
+// GEM System Requests
+// ============================================================================
+
+/**
+ * Gem history type filter
+ */
+export type GemHistoryTypeFilter = "earn" | "spend" | "all";
+
+/**
+ * Get gem history parameters
+ */
+export interface GetGemHistoryParams extends PaginationParams {
+  /** Filter by transaction type */
+  type?: GemHistoryTypeFilter;
+}
+
+/**
+ * Get expiring gems parameters
+ */
+export interface GetExpiringGemsParams {
+  /** Number of days ahead to check (default: 30, max: 180) */
+  days?: number;
+}
+
+// ============================================================================
+// Browsing Location Requests
+// ============================================================================
+
+/**
+ * Save browsing location request
+ */
+export interface SaveBrowsingLocationRequest {
+  /** Full display address from Google Places */
+  formattedAddress: string;
+  /** City name */
+  city: string;
+  /** State/Province (optional) */
+  stateProvince?: string;
+  /** ISO 2-letter country code (e.g., "SG", "US") */
+  country: string;
+  /** Latitude coordinate */
+  latitude: number;
+  /** Longitude coordinate */
+  longitude: number;
+}
+

package/lib/ecommerce/types/responses.ts

@@ -951,3 +951,317 @@ export interface ActiveFlashSalesResponse {
   serverTime: string;
 }
 
+// ============================================
+// SHIPPING RESPONSES
+// ============================================
+
+import type {
+  MerchantShippingSettings,
+  ShippingZone,
+  ShippingRate,
+  ShippingOption,
+} from "./entities";
+
+/**
+ * Get shipping settings response
+ */
+export interface ShippingSettingsResponse {
+  /** Shipping settings */
+  settings: MerchantShippingSettings | {
+    defaultHandlingFee: number;
+    defaultProcessingDays: number;
+    freeShippingEnabled: boolean;
+    freeShippingThreshold: number | null;
+    defaultWeightKg: number;
+    showEstimatedDelivery: boolean;
+  };
+}
+
+/**
+ * List shipping zones response
+ */
+export interface ListShippingZonesResponse {
+  /** Shipping zones */
+  zones: ShippingZone[];
+}
+
+/**
+ * Shipping zone response
+ */
+export interface ShippingZoneResponse {
+  /** Shipping zone */
+  zone: ShippingZone;
+}
+
+/**
+ * List shipping rates response
+ */
+export interface ListShippingRatesResponse {
+  /** Shipping rates */
+  rates: ShippingRate[];
+}
+
+/**
+ * Shipping rate response
+ */
+export interface ShippingRateResponse {
+  /** Shipping rate */
+  rate: ShippingRate;
+}
+
+/**
+ * Calculate shipping options response
+ */
+export interface CalculateShippingResponse {
+  /** Available shipping options */
+  shippingOptions: ShippingOption[];
+}
+
+// ============================================================================
+// Payment Method Responses
+// ============================================================================
+
+/**
+ * Payment method info for display
+ */
+export interface PaymentMethodInfo {
+  /** Payment method ID (e.g., "USDC_ESCROW") */
+  id: string;
+  /** Display name (e.g., "USDC (Hyperliquid)") */
+  name: string;
+  /** Description of the payment method */
+  description: string;
+  /** Icon identifier */
+  icon?: string;
+  /** Whether the payment requires user signature (e.g., blockchain) */
+  requiresSignature?: boolean;
+  /** Whether refunds are supported */
+  supportsRefund?: boolean;
+}
+
+/**
+ * Get payment methods response
+ */
+export interface GetPaymentMethodsResponse {
+  /** Whether the request was successful */
+  success: boolean;
+  /** Whether payments are globally enabled */
+  paymentsEnabled: boolean;
+  /** List of enabled payment methods */
+  methods: PaymentMethodInfo[];
+  /** Optional message (e.g., when payments are disabled) */
+  message?: string;
+}
+
+/**
+ * Process payment request
+ */
+export interface ProcessPaymentRequest {
+  /** Order ID to pay for */
+  orderId: string;
+  /** Payment method to use */
+  paymentMethod: string;
+  /** Amount in USDC */
+  amount: number;
+  /** Pre-signed action for USDC_ESCROW */
+  signedAction?: {
+    action: unknown;
+    nonce: number;
+    signature: unknown;
+  };
+  /** Stripe payment method ID */
+  stripePaymentMethodId?: string;
+  /** BasedPay account ID */
+  basedPayAccountId?: string;
+  /** Points to spend */
+  pointsAmount?: number;
+}
+
+/**
+ * Process payment response
+ */
+export interface ProcessPaymentResponse {
+  /** Whether the payment was successful */
+  success: boolean;
+  /** Payment transaction ID */
+  transactionId?: string;
+  /** Blockchain transaction hash (for crypto payments) */
+  transactionHash?: string;
+  /** Payment status */
+  status: "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED" | "REFUNDED";
+  /** Amount charged */
+  amount: number;
+  /** Currency */
+  currency: string;
+  /** Error message if failed */
+  error?: string;
+  /** Error code */
+  errorCode?: string;
+}
+
+// ============================================================================
+// GEM System Responses
+// ============================================================================
+
+/**
+ * Gem source type - how gems were earned
+ */
+export type GemSource = 
+  | "BUILDER_CODE"
+  | "PREDICTION"
+  | "CARD_SPEND"
+  | "MALL_SPEND"
+  | "ADMIN"
+  | "REFUND";
+
+/**
+ * Get gem balance response
+ */
+export interface GetGemBalanceResponse {
+  /** User ID */
+  userId: string;
+  /** Total gems owned */
+  totalGems: number;
+  /** Available gems (not reserved) */
+  availableGems: number;
+  /** Gems expiring within 30 days */
+  expiringSoon: number;
+  /** Last balance update timestamp */
+  lastUpdated: string;
+  /** USD equivalent (totalGems / 100) */
+  usdEquivalent: number;
+  /** Conversion rate (gems per $1) */
+  conversionRate: number;
+}
+
+/**
+ * Gem history item type
+ */
+export type GemHistoryType = "earn" | "spend" | "expire";
+
+/**
+ * Gem history item
+ */
+export interface GemHistoryItem {
+  /** Transaction ID */
+  id: string;
+  /** Type of transaction */
+  type: GemHistoryType;
+  /** Amount of gems (positive for earn, negative for spend) */
+  amount: number;
+  /** Source type (for earn transactions) */
+  source?: GemSource;
+  /** Reason description (for spend transactions) */
+  reason?: string;
+  /** When the transaction occurred */
+  createdAt: string;
+  /** When the gems expire (for earn transactions) */
+  expiresAt?: string;
+}
+
+/**
+ * Get gem history response
+ */
+export interface GetGemHistoryResponse {
+  /** History items */
+  items: GemHistoryItem[];
+  /** Total count of items */
+  total: number;
+  /** Pagination info */
+  pagination: {
+    /** Items per page */
+    limit: number;
+    /** Current offset */
+    offset: number;
+    /** Whether more items exist */
+    hasMore: boolean;
+  };
+}
+
+/**
+ * Expiring gem batch
+ */
+export interface ExpiringGemBatch {
+  /** Batch ID */
+  id: string;
+  /** Remaining gems in batch */
+  amount: number;
+  /** How the gems were earned */
+  source: GemSource;
+  /** When the batch expires */
+  expiresAt: string;
+  /** When the batch was created */
+  createdAt: string;
+  /** Days until expiry */
+  daysUntilExpiry: number;
+}
+
+/**
+ * Get expiring gems response
+ */
+export interface GetExpiringGemsResponse {
+  /** Total gems expiring within the query period */
+  totalExpiring: number;
+  /** Expiring batches */
+  batches: ExpiringGemBatch[];
+  /** Query parameters used */
+  queryParams: {
+    /** Days ahead that were queried */
+    days: number;
+  };
+}
+
+// ============================================================================
+// Browsing Location Responses
+// ============================================================================
+
+/**
+ * User's browsing location for geo-based product filtering
+ */
+export interface BrowsingLocation {
+  /** Location ID */
+  id: string;
+  /** Full display address */
+  formattedAddress: string;
+  /** City name */
+  city: string;
+  /** State/Province (if applicable) */
+  stateProvince?: string | null;
+  /** ISO 2-letter country code */
+  country: string;
+  /** Latitude coordinate */
+  latitude: number;
+  /** Longitude coordinate */
+  longitude: number;
+  /** Last updated timestamp */
+  updatedAt: string;
+}
+
+/**
+ * Get browsing location response
+ */
+export interface GetBrowsingLocationResponse {
+  /** User's saved browsing location (null if not set) */
+  location: BrowsingLocation | null;
+}
+
+/**
+ * Save browsing location response
+ */
+export interface SaveBrowsingLocationResponse {
+  /** Whether the operation was successful */
+  success: boolean;
+  /** The saved location */
+  location: BrowsingLocation;
+}
+
+/**
+ * Delete browsing location response
+ */
+export interface DeleteBrowsingLocationResponse {
+  /** Whether the operation was successful */
+  success: boolean;
+  /** Success message */
+  message: string;
+}
+

package/lib/utils/formatter.ts

@@ -80,7 +80,7 @@ export const formatSizeForOrder = ({
   sz,
   szDecimals,
 }: {
-  sz: number;
+  sz: number | string;
   szDecimals: number;
 }) => {
   return new Decimal(sz).toDP(szDecimals, Decimal.ROUND_DOWN).toNumber();

package/lib/utils/time.ts

@@ -49,3 +49,27 @@ export function getLatestCompletedWeek(
   return { weekNumber, startDate, endDate };
 }
 
+/**
+ * Gets week information from a week number.
+ * This is the inverse of getLatestCompletedWeek - it converts a week number to start/end dates.
+ * 
+ * @param weekNumber - The week number (1-based, where week 1 starts at WEEK1_START_DATE)
+ * @param weekStartsOn - Day of week the week should start on. Defaults to Thursday.
+ * @returns WeekInfo with weekNumber, startDate, and endDate
+ */
+export function getWeekInfoFromNumber(
+  weekNumber: number,
+  weekStartsOn: DayOfWeek = DayOfWeek.Thursday
+): WeekInfo {
+  // Using a fixed point in time for week 1 calculation for consistency
+  const week1StartDate = new Date(process.env.WEEK1_START_DATE || "2025-12-04T00:00:00Z");
+  
+  // Calculate start date: week 1 starts at week1StartDate, week N starts at week1StartDate + (N-1) weeks
+  const startDate = new Date(week1StartDate.getTime() + (weekNumber - 1) * WEEK_IN_MS);
+  
+  // End date is 7 days after start date
+  const endDate = new Date(startDate.getTime() + WEEK_IN_MS);
+  
+  return { weekNumber, startDate, endDate };
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basedone/core",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Core utilities for Based One",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -36,17 +36,18 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@types/react": "^18.0.0",
+    "axios": "^1.6.0",
     "tsup": "^8.5.0",
     "tsx": "^4.19.2",
     "typescript": "^5.0.0",
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "axios": "^1.6.0",
     "decimal.js": "^10.6.0"
   },
   "peerDependencies": {
     "@nktkas/hyperliquid": "^0.24.3",
+    "axios": "^1.6.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {