@thorprovider/medusa-extended 1.0.0 → 1.1.0

package/src/dropshipper.ts

@@ -0,0 +1,1078 @@
+/**
+ * @fileoverview Dropshipper Client — Thor Commerce Extended
+ * @module @thorprovider/medusa-extended/dropshipper
+ *
+ * HTTP client for all `/admin/thor/dropshipper/` endpoints.
+ *
+ * Used by both:
+ *   - X (ThorProvider admin) — authenticated via admin JWT, role "Admin"
+ *   - Y (Dropshipper panel) — authenticated via dropshipper JWT, role "Dropshipper"
+ *
+ * Access control is enforced server-side via `withDropshipperScope` middleware.
+ * This client always sends `Authorization: Bearer <token>`.
+ *
+ * Endpoint reference: `dropshipping-api-contract.md`
+ */
+
+import type {
+  // Onboarding
+  OnboardDropshipperBody,
+  OnboardDropshipperResponse,
+  // Variant Costs
+  GetVariantCostsOptions,
+  GetVariantCostsResponse,
+  CreateVariantCostBody,
+  CreateVariantCostResponse,
+  BatchVariantCostsBody,
+  BatchVariantCostsResponse,
+  DeleteVariantCostResponse,
+  // Products & Prices
+  GetDropshipperProductsOptions,
+  GetDropshipperProductsResponse,
+  UpdateDropshipperPricesBody,
+  UpdateDropshipperPricesResponse,
+  // Orders
+  GetDropshipperOrdersOptions,
+  GetDropshipperOrdersResponse,
+  GetDropshipperOrderDetailResponse,
+  CreateDropshipperOrderBody,
+  CreateDropshipperOrderResponse,
+  SetPaymentCollectorBody,
+  SetPaymentCollectorResponse,
+  // Order Cancel & Edits
+  CancelDropshipperOrderResponse,
+  CreateOrderEditBody,
+  CreateOrderEditResponse,
+  AddOrderEditItemBody,
+  AddOrderEditItemResponse,
+  ConfirmOrderEditResponse,
+  // Order Notes
+  OrderNote,
+  CreateOrderNoteBody,
+  GetOrderNotesResponse,
+  DeleteOrderNoteResponse,
+  // Dropshipper Addresses
+  DropshipperAddressBody,
+  DropshipperAddressResponse,
+  GetDropshipperAddressesResponse,
+  // Categories
+  GetDropshipperCategoriesOptions,
+  GetDropshipperCategoriesResponse,
+  CreateDropshipperCategoryBody,
+  UpdateDropshipperCategoryBody,
+  DeleteDropshipperCategoryResponse,
+  CreateCategoryMappingBody,
+  CreateCategoryMappingResponse,
+  DeleteCategoryMappingResponse,
+  // Customers
+  GetDropshipperCustomersOptions,
+  GetDropshipperCustomersResponse,
+  GetDropshipperCustomerDetailResponse,
+  CreateDropshipperCustomerBody,
+  CreateDropshipperCustomerResponse,
+  // Account & Settlements (Y)
+  GetDropshipperAccountResponse,
+  GetDropshipperPayableResponse,
+  GetDropshipperReceivableResponse,
+  GetSettlementsOptions,
+  GetSettlementsResponse,
+  GetSettlementDetailResponse,
+  // Admin Settlements (X)
+  CreateSettlementBody,
+  CreateSettlementResponse,
+  ConfirmSettlementBody,
+  CancelSettlementBody,
+  UpdateSettlementStatusResponse,
+  // Admin Account Management (X)
+  GetAdminDropshipperAccountsResponse,
+  GetAdminAccountBalanceResponse,
+  GetAdminPriceListsResponse,
+  GetUserChannelResponse,
+  // Promotions
+  GetDropshipperPromotionsOptions,
+  GetDropshipperPromotionsResponse,
+  CreateDropshipperPromotionBody,
+  UpdateDropshipperPromotionBody,
+  DeleteDropshipperPromotionResponse,
+  // Dashboard
+  GetDashboardStatsOptions,
+  GetDashboardStatsResponse,
+  // Storefront (V)
+  GetStorefrontDropshipperCategoriesResponse,
+  // Inline return types
+  DropshipperCategory,
+  DropshipperPromotion,
+} from '@thorprovider/types';
+import { createLogger, ProviderAPIError } from '@thorprovider/adapters';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type FetchMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+
+/**
+ * Configuration required to instantiate the dropshipper client.
+ */
+export interface DropshipperClientConfig {
+  /** Medusa backend base URL */
+  baseUrl: string;
+  /**
+   * JWT token obtained from `POST /auth/user/emailpass`.
+   * Used as `Authorization: Bearer <token>`.
+   */
+  token: string;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// DropshipperClient
+// ---------------------------------------------------------------------------
+
+/**
+ * HTTP client for Thor Commerce dropshipping endpoints (`/admin/thor/dropshipper/`).
+ *
+ * All methods throw `ProviderAPIError` on non-2xx responses.
+ *
+ * @example
+ * ```typescript
+ * const client = new DropshipperClient({
+ *   baseUrl: process.env.MEDUSA_BACKEND_URL!,
+ *   token: jwtFromLogin,
+ * });
+ *
+ * // Y: list own products
+ * const { products } = await client.getProducts();
+ *
+ * // X: onboard a new dropshipper
+ * const { dropshipper } = await client.onboardDropshipper({ ... });
+ * ```
+ */
+export class DropshipperClient {
+  private baseUrl: string;
+  private token: string;
+  private logger: ReturnType<typeof createLogger>;
+
+  constructor(config: DropshipperClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, '');
+    this.token = config.token;
+    this.logger = createLogger('DropshipperClient', config.debug);
+  }
+
+  // -------------------------------------------------------------------------
+  // Private — HTTP helper
+  // -------------------------------------------------------------------------
+
+  private async request<T>(
+    method: FetchMethod,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    this.logger.debug(`[dropshipper] ${method} ${path}`);
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.token}`,
+      'Content-Type': 'application/json',
+    };
+
+    const init: RequestInit = {
+      method,
+      headers,
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    };
+
+    let response: Response;
+    try {
+      response = await fetch(url, init);
+    } catch (networkError: any) {
+      throw new ProviderAPIError(
+        `[dropshipper] Network error on ${method} ${path}: ${networkError.message}`,
+        'NETWORK_ERROR',
+        networkError,
+      );
+    }
+
+    if (!response.ok) {
+      let message = `HTTP ${response.status}`;
+      try {
+        const json = await response.json();
+        message = json?.message ?? message;
+      } catch {
+        // ignore parse errors
+      }
+      throw new ProviderAPIError(
+        `[dropshipper] ${method} ${path} failed: ${message}`,
+        `DROPSHIPPER_API_${response.status}`,
+        response.status,
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  // -------------------------------------------------------------------------
+  // Onboarding (Solo X)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Create a new dropshipper account (sales channel + user + price list).
+   *
+   * `POST /admin/thor/dropshipper/onboard`
+   */
+  async onboardDropshipper(
+    body: OnboardDropshipperBody,
+  ): Promise<OnboardDropshipperResponse> {
+    return this.request<OnboardDropshipperResponse>(
+      'POST',
+      '/admin/thor/dropshipper/onboard',
+      body,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Variant Costs (Solo X)
+  // -------------------------------------------------------------------------
+
+  /**
+   * List variant cost records, optionally filtered by account/variant/currency.
+   *
+   * `GET /admin/thor/dropshipper/variant-costs`
+   */
+  async getVariantCosts(
+    options: GetVariantCostsOptions = {},
+  ): Promise<GetVariantCostsResponse> {
+    const { account_id, variant_id, currency_code, limit = 20, offset = 0 } = options;
+    const qs = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset),
+      ...(account_id ? { account_id } : {}),
+      ...(variant_id ? { variant_id } : {}),
+      ...(currency_code ? { currency_code } : {}),
+    });
+    return this.request<GetVariantCostsResponse>(
+      'GET',
+      `/admin/thor/dropshipper/variant-costs?${qs}`,
+    );
+  }
+
+  /**
+   * Upsert a single variant cost record.
+   *
+   * `POST /admin/thor/dropshipper/variant-costs`
+   */
+  async createVariantCost(
+    body: CreateVariantCostBody,
+  ): Promise<CreateVariantCostResponse> {
+    return this.request<CreateVariantCostResponse>(
+      'POST',
+      '/admin/thor/dropshipper/variant-costs',
+      body,
+    );
+  }
+
+  /**
+   * Batch-upsert variant costs for a given account and currency.
+   *
+   * `POST /admin/thor/dropshipper/variant-costs/batch`
+   */
+  async batchVariantCosts(
+    body: BatchVariantCostsBody,
+  ): Promise<BatchVariantCostsResponse> {
+    return this.request<BatchVariantCostsResponse>(
+      'POST',
+      '/admin/thor/dropshipper/variant-costs/batch',
+      body,
+    );
+  }
+
+  /**
+   * Delete a variant cost record by ID.
+   *
+   * `DELETE /admin/thor/dropshipper/variant-costs/:id`
+   */
+  async deleteVariantCost(id: string): Promise<DeleteVariantCostResponse> {
+    return this.request<DeleteVariantCostResponse>(
+      'DELETE',
+      `/admin/thor/dropshipper/variant-costs/${id}`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Products (Solo Y)
+  // -------------------------------------------------------------------------
+
+  /**
+   * List products available in Y's channel with cost/margin data.
+   *
+   * `GET /admin/thor/dropshipper/products`
+   */
+  async getProducts(
+    options: GetDropshipperProductsOptions = {},
+  ): Promise<GetDropshipperProductsResponse> {
+    const { q, category_id, status, in_stock, limit = 20, offset = 0 } = options;
+    const qs = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset),
+      ...(q ? { q } : {}),
+      ...(category_id ? { category_id } : {}),
+      ...(status ? { status } : {}),
+      ...(in_stock !== undefined ? { in_stock: String(in_stock) } : {}),
+    });
+    return this.request<GetDropshipperProductsResponse>(
+      'GET',
+      `/admin/thor/dropshipper/products?${qs}`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Prices (Solo Y)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Bulk-update sale prices on Y's channel price list.
+   *
+   * `PUT /admin/thor/dropshipper/prices`
+   */
+  async updatePrices(
+    body: UpdateDropshipperPricesBody,
+  ): Promise<UpdateDropshipperPricesResponse> {
+    return this.request<UpdateDropshipperPricesResponse>(
+      'PUT',
+      '/admin/thor/dropshipper/prices',
+      body,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Orders (Y + X for set-payment-collector)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Paginated list of orders in Y's channel.
+   *
+   * `GET /admin/thor/dropshipper/orders`
+   */
+  async getOrders(
+    options: GetDropshipperOrdersOptions = {},
+  ): Promise<GetDropshipperOrdersResponse> {
+    const { status, payment_collector, settlement_status, from, to, q, limit = 20, offset = 0 } = options;
+    const qs = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset),
+      ...(status ? { status } : {}),
+      ...(payment_collector ? { payment_collector } : {}),
+      ...(settlement_status ? { settlement_status } : {}),
+      ...(from ? { from } : {}),
+      ...(to ? { to } : {}),
+      ...(q ? { q } : {}),
+    });
+    return this.request<GetDropshipperOrdersResponse>(
+      'GET',
+      `/admin/thor/dropshipper/orders?${qs}`,
+    );
+  }
+
+  /**
+   * Full detail for a single order with profit breakdown.
+   *
+   * `GET /admin/thor/dropshipper/orders/:id`
+   */
+  async getOrder(orderId: string): Promise<GetDropshipperOrderDetailResponse> {
+    return this.request<GetDropshipperOrderDetailResponse>(
+      'GET',
+      `/admin/thor/dropshipper/orders/${orderId}`,
+    );
+  }
+
+  /**
+   * Manually create an order on behalf of a customer.
+   *
+   * `POST /admin/thor/dropshipper/orders`
+   */
+  async createOrder(
+    body: CreateDropshipperOrderBody,
+  ): Promise<CreateDropshipperOrderResponse> {
+    return this.request<CreateDropshipperOrderResponse>(
+      'POST',
+      '/admin/thor/dropshipper/orders',
+      body,
+    );
+  }
+
+   /**
+    * Set who collects payment for an order (Solo X).
+    *
+    * `POST /admin/thor/dropshipper/orders/:id/set-payment-collector`
+    */
+   async setPaymentCollector(
+     orderId: string,
+     body: SetPaymentCollectorBody,
+   ): Promise<SetPaymentCollectorResponse> {
+     return this.request<SetPaymentCollectorResponse>(
+       'POST',
+       `/admin/thor/dropshipper/orders/${orderId}/set-payment-collector`,
+       body,
+    );
+    }
+
+  // -------------------------------------------------------------------------
+  // Order Cancel & Edits (Solo Y) — B-04
+  // -------------------------------------------------------------------------
+
+  /**
+   * Cancel a dropshipper order.
+   *
+   * `POST /admin/thor/dropshipper/orders/:id/cancel`
+   */
+  async cancelOrder(orderId: string): Promise<CancelDropshipperOrderResponse> {
+    return this.request<CancelDropshipperOrderResponse>(
+      'POST',
+      `/admin/thor/dropshipper/orders/${orderId}/cancel`,
+    );
+  }
+
+  /**
+   * Create an order edit for a dropshipper order.
+   *
+   * `POST /admin/thor/dropshipper/orders/:id/edit`
+   */
+  async createOrderEdit(
+    orderId: string,
+    body: CreateOrderEditBody = {},
+  ): Promise<CreateOrderEditResponse> {
+    return this.request<CreateOrderEditResponse>(
+      'POST',
+      `/admin/thor/dropshipper/orders/${orderId}/edit`,
+      body,
+    );
+  }
+
+  /**
+   * Add an item to the active order edit.
+   *
+   * `POST /admin/thor/dropshipper/orders/:id/edit/items`
+   */
+  async addOrderEditItem(
+    orderId: string,
+    body: AddOrderEditItemBody,
+  ): Promise<AddOrderEditItemResponse> {
+    return this.request<AddOrderEditItemResponse>(
+      'POST',
+      `/admin/thor/dropshipper/orders/${orderId}/edit/items`,
+      body,
+    );
+  }
+
+  /**
+   * Confirm the active order edit, applying changes to the order.
+   *
+   * `POST /admin/thor/dropshipper/orders/:id/edit/confirm`
+   */
+  async confirmOrderEdit(
+    orderId: string,
+  ): Promise<ConfirmOrderEditResponse> {
+    return this.request<ConfirmOrderEditResponse>(
+      'POST',
+      `/admin/thor/dropshipper/orders/${orderId}/edit/confirm`,
+    );
+  }
+
+    /**
+      * Get all notes for an order.
+   *
+   * `GET /admin/thor/dropshipper/orders/:id/notes`
+   */
+  async getOrderNotes(orderId: string): Promise<GetOrderNotesResponse> {
+    return this.request<GetOrderNotesResponse>(
+      'GET',
+      `/admin/thor/dropshipper/orders/${orderId}/notes`,
+    );
+  }
+
+  /**
+   * Create a new note for an order.
+   *
+   * `POST /admin/thor/dropshipper/orders/:id/notes`
+   */
+  async createOrderNote(
+    orderId: string,
+    body: CreateOrderNoteBody,
+  ): Promise<OrderNote> {
+    return this.request<OrderNote>(
+      'POST',
+      `/admin/thor/dropshipper/orders/${orderId}/notes`,
+      body,
+    );
+  }
+
+  /**
+   * Delete a note from an order.
+   *
+   * `DELETE /admin/thor/dropshipper/orders/:id/notes/:noteId`
+   */
+  async deleteOrderNote(
+    orderId: string,
+    noteId: string,
+  ): Promise<DeleteOrderNoteResponse> {
+    return this.request<DeleteOrderNoteResponse>(
+      'DELETE',
+      `/admin/thor/dropshipper/orders/${orderId}/notes/${noteId}`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Custom Categories (Solo Y)
+  // -------------------------------------------------------------------------
+
+  /**
+   * List Y's custom product categories.
+   *
+   * `GET /admin/thor/dropshipper/categories`
+   */
+  async getCategories(
+    options: GetDropshipperCategoriesOptions = {},
+  ): Promise<GetDropshipperCategoriesResponse> {
+    const { parent_id, include_children } = options;
+    const qs = new URLSearchParams({
+      ...(parent_id ? { parent_id } : {}),
+      ...(include_children !== undefined ? { include_children: String(include_children) } : {}),
+    });
+    const query = qs.toString() ? `?${qs}` : '';
+    return this.request<GetDropshipperCategoriesResponse>(
+      'GET',
+      `/admin/thor/dropshipper/categories${query}`,
+    );
+  }
+
+  /**
+   * Create a custom category in Y's channel.
+   *
+   * `POST /admin/thor/dropshipper/categories`
+   */
+  async createCategory(
+    body: CreateDropshipperCategoryBody,
+  ): Promise<DropshipperCategory> {
+    return this.request<DropshipperCategory>(
+      'POST',
+      '/admin/thor/dropshipper/categories',
+      body,
+    );
+  }
+
+  /**
+   * Update a custom category.
+   *
+   * `PUT /admin/thor/dropshipper/categories/:id`
+   */
+  async updateCategory(
+    categoryId: string,
+    body: UpdateDropshipperCategoryBody,
+  ): Promise<DropshipperCategory> {
+    return this.request<DropshipperCategory>(
+      'PUT',
+      `/admin/thor/dropshipper/categories/${categoryId}`,
+      body,
+    );
+  }
+
+  /**
+   * Delete a custom category.
+   *
+   * `DELETE /admin/thor/dropshipper/categories/:id`
+   */
+  async deleteCategory(
+    categoryId: string,
+  ): Promise<DeleteDropshipperCategoryResponse> {
+    return this.request<DeleteDropshipperCategoryResponse>(
+      'DELETE',
+      `/admin/thor/dropshipper/categories/${categoryId}`,
+    );
+  }
+
+  /**
+   * Map a product to a custom category.
+   *
+   * `POST /admin/thor/dropshipper/category-mappings`
+   */
+  async createCategoryMapping(
+    body: CreateCategoryMappingBody,
+  ): Promise<CreateCategoryMappingResponse> {
+    return this.request<CreateCategoryMappingResponse>(
+      'POST',
+      '/admin/thor/dropshipper/category-mappings',
+      body,
+    );
+  }
+
+  /**
+   * Remove a product-to-category mapping.
+   *
+   * `DELETE /admin/thor/dropshipper/category-mappings/:id`
+   */
+  async deleteCategoryMapping(
+    mappingId: string,
+  ): Promise<DeleteCategoryMappingResponse> {
+    return this.request<DeleteCategoryMappingResponse>(
+      'DELETE',
+      `/admin/thor/dropshipper/category-mappings/${mappingId}`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Customers (Solo Y)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Paginated list of customers in Y's channel.
+   *
+   * `GET /admin/thor/dropshipper/customers`
+   */
+  async getCustomers(
+    options: GetDropshipperCustomersOptions = {},
+  ): Promise<GetDropshipperCustomersResponse> {
+    const { q, has_orders, from, limit = 20, offset = 0 } = options;
+    const qs = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset),
+      ...(q ? { q } : {}),
+      ...(has_orders !== undefined ? { has_orders: String(has_orders) } : {}),
+      ...(from ? { from } : {}),
+    });
+    return this.request<GetDropshipperCustomersResponse>(
+      'GET',
+      `/admin/thor/dropshipper/customers?${qs}`,
+    );
+  }
+
+  /**
+   * Full detail for a single customer.
+   *
+   * `GET /admin/thor/dropshipper/customers/:id`
+   */
+  async getCustomer(
+    customerId: string,
+  ): Promise<GetDropshipperCustomerDetailResponse> {
+    return this.request<GetDropshipperCustomerDetailResponse>(
+      'GET',
+      `/admin/thor/dropshipper/customers/${customerId}`,
+    );
+  }
+
+  /**
+   * Create a customer scoped to Y's channel.
+   *
+   * `POST /admin/thor/dropshipper/customers`
+   */
+  async createCustomer(
+    body: CreateDropshipperCustomerBody,
+  ): Promise<CreateDropshipperCustomerResponse> {
+    return this.request<CreateDropshipperCustomerResponse>(
+      'POST',
+      '/admin/thor/dropshipper/customers',
+       body,
+     );
+    }
+
+  // -------------------------------------------------------------------------
+  // Customer Addresses (Solo Y) — B-06
+  // -------------------------------------------------------------------------
+
+  /**
+   * List addresses for a customer in Y's channel.
+   *
+   * `GET /admin/thor/dropshipper/customers/:id/addresses`
+   */
+  async getCustomerAddresses(
+    customerId: string,
+  ): Promise<GetDropshipperAddressesResponse> {
+    return this.request<GetDropshipperAddressesResponse>(
+      'GET',
+      `/admin/thor/dropshipper/customers/${customerId}/addresses`,
+    );
+  }
+
+  /**
+   * Create a new address for a customer.
+   *
+   * `POST /admin/thor/dropshipper/customers/:id/addresses`
+   */
+  async createCustomerAddress(
+    customerId: string,
+    body: DropshipperAddressBody,
+  ): Promise<DropshipperAddressResponse> {
+    return this.request<DropshipperAddressResponse>(
+      'POST',
+      `/admin/thor/dropshipper/customers/${customerId}/addresses`,
+      body,
+    );
+  }
+
+  /**
+   * Update an existing customer address.
+   *
+   * `PUT /admin/thor/dropshipper/customers/:id/addresses/:addressId`
+   */
+  async updateCustomerAddress(
+    customerId: string,
+    addressId: string,
+    body: Partial<DropshipperAddressBody>,
+  ): Promise<DropshipperAddressResponse> {
+    return this.request<DropshipperAddressResponse>(
+      'PUT',
+      `/admin/thor/dropshipper/customers/${customerId}/addresses/${addressId}`,
+      body,
+    );
+  }
+
+  /**
+   * Delete a customer address.
+   *
+   * `DELETE /admin/thor/dropshipper/customers/:id/addresses/:addressId`
+   */
+  async deleteCustomerAddress(
+    customerId: string,
+    addressId: string,
+  ): Promise<{ deleted: true; id: string }> {
+    return this.request<{ deleted: true; id: string }>(
+      'DELETE',
+      `/admin/thor/dropshipper/customers/${customerId}/addresses/${addressId}`,
+    );
+  }
+
+    // -------------------------------------------------------------------------
+    // Account & Settlements (Y read-only)
+    // -------------------------------------------------------------------------
+
+   /**
+    * Y's account info with current balance.
+    *
+    * `GET /admin/thor/dropshipper/account`
+    */
+   async getAccount(): Promise<GetDropshipperAccountResponse> {
+     return this.request<GetDropshipperAccountResponse>(
+       'GET',
+       '/admin/thor/dropshipper/account',
+     );
+   }
+
+   /**
+    * Orders where Y owes money to X (Y collected payment, needs to pay costs).
+    *
+    * `GET /admin/thor/dropshipper/account/payable`
+    */
+   async getPayable(): Promise<GetDropshipperPayableResponse> {
+     return this.request<GetDropshipperPayableResponse>(
+       'GET',
+       '/admin/thor/dropshipper/account/payable',
+     );
+   }
+
+   /**
+    * Orders where X owes money to Y (X collected COD, needs to transfer profit).
+    *
+    * `GET /admin/thor/dropshipper/account/receivable`
+    */
+   async getReceivable(): Promise<GetDropshipperReceivableResponse> {
+     return this.request<GetDropshipperReceivableResponse>(
+       'GET',
+       '/admin/thor/dropshipper/account/receivable',
+     );
+   }
+
+   /**
+    * List settlements (Y sees own; X can filter by account_id).
+    *
+    * `GET /admin/thor/dropshipper/settlements`
+    */
+   async getSettlements(
+     options: GetSettlementsOptions = {},
+   ): Promise<GetSettlementsResponse> {
+     const { status, type, account_id, limit = 20, offset = 0 } = options;
+     const qs = new URLSearchParams({
+       limit: String(limit),
+       offset: String(offset),
+       ...(status ? { status } : {}),
+       ...(type ? { type } : {}),
+       ...(account_id ? { account_id } : {}),
+     });
+     return this.request<GetSettlementsResponse>(
+       'GET',
+       `/admin/thor/dropshipper/settlements?${qs}`,
+     );
+   }
+
+   /**
+    * Full detail for a single settlement record.
+    *
+    * `GET /admin/thor/dropshipper/settlements/:id`
+    */
+   async getSettlement(
+     settlementId: string,
+   ): Promise<GetSettlementDetailResponse> {
+     return this.request<GetSettlementDetailResponse>(
+       'GET',
+       `/admin/thor/dropshipper/settlements/${settlementId}`,
+
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Admin Settlements (Solo X)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Create a settlement record for a dropshipper account.
+   *
+   * `POST /admin/thor/dropshipper/admin/settlements`
+   */
+  async createSettlement(
+    body: CreateSettlementBody,
+  ): Promise<CreateSettlementResponse> {
+    return this.request<CreateSettlementResponse>(
+      'POST',
+      '/admin/thor/dropshipper/admin/settlements',
+      body,
+    );
+  }
+
+  /**
+   * Confirm a pending settlement (marks it as paid/received).
+   *
+   * `POST /admin/thor/dropshipper/admin/settlements/:id/confirm`
+   */
+  async confirmSettlement(
+    settlementId: string,
+    body: ConfirmSettlementBody = {},
+  ): Promise<UpdateSettlementStatusResponse> {
+    return this.request<UpdateSettlementStatusResponse>(
+      'POST',
+      `/admin/thor/dropshipper/admin/settlements/${settlementId}/confirm`,
+      body,
+    );
+  }
+
+  /**
+   * Cancel a pending settlement.
+   *
+   * `POST /admin/thor/dropshipper/admin/settlements/:id/cancel`
+   */
+  async cancelSettlement(
+    settlementId: string,
+    body: CancelSettlementBody = {},
+  ): Promise<UpdateSettlementStatusResponse> {
+    return this.request<UpdateSettlementStatusResponse>(
+      'POST',
+      `/admin/thor/dropshipper/admin/settlements/${settlementId}/cancel`,
+      body,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Admin Settlements — list (Solo X)
+  // -------------------------------------------------------------------------
+
+  /**
+   * X views all settlement records across all dropshipper accounts.
+   *
+   * `GET /admin/thor/dropshipper/admin/settlements`
+   */
+  async getAdminSettlements(
+    options: GetSettlementsOptions = {},
+  ): Promise<GetSettlementsResponse> {
+    const { status, type, account_id, limit = 20, offset = 0 } = options;
+    const qs = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset),
+      ...(status ? { status } : {}),
+      ...(type ? { type } : {}),
+      ...(account_id ? { account_id } : {}),
+    });
+    return this.request<GetSettlementsResponse>(
+      'GET',
+      `/admin/thor/dropshipper/admin/settlements?${qs}`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Admin Account Management (Solo X)
+  // -------------------------------------------------------------------------
+
+  /**
+   * List all dropshipper accounts.
+   *
+   * `GET /admin/thor/dropshipper/admin/accounts`
+   */
+  async getAdminAccounts(): Promise<GetAdminDropshipperAccountsResponse> {
+    return this.request<GetAdminDropshipperAccountsResponse>(
+      'GET',
+      '/admin/thor/dropshipper/admin/accounts',
+    );
+  }
+
+  /**
+   * Full balance detail for a specific dropshipper account.
+   *
+   * `GET /admin/thor/dropshipper/admin/accounts/:id/balance`
+   */
+  async getAdminAccountBalance(
+    accountId: string,
+  ): Promise<GetAdminAccountBalanceResponse> {
+    return this.request<GetAdminAccountBalanceResponse>(
+      'GET',
+      `/admin/thor/dropshipper/admin/accounts/${accountId}/balance`,
+    );
+  }
+
+  /**
+   * List all dropshipper price lists.
+   *
+   * `GET /admin/thor/dropshipper/admin/price-lists`
+   */
+  async getAdminPriceLists(): Promise<GetAdminPriceListsResponse> {
+    return this.request<GetAdminPriceListsResponse>(
+      'GET',
+      '/admin/thor/dropshipper/admin/price-lists',
+    );
+  }
+
+  /**
+   * Utility: look up which sales channel a user belongs to.
+   *
+   * `GET /admin/thor/dropshipper/admin/user-channel`
+   */
+  async getUserChannel(): Promise<GetUserChannelResponse> {
+    return this.request<GetUserChannelResponse>(
+      'GET',
+      '/admin/thor/dropshipper/admin/user-channel',
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Promotions (Solo Y)
+  // -------------------------------------------------------------------------
+
+  /**
+   * List Y's promotions (discount codes).
+   *
+   * `GET /admin/thor/dropshipper/promotions`
+   */
+  async getPromotions(
+    options: GetDropshipperPromotionsOptions = {},
+  ): Promise<GetDropshipperPromotionsResponse> {
+    const { type, limit = 20, offset = 0 } = options;
+    const qs = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset),
+      ...(type ? { type } : {}),
+    });
+    return this.request<GetDropshipperPromotionsResponse>(
+      'GET',
+      `/admin/thor/dropshipper/promotions?${qs}`,
+    );
+  }
+
+  /**
+   * Create a promotion for Y's channel.
+   *
+   * `POST /admin/thor/dropshipper/promotions`
+   */
+  async createPromotion(
+    body: CreateDropshipperPromotionBody,
+  ): Promise<DropshipperPromotion> {
+    return this.request<DropshipperPromotion>(
+      'POST',
+      '/admin/thor/dropshipper/promotions',
+      body,
+    );
+  }
+
+  /**
+   * Get a single promotion by ID.
+   *
+   * `GET /admin/thor/dropshipper/promotions/:id`
+   */
+  async getPromotion(promotionId: string): Promise<DropshipperPromotion> {
+    return this.request<DropshipperPromotion>(
+      'GET',
+      `/admin/thor/dropshipper/promotions/${promotionId}`,
+    );
+  }
+
+  /**
+   * Update an existing promotion.
+   *
+   * `PUT /admin/thor/dropshipper/promotions/:id`
+   */
+  async updatePromotion(
+    promotionId: string,
+    body: UpdateDropshipperPromotionBody,
+  ): Promise<DropshipperPromotion> {
+    return this.request<DropshipperPromotion>(
+      'PUT',
+      `/admin/thor/dropshipper/promotions/${promotionId}`,
+      body,
+    );
+  }
+
+  /**
+   * Delete a promotion.
+   *
+   * `DELETE /admin/thor/dropshipper/promotions/:id`
+   */
+  async deletePromotion(
+    promotionId: string,
+  ): Promise<DeleteDropshipperPromotionResponse> {
+    return this.request<DeleteDropshipperPromotionResponse>(
+      'DELETE',
+      `/admin/thor/dropshipper/promotions/${promotionId}`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Dashboard (Solo Y)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Aggregate stats for Y's dashboard (revenue, profit, top products).
+   *
+   * `GET /admin/thor/dropshipper/dashboard/stats`
+   */
+  async getDashboardStats(
+    options: GetDashboardStatsOptions = {},
+  ): Promise<GetDashboardStatsResponse> {
+    const { period, from, to, currency_code } = options;
+    const qs = new URLSearchParams({
+      ...(period ? { period } : {}),
+      ...(from ? { from } : {}),
+      ...(to ? { to } : {}),
+      ...(currency_code ? { currency_code } : {}),
+    });
+    const query = qs.toString() ? `?${qs}` : '';
+    return this.request<GetDashboardStatsResponse>(
+      'GET',
+      `/admin/thor/dropshipper/dashboard/stats${query}`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Storefront (V — end customer, uses publishable API key)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Public endpoint: dropshipper-scoped categories for the storefront.
+   * Typically called with a publishable API key rather than a JWT.
+   *
+   * `GET /store/thor/dropshipper-categories`
+   */
+  async getStorefrontCategories(): Promise<GetStorefrontDropshipperCategoriesResponse> {
+    return this.request<GetStorefrontDropshipperCategoriesResponse>(
+      'GET',
+      '/store/thor/dropshipper-categories',
+    );
+  }
+}
+
+// Re-export types used by callers so they don't need to import from @thorprovider/types directly.
+export type { DropshipperCategory, DropshipperPromotion } from '@thorprovider/types';