@basedone/core 0.2.3 → 0.2.4

package/dist/index.js

@@ -43324,6 +43324,148 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   async getPaymentMethods() {
     return this.get("/api/marketplace/payments/methods");
   }
+  // ============================================================================
+  // GEM System API
+  // ============================================================================
+  /**
+   * Get user's gem balance
+   * 
+   * Returns the current gem balance including total gems, available gems,
+   * and gems expiring soon. Gems are earned at 100 per $1 of revenue.
+   * 
+   * @returns Current gem balance with USD equivalent
+   * 
+   * @example
+   * ```typescript
+   * const balance = await client.getGemBalance();
+   * console.log(`You have ${balance.totalGems} gems (${balance.usdEquivalent} USD)`);
+   * console.log(`${balance.expiringSoon} gems expiring soon`);
+   * ```
+   */
+  async getGemBalance() {
+    return this.get("/api/gems/balance");
+  }
+  /**
+   * Get gem transaction history
+   * 
+   * Returns paginated history of gem transactions including earning,
+   * spending, and expiration events.
+   * 
+   * @param params - Query parameters for filtering and pagination
+   * @returns Paginated gem history
+   * 
+   * @example
+   * ```typescript
+   * // Get all history
+   * const history = await client.getGemHistory({ limit: 20, offset: 0 });
+   * 
+   * // Get only earned gems
+   * const earned = await client.getGemHistory({ type: "earn", limit: 10 });
+   * 
+   * // Get only spent gems
+   * const spent = await client.getGemHistory({ type: "spend", limit: 10 });
+   * 
+   * history.items.forEach(item => {
+   *   console.log(`${item.type}: ${item.amount} gems - ${item.createdAt}`);
+   * });
+   * ```
+   */
+  async getGemHistory(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/gems/history${queryString}`);
+  }
+  /**
+   * Get gems that are expiring soon
+   * 
+   * Returns gem batches that will expire within the specified number of days.
+   * Useful for prompting users to spend gems before they expire.
+   * 
+   * @param params - Query parameters (days: default 30, max 180)
+   * @returns Expiring gem batches with countdown info
+   * 
+   * @example
+   * ```typescript
+   * // Get gems expiring in next 30 days (default)
+   * const expiring = await client.getExpiringGems();
+   * 
+   * // Get gems expiring in next 7 days
+   * const urgent = await client.getExpiringGems({ days: 7 });
+   * 
+   * if (expiring.totalExpiring > 0) {
+   *   console.log(`${expiring.totalExpiring} gems expiring soon!`);
+   *   expiring.batches.forEach(batch => {
+   *     console.log(`${batch.amount} gems expire in ${batch.daysUntilExpiry} days`);
+   *   });
+   * }
+   * ```
+   */
+  async getExpiringGems(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/gems/expiring${queryString}`);
+  }
+  // ============================================================================
+  // Browsing Location API
+  // ============================================================================
+  /**
+   * Get user's browsing location
+   * 
+   * Returns the user's saved delivery location for geo-based product filtering.
+   * This location is used to show products from merchants that ship to the area.
+   * 
+   * @returns Current browsing location or null if not set
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getBrowsingLocation();
+   * if (result.location) {
+   *   console.log(`Delivery to: ${result.location.city}, ${result.location.country}`);
+   * }
+   * ```
+   */
+  async getBrowsingLocation() {
+    return this.get("/api/user/browsing-location");
+  }
+  /**
+   * Save user's browsing location
+   * 
+   * Sets the user's delivery location for geo-based product filtering.
+   * Products will be filtered to show only items from merchants that ship to this location.
+   * 
+   * @param request - Location data from Google Places or manual input
+   * @returns The saved location
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.saveBrowsingLocation({
+   *   formattedAddress: "Singapore, Singapore",
+   *   city: "Singapore",
+   *   country: "SG",
+   *   latitude: 1.3521,
+   *   longitude: 103.8198
+   * });
+   * console.log(`Location saved: ${result.location.formattedAddress}`);
+   * ```
+   */
+  async saveBrowsingLocation(request) {
+    return this.post("/api/user/browsing-location", request);
+  }
+  /**
+   * Clear user's browsing location
+   * 
+   * Removes the user's saved delivery location. Products will no longer
+   * be filtered by shipping destination.
+   * 
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.clearBrowsingLocation();
+   * console.log("Location cleared - showing all products");
+   * ```
+   */
+  async clearBrowsingLocation() {
+    return this.delete("/api/user/browsing-location");
+  }
 };
 
 // lib/ecommerce/client/merchant.ts
