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.

27.0 KB
Raw Blame
import type { PackageTypeKind, PickupStockPolicy } from '@spree/core'
/**
 * The client registry.
 *
 * `@spree/dashboard-core` is the framework behind more than one panel: the
 * marketplace operator's dashboard talks to the Admin API, a seller's panel
 * talks to the Seller API. Those are different surfaces with different
 * credentials — a seller JWT and `X-Spree-Seller-Id` rather than a secret key
 * and a store header — so the framework cannot own either client. Each host
 * builds its own and registers it here at boot.
 *
 * Only the surface both panels share is typed. Anything admin-only
 * (`customFieldDefinitions`, `imports`, store switching) stays on the admin
 * client, imported directly by the code that needs it — typing it here would
 * promise the seller panel methods its API does not have.
 */

import type {
  DigitalAssetProvider,
  PaginationMeta,
  PermissionRule,
  UploadFileOptions,
} from '@spree/admin-sdk'
import type { CountryCode, DimensionUnit, WeightUnit } from '@spree/core'

/** What a panel may change on the signed-in person's own account. */
export interface PanelAccountParams {
  first_name?: string
  last_name?: string
  /** The panel's UI language, as a bundle code the panel ships (e.g. `de`). */
  selected_locale?: string
  /**
   * A `signed_id` from an upload to set the photo, or `null` to remove it. Omit to
   * leave the current one alone — the only field here where `null` means
   * something the API acts on.
   */
  avatar_signed_id?: string | null
}

/**
 * The account fields both panels' `/me` answer with. Deliberately the subset
 * they share — anything one API alone returns stays on its own client.
 */
export interface PanelAccountUser {
  id: string
  email: string
  first_name?: string | null
  last_name?: string | null
  full_name?: string | null
  selected_locale?: string | null
  avatar_url?: string | null
}

/** What the permission provider needs, whichever panel asked. */
export interface PanelPermissions {
  /**
   * CanCanCan rules. The seller panel returns none — its capability is the
   * key list alone — so an empty array is a valid answer, not a failure.
   */
  rules: PermissionRule[]
  keys: string[]
}

