@spree/seller-dashboard 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vendo Connect Inc., Vendo Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @spree/seller-dashboard
+
+The React seller panel for [Spree Commerce](https://spreecommerce.org) marketplaces — the surface a seller signs into to manage their products, orders and fulfillments. Built on the [Seller API](https://spreecommerce.org/docs/api-reference/seller-api/introduction) via `@spree/seller-sdk`.
+
+> **Beta.** Published under the `beta` tag while Spree 6.0 is in beta, and
+> promoted to `latest` at 6.0 GA. Install it explicitly:
+>
+> ```bash
+> npm install @spree/seller-dashboard@beta
+> ```
+
+It shares its primitives with `@spree/dashboard` — components from `@spree/dashboard-ui`, framework pieces from `@spree/dashboard-core` — so the two panels stay visually and behaviourally consistent.
+
+## Usage
+
+Host it from a thin app that renders `<SellerDashboard />`. Scaffold one with:
+
+```bash
+npx spree add seller-dashboard
+```
+
+Rails serves the built bundle at `/sellers` when `SPREE_SELLER_PANEL_DIST_PATH` points at it — the Docker image built from the Spree starter does this for you.
+
+## Documentation
+
+- [Seller API reference](https://spreecommerce.org/docs/api-reference/seller-api/introduction) — the API this panel is built on
+- [Spree developer documentation](https://spreecommerce.org/docs)
+
+## License
+
+MIT

package/dist/vite-plugin/index.js

@@ -0,0 +1,51 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import {
+  spreeDashboardPlugin as spreeDashboardCorePlugin
+} from "@spree/dashboard-core/vite";
+import { TanStackRouterVite } from "@tanstack/router-plugin/vite";
+import { index, layout, physical, rootRoute, route } from "@tanstack/virtual-file-routes";
+function spreeSellerDashboardPlugin(options = {}) {
+  const hostRoot = options.root ?? process.cwd();
+  return [
+    // This shell is always scanned, whatever the host passes. Core defaults to
+    // the operator's dashboard, which a seller's host does not install — and a
+    // host naming its own shell is adding one, not replacing the panel whose
+    // components it renders. Overwriting instead of merging drops the panel's
+    // classes from the production CSS, and only in a built bundle.
+    ...spreeDashboardCorePlugin({
+      ...options,
+      shellPackages: ["@spree/seller-dashboard", ...options.shellPackages ?? []]
+    }),
+    sellerRouterPlugin(hostRoot, options)
+  ];
+}
+function sellerRouterPlugin(hostRoot, options) {
+  const fromHost = createRequire(path.join(hostRoot, "package.json"));
+  const shellEntry = fromHost.resolve("@spree/seller-dashboard");
+  const shellRoutesDir = path.join(path.dirname(shellEntry), "routes");
+  const virtualRouteConfig = rootRoute("__root.tsx", [
+    route("/login", "login.tsx"),
+    route("/forgot-password", "forgot-password.tsx"),
+    route("/reset-password", "reset-password.tsx"),
+    route("/accept-invitation/$invitationId", "accept-invitation.$invitationId.tsx"),
+    layout("_authenticated.tsx", [
+      index("_authenticated/index.tsx"),
+      route("/$sellerId", "_authenticated/$sellerId.tsx", [
+        physical("", "_authenticated/$sellerId")
+      ])
+    ])
+  ]);
+  return TanStackRouterVite({
+    target: "react",
+    virtualRouteConfig,
+    routesDirectory: shellRoutesDir,
+    generatedRouteTree: path.resolve(
+      hostRoot,
+      options.generatedRouteTree ?? "src/routeTree.gen.ts"
+    )
+  });
+}
+export {
+  spreeSellerDashboardPlugin
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@spree/seller-dashboard",
+  "version": "1.0.0-beta.1",
+  "license": "MIT",
+  "type": "module",
+  "description": "Spree marketplace seller panel — the seller-facing counterpart to the admin dashboard.",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles.css": "./src/styles.css",
+    "./vite": {
+      "types": "./src/vite/index.ts",
+      "default": "./dist/vite-plugin/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist/vite-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@hookform/resolvers": "^5.2.2",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@tanstack/react-query": "^5.90.2",
+    "@tanstack/react-router": "^1.133.32",
+    "@tanstack/router-plugin": "^1.167.35",
+    "@tanstack/virtual-file-routes": "^1.162.0",
+    "i18next": "^26.2.0",
+    "lucide-react": "^0.545.0",
+    "react-hook-form": "^7.65.0",
+    "react-i18next": "^17.0.8",
+    "zod": "^4.4.3",
+    "@spree/dashboard-ui": "1.0.0-beta.1",
+    "@spree/seller-sdk": "1.0.0-beta.1",
+    "@spree/dashboard-core": "1.0.0-beta.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.13",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1",
+    "@vitejs/plugin-react": "^6.0.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tsup": "^8.5.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.0"
+  },
+  "scripts": {
+    "build": "pnpm generate:routes && tsup",
+    "typecheck": "tsc -b",
+    "lint": "biome check .",
+    "lint:fix": "biome check --fix .",
+    "format": "biome format --write .",
+    "generate:routes": "node scripts/generate-routes.mjs"
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,203 @@
+import { setApiClient } from '@spree/dashboard-core'
+import type { SellerApiClient, SellerExportCreateParams } from '@spree/seller-sdk'
+import { createSellerClient } from '@spree/seller-sdk'
+
+/**
+ * Which seller the signed-in user is acting as.
+ *
+ * Kept out of React state because the client needs it on every request,
+ * including ones fired before any component renders. The URL is the real
+ * source of truth — the `$sellerId` route layout writes it here as it renders
+ * — and this copy is only what the request headers read.
+ */
+const SELLER_STORAGE_KEY = 'spree.seller.id'
+
+let client: SellerApiClient | null = null
+
+/**
+ * The seller the client is currently sending, mirrored here because the SDK
+ * keeps it in a closure with no reader.
+ *
+ * Not the same thing as the stored choice: a browser that blocks storage
+ * (private mode, sandboxed iframe) still runs the panel perfectly well, and
+ * `rememberSeller` sets the client either way. Reading `localStorage` to
+ * answer "who are we acting as" would come back empty in exactly those
+ * sessions and drop the header off every file download.
+ */
+let activeSellerId: string | null = null
+
+/**
+ * Builds the Seller API client and registers it with the shared framework.
+ *
+ * The host calls this once at boot, before rendering. `@spree/dashboard-core`
+ * is the framework behind both panels, so it cannot own either client — the
+ * operator's dashboard registers an Admin API client the same way.
+ *
+ * Leave `baseUrl` unset for relative URLs, so the Vite dev proxy (or a
+ * static-host rewrite in production) keeps the panel same-origin with the API
+ * — which is what lets the seller refresh cookie ride under `SameSite=Lax`
+ * without HTTPS. Set it only for a genuinely cross-origin deployment.
+ */
+export function createSellerApiClient({
+  baseUrl = '',
+}: {
+  baseUrl?: string
+} = {}): SellerApiClient {
+  client = createSellerClient({ baseUrl })
+
+  const remembered = rememberedSeller()
+  if (remembered) setActiveSeller(remembered)
+
+  setApiClient({
+    auth: client.auth,
+    setToken: (token: string) => sellerClient().setToken(token),
+    onUnauthorized: (handler) => sellerClient().onUnauthorized(handler),
+    // A stale seller header would ride into the next seller's first requests
+    // and 403 them against a seller they may hold no role on.
+    clearTenant: forgetSeller,
+    fetchPermissions: async () => {
+      const response = await sellerClient().me()
+
+      // Both shapes, exactly as the operator's dashboard receives them. The
+      // framework's `<Can>` reads CanCanCan rules; the key list is what the
+      // API's own gate enforces. Dropping the rules here (an earlier version
+      // did) left every `<Can>` on the panel answering false — silently.
+      return { rules: response.permissions ?? [], keys: response.permission_keys ?? [] }
+    },
+    // The shared address form reads countries through the registered client,
+    // so it works in a panel that has no admin credential.
+    listCountries: () => sellerClient().countries.list(),
+    createDirectUpload: (params) => sellerClient().directUploads.create(params),
+    // A file download is a bare fetch, so it does not go through the client
+    // and picks up none of its headers. Without the seller header the Seller
+    // API refuses the request before the action runs, so an export would
+    // generate fine and then fail to download.
+    downloadHeaders: (): Record<string, string> =>
+      activeSellerId ? { 'X-Spree-Seller-Id': activeSellerId } : {},
+    // Backs the shared export dialog, the same one the operator's dashboard
+    // renders. The Seller API narrows what may be exported to records that
+    // can be scoped to one seller, and refuses anything else.
+    exports: {
+      create: (params) => sellerClient().exports.create(params as SellerExportCreateParams),
+      get: (id) => sellerClient().exports.get(id),
+    },
+    // Backs the shared CSV import wizard. Products only: customers belong to
+    // the marketplace and translations of catalog copy are its merchandising,
+    // so the Seller API refuses both and the wizard offers neither.
+    imports: {
+      list: (params) => sellerClient().imports.list(params),
+      get: (id) => sellerClient().imports.get(id),
+      create: (params) =>
+        sellerClient().imports.create({
+          ...params,
+          // Narrowed by the API too — this only keeps the SDK's own type
+          // honest about what this branch accepts.
+          type: params.type as 'products',
+        }),
+      completeMapping: (id, params) => sellerClient().imports.completeMapping(id, params),
+      retryFailedRows: (id) => sellerClient().imports.retryFailedRows(id),
+      delete: (id) => sellerClient().imports.delete(id),
+      rows: { list: (importId, params) => sellerClient().imports.rows.list(importId, params) },
+      types: ['products'],
+      // This panel's product list is keyed `seller-products`, so core's
+      // default `products` invalidation would miss it and the list would sit
+      // on its pre-import cache.
+      invalidateKeys: ['seller-products'],
+      templateUrl: (type) => `/api/v3/seller/imports/template?type=${encodeURIComponent(type)}`,
+      exampleUrl: (type) => `/api/v3/seller/imports/example?type=${encodeURIComponent(type)}`,
+      downloadUrl: (id) => `/api/v3/seller/imports/${id}/download`,
+    },
+    // Backs the shared stock-locations page. No `delete`: a location holds
+    // stock levels and is named on historical fulfillments, so the Seller API
+    // does not offer it and the page hides the action accordingly.
+    stockLocations: {
+      list: (params) => sellerClient().stockLocations.list(params),
+      get: (id) => sellerClient().stockLocations.get(id),
+      create: (params) => sellerClient().stockLocations.create(params),
+      update: (id, params) => sellerClient().stockLocations.update(id, params),
+    },
+    // The marketplace's vocabulary the product form picks from: types and
+    // delivery profiles only. Categories, collections and tags are filing,
+    // which is the operator's at review, so they are not registered and the
+    // shared Categorization card offers just these two
+    // (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
+    productTypes: {
+      list: (params) => sellerClient().productTypes.list(params),
+      get: (id) => sellerClient().productTypes.get(id),
+    },
+    deliveryProfiles: { list: (params) => sellerClient().deliveryProfiles.list(params) },
+    // What this seller packs into: their own boxes and cartons, plus the
+    // marketplace's shared packaging, which the API lists read-only. Backs
+    // both the packaging settings page and the variant editor's carton
+    // picker (docs/plans/6.0-seller-package-types.md).
+    packageTypes: {
+      list: (params) => sellerClient().packageTypes.list(params),
+      get: (id) => sellerClient().packageTypes.get(id),
+      create: (params) => sellerClient().packageTypes.create(params),
+      update: (id, params) => sellerClient().packageTypes.update(id, params),
+      delete: (id) => sellerClient().packageTypes.delete(id),
+    },
+  })
+
+  return client
+}
+
+/**
+ * The registered client.
+ *
+ * Throws rather than returning null: a panel rendering without one is
+ * misconfigured, and every call would otherwise fail further away with a less
+ * useful message.
+ */
+export function sellerClient(): SellerApiClient {
+  if (!client) {
+    throw new Error(
+      '@spree/seller-dashboard: no API client created. Call createSellerApiClient() at boot, ' +
+        'before rendering the panel.',
+    )
+  }
+
+  return client
+}
+
+/** Points subsequent requests at a seller, without persisting the choice. */
+export function setActiveSeller(sellerId: string): void {
+  activeSellerId = sellerId
+  sellerClient().setSeller(sellerId)
+}
+
+/**
+ * Persists the choice so a reload does not drop the seller back to the picker.
+ *
+ * Every access is guarded: a browser that blocks storage (sandboxed iframe,
+ * blocked third-party storage, some private modes) throws on `localStorage`,
+ * and these run at boot and during logout — the two places a throw would
+ * leave the panel unusable rather than merely forgetful. Losing the memory is
+ * a small cost; failing to boot or to sign out is not.
+ */
+export function rememberSeller(sellerId: string): void {
+  try {
+    localStorage.setItem(SELLER_STORAGE_KEY, sellerId)
+  } catch {
+    // Storage unavailable — the choice lives for this page only.
+  }
+  setActiveSeller(sellerId)
+}
+
+export function forgetSeller(): void {
+  try {
+    localStorage.removeItem(SELLER_STORAGE_KEY)
+  } catch {
+    // Nothing to forget; clearing the header below is what matters for logout.
+  }
+  activeSellerId = null
+  client?.setSeller('')
+}
+
+export function rememberedSeller(): string | null {
+  try {
+    return localStorage.getItem(SELLER_STORAGE_KEY)
+  } catch {
+    return null
+  }
+}

package/src/components/centered-message.tsx

@@ -0,0 +1,8 @@
+/** Full-height placeholder for the panel's loading and error states. */
+export function CenteredMessage({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex min-h-screen items-center justify-center text-muted-foreground text-sm">
+      {children}
+    </div>
+  )
+}

package/src/components/finance/balance-summary.tsx

@@ -0,0 +1,69 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@spree/dashboard-ui'
+import type { Balance } from '@spree/seller-sdk'
+import { useTranslation } from 'react-i18next'
+
+/**
+ * What the marketplace owes this seller, one card per currency.
+ *
+ * Nothing is ever converted between currencies, so two currencies are two
+ * positions rather than one total. `pending` is money the payout provider has
+ * not confirmed yet — shown beside the balance so a seller who has shipped
+ * does not read their own order as unpaid.
+ *
+ * A position has two sides when the seller banks in a currency other than the
+ * one they sold in: the balance is what their account will actually be paid,
+ * and the sale's own figure is shown beneath it. Both are recorded figures.
+ */
+export function BalanceSummary({ balances }: { balances: Balance[] }) {
+  const { t } = useTranslation()
+
+  if (balances.length === 0) {
+    return (
+      <Card>
+        <CardHeader>
+          <CardTitle>{t('earnings.balance.title')}</CardTitle>
+          <CardDescription>{t('earnings.balance.empty')}</CardDescription>
+        </CardHeader>
+      </Card>
+    )
+  }
+
+  return (
+    <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      {balances.map((balance) => (
+        <Card key={`${balance.currency}-${balance.settlement_currency}`}>
+          <CardHeader>
+            <CardTitle>
+              {t('earnings.balance.owed', { currency: balance.settlement_currency })}
+            </CardTitle>
+            {balance.converted && (
+              <CardDescription>
+                {t('earnings.balance.converted', { currency: balance.currency })}
+              </CardDescription>
+            )}
+          </CardHeader>
+          <CardContent className="flex flex-col gap-3">
+            <span className="text-2xl font-semibold tabular-nums">{balance.display_balance}</span>
+            <dl className="flex flex-col gap-1 text-sm">
+              <Figure label={t('earnings.balance.earned')} value={balance.display_earned} />
+              {balance.converted && (
+                <Figure label={t('earnings.balance.payable')} value={balance.display_payable} />
+              )}
+              <Figure label={t('earnings.balance.paid')} value={balance.display_paid} />
+              <Figure label={t('earnings.balance.pending')} value={balance.display_pending} />
+            </dl>
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  )
+}
+
+function Figure({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="flex items-center justify-between gap-3">
+      <dt className="text-muted-foreground">{label}</dt>
+      <dd className="tabular-nums">{value}</dd>
+    </div>
+  )
+}

package/src/components/onboarding-nav-badge.tsx

@@ -0,0 +1,38 @@
+import { Badge } from '@spree/dashboard-ui'
+import { useQuery } from '@tanstack/react-query'
+import { useParams } from '@tanstack/react-router'
+import { sellerClient } from '../api-client'
+
+/**
+ * Progress counter beside the onboarding nav entry, mirroring the operator's
+ * Getting Started badge — a seller can see how far along they are without
+ * opening the page.
+ *
+ * Shares the onboarding query key with the page itself, so the two read one
+ * cache entry: the badge updates the moment a task completes, and visiting
+ * the page costs no extra request.
+ *
+ * Hidden once everything is done, like its operator twin — a badge that
+ * always reads `4/4` is noise.
+ */
+export function OnboardingNavBadge() {
+  // `strict: false`: the badge renders inside the sidebar, which the seller
+  // picker also mounts — there is no `$sellerId` in scope there.
+  const { sellerId } = useParams({ strict: false }) as { sellerId?: string }
+
+  const { data } = useQuery({
+    queryKey: ['seller', sellerId, 'onboarding'],
+    queryFn: () => sellerClient().onboarding.get(),
+    enabled: Boolean(sellerId),
+  })
+
+  const progress = data?.progress
+  if (!progress || progress.total === 0 || progress.done === progress.total) return null
+
+  return (
+    <Badge variant="outline" className="mr-1 flex items-center gap-0 rounded-lg">
+      <span>{progress.done}</span>
+      <span className="opacity-50">/{progress.total}</span>
+    </Badge>
+  )
+}

package/src/components/orders/fulfillment-deliveries.tsx

@@ -0,0 +1,116 @@
+import {
+  Button,
+  CardContent,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  StatusBadge,
+  useConfirm,
+} from '@spree/dashboard-ui'
+import { EllipsisVerticalIcon, PencilIcon, TrashIcon } from '@spree/dashboard-ui/icons'
+import type { Delivery } from '@spree/seller-sdk'
+import { useTranslation } from 'react-i18next'
+import { useFulfillmentActions } from '../../hooks/use-fulfillments'
+
+/**
+ * The tracked consignments of one parcel.
+ *
+ * A parcel usually travels as one, but three boxes or a pallet under a freight
+ * PRO number are the same shape — each with its own tracking number and its
+ * own carrier status. Confirming arrival is not here: that a parcel landed is
+ * the buyer's word, not the sender's, so it stays with the operator.
+ */
+export function FulfillmentDeliveries({
+  orderId,
+  fulfillmentId,
+  deliveries,
+  onEdit,
+}: {
+  orderId: string
+  fulfillmentId: string
+  deliveries: Delivery[]
+  onEdit: (delivery: Delivery) => void
+}) {
+  const { t } = useTranslation()
+  const confirm = useConfirm()
+  const { deleteDelivery } = useFulfillmentActions(orderId)
+
+  if (deliveries.length === 0) return null
+
+  async function handleDelete(delivery: Delivery) {
+    const ok = await confirm({
+      message: t('orders.fulfillments.confirm_delete_delivery'),
+      variant: 'destructive',
+      confirmLabel: t('common.delete'),
+    })
+    if (!ok) return
+    deleteDelivery.mutate({ fulfillmentId, deliveryId: delivery.id })
+  }
+
+  return (
+    <CardContent className="flex flex-col gap-2 border-border-subtle border-b py-3 text-sm">
+      {deliveries.map((delivery) => (
+        <div key={delivery.id} className="flex flex-wrap items-center justify-between gap-2">
+          <div className="flex min-w-0 flex-wrap items-center gap-2">
+            <span className="text-muted-foreground">
+              {delivery.carrier_name ?? t('orders.tracking_label')}:
+            </span>
+            {delivery.tracking_url ? (
+              <a
+                href={delivery.tracking_url}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="truncate underline"
+              >
+                {delivery.tracking_number}
+              </a>
+            ) : (
+              <span className="truncate">{delivery.tracking_number}</span>
+            )}
+            <StatusBadge
+              status={delivery.status}
+              label={t(`orders.fulfillments.carrier_status_${delivery.status}`, {
+                defaultValue: delivery.status,
+              })}
+            />
+          </div>
+
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button variant="ghost" size="icon-xs">
+                <EllipsisVerticalIcon className="size-4" />
+                <span className="sr-only">{t('admin.actions.actions_menu')}</span>
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              <DropdownMenuItem onClick={() => onEdit(delivery)}>
+                <PencilIcon className="size-4" />
+                {t('common.edit')}
+              </DropdownMenuItem>
+
+              {/* Two consignments are not removable: one a label minted, since
+                  the label records what was bought, and one that arrived,
+                  since its arrival is what the returns window counts from. The
+                  server refuses both; this keeps the menu honest. */}
+              {!delivery.shipping_label_id && delivery.status !== 'delivered' && (
+                <>
+                  <DropdownMenuSeparator />
+                  <DropdownMenuItem
+                    variant="destructive"
+                    disabled={deleteDelivery.isPending}
+                    onClick={() => handleDelete(delivery)}
+                  >
+                    <TrashIcon className="size-4" />
+                    {t('common.delete')}
+                  </DropdownMenuItem>
+                </>
+              )}
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </div>
+      ))}
+    </CardContent>
+  )
+}