Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

230 KB
Raw Blame
import type {
  AuthProvidersResponse,
  EmailPasswordLogin,
  FileUploadCreateParams,
  ListParams,
  LoginCredentials,
  PaginatedResponse,
  PaginationMeta,
  PreferenceSchema,
  ProviderLogin,
  RequestFn,
  RequestOptions,
  UploadFileOptions,
} from '@spree/sdk-core'
import { getParams, transformListParams, uploadFile } from '@spree/sdk-core'
import type {
  AddressFilters,
  AddressSort,
  AdminUserFilters,
  AdminUserSort,
  AllowedOriginFilters,
  AllowedOriginSort,
  ApiKeyFilters,
  ApiKeySort,
  CatalogFilters,
  CatalogOrderMinimumFilters,
  CatalogOrderMinimumSort,
  CatalogSort,
  CategoryFilters,
  CategorySort,
  ChannelFilters,
  ChannelSort,
  ClaimFilters,
  ClaimReasonFilters,
  ClaimReasonSort,
  ClaimSort,
  CollectionFilters,
  CollectionSort,
  CommissionLineFilters,
  CommissionLineSort,
  CommissionRateFilters,
  CommissionRateSort,
  CompanyFilters,
  CompanyInvitationFilters,
  CompanyInvitationSort,
  CompanyMembershipFilters,
  CompanyMembershipSort,
  CompanySort,
  ConsentRecordFilters,
  ConsentRecordSort,
  CouponCodeFilters,
  CouponCodeSort,
  CreditCardFilters,
  CreditCardSort,
  CustomerFilters,
  CustomerGroupFilters,
  CustomerGroupSort,
  CustomerSort,
  CustomFieldDefinitionFilters,
  CustomFieldDefinitionSort,
  CustomFieldFilters,
  CustomFieldSort,
  DataRequestFilters,
  DataRequestSort,
  DeliveryMethodFilters,
  DeliveryMethodSort,
  DeliveryProfileFilters,
  DeliveryProfileSort,
  DeliveryZoneFilters,
  DeliveryZoneSort,
  DigitalAssetFilters,
  DigitalAssetSort,
  DigitalLinkFilters,
  DigitalLinkSort,
  DiscountFilters,
  DiscountSort,
  ExchangeFilters,
  ExchangeSort,
  ExportFilters,
  ExportSort,
  FeeFilters,
  FeeSort,
  FulfillmentFilters,
  FulfillmentSort,
  GiftCardBatchFilters,
  GiftCardBatchSort,
  GiftCardFilters,
  GiftCardSort,
  ImportFilters,
  ImportRowFilters,
  ImportRowSort,
  ImportSort,
  IntegrationFilters,
  IntegrationSort,
  InvitationFilters,
  InvitationSort,
  LineItemFilters,
  LineItemSort,
  MarketFilters,
  MarketSort,
  MediaFilters,
  MediaSort,
  OptionTypeFilters,
  OptionTypeSort,
  OrderCancellationReasonFilters,
  OrderCancellationReasonSort,
  OrderFilters,
  OrderGroupFilters,
  OrderGroupSort,
  OrderRoutingRuleFilters,
  OrderRoutingRuleSort,
  OrderSort,
  PackageTypeFilters,
  PackageTypeSort,
  PaymentFilters,
  PaymentMethodFilters,
  PaymentMethodSort,
  PaymentSort,
  PolicyFilters,
  PolicySort,
  PriceFilters,
  PriceListFilters,
  PriceListSort,
  PriceSort,
  ProductFilters,
  ProductSearchFilters,
  ProductSearchSort,
  ProductSort,
  ProductTypeFilters,
  ProductTypeSort,
  PromotionActionFilters,
  PromotionActionSort,
  PromotionFilters,
  PromotionRuleFilters,
  PromotionRuleSort,
  PromotionSort,
  PurchaseOrderFilters,
  PurchaseOrderSort,
  RefundFilters,
  RefundReasonFilters,
  RefundReasonSort,
  RefundSort,
  ReturnFilters,
  ReturnReasonFilters,
  ReturnReasonSort,
  ReturnSort,
  RoleFilters,
  RoleSort,
  SavedReportFilters,
  SavedReportSort,
  SellerFilters,
  SellerPayoutFilters,
  SellerPayoutSort,
  SellerRequirementFilters,
  SellerRequirementSort,
  SellerRequirementSubmissionFilters,
  SellerRequirementSubmissionSort,
  SellerSort,
  SellerTransferFilters,
  SellerTransferSort,
  StockLevelFilters,
  StockLevelSort,
  StockLocationFilters,
  StockLocationSort,
  StockMovementFilters,
  StockMovementSort,
  StockReservationFilters,
  StockReservationSort,
  StockTransferFilters,
  StockTransferSort,
  StoreCreditEventFilters,
  StoreCreditEventSort,
  StoreCreditFilters,
  StoreCreditSort,
  SupplierFilters,
  SupplierSort,
  TaxCategoryFilters,
  TaxCategorySort,
  TaxExemptionCertificateFilters,
  TaxExemptionCertificateSort,
  TaxExemptionReasonFilters,
  TaxExemptionReasonSort,
  TaxIdentifierFilters,
  TaxIdentifierSort,
  TaxLineFilters,
  TaxLineSort,
  TaxRateFilters,
  TaxRateSort,
  VariantFilters,
  VariantSort,
  WebhookDeliveryFilters,
  WebhookDeliverySort,
  WebhookEndpointFilters,
  WebhookEndpointSort,
} from './types/filters.generated'

// ============================================
// Semantic reporting contract (docs/plans/6.0-analytics-semantic-layer.md)
// ============================================

// Every sales context field, so adding one to `VariantSalesContextParams`
// fails to compile until it is listed here too.
const VARIANT_SALES_CONTEXT_FIELDS: Record<keyof VariantSalesContextParams, true> = {
  order_id: true,
  market_id: true,
  channel_id: true,
  customer_id: true,
  company_id: true,
  currency: true,
}

// The sales context scopes and prices the list, so it stays out of the Ransack filters.
function variantListQuery(
  params: ListParams<VariantFilters, VariantSort> & VariantSalesContextParams,
): ReturnType<typeof transformListParams> {
  const filters: Record<string, unknown> = { ...params }
  const context: Record<string, string> = {}
  for (const field of Object.keys(VARIANT_SALES_CONTEXT_FIELDS)) {
    const value = filters[field]
    if (typeof value === 'string' && value) context[field] = value
    delete filters[field]
  }
  return { ...transformListParams(filters), ...context }
}

export type ReportingGrain = 'hour' | 'day' | 'week' | 'month'

export type ReportingCompare = 'previous_period' | 'previous_year'

export type ReportingMetricFilterOp = 'eq' | 'gt' | 'gte' | 'lt' | 'lte'

export type ReportingQuery = {
  /** Registered metric names — discover via `reporting.schema()`. */
  metrics: string[]
  dimensions?: Array<
    | string
    | {
        name: string
        grain?: ReportingGrain
        /**
         * Include members with no matching rows, so a breakdown lists what had
         * no activity ("which products never sold"). One dimension only, and
         * only where `supports_include_empty` is set on the schema entry.
         */
        include_empty?: boolean
      }
  >
  filters?: Array<{ dimension: string; op: 'eq' | 'in'; value: string | string[] }>
  /**
   * Filter on an aggregate (a HAVING clause), e.g. `units_sold = 0`. Narrows
   * the rows only — the totals stay the period's real figure. The metric must
   * also appear in `metrics`, and cannot be a derived one.
   */
  metric_filters?: Array<{ metric: string; op: ReportingMetricFilterOp; value: number }>
  /**
   * A named preset (`last_month`, `week_to_date`, `last_4_weeks`, any
   * `last_<n>_<days|weeks|months>`), or ISO 8601 dates/datetimes in
   * since/until (a bare date covers the store's whole day); defaults to the
   * last 30 days. Everything resolves in the store timezone.
   */
  time_range?: { preset?: string; since?: string; until?: string }
  compare?: ReportingCompare
  /** Metric name, `-` prefix for descending. */
  sort?: string
  limit?: number
  currency?: string
}

export interface ReportingMetricValue {
  value: number
  /** Formatted money string — present on money metrics only. */
  display?: string
  /** Present when the query requested a comparison. */
  previous?: number
  /** Percentage change vs the previous period; null when there is no baseline. */
  growth?: number | null
}

/** Hydrated display payload for lookup-backed dimensions. */
export interface ReportingDimensionValue {
  /** Prefixed id (e.g. `cust_…`); null when the underlying record is gone (e.g. guest customers). */
  id: string | null
  label: string
  meta: Record<string, unknown>
}

export interface ReportingRow {
  /** Raw values for plain dimensions (time buckets, statuses); display payloads for lookups. */
  dimensions: Record<string, string | ReportingDimensionValue>
  metrics: Record<string, ReportingMetricValue>
}

export interface ReportingResult {
  meta: {
    currency: string
    time_range: { since: string; until: string }
    previous_time_range: { since: string; until: string } | null
    metrics: string[]
    dimensions: Array<{ name: string; grain?: string }>
  }
  totals: Record<string, ReportingMetricValue>
  rows: ReportingRow[]
}

export interface ReportingSchemaMetric {
  name: string
  /** Metrics from different families cannot be combined in one query. */
  family?: string
  label: string
  description?: string
  format: 'money' | 'integer' | 'decimal' | 'percent' | string
  currency?: string
  derived: boolean
  /** Derived metrics are computed after aggregation, so they cannot be sorted or filtered in SQL. */
  filterable?: boolean
}

export interface ReportingSchemaDimension {
  name: string
  label: string
  description?: string
  type: 'value' | 'time' | string
  grains?: ReportingGrain[]
  /** Set when rows carry hydrated `{ id, label, meta }` payloads for this dimension. */
  lookup?: string
  filter_ops: Array<'eq' | 'in'>
  /** Whether this dimension can lead a query with `include_empty`. */
  supports_include_empty?: boolean
  /** Enumerated raw values for status-like dimensions. */
  values?: Array<{ name: string; label: string }>
  /** Metrics this dimension can break down without double counting. */
  compatible_metrics: string[]
}

/** Members that can be queried together: sales, payments, inventory, carts. */
export interface ReportingSchemaFamily {
  name: string
  label: string
  metrics: string[]
  dimensions: string[]
}

/** The self-describing contract, filtered to what the caller may reference. */
export interface ReportingSchema {
  meta: { currency: string; timezone: string; supported_currencies: string[] }
  families: ReportingSchemaFamily[]
  metrics: ReportingSchemaMetric[]
  dimensions: ReportingSchemaDimension[]
  time_range: {
    presets: Array<{ name: string; label: string }>
    relative: string[]
    absolute: string
  }
  /** Ranking defaults the server applies (`limit` when omitted, and its ceiling). */
  limits: { default: number; max: number; max_buckets?: number }
  /** Ops accepted by `metric_filters`. */
  metric_filter_ops?: ReportingMetricFilterOp[]
  compare_modes?: ReportingCompare[]
}

export interface DashboardCounters {
  /** Prefixed channel id the order-based counts are scoped to; null means all channels. Stock counts are always store-wide. */
  channel_id: string | null
  /**
   * The counters registered on `Spree.reporting` that this caller may read,
   * in registration order. Labels, links and the sidebar entry each one
   * badges all come from the server, so a counter an extension registers
   * renders without a dashboard change.
   */
  counters: DashboardCounter[]
}

export interface AuthTokens {
  /** Short-lived JWT access token. Goes in `Authorization: Bearer`. Keep in memory only. */
  token: string
  user: AdminUser
}

export interface PermissionRule {
  /** true for `can`, false for `cannot` */
  allow: boolean
  /** Action names, e.g. ["read", "update"] or ["manage"] */
  actions: string[]
  /** Subject short names, e.g. ["product"] or ["all"] */
  subjects: string[]
  /** Whether the server rule has per-record conditions. If true, the action may be denied at the record level and the SPA should expect possible 403. */
  has_conditions: boolean
}

export interface MeResponse {
  /**
   * The signed-in admin, serialized exactly like every other admin user — so a
   * profile save can be merged straight into the auth context without dropping
   * the fields the top bar reads (`full_name`, `avatar_url`).
   */
  user: AdminUser
  permissions: PermissionRule[]
  /**
   * The flat expanded catalog permission keys the user holds on the current
   * store (`read_orders`, `write_products`, …) — the same vocabulary as API
   * key scopes and the role editor. `write_x` is always accompanied by its
   * implied `read_x`.
   */
  permission_keys: string[]
}

import type {
  AdminUserUpdateParams,
  AllowedOriginCreateParams,
  AllowedOriginUpdateParams,
  ApiKeyCreateParams,
  ApiKeyUpdateParams,
  BulkTagsParams,
  CatalogAssignParams,
  CatalogCreateParams,
  CatalogOrderMinimumParams,
  CatalogProductTermsParams,
  CatalogUpdateParams,
  CategoryCreateParams,
  CategoryRepositionParams,
  CategoryUpdateParams,
  ChannelAddProductsParams,
  ChannelCreateParams,
  ChannelRemoveProductsParams,
  ChannelUpdateParams,
  ClaimCancelParams,
  ClaimCreateParams,
  ClaimDenyParams,
  ClaimResolveParams,
  ClaimUpdateParams,
  CollectionCreateParams,
  CollectionUpdateParams,
  CommissionRateCreateParams,
  CommissionRateUpdateParams,
  CommissionRuleType,
  CompanyAddressCreateParams,
  CompanyAddressUpdateParams,
  CompanyCreateParams,
  CompanyMembershipCreateParams,
  CompanyUpdateParams,
  CustomerAddressCreateParams,
  CustomerAddressUpdateParams,
  CustomerBulkGroupsParams,
  CustomerCreateParams,
  CustomerGroupCreateParams,
  CustomerGroupUpdateParams,
  CustomerStoreCreditCreateParams,
  CustomerStoreCreditUpdateParams,
  CustomerUpdateParams,
  CustomFieldCreateParams,
  CustomFieldDefinitionCreateParams,
  CustomFieldDefinitionUpdateParams,
  CustomFieldOwnerType,
  CustomFieldResourceType,
  CustomFieldUpdateParams,
  DataRequestCreateParams,
  DeliveryCreateParams,
  DeliveryMarkDeliveredParams,
  DeliveryMethodCreateParams,
  DeliveryMethodRuleCreateParams,
  DeliveryMethodRuleUpdateParams,
  DeliveryMethodUpdateParams,
  DeliveryOriginGroupParams,
  DeliveryProfileCreateParams,
  DeliveryProfileUpdateParams,
  DeliveryUpdateParams,
  DeliveryZoneCreateParams,
  DeliveryZoneUpdateParams,
  DigitalAssetCreateParams,
  DigitalAssetProvider,
  DigitalAssetUpdateParams,
  DiscountCodeApplyParams,
  DiscountCreateParams,
  DiscountUpdateParams,
  EmailTemplateDraftParams,
  EmailTemplateLanguageParams,
  EmailTemplatePreviewParams,
  EmailTemplateRestoreParams,
  EmailTemplateVersionParams,
  ExchangeCancelParams,
  ExchangeCreateParams,
  ExchangeFulfillParams,
  ExchangeReceiveParams,
  ExchangeUpdateParams,
  ExportCreateParams,
  FeeCreateParams,
  FeeUpdateParams,
  FulfillmentCreateParams,
  FulfillmentFulfillParams,
  FulfillmentMarkDeliveredParams,
  FulfillmentSplitParams,
  FulfillmentUpdateParams,
  GiftCardApplyParams,
  GiftCardBatchCreateParams,
  GiftCardCreateParams,
  GiftCardUpdateParams,
  ImportCompleteMappingParams,
  ImportCreateParams,
  IntegrationCreateParams,
  IntegrationTypeDefinition,
  IntegrationUpdateParams,
  InvitationAcceptParams,
  InvitationCreateParams,
  LineItemCreateParams,
  LineItemUpdateParams,
  MaintenanceTaskRunCreateParams,
  MarketCreateParams,
  MarketUpdateParams,
  MediaCreateParams,
  MediaLibraryCreateParams,
  MediaLibraryUpdateParams,
  MediaUpdateParams,
  MediaUsageReference,
  MeUpdateParams,
  OauthAuthorizationParams,
  OptionTypeCreateParams,
  OptionTypeUpdateParams,
  OrderCancelParams,
  OrderCompleteParams,
  OrderCreateParams,
  OrderRoutingRuleCreateParams,
  OrderRoutingRuleUpdateParams,
  OrderUpdateParams,
  PackageTypeCreateParams,
  PackageTypeUpdateParams,
  PasswordResetParams,
  PasswordResetRequestParams,
  PaymentCaptureParams,
  PaymentCreateParams,
  PaymentMethodCreateParams,
  PaymentMethodType,
  PaymentMethodUpdateParams,
  PolicyCreateParams,
  PolicyUpdateParams,
  PriceBulkDestroyParams,
  PriceBulkUpsertParams,
  PriceCreateParams,
  PriceListCreateParams,
  PriceListUpdateParams,
  PriceUpdateParams,
  ProductBulkCategoriesParams,
  ProductBulkChannelsParams,
  ProductBulkCollectionsParams,
  ProductBulkDestroyParams,
  ProductBulkStatusParams,
  ProductCreateParams,
  ProductMembershipRepositionParams,
  ProductRejectParams,
  ProductTypeApplyToProductsResponse,
  ProductTypeCreateParams,
  ProductTypeUpdateParams,
  ProductUpdateParams,
  PromotionActionCalculator,
  PromotionActionCreateParams,
  PromotionActionUpdateParams,
  PromotionCreateParams,
  PromotionRuleCreateParams,
  PromotionRuleUpdateParams,
  PromotionUpdateParams,
  PurchaseOrderCancelParams,
  PurchaseOrderCreateParams,
  PurchaseOrderUpdateParams,
  ReasonCreateParams,
  ReasonUpdateParams,
  ReceivableCloseParams,
  RefundCreateParams,
  ResourceTypeDefinition,
  ReturnCancelParams,
  ReturnCreateParams,
  ReturnReceiveParams,
  ReturnRefundParams,
  ReturnUpdateParams,
  RoleCreateParams,
  RoleUpdateParams,
  SavedReportCreateParams,
  SavedReportUpdateParams,
  SellerApproveParams,
  SellerCreateParams,
  SellerInviteParams,
  SellerOnboarding,
  SellerPayoutCompleteParams,
  SellerRejectParams,
  SellerReopenOnboardingParams,
  SellerRequirementCreateParams,
  SellerRequirementReviewParams,
  SellerRequirementType,
  SellerRequirementUpdateParams,
  SellerRequirementWaiveParams,
  SellerSuspendParams,
  SellerUpdateParams,
  SetupCountries,
  SetupParams,
  SetupStatus,
  ShippingLabelCreateParams,
  StockLevelBulkUpsertParams,
  StockLevelUpdateParams,
  StockLocationCreateParams,
  StockLocationUpdateParams,
  StockReceiptCreateParams,
  StockTransferCancelParams,
  StockTransferCreateParams,
  StockTransferMarkInTransitParams,
  StockTransferUpdateParams,
  StoreCreditApplyParams,
  StoreCreditListResponse,
  StoreDataSources,
  StorePayoutProvider,
  StoreUpdateParams,
  SupplierCreateParams,
  SupplierUpdateParams,
  TaxCategoryCreateParams,
  TaxCategoryUpdateParams,
  TaxExemptionCertificateCreateParams,
  TaxExemptionCertificateUpdateParams,
  TaxExemptionReasonCreateParams,
  TaxExemptionReasonUpdateParams,
  TaxIdentifierCreateParams,
  TaxIdentifierUpdateParams,
  TaxProviderOption,
  TaxRateCreateParams,
  TaxRateUpdateParams,
  TrackingCarrierOption,
  VariantCreateParams,
  VariantSalesContextParams,
  VariantUpdateParams,
  WebhookEndpointCreateParams,
  WebhookEndpointDisableParams,
  WebhookEndpointUpdateParams,
} from './params'
import type {
  Address,
  AdminUser,
  AllowedOrigin,
  ApiKey,
  Catalog,
  CatalogAssignment,
  CatalogOrderMinimum,
  CatalogProduct,
  Category,
  Channel,
  Claim,
  ClaimReason,
  Collection,
  CommissionLine,
  CommissionRate,
  Company,
  CompanyInvitation,
  CompanyMembership,
  ConsentRecord,
  Country,
  CouponCode,
  CreditCard,
  Customer,
  CustomerGroup,
  CustomField,
  CustomFieldDefinition,
  DashboardCounter,
  DataRequest,
  Delivery,
  DeliveryMethod,
  DeliveryMethodRule,
  DeliveryOriginGroup,
  DeliveryProfile,
  DeliveryRateProviderOption,
  DeliveryZone,
  DigitalAsset,
  DigitalLink,
  Discount,
  EmailTemplate,
  EmailTemplatePreview,
  EmailTemplateRevision,
  EmailTemplateSampleRecord,
  Exchange,
  Export,
  Fee,
  FileUpload,
  Fulfillment,
  FulfillmentProviderOption,
  GiftCard,
  GiftCardBatch,
  Import,
  ImportRow,
  Integration,
  Invitation,
  InvitationAcceptanceLink,
  LineItem,
  Locale,
  MaintenanceTaskRun,
  Market,
  Media,
  OauthAccessToken,
  OauthApplication,
  OauthConsentRequest,
  OauthRedirect,
  OptionType,
  Order,
  OrderCancellationReason,
  OrderGroup,
  OrderRoutingRule,
  PackageType,
  Payment,
  PaymentMethod,
  Permission,
  Policy,
  Price,
  PriceList,
  PriceListProduct,
  Product,
  ProductType,
  Promotion,
  PromotionAction,
  PromotionRule,
  PurchaseOrder,
  Refund,
  RefundReason,
  ResourceTranslations,
  ResourceTranslationsNode,
  Return,
  ReturnReason,
  Role,
  SavedReport,
  Seller,
  SellerBalance,
  SellerPayout,
  SellerRequirement,
  SellerRequirementSubmission,
  SellerTeamMember,
  SellerTransfer,
  ShippingLabel,
  StockLevel,
  StockLocation,
  StockMovement,
  StockReceipt,
  StockReservation,
  StockTransfer,
  Store,
  StoreCredit,
  StoreCreditEvent,
  Supplier,
  TaxCategory,
  TaxExemptionCertificate,
  TaxExemptionReason,
  TaxIdentifier,
  TaxLine,
  TaxRate,
  TranslatableResource,
  TranslationBatchEntry,
  TranslationCoverage,
  UpdateStatus,
  UpgradeStep,
  UpgradeStepsMeta,
  Variant,
  WebhookDelivery,
  WebhookEndpoint,
  WebhookEvent,
} from './types'

/**
 * Maps a built-in CustomField owner type (e.g. `product`) to its admin
 * route segment. The generic `client.customFields(ownerType, ownerId)` escape
 * hatch reads this map; plugin owners that aren't registered here hit the
 * runtime "Unknown owner type" error and should use the first-class accessor
 * exposed by their plugin.
 *
 * `satisfies` here keeps the map keys as a subset of the strict-literal arm of
 * `CustomFieldOwnerType`. Adding a built-in owner means updating both this map
 * and the union in `params.ts`; the type system flags the map side.
 */