/** What every panel's client can do, whichever API it talks to. */
export interface PanelApiClient {
  auth: {
    login(params: { email: string; password: string }): Promise<PanelSession>
    refresh(): Promise<PanelSession>
    logout(): Promise<void>
    /**
     * Optional sign-in flows, because not every panel offers all of them.
     * Both panels accept invitations and reset passwords — each against its
     * own API, so the session that comes back carries the right audience and
     * the emailed link opens the right panel. First-run setup remains the
     * marketplace's own, so a seller's client leaves it undefined.
     */
    acceptInvitation?(id: string, token: string, params: unknown): Promise<PanelSession>
    resetPassword?(token: string, params: unknown): Promise<PanelSession>
    completeSetup?(params: unknown): Promise<PanelSession>
  }
  setToken(token: string): void
  onUnauthorized(handler: () => Promise<boolean>): void
  /**
   * Forgets which tenant the session was acting as — the store on the admin
   * panel, the seller on a seller's. Left set, it rides into the next
   * principal's first requests and 403s them against a tenant they may hold
   * no role on.
   */
  clearTenant?(): void
  /**
   * Reads the signed-in principal's capability. Panel-specific because the
   * two APIs answer different shapes: the admin `/me` returns CanCanCan rules
   * and keys, the seller `/me` returns keys scoped to the selected seller.
   */
  fetchPermissions(): Promise<PanelPermissions>
  /**
   * Countries (with their states) for the shared address form.
   *
   * Registered rather than imported, for the same reason as everything else
   * here: reaching for `adminClient` would make the one address form work
   * only in the operator's panel, and a seller filling in a billing address
   * would get an empty country list.
   */
  listCountries?(): Promise<{ data: PanelCountry[] }>
  /**
   * Stock locations, for the shared management page.
   *
   * Both panels manage the same records against their own branch — the
   * operator every location in the store, a seller only their own, scoped
   * server-side. `delete` is optional because a seller's API does not offer
   * it: a location holds stock levels and is named on historical
   * fulfillments, so they retire one by deactivating it.
   */
  /**
   * Uploads a file through the panel's own `POST /files` and resolves to its
   * `signed_id`.
   *
   * Registered rather than imported for the same reason as everything else
   * here: the shared upload field would otherwise work only in the
   * operator's panel, and a seller uploading an onboarding document would
   * get a 401 from an API they hold no key for.
   */
  uploadFile?(file: File, options: UploadFileOptions): Promise<{ signed_id: string }>
  /**
   * Writes the signed-in person's own account — their name, photo and the
   * panel's language.
   *
   * Registered rather than imported for the same reason as everything else
   * here: the account menu's language switcher is one shared component, and
   * reaching for `adminClient` inside it would send a seller's language
   * change to an API they hold no credential for.
   *
   * Required, unlike most of this contract: the account menu lives in the
   * shared sidebar, so every panel mounting the shell already offers the
   * language switcher that calls this. An optional marker would describe a
   * host that does not exist and push a runtime guard onto every caller.
   */
  updateAccount(params: PanelAccountParams): Promise<{ user: PanelAccountUser }>
  stockLocations?: {
    list(params?: Record<string, unknown>): Promise<{ data: PanelStockLocation[]; meta?: unknown }>
    get(id: string): Promise<PanelStockLocation>
    create(params: PanelStockLocationCreateParams): Promise<PanelStockLocation>
    update(id: string, params: PanelStockLocationParams): Promise<PanelStockLocation>
    delete?(id: string): Promise<void>
  }
  /**
   * The reference data the shared product form reads: the option types a
   * variant is built from, and the categories, collections and product types
   * a product is filed under.
   *
   * Registered for the same reason as everything above — the form is one set
   * of cards serving both panels, and reaching for `adminClient` inside them
   * would leave a seller with empty pickers. Each is optional: a panel that
   * offers no such picker simply does not register it, and the card hides.
   */
  optionTypes?: {
    list(params?: Record<string, unknown>): Promise<{ data: PanelOptionType[] }>
    /**
     * Naming a new option (Size, Colour) while building a variant matrix.
     * Operator-only: a seller names options inline on the variant instead,
     * so their client leaves these out and the builder hides.
     *
     * `name` and `label` are named rather than left to a loose record — they
     * are what the API requires, and a contract that did not say so would
     * push the check to a cast at the registration site.
     */
    create?(
      params: { name: string; label: string } & Record<string, unknown>,
    ): Promise<PanelOptionType>
    update?(
      id: string,
      params: { option_values?: Array<{ name: string; label: string }> } & Record<string, unknown>,
    ): Promise<PanelOptionType>
  }
  categories?: {
    list(params?: Record<string, unknown>): Promise<{ data: PanelNamedRecord[] }>
  }
  collections?: {
    list(params?: Record<string, unknown>): Promise<{ data: PanelCollection[] }>
  }
  productTypes?: {
    list(params?: Record<string, unknown>): Promise<{ data: PanelProductType[] }>
    get(id: string): Promise<PanelProductType>
  }
  /**
   * Tax category is marketplace configuration a seller does not write, so
   * their client registers none and the card that reads it hides.
   *
   * Delivery profiles are different: the marketplace defines them, but a
   * seller assigns one to their own product — it decides how their goods can
   * be shipped at all — so both panels register this one
   * (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
   */
  taxCategories?: {
    list(params?: Record<string, unknown>): Promise<{ data: PanelNamedRecord[] }>
  }
  deliveryProfiles?: {
    list(params?: Record<string, unknown>): Promise<{ data: PanelDeliveryProfile[] }>
  }
  /**
   * The packaging this panel can see: the boxes parcels ship in, the cartons
   * products are packed into, the pallets a wholesale order leaves on.
   *
   * `list` alone is enough for the variant editor's carton picker, which is
   * why the write methods are optional — a panel that only needs the picker
   * registers `list` and the packaging settings page is simply not routed.
   */
  packageTypes?: PanelPackageTypeReads | PanelPackageTypeWrites
  /**
   * Headers a file download must carry beyond the bearer token.
   *
   * A download is a bare `fetch`, not an SDK call, so it bypasses whatever
   * the client normally attaches — which on the seller panel is
   * `X-Spree-Seller-Id`, and without it every Seller API request is refused
   * before the action runs. The admin panel needs none, so it registers none.
   */
  downloadHeaders?(): Record<string, string>
  /**
   * Queuing a CSV export and reading it back.
   *
   * Registered rather than imported for the same reason as everything else
   * here: the export dialog is one component serving both panels, and
   * reaching for `adminClient` inside it would make a seller's export request
   * go out against an API they hold no key for.
   *
   * Which datasets may be exported is the API's business, not this
   * contract's — each panel offers its own list, and the server refuses the
   * rest. A panel that offers no export simply registers none, and the button
   * hides.
   */
  exports?: {
    create(params: PanelExportCreateParams): Promise<PanelExport>
    get(id: string): Promise<PanelExport>
  }
  /** Removing a file already on a product. */
  deleteProductMedia?(productId: string, mediaId: string): Promise<void>
  /**
   * The downloadable files a digital product delivers to its buyers.
   *
   * Registered rather than imported for the same reason as everything else
   * here: the Digital files card is one component serving both panels.
   * `providers` is operator-only — a provider is the marketplace's own code
   * reaching into its internal systems — so a seller's client leaves it out
   * and the card offers file uploads alone.
   */
  digitalAssets?: {
    list(
      productId: string,
      params?: { page?: number; limit?: number },
    ): Promise<{ data: PanelDigitalAsset[]; meta?: PaginationMeta }>
    create(productId: string, params: PanelDigitalAssetParams): Promise<PanelDigitalAsset>
    update(
      productId: string,
      id: string,
      params: PanelDigitalAssetParams,
    ): Promise<PanelDigitalAsset>
    delete(productId: string, id: string): Promise<void>
    providers?(productId: string): Promise<{ data: DigitalAssetProvider[] }>
  }
  /**
   * The store-wide media library, for placing a file already uploaded onto
   * another product. Operator-only: a seller sees their own product's files,
   * never the marketplace's library, so their client registers none and the
   * "add from library" affordance hides.
   */
  mediaLibrary?: {
    list(params?: Record<string, unknown>): Promise<{ data: PanelMediaRecord[] }>
  }
  /**
   * CSV imports, for whichever catalog this panel manages.
   *
   * Registered rather than imported for the same reason as everything else
   * here: the wizard is one component serving both panels, and reaching for
   * `adminClient` inside it would leave a seller uploading against an API
   * they hold no key for.
   *
   * Structural, not either SDK's type — the two branches serve the same
   * payload from parallel serializers, and the wizard reads only what both
   * carry. `templateUrl` and `exampleUrl` are functions rather than fixed
   * strings because each panel's endpoints live under its own branch, and the
   * download helpers take a URL rather than a resource method (they stream
   * with the caller's JWT).
   */
  imports?: {
    list(params?: Record<string, unknown>): Promise<{ data: PanelImport[]; meta?: PanelPageMeta }>
    get(id: string): Promise<PanelImport>
    create(params: PanelImportCreateParams): Promise<PanelImport>
    completeMapping(id: string, params?: PanelImportCompleteMappingParams): Promise<PanelImport>
    retryFailedRows(id: string): Promise<PanelImport>
    delete(id: string): Promise<void>
    rows: {
      list(
        importId: string,
        params?: Record<string, unknown>,
      ): Promise<{ data: PanelImportRow[]; meta?: PanelPageMeta }>
    }
    /** Which datasets this panel may import — the wizard offers no others. */
    types: readonly string[]
    /**
     * Query-key roots a finished import should mark stale, on top of the
     * defaults core invalidates.
     *
     * The pipeline writes records server-side, outside any tracked mutation,
     * so nothing else ever marks those lists stale — and each panel names its
     * lists differently (the operator's products table is keyed `products`,
     * a seller's `seller-products`). A panel that does not name its own keys
     * gets a list still serving its pre-import cache, which reads as an
     * import that silently did nothing.
     */
    invalidateKeys?: readonly string[]
    /**
     * Paths to this panel's import endpoints, relative to the API origin.
     *
     * Root-relative on purpose: `downloadFromApi` resolves them against
     * `VITE_SPREE_API_URL` and sends the JWT only when the result is that
     * origin, so a panel pointed at a different API host must set that
     * variable too (both starters feed the client and the download path from
     * it). An absolute URL to another host is safe but pointless — the token
     * is withheld and the request will not authenticate.
     */
    templateUrl(type: string): string
    exampleUrl(type: string): string
    downloadUrl(id: string): string
  }
  /**
   * The store's tag vocabulary. Operator-only: tags are tenanted to the store
   * (`acts_as_taggable_tenant :store_id`), so a seller typing a new one would
   * be writing into the marketplace's own namespace.
   */
  tags?: {
    list(params?: Record<string, unknown>): Promise<{ data: Array<{ name: string }> }>
  }
}

