@basedone/core 0.2.1 → 0.2.3

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",
 }

package/lib/ecommerce/types/requests.ts

@@ -144,6 +144,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;
 }
 
 /**
@@ -578,3 +586,117 @@ export interface CreateFlashSaleRequest {
  */
 export interface UpdateFlashSaleRequest extends Partial<CreateFlashSaleRequest> {}
 
+/**
+ * List merchant products params
+ */
+export interface ListMerchantProductsParams extends PaginationParams {
+  /** Search query */
+  search?: string;
+  /** Filter by category slug */
+  category?: string;
+  /** Minimum price */
+  minPrice?: number;
+  /** Maximum price */
+  maxPrice?: number;
+  /** Sort by: popular, latest, top_sales, price_asc, price_desc, rating */
+  sortBy?: "popular" | "latest" | "top_sales" | "price_asc" | "price_desc" | "rating";
+}
+
+/**
+ * List followed merchants params
+ */
+export interface ListFollowingParams extends PaginationParams {
+  /** Sort by: recent (default) or name */
+  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;
+}
+

package/lib/ecommerce/types/responses.ts

@@ -340,6 +340,102 @@ export interface MerchantProfileResponse {
   merchant: Merchant;
 }
 
+/**
+ * Public merchant profile (for storefront)
+ */
+export interface PublicMerchantProfile {
+  /** Merchant ID */
+  id: string;
+  /** Merchant name */
+  name: string;
+  /** Description */
+  description: string | null;
+  /** Created at */
+  createdAt: string;
+  /** Number of active products */
+  productCount: number;
+  /** Total orders */
+  orderCount: number;
+  /** Average rating */
+  averageRating: number | null;
+  /** Total sold count */
+  totalSold: number;
+  /** Total view count */
+  totalViews: number;
+  /** Review count */
+  reviewCount: number;
+  /** Follower count */
+  followerCount: number;
+  /** Categories the merchant sells in */
+  categories: string[];
+}
+
+/**
+ * Public merchant profile response
+ */
+export interface PublicMerchantProfileResponse {
+  /** Merchant */
+  merchant: PublicMerchantProfile;
+}
+
+/**
+ * Merchant products response
+ */
+export interface MerchantProductsResponse extends PaginatedResponse<Product> {
+  /** Merchant info */
+  merchant: {
+    id: string;
+    name: string;
+  };
+}
+
+/**
+ * Follow status response
+ */
+export interface FollowStatusResponse {
+  /** Whether the user is following */
+  isFollowing: boolean;
+  /** When the user followed (null if not following) */
+  followedAt: string | null;
+}
+
+/**
+ * Follow action response
+ */
+export interface FollowActionResponse {
+  /** Success flag */
+  success: boolean;
+  /** Human-readable message */
+  message: string;
+  /** Whether the user is now following */
+  isFollowing: boolean;
+  /** When the user followed (only for follow action) */
+  followedAt?: string;
+}
+
+/**
+ * Followed merchant summary
+ */
+export interface FollowedMerchantSummary {
+  /** When the user followed */
+  followedAt: string;
+  /** Merchant info */
+  merchant: {
+    id: string;
+    name: string;
+    description: string | null;
+    createdAt: string;
+    productCount: number;
+    averageRating: number | null;
+    totalSold: number;
+  };
+}
+
+/**
+ * List followed merchants response
+ */
+export interface ListFollowingResponse extends PaginatedResponse<FollowedMerchantSummary> {}
+
 /**
  * List coupons response
  */
@@ -855,3 +951,151 @@ 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;
+}
+

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.1",
+  "version": "0.2.3",
   "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": {