const CUSTOM_FIELD_OWNER_PATHS = {
  product: '/products',
  variant: '/variants',
  order: '/orders',
  customer: '/customers',
  category: '/categories',
  collection: '/collections',
  option_type: '/option_types',
  seller: '/sellers',
  promotion: '/promotions',
  gift_card: '/gift_cards',
  store_credit: '/store_credits',
  stock_transfer: '/stock_transfers',
  purchase_order: '/purchase_orders',
  company: '/companies',
  payment_method: '/payment_methods',
  delivery_method: '/delivery_methods',
  tax_rate: '/tax_rates',
  product_type: '/product_types',
  media: '/media',
  store: '/stores',
} as const satisfies Record<Exclude<CustomFieldOwnerType, string & {}>, string>

export class AdminClient {
  /**
   * Low-level request function for calling custom Admin API endpoints —
   * e.g. ones added by a Spree extension gem that doesn't ship its own
   * client.
   *
   * Uses the same auth headers (secret API key or JWT, whichever was
   * configured), retry logic, and base URL as the built-in resources.
   * Paths are relative to `/api/v3/admin`.
   *
   * @example
   * ```ts
   * import { createAdminClient } from '@spree/admin-sdk'
   * import type { PaginatedResponse } from '@spree/admin-sdk'
   *
   * interface Brand { id: string; name: string; slug: string }
   *
   * const client = createAdminClient({ baseUrl: 'https://api.shop.com', token: '...' })
   *
   * const brands = await client.request<PaginatedResponse<Brand>>('GET', '/brands')
   * const brand = await client.request<Brand>('GET', '/brands/brand_2X9aQf7kEw')
   * ```
   */
  readonly request: RequestFn

  constructor(request: RequestFn) {
    this.request = request
  }