export interface PanelDeliveryProfile extends PanelNamedRecord {
  default?: boolean
}

export interface PanelPackageType extends PanelNamedRecord {
  kind?: string
  /**
   * Read alongside the name so a picker can tell two cartons apart. Decimals
   * arrive as strings, as every measurement on the wire does.
   */
  length?: string | null
  width?: string | null
  height?: string | null
  dimensions_unit?: string | null
  /** The empty package's own weight, added to every quote. */
  weight?: string | null
  max_weight?: string | null
  weight_unit?: string | null
  /** Cubic meters, derived; null until every side is measured. */
  volume?: string | null
  /** The box this owner's parcels are quoted with — one per owner. */
  default?: boolean
  /**
   * False on a row this panel may read but not change: the seller panel lists
   * the marketplace's packaging so a seller knows what they can pack into,
   * and every write against it is refused. Absent on the operator's own
   * serializer, where every row is theirs, so the page treats undefined as
   * editable.
   */
  editable?: boolean
  /** Operator-only; the seller panel's serializer leaves it out. */
  metadata?: Record<string, unknown> | null
  /** Whose packaging this is; null is the marketplace's own. */
  seller_id?: string | null
  seller_name?: string | null
  created_at?: string
  updated_at?: string
}

/**
 * Measurements written back for a package type. Every field optional: the
 * form sends the whole shape on create, and a partial one when a single
 * measurement changes.
 */
