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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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
}