@basedone/core 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { SpotToken, MarginTables, PerpsAssetCtx, SpotMeta, ExchangeClient, SuccessResponse, InfoClient } from '@nktkas/hyperliquid';
 import { Hex } from '@nktkas/hyperliquid/types';
 export { A as AllPerpsMeta, d as AssetIdUtils, B as BaseInstrument, I as InstrumentClient, M as MarketInstrument, c as PerpsInstrument, P as PerpsMeta, a as PerpsMetaAndAssetCtxs, b as PerpsUniverse, S as SpotInstrument, g as getAllPerpsMeta } from './client-CgmiTuEX.js';
-export { ActiveFlashSalesResponse, AnalyticsOverview, ApiResponse, AppliedDiscount, Banner, BannerResponse, BannerType, BaseEcommerceClient, BaseEntity, CalculateCartDiscountsRequest, CalculateCartDiscountsResponse, CalculateShippingRequest, CalculateShippingResponse, CalculateTaxRequest, CalculateTaxResponse, CartItem, ConfirmEscrowDepositResponse, Coupon, CouponResponse, CouponUsage, CreateBannerRequest, CreateCouponRequest, CreateFlashSaleRequest, CreateOrderEventRequest, CreateOrderEventResponse, CreateOrderRequest, CreateOrderResponse, CreateProductRequest, CreateProductVariantRequest, CreateReviewRequest, CreateShippingMethodRequest, CreateShippingRateRequest, CreateShippingZoneRequest, CreateTaxNexusRequest, CreateTaxRuleRequest, CustomerEcommerceClient, CustomerMessagesResponse, CustomerSummary, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, EcommerceClientConfig, FlashSale, FlashSaleItem, FlashSaleItemInput, FollowActionResponse, FollowStatusResponse, FollowedMerchantSummary, GenerateTaxReportRequest, GetAnalyticsParams, GetAnalyticsResponse, GetCouponResponse, GetOrderResponse, GetPaymentMethodsResponse, GetProductMetricsResponse, GetProductResponse, GetTaxReportResponse, InventoryAuditAction, InventoryAuditEntry, ListActiveBannersParams, ListActiveFlashSalesParams, ListBannersResponse, ListCouponsResponse, ListCustomersParams, ListCustomersResponse, ListFollowingParams, ListFollowingResponse, ListInventoryAuditResponse, ListMediaAssetsResponse, ListMerchantProductsParams, ListMessagesResponse, ListOrdersParams, ListOrdersResponse, ListProductVariantsResponse, ListProductsParams, ListProductsResponse, ListReturnsResponse, ListReviewsParams, ListReviewsResponse, ListShipmentsResponse, ListShippingAddressesResponse, ListShippingMethodsResponse, ListShippingRatesResponse, ListShippingZonesResponse, ListTaxNexusResponse, ListTaxReportsParams, ListTaxReportsResponse, ListTaxRulesResponse, MediaAsset, MediaAssetResponse, Merchant, MerchantEcommerceClient, MerchantProductsResponse, MerchantProfileRequest, MerchantProfileResponse, MerchantShippingSettings, MerchantStatus, Message, MessageResponse, MessageStatsResponse, Order, OrderEvent, OrderItem, OrderReceiptResponse, OrderStatus, OrdersByStatus, PaginatedResponse, PaginationParams, Payment, PaymentMethod, PaymentMethodInfo, PaymentStatus, ProcessPaymentRequest, ProcessPaymentResponse, Product, ProductDimensions, ProductDiscountsResponse, ProductMetrics, ProductResponse, ProductReview, ProductSortBy, ProductVariant, ProductVariantResponse, PublicMerchantProfile, PublicMerchantProfileResponse, RecentOrderSummary, RespondToReviewRequest, Return, ReturnItem, ReturnResponse, ReturnStatus, RevenueByDay, ReviewResponse, ReviewSortBy, ReviewStatus, SendMessageRequest, Settlement, Shipment, ShipmentResponse, ShipmentStatus, ShippingAddress, ShippingAddressRequest, ShippingAddressResponse, ShippingMethod, ShippingMethodResponse, ShippingOption, ShippingRate, ShippingRateResponse, ShippingSettingsResponse, ShippingZone, ShippingZoneResponse, SortOrder, SuccessResponse, TaxBehavior, TaxBreakdownItem, TaxNexus, TaxNexusResponse, TaxReport, TaxReportDetails, TaxReportPeriodType, TaxReportResponse, TaxReportStatus, TaxRule, TaxRuleResponse, TaxSettings, TaxSettingsResponse, TaxType, TopProduct, TrackBannerRequest, UpdateBannerRequest, UpdateCouponRequest, UpdateFlashSaleRequest, UpdateOrderResponse, UpdateOrderStatusRequest, UpdateProductRequest, UpdateProductVariantRequest, UpdateShipmentRequest, UpdateShippingMethodRequest, UpdateShippingRateRequest, UpdateShippingSettingsRequest, UpdateShippingZoneRequest, UpdateTaxNexusRequest, UpdateTaxReportStatusRequest, UpdateTaxRuleRequest, UpdateTaxSettingsRequest, UserShippingAddress, ValidateDiscountRequest, ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './ecommerce.js';
+export { ActiveFlashSalesResponse, AnalyticsOverview, ApiResponse, AppliedDiscount, Banner, BannerResponse, BannerType, BaseEcommerceClient, BaseEntity, BrowsingLocation, CalculateCartDiscountsRequest, CalculateCartDiscountsResponse, CalculateShippingRequest, CalculateShippingResponse, CalculateTaxRequest, CalculateTaxResponse, CartItem, ConfirmEscrowDepositResponse, Coupon, CouponResponse, CouponUsage, CreateBannerRequest, CreateCouponRequest, CreateFlashSaleRequest, CreateOrderEventRequest, CreateOrderEventResponse, CreateOrderRequest, CreateOrderResponse, CreateProductRequest, CreateProductVariantRequest, CreateReviewRequest, CreateShippingMethodRequest, CreateShippingRateRequest, CreateShippingZoneRequest, CreateTaxNexusRequest, CreateTaxRuleRequest, CustomerEcommerceClient, CustomerMessagesResponse, CustomerSummary, DeleteBrowsingLocationResponse, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, EcommerceClientConfig, ExpiringGemBatch, FlashSale, FlashSaleAllowanceInfo, FlashSaleItem, FlashSaleItemInput, FollowActionResponse, FollowStatusResponse, FollowedMerchantSummary, GemHistoryItem, GemHistoryType, GemHistoryTypeFilter, GemSource, GenerateTaxReportRequest, GetAnalyticsParams, GetAnalyticsResponse, GetBrowsingLocationResponse, GetCouponResponse, GetExpiringGemsParams, GetExpiringGemsResponse, GetFlashSaleAllowanceParams, GetFlashSaleAllowanceResponse, GetGemBalanceResponse, GetGemHistoryParams, GetGemHistoryResponse, GetOrderResponse, GetPaymentMethodsResponse, GetProductMetricsResponse, GetProductResponse, GetTaxReportResponse, InventoryAuditAction, InventoryAuditEntry, ListActiveBannersParams, ListActiveFlashSalesParams, ListBannersResponse, ListCouponsResponse, ListCustomersParams, ListCustomersResponse, ListFollowingParams, ListFollowingResponse, ListInventoryAuditResponse, ListMediaAssetsResponse, ListMerchantProductsParams, ListMessagesResponse, ListOrdersParams, ListOrdersResponse, ListProductVariantsResponse, ListProductsParams, ListProductsResponse, ListReturnsResponse, ListReviewsParams, ListReviewsResponse, ListShipmentsResponse, ListShippingAddressesResponse, ListShippingMethodsResponse, ListShippingRatesResponse, ListShippingZonesResponse, ListTaxNexusResponse, ListTaxReportsParams, ListTaxReportsResponse, ListTaxRulesResponse, MediaAsset, MediaAssetResponse, Merchant, MerchantEcommerceClient, MerchantProductsResponse, MerchantProfileRequest, MerchantProfileResponse, MerchantShippingSettings, MerchantStatus, Message, MessageResponse, MessageStatsResponse, Order, OrderEvent, OrderItem, OrderReceiptResponse, OrderStatus, OrdersByStatus, PaginatedResponse, PaginationParams, Payment, PaymentMethod, PaymentMethodInfo, PaymentStatus, ProcessPaymentRequest, ProcessPaymentResponse, Product, ProductDimensions, ProductDiscountsResponse, ProductMetrics, ProductResponse, ProductReview, ProductSortBy, ProductVariant, ProductVariantResponse, PublicMerchantProfile, PublicMerchantProfileResponse, RecentOrderSummary, RespondToReviewRequest, Return, ReturnItem, ReturnResponse, ReturnStatus, RevenueByDay, ReviewResponse, ReviewSortBy, ReviewStatus, SaveBrowsingLocationRequest, SaveBrowsingLocationResponse, SendMessageRequest, Settlement, Shipment, ShipmentResponse, ShipmentStatus, ShippingAddress, ShippingAddressRequest, ShippingAddressResponse, ShippingMethod, ShippingMethodResponse, ShippingOption, ShippingRate, ShippingRateResponse, ShippingSettingsResponse, ShippingZone, ShippingZoneResponse, SortOrder, SuccessResponse, TaxBehavior, TaxBreakdownItem, TaxNexus, TaxNexusResponse, TaxReport, TaxReportDetails, TaxReportPeriodType, TaxReportResponse, TaxReportStatus, TaxRule, TaxRuleResponse, TaxSettings, TaxSettingsResponse, TaxType, TopProduct, TrackBannerRequest, UpdateBannerRequest, UpdateCouponRequest, UpdateFlashSaleRequest, UpdateOrderResponse, UpdateOrderStatusRequest, UpdateProductRequest, UpdateProductVariantRequest, UpdateShipmentRequest, UpdateShippingMethodRequest, UpdateShippingRateRequest, UpdateShippingSettingsRequest, UpdateShippingZoneRequest, UpdateTaxNexusRequest, UpdateTaxReportStatusRequest, UpdateTaxRuleRequest, UpdateTaxSettingsRequest, UserShippingAddress, ValidateDiscountRequest, ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './ecommerce.js';
 import 'axios';
 
 declare function encodeSlug(slug: string): bigint;

package/dist/index.js

@@ -43187,6 +43187,35 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
     const queryString = params ? buildQueryString(params) : "";
     return this.get(`/api/marketplace/flash-sales/active${queryString}`);
   }
+  /**
+   * Get flash sale allowance
+   * 
+   * Fetches user's remaining purchase allowance for flash sale items.
+   * Used to enforce per-customer purchase limits.
+   * 
+   * @param params - Request params with product IDs
+   * @returns Allowance info for each product
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getFlashSaleAllowance({
+   *   productIds: ["prod_123", "prod_456"]
+   * });
+   * 
+   * Object.entries(result.allowances).forEach(([productId, info]) => {
+   *   if (info.limitPerCustomer !== null) {
+   *     console.log(`Product ${productId}:`);
+   *     console.log(`  Limit: ${info.limitPerCustomer} per customer`);
+   *     console.log(`  You've purchased: ${info.purchased}`);
+   *     console.log(`  You can buy: ${info.remaining} more`);
+   *   }
+   * });
+   * ```
+   */
+  async getFlashSaleAllowance(params) {
+    const queryString = buildQueryString({ productIds: params.productIds.join(",") });
+    return this.get(`/api/marketplace/flash-sales/allowance${queryString}`);
+  }
   // ============================================================================
   // Merchant Storefront API
   // ============================================================================
@@ -43324,6 +43353,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 +45158,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-P5C65GIG.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

@@ -22,9 +22,13 @@ import type {
   TrackBannerRequest,
   SendMessageRequest,
   ListActiveFlashSalesParams,
+  GetFlashSaleAllowanceParams,
   ListMerchantProductsParams,
   ListFollowingParams,
   CalculateShippingRequest,
+  GetGemHistoryParams,
+  GetExpiringGemsParams,
+  SaveBrowsingLocationRequest,
   
   // Response types
   ListProductsResponse,
@@ -48,6 +52,7 @@ import type {
   MessageStatsResponse,
   MessageResponse,
   ActiveFlashSalesResponse,
+  GetFlashSaleAllowanceResponse,
   GetPaymentMethodsResponse,
   PublicMerchantProfileResponse,
   MerchantProductsResponse,
@@ -55,6 +60,12 @@ import type {
   FollowActionResponse,
   ListFollowingResponse,
   CalculateShippingResponse,
+  GetGemBalanceResponse,
+  GetBrowsingLocationResponse,
+  SaveBrowsingLocationResponse,
+  DeleteBrowsingLocationResponse,
+  GetGemHistoryResponse,
+  GetExpiringGemsResponse,
 } from "../types";
 
 /**
@@ -675,6 +686,36 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
     const queryString = params ? buildQueryString(params) : "";
     return this.get(`/api/marketplace/flash-sales/active${queryString}`);
   }
+
+  /**
+   * Get flash sale allowance
+   * 
+   * Fetches user's remaining purchase allowance for flash sale items.
+   * Used to enforce per-customer purchase limits.
+   * 
+   * @param params - Request params with product IDs
+   * @returns Allowance info for each product
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getFlashSaleAllowance({
+   *   productIds: ["prod_123", "prod_456"]
+   * });
+   * 
+   * Object.entries(result.allowances).forEach(([productId, info]) => {
+   *   if (info.limitPerCustomer !== null) {
+   *     console.log(`Product ${productId}:`);
+   *     console.log(`  Limit: ${info.limitPerCustomer} per customer`);
+   *     console.log(`  You've purchased: ${info.purchased}`);
+   *     console.log(`  You can buy: ${info.remaining} more`);
+   *   }
+   * });
+   * ```
+   */
+  async getFlashSaleAllowance(params: GetFlashSaleAllowanceParams): Promise<GetFlashSaleAllowanceResponse> {
+    const queryString = buildQueryString({ productIds: params.productIds.join(",") });
+    return this.get(`/api/marketplace/flash-sales/allowance${queryString}`);
+  }
   
   // ============================================================================
   // Merchant Storefront API
@@ -825,5 +866,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;
 }
 
 /**
@@ -541,6 +547,15 @@ export interface ListActiveFlashSalesParams {
   merchantId?: string;
 }
 
+/**
+ * Get flash sale allowance request
+ * Get user's remaining purchase allowance for flash sale items
+ */
+export interface GetFlashSaleAllowanceParams {
+  /** Comma-separated list of product IDs */
+  productIds: string[];
+}
+
 /**
  * Flash sale item input
  */
@@ -700,3 +715,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;
+}
+