@thorprovider/types 3.7.0 → 3.9.0

package/publish.log

@@ -0,0 +1,60 @@
+npm warn Unknown project config "network-concurrency". This will stop working in the next major version of npm.
+npm warn publish npm auto-corrected some errors in your package.json when publishing.  Please run "npm pkg fix" to address these errors.
+npm warn publish errors corrected:
+npm warn publish "repository.url" was normalized to "git+https://github.com/thorprovider/thor-commerce.git"
+npm notice
+npm notice 📦  @thor/types@2.0.1
+npm notice Tarball Contents
+npm notice 277B AGENTS.md
+npm notice 1.6kB CHANGELOG.md
+npm notice 6.4kB README.md
+npm notice 101.2kB dist/index.d.mts
+npm notice 101.2kB dist/index.d.ts
+npm notice 3.2kB dist/index.js
+npm notice 14.3kB dist/index.js.map
+npm notice 1.9kB dist/index.mjs
+npm notice 14.2kB dist/index.mjs.map
+npm notice 832B package.json
+npm notice 724B src/admin/AdminUser.ts
+npm notice 946B src/admin/AuditLog.ts
+npm notice 2.0kB src/admin/DashboardConfig.ts
+npm notice 1.5kB src/admin/DashboardMetrics.ts
+npm notice 268B src/admin/index.ts
+npm notice 1.2kB src/admin/SiteConfigMetadata.ts
+npm notice 6.5kB src/auth.ts
+npm notice 2.8kB src/cart.ts
+npm notice 3.0kB src/category.ts
+npm notice 733B src/collection.ts
+npm notice 35.3kB src/commerce-provider.ts
+npm notice 2.1kB src/common.ts
+npm notice 4.6kB src/customer.ts
+npm notice 2.5kB src/designer-config.ts
+npm notice 7.3kB src/header-config.README.md
+npm notice 4.6kB src/header-config.ts
+npm notice 5.5kB src/index.ts
+npm notice 5.0kB src/order.ts
+npm notice 6.0kB src/payment.ts
+npm notice 10.7kB src/product.ts
+npm notice 3.8kB src/provider.ts
+npm notice 1.4kB src/region.ts
+npm notice 2.1kB src/site-config-labels.ts
+npm notice 3.0kB src/site-config.ts
+npm notice 1.3kB src/stock-location.ts
+npm notice 1.5kB src/storefront-config.ts
+npm notice 3.3kB src/storefront.ts
+npm notice 333B tsconfig.json
+npm notice 303B tsup.config.ts
+npm notice Tarball Details
+npm notice name: @thor/types
+npm notice version: 2.0.1
+npm notice filename: thor-types-2.0.1.tgz
+npm notice package size: 87.7 kB
+npm notice unpacked size: 365.5 kB
+npm notice shasum: 45a0c68b20d21a5446a471abb9077f2dd59cdd0d
+npm notice integrity: sha512-AJRNa0Gs1osFo[...]RLXmlsHuMfinQ==
+npm notice total files: 39
+npm notice
+npm notice Publishing to https://npm.pkg.github.com with tag latest and restricted access
+npm error code E401
+npm error 401 Unauthorized - PUT https://npm.pkg.github.com/@thor%2ftypes - unauthenticated: User cannot be authenticated with the token provided.
+npm error A complete log of this run can be found in: /home/nelson/.npm/_logs/2026-04-16T15_45_29_457Z-debug-0.log

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;
+}