@@ -44987,6 +45129,7 @@ var ProductSortBy = /* @__PURE__ */ ((ProductSortBy2) => {
   ProductSortBy2["PRICE_DESC"] = "price_desc";
   ProductSortBy2["POPULAR"] = "popular";
   ProductSortBy2["FEATURED"] = "featured";
+  ProductSortBy2["NEARBY"] = "nearby";
   return ProductSortBy2;
 })(ProductSortBy || {});
 var ReviewSortBy = /* @__PURE__ */ ((ReviewSortBy2) => {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantEcommerceClient, MerchantStatus, OrderStatus, PaymentMethod, PaymentStatus, ProductSortBy, ReturnStatus, ReviewSortBy, ReviewStatus, ShipmentStatus, SortOrder, TaxBehavior, TaxReportPeriodType, TaxReportStatus, TaxType, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './chunk-SKX4VGEN.mjs';
+export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantEcommerceClient, MerchantStatus, OrderStatus, PaymentMethod, PaymentStatus, ProductSortBy, ReturnStatus, ReviewSortBy, ReviewStatus, ShipmentStatus, SortOrder, TaxBehavior, TaxReportPeriodType, TaxReportStatus, TaxType, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './chunk-NVL2HX2H.mjs';
 export { AssetIdUtils, InstrumentClient } from './chunk-VBC6EQ7Q.mjs';
 import { __glob } from './chunk-4UEJOM6W.mjs';
 import Decimal, { Decimal as Decimal$1 } from 'decimal.js';

package/lib/ecommerce/client/customer.ts

@@ -25,6 +25,9 @@ import type {
   ListMerchantProductsParams,
   ListFollowingParams,
   CalculateShippingRequest,
+  GetGemHistoryParams,
+  GetExpiringGemsParams,
+  SaveBrowsingLocationRequest,
   
   // Response types
   ListProductsResponse,
@@ -55,6 +58,12 @@ import type {
   FollowActionResponse,
   ListFollowingResponse,
   CalculateShippingResponse,
+  GetGemBalanceResponse,
+  GetBrowsingLocationResponse,
+  SaveBrowsingLocationResponse,
+  DeleteBrowsingLocationResponse,
+  GetGemHistoryResponse,
+  GetExpiringGemsResponse,
 } from "../types";
 
 /**
@@ -825,5 +834,155 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   async getPaymentMethods(): Promise<GetPaymentMethodsResponse> {
     return this.get("/api/marketplace/payments/methods");
   }
+
+  // ============================================================================
+  // GEM System API
+  // ============================================================================
+
+  /**
+   * Get user's gem balance
+   * 
+   * Returns the current gem balance including total gems, available gems,
+   * and gems expiring soon. Gems are earned at 100 per $1 of revenue.
+   * 
+   * @returns Current gem balance with USD equivalent
+   * 
+   * @example
+   * ```typescript
+   * const balance = await client.getGemBalance();
+   * console.log(`You have ${balance.totalGems} gems (${balance.usdEquivalent} USD)`);
+   * console.log(`${balance.expiringSoon} gems expiring soon`);
+   * ```
+   */
+  async getGemBalance(): Promise<GetGemBalanceResponse> {
+    return this.get("/api/gems/balance");
+  }
+
+  /**
+   * Get gem transaction history
+   * 
+   * Returns paginated history of gem transactions including earning,
+   * spending, and expiration events.
+   * 
+   * @param params - Query parameters for filtering and pagination
+   * @returns Paginated gem history
+   * 
+   * @example
+   * ```typescript
+   * // Get all history
+   * const history = await client.getGemHistory({ limit: 20, offset: 0 });
+   * 
+   * // Get only earned gems
+   * const earned = await client.getGemHistory({ type: "earn", limit: 10 });
+   * 
+   * // Get only spent gems
+   * const spent = await client.getGemHistory({ type: "spend", limit: 10 });
+   * 
+   * history.items.forEach(item => {
+   *   console.log(`${item.type}: ${item.amount} gems - ${item.createdAt}`);
+   * });
+   * ```
+   */
+  async getGemHistory(params?: GetGemHistoryParams): Promise<GetGemHistoryResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/gems/history${queryString}`);
+  }
+
+  /**
+   * Get gems that are expiring soon
+   * 
+   * Returns gem batches that will expire within the specified number of days.
+   * Useful for prompting users to spend gems before they expire.
+   * 
+   * @param params - Query parameters (days: default 30, max 180)
+   * @returns Expiring gem batches with countdown info
+   * 
+   * @example
+   * ```typescript
+   * // Get gems expiring in next 30 days (default)
+   * const expiring = await client.getExpiringGems();
+   * 
+   * // Get gems expiring in next 7 days
+   * const urgent = await client.getExpiringGems({ days: 7 });
+   * 
+   * if (expiring.totalExpiring > 0) {
+   *   console.log(`${expiring.totalExpiring} gems expiring soon!`);
+   *   expiring.batches.forEach(batch => {
+   *     console.log(`${batch.amount} gems expire in ${batch.daysUntilExpiry} days`);
+   *   });
+   * }
+   * ```
+   */
+  async getExpiringGems(params?: GetExpiringGemsParams): Promise<GetExpiringGemsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/gems/expiring${queryString}`);
+  }
+
+  // ============================================================================
+  // Browsing Location API
+  // ============================================================================
+
+  /**
+   * Get user's browsing location
+   * 
+   * Returns the user's saved delivery location for geo-based product filtering.
+   * This location is used to show products from merchants that ship to the area.
+   * 
+   * @returns Current browsing location or null if not set
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getBrowsingLocation();
+   * if (result.location) {
+   *   console.log(`Delivery to: ${result.location.city}, ${result.location.country}`);
+   * }
+   * ```
+   */
+  async getBrowsingLocation(): Promise<GetBrowsingLocationResponse> {
+    return this.get("/api/user/browsing-location");
+  }
+
+  /**
+   * Save user's browsing location
+   * 
+   * Sets the user's delivery location for geo-based product filtering.
+   * Products will be filtered to show only items from merchants that ship to this location.
+   * 
+   * @param request - Location data from Google Places or manual input
+   * @returns The saved location
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.saveBrowsingLocation({
+   *   formattedAddress: "Singapore, Singapore",
+   *   city: "Singapore",
+   *   country: "SG",
+   *   latitude: 1.3521,
+   *   longitude: 103.8198
+   * });
+   * console.log(`Location saved: ${result.location.formattedAddress}`);
+   * ```
+   */
+  async saveBrowsingLocation(request: SaveBrowsingLocationRequest): Promise<SaveBrowsingLocationResponse> {
+    return this.post("/api/user/browsing-location", request);
+  }
+
+  /**
+   * Clear user's browsing location
+   * 
+   * Removes the user's saved delivery location. Products will no longer
+   * be filtered by shipping destination.
+   * 
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.clearBrowsingLocation();
+   * console.log("Location cleared - showing all products");
+   * ```
+   */
+  async clearBrowsingLocation(): Promise<DeleteBrowsingLocationResponse> {
+    return this.delete("/api/user/browsing-location");
+  }
 }
 

package/lib/ecommerce/types/enums.ts

@@ -258,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;
 }
 
 /**
@@ -700,3 +706,50 @@ export interface CalculateShippingRequest {
   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

@@ -1099,3 +1099,169 @@ export interface ProcessPaymentResponse {
   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basedone/core",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Core utilities for Based One",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",