@thorprovider/types 3.3.0 → 3.4.1

package/src/admin/DropshippingAdmin.ts

@@ -0,0 +1,995 @@
+/**
+ * @thorprovider/types — Dropshipping Admin Types
+ *
+ * Type definitions for all dropshipping API operations on the Thor Commerce
+ * extended backend plugin (`/admin/thor/dropshipper/`).
+ *
+ * These types map 1:1 to the API contract defined in
+ * `dropshipping-api-contract.md`.
+ *
+ * Actors:
+ *   X = ThorProvider admin (role "Admin")
+ *   Y = Dropshipper (role "Dropshipper")
+ *   V = End customer (store)
+ *
+ * @module admin/DropshippingAdmin
+ */
+
+import type { Address } from '../customer';
+
+// ============================================================
+// Shared primitives
+// ============================================================
+
+/** Slim reference to a dropshipper account */
+export interface DropshipperAccountRef {
+  id: string;
+  provider_name: string;
+}
+
+// ============================================================
+// Onboarding (Solo X)
+// ============================================================
+
+/** Body for `POST /admin/thor/dropshipper/onboard` */
+export interface OnboardDropshipperBody {
+  /** Business name — used as SalesChannel name and DropshipperAccount.provider_name */
+  business_name: string;
+  /** Dropshipper user email. Must be unique in the system. */
+  email: string;
+  /** Initial password. Y should change it on first access. */
+  password: string;
+  /** Contact phone number */
+  phone?: string;
+  /** Name of the account contact person */
+  contact_name?: string;
+  /** Payment terms in days after delivery. Default: 15 */
+  payment_terms_days?: number;
+  /** Primary currency code. Default: "usd" */
+  currency_code?: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/onboard` */
+export interface OnboardDropshipperResponse {
+  dropshipper: {
+    user_id: string;
+    email: string;
+    sales_channel_id: string;
+    sales_channel_name: string;
+    account_id: string;
+    price_list_id: string;
+    /** Publishable API key token for the storefront */
+    publishable_key_token: string;
+    role: 'Dropshipper';
+  };
+}
+
+// ============================================================
+// Variant Costs (Solo X)
+// ============================================================
+
+/** A single variant cost record */
+export interface VariantCost {
+  id: string;
+  account_id: string;
+  variant_id: string;
+  variant_title?: string;
+  product_title?: string;
+  cost_amount: number;
+  currency_code: string;
+  created_at?: string;
+  updated_at: string;
+}
+
+/** Options for `GET /admin/thor/dropshipper/variant-costs` */
+export interface GetVariantCostsOptions {
+  /** Filter by dropshipper account */
+  account_id?: string;
+  variant_id?: string;
+  currency_code?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/variant-costs` */
+export interface GetVariantCostsResponse {
+  variant_costs: VariantCost[];
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+/** Body for `POST /admin/thor/dropshipper/variant-costs` (upsert) */
+export interface CreateVariantCostBody {
+  account_id: string;
+  variant_id: string;
+  cost_amount: number;
+  currency_code: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/variant-costs` */
+export interface CreateVariantCostResponse {
+  variant_cost: VariantCost;
+}
+
+/** Single item in a batch variant cost update */
+export interface BatchVariantCostItem {
+  variant_id: string;
+  cost_amount: number;
+}
+
+/** Body for `POST /admin/thor/dropshipper/variant-costs/batch` */
+export interface BatchVariantCostsBody {
+  account_id: string;
+  currency_code: string;
+  costs: BatchVariantCostItem[];
+}
+
+/** Response for `POST /admin/thor/dropshipper/variant-costs/batch` */
+export interface BatchVariantCostsResponse {
+  updated: number;
+  errors: unknown[];
+}
+
+/** Response for `DELETE /admin/thor/dropshipper/variant-costs/:id` */
+export interface DeleteVariantCostResponse {
+  deleted: true;
+  id: string;
+}
+
+// ============================================================
+// Products & Sale Prices (Solo Y)
+// ============================================================
+
+/** A product variant as seen by the dropshipper */
+export interface DropshipperVariant {
+  id: string;
+  title: string;
+  sku: string | null;
+  stock_quantity: number;
+  /** Price Y pays to X. Read-only for Y. */
+  cost_price: number;
+  cost_price_currency: string;
+  /** "custom" if from DropshipperVariantCost, "base_price" if fallback */
+  cost_price_source: 'custom' | 'base_price';
+  /** Price Y charges to V. From the channel's price list. */
+  sale_price: number;
+  sale_price_currency: string;
+  /** sale_price - cost_price (calculated by backend) */
+  margin: number;
+  /** (margin / sale_price) × 100 (calculated by backend) */
+  margin_percent: number;
+}
+
+/** A product as seen by the dropshipper */
+export interface DropshipperProduct {
+  id: string;
+  title: string;
+  thumbnail: string | null;
+  status: 'published' | 'draft' | string;
+  variants: DropshipperVariant[];
+}
+
+/** Options for `GET /admin/thor/dropshipper/products` */
+export interface GetDropshipperProductsOptions {
+  /** Search by product or variant title */
+  q?: string;
+  category_id?: string;
+  status?: 'published' | 'draft';
+  in_stock?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/products` */
+export interface GetDropshipperProductsResponse {
+  products: DropshipperProduct[];
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+/** Single price update item */
+export interface DropshipperPriceItem {
+  variant_id: string;
+  amount: number;
+}
+
+/** Body for `PUT /admin/thor/dropshipper/prices` */
+export interface UpdateDropshipperPricesBody {
+  currency_code: string;
+  prices: DropshipperPriceItem[];
+}
+
+/** Response for `PUT /admin/thor/dropshipper/prices` */
+export interface UpdateDropshipperPricesResponse {
+  updated: number;
+  price_list_id: string;
+}
+
+// ============================================================
+// Orders (Solo Y, except set-payment-collector which is Solo X)
+// ============================================================
+
+/** Slim customer reference on an order */
+export interface DropshipperOrderCustomer {
+  id: string;
+  full_name: string;
+  email: string;
+  phone?: string;
+}
+
+/** Slim order row as returned in list responses */
+export interface DropshipperOrder {
+  id: string;
+  display_id: number;
+  status: string;
+  fulfillment_status: string | null;
+  created_at: string;
+  customer: DropshipperOrderCustomer;
+  currency_code: string;
+  total: number;
+  profit: number;
+  margin_percent: number;
+  items_count: number;
+  payment_collected_by: 'dropshipper' | 'provider' | null;
+  settlement_status: 'settled' | 'unsettled';
+}
+
+/** Options for `GET /admin/thor/dropshipper/orders` */
+export interface GetDropshipperOrdersOptions {
+  status?: string;
+  payment_collector?: 'dropshipper' | 'provider';
+  settlement_status?: 'settled' | 'unsettled';
+  from?: string;
+  to?: string;
+  q?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/orders` */
+export interface GetDropshipperOrdersResponse {
+  orders: DropshipperOrder[];
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+/** A shipping address on an order */
+export interface DropshipperOrderShippingAddress {
+  full_name: string;
+  address_1: string;
+  city: string;
+  province: string | null;
+  postal_code: string;
+  country_code: string;
+}
+
+/** A line item with cost and profit breakdown */
+export interface DropshipperOrderItem {
+  id: string;
+  title: string;
+  variant_title: string;
+  sku: string | null;
+  quantity: number;
+  unit_price: number;
+  cost_price: number;
+  subtotal: number;
+  cost_subtotal: number;
+  profit: number;
+  thumbnail: string | null;
+}
+
+/** Order totals with profit breakdown */
+export interface DropshipperOrderTotals {
+  subtotal: number;
+  shipping_total: number;
+  discount_total: number;
+  total: number;
+  cost_total: number;
+  profit: number;
+  margin_percent: number;
+}
+
+/** Timeline event on an order */
+export interface DropshipperOrderTimelineEvent {
+  event: string;
+  timestamp: string;
+}
+
+/** Full order detail as returned by GET /admin/thor/dropshipper/orders/:id */
+export interface DropshipperOrderDetail {
+  id: string;
+  display_id: number;
+  status: string;
+  fulfillment_status: string | null;
+  created_at: string;
+  currency_code: string;
+  customer: DropshipperOrderCustomer & { phone?: string };
+  shipping_address: DropshipperOrderShippingAddress;
+  items: DropshipperOrderItem[];
+  totals: DropshipperOrderTotals;
+  payment_collected_by: 'dropshipper' | 'provider' | null;
+  settlement_status: 'settled' | 'unsettled';
+  timeline: DropshipperOrderTimelineEvent[];
+}
+
+/** Response for `GET /admin/thor/dropshipper/orders/:id` */
+export interface GetDropshipperOrderDetailResponse {
+  order: DropshipperOrderDetail;
+}
+
+/** A line item in a manual order creation */
+export interface CreateOrderItem {
+  variant_id: string;
+  quantity: number;
+}
+
+/** Body for `POST /admin/thor/dropshipper/orders` */
+export interface CreateDropshipperOrderBody {
+  customer_id: string;
+  currency_code: string;
+  items: CreateOrderItem[];
+  shipping_address: DropshipperOrderShippingAddress & { phone?: string };
+  shipping_method_id?: string;
+  notes?: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/orders` */
+export interface CreateDropshipperOrderResponse {
+  order: {
+    id: string;
+    display_id: number;
+    status: string;
+    total: number;
+    profit: number;
+    created_at: string;
+  };
+}
+
+/** Body for `POST /admin/thor/dropshipper/orders/:id/set-payment-collector` */
+export interface SetPaymentCollectorBody {
+  payment_collected_by: 'dropshipper' | 'provider';
+}
+
+/** Response for `POST /admin/thor/dropshipper/orders/:id/set-payment-collector` */
+export interface SetPaymentCollectorResponse {
+  order_id: string;
+  payment_collected_by: 'dropshipper' | 'provider';
+  updated_at: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/orders/:id/cancel` */
+export interface CancelDropshipperOrderResponse {
+  order: { id: string; status: string; [key: string]: unknown }
+}
+
+// ============================================================
+// Order Edits (Solo Y)
+// ============================================================
+
+/** Body for `POST /admin/thor/dropshipper/orders/:id/edits` */
+export interface CreateOrderEditBody {
+  internal_note?: string
+}
+
+/** Response for `POST /admin/thor/dropshipper/orders/:id/edits` */
+export interface CreateOrderEditResponse {
+  order_edit: { id: string; order_id: string; status: string; [key: string]: unknown }
+}
+
+/** Body for `POST /admin/thor/dropshipper/orders/:id/edits/:edit_id/items` */
+export interface AddOrderEditItemBody {
+  variant_id: string
+  quantity: number
+  unit_price?: number
+}
+
+/** Response for `POST /admin/thor/dropshipper/orders/:id/edits/:edit_id/items` */
+export interface AddOrderEditItemResponse {
+  order_edit: { id: string; [key: string]: unknown }
+}
+
+/** Response for `POST /admin/thor/dropshipper/orders/:id/edits/:edit_id/confirm` */
+export interface ConfirmOrderEditResponse {
+  order: { id: string; [key: string]: unknown }
+}
+
+// ============================================================
+// Custom Categories (Solo Y)
+// ============================================================
+
+/** A dropshipper custom category node */
+export interface DropshipperCategory {
+  id: string;
+  name: string;
+  handle: string;
+  description?: string | null;
+  position: number;
+  parent_id: string | null;
+  sales_channel_id?: string;
+  products_count?: number;
+  children?: DropshipperCategory[];
+  created_at?: string;
+  updated_at?: string;
+}
+
+/** Options for `GET /admin/thor/dropshipper/categories` */
+export interface GetDropshipperCategoriesOptions {
+  parent_id?: string;
+  include_children?: boolean;
+}
+
+/** Response for `GET /admin/thor/dropshipper/categories` */
+export interface GetDropshipperCategoriesResponse {
+  categories: DropshipperCategory[];
+}
+
+/** Body for `POST /admin/thor/dropshipper/categories` */
+export interface CreateDropshipperCategoryBody {
+  name: string;
+  /** Auto-generated from name if omitted. Must be unique within the channel. */
+  handle?: string;
+  description?: string;
+  parent_id?: string | null;
+  position?: number;
+}
+
+/** Body for `PUT /admin/thor/dropshipper/categories/:id` */
+export interface UpdateDropshipperCategoryBody {
+  name?: string;
+  description?: string;
+  handle?: string;
+  parent_id?: string | null;
+  position?: number;
+}
+
+/** Response for `DELETE /admin/thor/dropshipper/categories/:id` */
+export interface DeleteDropshipperCategoryResponse {
+  deleted: true;
+  id: string;
+  /** Number of products unmapped from the deleted category */
+  unmapped_products: number;
+}
+
+/** Body for `POST /admin/thor/dropshipper/category-mappings` */
+export interface CreateCategoryMappingBody {
+  category_id: string;
+  product_id: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/category-mappings` */
+export interface CreateCategoryMappingResponse {
+  mapping: {
+    id: string;
+    category_id: string;
+    product_id: string;
+    created_at: string;
+  };
+}
+
+/** Response for `DELETE /admin/thor/dropshipper/category-mappings/:id` */
+export interface DeleteCategoryMappingResponse {
+  deleted: true;
+  id: string;
+}
+
+// ============================================================
+// Customers (Solo Y)
+// ============================================================
+
+/** A customer as seen by the dropshipper (list view) */
+export interface DropshipperCustomer {
+  id: string;
+  first_name: string | null;
+  last_name: string | null;
+  email: string;
+  phone: string | null;
+  created_at: string;
+  total_orders: number;
+  total_spent: number;
+  currency_code: string;
+  last_order_at: string | null;
+}
+
+/** Stats on a customer as seen by the dropshipper */
+export interface DropshipperCustomerStats {
+  total_orders: number;
+  total_spent: number;
+  total_profit_generated: number;
+  avg_order_value: number;
+  currency_code: string;
+  first_order_at: string | null;
+  last_order_at: string | null;
+}
+
+/** Slim order reference for customer detail */
+export interface DropshipperCustomerOrderRef {
+  id: string;
+  display_id: number;
+  status: string;
+  total: number;
+  created_at: string;
+}
+
+/** Full customer detail as seen by the dropshipper */
+export interface DropshipperCustomerDetail {
+  id: string;
+  first_name: string | null;
+  last_name: string | null;
+  email: string;
+  phone: string | null;
+  created_at: string;
+  default_shipping_address?: DropshipperOrderShippingAddress | null;
+  stats: DropshipperCustomerStats;
+  recent_orders: DropshipperCustomerOrderRef[];
+}
+
+/** Options for `GET /admin/thor/dropshipper/customers` */
+export interface GetDropshipperCustomersOptions {
+  q?: string;
+  has_orders?: boolean;
+  from?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/customers` */
+export interface GetDropshipperCustomersResponse {
+  customers: DropshipperCustomer[];
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/customers/:id` */
+export interface GetDropshipperCustomerDetailResponse {
+  customer: DropshipperCustomerDetail;
+}
+
+/** Body for `POST /admin/thor/dropshipper/customers` */
+export interface CreateDropshipperCustomerBody {
+  first_name?: string;
+  last_name?: string;
+  email: string;
+  phone?: string;
+  password: string;
+  shipping_address?: {
+    address_1?: string;
+    city?: string;
+    province?: string;
+    postal_code?: string;
+    country_code?: string;
+  };
+}
+
+/** Response for `POST /admin/thor/dropshipper/customers` */
+export interface CreateDropshipperCustomerResponse {
+  customer: {
+    id: string;
+    email: string;
+    first_name: string | null;
+    last_name: string | null;
+    sales_channel_id: string;
+    created_at: string;
+  };
+}
+
+// ============================================================
+// Account & Settlements (Y read-only + X creates/confirms)
+// ============================================================
+
+/** Balance breakdown for a dropshipper account */
+export interface DropshipperBalance {
+  /** Sum of cost_price × qty for delivered orders where Y collected payment. Unsettled. */
+  payable_to_provider: number;
+  /** Sum of profit for delivered orders where X collected payment (COD). Unsettled. */
+  receivable_from_provider: number;
+  /** receivable - payable. Negative = Y owes X; positive = X owes Y. */
+  net_balance: number;
+  net_balance_label: string;
+}
+
+/** Pending order counts for a balance summary */
+export interface DropshipperPendingOrders {
+  payable_count: number;
+  payable_total: number;
+  receivable_count: number;
+  receivable_total: number;
+}
+
+/** Full account record as returned by `GET /admin/thor/dropshipper/account` */
+export interface DropshipperAccount {
+  id: string;
+  provider_name: string;
+  currency_code: string;
+  payment_terms_days: number;
+  balance: DropshipperBalance;
+  pending_orders: DropshipperPendingOrders;
+}
+
+/** Response for `GET /admin/thor/dropshipper/account` */
+export interface GetDropshipperAccountResponse {
+  account: DropshipperAccount;
+}
+
+/** A payable order row */
+export interface DropshipperPayableOrder {
+  id: string;
+  display_id: number;
+  fulfilled_at: string;
+  due_date: string;
+  customer_name: string;
+  sale_total: number;
+  cost_total: number;
+  amount_payable: number;
+  days_overdue: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/account/payable` */
+export interface GetDropshipperPayableResponse {
+  orders: DropshipperPayableOrder[];
+  total_payable: number;
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+/** A receivable order row */
+export interface DropshipperReceivableOrder {
+  id: string;
+  display_id: number;
+  fulfilled_at: string;
+  customer_name: string;
+  sale_total: number;
+  cost_total: number;
+  commission_amount: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/account/receivable` */
+export interface GetDropshipperReceivableResponse {
+  orders: DropshipperReceivableOrder[];
+  total_receivable: number;
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+/** A settlement record */
+export interface SettlementRecord {
+  id: string;
+  type: 'payment_to_provider' | 'commission_from_provider';
+  amount: number;
+  order_ids_count?: number;
+  status: 'pending' | 'confirmed' | 'cancelled';
+  notes?: string | null;
+  created_at: string;
+  settled_at: string | null;
+  confirmed_by: string | null;
+  account?: DropshipperAccountRef;
+  orders?: Array<{ id: string; display_id: number; fulfilled_at: string; cost_total: number }>;
+}
+
+/** Options for listing settlements */
+export interface GetSettlementsOptions {
+  status?: 'pending' | 'confirmed' | 'cancelled';
+  type?: 'payment_to_provider' | 'commission_from_provider';
+  account_id?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/settlements` */
+export interface GetSettlementsResponse {
+  settlements: SettlementRecord[];
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/settlements/:id` */
+export interface GetSettlementDetailResponse {
+  settlement: SettlementRecord;
+}
+
+/** Body for `POST /admin/thor/dropshipper/admin/settlements` (Solo X) */
+export interface CreateSettlementBody {
+  account_id: string;
+  type: 'payment_to_provider' | 'commission_from_provider';
+  order_ids: string[];
+  amount: number;
+  notes?: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/admin/settlements` */
+export interface CreateSettlementResponse {
+  settlement: SettlementRecord;
+}
+
+/** Body for `POST /admin/thor/dropshipper/admin/settlements/:id/confirm` */
+export interface ConfirmSettlementBody {
+  notes?: string;
+}
+
+/** Body for `POST /admin/thor/dropshipper/admin/settlements/:id/cancel` */
+export interface CancelSettlementBody {
+  reason?: string;
+}
+
+/** Response for confirm/cancel settlement */
+export interface UpdateSettlementStatusResponse {
+  settlement: SettlementRecord;
+}
+
+// ============================================================
+// Admin Account Management (Solo X)
+// ============================================================
+
+/** Full account record with channel info as seen by X */
+export interface AdminDropshipperAccount {
+  id: string;
+  provider_name: string;
+  provider_email?: string;
+  sales_channel_id: string;
+  sales_channel_name: string;
+  currency_code: string;
+  payment_terms_days: number;
+  created_at?: string;
+}
+
+/** Response for `GET /admin/thor/dropshipper/admin/accounts` */
+export interface GetAdminDropshipperAccountsResponse {
+  accounts: AdminDropshipperAccount[];
+}
+
+/** Extended balance for admin view of a specific account */
+export interface AdminDropshipperBalance extends DropshipperBalance {
+  payable_count: number;
+  payable_order_ids: string[];
+  payable_orders: DropshipperPayableOrder[];
+  receivable_count: number;
+  receivable_order_ids: string[];
+  receivable_orders: DropshipperReceivableOrder[];
+  unclassified_orders: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/admin/accounts/:id/balance` */
+export interface GetAdminAccountBalanceResponse {
+  account: Pick<AdminDropshipperAccount, 'id' | 'provider_name' | 'currency_code' | 'payment_terms_days' | 'sales_channel_id'>;
+  balance: AdminDropshipperBalance;
+}
+
+/** Response for `GET /admin/thor/dropshipper/admin/price-lists` */
+export interface GetAdminPriceListsResponse {
+  price_lists: Array<{
+    id: string;
+    sales_channel_id: string;
+    sales_channel_name: string;
+    provider_name: string;
+  }>;
+}
+
+/** Response for `GET /admin/thor/dropshipper/admin/user-channel` */
+export interface GetUserChannelResponse {
+  links: Array<{ sales_channel_id: string }>;
+}
+
+// ============================================================
+// Promotions (Solo Y)
+// ============================================================
+
+/** A dropshipper promotion record */
+export interface DropshipperPromotion {
+  id: string;
+  code: string;
+  /** Maps to application_method.type */
+  type: 'percentage' | 'fixed';
+  value: number;
+  status: 'active' | 'inactive' | string;
+  usage_limit: number | null;
+  usage_count: number;
+  starts_at: string | null;
+  ends_at: string | null;
+  target_type?: 'order' | 'items';
+  min_amount?: number | null;
+  currency_code?: string;
+}
+
+/** Options for `GET /admin/thor/dropshipper/promotions` */
+export interface GetDropshipperPromotionsOptions {
+  type?: 'percentage' | 'fixed';
+  limit?: number;
+  offset?: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/promotions` */
+export interface GetDropshipperPromotionsResponse {
+  promotions: DropshipperPromotion[];
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+/** An additional targeting rule for a promotion */
+export interface PromotionRule {
+  attribute: string;
+  operator: string;
+  values: string[];
+}
+
+/** Body for `POST /admin/thor/dropshipper/promotions` */
+export interface CreateDropshipperPromotionBody {
+  code: string;
+  type: 'percentage' | 'fixed';
+  value: number;
+  currency_code?: string;
+  target_type?: 'order' | 'items';
+  allocation?: 'each' | 'across';
+  usage_limit?: number | null;
+  starts_at?: string | null;
+  ends_at?: string | null;
+  rules?: PromotionRule[];
+}
+
+/** Body for `PUT /admin/thor/dropshipper/promotions/:id` */
+export interface UpdateDropshipperPromotionBody {
+  value?: number;
+  ends_at?: string | null;
+  usage_limit?: number | null;
+}
+
+/** Response for `DELETE /admin/thor/dropshipper/promotions/:id` */
+export interface DeleteDropshipperPromotionResponse {
+  deleted: true;
+  id: string;
+}
+
+// ============================================================
+// Dashboard & Stats (Solo Y)
+// ============================================================
+
+/** Options for `GET /admin/thor/dropshipper/dashboard/stats` */
+export interface GetDashboardStatsOptions {
+  period?: '7d' | '30d' | '90d' | 'custom';
+  /** Required when period = "custom" */
+  from?: string;
+  /** Required when period = "custom" */
+  to?: string;
+  currency_code?: string;
+}
+
+/** Core period metrics */
+export interface DashboardPeriodMetrics {
+  orders_count: number;
+  revenue_total: number;
+  profit_total: number;
+  avg_margin_percent: number;
+  avg_order_value: number;
+  customers_active?: number;
+  customers_new?: number;
+  currency_code: string;
+}
+
+/** Percentage changes vs. previous period */
+export interface DashboardChanges {
+  orders_count_pct: number;
+  revenue_total_pct: number;
+  profit_total_pct: number;
+  avg_margin_percent_pct: number;
+}
+
+/** Top product row by profit */
+export interface DashboardTopProduct {
+  product_id: string;
+  product_title: string;
+  variant_id: string;
+  variant_title: string;
+  units_sold: number;
+  revenue: number;
+  profit: number;
+  margin_percent: number;
+  thumbnail: string | null;
+}
+
+/** Full dashboard stats response */
+export interface DashboardStats {
+  period: {
+    from: string;
+    to: string;
+    label: string;
+  };
+  current: DashboardPeriodMetrics;
+  previous: DashboardPeriodMetrics;
+  changes: DashboardChanges;
+  orders_by_status: Record<string, number>;
+  settlement_summary: DropshipperBalance & {
+    pending_settlement_records: number;
+    currency_code: string;
+  };
+  recent_orders: Array<{
+    id: string;
+    display_id: number;
+    customer_name: string;
+    total: number;
+    profit: number;
+    status: string;
+    created_at: string;
+  }>;
+  top_products_by_profit: DashboardTopProduct[];
+}
+
+/** Response for `GET /admin/thor/dropshipper/dashboard/stats` */
+export interface GetDashboardStatsResponse {
+  stats?: DashboardStats;
+  // Some backends may return the stats object directly
+  [key: string]: unknown;
+}
+
+// ============================================================
+// Order Notes (Solo Y + Admin X can read)
+// ============================================================
+
+/** A note attached to an order */
+export interface OrderNote {
+  id: string;
+  order_id: string;
+  author_id: string;
+  text: string;
+  created_at: string;
+}
+
+/** Body for `POST /admin/thor/dropshipper/orders/:id/notes` */
+export interface CreateOrderNoteBody {
+  text: string;
+}
+
+/** Response for `GET /admin/thor/dropshipper/orders/:id/notes` */
+export interface GetOrderNotesResponse {
+  notes: OrderNote[];
+}
+
+/** Response for `DELETE /admin/thor/dropshipper/orders/:id/notes/:note_id` */
+export interface DeleteOrderNoteResponse {
+  id: string;
+  deleted: boolean;
+}
+
+// ============================================================
+// Dropshipper Addresses (Solo Y, scoped by channel)
+// ============================================================
+
+/** Body for creating/updating a dropshipper address */
+export interface DropshipperAddressBody {
+  first_name: string;
+  last_name: string;
+  company?: string;
+  address_1: string;
+  address_2?: string;
+  city: string;
+  province?: string;
+  postal_code: string;
+  country_code: string;
+  phone?: string;
+  is_default?: boolean;
+}
+
+/** Response for creating or updating a dropshipper address */
+export interface DropshipperAddressResponse {
+  address: Address;
+}
+
+/** Response for getting dropshipper addresses for a customer */
+export interface GetDropshipperAddressesResponse {
+  addresses: Address[];
+  count: number;
+}
+
+// ============================================================
+// Storefront (V — end customer, uses publishable API key)
+// ============================================================
+
+/** Response for `GET /store/thor/dropshipper-categories` */
+export interface GetStorefrontDropshipperCategoriesResponse {
+  categories: DropshipperCategory[];
+}