@thorprovider/types 3.7.0 → 3.8.0

package/src/admin/DropshippingAdmin.ts

@@ -313,6 +313,10 @@ export interface DropshipperShippingOption {
 export interface GetDropshipperShippingOptionsParams {
   currency_code: string;
   country_code?: string;
+  /** Province/state code for granular geo‑zone filtering */
+  province?: string;
+  /** City for granular geo‑zone filtering */
+  city?: string;
 }
 
 /** Response for `GET /admin/thor/dropshipper/orders/shipping-options` */
@@ -1133,3 +1137,628 @@ export interface GetDropshipperAddressesResponse {
 export interface GetStorefrontDropshipperCategoriesResponse {
   categories: DropshipperCategory[];
 }
+
+// ============================================================
+// Financial Endpoints — Group A (Endpoints 1-7)
+// ============================================================
+
+/** Settlement status values for orders */
+export type SettlementStatus =
+  | 'pending'
+  | 'partial'
+  | 'settled'
+  | 'guaranteed'
+  | 'refund_pending'
+  | 'compensated'
+  | 'recovery_pending'
+  | 'en_garantia'
+  | 'refunded';
+
+/** Financial movement types */
+export type FinancialMovementType =
+  | 'cobro'
+  | 'pago'
+  | 'ajuste'
+  | 'compensacion'
+  | 'devolucion'
+  | 'reverso'
+  | 'garantia';
+
+/** Financial movement statuses */
+export type FinancialMovementStatus =
+  | 'pendiente'
+  | 'confirmado'
+  | 'revertido'
+  | 'anulado';
+
+/** Impact direction of a financial movement */
+export type Impact =
+  | 'ds_debe_mas'
+  | 'ds_debe_menos'
+  | 'thor_debe_mas'
+  | 'thor_debe_menos'
+  | 'neutro';
+
+/** Ajuste subtype values */
+export type AjusteSubtype =
+  | 'bonificacion_comercial'
+  | 'penalizacion_general'
+  | 'credito_manual'
+  | 'debito_manual'
+  | 'correccion_saldo_inicial'
+  | 'error_migracion'
+  | 'compensacion_administrativa'
+  | 'aumento_comision'
+  | 'disminucion_comision'
+  | 'aumento_costo'
+  | 'disminucion_costo'
+  | 'diferencia_precio'
+  | 'penalizacion_orden'
+  | 'descuento_orden'
+  | 'ajuste_garantia'
+  | 'ajuste_devolucion'
+  | 'otro';
+
+/** Balance snapshot used in before/after projections */
+export interface BalanceSnapshot {
+  ds_debe: number;
+  thor_debe: number;
+  retenidos_total: number;
+  retenidos_thor: number;
+  retenidos_ds: number;
+  balance_neto: number;
+}
+
+/** An order applied to a financial movement */
+export interface OrderAppliedEntry {
+  order_id: string;
+  amount_applied: number;
+  display_id?: number | null;
+}
+
+/** An account adjustment paid within a financial movement */
+export interface AccountAdjustmentPaidEntry {
+  adjustment_id: string;
+  amount_applied: number;
+  side?: 'ds' | 'thor';
+}
+
+/** A full financial movement record */
+export interface FinancialMovement {
+  id: string;
+  reference: string;
+  type: FinancialMovementType;
+  subtype: string | null;
+  amount: number;
+  currency_code: string;
+  impact: Impact;
+  status: FinancialMovementStatus;
+  payment_method: string | null;
+  payment_reference: string | null;
+  orders_applied: OrderAppliedEntry[];
+  orders_applied_count: number;
+  account_adjustments_paid: AccountAdjustmentPaidEntry[];
+  adjustment_paid_amount: number;
+  adjustment_payment_status: string | null;
+  balance_before: BalanceSnapshot | null;
+  balance_after: BalanceSnapshot | null;
+  reason: string;
+  note: string | null;
+  created_by_admin_name: string;
+  confirmed_by_admin_name: string | null;
+  confirmed_at: string | null;
+  created_at: string;
+}
+
+/** An order entry in a compensation request */
+export interface CompensacionOrderEntry {
+  order_id: string;
+  amount_to_compensate: number;
+}
+
+/** An adjustment entry in a compensation request */
+export interface CompensacionAdjustmentEntry {
+  adjustment_id: string;
+  amount_to_compensate: number;
+}
+
+// ------------------------------------------------------------
+// 1. GET /admin/thor/dropshipper/account/balance
+// ------------------------------------------------------------
+
+/** Balance breakdown for the authenticated dropshipper */
+export interface DropshipperAccountBalance {
+  ds_debe: number;
+  ds_debe_orders_count: number;
+  thor_debe: number;
+  thor_debe_orders_count: number;
+  retenidos_total: number;
+  retenidos_thor: number;
+  retenidos_ds: number;
+  retenidos_orders_count: number;
+  balance_neto: number;
+  balance_direction: 'ds_debe' | 'thor_debe' | 'equilibrado';
+  currency_code: string;
+}
+
+/** Response for `GET /admin/thor/dropshipper/account/balance` */
+export interface GetDropshipperAccountBalanceResponse {
+  balance: DropshipperAccountBalance;
+  account: {
+    id: string;
+    provider_name: string;
+    payment_terms_days: number;
+  };
+}
+
+// ------------------------------------------------------------
+// 2. GET /admin/thor/dropshipper/account/orders
+// ------------------------------------------------------------
+
+/** A financial order row in the dropshipper's own view */
+export interface DropshipperFinancialOrder {
+  id: string;
+  display_id: number;
+  created_at: string;
+  customer_name: string | null;
+  quien_cobro: 'dropshipper' | 'provider' | null;
+  sale_total: number;
+  cost_total: number;
+  commission: number;
+  base_amount: number;
+  settled_amount: number;
+  pending_amount: number;
+  settlement_status: SettlementStatus;
+  retained_by: string | null;
+  due_date: string;
+  days_overdue: number;
+  is_overdue: boolean;
+  currency_code: string;
+}
+
+/** Options for `GET /admin/thor/dropshipper/account/orders` */
+export interface GetDropshipperAccountOrdersOptions {
+  tab?: 'all' | 'thor_cobro' | 'ds_cobro' | 'garantias';
+  status?: SettlementStatus;
+  limit?: number;
+  offset?: number;
+  q?: string;
+}
+
+/** Response for `GET /admin/thor/dropshipper/account/orders` */
+export interface GetDropshipperAccountOrdersResponse {
+  orders: DropshipperFinancialOrder[];
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+// ------------------------------------------------------------
+// 3. GET /admin/thor/dropshipper/admin/accounts/:id/orders
+// ------------------------------------------------------------
+
+/** A financial order row in the admin view (extends dropshipper view) */
+export interface AdminDropshipperFinancialOrder extends DropshipperFinancialOrder {
+  adjustment_applied_amount: number;
+  recovery_type: string | null;
+  recovery_amount: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/admin/accounts/:id/orders` */
+export interface GetAdminDropshipperAccountOrdersResponse {
+  orders: AdminDropshipperFinancialOrder[];
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+// ------------------------------------------------------------
+// 4. GET /admin/thor/dropshipper/admin/accounts/:id/settlements
+// ------------------------------------------------------------
+
+/** Options for `GET /admin/thor/dropshipper/admin/accounts/:id/settlements` */
+export interface GetAdminDropshipperAccountSettlementsOptions {
+  type?: FinancialMovementType;
+  status?: FinancialMovementStatus;
+  limit?: number;
+  offset?: number;
+}
+
+/** Response for `GET /admin/thor/dropshipper/admin/accounts/:id/settlements` */
+export interface GetAdminDropshipperAccountSettlementsResponse {
+  settlements: FinancialMovement[];
+  count: number;
+  offset: number;
+  limit: number;
+}
+
+// ------------------------------------------------------------
+// 5. POST /admin/thor/dropshipper/admin/accounts/:id/guarantee/:order_id
+// ------------------------------------------------------------
+
+/** Body for `POST /admin/thor/dropshipper/admin/accounts/:id/guarantee/:order_id` */
+export interface ResolveGuaranteeBody {
+  resolution: 'close' | 'close_with_refund';
+  amount?: number;
+  reason: string;
+  note?: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/admin/accounts/:id/guarantee/:order_id` */
+export interface ResolveGuaranteeResponse {
+  order_id: string;
+  status: SettlementStatus;
+  resolution: 'close' | 'close_with_refund';
+  financial_movement?: {
+    reference: string;
+    amount: number;
+    impact: Impact;
+    type: FinancialMovementType;
+  };
+  message: string;
+}
+
+// ------------------------------------------------------------
+// 6. POST /admin/thor/dropshipper/admin/accounts/:id/settlements/compensacion
+// ------------------------------------------------------------
+
+/** Body for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/compensacion` */
+export interface CreateCompensacionBody {
+  ds_orders: CompensacionOrderEntry[];
+  thor_orders: CompensacionOrderEntry[];
+  ds_adjustments?: CompensacionAdjustmentEntry[];
+  thor_adjustments?: CompensacionAdjustmentEntry[];
+  reason: string;
+  note?: string;
+}
+
+/** Compensation preview in the response */
+export interface CompensacionPreview {
+  before: BalanceSnapshot;
+  after: BalanceSnapshot;
+  total_ds: number;
+  total_thor: number;
+  monto_compensar: number;
+  compensation_type: 'total' | 'parcial';
+}
+
+/** Response for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/compensacion` */
+export interface CreateCompensacionResponse {
+  movement: {
+    id: string;
+    reference: string;
+    type: 'compensacion';
+    amount: number;
+    currency_code: string;
+    status: FinancialMovementStatus;
+    orders_applied: OrderAppliedEntry[];
+    reason: string;
+    created_at: string;
+  };
+  preview: CompensacionPreview;
+}
+
+// ------------------------------------------------------------
+// 7. POST /admin/thor/dropshipper/admin/accounts/:id/settlements/ajuste
+// ------------------------------------------------------------
+
+/** Body for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/ajuste` */
+export interface CreateAjusteBody {
+  subtype: AjusteSubtype;
+  impact: Impact;
+  amount: number;
+  reason: string;
+  note?: string;
+  evidence?: string[];
+  order_id?: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/ajuste` */
+export interface CreateAjusteResponse {
+  movement: {
+    id: string;
+    reference: string;
+    type: 'ajuste';
+    subtype: AjusteSubtype;
+    impact: Impact;
+    amount: number;
+    currency_code: string;
+    status: FinancialMovementStatus;
+    order_id: string | null;
+    reason: string;
+    created_at: string;
+  };
+  balance_before: BalanceSnapshot;
+  balance_after_projected: BalanceSnapshot;
+}
+
+// ============================================================
+// Financial Endpoints — Group B (Endpoints 8-14)
+// ============================================================
+
+/** Payment method for cobro/pago movements */
+export type PaymentMethod =
+  | 'transferencia'
+  | 'stripe'
+  | 'cheque'
+  | 'efectivo'
+  | 'otro';
+
+// ------------------------------------------------------------
+// 8. POST /admin/thor/dropshipper/admin/accounts/:id/settlements/cobro
+// ------------------------------------------------------------
+
+/** Body for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/cobro` */
+export interface CreateCobroBody {
+  orders_applied: OrderAppliedEntry[];
+  account_adjustments_paid?: AccountAdjustmentPaidEntry[];
+  payment_method: PaymentMethod;
+  payment_reference: string;
+  reason: string;
+  note?: string;
+  evidence?: string[];
+}
+
+/** Response for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/cobro` */
+export interface CreateCobroResponse {
+  movement: FinancialMovement;
+  balance_before: BalanceSnapshot;
+  balance_after_projected: BalanceSnapshot;
+}
+
+// ------------------------------------------------------------
+// 9. POST /admin/thor/dropshipper/admin/accounts/:id/settlements/pago
+// ------------------------------------------------------------
+
+/** Body for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/pago` */
+export interface CreatePagoBody {
+  orders_applied: OrderAppliedEntry[];
+  account_adjustments_paid?: AccountAdjustmentPaidEntry[];
+  payment_method: PaymentMethod;
+  payment_reference: string;
+  reason: string;
+  note?: string;
+  evidence?: string[];
+}
+
+/** Response for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/pago` */
+export interface CreatePagoResponse {
+  movement: FinancialMovement;
+  balance_before: BalanceSnapshot;
+  balance_after_projected: BalanceSnapshot;
+}
+
+// ------------------------------------------------------------
+// 10. POST /admin/thor/dropshipper/admin/accounts/:id/settlements/:mov_id/reverso
+// ------------------------------------------------------------
+
+/** Body for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/:mov_id/reverso` */
+export interface CreateReversoBody {
+  reversion_reason: string;
+  note?: string;
+}
+
+/** Reversal movement summary */
+export interface ReversoMovementSummary {
+  id: string;
+  reference: string;
+  type: 'reverso';
+  impact: Impact;
+  amount: number;
+  status: 'confirmado';
+  reverts_movement_id: string;
+  confirmed_at: string;
+}
+
+/** Original movement summary after reversal */
+export interface OriginalMovementSummary {
+  id: string;
+  reference: string;
+  type: FinancialMovementType;
+  status: 'revertido';
+  reverted_at: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/:mov_id/reverso` */
+export interface CreateReversoResponse {
+  reverso: ReversoMovementSummary;
+  original: OriginalMovementSummary;
+  balance_before: BalanceSnapshot;
+  balance_after: BalanceSnapshot;
+}
+
+// ------------------------------------------------------------
+// 11. POST /admin/thor/dropshipper/admin/accounts/:id/settlements/:mov_id/confirm
+// ------------------------------------------------------------
+
+/** Body for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/:mov_id/confirm` */
+export interface ConfirmMovementBody {
+  note?: string;
+}
+
+/** Confirmed movement summary */
+export interface ConfirmedMovementSummary {
+  id: string;
+  reference: string;
+  type: FinancialMovementType;
+  status: 'confirmado';
+  confirmed_at: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/:mov_id/confirm` */
+export interface ConfirmMovementResponse {
+  movement: ConfirmedMovementSummary;
+  balance_before: BalanceSnapshot;
+  balance_after: BalanceSnapshot;
+}
+
+// ------------------------------------------------------------
+// 12. POST /admin/thor/dropshipper/admin/accounts/:id/settlements/:mov_id/cancel
+// ------------------------------------------------------------
+
+/** Body for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/:mov_id/cancel` */
+export interface CancelMovementBody {
+  reason: string;
+}
+
+/** Cancelled movement summary */
+export interface CancelledMovementSummary {
+  id: string;
+  reference: string;
+  type: FinancialMovementType;
+  status: 'anulado';
+  reason: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/admin/accounts/:id/settlements/:mov_id/cancel` */
+export interface CancelMovementResponse {
+  movement: CancelledMovementSummary;
+}
+
+// ------------------------------------------------------------
+// 13. GET /admin/thor/dropshipper/admin/orders/:id/financial-analysis
+// ------------------------------------------------------------
+
+/** A single item in the financial analysis breakdown */
+export interface FinancialAnalysisItem {
+  id: string;
+  product_title: string;
+  variant_title: string;
+  variant_id: string;
+  sku: string | null;
+  quantity: number;
+  sale_price: number;
+  cost_thor: number;
+  commission: number;
+  margin: number;
+  margin_percent: number;
+  expected_cost_thor: number;
+  current_cost_thor: number;
+  expected_commission: number;
+  current_commission: number;
+  difference: number;
+  validation: string;
+}
+
+/** A settlement movement applied to an order in financial analysis */
+export interface FinancialAnalysisSettlementMovement {
+  movement_id: string;
+  reference: string;
+  type: FinancialMovementType;
+  impact: Impact;
+  amount_applied: number;
+  confirmed_at: string | null;
+  confirmed_by: string | null;
+}
+
+/** Settlement details within financial analysis */
+export interface FinancialAnalysisSettlementDetails {
+  settled_amount: number;
+  adjustment_applied_amount: number;
+  base_amount: number;
+  effective_settled: number;
+  movements: FinancialAnalysisSettlementMovement[];
+}
+
+/** Financial summary for an order */
+export interface FinancialAnalysisSummary {
+  ds_owes_to_thor: number;
+  thor_owes_to_ds: number;
+  total_sale: number;
+  total_cost_thor: number;
+  total_commission_ds: number;
+  total_margin: number;
+  total_margin_percent: number;
+}
+
+/** Dropshipper info within financial analysis */
+export interface FinancialAnalysisDropshipper {
+  account_id: string;
+  name: string;
+  payment_terms_days: number;
+}
+
+/** Full financial analysis for a single order */
+export interface FinancialAnalysis {
+  order_id: string;
+  display_id: number;
+  currency_code: string;
+  dropshipper: FinancialAnalysisDropshipper;
+  payment_collected_by: string | null;
+  settlement_status: SettlementStatus;
+  settlement_id: null;
+  summary: FinancialAnalysisSummary;
+  items: FinancialAnalysisItem[];
+  items_with_issues: number;
+  items_total: number;
+  settlement_details: FinancialAnalysisSettlementDetails;
+}
+
+/** Response for `GET /admin/thor/dropshipper/admin/orders/:id/financial-analysis` */
+export interface GetFinancialAnalysisResponse {
+  financial_analysis: FinancialAnalysis;
+}
+
+// ------------------------------------------------------------
+// 14. POST /admin/thor/dropshipper/orders/:id/payment
+// ------------------------------------------------------------
+
+/** Body for `POST /admin/thor/dropshipper/orders/:id/payment` */
+export interface RegisterPaymentBody {
+  paid_amount: number;
+  due_date?: string;
+  payment_provider_id?: string;
+  force_collector?: boolean;
+}
+
+/** Payment record in the register payment response */
+export interface RegisterPaymentRecord {
+  id: string;
+  amount: number;
+  provider_id: string;
+  status: string;
+  created_at: string;
+}
+
+/** Response for `POST /admin/thor/dropshipper/orders/:id/payment` */
+export interface RegisterPaymentResponse {
+  order_id: string;
+  payment: RegisterPaymentRecord;
+  paid_amount_total: number;
+  remaining: number;
+  payment_status: string;
+  payment_collected_by: string | null;
+  due_date: string | null;
+}
+
+// ============================================================
+// Dashboard Capabilities
+// ============================================================
+
+/**
+ * Flat boolean map telling the dropshipper dashboard which features
+ * the backend currently supports. Consumed via
+ * `GET /admin/thor/dropshipper/capabilities`.
+ */
+export interface DropshipperDashboardCapabilities {
+  /** Core navigation — always expected to be true */
+  dashboard: boolean;
+  orders: boolean;
+  products: boolean;
+  prices: boolean;
+  customers: boolean;
+  configuration: boolean;
+
+  /** Feature modules (may be disabled per-tenant or in development) */
+  financialSettlements: boolean;
+  promotions: boolean;
+  shipping: boolean;
+  reports: boolean;
+
+  /** Settings sub-pages (may be disabled per-tenant or in development) */
+  paymentSettings: boolean;
+  notifications: boolean;
+  security: boolean;
+  integrations: boolean;
+  team: boolean;
+}

package/src/index.ts

@@ -377,11 +377,41 @@ export type {
    AddOrderEditItemBody,
    AddOrderEditItemResponse,
    ConfirmOrderEditResponse,
-   // Dropshipper addresses (channel-scoped)
-   DropshipperAddressBody,
-   DropshipperAddressResponse,
-   GetDropshipperAddressesResponse,
-  } from './admin';
+    // Dropshipper addresses (channel-scoped)
+    DropshipperAddressBody,
+    DropshipperAddressResponse,
+    GetDropshipperAddressesResponse,
+     // Financial Endpoints — Group A
+     SettlementStatus,
+     GetDropshipperAccountBalanceResponse,
+     GetDropshipperAccountOrdersOptions,
+     GetDropshipperAccountOrdersResponse,
+     GetAdminDropshipperAccountOrdersResponse,
+     GetAdminDropshipperAccountSettlementsOptions,
+     GetAdminDropshipperAccountSettlementsResponse,
+     ResolveGuaranteeBody,
+     ResolveGuaranteeResponse,
+     CreateCompensacionBody,
+     CreateCompensacionResponse,
+     CreateAjusteBody,
+     CreateAjusteResponse,
+     // Financial Endpoints — Group B
+     CreateCobroBody,
+     CreateCobroResponse,
+     CreatePagoBody,
+     CreatePagoResponse,
+     CreateReversoBody,
+     CreateReversoResponse,
+     ConfirmMovementBody,
+     ConfirmMovementResponse,
+     CancelMovementBody,
+     CancelMovementResponse,
+     GetFinancialAnalysisResponse,
+     RegisterPaymentBody,
+     RegisterPaymentResponse,
+     // Dashboard Capabilities
+     DropshipperDashboardCapabilities,
+    } from './admin';
 
 // ============================================
 // Header Configuration Types