  /**
   * Builds a `customFields` accessor whose methods expect the parent ID as
   * their first argument. Inlined by each first-class resource (`products`,
   * `orders`, …) so callers can write `client.products.customFields.list(id)`.
   * The generic `customFields(ownerType, ownerId)` escape hatch curries the
   * parent ID up front and returns the same shape minus the leading `parentId`.
   * @internal
   */
  private parentScopedCustomFields(basePath: string) {
    return {
      list: (
        parentId: string,
        params?: ListParams<CustomFieldFilters, CustomFieldSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<CustomField>> =>
        this.request<PaginatedResponse<CustomField>>(
          'GET',
          `${basePath}/${parentId}/custom_fields`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (parentId: string, id: string, options?: RequestOptions): Promise<CustomField> =>
        this.request<CustomField>('GET', `${basePath}/${parentId}/custom_fields/${id}`, options),

      create: (
        parentId: string,
        params: CustomFieldCreateParams,
        options?: RequestOptions,
      ): Promise<CustomField> =>
        this.request<CustomField>('POST', `${basePath}/${parentId}/custom_fields`, {
          ...options,
          body: params,
        }),

      update: (
        parentId: string,
        id: string,
        params: CustomFieldUpdateParams,
        options?: RequestOptions,
      ): Promise<CustomField> =>
        this.request<CustomField>('PATCH', `${basePath}/${parentId}/custom_fields/${id}`, {
          ...options,
          body: params,
        }),

      delete: (parentId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `${basePath}/${parentId}/custom_fields/${id}`, options),
    }
  }

  /**
   * Builds a read-only `translations` accessor for a translatable parent
   * resource. `get` returns the full matrix (source values + per-locale
   * translations + nested translatable children). Writes go through
   * `client.translations.batch(...)`, the single atomic write surface.
   * @internal
   */
  private parentScopedTranslations(basePath: string) {
    return {
      get: (parentId: string, options?: RequestOptions): Promise<ResourceTranslations> =>
        this.request<{ data: ResourceTranslations }>(
          'GET',
          `${basePath}/${parentId}/translations`,
          options,
        ).then((r) => r.data),
    }
  }

  /**
   * The uniform nested products surface every product-curating parent
   * exposes — categories, collections, catalogs and price lists all speak
   * the same protocol. Both writes are bulk: one request adds or removes
   * any number of products, and the counts report what actually changed
   * (already-present ids don't fail an add, non-members don't fail a
   * remove).
   */
  private productMembership<Row = Product>(basePath: string) {
    return {
      /**
       * A parent whose listing says more about a member than the plain
       * product does — a catalog reports what its agreement charges — types
       * `Row` accordingly.
       */
      list: (
        parentId: string,
        params?: ListParams<ProductFilters, ProductSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Row>> =>
        this.request<PaginatedResponse<Row>>('GET', `${basePath}/${parentId}/products`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      /** Bulk-adds products; already-present rows are skipped. */
      create: (
        parentId: string,
        productIds: string[],
        options?: RequestOptions,
      ): Promise<{ added_count: number }> =>
        this.request<{ added_count: number }>('POST', `${basePath}/${parentId}/products`, {
          ...options,
          body: { product_ids: productIds },
        }),

      /** Bulk-removes products; ids that aren't members are ignored. */
      delete: (
        parentId: string,
        productIds: string[],
        options?: RequestOptions,
      ): Promise<{ removed_count: number }> =>
        this.request<{ removed_count: number }>('DELETE', `${basePath}/${parentId}/products`, {
          ...options,
          body: { product_ids: productIds },
        }),
    }
  }

  /**
   * `productMembership` plus per-member reposition, for the parents whose
   * membership carries a manual order (categories, collections).
   */
  private positionedProductMembership(basePath: string) {
    return {
      ...this.productMembership(basePath),

      /** Persists a drag-to-reorder; `new_position` is a 0-based index. */
      reposition: (
        parentId: string,
        productId: string,
        params: ProductMembershipRepositionParams,
        options?: RequestOptions,
      ): Promise<void> =>
        this.request<void>('PATCH', `${basePath}/${parentId}/products/${productId}/reposition`, {
          ...options,
          body: params,
        }),
    }
  }

  /**
   * Generic accessor for any custom-field-bearing resource. Use the
   * first-class accessors (`client.products.customFields`, etc.) when
   * available — they're more discoverable. Use this when the owner is a
   * plugin-registered resource without a dedicated accessor.
   *
   * ```ts
   * await client.customFields('product', 'prod_xxx').list()
   * ```
   */
  customFields(ownerType: CustomFieldOwnerType, ownerId: string) {
    const ownerPath = (CUSTOM_FIELD_OWNER_PATHS as Record<string, string>)[ownerType]
    if (!ownerPath) {
      throw new Error(
        `Unknown custom-field owner type: ${ownerType}. Add it to CUSTOM_FIELD_OWNER_PATHS.`,
      )
    }
    const scoped = this.parentScopedCustomFields(ownerPath)
    return {
      list: (params?: ListParams<CustomFieldFilters, CustomFieldSort>, options?: RequestOptions) =>
        scoped.list(ownerId, params, options),
      get: (id: string, options?: RequestOptions) => scoped.get(ownerId, id, options),
      create: (params: CustomFieldCreateParams, options?: RequestOptions) =>
        scoped.create(ownerId, params, options),
      update: (id: string, params: CustomFieldUpdateParams, options?: RequestOptions) =>
        scoped.update(ownerId, id, params, options),
      delete: (id: string, options?: RequestOptions) => scoped.delete(ownerId, id, options),
    }
  }

  // ============================================
  // Custom Field Definitions (per resource type)
  // ============================================

  readonly customFieldDefinitions = {
    list: (
      params?: ListParams<CustomFieldDefinitionFilters, CustomFieldDefinitionSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<CustomFieldDefinition>> =>
      this.request<PaginatedResponse<CustomFieldDefinition>>('GET', '/custom_field_definitions', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<CustomFieldDefinition> =>
      this.request<CustomFieldDefinition>('GET', `/custom_field_definitions/${id}`, options),

    /**
     * What a definition can be attached to. Comes from the server's registry,
     * so a resource an extension adds is offered without a dashboard release.
     */
    resourceTypes: (options?: RequestOptions): Promise<{ data: CustomFieldResourceType[] }> =>
      this.request<{ data: CustomFieldResourceType[] }>(
        'GET',
        '/custom_field_definitions/resource_types',
        options,
      ),

    create: (
      params: CustomFieldDefinitionCreateParams,
      options?: RequestOptions,
    ): Promise<CustomFieldDefinition> =>
      this.request<CustomFieldDefinition>('POST', '/custom_field_definitions', {
        ...options,
        body: params,
      }),

    update: (
      id: string,
      params: CustomFieldDefinitionUpdateParams,
      options?: RequestOptions,
    ): Promise<CustomFieldDefinition> =>
      this.request<CustomFieldDefinition>('PATCH', `/custom_field_definitions/${id}`, {
        ...options,
        body: params,
      }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/custom_field_definitions/${id}`, options),
  }

  // ============================================
  // Authentication
  // ============================================

  readonly auth = {
    /**
     * Exchange credentials for an access token. The refresh token is delivered as an
     * HttpOnly cookie scoped to `/api/v3/admin/auth` — never returned in the response body.
     */
    login: (credentials: LoginCredentials, options?: RequestOptions): Promise<AuthTokens> =>
      this.request<AuthTokens>('POST', '/auth/login', { ...options, body: credentials }),

    /**
     * Rotate the refresh cookie and obtain a new access token. Driven entirely by the
     * `spree_admin_refresh_token` HttpOnly cookie + `X-CSRF-Token` header (set by the SDK).
     */
    refresh: (options?: RequestOptions): Promise<AuthTokens> =>
      this.request<AuthTokens>('POST', '/auth/refresh', options),

    /**
     * Revoke the current refresh token server-side and clear auth cookies.
     * Idempotent: succeeds even when no session exists.
     */
    logout: (options?: RequestOptions): Promise<void> =>
      this.request<void>('POST', '/auth/logout', options),

    /**
     * List the authentication providers this store accepts. Unauthenticated — it
     * is read before a session exists, to decide whether the login page shows the
     * password form, SSO buttons, or both.
     */
    providers: (options?: RequestOptions): Promise<AuthProvidersResponse> =>
      this.request<AuthProvidersResponse>('GET', '/auth/providers', options),

    /**
     * Public (unauthenticated) lookup of a pending invitation by prefixed ID + token.
     * Returns just the safe-to-render context (store, role, inviter, invitee_exists)
     * so the SPA acceptance page can decide between sign-in and signup forms.
     */
    lookupInvitation: (id: string, token: string, options?: RequestOptions): Promise<Invitation> =>
      this.request<Invitation>('GET', `/auth/invitations/${id}/lookup`, {
        ...options,
        params: { token },
      }),

    /**
     * Public (unauthenticated) accept of an invitation. For existing accounts the
     * caller passes their password; for new accounts they pass password +
     * confirmation + names. Either path issues a JWT + refresh-token cookie
     * identical to `login`.
     */
    acceptInvitation: (
      id: string,
      token: string,
      params: InvitationAcceptParams,
      options?: RequestOptions,
    ): Promise<AuthTokens> =>
      this.request<AuthTokens>('POST', `/auth/invitations/${id}/accept`, {
        ...options,
        params: { token },
        body: params,
      }),

    /**
     * Public (unauthenticated) first-run setup availability check. True only
     * while the installation has no admin user — the login page uses it to
     * offer the setup screen.
     */
    setupStatus: (options?: RequestOptions): Promise<SetupStatus> =>
      this.request<SetupStatus>('GET', '/auth/setup', options),

    /**
     * Public (unauthenticated) list of countries the store can be set up in,
     * each with the currency and official languages derived from it. Returns
     * 404 once any admin user exists.
     */
    setupCountries: (options?: RequestOptions): Promise<SetupCountries> =>
      this.request<SetupCountries>('GET', '/auth/setup/countries', options),

    /**
     * Public (unauthenticated) first-run setup: creates the first admin
     * account and names the store, authorized by the one-time setup token
     * printed at install time. Issues a JWT + refresh-token cookie identical
     * to `login`. Returns 404 once any admin user exists.
     */
    completeSetup: (params: SetupParams, options?: RequestOptions): Promise<AuthTokens> =>
      this.request<AuthTokens>('POST', '/auth/setup', { ...options, body: params }),

    /**
     * Public (unauthenticated) request for a password reset email. Always
     * resolves (202) whether or not the email matches an account, to prevent
     * enumeration. The emailed link points at `redirect_url` when it is on the
     * dashboard's origin and the account is staff of the store, otherwise at the
     * dashboard's reset page, with the reset token appended as `?token=`.
     */
    requestPasswordReset: (
      params: PasswordResetRequestParams,
      options?: RequestOptions,
    ): Promise<void> =>
      this.request<void>('POST', '/auth/password_resets', { ...options, body: params }),

    /**
     * Public (unauthenticated) consume of a password reset token: sets the new
     * password and signs the admin in (JWT + refresh-token cookie, like `login`).
     * The token is single-use — it invalidates as soon as the password changes.
     */
    resetPassword: (
      token: string,
      params: PasswordResetParams,
      options?: RequestOptions,
    ): Promise<AuthTokens> =>
      this.request<AuthTokens>('PATCH', `/auth/password_resets/${encodeURIComponent(token)}`, {
        ...options,
        body: params,
      }),
  }

  // ============================================
  // Current admin user + permissions
  // ============================================

  readonly me = {
    /** Get the current admin user profile and their serialized permissions. */
    get: (options?: RequestOptions): Promise<MeResponse> =>
      this.request<MeResponse>('GET', '/me', options),

    /** Update the current admin's own profile (e.g. their UI language). */
    update: (params: MeUpdateParams, options?: RequestOptions): Promise<MeResponse> =>
      this.request<MeResponse>('PATCH', '/me', { ...options, body: params }),
  }

  readonly updates = {
    /**
     * Whether a newer Spree release exists, from the server's daily update
     * check. Needs a client created with `jwtToken` for an admin who can
     * manage the store; a secret key gets a 404.
     */
    get: (options?: RequestOptions): Promise<UpdateStatus> =>
      this.request<UpdateStatus>('GET', '/updates', options),
  }

  // ============================================
  // Dashboard
  // ============================================

  readonly reporting = {
    /** Run a semantic reporting query against the registered metric/dimension vocabulary. */
    query: (query: ReportingQuery, options?: RequestOptions): Promise<ReportingResult> =>
      this.request<ReportingResult>('POST', '/reporting/query', { ...options, body: query }),

    /** Registry introspection — drives pickers and agent tool schemas. */
    schema: (options?: RequestOptions): Promise<ReportingSchema> =>
      this.request<ReportingSchema>('GET', '/reporting/schema', options),

    /** Store-wide saved reports: a contract query plus visualization config. */
    savedReports: {
      list: (
        params?: ListParams<SavedReportFilters, SavedReportSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<SavedReport>> =>
        this.request<PaginatedResponse<SavedReport>>('GET', '/reporting/saved_reports', {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (id: string, options?: RequestOptions): Promise<SavedReport> =>
        this.request<SavedReport>('GET', `/reporting/saved_reports/${id}`, options),

      create: (params: SavedReportCreateParams, options?: RequestOptions): Promise<SavedReport> =>
        this.request<SavedReport>('POST', '/reporting/saved_reports', { ...options, body: params }),

      update: (
        id: string,
        params: SavedReportUpdateParams,
        options?: RequestOptions,
      ): Promise<SavedReport> =>
        this.request<SavedReport>('PATCH', `/reporting/saved_reports/${id}`, {
          ...options,
          body: params,
        }),

      delete: (id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/reporting/saved_reports/${id}`, options),
    },
  }

  readonly dashboard = {
    counters: (
      params?: { channel_id?: string },
      options?: RequestOptions,
    ): Promise<DashboardCounters> =>
      this.request<DashboardCounters>('GET', '/dashboard/counters', { ...options, params }),
  }

  // ============================================
  // Store Settings
  // ============================================

  readonly store = {
    get: (options?: RequestOptions): Promise<Store> =>
      this.request<Store>('GET', '/store', options),

    update: (params: StoreUpdateParams, options?: RequestOptions): Promise<Store> =>
      this.request<Store>('PATCH', '/store', { ...options, body: params }),

    /**
     * The pricing and inventory engines this store can choose between, and
     * whether each is usable — a provider whose integration is not connected
     * is listed but not selectable.
     */
    dataSources: (options?: RequestOptions): Promise<StoreDataSources> =>
      this.request<{ data: StoreDataSources }>('GET', '/store/data_sources', options).then(
        (r) => r.data,
      ),

    translations: this.parentScopedTranslations('/stores'),
  }

  /** The locales a merchant can translate content into for the current store. */
  readonly locales = {
    list: (options?: RequestOptions): Promise<Locale[]> =>
      this.request<{ data: Locale[] }>('GET', '/locales', options).then((r) => r.data),
  }

  /** Every translatable resource type and its translatable fields (registry). */
  readonly translatableResources = {
    list: (options?: RequestOptions): Promise<TranslatableResource[]> =>
      this.request<{ data: TranslatableResource[] }>(
        'GET',
        '/translatable_resources',
        options,
      ).then((r) => r.data),
  }

  /**
   * Translation writes that span multiple records (e.g. an option type plus
   * all its option values) in one atomic request. Each entry names its own
   * resource_type + resource_id; all succeed or none do.
   */
  readonly translations = {
    /**
     * Translation coverage across a whole resource type, for the centralized
     * Translations page.
     *
     * `resource_type` is sent as a plain param rather than through
     * `transformListParams`, which would wrap it into `q[resource_type]` and
     * leave the server without the one param it requires.
     */
    coverage: (
      resourceType: string,
      params?: ListParams & { search?: string } & Record<string, unknown>,
      options?: RequestOptions,
    ): Promise<{ data: TranslationCoverage; meta: PaginationMeta }> => {
      // `resource_type` and `search` are read as plain params by the server;
      // routing them through `transformListParams` would wrap both into
      // Ransack predicates (`q[resource_type]`) the controller never sees.
      const { page, limit, search, ...filters } = params ?? {}

      return this.request<{ data: TranslationCoverage; meta: PaginationMeta }>(
        'GET',
        '/translations',
        {
          ...options,
          params: {
            resource_type: resourceType,
            ...(page === undefined ? {} : { page: page as number }),
            ...(limit === undefined ? {} : { limit: limit as number }),
            ...(search === undefined ? {} : { search: search as string }),
            ...transformListParams(filters),
          },
        },
      )
    },

    batch: (
      entries: TranslationBatchEntry[],
      options?: RequestOptions,
    ): Promise<ResourceTranslationsNode[]> =>
      this.request<{ data: ResourceTranslationsNode[] }>('POST', '/translations/batch', {
        ...options,
        body: { translations: entries },
      }).then((r) => r.data),
  }

  // ============================================
  // Products
  // ============================================

  readonly products = {
    list: (
      params?: ListParams<ProductSearchFilters, ProductSearchSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Product>> =>
      this.request<PaginatedResponse<Product>>('GET', '/products', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Product> =>
      this.request<Product>('GET', `/products/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: ProductCreateParams, options?: RequestOptions): Promise<Product> =>
      this.request<Product>('POST', '/products', { ...options, body: params }),

    update: (id: string, params: ProductUpdateParams, options?: RequestOptions): Promise<Product> =>
      this.request<Product>('PATCH', `/products/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/products/${id}`, options),

    /**
     * Duplicate a product. Returns the freshly-created clone (status `draft`,
     * name prefixed "COPY OF"). Media is duplicated by default server-side.
     */
    clone: (id: string, options?: RequestOptions): Promise<Product> =>
      this.request<Product>('POST', `/products/${id}/clone`, options),

    /**
     * Accept a product a seller submitted, putting it on sale. Refuses
     * anything not awaiting review — reaching `active` from elsewhere is an
     * ordinary status write.
     */
    approve: (id: string, options?: RequestOptions): Promise<Product> =>
      this.request<Product>('PATCH', `/products/${id}/approve`, options),

    /**
     * Turn a submission down. The reason is shown to the seller, so they know
     * what to change before submitting again.
     */
    reject: (
      id: string,
      params?: ProductRejectParams,
      options?: RequestOptions,
    ): Promise<Product> =>
      this.request<Product>('PATCH', `/products/${id}/reject`, { ...options, body: params }),

    /**
     * Put one product on sale, running its status workflow so the
     * `product.activated` event fires. Refuses a product awaiting review,
     * which is approved or rejected instead.
     */
    activate: (id: string, options?: RequestOptions): Promise<Product> =>
      this.request<Product>('PATCH', `/products/${id}/activate`, options),

    /** Archive one product, taking it off sale. Refuses a product awaiting review. */
    archive: (id: string, options?: RequestOptions): Promise<Product> =>
      this.request<Product>('PATCH', `/products/${id}/archive`, options),

    /** Take one product off sale, back to a draft. Refuses a product awaiting review. */
    draft: (id: string, options?: RequestOptions): Promise<Product> =>
      this.request<Product>('PATCH', `/products/${id}/draft`, options),

    /**
     * Bulk-set `status` on a list of products. The server validates `status`
     * against the product status enum and reindexes affected products.
     */
    bulkStatusUpdate: (
      params: ProductBulkStatusParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number; status: string }> =>
      this.request('POST', '/products/bulk_status_update', { ...options, body: params }),

    /** Attach every product in `ids` to every category in `category_ids`. */
    bulkAddToCategories: (
      params: ProductBulkCategoriesParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number; category_count: number }> =>
      this.request('POST', '/products/bulk_add_to_categories', { ...options, body: params }),

    /** Detach every product in `ids` from every category in `category_ids`. */
    bulkRemoveFromCategories: (
      params: ProductBulkCategoriesParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number; category_count: number }> =>
      this.request('POST', '/products/bulk_remove_from_categories', { ...options, body: params }),

    /**
     * Attach every product in `ids` to every collection in `collection_ids`.
     * Automatic collections are skipped (their membership comes from rules), so
     * `collection_count` reports how many were actually applied.
     */
    bulkAddToCollections: (
      params: ProductBulkCollectionsParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number; collection_count: number }> =>
      this.request('POST', '/products/bulk_add_to_collections', { ...options, body: params }),

    /** Detach every product in `ids` from every collection in `collection_ids`. */
    bulkRemoveFromCollections: (
      params: ProductBulkCollectionsParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number; collection_count: number }> =>
      this.request('POST', '/products/bulk_remove_from_collections', { ...options, body: params }),

    /** Publish every product in `ids` on every channel in `channel_ids`. */
    bulkAddToChannels: (
      params: ProductBulkChannelsParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number; channel_count: number }> =>
      this.request('POST', '/products/bulk_add_to_channels', { ...options, body: params }),

    /** Unpublish every product in `ids` from every channel in `channel_ids`. */
    bulkRemoveFromChannels: (
      params: ProductBulkChannelsParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number; channel_count: number; removed: number }> =>
      this.request('POST', '/products/bulk_remove_from_channels', { ...options, body: params }),

    /** Add each tag name to every product. Tags are upserted by name. */
    bulkAddTags: (
      params: BulkTagsParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number; tag_count: number }> =>
      this.request('POST', '/products/bulk_add_tags', { ...options, body: params }),

    /** Remove each tag name from every product. No-op for non-tagged. */
    bulkRemoveTags: (
      params: BulkTagsParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number; tag_count: number }> =>
      this.request('POST', '/products/bulk_remove_tags', { ...options, body: params }),

    /** Soft-delete a list of products. */
    bulkDestroy: (
      params: ProductBulkDestroyParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number }> =>
      this.request('DELETE', '/products/bulk_destroy', { ...options, body: params }),

    media: {
      list: (
        productId: string,
        params?: ListParams<MediaFilters, MediaSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Media>> =>
        this.request<PaginatedResponse<Media>>('GET', `/products/${productId}/media`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      create: (
        productId: string,
        params: MediaCreateParams,
        options?: RequestOptions,
      ): Promise<Media> =>
        this.request<Media>('POST', `/products/${productId}/media`, { ...options, body: params }),

      update: (
        productId: string,
        id: string,
        params: MediaUpdateParams,
        options?: RequestOptions,
      ): Promise<Media> =>
        this.request<Media>('PATCH', `/products/${productId}/media/${id}`, {
          ...options,
          body: params,
        }),

      delete: (productId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/products/${productId}/media/${id}`, options),
    },

    digitalAssets: {
      list: (
        productId: string,
        params?: ListParams<DigitalAssetFilters, DigitalAssetSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<DigitalAsset>> =>
        this.request<PaginatedResponse<DigitalAsset>>(
          'GET',
          `/products/${productId}/digital_assets`,
          {
            ...options,
            params: params ? transformListParams(params) : undefined,
          },
        ),

      create: (
        productId: string,
        params: DigitalAssetCreateParams,
        options?: RequestOptions,
      ): Promise<DigitalAsset> =>
        this.request<DigitalAsset>('POST', `/products/${productId}/digital_assets`, {
          ...options,
          body: params,
        }),

      update: (
        productId: string,
        id: string,
        params: DigitalAssetUpdateParams,
        options?: RequestOptions,
      ): Promise<DigitalAsset> =>
        this.request<DigitalAsset>('PATCH', `/products/${productId}/digital_assets/${id}`, {
          ...options,
          body: params,
        }),

      delete: (productId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/products/${productId}/digital_assets/${id}`, options),

      /**
       * The sources a merchant can pick for a new asset: the uploaded-file
       * default plus any host-registered provider. A host with only the default
       * gets a single-entry list.
       */
      providers: (
        productId: string,
        options?: RequestOptions,
      ): Promise<{ data: DigitalAssetProvider[] }> =>
        this.request<{ data: DigitalAssetProvider[] }>(
          'GET',
          `/products/${productId}/digital_assets/providers`,
          options,
        ),
    },

    variants: {
      list: (
        productId: string,
        params?: ListParams<VariantFilters, VariantSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Variant>> =>
        this.request<PaginatedResponse<Variant>>('GET', `/products/${productId}/variants`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (
        productId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<Variant> =>
        this.request<Variant>('GET', `/products/${productId}/variants/${id}`, {
          ...options,
          params: getParams(params),
        }),

      create: (
        productId: string,
        params: VariantCreateParams,
        options?: RequestOptions,
      ): Promise<Variant> =>
        this.request<Variant>('POST', `/products/${productId}/variants`, {
          ...options,
          body: params,
        }),

      update: (
        productId: string,
        id: string,
        params: VariantUpdateParams,
        options?: RequestOptions,
      ): Promise<Variant> =>
        this.request<Variant>('PATCH', `/products/${productId}/variants/${id}`, {
          ...options,
          body: params,
        }),

      delete: (productId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/products/${productId}/variants/${id}`, options),

      media: {
        list: (
          productId: string,
          variantId: string,
          params?: ListParams<MediaFilters, MediaSort>,
          options?: RequestOptions,
        ): Promise<PaginatedResponse<Media>> =>
          this.request<PaginatedResponse<Media>>(
            'GET',
            `/products/${productId}/variants/${variantId}/media`,
            {
              ...options,
              params: params ? transformListParams(params) : undefined,
            },
          ),

        create: (
          productId: string,
          variantId: string,
          params: MediaCreateParams,
          options?: RequestOptions,
        ): Promise<Media> =>
          this.request<Media>('POST', `/products/${productId}/variants/${variantId}/media`, {
            ...options,
            body: params,
          }),

        update: (
          productId: string,
          variantId: string,
          id: string,
          params: MediaUpdateParams,
          options?: RequestOptions,
        ): Promise<Media> =>
          this.request<Media>('PATCH', `/products/${productId}/variants/${variantId}/media/${id}`, {
            ...options,
            body: params,
          }),

        delete: (
          productId: string,
          variantId: string,
          id: string,
          options?: RequestOptions,
        ): Promise<void> =>
          this.request<void>(
            'DELETE',
            `/products/${productId}/variants/${variantId}/media/${id}`,
            options,
          ),
      },
    },

    customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.product),

    translations: this.parentScopedTranslations('/products'),
  }

  // ============================================
  // Digital links
  // ============================================

  /**
   * Download grants issued to customers when an order is placed. They are never
   * created by hand — `reset` gives a customer their allowance back.
   */
  readonly digitalLinks = {
    list: (
      params?: ListParams<DigitalLinkFilters, DigitalLinkSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<DigitalLink>> =>
      this.request<PaginatedResponse<DigitalLink>>('GET', '/digital_links', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    retrieve: (id: string, options?: RequestOptions): Promise<DigitalLink> =>
      this.request<DigitalLink>('GET', `/digital_links/${id}`, options),

    reset: (id: string, options?: RequestOptions): Promise<DigitalLink> =>
      this.request<DigitalLink>('PATCH', `/digital_links/${id}/reset`, options),
  }

  // ============================================
  // Orders
  // ============================================

  readonly orders = {
    list: (
      params?: ListParams<OrderFilters, OrderSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Order>> =>
      this.request<PaginatedResponse<Order>>('GET', '/orders', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Order> =>
      this.request<Order>('GET', `/orders/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: OrderCreateParams, options?: RequestOptions): Promise<Order> =>
      this.request<Order>('POST', '/orders', { ...options, body: params }),

    update: (id: string, params: OrderUpdateParams, options?: RequestOptions): Promise<Order> =>
      this.request<Order>('PATCH', `/orders/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/orders/${id}`, options),

    /**
     * An order holding several sellers' goods divides into one order per
     * seller, and the group it produced is what comes back — narrow the result
     * with `isOrderGroup`.
     */
    complete: (
      id: string,
      params?: OrderCompleteParams,
      options?: RequestOptions,
    ): Promise<Order | OrderGroup> =>
      this.request<Order | OrderGroup>('PATCH', `/orders/${id}/complete`, {
        ...options,
        body: params,
      }),

    cancel: (id: string, params?: OrderCancelParams, options?: RequestOptions): Promise<Order> =>
      this.request<Order>('PATCH', `/orders/${id}/cancel`, { ...options, body: params }),

    approve: (id: string, options?: RequestOptions): Promise<Order> =>
      this.request<Order>('PATCH', `/orders/${id}/approve`, options),

    resendConfirmation: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('POST', `/orders/${id}/resend_confirmation`, options),

    /** Re-sends the "your files are ready" email. No-op when the order has no downloads. */
    resendDigitalLinks: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('POST', `/orders/${id}/resend_digital_links`, options),

    giftCards: {
      apply: (
        orderId: string,
        params: GiftCardApplyParams,
        options?: RequestOptions,
      ): Promise<unknown> =>
        this.request('POST', `/orders/${orderId}/gift_cards`, { ...options, body: params }),

      remove: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/orders/${orderId}/gift_cards/${id}`, options),
    },

    storeCredits: {
      apply: (
        orderId: string,
        params?: StoreCreditApplyParams,
        options?: RequestOptions,
      ): Promise<Order> =>
        this.request<Order>('POST', `/orders/${orderId}/store_credits`, {
          ...options,
          body: params,
        }),

      remove: (orderId: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/orders/${orderId}/store_credits`, options),
    },

    items: {
      list: (
        orderId: string,
        params?: ListParams<LineItemFilters, LineItemSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<LineItem>> =>
        this.request<PaginatedResponse<LineItem>>('GET', `/orders/${orderId}/items`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (
        orderId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<LineItem> =>
        this.request<LineItem>('GET', `/orders/${orderId}/items/${id}`, {
          ...options,
          params: getParams(params),
        }),

      create: (
        orderId: string,
        params: LineItemCreateParams,
        options?: RequestOptions,
      ): Promise<LineItem> =>
        this.request<LineItem>('POST', `/orders/${orderId}/items`, { ...options, body: params }),

      update: (
        orderId: string,
        id: string,
        params: LineItemUpdateParams,
        options?: RequestOptions,
      ): Promise<LineItem> =>
        this.request<LineItem>('PATCH', `/orders/${orderId}/items/${id}`, {
          ...options,
          body: params,
        }),

      delete: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/orders/${orderId}/items/${id}`, options),
    },

    fulfillments: {
      list: (
        orderId: string,
        params?: ListParams<FulfillmentFilters, FulfillmentSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Fulfillment>> =>
        this.request<PaginatedResponse<Fulfillment>>('GET', `/orders/${orderId}/fulfillments`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (
        orderId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<Fulfillment> =>
        this.request<Fulfillment>('GET', `/orders/${orderId}/fulfillments/${id}`, {
          ...options,
          params: getParams(params),
        }),

      create: (
        orderId: string,
        params: FulfillmentCreateParams,
        options?: RequestOptions,
      ): Promise<Fulfillment> =>
        this.request<Fulfillment>('POST', `/orders/${orderId}/fulfillments`, {
          ...options,
          body: params,
        }),

      update: (
        orderId: string,
        id: string,
        params: FulfillmentUpdateParams,
        options?: RequestOptions,
      ): Promise<Fulfillment> =>
        this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}`, {
          ...options,
          body: params,
        }),

      // Passing `items` ships only those quantities: they are split into a new
      // fulfillment, which is what comes back — the addressed fulfillment keeps
      // the remainder and stays open.
      fulfill: (
        orderId: string,
        id: string,
        params?: FulfillmentFulfillParams,
        options?: RequestOptions,
      ): Promise<Fulfillment> =>
        this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/fulfill`, {
          ...options,
          body: params,
        }),

      // Confirms the customer received the goods. Staff can record this by
      // hand — a merchant with no carrier integration still needs a delivered
      // state — and carriers reach the same endpoint through their webhooks.
      markDelivered: (
        orderId: string,
        id: string,
        params?: FulfillmentMarkDeliveredParams,
        options?: RequestOptions,
      ): Promise<Fulfillment> =>
        this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/mark_delivered`, {
          ...options,
          body: params,
        }),

      cancel: (orderId: string, id: string, options?: RequestOptions): Promise<Fulfillment> =>
        this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/cancel`, options),

      /**
       * The carrier documents bought or uploaded for a parcel. Creating one
       * with no body buys it through the parcel's carrier account; creating it
       * with a `file_signed_id` (from `files.upload()`) records
       * postage the merchant bought elsewhere. To print one, fetch
       * `download_url` with the `Authorization` header and drive the browser
       * download from a Blob — the bytes are streamed through the API rather
       * than served from storage.
       */
      labels: {
        list: (
          orderId: string,
          fulfillmentId: string,
          options?: RequestOptions,
        ): Promise<{ data: ShippingLabel[] }> =>
          this.request<{ data: ShippingLabel[] }>(
            'GET',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/labels`,
            options,
          ),

        get: (
          orderId: string,
          fulfillmentId: string,
          id: string,
          options?: RequestOptions,
        ): Promise<ShippingLabel> =>
          this.request<ShippingLabel>(
            'GET',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}`,
            options,
          ),

        create: (
          orderId: string,
          fulfillmentId: string,
          params?: ShippingLabelCreateParams,
          options?: RequestOptions,
        ): Promise<ShippingLabel> =>
          this.request<ShippingLabel>(
            'POST',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/labels`,
            { ...options, body: params },
          ),

        /**
         * Asks the carrier to refund a purchased label. The answer is
         * `refunded` when the carrier settled at once, `refund_requested` when
         * it will decide later. Uploaded labels cannot be refunded.
         */
        refund: (
          orderId: string,
          fulfillmentId: string,
          id: string,
          options?: RequestOptions,
        ): Promise<ShippingLabel> =>
          this.request<ShippingLabel>(
            'PATCH',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}/refund`,
            options,
          ),

        /** Uploaded labels only — a purchased label is refunded instead. */
        delete: (
          orderId: string,
          fulfillmentId: string,
          id: string,
          options?: RequestOptions,
        ): Promise<void> =>
          this.request<void>(
            'DELETE',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/labels/${id}`,
            options,
          ),
      },

      /**
       * The tracked consignments of a parcel — one per tracking number, each
       * carrying the carrier status last reported. A fulfillment's own
       * `tracking` field summarizes the first of them.
       */
      deliveries: {
        list: (
          orderId: string,
          fulfillmentId: string,
          options?: RequestOptions,
        ): Promise<{ data: Delivery[] }> =>
          this.request<{ data: Delivery[] }>(
            'GET',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries`,
            options,
          ),

        get: (
          orderId: string,
          fulfillmentId: string,
          id: string,
          options?: RequestOptions,
        ): Promise<Delivery> =>
          this.request<Delivery>(
            'GET',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
            options,
          ),

        create: (
          orderId: string,
          fulfillmentId: string,
          params: DeliveryCreateParams,
          options?: RequestOptions,
        ): Promise<Delivery> =>
          this.request<Delivery>(
            'POST',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries`,
            { ...options, body: params },
          ),

        /** A corrected tracking number starts the carrier journey over. */
        update: (
          orderId: string,
          fulfillmentId: string,
          id: string,
          params: DeliveryUpdateParams,
          options?: RequestOptions,
        ): Promise<Delivery> =>
          this.request<Delivery>(
            'PATCH',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
            { ...options, body: params },
          ),

        /** Refused for a consignment a label minted — refund the label. */
        delete: (
          orderId: string,
          fulfillmentId: string,
          id: string,
          options?: RequestOptions,
        ): Promise<void> =>
          this.request<void>(
            'DELETE',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}`,
            options,
          ),

        /**
         * Staff confirming one consignment arrived. The parcel becomes
         * delivered once every one of its consignments has.
         */
        markDelivered: (
          orderId: string,
          fulfillmentId: string,
          id: string,
          params?: DeliveryMarkDeliveredParams,
          options?: RequestOptions,
        ): Promise<Delivery> =>
          this.request<Delivery>(
            'PATCH',
            `/orders/${orderId}/fulfillments/${fulfillmentId}/deliveries/${id}/mark_delivered`,
            { ...options, body: params },
          ),
      },

      // Returns every fulfillment on the order, since a split re-shapes the
      // source as well as creating the new one (and destroys the source when
      // it is fully drained).
      split: (
        orderId: string,
        id: string,
        params: FulfillmentSplitParams,
        options?: RequestOptions,
      ): Promise<{ data: Fulfillment[] }> =>
        this.request<{ data: Fulfillment[] }>(
          'PATCH',
          `/orders/${orderId}/fulfillments/${id}/split`,
          {
            ...options,
            body: params,
          },
        ),
    },

    returns: {
      list: (
        orderId: string,
        params?: ListParams<ReturnFilters, ReturnSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Return>> =>
        this.request<PaginatedResponse<Return>>('GET', `/orders/${orderId}/returns`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (
        orderId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<Return> =>
        this.request<Return>('GET', `/orders/${orderId}/returns/${id}`, {
          ...options,
          params: getParams(params),
        }),

      create: (
        orderId: string,
        params: ReturnCreateParams,
        options?: RequestOptions,
      ): Promise<Return> =>
        this.request<Return>('POST', `/orders/${orderId}/returns`, {
          ...options,
          body: params,
        }),

      update: (
        orderId: string,
        id: string,
        params: ReturnUpdateParams,
        options?: RequestOptions,
      ): Promise<Return> =>
        this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}`, {
          ...options,
          body: params,
        }),

      approve: (orderId: string, id: string, options?: RequestOptions): Promise<Return> =>
        this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}/approve`, options),

      receive: (
        orderId: string,
        id: string,
        params?: ReturnReceiveParams,
        options?: RequestOptions,
      ): Promise<Return> =>
        this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}/receive`, {
          ...options,
          body: params,
        }),

      refund: (
        orderId: string,
        id: string,
        params?: ReturnRefundParams,
        options?: RequestOptions,
      ): Promise<Return> =>
        this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}/refund`, {
          ...options,
          body: params,
        }),

      cancel: (
        orderId: string,
        id: string,
        params?: ReturnCancelParams,
        options?: RequestOptions,
      ): Promise<Return> =>
        this.request<Return>('PATCH', `/orders/${orderId}/returns/${id}/cancel`, {
          ...options,
          body: params,
        }),

      /**
       * The prepaid label for the parcel coming back. Bought through the
       * carrier that shipped the goods out, or recorded from a file when the
       * merchant bought postage elsewhere — the same shape as a fulfillment's
       * labels, owned by the return instead.
       *
       * The customer downloads it from the storefront; this is the merchant's
       * side of the same record.
       */
      labels: {
        list: (
          orderId: string,
          returnId: string,
          options?: RequestOptions,
        ): Promise<{ data: ShippingLabel[] }> =>
          this.request<{ data: ShippingLabel[] }>(
            'GET',
            `/orders/${orderId}/returns/${returnId}/labels`,
            options,
          ),

        get: (
          orderId: string,
          returnId: string,
          id: string,
          options?: RequestOptions,
        ): Promise<ShippingLabel> =>
          this.request<ShippingLabel>(
            'GET',
            `/orders/${orderId}/returns/${returnId}/labels/${id}`,
            options,
          ),

        create: (
          orderId: string,
          returnId: string,
          params?: ShippingLabelCreateParams,
          options?: RequestOptions,
        ): Promise<ShippingLabel> =>
          this.request<ShippingLabel>('POST', `/orders/${orderId}/returns/${returnId}/labels`, {
            ...options,
            body: params,
          }),

        refund: (
          orderId: string,
          returnId: string,
          id: string,
          options?: RequestOptions,
        ): Promise<ShippingLabel> =>
          this.request<ShippingLabel>(
            'PATCH',
            `/orders/${orderId}/returns/${returnId}/labels/${id}/refund`,
            options,
          ),

        /** Uploaded labels only — a purchased label is refunded instead. */
        delete: (
          orderId: string,
          returnId: string,
          id: string,
          options?: RequestOptions,
        ): Promise<void> =>
          this.request<void>(
            'DELETE',
            `/orders/${orderId}/returns/${returnId}/labels/${id}`,
            options,
          ),
      },
    },

    exchanges: {
      list: (
        orderId: string,
        params?: ListParams<ExchangeFilters, ExchangeSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Exchange>> =>
        this.request<PaginatedResponse<Exchange>>('GET', `/orders/${orderId}/exchanges`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (
        orderId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<Exchange> =>
        this.request<Exchange>('GET', `/orders/${orderId}/exchanges/${id}`, {
          ...options,
          params: getParams(params),
        }),

      create: (
        orderId: string,
        params: ExchangeCreateParams,
        options?: RequestOptions,
      ): Promise<Exchange> =>
        this.request<Exchange>('POST', `/orders/${orderId}/exchanges`, {
          ...options,
          body: params,
        }),

      update: (
        orderId: string,
        id: string,
        params: ExchangeUpdateParams,
        options?: RequestOptions,
      ): Promise<Exchange> =>
        this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}`, {
          ...options,
          body: params,
        }),

      approve: (orderId: string, id: string, options?: RequestOptions): Promise<Exchange> =>
        this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/approve`, options),

      receive: (
        orderId: string,
        id: string,
        params?: ExchangeReceiveParams,
        options?: RequestOptions,
      ): Promise<Exchange> =>
        this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/receive`, {
          ...options,
          body: params,
        }),

      fulfill: (
        orderId: string,
        id: string,
        params?: ExchangeFulfillParams,
        options?: RequestOptions,
      ): Promise<Exchange> =>
        this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/fulfill`, {
          ...options,
          body: params,
        }),

      cancel: (
        orderId: string,
        id: string,
        params?: ExchangeCancelParams,
        options?: RequestOptions,
      ): Promise<Exchange> =>
        this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/cancel`, {
          ...options,
          body: params,
        }),
    },

    claims: {
      list: (
        orderId: string,
        params?: ListParams<ClaimFilters, ClaimSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Claim>> =>
        this.request<PaginatedResponse<Claim>>('GET', `/orders/${orderId}/claims`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (
        orderId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<Claim> =>
        this.request<Claim>('GET', `/orders/${orderId}/claims/${id}`, {
          ...options,
          params: getParams(params),
        }),

      create: (
        orderId: string,
        params: ClaimCreateParams,
        options?: RequestOptions,
      ): Promise<Claim> =>
        this.request<Claim>('POST', `/orders/${orderId}/claims`, {
          ...options,
          body: params,
        }),

      update: (
        orderId: string,
        id: string,
        params: ClaimUpdateParams,
        options?: RequestOptions,
      ): Promise<Claim> =>
        this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}`, {
          ...options,
          body: params,
        }),

      approve: (orderId: string, id: string, options?: RequestOptions): Promise<Claim> =>
        this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/approve`, options),

      resolve: (
        orderId: string,
        id: string,
        params: ClaimResolveParams,
        options?: RequestOptions,
      ): Promise<Claim> =>
        this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/resolve`, {
          ...options,
          body: params,
        }),

      deny: (
        orderId: string,
        id: string,
        params?: ClaimDenyParams,
        options?: RequestOptions,
      ): Promise<Claim> =>
        this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/deny`, {
          ...options,
          body: params,
        }),

      cancel: (
        orderId: string,
        id: string,
        params?: ClaimCancelParams,
        options?: RequestOptions,
      ): Promise<Claim> =>
        this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/cancel`, {
          ...options,
          body: params,
        }),
    },

    payments: {
      list: (
        orderId: string,
        params?: ListParams<PaymentFilters, PaymentSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Payment>> =>
        this.request<PaginatedResponse<Payment>>('GET', `/orders/${orderId}/payments`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (
        orderId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<Payment> =>
        this.request<Payment>('GET', `/orders/${orderId}/payments/${id}`, {
          ...options,
          params: getParams(params),
        }),

      create: (
        orderId: string,
        params: PaymentCreateParams,
        options?: RequestOptions,
      ): Promise<Payment> =>
        this.request<Payment>('POST', `/orders/${orderId}/payments`, { ...options, body: params }),

      /** Captures the payment: the full authorized amount, or `amount` for a partial capture. */
      capture: (
        orderId: string,
        id: string,
        params?: PaymentCaptureParams,
        options?: RequestOptions,
      ): Promise<Payment> =>
        this.request<Payment>('PATCH', `/orders/${orderId}/payments/${id}/capture`, {
          ...options,
          body: params,
        }),

      void: (orderId: string, id: string, options?: RequestOptions): Promise<Payment> =>
        this.request<Payment>('PATCH', `/orders/${orderId}/payments/${id}/void`, options),
    },

    refunds: {
      list: (
        orderId: string,
        params?: ListParams<RefundFilters, RefundSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Refund>> =>
        this.request<PaginatedResponse<Refund>>('GET', `/orders/${orderId}/refunds`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      create: (
        orderId: string,
        params: RefundCreateParams,
        options?: RequestOptions,
      ): Promise<Refund> =>
        this.request<Refund>('POST', `/orders/${orderId}/refunds`, { ...options, body: params }),
    },

    taxLines: {
      list: (
        orderId: string,
        params?: ListParams<TaxLineFilters, TaxLineSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<TaxLine>> =>
        this.request<PaginatedResponse<TaxLine>>('GET', `/orders/${orderId}/tax_lines`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (orderId: string, id: string, options?: RequestOptions): Promise<TaxLine> =>
        this.request<TaxLine>('GET', `/orders/${orderId}/tax_lines/${id}`, options),
    },

    discounts: {
      list: (
        orderId: string,
        params?: ListParams<DiscountFilters, DiscountSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Discount>> =>
        this.request<PaginatedResponse<Discount>>('GET', `/orders/${orderId}/discounts`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (orderId: string, id: string, options?: RequestOptions): Promise<Discount> =>
        this.request<Discount>('GET', `/orders/${orderId}/discounts/${id}`, options),

      /**
       * Creates a manual discount. With `line_item_id` a single row is
       * created; without it the value is distributed across line items
       * (largest remainder). Works on completed orders.
       */
      create: (
        orderId: string,
        params: DiscountCreateParams,
        options?: RequestOptions,
      ): Promise<{ data: Discount[] }> =>
        this.request<{ data: Discount[] }>('POST', `/orders/${orderId}/discounts`, {
          ...options,
          body: params,
        }),

      /** Manual rows only — promotion-sourced rows respond 422 (`discount_not_editable`). */
      update: (
        orderId: string,
        id: string,
        params: DiscountUpdateParams,
        options?: RequestOptions,
      ): Promise<Discount> =>
        this.request<Discount>('PATCH', `/orders/${orderId}/discounts/${id}`, {
          ...options,
          body: params,
        }),

      /** Manual rows only — promotion-sourced rows respond 422 (`discount_not_editable`). */
      delete: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/orders/${orderId}/discounts/${id}`, options),
    },

    /**
     * Discount codes on a draft order — same pending semantics as the
     * storefront cart endpoint (a real-but-not-yet-eligible code is stored
     * and activates on recalculation). Completed orders respond 422
     * (`discount_not_editable`); use manual discounts instead.
     */
    discountCodes: {
      create: (
        orderId: string,
        params: DiscountCodeApplyParams,
        options?: RequestOptions,
      ): Promise<Order> =>
        this.request<Order>('POST', `/orders/${orderId}/discount_codes`, {
          ...options,
          body: params,
        }),

      /** `code` is the discount code string, not an ID. */
      delete: (orderId: string, code: string, options?: RequestOptions): Promise<Order> =>
        this.request<Order>(
          'DELETE',
          `/orders/${orderId}/discount_codes/${encodeURIComponent(code)}`,
          options,
        ),
    },

    fees: {
      list: (
        orderId: string,
        params?: ListParams<FeeFilters, FeeSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Fee>> =>
        this.request<PaginatedResponse<Fee>>('GET', `/orders/${orderId}/fees`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (orderId: string, id: string, options?: RequestOptions): Promise<Fee> =>
        this.request<Fee>('GET', `/orders/${orderId}/fees/${id}`, options),

      create: (orderId: string, params: FeeCreateParams, options?: RequestOptions): Promise<Fee> =>
        this.request<Fee>('POST', `/orders/${orderId}/fees`, { ...options, body: params }),

      update: (
        orderId: string,
        id: string,
        params: FeeUpdateParams,
        options?: RequestOptions,
      ): Promise<Fee> =>
        this.request<Fee>('PATCH', `/orders/${orderId}/fees/${id}`, { ...options, body: params }),

      delete: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/orders/${orderId}/fees/${id}`, options),
    },

    customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.order),
  }

  // ============================================
  // Option Types
  // ============================================

  readonly optionTypes = {
    list: (
      params?: ListParams<OptionTypeFilters, OptionTypeSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<OptionType>> =>
      this.request<PaginatedResponse<OptionType>>('GET', '/option_types', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<OptionType> =>
      this.request<OptionType>('GET', `/option_types/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: OptionTypeCreateParams, options?: RequestOptions): Promise<OptionType> =>
      this.request<OptionType>('POST', '/option_types', { ...options, body: params }),

    update: (
      id: string,
      params: OptionTypeUpdateParams,
      options?: RequestOptions,
    ): Promise<OptionType> =>
      this.request<OptionType>('PATCH', `/option_types/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/option_types/${id}`, options),

    customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.option_type),

    translations: this.parentScopedTranslations('/option_types'),
  }

  // ============================================
  // Payment Methods
  // ============================================

  readonly deliveryMethods = {
    list: (
      params?: ListParams<DeliveryMethodFilters, DeliveryMethodSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<DeliveryMethod>> =>
      this.request<PaginatedResponse<DeliveryMethod>>('GET', '/delivery_methods', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<DeliveryMethod> =>
      this.request<DeliveryMethod>('GET', `/delivery_methods/${id}`, options),

    create: (
      params: DeliveryMethodCreateParams,
      options?: RequestOptions,
    ): Promise<DeliveryMethod> =>
      this.request<DeliveryMethod>('POST', '/delivery_methods', { ...options, body: params }),

    update: (
      id: string,
      params: DeliveryMethodUpdateParams,
      options?: RequestOptions,
    ): Promise<DeliveryMethod> =>
      this.request<DeliveryMethod>('PATCH', `/delivery_methods/${id}`, {
        ...options,
        body: params,
      }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/delivery_methods/${id}`, options),

    /** Registered delivery calculator classes, each with the JSON Schema of its preferences. */
    calculators: (
      options?: RequestOptions,
    ): Promise<{ data: Array<{ type: string; name: string; schema: PreferenceSchema }> }> =>
      this.request<{ data: Array<{ type: string; name: string; schema: PreferenceSchema }> }>(
        'GET',
        '/delivery_methods/calculators',
        options,
      ),

    /**
     * Registered fulfillment provider strategies plus the registered
     * fulfillment-type vocabulary (the strict set delivery methods and
     * product types validate against).
     */
    fulfillmentProviders: (
      options?: RequestOptions,
    ): Promise<{ data: FulfillmentProviderOption[] }> =>
      this.request<{ data: FulfillmentProviderOption[] }>(
        'GET',
        '/delivery_methods/fulfillment_providers',
        options,
      ),

    /** Rate providers available to this store, plus the default when none is chosen. */
    rateProviders: (
      options?: RequestOptions,
    ): Promise<{ data: DeliveryRateProviderOption[]; default: string }> =>
      this.request<{ data: DeliveryRateProviderOption[]; default: string }>(
        'GET',
        '/delivery_methods/rate_providers',
        options,
      ),

    /** Eligibility rules on a delivery method (item total / weight bounds, …). */
    rules: {
      list: (
        deliveryMethodId: string,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<DeliveryMethodRule>> =>
        this.request<PaginatedResponse<DeliveryMethodRule>>(
          'GET',
          `/delivery_methods/${deliveryMethodId}/rules`,
          options,
        ),

      create: (
        deliveryMethodId: string,
        params: DeliveryMethodRuleCreateParams,
        options?: RequestOptions,
      ): Promise<DeliveryMethodRule> =>
        this.request<DeliveryMethodRule>('POST', `/delivery_methods/${deliveryMethodId}/rules`, {
          ...options,
          body: params,
        }),

      update: (
        deliveryMethodId: string,
        id: string,
        params: DeliveryMethodRuleUpdateParams,
        options?: RequestOptions,
      ): Promise<DeliveryMethodRule> =>
        this.request<DeliveryMethodRule>(
          'PATCH',
          `/delivery_methods/${deliveryMethodId}/rules/${id}`,
          { ...options, body: params },
        ),

      delete: (deliveryMethodId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/delivery_methods/${deliveryMethodId}/rules/${id}`, options),
    },

    /** Registered rule kinds with preference schemas for building pickers. */
    ruleTypes: (
      options?: RequestOptions,
    ): Promise<{
      data: Array<{
        type: string
        name: string
        description: string
        schema: PreferenceSchema
        /** Association-backed config the rule accepts, e.g. `['product_ids']`. */
        association_fields: string[]
      }>
    }> =>
      this.request<{
        data: Array<{
          type: string
          name: string
          description: string
          schema: PreferenceSchema
          association_fields: string[]
        }>
      }>('GET', '/delivery_method_rules/types', options),
  }

  readonly deliveryProfiles = {
    list: (
      params?: ListParams<DeliveryProfileFilters, DeliveryProfileSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<DeliveryProfile>> =>
      this.request<PaginatedResponse<DeliveryProfile>>('GET', '/delivery_profiles', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<DeliveryProfile> =>
      this.request<DeliveryProfile>('GET', `/delivery_profiles/${id}`, options),

    create: (
      params: DeliveryProfileCreateParams,
      options?: RequestOptions,
    ): Promise<DeliveryProfile> =>
      this.request<DeliveryProfile>('POST', '/delivery_profiles', {
        ...options,
        body: params,
      }),

    /** `stock_location_ids` replaces the profile's full location set. */
    update: (
      id: string,
      params: DeliveryProfileUpdateParams,
      options?: RequestOptions,
    ): Promise<DeliveryProfile> =>
      this.request<DeliveryProfile>('PATCH', `/delivery_profiles/${id}`, {
        ...options,
        body: params,
      }),

    /** The default profile and profiles still referenced by products cannot be deleted. */
    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/delivery_profiles/${id}`, options),

    /** Registered profile kinds (shipping, digital, extension kinds). */
    kinds: (options?: RequestOptions): Promise<{ data: Array<{ kind: string }> }> =>
      this.request<{ data: Array<{ kind: string }> }>('GET', '/delivery_profiles/kinds', options),

    /** Origin groups partition a profile's fulfillment origins; its zones and methods each belong to one. */
    originGroups: {
      list: (
        deliveryProfileId: string,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<DeliveryOriginGroup>> =>
        this.request<PaginatedResponse<DeliveryOriginGroup>>(
          'GET',
          `/delivery_profiles/${deliveryProfileId}/origin_groups`,
          options,
        ),

      create: (
        deliveryProfileId: string,
        params: DeliveryOriginGroupParams,
        options?: RequestOptions,
      ): Promise<DeliveryOriginGroup> =>
        this.request<DeliveryOriginGroup>(
          'POST',
          `/delivery_profiles/${deliveryProfileId}/origin_groups`,
          { ...options, body: params },
        ),

      update: (
        deliveryProfileId: string,
        id: string,
        params: DeliveryOriginGroupParams,
        options?: RequestOptions,
      ): Promise<DeliveryOriginGroup> =>
        this.request<DeliveryOriginGroup>(
          'PATCH',
          `/delivery_profiles/${deliveryProfileId}/origin_groups/${id}`,
          { ...options, body: params },
        ),

      /** The last group, or one still holding zones or methods, cannot be deleted. */
      delete: (deliveryProfileId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>(
          'DELETE',
          `/delivery_profiles/${deliveryProfileId}/origin_groups/${id}`,
          options,
        ),
    },
  }

  readonly trackingCarriers = {
    /**
     * Registered tracking carriers (Spree.tracking_carriers) a tracking
     * number can be pinned to — the source for carrier pickers. Extensions
     * that register carriers appear here without a client change.
     */
    list: (options?: RequestOptions): Promise<{ data: TrackingCarrierOption[] }> =>
      this.request<{ data: TrackingCarrierOption[] }>('GET', '/tracking_carriers', options),
  }

  readonly deliveryZones = {
    list: (
      params?: ListParams<DeliveryZoneFilters, DeliveryZoneSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<DeliveryZone>> =>
      this.request<PaginatedResponse<DeliveryZone>>('GET', '/delivery_zones', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    /** Members are expand-gated; pass `{ expand: ['members'] }` to edit a zone. */
    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<DeliveryZone> =>
      this.request<DeliveryZone>('GET', `/delivery_zones/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: DeliveryZoneCreateParams, options?: RequestOptions): Promise<DeliveryZone> =>
      this.request<DeliveryZone>('POST', '/delivery_zones', { ...options, body: params }),

    /** `members` replaces the zone's full member set atomically. */
    update: (
      id: string,
      params: DeliveryZoneUpdateParams,
      options?: RequestOptions,
    ): Promise<DeliveryZone> =>
      this.request<DeliveryZone>('PATCH', `/delivery_zones/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/delivery_zones/${id}`, options),
  }

  readonly packageTypes = {
    list: (
      params?: ListParams<PackageTypeFilters, PackageTypeSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<PackageType>> =>
      this.request<PaginatedResponse<PackageType>>('GET', '/package_types', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<PackageType> =>
      this.request<PackageType>('GET', `/package_types/${id}`, options),

    create: (params: PackageTypeCreateParams, options?: RequestOptions): Promise<PackageType> =>
      this.request<PackageType>('POST', '/package_types', { ...options, body: params }),

    /** Setting `default` demotes whichever row was the store's box before. */
    update: (
      id: string,
      params: PackageTypeUpdateParams,
      options?: RequestOptions,
    ): Promise<PackageType> =>
      this.request<PackageType>('PATCH', `/package_types/${id}`, { ...options, body: params }),

    /** Refused while a variant is packed into it. */
    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/package_types/${id}`, options),
  }

  readonly paymentMethods = {
    list: (
      params?: ListParams<PaymentMethodFilters, PaymentMethodSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<PaymentMethod>> =>
      this.request<PaginatedResponse<PaymentMethod>>('GET', '/payment_methods', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<PaymentMethod> =>
      this.request<PaymentMethod>('GET', `/payment_methods/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: PaymentMethodCreateParams, options?: RequestOptions): Promise<PaymentMethod> =>
      this.request<PaymentMethod>('POST', '/payment_methods', { ...options, body: params }),

    update: (
      id: string,
      params: PaymentMethodUpdateParams,
      options?: RequestOptions,
    ): Promise<PaymentMethod> =>
      this.request<PaymentMethod>('PATCH', `/payment_methods/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/payment_methods/${id}`, options),

    types: (options?: RequestOptions): Promise<{ data: PaymentMethodType[] }> =>
      this.request<{ data: PaymentMethodType[] }>('GET', '/payment_methods/types', options),
  }

  // ============================================
  // Integrations (admin-only — provider credentials per store)
  // ============================================

  readonly integrations = {
    list: (
      params?: ListParams<IntegrationFilters, IntegrationSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Integration>> =>
      this.request<PaginatedResponse<Integration>>('GET', '/integrations', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<Integration> =>
      this.request<Integration>('GET', `/integrations/${id}`, options),

    create: (params: IntegrationCreateParams, options?: RequestOptions): Promise<Integration> =>
      this.request<Integration>('POST', '/integrations', { ...options, body: params }),

    update: (
      id: string,
      params: IntegrationUpdateParams,
      options?: RequestOptions,
    ): Promise<Integration> =>
      this.request<Integration>('PATCH', `/integrations/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/integrations/${id}`, options),

    /** Registered integration types with schemas and per-store connected state. */
    types: (options?: RequestOptions): Promise<{ data: IntegrationTypeDefinition[] }> =>
      this.request<{ data: IntegrationTypeDefinition[] }>('GET', '/integrations/types', options),

    /** Live connection check; nothing is persisted. */
    test: (
      id: string,
      options?: RequestOptions,
    ): Promise<{ connected: boolean; error_message: string | null }> =>
      this.request<{ connected: boolean; error_message: string | null }>(
        'POST',
        `/integrations/${id}/test`,
        options,
      ),
  }

  // ============================================
  // Price Lists (admin-only — wholesale, regional, volume pricing)
  // ============================================

  /**
   * CRUD plus lifecycle (`activate` / `deactivate`) for `Spree::PriceList`.
   * Membership (`product_ids: [...]`), rules (`rules: [...]`), and per-row
   * price overrides (`prices: [...]`) all ride along on the normal
   * `update` payload — one PATCH saves the entire editor. The
   * spreadsheet's initial render data is fetched via
   * `prices.list({ price_list_id_eq: …, currency_eq: … })`. Price lists
   * are admin-only; the storefront only ever sees the resolved price
   * (see `PriceSerializer#price_list_id`).
   */
  readonly priceLists = {
    list: (
      params?: ListParams<PriceListFilters, PriceListSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<PriceList>> =>
      this.request<PaginatedResponse<PriceList>>('GET', '/price_lists', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<PriceList> =>
      this.request<PriceList>('GET', `/price_lists/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: PriceListCreateParams, options?: RequestOptions): Promise<PriceList> =>
      this.request<PriceList>('POST', '/price_lists', { ...options, body: params }),

    update: (
      id: string,
      params: PriceListUpdateParams,
      options?: RequestOptions,
    ): Promise<PriceList> =>
      this.request<PriceList>('PATCH', `/price_lists/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/price_lists/${id}`, options),

    /** draft|inactive → active (or → scheduled if `starts_at` is in the future). */
    /** Which products the list prices — the same nested surface categories,
     * collections and catalogs expose. Adding materializes placeholder
     * prices per variant × currency; removing hard-deletes the rows. */
    products: this.productMembership<PriceListProduct>('/price_lists'),

    activate: (id: string, options?: RequestOptions): Promise<PriceList> =>
      this.request<PriceList>('PATCH', `/price_lists/${id}/activate`, options),

    /** active|scheduled → inactive. */
    deactivate: (id: string, options?: RequestOptions): Promise<PriceList> =>
      this.request<PriceList>('PATCH', `/price_lists/${id}/deactivate`, options),

    /**
     * Returns `[{ type, label, description, schema }]` for
     * every registered subclass in `Spree.pricing.rules`. Used to build
     * the "Add rule" picker + render a generic preferences form per
     * subclass. Rules themselves are not a separate REST resource —
     * the SPA ships them inline on the list's `update` payload.
     */
    ruleTypes: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
      this.request<{ data: ResourceTypeDefinition[] }>(
        'GET',
        '/price_lists/price_rule_types',
        options,
      ),
  }

  // ============================================
  // Prices (generic — base prices AND price-list overrides)
  // ============================================

  /**
   * CRUD + bulk endpoints for `Spree::Price`. One resource covers both
   * base prices (`price_list_id: null`) and price-list overrides
   * (`price_list_id: pl_…`). The spreadsheet UI for a price list uses
   * `list({ price_list_id_eq, currency_eq, page, limit })` for the
   * paginated read and `bulkUpsert(...)` for the save.
   */
  readonly prices = {
    list: (
      params?: ListParams<PriceFilters, PriceSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Price>> =>
      this.request<PaginatedResponse<Price>>('GET', '/prices', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Price> =>
      this.request<Price>('GET', `/prices/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: PriceCreateParams, options?: RequestOptions): Promise<Price> =>
      this.request<Price>('POST', '/prices', { ...options, body: params }),

    update: (id: string, params: PriceUpdateParams, options?: RequestOptions): Promise<Price> =>
      this.request<Price>('PATCH', `/prices/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/prices/${id}`, options),

    /**
     * One SQL round trip via `upsert_all` — model callbacks (PriceHistory,
     * after_save hooks) are bypassed for speed. Caller is responsible
     * for shipping sane values. Response is just `{ price_count }`: the
     * number of rows the DB touched.
     */
    bulkUpsert: (
      params: PriceBulkUpsertParams,
      options?: RequestOptions,
    ): Promise<{ price_count: number }> =>
      this.request('POST', '/prices/bulk_upsert', { ...options, body: params }),

    bulkDestroy: (
      params: PriceBulkDestroyParams,
      options?: RequestOptions,
    ): Promise<{ price_count: number }> =>
      this.request('DELETE', '/prices/bulk_destroy', { ...options, body: params }),
  }

  // ============================================
  // Promotions (with nested actions, rules, coupon codes)
  // ============================================

  readonly promotions = {
    list: (
      params?: ListParams<PromotionFilters, PromotionSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Promotion>> =>
      this.request<PaginatedResponse<Promotion>>('GET', '/promotions', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<Promotion> =>
      this.request<Promotion>('GET', `/promotions/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: PromotionCreateParams, options?: RequestOptions): Promise<Promotion> =>
      this.request<Promotion>('POST', '/promotions', { ...options, body: params }),

    update: (
      id: string,
      params: PromotionUpdateParams,
      options?: RequestOptions,
    ): Promise<Promotion> =>
      this.request<Promotion>('PATCH', `/promotions/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/promotions/${id}`, options),

    actions: {
      list: (
        promotionId: string,
        params?: ListParams<PromotionActionFilters, PromotionActionSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<PromotionAction>> =>
        this.request<PaginatedResponse<PromotionAction>>(
          'GET',
          `/promotions/${promotionId}/promotion_actions`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (promotionId: string, id: string, options?: RequestOptions): Promise<PromotionAction> =>
        this.request<PromotionAction>(
          'GET',
          `/promotions/${promotionId}/promotion_actions/${id}`,
          options,
        ),

      create: (
        promotionId: string,
        params: PromotionActionCreateParams,
        options?: RequestOptions,
      ): Promise<PromotionAction> =>
        this.request<PromotionAction>('POST', `/promotions/${promotionId}/promotion_actions`, {
          ...options,
          body: params,
        }),

      update: (
        promotionId: string,
        id: string,
        params: PromotionActionUpdateParams,
        options?: RequestOptions,
      ): Promise<PromotionAction> =>
        this.request<PromotionAction>(
          'PATCH',
          `/promotions/${promotionId}/promotion_actions/${id}`,
          { ...options, body: params },
        ),

      delete: (promotionId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/promotions/${promotionId}/promotion_actions/${id}`, options),
    },

    rules: {
      list: (
        promotionId: string,
        params?: ListParams<PromotionRuleFilters, PromotionRuleSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<PromotionRule>> =>
        this.request<PaginatedResponse<PromotionRule>>(
          'GET',
          `/promotions/${promotionId}/promotion_rules`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (promotionId: string, id: string, options?: RequestOptions): Promise<PromotionRule> =>
        this.request<PromotionRule>(
          'GET',
          `/promotions/${promotionId}/promotion_rules/${id}`,
          options,
        ),

      create: (
        promotionId: string,
        params: PromotionRuleCreateParams,
        options?: RequestOptions,
      ): Promise<PromotionRule> =>
        this.request<PromotionRule>('POST', `/promotions/${promotionId}/promotion_rules`, {
          ...options,
          body: params,
        }),

      update: (
        promotionId: string,
        id: string,
        params: PromotionRuleUpdateParams,
        options?: RequestOptions,
      ): Promise<PromotionRule> =>
        this.request<PromotionRule>('PATCH', `/promotions/${promotionId}/promotion_rules/${id}`, {
          ...options,
          body: params,
        }),

      delete: (promotionId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/promotions/${promotionId}/promotion_rules/${id}`, options),
    },

    couponCodes: {
      list: (
        promotionId: string,
        params?: ListParams<CouponCodeFilters, CouponCodeSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<CouponCode>> =>
        this.request<PaginatedResponse<CouponCode>>(
          'GET',
          `/promotions/${promotionId}/coupon_codes`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (promotionId: string, id: string, options?: RequestOptions): Promise<CouponCode> =>
        this.request<CouponCode>('GET', `/promotions/${promotionId}/coupon_codes/${id}`, options),
    },
  }

  readonly promotionActions = {
    types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
      this.request<{ data: ResourceTypeDefinition[] }>('GET', '/promotion_actions/types', options),

    calculators: (
      type: string,
      options?: RequestOptions,
    ): Promise<{ data: PromotionActionCalculator[] }> =>
      this.request<{ data: PromotionActionCalculator[] }>('GET', '/promotion_actions/calculators', {
        ...options,
        params: { type },
      }),
  }

  readonly promotionRules = {
    types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
      this.request<{ data: ResourceTypeDefinition[] }>('GET', '/promotion_rules/types', options),
  }

  // ============================================
  // Tags
  // ============================================

  readonly tags = {
    list: (
      /** `taggable_type` is the tagged resource's shorthand: `product`, `order` or `customer`. */
      params: { taggable_type: string; q?: string },
      options?: RequestOptions,
    ): Promise<{ data: Array<{ name: string }> }> =>
      this.request<{ data: Array<{ name: string }> }>('GET', '/tags', {
        ...options,
        params,
      }),
  }

  // ============================================
  // Customer groups
  // ============================================

  readonly customerGroups = {
    list: (
      params?: ListParams<CustomerGroupFilters, CustomerGroupSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<CustomerGroup>> =>
      this.request<PaginatedResponse<CustomerGroup>>('GET', '/customer_groups', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<CustomerGroup> =>
      this.request<CustomerGroup>('GET', `/customer_groups/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: CustomerGroupCreateParams, options?: RequestOptions): Promise<CustomerGroup> =>
      this.request<CustomerGroup>('POST', '/customer_groups', { ...options, body: params }),

    update: (
      id: string,
      params: CustomerGroupUpdateParams,
      options?: RequestOptions,
    ): Promise<CustomerGroup> =>
      this.request<CustomerGroup>('PATCH', `/customer_groups/${id}`, {
        ...options,
        body: params,
      }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/customer_groups/${id}`, options),
  }

  // ============================================
  // Marketplace sellers
  // ============================================

  /**
   * CRUD for `Spree::Seller`, plus the lifecycle actions. Status is never
   * writable through `update` — each transition is a workflow that also
   * sends mail and runs extension hooks, so moving a seller by hand would
   * skip all of it.
   */
  readonly sellers = {
    list: (
      params?: ListParams<SellerFilters, SellerSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Seller>> =>
      this.request<PaginatedResponse<Seller>>('GET', '/sellers', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Seller> =>
      this.request<Seller>('GET', `/sellers/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: SellerCreateParams, options?: RequestOptions): Promise<Seller> =>
      this.request<Seller>('POST', '/sellers', { ...options, body: params }),

    update: (id: string, params: SellerUpdateParams, options?: RequestOptions): Promise<Seller> =>
      this.request<Seller>('PATCH', `/sellers/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/sellers/${id}`, options),

    /** Opens the seller's team to someone; they join when they accept. */
    invite: (id: string, params: SellerInviteParams, options?: RequestOptions): Promise<Seller> =>
      this.request<Seller>('POST', `/sellers/${id}/invite`, { ...options, body: params }),

    /**
     * Lets the seller trade — also the way back from suspended or rejected.
     * Refused while a required onboarding requirement is unmet, unless
     * `override_requirements` says the operator means it anyway.
     */
    approve: (
      id: string,
      params?: SellerApproveParams,
      options?: RequestOptions,
    ): Promise<Seller> =>
      this.request<Seller>('PATCH', `/sellers/${id}/approve`, { ...options, body: params }),

    /** Where this seller stands against the marketplace's checklist. */
    onboarding: (id: string, options?: RequestOptions): Promise<SellerOnboarding> =>
      this.request<SellerOnboarding>('GET', `/sellers/${id}/onboarding`, options),

    /** Sends a seller awaiting review back to onboarding, with a note. */
    reopenOnboarding: (
      id: string,
      params?: SellerReopenOnboardingParams,
      options?: RequestOptions,
    ): Promise<Seller> =>
      this.request<Seller>('PATCH', `/sellers/${id}/reopen_onboarding`, {
        ...options,
        body: params,
      }),

    /**
     * Who runs this seller. The operator's view of what the seller panel
     * manages for itself — and the only way to repair a seller whose team has
     * locked itself out.
     */
    team: {
      list: (sellerId: string, options?: RequestOptions): Promise<{ data: SellerTeamMember[] }> =>
        this.request<{ data: SellerTeamMember[] }>('GET', `/sellers/${sellerId}/team`, options),

      /** Revokes a member's access. */
      delete: (sellerId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/sellers/${sellerId}/team/${id}`, options),
    },

    /** Offers to join this seller that nobody has accepted yet. */
    invitations: {
      list: (sellerId: string, options?: RequestOptions): Promise<{ data: Invitation[] }> =>
        this.request<{ data: Invitation[] }>('GET', `/sellers/${sellerId}/invitations`, options),

      /** Withdraws an offer. */
      delete: (sellerId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/sellers/${sellerId}/invitations/${id}`, options),

      /** Sends the email again; refused once the offer has lapsed. */
      resend: (sellerId: string, id: string, options?: RequestOptions): Promise<Invitation> =>
        this.request<Invitation>('PATCH', `/sellers/${sellerId}/invitations/${id}/resend`, options),

      /** The link that joins the seller's team; needs write access to sellers. */
      acceptanceLink: (
        sellerId: string,
        id: string,
        options?: RequestOptions,
      ): Promise<InvitationAcceptanceLink> =>
        this.request<InvitationAcceptanceLink>(
          'GET',
          `/sellers/${sellerId}/invitations/${id}/acceptance_link`,
          options,
        ),
    },

    /** What this seller submitted about the requirements, and its decisions. */
    requirementSubmissions: {
      list: (
        sellerId: string,
        params?: ListParams<SellerRequirementSubmissionFilters, SellerRequirementSubmissionSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<SellerRequirementSubmission>> =>
        this.request<PaginatedResponse<SellerRequirementSubmission>>(
          'GET',
          `/sellers/${sellerId}/requirement_submissions`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (
        sellerId: string,
        id: string,
        options?: RequestOptions,
      ): Promise<SellerRequirementSubmission> =>
        this.request<SellerRequirementSubmission>(
          'GET',
          `/sellers/${sellerId}/requirement_submissions/${id}`,
          options,
        ),

      accept: (
        sellerId: string,
        id: string,
        params?: SellerRequirementReviewParams,
        options?: RequestOptions,
      ): Promise<SellerRequirementSubmission> =>
        this.request<SellerRequirementSubmission>(
          'PATCH',
          `/sellers/${sellerId}/requirement_submissions/${id}/accept`,
          { ...options, body: params },
        ),

      reject: (
        sellerId: string,
        id: string,
        params?: SellerRequirementReviewParams,
        options?: RequestOptions,
      ): Promise<SellerRequirementSubmission> =>
        this.request<SellerRequirementSubmission>(
          'PATCH',
          `/sellers/${sellerId}/requirement_submissions/${id}/reject`,
          { ...options, body: params },
        ),

      /** Excuses this seller from one requirement the store asks of everyone. */
      waive: (
        sellerId: string,
        params: SellerRequirementWaiveParams,
        options?: RequestOptions,
      ): Promise<SellerRequirementSubmission> =>
        this.request<SellerRequirementSubmission>(
          'POST',
          `/sellers/${sellerId}/requirement_submissions`,
          { ...options, body: params },
        ),
    },

    suspend: (
      id: string,
      params?: SellerSuspendParams,
      options?: RequestOptions,
    ): Promise<Seller> =>
      this.request<Seller>('PATCH', `/sellers/${id}/suspend`, { ...options, body: params }),

    reject: (id: string, params?: SellerRejectParams, options?: RequestOptions): Promise<Seller> =>
      this.request<Seller>('PATCH', `/sellers/${id}/reject`, { ...options, body: params }),

    /**
     * Where this seller stands, one row per currency: earned, paid, still
     * owed, and earnings the payout provider has not yet confirmed.
     */
    balances: (id: string, options?: RequestOptions): Promise<{ data: SellerBalance[] }> =>
      this.request<{ data: SellerBalance[] }>('GET', `/sellers/${id}/balances`, options),

    /**
     * Settles this seller now, sweeping everything they are owed into a
     * payout per currency.
     *
     * What the `manual` payout interval means — the scheduled sweep skips
     * those sellers, leaving the operator to decide when. Also the way to pay
     * any seller early. Answers 422 when there is nothing to settle.
     */
    settle: (id: string, options?: RequestOptions): Promise<{ data: SellerPayout[] }> =>
      this.request<{ data: SellerPayout[] }>('POST', `/sellers/${id}/payouts`, options),

    customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.seller),
  }

  // ============================================
  // Seller onboarding requirements
  // ============================================

  /**
   * What this marketplace asks of a seller before it will let them trade.
   * Rows the operator composes from registered kinds — `types()` is what a
   * picker renders, and a marketplace's own kinds appear there as soon as
   * they are registered server-side.
   */
  readonly sellerRequirements = {
    list: (
      params?: ListParams<SellerRequirementFilters, SellerRequirementSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<SellerRequirement>> =>
      this.request<PaginatedResponse<SellerRequirement>>('GET', '/seller_requirements', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<SellerRequirement> =>
      this.request<SellerRequirement>('GET', `/seller_requirements/${id}`, options),

    create: (
      params: SellerRequirementCreateParams,
      options?: RequestOptions,
    ): Promise<SellerRequirement> =>
      this.request<SellerRequirement>('POST', '/seller_requirements', { ...options, body: params }),

    update: (
      id: string,
      params: SellerRequirementUpdateParams,
      options?: RequestOptions,
    ): Promise<SellerRequirement> =>
      this.request<SellerRequirement>('PATCH', `/seller_requirements/${id}`, {
        ...options,
        body: params,
      }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/seller_requirements/${id}`, options),

    /** The kinds an operator can add, with each one's configuration shape. */
    types: (options?: RequestOptions): Promise<{ data: SellerRequirementType[] }> =>
      this.request<{ data: SellerRequirementType[] }>('GET', '/seller_requirements/types', options),
  }

  // ============================================
  // Commissions (what the marketplace charges its sellers)
  // ============================================

  /**
   * CRUD for `Spree::CommissionRate`. Targeting rides the regular payload as
   * `rules: [...]` — the whole editor saves in one round-trip, and the server
   * replaces the rate's rules with exactly what it is sent.
   */
  readonly commissionRates = {
    list: (
      params?: ListParams<CommissionRateFilters, CommissionRateSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<CommissionRate>> =>
      this.request<PaginatedResponse<CommissionRate>>('GET', '/commission_rates', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<CommissionRate> =>
      this.request<CommissionRate>('GET', `/commission_rates/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (
      params: CommissionRateCreateParams,
      options?: RequestOptions,
    ): Promise<CommissionRate> =>
      this.request<CommissionRate>('POST', '/commission_rates', { ...options, body: params }),

    update: (
      id: string,
      params: CommissionRateUpdateParams,
      options?: RequestOptions,
    ): Promise<CommissionRate> =>
      this.request<CommissionRate>('PATCH', `/commission_rates/${id}`, {
        ...options,
        body: params,
      }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/commission_rates/${id}`, options),

    /**
     * Every registered rule kind with the schema describing its configuration,
     * so a client builds its editor from what the marketplace actually has
     * rather than a list hardcoded to match core's.
     */
    ruleTypes: (options?: RequestOptions): Promise<{ data: CommissionRuleType[] }> =>
      this.request<{ data: CommissionRuleType[] }>('GET', '/commission_rates/rule_types', options),
  }

  /**
   * Read-only view of `Spree::CommissionLine` — what each sale actually earned
   * the marketplace, frozen when the order was placed. There is no write path:
   * correcting a charge is a reversal, not an edit.
   */
  readonly commissionLines = {
    list: (
      params?: ListParams<CommissionLineFilters, CommissionLineSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<CommissionLine>> =>
      this.request<PaginatedResponse<CommissionLine>>('GET', '/commission_lines', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<CommissionLine> =>
      this.request<CommissionLine>('GET', `/commission_lines/${id}`, {
        ...options,
        params: getParams(params),
      }),
  }

  /**
   * `Spree::OrderGroup` — the checkout a split basket produced, and the
   * payments made against it. An order placed in one has no payments of its
   * own: its share of each of these is in its `payment_splits`.
   */
  readonly orderGroups = {
    list: (
      params?: ListParams<OrderGroupFilters, OrderGroupSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<OrderGroup>> =>
      this.request<PaginatedResponse<OrderGroup>>('GET', '/order_groups', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[]; fields?: string[] },
      options?: RequestOptions,
    ): Promise<OrderGroup> =>
      this.request<OrderGroup>('GET', `/order_groups/${id}`, {
        ...options,
        params: getParams(params),
      }),
  }

  // ============================================
  // Seller fund ledger
  // ============================================

  /**
   * Read-only view of `Spree::SellerTransfer` — what one order earned one
   * seller, credited when the goods went out. There is no write path: a
   * refund writes a reversal, which is another row rather than an edit.
   */
  readonly sellerTransfers = {
    list: (
      params?: ListParams<SellerTransferFilters, SellerTransferSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<SellerTransfer>> =>
      this.request<PaginatedResponse<SellerTransfer>>('GET', '/seller_transfers', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<SellerTransfer> =>
      this.request<SellerTransfer>('GET', `/seller_transfers/${id}`, {
        ...options,
        params: getParams(params),
      }),
  }

  /**
   * `Spree::SellerPayout` — one settlement to one seller. Created by the
   * sweep on that seller's own schedule rather than by a caller, so there is
   * no create or update. `complete` is what the built-in provider waits for:
   * the operator saying the bank transfer went out.
   */
  readonly sellerPayouts = {
    list: (
      params?: ListParams<SellerPayoutFilters, SellerPayoutSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<SellerPayout>> =>
      this.request<PaginatedResponse<SellerPayout>>('GET', '/seller_payouts', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<SellerPayout> =>
      this.request<SellerPayout>('GET', `/seller_payouts/${id}`, {
        ...options,
        params: getParams(params),
      }),

    complete: (
      id: string,
      data?: SellerPayoutCompleteParams,
      options?: RequestOptions,
    ): Promise<SellerPayout> =>
      this.request<SellerPayout>('PATCH', `/seller_payouts/${id}/complete`, {
        ...options,
        body: data,
      }),
  }

  // ============================================
  // Gift cards (admin-issued)
  // ============================================

  /**
   * CRUD for `Spree::GiftCard`. The list endpoint never embeds `customer`,
   * `created_by`, or `orders` by default — pass `expand=customer,created_by`
   * to populate row chips, or `expand=orders` on a detail read to surface
   * the consuming orders.
   */
  readonly giftCards = {
    list: (
      params?: ListParams<GiftCardFilters, GiftCardSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<GiftCard>> =>
      this.request<PaginatedResponse<GiftCard>>('GET', '/gift_cards', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<GiftCard> =>
      this.request<GiftCard>('GET', `/gift_cards/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: GiftCardCreateParams, options?: RequestOptions): Promise<GiftCard> =>
      this.request<GiftCard>('POST', '/gift_cards', { ...options, body: params }),

    update: (
      id: string,
      params: GiftCardUpdateParams,
      options?: RequestOptions,
    ): Promise<GiftCard> =>
      this.request<GiftCard>('PATCH', `/gift_cards/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/gift_cards/${id}`, options),
  }

  // ============================================
  // Store credits, across all customers
  // ============================================

  /**
   * Read-only view of what the store owes in prepaid balances. Issuing,
   * editing and deleting a credit stays nested under the customer that holds
   * it (`client.customers.storeCredits`).
   *
   * The list's `meta.totals` carries the outstanding balance as one row per
   * currency, summed over the same filter the page used — so filtering by a
   * customer answers that customer's balance and no filter answers the
   * store's liability.
   */
  readonly storeCredits = {
    list: (
      params?: ListParams<StoreCreditFilters, StoreCreditSort>,
      options?: RequestOptions,
    ): Promise<StoreCreditListResponse> =>
      this.request<StoreCreditListResponse>('GET', '/store_credits', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<StoreCredit> =>
      this.request<StoreCredit>('GET', `/store_credits/${id}`, {
        ...options,
        params: getParams(params),
      }),

    /** The credit's ledger — how its balance got to where it is. */
    events: {
      list: (
        storeCreditId: string,
        params?: ListParams<StoreCreditEventFilters, StoreCreditEventSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<StoreCreditEvent>> =>
        this.request<PaginatedResponse<StoreCreditEvent>>(
          'GET',
          `/store_credits/${storeCreditId}/events`,
          {
            ...options,
            params: params ? transformListParams(params) : undefined,
          },
        ),
    },
  }

  // ============================================
  // Post-sale, across all orders (read-only — creating any of these needs an
  // order, so writes live on client.orders.{returns,exchanges,claims})
  // ============================================

  readonly returns = {
    list: (
      params?: ListParams<ReturnFilters, ReturnSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Return>> =>
      this.request<PaginatedResponse<Return>>('GET', '/returns', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Return> =>
      this.request<Return>('GET', `/returns/${id}`, {
        ...options,
        params: getParams(params),
      }),
  }

  readonly exchanges = {
    list: (
      params?: ListParams<ExchangeFilters, ExchangeSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Exchange>> =>
      this.request<PaginatedResponse<Exchange>>('GET', '/exchanges', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<Exchange> =>
      this.request<Exchange>('GET', `/exchanges/${id}`, {
        ...options,
        params: getParams(params),
      }),
  }

  readonly claims = {
    list: (
      params?: ListParams<ClaimFilters, ClaimSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Claim>> =>
      this.request<PaginatedResponse<Claim>>('GET', '/claims', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Claim> =>
      this.request<Claim>('GET', `/claims/${id}`, {
        ...options,
        params: getParams(params),
      }),
  }

  // ============================================
  // Gift card batches (bulk issuance)
  // ============================================

  /**
   * Bulk-issue gift cards in groups of `codes_count`. The server generates
   * codes inline for batches up to `Spree.config.gift_card_batch_web_limit`
   * (default 500); larger batches enqueue a background job. The
   * SPA-facing list view filters cards by batch through
   * `/gift_cards?q[gift_card_batch_id_eq]=…`.
   */
  readonly giftCardBatches = {
    list: (
      params?: ListParams<GiftCardBatchFilters, GiftCardBatchSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<GiftCardBatch>> =>
      this.request<PaginatedResponse<GiftCardBatch>>('GET', '/gift_card_batches', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<GiftCardBatch> =>
      this.request<GiftCardBatch>('GET', `/gift_card_batches/${id}`, options),

    create: (params: GiftCardBatchCreateParams, options?: RequestOptions): Promise<GiftCardBatch> =>
      this.request<GiftCardBatch>('POST', '/gift_card_batches', { ...options, body: params }),
  }

  // ============================================
  // Tax configuration
  // ============================================

  /**
   * Tax rates for the built-in engine. A rate names the jurisdiction it
   * applies to — a country and optionally one of its states — rather than a
   * zone; one naming no country taxes everywhere.
   */
  readonly taxRates = {
    list: (
      params?: ListParams<TaxRateFilters, TaxRateSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<TaxRate>> =>
      this.request<PaginatedResponse<TaxRate>>('GET', '/tax_rates', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<TaxRate> =>
      this.request<TaxRate>('GET', `/tax_rates/${id}`, { ...options, params: getParams(params) }),

    create: (params: TaxRateCreateParams, options?: RequestOptions): Promise<TaxRate> =>
      this.request<TaxRate>('POST', '/tax_rates', { ...options, body: params }),

    update: (id: string, params: TaxRateUpdateParams, options?: RequestOptions): Promise<TaxRate> =>
      this.request<TaxRate>('PATCH', `/tax_rates/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/tax_rates/${id}`, options),
  }

  /**
   * The tax engines this installation has available, each declaring the
   * domains it cannot handle — so a dashboard can warn that pairing the
   * built-in engine with a US market means no local sales tax, rather than
   * letting a merchant discover it at checkout.
   */
  readonly taxProviders = {
    list: (options?: RequestOptions): Promise<PaginatedResponse<TaxProviderOption>> =>
      this.request<PaginatedResponse<TaxProviderOption>>('GET', '/tax_providers', options),
  }

  /**
   * How this installation can pay its sellers. Discovery only — which one a
   * store uses is a store preference, so there is nothing here to create.
   *
   * Each says whether it is usable by this store today, and whether it needs
   * sellers to hold an account with it: choosing one changes what the
   * marketplace has to ask of its sellers before it can pay them.
   */
  readonly payoutProviders = {
    list: (options?: RequestOptions): Promise<PaginatedResponse<StorePayoutProvider>> =>
      this.request<PaginatedResponse<StorePayoutProvider>>('GET', '/payout_providers', options),
  }

  // ============================================
  // Companies (business customers)
  // ============================================

  /**
   * Business customers as an organization tree: self-referential company
   * nodes (`kind: 'company' | 'division'`), each with an address book and
   * members whose standing covers the node's subtree. A legal-entity node
   * holds the tax registration that goes on its invoices and the exemption
   * certificates that decide whether its purchases are taxed; a division
   * reads both through its nearest legal-entity ancestor.
   *
   * List roots with `{ parent_id_null: 1 }` and a node's children with
   * `{ parent_id_eq: 'comp_…' }`. Deleting a node destroys its subtree.
   *
   * Address-book entries, memberships and invitations all belong to a node,
   * so every one of them is reached through it.
   */
  readonly companies = {
    list: (
      params?: ListParams<CompanyFilters, CompanySort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Company>> =>
      this.request<PaginatedResponse<Company>>('GET', '/companies', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Company> =>
      this.request<Company>('GET', `/companies/${id}`, { ...options, params: getParams(params) }),

    create: (params: CompanyCreateParams, options?: RequestOptions): Promise<Company> =>
      this.request<Company>('POST', '/companies', { ...options, body: params }),

    /** Re-parenting is an ordinary update — depth, cycle and store revalidate. */
    update: (id: string, params: CompanyUpdateParams, options?: RequestOptions): Promise<Company> =>
      this.request<Company>('PATCH', `/companies/${id}`, { ...options, body: params }),

    /** Destroys the node and its whole subtree. */
    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/companies/${id}`, options),

    addresses: {
      list: (
        companyId: string,
        params?: ListParams<AddressFilters, AddressSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Address>> =>
        this.request<PaginatedResponse<Address>>('GET', `/companies/${companyId}/addresses`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      create: (
        companyId: string,
        params: CompanyAddressCreateParams,
        options?: RequestOptions,
      ): Promise<Address> =>
        this.request<Address>('POST', `/companies/${companyId}/addresses`, {
          ...options,
          body: params,
        }),

      get: (companyId: string, id: string, options?: RequestOptions): Promise<Address> =>
        this.request<Address>('GET', `/companies/${companyId}/addresses/${id}`, options),

      /** Address fields edit the entry in place, so send only what changes. */
      update: (
        companyId: string,
        id: string,
        params: CompanyAddressUpdateParams,
        options?: RequestOptions,
      ): Promise<Address> =>
        this.request<Address>('PATCH', `/companies/${companyId}/addresses/${id}`, {
          ...options,
          body: params,
        }),

      delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/companies/${companyId}/addresses/${id}`, options),
    },

    /**
     * The people with standing over the node (and, through it, its subtree).
     * `create` takes an email and does the right thing: a membership for an
     * existing customer, a CompanyInvitation otherwise — check the returned
     * id prefix (`cmem_` vs `cinv_`).
     */
    memberships: {
      list: (
        companyId: string,
        params?: ListParams<CompanyMembershipFilters, CompanyMembershipSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<CompanyMembership>> =>
        this.request<PaginatedResponse<CompanyMembership>>(
          'GET',
          `/companies/${companyId}/memberships`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      create: (
        companyId: string,
        params: CompanyMembershipCreateParams,
        options?: RequestOptions,
      ): Promise<CompanyMembership | CompanyInvitation> =>
        this.request<CompanyMembership | CompanyInvitation>(
          'POST',
          `/companies/${companyId}/memberships`,
          { ...options, body: params },
        ),

      get: (companyId: string, id: string, options?: RequestOptions): Promise<CompanyMembership> =>
        this.request<CompanyMembership>(
          'GET',
          `/companies/${companyId}/memberships/${id}`,
          options,
        ),

      /** Withdraws the member's standing. The customer account is untouched. */
      delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/companies/${companyId}/memberships/${id}`, options),
    },

    invitations: {
      list: (
        companyId: string,
        params?: ListParams<CompanyInvitationFilters, CompanyInvitationSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<CompanyInvitation>> =>
        this.request<PaginatedResponse<CompanyInvitation>>(
          'GET',
          `/companies/${companyId}/invitations`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (companyId: string, id: string, options?: RequestOptions): Promise<CompanyInvitation> =>
        this.request<CompanyInvitation>(
          'GET',
          `/companies/${companyId}/invitations/${id}`,
          options,
        ),

      /** Revokes a pending invitation; its token then stops resolving. */
      delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/companies/${companyId}/invitations/${id}`, options),
    },

    /**
     * The business's own tax registrations, one per kind. A company
     * registration takes precedence over the buyer's own when a sale is for
     * that business, because the invoice is addressed to the entity rather
     * than the person who placed the order.
     */
    taxIdentifiers: {
      list: (
        companyId: string,
        params?: ListParams<TaxIdentifierFilters, TaxIdentifierSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<TaxIdentifier>> =>
        this.request<PaginatedResponse<TaxIdentifier>>(
          'GET',
          `/companies/${companyId}/tax_identifiers`,
          {
            ...options,
            params: params ? transformListParams(params) : undefined,
          },
        ),

      get: (companyId: string, id: string, options?: RequestOptions): Promise<TaxIdentifier> =>
        this.request<TaxIdentifier>(
          'GET',
          `/companies/${companyId}/tax_identifiers/${id}`,
          options,
        ),

      create: (
        companyId: string,
        params: TaxIdentifierCreateParams,
        options?: RequestOptions,
      ): Promise<TaxIdentifier> =>
        this.request<TaxIdentifier>('POST', `/companies/${companyId}/tax_identifiers`, {
          ...options,
          body: params,
        }),

      update: (
        companyId: string,
        id: string,
        params: TaxIdentifierUpdateParams,
        options?: RequestOptions,
      ): Promise<TaxIdentifier> =>
        this.request<TaxIdentifier>('PATCH', `/companies/${companyId}/tax_identifiers/${id}`, {
          ...options,
          body: params,
        }),

      delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/companies/${companyId}/tax_identifiers/${id}`, options),

      /**
       * Asks the registry again. A registry answers only "valid now", so a
       * number verified last year may have been deregistered since. Returns
       * `202` with the check queued.
       */
      validate: (companyId: string, id: string, options?: RequestOptions): Promise<TaxIdentifier> =>
        this.request<TaxIdentifier>(
          'POST',
          `/companies/${companyId}/tax_identifiers/${id}/validate`,
          options,
        ),
    },

    /**
     * Exemption evidence. Certificates start `pending` and exempt nothing
     * until verified; `active` — not `status` — answers whether one exempts a
     * sale, since a verified certificate stops counting once its expiry date
     * passes.
     *
     * Upload the document via `files.upload()` first and pass the
     * returned `signed_id` as `document_signed_id`. To read it back, fetch
     * `document_url` with the `Authorization` header and drive the browser
     * download from a Blob — the bytes are streamed through the API rather
     * than served from storage, so a top-level navigation carrying no JWT
     * will not work.
     */
    taxExemptionCertificates: {
      list: (
        companyId: string,
        params?: ListParams<TaxExemptionCertificateFilters, TaxExemptionCertificateSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<TaxExemptionCertificate>> =>
        this.request<PaginatedResponse<TaxExemptionCertificate>>(
          'GET',
          `/companies/${companyId}/tax_exemption_certificates`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (
        companyId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<TaxExemptionCertificate> =>
        this.request<TaxExemptionCertificate>(
          'GET',
          `/companies/${companyId}/tax_exemption_certificates/${id}`,
          { ...options, params: getParams(params) },
        ),

      create: (
        companyId: string,
        params: TaxExemptionCertificateCreateParams,
        options?: RequestOptions,
      ): Promise<TaxExemptionCertificate> =>
        this.request<TaxExemptionCertificate>(
          'POST',
          `/companies/${companyId}/tax_exemption_certificates`,
          { ...options, body: params },
        ),

      update: (
        companyId: string,
        id: string,
        params: TaxExemptionCertificateUpdateParams,
        options?: RequestOptions,
      ): Promise<TaxExemptionCertificate> =>
        this.request<TaxExemptionCertificate>(
          'PATCH',
          `/companies/${companyId}/tax_exemption_certificates/${id}`,
          { ...options, body: params },
        ),

      /**
       * Accepts the certificate, which is what makes it exempt sales. Only a
       * pending certificate can be accepted. An installation that checks
       * numbers against a registry, or requires a second approval, can refuse
       * here — the refusal arrives as a validation error.
       */
      verify: (
        companyId: string,
        id: string,
        options?: RequestOptions,
      ): Promise<TaxExemptionCertificate> =>
        this.request<TaxExemptionCertificate>(
          'PATCH',
          `/companies/${companyId}/tax_exemption_certificates/${id}/verify`,
          options,
        ),

      /**
       * Withdraws accepted evidence. A verified certificate cannot be deleted
       * — how a sale was taxed has to stay explainable — so this is the way
       * out.
       */
      revoke: (
        companyId: string,
        id: string,
        options?: RequestOptions,
      ): Promise<TaxExemptionCertificate> =>
        this.request<TaxExemptionCertificate>(
          'PATCH',
          `/companies/${companyId}/tax_exemption_certificates/${id}/revoke`,
          options,
        ),

      /** Only a certificate still awaiting a decision can be deleted. */
      delete: (companyId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>(
          'DELETE',
          `/companies/${companyId}/tax_exemption_certificates/${id}`,
          options,
        ),
    },
  }

  // ============================================
  // Catalogs (assortment + optional price list)
  // ============================================

  /**
   * Catalogs narrow what an audience sees and, through an attached price
   * list, what they pay. Audiences are assignments: a channel, a customer
   * group, a market, or a company node (covering its subtree).
   */
  readonly catalogs = {
    list: (
      params?: ListParams<CatalogFilters, CatalogSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Catalog>> =>
      this.request<PaginatedResponse<Catalog>>('GET', '/catalogs', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Catalog> =>
      this.request<Catalog>('GET', `/catalogs/${id}`, { ...options, params: getParams(params) }),

    create: (params: CatalogCreateParams, options?: RequestOptions): Promise<Catalog> =>
      this.request<Catalog>('POST', '/catalogs', { ...options, body: params }),

    update: (id: string, params: CatalogUpdateParams, options?: RequestOptions): Promise<Catalog> =>
      this.request<Catalog>('PATCH', `/catalogs/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/catalogs/${id}`, options),

    /**
     * The catalog's assortment. Rows carry `catalog_price` when asked for
     * with `expand: ['catalog_price']` — what a buyer on this agreement pays
     * and where the amount comes from.
     */
    products: this.productMembership<CatalogProduct>('/catalogs'),

    /**
     * Puts the agreement into effect: its audience starts seeing its
     * assortment and paying its prices. Refused for a catalog nobody is
     * assigned to, which would reach no buyer.
     */
    activate: (id: string, options?: RequestOptions): Promise<Catalog> =>
      this.request<Catalog>('PATCH', `/catalogs/${id}/activate`, options),

    /** Takes it out of effect; everything it holds survives untouched. */
    deactivate: (id: string, options?: RequestOptions): Promise<Catalog> =>
      this.request<Catalog>('PATCH', `/catalogs/${id}/deactivate`, options),

    /**
     * Copies the attached price list's products into the assortment.
     * Explicit by design — an empty assortment is a pricing-only overlay
     * (nothing hidden), so making a catalog restrictive is deliberate.
     */
    importProducts: (id: string, options?: RequestOptions): Promise<{ added_count: number }> =>
      this.request<{ added_count: number }>('POST', `/catalogs/${id}/import_products`, options),

    /** Shows the catalog to an audience. */
    assign: (
      id: string,
      params: CatalogAssignParams,
      options?: RequestOptions,
    ): Promise<CatalogAssignment> =>
      this.request<CatalogAssignment>('POST', `/catalogs/${id}/assign`, {
        ...options,
        body: params,
      }),

    /**
     * A catalog's quantity terms. The catalog-wide default is a pair of
     * fields on the catalog itself, so this is strictly the overrides.
     *
     * Written as a whole set at the grain a merchant states them at (per
     * product, over rows the database keeps per variant). Read them back on
     * the assortment rows instead: `catalogs.products.list(id, { expand:
     * ['quantity_rule'] })`.
     */
    quantityRules: {
      /**
       * Writes the whole set in one request. A product whose pair is both
       * null has its terms cleared; a product not yet in the assortment is
       * added, since a term with nothing to apply to is not a reachable
       * state.
       */
      upsert: (
        catalogId: string,
        params: CatalogProductTermsParams,
        options?: RequestOptions,
      ): Promise<void> =>
        this.request<void>('PUT', `/catalogs/${catalogId}/quantity_rules`, {
          ...options,
          body: params,
        }),
    },

    /** The order minimum in each currency this agreement states one for. */
    orderMinimums: {
      list: (
        catalogId: string,
        params?: ListParams<CatalogOrderMinimumFilters, CatalogOrderMinimumSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<CatalogOrderMinimum>> =>
        this.request<PaginatedResponse<CatalogOrderMinimum>>(
          'GET',
          `/catalogs/${catalogId}/order_minimums`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      create: (
        catalogId: string,
        params: CatalogOrderMinimumParams,
        options?: RequestOptions,
      ): Promise<CatalogOrderMinimum> =>
        this.request<CatalogOrderMinimum>('POST', `/catalogs/${catalogId}/order_minimums`, {
          ...options,
          body: params,
        }),

      update: (
        catalogId: string,
        id: string,
        params: CatalogOrderMinimumParams,
        options?: RequestOptions,
      ): Promise<CatalogOrderMinimum> =>
        this.request<CatalogOrderMinimum>('PATCH', `/catalogs/${catalogId}/order_minimums/${id}`, {
          ...options,
          body: params,
        }),

      delete: (catalogId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/catalogs/${catalogId}/order_minimums/${id}`, options),
    },
  }

  readonly catalogAssignments = {
    /** Withdraws the catalog from an audience. */
    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/catalog_assignments/${id}`, options),
  }

  // ============================================
  // Exports (CSV: products, orders, customers, …)
  // ============================================

  /**
   * Queues asynchronous CSV exports and reports their progress. After
   * `create()`, poll `get(id)` until `done === true`, then fetch
   * `download_url` (with `Authorization: Bearer …`) and drive the browser
   * download via a Blob — top-level navigation cannot carry an in-memory
   * JWT, so `window.location.href = download_url` does not work.
   */
  readonly exports = {
    list: (
      params?: ListParams<ExportFilters, ExportSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Export>> =>
      this.request<PaginatedResponse<Export>>('GET', '/exports', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<Export> =>
      this.request<Export>('GET', `/exports/${id}`, options),

    create: (params: ExportCreateParams, options?: RequestOptions): Promise<Export> =>
      this.request<Export>('POST', '/exports', { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/exports/${id}`, options),
  }

  // ============================================
  // Maintenance tasks
  // ============================================

  /**
   * The upgrade manifest as an ordered checklist: what this release still
   * needs run, the operator notes each step carries, and how each last went.
   *
   * Read-only — running a step is starting the task it names through
   * `maintenanceTaskRuns.create()` with the step's own `task_name` and
   * `arguments`.
   */
  readonly upgradeSteps = {
    list: (options?: RequestOptions): Promise<{ data: UpgradeStep[]; meta: UpgradeStepsMeta }> =>
      this.request<{ data: UpgradeStep[]; meta: UpgradeStepsMeta }>(
        'GET',
        '/upgrade_steps',
        options,
      ),
  }

  /**
   * Runs of a maintenance task — the progress to poll while one is working and
   * the audit trail afterwards (who ran what, with which arguments, and how it
   * ended).
   *
   * After `create()`, poll `get(id)` while `active` is true; show `tick_count`
   * against `tick_total`, or `tick_count` alone when the task could not count
   * its collection. `cancel` stops an active run for good. There is no delete:
   * a run records work that touched merchant data.
   */
  readonly maintenanceTaskRuns = {
    list: (
      params?: ListParams & Record<string, unknown>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<MaintenanceTaskRun>> =>
      this.request<PaginatedResponse<MaintenanceTaskRun>>('GET', '/maintenance_task_runs', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<MaintenanceTaskRun> =>
      this.request<MaintenanceTaskRun>('GET', `/maintenance_task_runs/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (
      params: MaintenanceTaskRunCreateParams,
      options?: RequestOptions,
    ): Promise<MaintenanceTaskRun> =>
      this.request<MaintenanceTaskRun>('POST', '/maintenance_task_runs', {
        ...options,
        body: params,
      }),

    cancel: (id: string, options?: RequestOptions): Promise<MaintenanceTaskRun> =>
      this.request<MaintenanceTaskRun>(
        'POST',
        `/maintenance_task_runs/${id}/cancellation`,
        options,
      ),
  }

  // ============================================
  // Imports (CSV: products, customers, …)
  // ============================================

  /**
   * Queues asynchronous CSV imports and drives the mapping flow. Upload the
   * file via `files.upload()` first, then `create()` the import with
   * the returned `signed_id` as `attachment_signed_id` — the response is in the `mapping` state and
   * carries `schema_fields`, `csv_headers`, a `sample_row` and the
   * auto-assigned `mappings`. Adjust mappings if needed and call
   * `completeMapping(id)` to start processing, then poll `get(id)` while
   * `status` is `completed_mapping`/`processing` (`completed`/`failed` are
   * terminal). Failed rows are listed via `rows.list(id, { status_eq:
   * 'failed' })` (flat Ransack predicates, wrapped into `q[...]` by
   * `transformListParams`) and can be re-processed with `retryFailedRows(id)`.
   */
  readonly imports = {
    list: (
      params?: ListParams<ImportFilters, ImportSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Import>> =>
      this.request<PaginatedResponse<Import>>('GET', '/imports', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<Import> =>
      this.request<Import>('GET', `/imports/${id}`, options),

    create: (params: ImportCreateParams, options?: RequestOptions): Promise<Import> =>
      this.request<Import>('POST', '/imports', { ...options, body: params }),

    completeMapping: (
      id: string,
      params?: ImportCompleteMappingParams,
      options?: RequestOptions,
    ): Promise<Import> =>
      this.request<Import>('PATCH', `/imports/${id}/complete_mapping`, {
        ...options,
        body: params ?? {},
      }),

    retryFailedRows: (id: string, options?: RequestOptions): Promise<Import> =>
      this.request<Import>('PATCH', `/imports/${id}/retry_failed_rows`, options),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/imports/${id}`, options),

    rows: {
      list: (
        importId: string,
        params?: ListParams<ImportRowFilters, ImportRowSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<ImportRow>> =>
        this.request<PaginatedResponse<ImportRow>>('GET', `/imports/${importId}/rows`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),
    },
  }

  // ============================================
  // Customers
  // ============================================

  readonly customers = {
    list: (
      params?: ListParams<CustomerFilters, CustomerSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Customer>> =>
      this.request<PaginatedResponse<Customer>>('GET', '/customers', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<Customer> =>
      this.request<Customer>('GET', `/customers/${id}`, {
        ...options,
        params: getParams(params),
      }),

    creditCards: {
      list: (
        customerId: string,
        params?: ListParams<CreditCardFilters, CreditCardSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<CreditCard>> =>
        this.request<PaginatedResponse<CreditCard>>(
          'GET',
          `/customers/${customerId}/credit_cards`,
          {
            ...options,
            params: params ? transformListParams(params) : undefined,
          },
        ),

      get: (
        customerId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<CreditCard> =>
        this.request<CreditCard>('GET', `/customers/${customerId}/credit_cards/${id}`, {
          ...options,
          params: getParams(params),
        }),

      delete: (customerId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/customers/${customerId}/credit_cards/${id}`, options),
    },

    create: (params: CustomerCreateParams, options?: RequestOptions): Promise<Customer> =>
      this.request<Customer>('POST', '/customers', { ...options, body: params }),

    update: (
      id: string,
      params: CustomerUpdateParams,
      options?: RequestOptions,
    ): Promise<Customer> =>
      this.request<Customer>('PATCH', `/customers/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/customers/${id}`, options),

    /**
     * Everything the store holds about this customer, for answering a GDPR
     * subject access request that arrived by email.
     */
    export: (id: string, options?: RequestOptions): Promise<Record<string, unknown>> =>
      this.request<Record<string, unknown>>('GET', `/customers/${id}/export`, options),

    /**
     * Erases the customer's personal data, keeping the financial record.
     * Irreversible.
     */
    anonymize: (id: string, options?: RequestOptions): Promise<Customer> =>
      this.request<Customer>('POST', `/customers/${id}/anonymize`, options),

    /**
     * Bulk-attach a set of customers to a set of groups. Both arrays carry
     * prefixed IDs; the server decodes them. Idempotent.
     */
    bulkAddToGroups: (
      params: CustomerBulkGroupsParams,
      options?: RequestOptions,
    ): Promise<{ customer_count: number; customer_group_count: number }> =>
      this.request('POST', '/customers/bulk_add_to_groups', { ...options, body: params }),

    /**
     * Bulk-detach a set of customers from a set of groups. No-op for
     * non-members. Same shape as `bulkAddToGroups`.
     */
    bulkRemoveFromGroups: (
      params: CustomerBulkGroupsParams,
      options?: RequestOptions,
    ): Promise<{ customer_count: number; customer_group_count: number }> =>
      this.request('POST', '/customers/bulk_remove_from_groups', { ...options, body: params }),

    /** Add each tag name to every customer. Tags are upserted by name. */
    bulkAddTags: (
      params: BulkTagsParams,
      options?: RequestOptions,
    ): Promise<{ customer_count: number; tag_count: number }> =>
      this.request('POST', '/customers/bulk_add_tags', { ...options, body: params }),

    /** Remove each tag name from every customer. No-op for non-tagged. */
    bulkRemoveTags: (
      params: BulkTagsParams,
      options?: RequestOptions,
    ): Promise<{ customer_count: number; tag_count: number }> =>
      this.request('POST', '/customers/bulk_remove_tags', { ...options, body: params }),

    addresses: {
      list: (
        customerId: string,
        params?: ListParams<AddressFilters, AddressSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<Address>> =>
        this.request<PaginatedResponse<Address>>('GET', `/customers/${customerId}/addresses`, {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      get: (
        customerId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<Address> =>
        this.request<Address>('GET', `/customers/${customerId}/addresses/${id}`, {
          ...options,
          params: getParams(params),
        }),

      create: (
        customerId: string,
        params: CustomerAddressCreateParams,
        options?: RequestOptions,
      ): Promise<Address> =>
        this.request<Address>('POST', `/customers/${customerId}/addresses`, {
          ...options,
          body: params,
        }),

      update: (
        customerId: string,
        id: string,
        params: CustomerAddressUpdateParams,
        options?: RequestOptions,
      ): Promise<Address> =>
        this.request<Address>('PATCH', `/customers/${customerId}/addresses/${id}`, {
          ...options,
          body: params,
        }),

      delete: (customerId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/customers/${customerId}/addresses/${id}`, options),
    },

    /**
     * The customer's own tax registrations — the durable profile value, as
     * opposed to the override entered during a single checkout. A company's
     * registration outranks these when the buyer purchases for a business.
     */
    taxIdentifiers: {
      list: (
        customerId: string,
        params?: ListParams<TaxIdentifierFilters, TaxIdentifierSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<TaxIdentifier>> =>
        this.request<PaginatedResponse<TaxIdentifier>>(
          'GET',
          `/customers/${customerId}/tax_identifiers`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (customerId: string, id: string, options?: RequestOptions): Promise<TaxIdentifier> =>
        this.request<TaxIdentifier>(
          'GET',
          `/customers/${customerId}/tax_identifiers/${id}`,
          options,
        ),

      create: (
        customerId: string,
        params: TaxIdentifierCreateParams,
        options?: RequestOptions,
      ): Promise<TaxIdentifier> =>
        this.request<TaxIdentifier>('POST', `/customers/${customerId}/tax_identifiers`, {
          ...options,
          body: params,
        }),

      update: (
        customerId: string,
        id: string,
        params: TaxIdentifierUpdateParams,
        options?: RequestOptions,
      ): Promise<TaxIdentifier> =>
        this.request<TaxIdentifier>('PATCH', `/customers/${customerId}/tax_identifiers/${id}`, {
          ...options,
          body: params,
        }),

      delete: (customerId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/customers/${customerId}/tax_identifiers/${id}`, options),

      /**
       * Re-asks the registry. Manual because a registry answers only "valid
       * now" — a number verified last year may have been deregistered since.
       */
      validate: (
        customerId: string,
        id: string,
        options?: RequestOptions,
      ): Promise<TaxIdentifier> =>
        this.request<TaxIdentifier>(
          'POST',
          `/customers/${customerId}/tax_identifiers/${id}/validate`,
          options,
        ),
    },

    storeCredits: {
      list: (
        customerId: string,
        params?: ListParams<StoreCreditFilters, StoreCreditSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<StoreCredit>> =>
        this.request<PaginatedResponse<StoreCredit>>(
          'GET',
          `/customers/${customerId}/store_credits`,
          {
            ...options,
            params: params ? transformListParams(params) : undefined,
          },
        ),

      get: (
        customerId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<StoreCredit> =>
        this.request<StoreCredit>('GET', `/customers/${customerId}/store_credits/${id}`, {
          ...options,
          params: getParams(params),
        }),

      create: (
        customerId: string,
        params: CustomerStoreCreditCreateParams,
        options?: RequestOptions,
      ): Promise<StoreCredit> =>
        this.request<StoreCredit>('POST', `/customers/${customerId}/store_credits`, {
          ...options,
          body: params,
        }),

      update: (
        customerId: string,
        id: string,
        params: CustomerStoreCreditUpdateParams,
        options?: RequestOptions,
      ): Promise<StoreCredit> =>
        this.request<StoreCredit>('PATCH', `/customers/${customerId}/store_credits/${id}`, {
          ...options,
          body: params,
        }),

      delete: (customerId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/customers/${customerId}/store_credits/${id}`, options),
    },

    customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.customer),
  }

  /** The consents customers gave or withdrew — evidence of what each one agreed to and when. */
  readonly consentRecords = {
    list: (
      params?: ListParams<ConsentRecordFilters, ConsentRecordSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<ConsentRecord>> =>
      this.request<PaginatedResponse<ConsentRecord>>('GET', '/consent_records', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),
  }

  /** Requests customers made to export (`access`) or erase (`erasure`) their personal data. */
  readonly dataRequests = {
    list: (
      params?: ListParams<DataRequestFilters, DataRequestSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<DataRequest>> =>
      this.request<PaginatedResponse<DataRequest>>('GET', '/data_requests', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    /**
     * Records a request the customer made to the merchant directly and starts
     * answering it. A request of the same kind already in progress is returned
     * instead of a second one.
     */
    create: (params: DataRequestCreateParams, options?: RequestOptions): Promise<DataRequest> =>
      this.request<DataRequest>('POST', '/data_requests', { ...options, body: params }),
  }

  // ============================================
  // Categories
  // ============================================

  /**
   * The media library — every file in the store, whether or not it has been
   * placed on a product. Files are put ON a product through
   * `products.media.create` with a `source_media_id`; this is where they are
   * uploaded, browsed and deleted.
   */
  readonly media = {
    list: (
      params?: ListParams<MediaFilters, MediaSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Media>> =>
      this.request<PaginatedResponse<Media>>('GET', '/media', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<Media> =>
      this.request<Media>('GET', `/media/${id}`, options),

    /** Upload a file before deciding where it goes. */
    create: (params: MediaLibraryCreateParams, options?: RequestOptions): Promise<Media> =>
      this.request<Media>('POST', '/media', { ...options, body: params }),

    update: (
      id: string,
      params: MediaLibraryUpdateParams,
      options?: RequestOptions,
    ): Promise<Media> => this.request<Media>('PATCH', `/media/${id}`, { ...options, body: params }),

    /**
     * Deletes the file. A file still in use is refused (422 with its usage)
     * unless `detach` is set, which removes it from every place using it —
     * product galleries, category and collection images — in one pass.
     * Descriptions embedding it keep a URL that no longer resolves.
     */
    delete: (id: string, params?: { detach?: boolean }, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/media/${id}`, {
        ...options,
        params: params?.detach ? { detach: 'true' } : undefined,
      }),

    /**
     * Where this file is in use. Worth showing before a delete: reuse shares
     * the file, so removing one placement can leave others pointing at it.
     */
    usage: (id: string, options?: RequestOptions): Promise<{ data: MediaUsageReference[] }> =>
      this.request<{ data: MediaUsageReference[] }>('GET', `/media/${id}/usage`, options),
  }

  readonly categories = {
    list: (
      params?: ListParams<CategoryFilters, CategorySort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Category>> =>
      this.request<PaginatedResponse<Category>>('GET', '/categories', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<Category> =>
      this.request<Category>('GET', `/categories/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: CategoryCreateParams, options?: RequestOptions): Promise<Category> =>
      this.request<Category>('POST', '/categories', { ...options, body: params }),

    update: (
      id: string,
      params: CategoryUpdateParams,
      options?: RequestOptions,
    ): Promise<Category> =>
      this.request<Category>('PATCH', `/categories/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/categories/${id}`, options),

    /** Move a category to a new parent and/or index within the tree. */
    reposition: (
      id: string,
      params: CategoryRepositionParams,
      options?: RequestOptions,
    ): Promise<Category> =>
      this.request<Category>('PATCH', `/categories/${id}/reposition`, { ...options, body: params }),

    /** Manual product membership + ordering within a category. */
    products: this.positionedProductMembership('/categories'),

    customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.category),

    translations: this.parentScopedTranslations('/categories'),
  }

  // ============================================
  // Collections
  // ============================================

  readonly collections = {
    list: (
      params?: ListParams<CollectionFilters, CollectionSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Collection>> =>
      this.request<PaginatedResponse<Collection>>('GET', '/collections', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<Collection> =>
      this.request<Collection>('GET', `/collections/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: CollectionCreateParams, options?: RequestOptions): Promise<Collection> =>
      this.request<Collection>('POST', '/collections', { ...options, body: params }),

    /**
     * Collections are a flat list, so reordering one is a plain `position`
     * update — `acts_as_list` shifts its siblings on save and there is no
     * separate reposition action.
     */
    update: (
      id: string,
      params: CollectionUpdateParams,
      options?: RequestOptions,
    ): Promise<Collection> =>
      this.request<Collection>('PATCH', `/collections/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/collections/${id}`, options),

    /**
     * Manual product membership + ordering within a collection. `add`, `remove`
     * and `reposition` are rejected on an automatic collection, whose members
     * are materialized from its rules; `list` works on both.
     */
    products: this.positionedProductMembership('/collections'),

    customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.collection),

    translations: this.parentScopedTranslations('/collections'),
  }

  /**
   * Collection rule kinds. Read-only discovery — rules themselves are written
   * through the owning collection's `rules` array on update. The list is
   * registry-driven server-side, so plugin-registered rules appear here too.
   */
  readonly collectionRules = {
    types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
      this.request<{ data: ResourceTypeDefinition[] }>('GET', '/collection_rules/types', options),
  }

  // ============================================
  // Variants (top-level, for search/autocomplete)
  // ============================================

  readonly variants = {
    list: (
      params?: ListParams<VariantFilters, VariantSort> & VariantSalesContextParams,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Variant>> =>
      this.request<PaginatedResponse<Variant>>('GET', '/variants', {
        ...options,
        params: params ? variantListQuery(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Variant> =>
      this.request<Variant>('GET', `/variants/${id}`, {
        ...options,
        params: getParams(params),
      }),

    customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS.variant),
  }

  // ============================================
  // Tax Categories
  // ============================================

  readonly productTypes = {
    list: (
      params?: ListParams<ProductTypeFilters, ProductTypeSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<ProductType>> =>
      this.request<PaginatedResponse<ProductType>>('GET', '/product_types', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<ProductType> =>
      this.request<ProductType>('GET', `/product_types/${id}`, options),

    create: (params: ProductTypeCreateParams, options?: RequestOptions): Promise<ProductType> =>
      this.request<ProductType>('POST', '/product_types', { ...options, body: params }),

    update: (
      id: string,
      params: ProductTypeUpdateParams,
      options?: RequestOptions,
    ): Promise<ProductType> =>
      this.request<ProductType>('PATCH', `/product_types/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/product_types/${id}`, options),

    /**
     * Backfills the type's option types and categories onto the products that
     * already carry it. Additive — nothing is removed. Runs in the background;
     * the response reports how many products are affected.
     */
    applyToProducts: (
      id: string,
      options?: RequestOptions,
    ): Promise<ProductTypeApplyToProductsResponse> =>
      this.request<ProductTypeApplyToProductsResponse>(
        'POST',
        `/product_types/${id}/apply_to_products`,
        options,
      ),
  }

  readonly taxCategories = {
    list: (
      params?: ListParams<TaxCategoryFilters, TaxCategorySort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<TaxCategory>> =>
      this.request<PaginatedResponse<TaxCategory>>('GET', '/tax_categories', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<TaxCategory> =>
      this.request<TaxCategory>('GET', `/tax_categories/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: TaxCategoryCreateParams, options?: RequestOptions): Promise<TaxCategory> =>
      this.request<TaxCategory>('POST', '/tax_categories', { ...options, body: params }),

    update: (
      id: string,
      params: TaxCategoryUpdateParams,
      options?: RequestOptions,
    ): Promise<TaxCategory> =>
      this.request<TaxCategory>('PATCH', `/tax_categories/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/tax_categories/${id}`, options),
  }

  // ============================================
  // Policies — the store's legal documents
  // ============================================

  /**
   * The store's own policy documents: terms of service, privacy, returns,
   * shipping, and anything else the merchant publishes.
   *
   * Addressable by slug as well as prefixed id. A marketplace seller's
   * policies are theirs and live on the seller API, not here.
   */
  readonly policies = {
    list: (
      params?: ListParams<PolicyFilters, PolicySort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Policy>> =>
      this.request<PaginatedResponse<Policy>>('GET', '/policies', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (idOrSlug: string, options?: RequestOptions): Promise<Policy> =>
      this.request<Policy>('GET', `/policies/${idOrSlug}`, options),

    create: (params: PolicyCreateParams, options?: RequestOptions): Promise<Policy> =>
      this.request<Policy>('POST', '/policies', { ...options, body: params }),

    update: (
      idOrSlug: string,
      params: PolicyUpdateParams,
      options?: RequestOptions,
    ): Promise<Policy> =>
      this.request<Policy>('PATCH', `/policies/${idOrSlug}`, { ...options, body: params }),

    delete: (idOrSlug: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/policies/${idOrSlug}`, options),
  }

  // ============================================
  // Reasons — why a return, claim or refund happened
  // ============================================

  /** Why a customer sent something back. Shared by returns and exchanges. */
  readonly returnReasons = {
    list: (
      params?: ListParams<ReturnReasonFilters, ReturnReasonSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<ReturnReason>> =>
      this.request<PaginatedResponse<ReturnReason>>('GET', '/return_reasons', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<ReturnReason> =>
      this.request<ReturnReason>('GET', `/return_reasons/${id}`, options),

    create: (params: ReasonCreateParams, options?: RequestOptions): Promise<ReturnReason> =>
      this.request<ReturnReason>('POST', '/return_reasons', { ...options, body: params }),

    update: (
      id: string,
      params: ReasonUpdateParams,
      options?: RequestOptions,
    ): Promise<ReturnReason> =>
      this.request<ReturnReason>('PATCH', `/return_reasons/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/return_reasons/${id}`, options),
  }

  /** What went wrong with a delivery — damaged, missing, wrong item. */
  readonly claimReasons = {
    list: (
      params?: ListParams<ClaimReasonFilters, ClaimReasonSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<ClaimReason>> =>
      this.request<PaginatedResponse<ClaimReason>>('GET', '/claim_reasons', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<ClaimReason> =>
      this.request<ClaimReason>('GET', `/claim_reasons/${id}`, options),

    create: (params: ReasonCreateParams, options?: RequestOptions): Promise<ClaimReason> =>
      this.request<ClaimReason>('POST', '/claim_reasons', { ...options, body: params }),

    update: (
      id: string,
      params: ReasonUpdateParams,
      options?: RequestOptions,
    ): Promise<ClaimReason> =>
      this.request<ClaimReason>('PATCH', `/claim_reasons/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/claim_reasons/${id}`, options),
  }

  /** Why an order was called off before it shipped. */
  readonly orderCancellationReasons = {
    list: (
      params?: ListParams<OrderCancellationReasonFilters, OrderCancellationReasonSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<OrderCancellationReason>> =>
      this.request<PaginatedResponse<OrderCancellationReason>>(
        'GET',
        '/order_cancellation_reasons',
        {
          ...options,
          params: params ? transformListParams(params) : undefined,
        },
      ),

    get: (id: string, options?: RequestOptions): Promise<OrderCancellationReason> =>
      this.request<OrderCancellationReason>('GET', `/order_cancellation_reasons/${id}`, options),

    create: (
      params: ReasonCreateParams,
      options?: RequestOptions,
    ): Promise<OrderCancellationReason> =>
      this.request<OrderCancellationReason>('POST', '/order_cancellation_reasons', {
        ...options,
        body: params,
      }),

    update: (
      id: string,
      params: ReasonUpdateParams,
      options?: RequestOptions,
    ): Promise<OrderCancellationReason> =>
      this.request<OrderCancellationReason>('PATCH', `/order_cancellation_reasons/${id}`, {
        ...options,
        body: params,
      }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/order_cancellation_reasons/${id}`, options),
  }

  /**
   * Why a business buys without tax — the reasons a merchant records on a tax
   * exemption certificate. `code` is what the certificate stores and the tax
   * engine receives; `taxProviders.list()` says which codes an engine reads.
   */
  readonly taxExemptionReasons = {
    list: (
      params?: ListParams<TaxExemptionReasonFilters, TaxExemptionReasonSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<TaxExemptionReason>> =>
      this.request<PaginatedResponse<TaxExemptionReason>>('GET', '/tax_exemption_reasons', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<TaxExemptionReason> =>
      this.request<TaxExemptionReason>('GET', `/tax_exemption_reasons/${id}`, options),

    create: (
      params: TaxExemptionReasonCreateParams,
      options?: RequestOptions,
    ): Promise<TaxExemptionReason> =>
      this.request<TaxExemptionReason>('POST', '/tax_exemption_reasons', {
        ...options,
        body: params,
      }),

    update: (
      id: string,
      params: TaxExemptionReasonUpdateParams,
      options?: RequestOptions,
    ): Promise<TaxExemptionReason> =>
      this.request<TaxExemptionReason>('PATCH', `/tax_exemption_reasons/${id}`, {
        ...options,
        body: params,
      }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/tax_exemption_reasons/${id}`, options),
  }

  /**
   * Why money went back. Some rows are seeded and immutable: core looks
   * them up by name, so `can_be_deleted` is false and renaming is refused.
   */
  readonly refundReasons = {
    list: (
      params?: ListParams<RefundReasonFilters, RefundReasonSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<RefundReason>> =>
      this.request<PaginatedResponse<RefundReason>>('GET', '/refund_reasons', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, options?: RequestOptions): Promise<RefundReason> =>
      this.request<RefundReason>('GET', `/refund_reasons/${id}`, options),

    create: (params: ReasonCreateParams, options?: RequestOptions): Promise<RefundReason> =>
      this.request<RefundReason>('POST', '/refund_reasons', { ...options, body: params }),

    update: (
      id: string,
      params: ReasonUpdateParams,
      options?: RequestOptions,
    ): Promise<RefundReason> =>
      this.request<RefundReason>('PATCH', `/refund_reasons/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/refund_reasons/${id}`, options),
  }

  // ============================================
  // Channels (per-store distribution surfaces — online, POS, wholesale)
  // ============================================

  readonly channels = {
    list: (
      params?: ListParams<ChannelFilters, ChannelSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Channel>> =>
      this.request<PaginatedResponse<Channel>>('GET', '/channels', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Channel> =>
      this.request<Channel>('GET', `/channels/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: ChannelCreateParams, options?: RequestOptions): Promise<Channel> =>
      this.request<Channel>('POST', '/channels', { ...options, body: params }),

    update: (id: string, params: ChannelUpdateParams, options?: RequestOptions): Promise<Channel> =>
      this.request<Channel>('PATCH', `/channels/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/channels/${id}`, options),

    /**
     * Publishes the listed products on this channel. Idempotent — re-publishing
     * an already-published product is a no-op for its existing publication
     * window unless +published_at+ / +unpublished_at+ are explicitly passed.
     * Cross-store onboarding is allowed: if the caller's API key has update
     * permission on a product owned by a sibling store, that product is
     * co-published onto this channel. Products the caller can't update are
     * silently dropped.
     */
    addProducts: (
      id: string,
      params: ChannelAddProductsParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number }> =>
      this.request<{ product_count: number }>('POST', `/channels/${id}/add_products`, {
        ...options,
        body: params,
      }),

    /** Unpublishes the listed products from this channel. */
    removeProducts: (
      id: string,
      params: ChannelRemoveProductsParams,
      options?: RequestOptions,
    ): Promise<{ product_count: number }> =>
      this.request<{ product_count: number }>('POST', `/channels/${id}/remove_products`, {
        ...options,
        body: params,
      }),

    /**
     * Order routing rules — the channel's prioritized list of signals the
     * `Rules` routing strategy walks when choosing fulfillment locations.
     * Rule kinds are discovered via `client.orderRoutingRules.types()`.
     */
    orderRoutingRules: {
      list: (
        channelId: string,
        params?: ListParams<OrderRoutingRuleFilters, OrderRoutingRuleSort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<OrderRoutingRule>> =>
        this.request<PaginatedResponse<OrderRoutingRule>>(
          'GET',
          `/channels/${channelId}/order_routing_rules`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (channelId: string, id: string, options?: RequestOptions): Promise<OrderRoutingRule> =>
        this.request<OrderRoutingRule>(
          'GET',
          `/channels/${channelId}/order_routing_rules/${id}`,
          options,
        ),

      create: (
        channelId: string,
        params: OrderRoutingRuleCreateParams,
        options?: RequestOptions,
      ): Promise<OrderRoutingRule> =>
        this.request<OrderRoutingRule>('POST', `/channels/${channelId}/order_routing_rules`, {
          ...options,
          body: params,
        }),

      update: (
        channelId: string,
        id: string,
        params: OrderRoutingRuleUpdateParams,
        options?: RequestOptions,
      ): Promise<OrderRoutingRule> =>
        this.request<OrderRoutingRule>(
          'PATCH',
          `/channels/${channelId}/order_routing_rules/${id}`,
          { ...options, body: params },
        ),

      delete: (channelId: string, id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/channels/${channelId}/order_routing_rules/${id}`, options),
    },
  }

  readonly orderRoutingRules = {
    types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>
      this.request<{ data: ResourceTypeDefinition[] }>(
        'GET',
        '/order_routing_rules/types',
        options,
      ),
  }

  /**
   * Markets — store-scoped pricing regions. Each market binds one or more
   * countries to a currency, a default locale, and a tax-display policy.
   * Drives label resolution for `Spree::PriceRules::MarketRule` and is the
   * unit that price lists target.
   */
  readonly markets = {
    list: (
      params?: ListParams<MarketFilters, MarketSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Market>> =>
      this.request<PaginatedResponse<Market>>('GET', '/markets', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Market> =>
      this.request<Market>('GET', `/markets/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: MarketCreateParams, options?: RequestOptions): Promise<Market> =>
      this.request<Market>('POST', '/markets', { ...options, body: params }),

    update: (id: string, params: MarketUpdateParams, options?: RequestOptions): Promise<Market> =>
      this.request<Market>('PATCH', `/markets/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/markets/${id}`, options),
  }

  // ============================================
  // Stock Locations
  // ============================================

  readonly stockLocations = {
    list: (
      params?: ListParams<StockLocationFilters, StockLocationSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<StockLocation>> =>
      this.request<PaginatedResponse<StockLocation>>('GET', '/stock_locations', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<StockLocation> =>
      this.request<StockLocation>('GET', `/stock_locations/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: StockLocationCreateParams, options?: RequestOptions): Promise<StockLocation> =>
      this.request<StockLocation>('POST', '/stock_locations', { ...options, body: params }),

    update: (
      id: string,
      params: StockLocationUpdateParams,
      options?: RequestOptions,
    ): Promise<StockLocation> =>
      this.request<StockLocation>('PATCH', `/stock_locations/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/stock_locations/${id}`, options),
  }

  // ============================================
  // Stock Levels
  // ============================================

  readonly stockLevels = {
    list: (
      params?: ListParams<StockLevelFilters, StockLevelSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<StockLevel>> =>
      this.request<PaginatedResponse<StockLevel>>('GET', '/stock_levels', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<StockLevel> =>
      this.request<StockLevel>('GET', `/stock_levels/${id}`, {
        ...options,
        params: getParams(params),
      }),

    update: (
      id: string,
      params: StockLevelUpdateParams,
      options?: RequestOptions,
    ): Promise<StockLevel> =>
      this.request<StockLevel>('PATCH', `/stock_levels/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/stock_levels/${id}`, options),

    /**
     * Sets stock levels for many (variant, location) pairs at once — what a
     * warehouse feed posts on a schedule. Rows name their variant and location
     * either by Spree id or by an external reference, so a feed can use the
     * keys it already holds.
     *
     * Each change is recorded as a stock movement, so the history stays
     * intact. Response is `{ stock_level_count }`.
     */
    bulkUpsert: (
      params: StockLevelBulkUpsertParams,
      options?: RequestOptions,
    ): Promise<{ stock_level_count: number }> =>
      this.request('POST', '/stock_levels/bulk_upsert', { ...options, body: params }),
  }

  // ============================================
  // Stock Movements
  // ============================================

  // Read-only: a movement records something that already happened to stock.
  // Reversing one means writing its counterpart through the resource that
  // caused it.
  readonly stockMovements = {
    list: (
      params?: ListParams<StockMovementFilters, StockMovementSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<StockMovement>> =>
      this.request<PaginatedResponse<StockMovement>>('GET', '/stock_movements', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<StockMovement> =>
      this.request<StockMovement>('GET', `/stock_movements/${id}`, {
        ...options,
        params: getParams(params),
      }),
  }

  // ============================================
  // Stock Reservations
  // ============================================

  /**
   * Stock held for orders being checked out, so it cannot be sold twice
   * before they complete or the hold expires. Read-only: holds are placed and
   * released by checkout.
   */
  readonly stockReservations = {
    list: (
      params?: ListParams<StockReservationFilters, StockReservationSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<StockReservation>> =>
      this.request<PaginatedResponse<StockReservation>>('GET', '/stock_reservations', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),
  }

  // ============================================
  // Stock Transfers
  // ============================================

  /**
   * Stock moving between two of the merchant's own warehouses. A transfer is a
   * trip: `create` records a plan, `markInTransit` takes the units off the
   * source shelf, and each delivery the destination counts in is a stock
   * receipt (`stockReceipts.create`). Receiving from a supplier is a purchase
   * order, not a transfer.
   */
  readonly stockTransfers = {
    list: (
      params?: ListParams<StockTransferFilters, StockTransferSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<StockTransfer>> =>
      this.request<PaginatedResponse<StockTransfer>>('GET', '/stock_transfers', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<StockTransfer> =>
      this.request<StockTransfer>('GET', `/stock_transfers/${id}`, {
        ...options,
        params: getParams(params),
      }),

    /** Persists a draft. Nothing moves until `markInTransit`. */
    create: (params: StockTransferCreateParams, options?: RequestOptions): Promise<StockTransfer> =>
      this.request<StockTransfer>('POST', '/stock_transfers', { ...options, body: params }),

    /** Drafts only: past that, what is in the box is a matter of record. */
    update: (
      id: string,
      params: StockTransferUpdateParams,
      options?: RequestOptions,
    ): Promise<StockTransfer> =>
      this.request<StockTransfer>('PATCH', `/stock_transfers/${id}`, { ...options, body: params }),

    /** Drafts only: anything that has shipped is cancelled, not deleted. */
    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/stock_transfers/${id}`, options),

    /** Freezes the lines without taking anything off the shelf. */
    markReady: (id: string, options?: RequestOptions): Promise<StockTransfer> =>
      this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/mark_ready`, options),

    /**
     * The van has left: writes the source's `shipped` movements. Pass
     * `force` to ship anyway when the shelf cannot cover it.
     */
    markInTransit: (
      id: string,
      params?: StockTransferMarkInTransitParams,
      options?: RequestOptions,
    ): Promise<StockTransfer> =>
      this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/mark_in_transit`, {
        ...options,
        body: params,
      }),

    /** Unfreezes a ready-to-ship transfer; nothing has left the source yet. */
    markDraft: (id: string, options?: RequestOptions): Promise<StockTransfer> =>
      this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/mark_draft`, options),
    /**
     * Ends a partially received transfer whose missing units are not going to
     * turn up. Nothing moves; the outstanding count stays on each line.
     */
    close: (
      id: string,
      params?: ReceivableCloseParams,
      options?: RequestOptions,
    ): Promise<StockTransfer> =>
      this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/close`, {
        ...options,
        body: params,
      }),
    /**
     * The deliveries the destination counted in. Creating one is how a
     * transfer is received: this delivery's counts, accepted and refused,
     * per line — a second box adds to the first.
     */
    stockReceipts: {
      list: (
        stockTransferId: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<PaginatedResponse<StockReceipt>> =>
        this.request<PaginatedResponse<StockReceipt>>(
          'GET',
          `/stock_transfers/${stockTransferId}/stock_receipts`,
          { ...options, params: getParams(params) },
        ),
      get: (
        stockTransferId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<StockReceipt> =>
        this.request<StockReceipt>(
          'GET',
          `/stock_transfers/${stockTransferId}/stock_receipts/${id}`,
          { ...options, params: getParams(params) },
        ),
      create: (
        stockTransferId: string,
        params?: StockReceiptCreateParams,
        options?: RequestOptions,
      ): Promise<StockReceipt> =>
        this.request<StockReceipt>('POST', `/stock_transfers/${stockTransferId}/stock_receipts`, {
          ...options,
          body: params,
        }),
    },
    cancel: (
      id: string,
      params?: StockTransferCancelParams,
      options?: RequestOptions,
    ): Promise<StockTransfer> =>
      this.request<StockTransfer>('PATCH', `/stock_transfers/${id}/cancel`, {
        ...options,
        body: params,
      }),
  }

  // ============================================
  // Suppliers
  // ============================================

  /** The merchant's supplier address book. */
  readonly suppliers = {
    list: (
      params?: ListParams<SupplierFilters, SupplierSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Supplier>> =>
      this.request<PaginatedResponse<Supplier>>('GET', '/suppliers', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<Supplier> =>
      this.request<Supplier>('GET', `/suppliers/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: SupplierCreateParams, options?: RequestOptions): Promise<Supplier> =>
      this.request<Supplier>('POST', '/suppliers', { ...options, body: params }),

    update: (
      id: string,
      params: SupplierUpdateParams,
      options?: RequestOptions,
    ): Promise<Supplier> =>
      this.request<Supplier>('PATCH', `/suppliers/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/suppliers/${id}`, options),
  }

  // ============================================
  // Purchase Orders
  // ============================================

  /**
   * Goods bought from a supplier. Ordered units never count toward
   * availability: nothing reaches the shelf until a delivery is booked in as
   * a stock receipt (`stockReceipts.create`).
   */
  readonly purchaseOrders = {
    list: (
      params?: ListParams<PurchaseOrderFilters, PurchaseOrderSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<PurchaseOrder>> =>
      this.request<PaginatedResponse<PurchaseOrder>>('GET', '/purchase_orders', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<PurchaseOrder> =>
      this.request<PurchaseOrder>('GET', `/purchase_orders/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: PurchaseOrderCreateParams, options?: RequestOptions): Promise<PurchaseOrder> =>
      this.request<PurchaseOrder>('POST', '/purchase_orders', { ...options, body: params }),

    /** Drafts only: a placed order is a matter of record with the supplier. */
    update: (
      id: string,
      params: PurchaseOrderUpdateParams,
      options?: RequestOptions,
    ): Promise<PurchaseOrder> =>
      this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/purchase_orders/${id}`, options),

    /** Sends the order: freezes the lines and starts the expected-date clock. */
    markOrdered: (id: string, options?: RequestOptions): Promise<PurchaseOrder> =>
      this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/mark_ordered`, options),

    /** Reopens a placed order for editing, while no delivery has been booked. */
    markDraft: (id: string, options?: RequestOptions): Promise<PurchaseOrder> =>
      this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/mark_draft`, options),
    /**
     * Ends a partially received order whose balance the supplier will not
     * deliver. What arrived stays; the outstanding count stays on each line.
     */
    close: (
      id: string,
      params?: ReceivableCloseParams,
      options?: RequestOptions,
    ): Promise<PurchaseOrder> =>
      this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/close`, {
        ...options,
        body: params,
      }),
    /**
     * The deliveries booked against an order. Creating one is how an order is
     * received: this delivery's counts, accepted and refused, per line, at
     * the line's cost — a second delivery adds to the first.
     */
    stockReceipts: {
      list: (
        purchaseOrderId: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<PaginatedResponse<StockReceipt>> =>
        this.request<PaginatedResponse<StockReceipt>>(
          'GET',
          `/purchase_orders/${purchaseOrderId}/stock_receipts`,
          { ...options, params: getParams(params) },
        ),
      get: (
        purchaseOrderId: string,
        id: string,
        params?: { expand?: string[] },
        options?: RequestOptions,
      ): Promise<StockReceipt> =>
        this.request<StockReceipt>(
          'GET',
          `/purchase_orders/${purchaseOrderId}/stock_receipts/${id}`,
          { ...options, params: getParams(params) },
        ),
      create: (
        purchaseOrderId: string,
        params?: StockReceiptCreateParams,
        options?: RequestOptions,
      ): Promise<StockReceipt> =>
        this.request<StockReceipt>('POST', `/purchase_orders/${purchaseOrderId}/stock_receipts`, {
          ...options,
          body: params,
        }),
    },
    cancel: (
      id: string,
      params?: PurchaseOrderCancelParams,
      options?: RequestOptions,
    ): Promise<PurchaseOrder> =>
      this.request<PurchaseOrder>('PATCH', `/purchase_orders/${id}/cancel`, {
        ...options,
        body: params,
      }),
  }

  // ============================================
  // Countries
  // ============================================

  readonly countries = {
    list: (
      params?: ListParams & Record<string, unknown>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Country>> =>
      this.request<PaginatedResponse<Country>>('GET', '/countries', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      iso: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<Country> =>
      this.request<Country>('GET', `/countries/${iso}`, {
        ...options,
        params: getParams(params),
      }),
  }

  // ============================================
  // Files
  // ============================================

  /**
   * Uploading the files other endpoints use — product media, imports, logos,
   * documents. Each upload returns a `signed_id`: pass it unchanged to the
   * endpoint that uses the file (`signed_id`, `avatar_signed_id`,
   * `attachment_signed_id`, …) within a day, after which it expires.
   */
  readonly files = {
    /**
     * Creates an upload. JSON metadata returns `upload`, the storage target to
     * send the bytes to; a `FormData` body with a `file` part stores the bytes
     * directly and returns `upload: null`. `upload()` does both steps for you.
     */
    create: (
      params: FileUploadCreateParams | FormData,
      options?: RequestOptions,
    ): Promise<FileUpload> =>
      this.request<FileUpload>('POST', '/files', { ...options, body: params }),

    /**
     * Uploads a file and resolves to the response; its `signed_id` is what the
     * endpoint that uses the file takes. Pass `visibility: 'private'` for
     * documents, imports and digital products.
     */
    upload: (
      file: Blob,
      options: UploadFileOptions = {},
      requestOptions?: RequestOptions,
    ): Promise<FileUpload> =>
      uploadFile((body) => this.files.create(body, requestOptions), file, options),
  }

  // ============================================
  // Staff (admin users with role assignment on the current store)
  // ============================================

  readonly adminUsers = {
    list: (
      params?: ListParams<AdminUserFilters, AdminUserSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<AdminUser>> =>
      this.request<PaginatedResponse<AdminUser>>('GET', '/admin_users', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<AdminUser> =>
      this.request<AdminUser>('GET', `/admin_users/${id}`, {
        ...options,
        params: getParams(params),
      }),

    update: (
      id: string,
      params: AdminUserUpdateParams,
      options?: RequestOptions,
    ): Promise<AdminUser> =>
      this.request<AdminUser>('PATCH', `/admin_users/${id}`, { ...options, body: params }),

    /**
     * Removes the user's role assignments on the current store. The account is
     * preserved — the user keeps access to any other stores. Mirrors the
     * legacy "remove from staff" behaviour rather than the legacy controller's
     * hard delete.
     */
    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/admin_users/${id}`, options),
  }

  // ============================================
  // Invitations (pending staff invitations)
  // ============================================

  readonly invitations = {
    list: (
      params?: ListParams<InvitationFilters, InvitationSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Invitation>> =>
      this.request<PaginatedResponse<Invitation>>('GET', '/invitations', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<Invitation> =>
      this.request<Invitation>('GET', `/invitations/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: InvitationCreateParams, options?: RequestOptions): Promise<Invitation> =>
      this.request<Invitation>('POST', '/invitations', { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/invitations/${id}`, options),

    /** Issues a fresh token + email for a pending invitation. */
    resend: (id: string, options?: RequestOptions): Promise<Invitation> =>
      this.request<Invitation>('PATCH', `/invitations/${id}/resend`, options),

    /**
     * The acceptance link of a pending invitation. It carries the token, so it
     * needs write access to staff and the right to grant the invitation's role.
     */
    acceptanceLink: (id: string, options?: RequestOptions): Promise<InvitationAcceptanceLink> =>
      this.request<InvitationAcceptanceLink>('GET', `/invitations/${id}/acceptance_link`, options),
  }

  // ============================================
  // API Keys (publishable + secret)
  // ============================================

  /**
   * OAuth 2.1 consent, for the screen a merchant approves when an agent or an
   * app asks for access to the store.
   *
   * `authorization` describes what is being asked for; `approve` and `deny`
   * both answer with the `redirect_uri` the browser should then be sent to.
   * These require a signed-in admin: a secret key authenticates but is not a
   * person, so it can never grant authority on someone's behalf.
   */
  readonly oauth = {
    authorization: (
      params: OauthAuthorizationParams,
      options?: RequestOptions,
    ): Promise<OauthConsentRequest> =>
      this.request<OauthConsentRequest>('GET', '/oauth/authorize', {
        ...options,
        // The authorization request is a flat set of strings by construction,
        // so it travels as query params untouched — no Ransack wrapping, and
        // nothing re-derived on the way.
        params: { ...params } as Record<string, string | undefined>,
      }),

    approve: (params: OauthAuthorizationParams, options?: RequestOptions): Promise<OauthRedirect> =>
      this.request<OauthRedirect>('POST', '/oauth/authorize', { ...options, body: params }),

    deny: (params: OauthAuthorizationParams, options?: RequestOptions): Promise<OauthRedirect> =>
      this.request<OauthRedirect>('DELETE', '/oauth/authorize', { ...options, body: params }),

    /** The OAuth clients registered against this store. */
    applications: {
      list: (
        params?: ListParams & Record<string, unknown>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<OauthApplication>> =>
        this.request<PaginatedResponse<OauthApplication>>('GET', '/oauth/applications', {
          ...options,
          params: params ? transformListParams(params) : undefined,
        }),

      create: (
        params: { name: string; redirect_uri: string },
        options?: RequestOptions,
      ): Promise<OauthApplication> =>
        this.request<OauthApplication>('POST', '/oauth/applications', {
          ...options,
          body: params,
        }),

      update: (
        id: string,
        params: Partial<{ name: string; redirect_uri: string }>,
        options?: RequestOptions,
      ): Promise<OauthApplication> =>
        this.request<OauthApplication>('PATCH', `/oauth/applications/${id}`, {
          ...options,
          body: params,
        }),

      /** Removes the registration, and every grant and token with it. */
      delete: (id: string, options?: RequestOptions): Promise<void> =>
        this.request<void>('DELETE', `/oauth/applications/${id}`, options ?? {}),

      /**
       * The live access a connected client holds, one entry per person who
       * connected it. A store registers a client once and everyone connects
       * to that same registration, so this is who is actually connected.
       */
      tokens: {
        list: (
          applicationId: string,
          params?: ListParams,
          options?: RequestOptions,
        ): Promise<PaginatedResponse<OauthAccessToken>> =>
          this.request<PaginatedResponse<OauthAccessToken>>(
            'GET',
            `/oauth/applications/${applicationId}/tokens`,
            { ...(options ?? {}), params: params ? transformListParams(params) : undefined },
          ),

        /**
         * Revokes one person's access, leaving their colleagues connected.
         */
        delete: (applicationId: string, id: string, options?: RequestOptions): Promise<void> =>
          this.request<void>(
            'DELETE',
            `/oauth/applications/${applicationId}/tokens/${id}`,
            options ?? {},
          ),
      },
    },
  }

  readonly apiKeys = {
    list: (
      params?: ListParams<ApiKeyFilters, ApiKeySort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<ApiKey>> =>
      this.request<PaginatedResponse<ApiKey>>('GET', '/api_keys', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<ApiKey> =>
      this.request<ApiKey>('GET', `/api_keys/${id}`, {
        ...options,
        params: getParams(params),
      }),

    /**
     * Describes the key that authenticated this request, including its live
     * scopes — useful to show the real, current authority of a secret key
     * (e.g. after a scope change) rather than a cached snapshot. Only available
     * to secret-key principals; a JWT admin has no single key to describe.
     */
    current: (options?: RequestOptions): Promise<ApiKey> =>
      this.request<ApiKey>('GET', '/api_keys/current', options ?? {}),

    /**
     * Creates a publishable or secret API key. For secret keys the response
     * carries `plaintext_token` exactly once — store it client-side immediately
     * because subsequent reads will return `null`.
     */
    create: (params: ApiKeyCreateParams, options?: RequestOptions): Promise<ApiKey> =>
      this.request<ApiKey>('POST', '/api_keys', { ...options, body: params }),

    /**
     * Updates a key's `name`. `key_type` and `scopes` are fixed at creation —
     * to change authority, create a new key and revoke the old one (`revoke`).
     */
    update: (id: string, params: ApiKeyUpdateParams, options?: RequestOptions): Promise<ApiKey> =>
      this.request<ApiKey>('PATCH', `/api_keys/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/api_keys/${id}`, options),

    /** Marks a key revoked without deleting the row (preserves audit history). */
    revoke: (id: string, options?: RequestOptions): Promise<ApiKey> =>
      this.request<ApiKey>('PATCH', `/api_keys/${id}/revoke`, options),
  }

  // ============================================
  // Allowed Origins (CORS allowlist for admin cookie auth)
  // ============================================

  /**
   * Origins permitted to call the admin API from a browser. Backs the
   * `Rack::Cors` allowlist and the CSRF boundary of the admin cookie session
   * (see `docs/plans/5.5-admin-auth-cookie-refresh.md`). Each entry is a
   * bare `scheme://host[:port]` — no paths, queries, or fragments.
   */
  readonly allowedOrigins = {
    list: (
      params?: ListParams<AllowedOriginFilters, AllowedOriginSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<AllowedOrigin>> =>
      this.request<PaginatedResponse<AllowedOrigin>>('GET', '/allowed_origins', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<AllowedOrigin> =>
      this.request<AllowedOrigin>('GET', `/allowed_origins/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: AllowedOriginCreateParams, options?: RequestOptions): Promise<AllowedOrigin> =>
      this.request<AllowedOrigin>('POST', '/allowed_origins', { ...options, body: params }),

    update: (
      id: string,
      params: AllowedOriginUpdateParams,
      options?: RequestOptions,
    ): Promise<AllowedOrigin> =>
      this.request<AllowedOrigin>('PATCH', `/allowed_origins/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/allowed_origins/${id}`, options),
  }

  // ============================================
  // Webhook Endpoints + Deliveries
  // ============================================

  readonly emailTemplates = {
    /** Every editable email template: customer emails, the layout and shared partials. */
    list: (
      params?: EmailTemplateLanguageParams,
      options?: RequestOptions,
    ): Promise<{ data: EmailTemplate[] }> =>
      this.request<{ data: EmailTemplate[] }>('GET', '/email_templates', { ...options, params }),

    /** One template in one language, with the draft (`expand: ['draft.updated_by']` names who saved it). */
    get: (
      id: string,
      params?: EmailTemplateLanguageParams & { expand?: string[] },
      options?: RequestOptions,
    ): Promise<EmailTemplate> =>
      this.request<EmailTemplate>('GET', `/email_templates/${id}`, {
        ...options,
        // getParams keeps only expand and fields, so the language is added back.
        params: {
          ...getParams(params),
          ...(params?.language ? { language: params.language } : {}),
        },
      }),

    /** Goes back to Spree's default and discards the draft. Published versions stay in the history. */
    revert: (
      id: string,
      params?: EmailTemplateVersionParams,
      options?: RequestOptions,
    ): Promise<EmailTemplate> =>
      this.request<EmailTemplate>('DELETE', `/email_templates/${id}`, { ...options, params }),

    draft: {
      /** Saves the draft. A save from a stale `lock_version` is refused with 409. */
      update: (
        id: string,
        params: EmailTemplateDraftParams,
        options?: RequestOptions,
      ): Promise<EmailTemplate> =>
        this.request<EmailTemplate>('PUT', `/email_templates/${id}/draft`, {
          ...options,
          body: params,
        }),

      delete: (
        id: string,
        params?: EmailTemplateVersionParams,
        options?: RequestOptions,
      ): Promise<EmailTemplate> =>
        this.request<EmailTemplate>('DELETE', `/email_templates/${id}/draft`, {
          ...options,
          params,
        }),
    },

    /** Makes the draft live; refused with 422 and each problem's email and line when it does not render. */
    publish: (
      id: string,
      params?: EmailTemplateVersionParams,
      options?: RequestOptions,
    ): Promise<EmailTemplate> =>
      this.request<EmailTemplate>('POST', `/email_templates/${id}/publication`, {
        ...options,
        body: params ?? {},
      }),

    /** Renders the template, or unsaved changes to it, with sample data. */
    preview: (
      id: string,
      params?: EmailTemplatePreviewParams,
      options?: RequestOptions,
    ): Promise<EmailTemplatePreview> =>
      this.request<EmailTemplatePreview>('POST', `/email_templates/${id}/preview`, {
        ...options,
        body: params ?? {},
      }),

    /** Sends the rendered template to the signed-in admin. */
    sendTest: (
      id: string,
      params?: EmailTemplatePreviewParams,
      options?: RequestOptions,
    ): Promise<{ sent_to: string }> =>
      this.request<{ sent_to: string }>('POST', `/email_templates/${id}/test_email`, {
        ...options,
        body: params ?? {},
      }),

    sampleRecords: {
      /** The store's latest records the template can be previewed with, newest first. */
      list: (
        id: string,
        params?: { email_key?: string },
        options?: RequestOptions,
      ): Promise<{ data: EmailTemplateSampleRecord[] }> =>
        this.request<{ data: EmailTemplateSampleRecord[] }>(
          'GET',
          `/email_templates/${id}/sample_records`,
          { ...options, params },
        ),
    },

    revisions: {
      /** Published versions in one language, newest first. */
      list: (
        id: string,
        params?: ListParams & EmailTemplateLanguageParams & Record<string, unknown>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<EmailTemplateRevision>> =>
        this.request<PaginatedResponse<EmailTemplateRevision>>(
          'GET',
          `/email_templates/${id}/revisions`,
          {
            ...options,
            // The language picks the version, so it stays out of the Ransack filters.
            params: params
              ? (({ language, ...list }) => ({
                  ...transformListParams(list),
                  ...(language ? { language } : {}),
                }))(params)
              : undefined,
          },
        ),

      /** Copies a revision into the draft, to publish like any change. */
      restore: (
        id: string,
        revisionId: string,
        params?: EmailTemplateRestoreParams,
        options?: RequestOptions,
      ): Promise<EmailTemplate> =>
        this.request<EmailTemplate>(
          'POST',
          `/email_templates/${id}/revisions/${revisionId}/restoration`,
          { ...options, body: params ?? {} },
        ),
    },
  }

  /**
   * The events a webhook endpoint can subscribe to, including those installed
   * extensions declare. A `credential` event carries a live credential and
   * needs `credential_permission` to subscribe to; a `deprecated` one names the
   * event that replaces it in `replaced_by`.
   */
  readonly webhookEvents = {
    list: (options?: RequestOptions): Promise<{ data: WebhookEvent[]; meta: { count: number } }> =>
      this.request<{ data: WebhookEvent[]; meta: { count: number } }>(
        'GET',
        '/webhook_events',
        options,
      ),
  }

  /**
   * Outbound webhook subscriptions: each endpoint receives a signed POST when
   * any subscribed event fires (`subscriptions` is a list of event names or
   * `*` patterns). The plaintext `secret_key` is returned **once** on create —
   * persist it client-side immediately because later reads serialize `null`.
   * Each endpoint exposes a nested `deliveries` log for auditing and retry.
   */
  readonly webhookEndpoints = {
    list: (
      params?: ListParams<WebhookEndpointFilters, WebhookEndpointSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<WebhookEndpoint>> =>
      this.request<PaginatedResponse<WebhookEndpoint>>('GET', '/webhook_endpoints', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (
      id: string,
      params?: { expand?: string[] },
      options?: RequestOptions,
    ): Promise<WebhookEndpoint> =>
      this.request<WebhookEndpoint>('GET', `/webhook_endpoints/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (
      params: WebhookEndpointCreateParams,
      options?: RequestOptions,
    ): Promise<WebhookEndpoint> =>
      this.request<WebhookEndpoint>('POST', '/webhook_endpoints', { ...options, body: params }),

    update: (
      id: string,
      params: WebhookEndpointUpdateParams,
      options?: RequestOptions,
    ): Promise<WebhookEndpoint> =>
      this.request<WebhookEndpoint>('PATCH', `/webhook_endpoints/${id}`, {
        ...options,
        body: params,
      }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/webhook_endpoints/${id}`, options),

    /** Fires a synthetic `webhook.test` delivery so admins can verify reachability. */
    sendTest: (id: string, options?: RequestOptions): Promise<WebhookDelivery> =>
      this.request<WebhookDelivery>('POST', `/webhook_endpoints/${id}/send_test`, options),

    /** Re-enables an endpoint that was disabled (manually or after auto-disable). */
    enable: (id: string, options?: RequestOptions): Promise<WebhookEndpoint> =>
      this.request<WebhookEndpoint>('PATCH', `/webhook_endpoints/${id}/enable`, options),

    /** Manually disable an endpoint with an optional human-readable reason. */
    disable: (
      id: string,
      params?: WebhookEndpointDisableParams,
      options?: RequestOptions,
    ): Promise<WebhookEndpoint> =>
      this.request<WebhookEndpoint>('PATCH', `/webhook_endpoints/${id}/disable`, {
        ...options,
        body: params,
      }),

    deliveries: {
      list: (
        endpointId: string,
        params?: ListParams<WebhookDeliveryFilters, WebhookDeliverySort>,
        options?: RequestOptions,
      ): Promise<PaginatedResponse<WebhookDelivery>> =>
        this.request<PaginatedResponse<WebhookDelivery>>(
          'GET',
          `/webhook_endpoints/${endpointId}/deliveries`,
          { ...options, params: params ? transformListParams(params) : undefined },
        ),

      get: (endpointId: string, id: string, options?: RequestOptions): Promise<WebhookDelivery> =>
        this.request<WebhookDelivery>(
          'GET',
          `/webhook_endpoints/${endpointId}/deliveries/${id}`,
          options,
        ),

      /**
       * Creates a new delivery row with the same payload + event_name and
       * queues it. The original row is preserved for audit history.
       */
      redeliver: (
        endpointId: string,
        id: string,
        options?: RequestOptions,
      ): Promise<WebhookDelivery> =>
        this.request<WebhookDelivery>(
          'POST',
          `/webhook_endpoints/${endpointId}/deliveries/${id}/redeliver`,
          options,
        ),
    },
  }

  // ============================================
  // Roles (staff roles + catalog permissions)
  // ============================================

  readonly roles = {
    list: (
      params?: ListParams<RoleFilters, RoleSort>,
      options?: RequestOptions,
    ): Promise<PaginatedResponse<Role>> =>
      this.request<PaginatedResponse<Role>>('GET', '/roles', {
        ...options,
        params: params ? transformListParams(params) : undefined,
      }),

    get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Role> =>
      this.request<Role>('GET', `/roles/${id}`, {
        ...options,
        params: getParams(params),
      }),

    create: (params: RoleCreateParams, options?: RequestOptions): Promise<Role> =>
      this.request<Role>('POST', '/roles', { ...options, body: params }),

    update: (id: string, params: RoleUpdateParams, options?: RequestOptions): Promise<Role> =>
      this.request<Role>('PATCH', `/roles/${id}`, { ...options, body: params }),

    delete: (id: string, options?: RequestOptions): Promise<void> =>
      this.request<void>('DELETE', `/roles/${id}`, options),
  }

  // ============================================
  // Permissions (the grant vocabulary — read-only catalog)
  // ============================================

  readonly permissions = {
    list: (options?: RequestOptions): Promise<{ data: Permission[]; meta: { count: number } }> =>
      this.request<{ data: Permission[]; meta: { count: number } }>('GET', '/permissions', options),
  }
}

// Re-export for type convenience
export type {
  EmailPasswordLogin,
  ListParams,
  LoginCredentials,
  PaginatedResponse,
  ProviderLogin,
  RequestOptions,
}