export interface PanelPackageTypeParams {
  name?: string
  /**
   * Narrow rather than `string`, because both SDKs validate the vocabulary at
   * the type level and a widened contract would not assign to either.
   */
  kind?: PanelPackageTypeKind
  length?: number | null
  width?: number | null
  height?: number | null
  dimensions_unit?: DimensionUnit | null
  weight?: number | null
  max_weight?: number | null
  weight_unit?: WeightUnit | null
  default?: boolean
  /**
   * Not nullable: both SDKs take a merge, so clearing a key is sending the
   * object without it rather than sending null.
   */
  metadata?: Record<string, unknown>
}

/**
 * Enough for the variant editor's carton picker: a panel that only needs the
 * picker registers this and never routes to the packaging settings page.
 */
export interface PanelPackageTypeReads {
  list(params?: Record<string, unknown>): Promise<{ data: PanelPackageType[]; meta?: unknown }>
}

/**
 * What the packaging settings page needs. Required rather than optional, so a
 * panel that routes to the page while registering reads only fails to
 * compile instead of rendering a page whose every write throws.
 */
export interface PanelPackageTypeWrites extends PanelPackageTypeReads {
  get(id: string): Promise<PanelPackageType>
  create(params: PanelPackageTypeCreateParams): Promise<PanelPackageType>
  update(id: string, params: PanelPackageTypeParams): Promise<PanelPackageType>
  delete?(id: string): Promise<void>
}

/** @deprecated Use `PackageTypeKind` from `@spree/core`. */
export type PanelPackageTypeKind = PackageTypeKind
/** @deprecated Use `DimensionUnit` from `@spree/core`. */
export type PanelPackageDimensionUnit = DimensionUnit
/** @deprecated Use `WeightUnit` from `@spree/core`. */
export type PanelPackageWeightUnit = WeightUnit

/**
 * A new row must say what it is and what to call it — packaging without
 * either cannot exist, and neither SDK makes them optional.
 */
export type PanelPackageTypeCreateParams = PanelPackageTypeParams & {
  name: string
  kind: PanelPackageTypeKind
}

/**
 * One CSV import, as the shared wizard reads it: the mapping payload while
 * `mapping`, the poll counters once processing starts.
 */
