@basedone/core 0.2.2 → 0.2.4

package/lib/ecommerce/client/merchant.ts

@@ -37,6 +37,12 @@ import type {
   GetAnalyticsParams,
   RespondToReviewRequest,
   PaginationParams,
+  // Shipping request types
+  UpdateShippingSettingsRequest,
+  CreateShippingZoneRequest,
+  UpdateShippingZoneRequest,
+  CreateShippingRateRequest,
+  UpdateShippingRateRequest,
   
   // Response types
   MerchantProfileResponse,
@@ -79,6 +85,12 @@ import type {
   GetTaxReportResponse,
   TaxReportResponse,
   SuccessResponse,
+  // Shipping response types
+  ShippingSettingsResponse,
+  ListShippingZonesResponse,
+  ShippingZoneResponse,
+  ListShippingRatesResponse,
+  ShippingRateResponse,
 } from "../types";
 
 /**
@@ -691,6 +703,204 @@ export class MerchantEcommerceClient extends BaseEcommerceClient {
   async updateShipment(shipmentId: string, request: UpdateShipmentRequest): Promise<ShipmentResponse> {
     return this.patch(`/api/marketplace/merchant/shipping/shipments/${shipmentId}`, request);
   }
+
+  // ============================================================================
+  // Shipping Settings (Zones & Rates)
+  // ============================================================================
+
+  /**
+   * Get merchant shipping settings
+   * 
+   * @returns Shipping settings
+   * 
+   * @example
+   * ```typescript
+   * const { settings } = await client.getShippingSettings();
+   * console.log("Handling fee:", settings.defaultHandlingFee);
+   * ```
+   */
+  async getShippingSettings(): Promise<ShippingSettingsResponse> {
+    return this.get("/api/marketplace/merchant/shipping/settings");
+  }
+
+  /**
+   * Update merchant shipping settings
+   * 
+   * @param request - Settings to update
+   * @returns Updated settings
+   * 
+   * @example
+   * ```typescript
+   * await client.updateShippingSettings({
+   *   defaultHandlingFee: 2.50,
+   *   freeShippingEnabled: true,
+   *   freeShippingThreshold: 100
+   * });
+   * ```
+   */
+  async updateShippingSettings(request: UpdateShippingSettingsRequest): Promise<ShippingSettingsResponse> {
+    return this.post("/api/marketplace/merchant/shipping/settings", request);
+  }
+
+  /**
+   * List all shipping zones
+   * 
+   * @returns List of shipping zones with rate counts
+   * 
+   * @example
+   * ```typescript
+   * const { zones } = await client.listShippingZones();
+   * zones.forEach(z => console.log(z.name, z.countries.length, "countries"));
+   * ```
+   */
+  async listShippingZones(): Promise<ListShippingZonesResponse> {
+    return this.get("/api/marketplace/merchant/shipping/zones");
+  }
+
+  /**
+   * Get a shipping zone by ID
+   * 
+   * @param zoneId - Zone ID
+   * @returns Zone with rates
+   * 
+   * @example
+   * ```typescript
+   * const { zone } = await client.getShippingZone("zone_123");
+   * console.log(zone.name, zone.rates?.length, "rates");
+   * ```
+   */
+  async getShippingZone(zoneId: string): Promise<ShippingZoneResponse> {
+    return this.get(`/api/marketplace/merchant/shipping/zones/${zoneId}`);
+  }
+
+  /**
+   * Create a shipping zone
+   * 
+   * @param request - Zone data
+   * @returns Created zone
+   * 
+   * @example
+   * ```typescript
+   * const { zone } = await client.createShippingZone({
+   *   name: "Southeast Asia",
+   *   countries: ["SG", "MY", "TH", "ID", "PH", "VN"],
+   *   isDefault: false,
+   *   priority: 10
+   * });
+   * ```
+   */
+  async createShippingZone(request: CreateShippingZoneRequest): Promise<ShippingZoneResponse> {
+    return this.post("/api/marketplace/merchant/shipping/zones", request);
+  }
+
+  /**
+   * Update a shipping zone
+   * 
+   * @param zoneId - Zone ID
+   * @param request - Updated zone data
+   * @returns Updated zone
+   * 
+   * @example
+   * ```typescript
+   * await client.updateShippingZone("zone_123", {
+   *   countries: ["SG", "MY", "TH", "ID", "PH", "VN", "BN"]
+   * });
+   * ```
+   */
+  async updateShippingZone(zoneId: string, request: UpdateShippingZoneRequest): Promise<ShippingZoneResponse> {
+    return this.put(`/api/marketplace/merchant/shipping/zones/${zoneId}`, request);
+  }
+
+  /**
+   * Delete a shipping zone
+   * 
+   * @param zoneId - Zone ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteShippingZone("zone_123");
+   * ```
+   */
+  async deleteShippingZone(zoneId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/shipping/zones/${zoneId}`);
+  }
+
+  /**
+   * List shipping rates
+   * 
+   * @param zoneId - Optional zone ID to filter by
+   * @returns List of shipping rates
+   * 
+   * @example
+   * ```typescript
+   * // All rates
+   * const { rates } = await client.listShippingRates();
+   * 
+   * // Rates for a specific zone
+   * const { rates: zoneRates } = await client.listShippingRates("zone_123");
+   * ```
+   */
+  async listShippingRates(zoneId?: string): Promise<ListShippingRatesResponse> {
+    const query = zoneId ? `?zoneId=${zoneId}` : "";
+    return this.get(`/api/marketplace/merchant/shipping/rates${query}`);
+  }
+
+  /**
+   * Create a shipping rate
+   * 
+   * @param request - Rate data
+   * @returns Created rate
+   * 
+   * @example
+   * ```typescript
+   * const { rate } = await client.createShippingRate({
+   *   zoneId: "zone_123",
+   *   name: "Standard Shipping",
+   *   baseRate: 5.00,
+   *   perKgRate: 1.50,
+   *   minDeliveryDays: 7,
+   *   maxDeliveryDays: 14
+   * });
+   * ```
+   */
+  async createShippingRate(request: CreateShippingRateRequest): Promise<ShippingRateResponse> {
+    return this.post("/api/marketplace/merchant/shipping/rates", request);
+  }
+
+  /**
+   * Update a shipping rate
+   * 
+   * @param rateId - Rate ID
+   * @param request - Updated rate data
+   * @returns Updated rate
+   * 
+   * @example
+   * ```typescript
+   * await client.updateShippingRate("rate_123", {
+   *   baseRate: 6.00,
+   *   freeAboveAmount: 75
+   * });
+   * ```
+   */
+  async updateShippingRate(rateId: string, request: UpdateShippingRateRequest): Promise<ShippingRateResponse> {
+    return this.put(`/api/marketplace/merchant/shipping/rates/${rateId}`, request);
+  }
+
+  /**
+   * Delete a shipping rate
+   * 
+   * @param rateId - Rate ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteShippingRate("rate_123");
+   * ```
+   */
+  async deleteShippingRate(rateId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/shipping/rates/${rateId}`);
+  }
   
   // ============================================================================
   // Returns & Refunds
@@ -1337,5 +1547,578 @@ export class MerchantEcommerceClient extends BaseEcommerceClient {
   async exportTaxReport(reportId: string): Promise<string> {
     return this.get(`/api/marketplace/merchant/tax-reports/${reportId}/export`);
   }
+
+  // ============================================
+  // DROPSHIPPING APIs
+  // ============================================
+
+  /**
+   * List connected dropship suppliers
+   * 
+   * @returns Connected and available suppliers
+   * 
+   * @example
+   * ```typescript
+   * const { connected, available } = await client.listDropshipSuppliers();
+   * ```
+   */
+  async listDropshipSuppliers(): Promise<{
+    connected: DropshipSupplier[];
+    available: DropshipSupplierInfo[];
+  }> {
+    return this.get("/api/marketplace/merchant/dropship/suppliers");
+  }
+
+  /**
+   * Connect a new dropship supplier
+   * 
+   * @param request - Supplier credentials
+   * @returns Connected supplier
+   * 
+   * @example
+   * ```typescript
+   * const supplier = await client.connectDropshipSupplier({
+   *   code: "CJ_DROPSHIPPING",
+   *   apiKey: "your-api-key"
+   * });
+   * ```
+   */
+  async connectDropshipSupplier(request: ConnectDropshipSupplierRequest): Promise<{
+    supplier: DropshipSupplier;
+    message: string;
+  }> {
+    return this.post("/api/marketplace/merchant/dropship/suppliers", request);
+  }
+
+  /**
+   * Update dropship supplier settings
+   * 
+   * @param supplierId - Supplier ID
+   * @param request - Settings to update
+   * @returns Updated supplier
+   */
+  async updateDropshipSupplier(
+    supplierId: string,
+    request: UpdateDropshipSupplierRequest
+  ): Promise<{ supplier: DropshipSupplier }> {
+    return this.put(`/api/marketplace/merchant/dropship/suppliers/${supplierId}`, request);
+  }
+
+  /**
+   * Disconnect a dropship supplier
+   * 
+   * @param supplierId - Supplier ID
+   */
+  async disconnectDropshipSupplier(supplierId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/dropship/suppliers/${supplierId}`);
+  }
+
+  /**
+   * Search products from connected suppliers
+   * 
+   * @param request - Search parameters
+   * @returns Search results with pagination
+   * 
+   * @example
+   * ```typescript
+   * const results = await client.searchDropshipProducts({
+   *   supplierId: "supplier_123",
+   *   query: "wireless headphones",
+   *   limit: 20
+   * });
+   * ```
+   */
+  async searchDropshipProducts(request: SearchDropshipProductsRequest): Promise<{
+    products: SupplierProduct[];
+    pagination: { total: number; page: number; limit: number; hasMore: boolean };
+    supplier?: string;
+  }> {
+    return this.post("/api/marketplace/merchant/dropship/search", request);
+  }
+
+  /**
+   * Get dropship supplier categories
+   * 
+   * @param supplierId - Supplier ID
+   * @returns Category list
+   */
+  async getDropshipCategories(supplierId: string): Promise<{ categories: SupplierCategory[] }> {
+    return this.get(`/api/marketplace/merchant/dropship/categories?supplierId=${supplierId}`);
+  }
+
+  /**
+   * Get detailed product info from supplier
+   * 
+   * @param supplierId - Supplier ID
+   * @param externalProductId - Supplier's product ID
+   * @returns Product details with suggested pricing
+   */
+  async getDropshipProductDetails(
+    supplierId: string,
+    externalProductId: string
+  ): Promise<{
+    product: SupplierProduct;
+    suggestedPrice: number;
+    estimatedMargin: number;
+  }> {
+    return this.get(
+      `/api/marketplace/merchant/dropship/products/${encodeURIComponent(externalProductId)}?supplierId=${supplierId}`
+    );
+  }
+
+  /**
+   * Import a product from supplier to your store
+   * 
+   * @param request - Import parameters
+   * @returns Created product IDs
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.importDropshipProduct({
+   *   supplierId: "supplier_123",
+   *   externalProductId: "ext_product_456",
+   *   priceUSDC: 29.99,
+   *   title: "Custom Title"
+   * });
+   * ```
+   */
+  async importDropshipProduct(request: ImportDropshipProductRequest): Promise<{
+    success: boolean;
+    productId?: string;
+    dropshipProductId?: string;
+    error?: string;
+  }> {
+    return this.post("/api/marketplace/merchant/dropship/import", request);
+  }
+
+  /**
+   * Bulk import products from supplier
+   * 
+   * @param request - Bulk import parameters
+   * @returns Import results
+   */
+  async bulkImportDropshipProducts(request: BulkImportDropshipProductsRequest): Promise<{
+    success: boolean;
+    imported: number;
+    failed: number;
+    results: Array<{
+      externalProductId: string;
+      success: boolean;
+      productId?: string;
+      error?: string;
+    }>;
+  }> {
+    return this.post("/api/marketplace/merchant/dropship/import", request);
+  }
+
+  /**
+   * List imported dropship products
+   * 
+   * @param params - Filter parameters
+   * @returns Imported products list
+   */
+  async listDropshipProducts(params?: {
+    supplierId?: string;
+    isActive?: boolean;
+    limit?: number;
+    offset?: number;
+  }): Promise<{
+    items: DropshipProduct[];
+    pagination: { total: number; limit: number; offset: number; hasMore: boolean };
+  }> {
+    const query = params ? `?${buildQueryString(params)}` : "";
+    return this.get(`/api/marketplace/merchant/dropship/import${query}`);
+  }
+
+  /**
+   * List dropship order links
+   * 
+   * @param params - Filter parameters
+   * @returns Order links with status summary
+   */
+  async listDropshipOrders(params?: {
+    status?: string | string[];
+    limit?: number;
+    offset?: number;
+  }): Promise<{
+    items: DropshipOrderLink[];
+    pagination: { total: number; limit: number; offset: number; hasMore: boolean };
+    summary: {
+      pending: number;
+      forwarded: number;
+      processing: number;
+      shipped: number;
+      delivered: number;
+      failed: number;
+    };
+  }> {
+    let query = "";
+    if (params) {
+      const queryParams: Record<string, string> = {};
+      if (params.status) {
+        queryParams.status = Array.isArray(params.status) ? params.status.join(",") : params.status;
+      }
+      if (params.limit) queryParams.limit = params.limit.toString();
+      if (params.offset) queryParams.offset = params.offset.toString();
+      query = `?${buildQueryString(queryParams)}`;
+    }
+    return this.get(`/api/marketplace/merchant/dropship/orders${query}`);
+  }
+
+  /**
+   * Forward orders to supplier
+   * 
+   * @param orderItemIds - Order item IDs to forward
+   * @returns Forward results
+   */
+  async forwardDropshipOrders(orderItemIds: string[]): Promise<{
+    success: boolean;
+    forwarded: number;
+    failed: number;
+    results: Array<{
+      orderItemId: string;
+      success: boolean;
+      externalOrderId?: string;
+      error?: string;
+    }>;
+  }> {
+    return this.post("/api/marketplace/merchant/dropship/orders", {
+      action: "forward",
+      orderItemIds,
+    });
+  }
+
+  /**
+   * Sync tracking for all pending dropship orders
+   * 
+   * @returns Sync results
+   */
+  async syncDropshipTracking(): Promise<{
+    success: boolean;
+    total: number;
+    synced: number;
+    updated: number;
+    failed: number;
+  }> {
+    return this.post("/api/marketplace/merchant/dropship/orders", {
+      action: "sync",
+    });
+  }
+
+  /**
+   * Get order forwarding details for manual forwarding
+   * 
+   * @param orderItemId - Order item ID
+   * @returns Forwarding details
+   */
+  async getDropshipOrderDetails(orderItemId: string): Promise<{
+    details: {
+      orderId: string;
+      orderItemId: string;
+      productTitle: string;
+      quantity: number;
+      supplierName: string;
+      supplierProductId: string;
+      supplierPrice: number;
+      shippingAddress: ShippingAddress;
+      estimatedCost: number;
+      status: string;
+    };
+  }> {
+    return this.get(`/api/marketplace/merchant/dropship/orders/${orderItemId}/forward`);
+  }
+
+  /**
+   * Forward a single order item to supplier
+   * 
+   * @param orderItemId - Order item ID
+   * @returns Forward result
+   */
+  async forwardDropshipOrder(orderItemId: string): Promise<{
+    success: boolean;
+    dropshipOrderLinkId?: string;
+    externalOrderId?: string;
+    error?: string;
+  }> {
+    return this.post(`/api/marketplace/merchant/dropship/orders/${orderItemId}/forward`, {});
+  }
+
+  /**
+   * Get dropship settings
+   * 
+   * @returns Merchant dropship settings
+   */
+  async getDropshipSettings(): Promise<{ settings: DropshipMerchantSettings }> {
+    return this.get("/api/marketplace/merchant/dropship/settings");
+  }
+
+  /**
+   * Update dropship settings
+   * 
+   * @param request - Settings to update
+   * @returns Updated settings
+   */
+  async updateDropshipSettings(request: UpdateDropshipSettingsRequest): Promise<{
+    settings: DropshipMerchantSettings;
+  }> {
+    return this.put("/api/marketplace/merchant/dropship/settings", request);
+  }
+
+  /**
+   * Sync dropship products and/or orders
+   * 
+   * @param type - Sync type (products, orders, all, single)
+   * @param dropshipProductId - For single product sync
+   * @returns Sync results
+   */
+  async syncDropship(
+    type: "products" | "orders" | "all" | "single",
+    dropshipProductId?: string
+  ): Promise<{
+    success: boolean;
+    type: string;
+    results: {
+      products?: { total: number; synced: number; failed: number };
+      orders?: { total: number; synced: number; updated: number; failed: number };
+      product?: { success: boolean; updated: boolean; error?: string };
+    };
+  }> {
+    return this.post("/api/marketplace/merchant/dropship/sync", {
+      type,
+      dropshipProductId,
+    });
+  }
+}
+
+// ============================================
+// DROPSHIPPING TYPES
+// ============================================
+
+export interface DropshipSupplier {
+  id: string;
+  code: string;
+  name: string;
+  isActive: boolean;
+  autoForward: boolean;
+  settings?: Record<string, any>;
+  createdAt: string;
+}
+
+export interface DropshipSupplierInfo {
+  code: string;
+  name: string;
+  description: string;
+  features: string[];
+  isConnected: boolean;
+}
+
+export interface ConnectDropshipSupplierRequest {
+  code: string;
+  apiKey?: string;
+  apiSecret?: string;
+  accessToken?: string;
+}
+
+export interface UpdateDropshipSupplierRequest {
+  autoForward?: boolean;
+  settings?: Record<string, any>;
+  apiKey?: string;
+  apiSecret?: string;
+  accessToken?: string;
+}
+
+export interface SearchDropshipProductsRequest {
+  supplierId?: string;
+  supplierCode?: string;
+  query?: string;
+  category?: string;
+  minPrice?: number;
+  maxPrice?: number;
+  page?: number;
+  limit?: number;
+  sortBy?: "price_asc" | "price_desc" | "rating" | "orders" | "newest";
+}
+
+export interface SupplierProduct {
+  externalProductId: string;
+  externalUrl?: string;
+  externalSku?: string;
+  title: string;
+  description: string;
+  images: string[];
+  price: number;
+  currency: string;
+  shippingCost?: number;
+  processingDays?: number;
+  shippingDays?: number;
+  warehouseLocation?: string;
+  category?: string;
+  variants?: SupplierProductVariant[];
+  rating?: number;
+  reviewCount?: number;
+  minOrderQuantity?: number;
+  inventory?: number;
+}
+
+export interface SupplierProductVariant {
+  externalVariantId: string;
+  name: string;
+  sku?: string;
+  price: number;
+  inventory?: number;
+  attributes: Record<string, string>;
+  image?: string;
+}
+
+export interface SupplierCategory {
+  id: string;
+  name: string;
+  parentId?: string;
+  children?: SupplierCategory[];
+}
+
+export interface ImportDropshipProductRequest {
+  supplierId: string;
+  externalProductId: string;
+  priceUSDC: number;
+  compareAtPrice?: number;
+  title?: string;
+  richDescription?: string;
+  category?: string;
+  categoryId?: string;
+  tags?: string[];
+  isActive?: boolean;
+}
+
+export interface BulkImportDropshipProductsRequest {
+  supplierId: string;
+  products: Array<{
+    externalProductId: string;
+    priceUSDC: number;
+    compareAtPrice?: number;
+    title?: string;
+    category?: string;
+    categoryId?: string;
+  }>;
+}
+
+export interface DropshipProduct {
+  id: string;
+  supplierId: string;
+  externalProductId: string;
+  externalUrl?: string;
+  supplierPrice: string;
+  supplierCurrency: string;
+  shippingCost?: string;
+  processingDays?: number;
+  shippingDays?: number;
+  warehouseLocation?: string;
+  productSnapshot: any;
+  lastSyncedAt?: string;
+  syncError?: string;
+  localProductId?: string;
+  localProduct?: {
+    id: string;
+    title: string;
+    priceUSDC: string;
+    images: string[];
+    isActive: boolean;
+    inventory?: number;
+    soldCount: number;
+  };
+  supplier?: {
+    id: string;
+    name: string;
+    code: string;
+  };
+  isActive: boolean;
+  createdAt: string;
+}
+
+export interface DropshipOrderLink {
+  id: string;
+  orderId: string;
+  orderItemId: string;
+  supplierId: string;
+  dropshipProductId?: string;
+  externalOrderId?: string;
+  externalStatus?: string;
+  status: string;
+  forwardedAt?: string;
+  processedAt?: string;
+  shippedAt?: string;
+  deliveredAt?: string;
+  trackingNumber?: string;
+  trackingUrl?: string;
+  carrier?: string;
+  supplierCost?: string;
+  shippingCost?: string;
+  lastError?: string;
+  order?: {
+    id: string;
+    status: string;
+    totalUSDC: string;
+    shippingAddress: any;
+    createdAt: string;
+  };
+  orderItem?: {
+    id: string;
+    titleSnapshot: string;
+    quantity: number;
+    unitPriceUSDC: string;
+  };
+  supplier?: {
+    id: string;
+    name: string;
+    code: string;
+  };
+  createdAt: string;
+}
+
+export interface DropshipMerchantSettings {
+  merchantId: string;
+  defaultMarkupType: string;
+  defaultMarkupValue: string;
+  roundPriceTo?: string;
+  autoForwardOrders: boolean;
+  autoSyncTracking: boolean;
+  syncIntervalMinutes: number;
+  autoSyncInventory: boolean;
+  lowStockThreshold: number;
+  outOfStockBehavior: string;
+  defaultShippingMethod?: string;
+  freeShippingThreshold?: string;
+  notifyOnNewOrder: boolean;
+  notifyOnLowStock: boolean;
+  notifyOnShipment: boolean;
+}
+
+export interface UpdateDropshipSettingsRequest {
+  defaultMarkupType?: string;
+  defaultMarkupValue?: number;
+  roundPriceTo?: number | null;
+  autoForwardOrders?: boolean;
+  autoSyncTracking?: boolean;
+  syncIntervalMinutes?: number;
+  autoSyncInventory?: boolean;
+  lowStockThreshold?: number;
+  outOfStockBehavior?: string;
+  defaultShippingMethod?: string | null;
+  freeShippingThreshold?: number | null;
+  notifyOnNewOrder?: boolean;
+  notifyOnLowStock?: boolean;
+  notifyOnShipment?: boolean;
+}
+
+interface ShippingAddress {
+  fullName: string;
+  phone: string;
+  email?: string;
+  addressLine1: string;
+  addressLine2?: string;
+  city: string;
+  state?: string;
+  postalCode: string;
+  country: string;
 }