@thorprovider/types 3.2.1 → 3.4.0

package/src/admin/MultiTenantAdmin.ts

@@ -0,0 +1,295 @@
+/**
+ * @thorprovider/types — Multi-Tenant Admin Types
+ *
+ * Type definitions for admin operations on the Thor Commerce multi-tenant
+ * backend plugin (`/admin/thor/`).
+ *
+ * These types map 1:1 to the API contract defined in
+ * `multitenant-api-contract.md`.
+ *
+ * @module admin/MultiTenantAdmin
+ */
+
+// ============================================================
+// Sales Channel — Customers
+// ============================================================
+
+/**
+ * A customer entry as returned by the admin multi-tenant API.
+ */
+export interface AdminChannelCustomer {
+  id: string;
+  email: string;
+  first_name: string | null;
+  last_name: string | null;
+  phone: string | null;
+  created_at: string;
+}
+
+/** Response for `GET /admin/thor/sales-channels/:id/customers` */
+export interface GetChannelCustomersResponse {
+  customers: AdminChannelCustomer[];
+  count: number;
+  limit: number;
+  offset: number;
+}
+
+/** Options for paginating channel customers */
+export interface GetChannelCustomersOptions {
+  /** Max customers to return (default 20, max 100) */
+  limit?: number;
+  /** Pagination offset (default 0) */
+  offset?: number;
+}
+
+// ============================================================
+// Sales Channel — API Keys
+// ============================================================
+
+/**
+ * A publishable API key entry as returned by the admin multi-tenant API.
+ */
+export interface AdminApiKey {
+  id: string;
+  title: string;
+  token: string;
+  type: 'publishable' | string;
+  created_at: string;
+}
+
+/** Response for `GET /admin/thor/sales-channels/:id/api-keys` */
+export interface GetChannelApiKeysResponse {
+  api_keys: AdminApiKey[];
+}
+
+// ============================================================
+// Sales Channel — Categories
+// ============================================================
+
+/**
+ * A product category entry as returned by admin channel category endpoints.
+ */
+export interface AdminChannelCategory {
+  id: string;
+  name: string;
+  handle: string;
+  description: string | null;
+  parent_category_id: string | null;
+  rank: number;
+  metadata: Record<string, unknown>;
+}
+
+/** Response for `GET /admin/thor/sales-channels/:id/categories` */
+export interface GetChannelCategoriesResponse {
+  categories: AdminChannelCategory[];
+  count: number;
+}
+
+/** Options for listing channel categories */
+export interface GetChannelCategoriesOptions {
+  /** Max categories per page (default 20, max 100) */
+  limit?: number;
+  /** Pagination offset (default 0) */
+  offset?: number;
+  /** Expand child categories in nested tree */
+  include_descendants?: boolean;
+}
+
+/**
+ * A slim sales channel reference returned when listing channels for a resource.
+ */
+export interface AdminSalesChannelRef {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+/** Response for `GET /admin/thor/categories/:id/sales-channels` */
+export interface GetCategorySalesChannelsResponse {
+  sales_channels: AdminSalesChannelRef[];
+}
+
+/** Body for `POST /admin/thor/categories/:id/sales-channels` */
+export interface AssignCategoriesToChannelsBody {
+  sales_channel_ids: string[];
+}
+
+/** Response for `POST /admin/thor/categories/:id/sales-channels` */
+export interface AssignCategoriesToChannelsResponse {
+  message: string;
+  linked: number;
+}
+
+/** Body for `DELETE /admin/thor/categories/:id/sales-channels` */
+export interface UnassignCategoriesFromChannelsBody {
+  sales_channel_ids: string[];
+}
+
+/** Response for `DELETE /admin/thor/categories/:id/sales-channels` */
+export interface UnassignCategoriesFromChannelsResponse {
+  message: string;
+  dismissed: number;
+}
+
+// ============================================================
+// Collections — Channel Mapping
+// ============================================================
+
+/** Response for `GET /admin/thor/collections/:id/sales-channels` */
+export interface GetCollectionSalesChannelsResponse {
+  sales_channels: AdminSalesChannelRef[];
+}
+
+/** Body for `POST /admin/thor/collections/:id/sales-channels` */
+export interface AssignCollectionsToChannelsBody {
+  sales_channel_ids: string[];
+}
+
+/** Response for `POST /admin/thor/collections/:id/sales-channels` */
+export interface AssignCollectionsToChannelsResponse {
+  message: string;
+  linked: number;
+}
+
+/** Body for `DELETE /admin/thor/collections/:id/sales-channels` */
+export interface UnassignCollectionsFromChannelsBody {
+  sales_channel_ids: string[];
+}
+
+/** Response for `DELETE /admin/thor/collections/:id/sales-channels` */
+export interface UnassignCollectionsFromChannelsResponse {
+  message: string;
+  dismissed: number;
+}
+
+// ============================================================
+// Storefront Config (Admin CRUD)
+// ============================================================
+
+/**
+ * SEO defaults as stored in the storefront config.
+ */
+export interface AdminStorefrontSeoDefaults {
+  title: string;
+  description: string;
+  ogImage?: string;
+}
+
+/**
+ * Full storefront config record as returned by admin endpoints.
+ * Uses snake_case to match the API contract response shape exactly.
+ */
+export interface AdminStorefrontConfig {
+  id: string;
+  sales_channel_id: string;
+  theme_accent_color: string;
+  logo_url: string;
+  currency_code: string;
+  seo_defaults: AdminStorefrontSeoDefaults;
+  frontend_webhook_url?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+/** Response for `GET /admin/thor/storefront-config/:id` */
+export interface GetAdminStorefrontConfigResponse {
+  storefront_config: AdminStorefrontConfig;
+}
+
+/** Body for `PUT /admin/thor/storefront-config/:id` */
+export interface UpdateStorefrontConfigBody {
+  theme_accent_color: string;
+  logo_url: string;
+  currency_code: string;
+  seo_defaults: {
+    title: string;
+    description: string;
+    ogImage?: string;
+  };
+  frontend_webhook_url?: string;
+}
+
+/** Response for `PUT /admin/thor/storefront-config/:id` */
+export interface UpdateStorefrontConfigResponse {
+  storefront_config: AdminStorefrontConfig;
+}
+
+// ============================================================
+// Site Designer Config (Admin CRUD + History + Restore)
+// ============================================================
+
+/**
+ * A single history entry for the Site Designer config.
+ */
+export interface AdminSiteConfigHistoryEntry {
+  id?: string;
+  version: string;
+  createdAt: string;
+  createdBy?: string;
+}
+
+/**
+ * Full site config record as returned by admin endpoints.
+ * `config` is the free-form `DesignerConfig` JSON object.
+ */
+export interface AdminSiteConfig {
+  id: string;
+  sales_channel_id: string;
+  version: string;
+  /** Free-form DesignerConfig object managed by the Site Designer */
+  config: Record<string, unknown>;
+  history?: AdminSiteConfigHistoryEntry[];
+  created_at?: string;
+  updated_at?: string;
+}
+
+/** Response for `GET /admin/thor/site-config/:sales_channel_id` */
+export interface GetAdminSiteConfigResponse {
+  site_config: AdminSiteConfig;
+}
+
+/** Body for `PUT /admin/thor/site-config/:sales_channel_id` */
+export type UpdateSiteConfigBody = Record<string, unknown>;
+
+/** Response for `PUT /admin/thor/site-config/:sales_channel_id` */
+export interface UpdateSiteConfigResponse {
+  site_config: AdminSiteConfig;
+}
+
+/**
+ * A full history entry including the stored config snapshot.
+ */
+export interface AdminSiteConfigHistoryEntryFull {
+  id: string;
+  version: string;
+  config: Record<string, unknown>;
+  createdAt: string;
+  createdBy?: string;
+}
+
+/** Response for `GET /admin/thor/site-config/:sales_channel_id/history` */
+export interface GetAdminSiteConfigHistoryResponse {
+  history: AdminSiteConfigHistoryEntryFull[];
+  count: number;
+}
+
+/** Options for paginating site config history */
+export interface GetAdminSiteConfigHistoryOptions {
+  limit?: number;
+  offset?: number;
+}
+
+/** Response for `POST /admin/thor/site-config/:sales_channel_id/restore/:version` */
+export interface RestoreSiteConfigResponse {
+  site_config: AdminSiteConfig;
+}
+
+// ============================================================
+// Channel Link — Store endpoints
+// ============================================================
+
+/** Response for `POST /store/thor/customers/me/channels` */
+export interface LinkCustomerToChannelResponse {
+  linked: boolean;
+  reason?: 'already_linked';
+}

package/src/admin/index.ts

@@ -11,3 +11,5 @@ export * from './AuditLog';
 export * from './DashboardConfig';
 export * from './DashboardMetrics';
 export * from './SiteConfigMetadata';
+export * from './MultiTenantAdmin';
+export * from './DropshippingAdmin';

package/src/commerce-provider.ts

@@ -740,6 +740,48 @@ export interface CommerceProvider {
    * ```
    */
   updateBillingAddress?(cartId: string, address: Address): Promise<Cart>;
+
+  /**
+   * Update the shipping address on a cart.
+   *
+   * Sets the customer's delivery address and email before proceeding to
+   * shipping method and payment selection.
+   *
+   * @param cartId - Cart ID
+   * @param address - Shipping address and contact details
+   * @throws {ProviderAPIError} If cart not found or address is invalid
+   *
+   * @example
+   * ```typescript
+   * await commerce.updateShippingAddress(cartId, {
+   *   email: 'customer@example.com',
+   *   firstName: 'Jane',
+   *   lastName: 'Doe',
+   *   address1: '123 Main St',
+   *   city: 'Madrid',
+   *   province: 'Madrid',
+   *   postalCode: '28001',
+   *   countryCode: 'ES',
+   *   phone: '+34 600 000 000',
+   * });
+   * ```
+   */
+  updateShippingAddress?(
+    cartId: string,
+    address: {
+      email: string;
+      firstName: string;
+      lastName: string;
+      address1: string;
+      address2?: string;
+      company?: string;
+      city: string;
+      province: string;
+      postalCode: string;
+      countryCode: string;
+      phone: string;
+    },
+  ): Promise<void>;
   
   // ============================================  // Customer Operations (Optional)
   // ============================================

package/src/index.ts

@@ -226,7 +226,147 @@ export type {
   AuditLogAdapter,
   SiteConfigMetadata,
   ConfigHistoryEntry,
-} from './admin';
+  // Multi-tenant admin types
+  AdminChannelCustomer,
+  GetChannelCustomersResponse,
+  GetChannelCustomersOptions,
+  AdminApiKey,
+  GetChannelApiKeysResponse,
+  AdminChannelCategory,
+  GetChannelCategoriesResponse,
+  GetChannelCategoriesOptions,
+  AdminSalesChannelRef,
+  GetCategorySalesChannelsResponse,
+  AssignCategoriesToChannelsBody,
+  AssignCategoriesToChannelsResponse,
+  UnassignCategoriesFromChannelsBody,
+  UnassignCategoriesFromChannelsResponse,
+  GetCollectionSalesChannelsResponse,
+  AssignCollectionsToChannelsBody,
+  AssignCollectionsToChannelsResponse,
+  UnassignCollectionsFromChannelsBody,
+  UnassignCollectionsFromChannelsResponse,
+  AdminStorefrontSeoDefaults,
+  AdminStorefrontConfig,
+  GetAdminStorefrontConfigResponse,
+  UpdateStorefrontConfigBody,
+  UpdateStorefrontConfigResponse,
+  AdminSiteConfigHistoryEntry,
+  AdminSiteConfig,
+  GetAdminSiteConfigResponse,
+  UpdateSiteConfigBody,
+  UpdateSiteConfigResponse,
+  AdminSiteConfigHistoryEntryFull,
+  GetAdminSiteConfigHistoryResponse,
+  GetAdminSiteConfigHistoryOptions,
+  RestoreSiteConfigResponse,
+  LinkCustomerToChannelResponse,
+  // Dropshipping types
+  DropshipperAccountRef,
+  OnboardDropshipperBody,
+  OnboardDropshipperResponse,
+  VariantCost,
+  GetVariantCostsOptions,
+  GetVariantCostsResponse,
+  CreateVariantCostBody,
+  CreateVariantCostResponse,
+  BatchVariantCostItem,
+  BatchVariantCostsBody,
+  BatchVariantCostsResponse,
+  DeleteVariantCostResponse,
+  DropshipperVariant,
+  DropshipperProduct,
+  GetDropshipperProductsOptions,
+  GetDropshipperProductsResponse,
+  DropshipperPriceItem,
+  UpdateDropshipperPricesBody,
+  UpdateDropshipperPricesResponse,
+  DropshipperOrderCustomer,
+  DropshipperOrder,
+  GetDropshipperOrdersOptions,
+  GetDropshipperOrdersResponse,
+  DropshipperOrderShippingAddress,
+  DropshipperOrderItem,
+  DropshipperOrderTotals,
+  DropshipperOrderTimelineEvent,
+  DropshipperOrderDetail,
+  GetDropshipperOrderDetailResponse,
+  CreateOrderItem,
+  CreateDropshipperOrderBody,
+  CreateDropshipperOrderResponse,
+  SetPaymentCollectorBody,
+  SetPaymentCollectorResponse,
+  DropshipperCategory,
+  GetDropshipperCategoriesOptions,
+  GetDropshipperCategoriesResponse,
+  CreateDropshipperCategoryBody,
+  UpdateDropshipperCategoryBody,
+  DeleteDropshipperCategoryResponse,
+  CreateCategoryMappingBody,
+  CreateCategoryMappingResponse,
+  DeleteCategoryMappingResponse,
+  DropshipperCustomer,
+  DropshipperCustomerStats,
+  DropshipperCustomerOrderRef,
+  DropshipperCustomerDetail,
+  GetDropshipperCustomersOptions,
+  GetDropshipperCustomersResponse,
+  GetDropshipperCustomerDetailResponse,
+  CreateDropshipperCustomerBody,
+  CreateDropshipperCustomerResponse,
+  DropshipperBalance,
+  DropshipperPendingOrders,
+  DropshipperAccount,
+  GetDropshipperAccountResponse,
+  DropshipperPayableOrder,
+  GetDropshipperPayableResponse,
+  DropshipperReceivableOrder,
+  GetDropshipperReceivableResponse,
+  SettlementRecord,
+  GetSettlementsOptions,
+  GetSettlementsResponse,
+  GetSettlementDetailResponse,
+  CreateSettlementBody,
+  CreateSettlementResponse,
+  ConfirmSettlementBody,
+  CancelSettlementBody,
+  UpdateSettlementStatusResponse,
+  AdminDropshipperAccount,
+  AdminDropshipperBalance,
+  GetAdminDropshipperAccountsResponse,
+  GetAdminAccountBalanceResponse,
+  GetAdminPriceListsResponse,
+  GetUserChannelResponse,
+  DropshipperPromotion,
+  GetDropshipperPromotionsOptions,
+  GetDropshipperPromotionsResponse,
+  PromotionRule,
+  CreateDropshipperPromotionBody,
+  UpdateDropshipperPromotionBody,
+   DeleteDropshipperPromotionResponse,
+   GetDashboardStatsOptions,
+   DashboardPeriodMetrics,
+   DashboardChanges,
+   DashboardTopProduct,
+   DashboardStats,
+   GetDashboardStatsResponse,
+   GetStorefrontDropshipperCategoriesResponse,
+   OrderNote,
+   CreateOrderNoteBody,
+   GetOrderNotesResponse,
+   DeleteOrderNoteResponse,
+   // Order cancel and edits
+   CancelDropshipperOrderResponse,
+   CreateOrderEditBody,
+   CreateOrderEditResponse,
+   AddOrderEditItemBody,
+   AddOrderEditItemResponse,
+   ConfirmOrderEditResponse,
+   // Dropshipper addresses (channel-scoped)
+   DropshipperAddressBody,
+   DropshipperAddressResponse,
+   GetDropshipperAddressesResponse,
+  } from './admin';
 
 // ============================================
 // Header Configuration Types