export interface PanelImport {
  id: string
  /** Human-facing identifier shown in the wizard header (`IM1001`). */
  number: string
  type: string | null
  status: string
  rows_count: number
  completed_rows_count: number
  failed_rows_count: number
  processing_errors?: string | null
  delimiter?: string
  schema_fields: Array<{ name: string; label: string; required: boolean }>
  csv_headers: string[]
  sample_row: Record<string, string | null>
  mappings: Array<{ schema_field: string; file_column: string | null; required: boolean }>
  original_filename?: string | null
  original_byte_size?: number | null
  original_file_url?: string | null
  /** The list a `price_list_prices` import merges into; null elsewhere. */
  price_list_id?: string | null
  created_at?: string
  updated_at?: string
}

/**
 * Pagination meta, as both APIs answer it. Structural for the same reason the
 * records are: the two branches serve one shape and the shared UI reads only
 * what both carry.
 */
export interface PanelPageMeta {
  count: number
  page: number
  pages: number
  from?: number
  to?: number
}

/** One row of an import — the failure report's unit. */
export interface PanelImportRow {
  id: string
  row_number: number
  status: string
  validation_errors?: string | null
  data?: Record<string, string | null>
}

export interface PanelImportCreateParams {
  type: string
  /** The `signed_id` of the already uploaded CSV. */
  attachment_signed_id: string
  /** CSV column separator — the four both APIs accept. */
  delimiter?: PanelImportDelimiter
  /** The price list a `price_list_prices` import merges into. */
  price_list_id?: string
  results_url?: string
}

/** The column separators the import upload form offers. */
export type PanelImportDelimiter = ',' | ';' | '|' | '\t'

export interface PanelImportCompleteMappingParams {
  mappings?: Array<{ schema_field: string; file_column: string | null }>
}

/**
 * What either panel sends to queue an export.
 *
 * `type` stays a plain string: the operator's registry and a seller's
 * allowlist are different sets, and each SDK narrows it to its own.
 */
export interface PanelExportCreateParams {
  type: string
  search_params?: Record<string, unknown>
  record_selection?: 'filtered' | 'all'
  results_url?: string
}

/**
 * An export as the dialog polls it. Structural rather than either SDK's
 * type — both serializers carry exactly this, and what only one of them adds
 * is not the dialog's business.
 */
export interface PanelExport {
  id: string
  done: boolean
  download_url?: string | null
  filename?: string | null
}

/**
 * A downloadable file, as the Digital files card reads it. Structural, like
 * the other records here: both serializers carry these fields, and only the
 * operator's adds `provider_settings`.
 */
export interface PanelDigitalAsset {
  id: string
  variant_id: string | null
  filename: string | null
  content_type: string | null
  byte_size: number | null
  /** Null means the store's download settings apply. */
  authorized_clicks: number | null
  authorized_days: number | null
  /** The limits in force, after the store-settings fallback. */
  effective_authorized_clicks: number
  effective_authorized_days: number
  provider_type: string | null
  provider_name: string
  download_url: string | null
  provider_settings?: Record<string, unknown>
}

/**
 * What either panel writes. The provider fields are the operator's alone; a
 * seller's API refuses them.
 */
export interface PanelDigitalAssetParams {
  signed_id?: string
  variant_id?: string
  authorized_clicks?: number | null
  authorized_days?: number | null
  provider_type?: string
  provider_settings?: Record<string, unknown>
}

/** A library file, as the picker lists it. */
export interface PanelMediaRecord {
  id: string
  alt?: string | null
  small_url?: string | null
  original_url?: string | null
}

/** Anything the form lists by name in a picker. */
export interface PanelNamedRecord {
  id: string
  name: string
}

/**
 * A rule-based collection fills itself, so the form offers only manual ones
 * to pick from.
 */
export interface PanelCollection extends PanelNamedRecord {
  automatic?: boolean
}

/**
 * An option type as the variants builder reads it. Structural, like
 * PanelStockLocation: both serializers carry the name and its values, and
 * what only one of them adds is not the form's business.
 */
export interface PanelOptionType {
  id: string
  name: string
  label: string
  kind?: string
  position?: number
  option_values?: Array<{
    id: string
    name: string
    label: string
    position?: number
    color_code?: string | null
  }>
}

export interface PanelProductType {
  id: string
  name: string
  option_type_ids?: string[]
  /**
   * The option types picking this type will add, already named. A panel that
   * manages no option-type vocabulary (a seller's) cannot resolve
   * `option_type_ids` against a list it never loads, so its API sends the
   * labels instead and the form reads whichever it was given.
   */
  option_type_labels?: string[]
  category_ids?: string[]
  custom_field_definitions?: unknown[]
}

/**
 * A stock location as the shared page reads it.
 *
 * Structural rather than either SDK's type: the two serializers overlap on
 * everything this page shows, and the fields only one of them carries
 * (`admin_name`, `propagate_all_variants`) are optional here so the page can
 * hide what a panel does not send.
 */
export interface PanelStockLocation {
  id: string
  name: string
  admin_name?: string | null
  kind: string
  active: boolean
  default: boolean
  propagate_all_variants?: boolean
  backorderable_default?: boolean
  address1?: string | null
  address2?: string | null
  city?: string | null
  zipcode?: string | null
  phone?: string | null
  company?: string | null
  country_code?: CountryCode | null
  state_code?: string | null
  state_name?: string | null
  /** Rendered read-only in the table; either panel's serializer derives it. */
  state_text?: string | null
  pickup_enabled?: boolean
  /** Whether this location accepts goods coming back. */
  returns_enabled?: boolean
  /** Open on read — a serializer answers whatever is stored. */
  pickup_stock_policy?: string
  pickup_ready_in_minutes?: number | null
  pickup_instructions?: string | null
  /** Operator-only; the seller panel's serializer leaves it out. */
  external_references?: Record<string, string>
}

/**
 * What either panel accepts when updating one — every field optional, since
 * a caller may be writing a single toggle.
 */
export type PanelStockLocationParams = Partial<
  Omit<PanelStockLocation, 'id' | 'pickup_stock_policy'>
> & {
  /**
   * Narrowed on write where the read type is open: `kind` stays a free string
   * because plugins register their own, but the pickup policy is a fixed pair
   * the server validates, and both SDKs type it that way.
   */
  pickup_stock_policy?: PickupStockPolicy
}

/**
 * Creating one additionally requires a name, matching both APIs: a location
 * without one cannot exist, and neither SDK makes it optional.
 */
export type PanelStockLocationCreateParams = PanelStockLocationParams & { name: string }

/**
 * A country as the address form needs it. Structural, not the Admin SDK's
 * `Country`: both panels' country endpoints answer this shape, and typing
 * the wider one here would bind core to a package a seller's panel does not
 * install.
 */
export interface PanelCountry {
  iso: CountryCode
  iso3: string
  states_required?: boolean
  zipcode_required?: boolean
  states?: Array<{ abbr: string; name: string }>
}

/** What a sign-in returns, whichever panel asked. */
export interface PanelSession {
  token: string
  // Panel-specific: an AdminUser here, the same class through the seller API.
  // Typed loosely so core does not depend on either package's user type.
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  user: any
}

let registered: PanelApiClient | null = null

/**
 * Registers the client for this panel. Call once at boot, before rendering —
 * providers read it on mount.
 */
export function setApiClient(client: PanelApiClient): void {
  registered = client
}

/**
 * The registered client.
 *
 * Throws rather than returning null: a panel that renders without registering
 * one is misconfigured, and every call would otherwise fail somewhere further
 * away with a less useful message.
 */
export function getApiClient(): PanelApiClient {
  if (!registered) {
    throw new Error(
      '@spree/dashboard-core: no API client registered. Call setApiClient(client) at boot, ' +
        'before rendering the app.',
    )
  }

  return registered
}

/** Whether a client has been registered. For tests and conditional boot paths. */
export function hasApiClient(): boolean {
  return registered !== null
}

/**
 * Hands filters built at runtime to a typed SDK list method. A table builds
 * its filters from its column definitions, and a page shared by both panels
 * sends the same keys to two APIs with different filter types, so neither can
 * be checked by the compiler; the API validates them instead.
 */
export function runtimeListParams<P>(params?: Record<string, unknown>): P {
  return params as P
}