@spree/seller-dashboard 1.0.0-beta.1

package/src/hooks/use-fulfillments.ts

@@ -0,0 +1,155 @@
+import { useResourceKeyBuilder } from '@spree/dashboard-core'
+import { toastManager } from '@spree/dashboard-ui'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+/**
+ * Everything a seller does to a parcel.
+ *
+ * Each verb is its own endpoint because each carries different arguments —
+ * shipping takes a tracking number and which units went, splitting takes a
+ * variant and a quantity.
+ */
+export function useFulfillmentActions(orderId: string) {
+  const queryClient = useQueryClient()
+  const buildKey = useResourceKeyBuilder()
+
+  function useFulfillmentMutation<TParams>(mutationFn: (params: TParams) => Promise<unknown>) {
+    return useMutation({
+      mutationFn,
+      onSuccess: () => {
+        queryClient.invalidateQueries({ queryKey: buildKey('seller-order', orderId) })
+        queryClient.invalidateQueries({ queryKey: buildKey('seller-orders') })
+      },
+      onError: (error) => {
+        // A rejected workflow — a parcel that cannot ship, a split that would
+        // empty its source — otherwise looks like a dead button.
+        toastManager.add({
+          type: 'error',
+          title: error instanceof Error ? error.message : String(error),
+        })
+      },
+    })
+  }
+
+  const fulfill = useFulfillmentMutation(
+    ({
+      fulfillmentId,
+      ...params
+    }: {
+      fulfillmentId: string
+      tracking?: string
+      tracking_carrier?: string
+      notify_customer?: boolean
+      items?: Array<{ item_id: string; quantity: number }>
+    }) => sellerClient().orders.fulfillments.fulfill(orderId, fulfillmentId, params),
+  )
+
+  const update = useFulfillmentMutation(
+    ({
+      fulfillmentId,
+      ...params
+    }: {
+      fulfillmentId: string
+      tracking?: string
+      tracking_carrier?: string
+      stock_location_id?: string
+      selected_delivery_rate_id?: string
+    }) => sellerClient().orders.fulfillments.update(orderId, fulfillmentId, params),
+  )
+
+  const cancel = useFulfillmentMutation((fulfillmentId: string) =>
+    sellerClient().orders.fulfillments.cancel(orderId, fulfillmentId),
+  )
+
+  const split = useFulfillmentMutation(
+    ({
+      fulfillmentId,
+      ...params
+    }: {
+      fulfillmentId: string
+      variant_id: string
+      quantity: number
+      stock_location_id?: string
+    }) => sellerClient().orders.fulfillments.split(orderId, fulfillmentId, params),
+  )
+
+  // A parcel's consignments. One parcel usually travels as one, but three
+  // boxes or a pallet under a freight PRO number are the same shape, and each
+  // carries its own tracking number and carrier status.
+  const createDelivery = useFulfillmentMutation(
+    ({
+      fulfillmentId,
+      ...params
+    }: {
+      fulfillmentId: string
+      tracking_number: string
+      carrier?: string
+      service?: string
+      tracking_url?: string
+    }) => sellerClient().orders.fulfillments.deliveries.create(orderId, fulfillmentId, params),
+  )
+
+  const updateDelivery = useFulfillmentMutation(
+    ({
+      fulfillmentId,
+      deliveryId,
+      ...params
+    }: {
+      fulfillmentId: string
+      deliveryId: string
+      tracking_number?: string
+      carrier?: string
+      service?: string
+      tracking_url?: string
+    }) =>
+      sellerClient().orders.fulfillments.deliveries.update(
+        orderId,
+        fulfillmentId,
+        deliveryId,
+        params,
+      ),
+  )
+
+  const deleteDelivery = useFulfillmentMutation(
+    ({ fulfillmentId, deliveryId }: { fulfillmentId: string; deliveryId: string }) =>
+      sellerClient().orders.fulfillments.deliveries.delete(orderId, fulfillmentId, deliveryId),
+  )
+
+  // Postage the seller bought elsewhere and is recording here. Buying and
+  // refunding run through the operator's carrier account, so neither is
+  // offered — the endpoint refuses both.
+  const uploadLabel = useFulfillmentMutation(
+    ({
+      fulfillmentId,
+      ...params
+    }: {
+      fulfillmentId: string
+      file: string
+      // Required: a label with no tracking number is refused server-side,
+      // since nothing could then follow the parcel it prints.
+      tracking_number: string
+      carrier?: string
+      service?: string
+      cost?: string
+      currency?: string
+    }) => sellerClient().orders.fulfillments.labels.create(orderId, fulfillmentId, params),
+  )
+
+  const deleteLabel = useFulfillmentMutation(
+    ({ fulfillmentId, labelId }: { fulfillmentId: string; labelId: string }) =>
+      sellerClient().orders.fulfillments.labels.delete(orderId, fulfillmentId, labelId),
+  )
+
+  return {
+    fulfill,
+    update,
+    cancel,
+    split,
+    createDelivery,
+    updateDelivery,
+    deleteDelivery,
+    uploadLabel,
+    deleteLabel,
+  }
+}

package/src/hooks/use-ledger.ts

@@ -0,0 +1,46 @@
+import { useResourceKey } from '@spree/dashboard-core'
+import { useQuery } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+/**
+ * Where this seller stands, one row per currency.
+ *
+ * Nothing is ever converted between currencies, so a seller trading in two
+ * has two positions and the panel shows both rather than a total.
+ */
+export function useBalances() {
+  return useQuery({
+    queryKey: useResourceKey('seller-balances'),
+    queryFn: () => sellerClient().balances.list(),
+  })
+}
+
+/** One settlement, for its own page. */
+export function usePayout(payoutId: string) {
+  return useQuery({
+    queryKey: useResourceKey('seller-payout', payoutId),
+    queryFn: () => sellerClient().payouts.get(payoutId),
+    enabled: !!payoutId,
+  })
+}
+
+/**
+ * The earnings a settlement covers, or the ones an order produced.
+ *
+ * Both read the same list filtered a different way, so the pages that ask
+ * either question share one hook and one query key shape.
+ *
+ * Paged rather than capped: the server clamps `limit` at 100, and a payout
+ * covering more than that must not render one page and call it the whole
+ * settlement.
+ */
+export function useTransfers(filter: { payout_id_eq?: string; order_id_eq?: string }, page = 1) {
+  const key = filter.payout_id_eq ?? filter.order_id_eq ?? 'all'
+
+  return useQuery({
+    queryKey: useResourceKey('seller-transfers', key, String(page)),
+    queryFn: () => sellerClient().transfers.list({ ...filter, limit: 100, page }),
+    enabled: !!(filter.payout_id_eq || filter.order_id_eq),
+    placeholderData: (previous) => previous,
+  })
+}

package/src/hooks/use-order.ts

@@ -0,0 +1,62 @@
+import { useResourceKey, useResourceKeyBuilder } from '@spree/dashboard-core'
+import { toastManager } from '@spree/dashboard-ui'
+import type { Order } from '@spree/seller-sdk'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+/** One order, with everything the page renders about it. */
+export function useOrder(orderId: string) {
+  return useQuery({
+    queryKey: useResourceKey('seller-order', orderId),
+    // The shares of the basket's payment are expand-gated, and the payment
+    // card is what reads them.
+    queryFn: () => sellerClient().orders.get(orderId, { expand: ['payment_splits'] }),
+    enabled: !!orderId,
+  })
+}
+
+/** Withdrawing from an order this seller cannot fulfil. */
+export function useCancelOrder(orderId: string) {
+  return useOrderMutation(
+    orderId,
+    (params?: {
+      cancel_reason_id?: string
+      cancel_note?: string
+      refund_payments?: boolean
+      notify_customer?: boolean
+    }) => sellerClient().orders.cancel(orderId, params),
+  )
+}
+
+/** The seller's working note, and what the buyer asked for. */
+export function useUpdateOrderNotes(orderId: string) {
+  return useOrderMutation(orderId, (params: { customer_note?: string; internal_note?: string }) =>
+    sellerClient().orders.notes.update(orderId, params),
+  )
+}
+
+/**
+ * A write against the order itself. Refreshes the order and the list behind
+ * it — a canceled order reads differently in both places.
+ */
+export function useOrderMutation<TParams, TResult = Order>(
+  orderId: string,
+  mutationFn: (params: TParams) => Promise<TResult>,
+) {
+  const queryClient = useQueryClient()
+  const buildKey = useResourceKeyBuilder()
+
+  return useMutation({
+    mutationFn,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: buildKey('seller-order', orderId) })
+      queryClient.invalidateQueries({ queryKey: buildKey('seller-orders') })
+    },
+    onError: (error) => {
+      toastManager.add({
+        type: 'error',
+        title: error instanceof Error ? error.message : String(error),
+      })
+    },
+  })
+}

package/src/hooks/use-post-sale.ts

@@ -0,0 +1,202 @@
+import { useResourceKey, useResourceKeyBuilder } from '@spree/dashboard-core'
+import { toastManager } from '@spree/dashboard-ui'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+/**
+ * What has come back, or gone wrong, on one order.
+ *
+ * Fetched separately from the order so its payload stays lean — most orders
+ * have none of these.
+ */
+export function useOrderReturns(orderId: string) {
+  return useQuery({
+    queryKey: useResourceKey('seller-order-returns', orderId),
+    queryFn: () => sellerClient().orders.returns.list(orderId),
+    enabled: !!orderId,
+  })
+}
+
+export function useOrderExchanges(orderId: string) {
+  return useQuery({
+    queryKey: useResourceKey('seller-order-exchanges', orderId),
+    queryFn: () => sellerClient().orders.exchanges.list(orderId),
+    enabled: !!orderId,
+  })
+}
+
+export function useOrderClaims(orderId: string) {
+  return useQuery({
+    queryKey: useResourceKey('seller-order-claims', orderId),
+    queryFn: () => sellerClient().orders.claims.list(orderId),
+    enabled: !!orderId,
+  })
+}
+
+/**
+ * Refreshes the list this write belongs to and the order itself — refunding
+ * changes what the order is owed.
+ */
+function usePostSaleMutation<TParams>(
+  orderId: string,
+  resourceKey: string,
+  mutationFn: (params: TParams) => Promise<unknown>,
+) {
+  const queryClient = useQueryClient()
+  const buildKey = useResourceKeyBuilder()
+
+  return useMutation({
+    mutationFn,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: buildKey(resourceKey, orderId) })
+      queryClient.invalidateQueries({ queryKey: buildKey('seller-order', orderId) })
+    },
+    onError: (error) => {
+      toastManager.add({
+        type: 'error',
+        title: error instanceof Error ? error.message : String(error),
+      })
+    },
+  })
+}
+
+export function useReturnActions(orderId: string) {
+  const key = 'seller-order-returns'
+  const returns = () => sellerClient().orders.returns
+
+  const create = usePostSaleMutation(
+    orderId,
+    key,
+    (params: {
+      items: Array<{ fulfillment_item_id: string; quantity: number }>
+      memo?: string
+      reason_id?: string
+      stock_location_id?: string
+    }) => returns().create(orderId, params),
+  )
+
+  const approve = usePostSaleMutation(orderId, key, (id: string) => returns().approve(orderId, id))
+
+  const receive = usePostSaleMutation(
+    orderId,
+    key,
+    ({
+      returnId,
+      items,
+    }: {
+      returnId: string
+      items?: Array<{ return_line_item_id: string; quantity: number; resellable?: boolean }>
+    }) => returns().receive(orderId, returnId, items ? { items } : undefined),
+  )
+
+  const refund = usePostSaleMutation(
+    orderId,
+    key,
+    ({
+      returnId,
+      refundMethod,
+      amount,
+    }: {
+      returnId: string
+      refundMethod?: 'original_payment' | 'store_credit'
+      amount?: string
+    }) => returns().refund(orderId, returnId, { refund_method: refundMethod, amount }),
+  )
+
+  const cancel = usePostSaleMutation(orderId, key, (id: string) => returns().cancel(orderId, id))
+
+  return { create, approve, receive, refund, cancel }
+}
+
+export function useExchangeActions(orderId: string) {
+  const key = 'seller-order-exchanges'
+  const exchanges = () => sellerClient().orders.exchanges
+
+  const create = usePostSaleMutation(
+    orderId,
+    key,
+    (params: {
+      items: Array<{ fulfillment_item_id: string; new_variant_id: string; quantity: number }>
+      memo?: string
+      reason_id?: string
+    }) => exchanges().create(orderId, params),
+  )
+
+  const approve = usePostSaleMutation(orderId, key, (id: string) =>
+    exchanges().approve(orderId, id),
+  )
+
+  const receive = usePostSaleMutation(
+    orderId,
+    key,
+    ({
+      exchangeId,
+      items,
+    }: {
+      exchangeId: string
+      items?: Array<{ exchange_line_item_id: string; quantity: number; resellable?: boolean }>
+    }) => exchanges().receive(orderId, exchangeId, items ? { items } : undefined),
+  )
+
+  const fulfill = usePostSaleMutation(
+    orderId,
+    key,
+    ({
+      exchangeId,
+      refundMethod,
+    }: {
+      exchangeId: string
+      refundMethod?: 'original_payment' | 'store_credit'
+    }) => exchanges().fulfill(orderId, exchangeId, { refund_method: refundMethod }),
+  )
+
+  const cancel = usePostSaleMutation(orderId, key, (id: string) => exchanges().cancel(orderId, id))
+
+  return { create, approve, receive, fulfill, cancel }
+}
+
+export function useClaimActions(orderId: string) {
+  const key = 'seller-order-claims'
+  const claims = () => sellerClient().orders.claims
+
+  const create = usePostSaleMutation(
+    orderId,
+    key,
+    (params: {
+      items: Array<{ line_item_id: string; quantity: number; description?: string }>
+      memo?: string
+      reason_id?: string
+    }) => claims().create(orderId, params),
+  )
+
+  const approve = usePostSaleMutation(orderId, key, (id: string) => claims().approve(orderId, id))
+
+  const resolve = usePostSaleMutation(
+    orderId,
+    key,
+    ({
+      claimId,
+      resolution,
+      refundMethod,
+      amount,
+      replacementLineItemIds,
+    }: {
+      claimId: string
+      resolution: 'refund' | 'replacement' | 'refund_and_replacement'
+      refundMethod?: 'original_payment' | 'store_credit'
+      amount?: string
+      replacementLineItemIds?: string[]
+    }) =>
+      claims().resolve(orderId, claimId, {
+        resolution,
+        refund_method: refundMethod,
+        amount,
+        replacement_line_item_ids: replacementLineItemIds,
+      }),
+  )
+
+  const deny = usePostSaleMutation(orderId, key, (id: string) => claims().deny(orderId, id))
+  const cancel = usePostSaleMutation(orderId, key, (id: string) => claims().cancel(orderId, id))
+
+  return { create, approve, resolve, deny, cancel }
+}

package/src/hooks/use-reasons.ts

@@ -0,0 +1,34 @@
+import { useResourceKey } from '@spree/dashboard-core'
+import { useQuery } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+export type ReasonKind = 'return-reasons' | 'claim-reasons' | 'order-cancellation-reasons'
+
+/**
+ * The marketplace's vocabulary for why goods came back, what went wrong, or
+ * why an order was called off. Operator-owned and slow-moving, so one fetch
+ * serves every dialog.
+ */
+export function useReasons(kind: ReasonKind, enabled = true) {
+  return useQuery({
+    queryKey: useResourceKey(kind),
+    queryFn: () => {
+      const client = sellerClient()
+      if (kind === 'return-reasons') return client.returnReasons.list()
+      if (kind === 'claim-reasons') return client.claimReasons.list()
+      return client.orderCancellationReasons.list()
+    },
+    staleTime: 5 * 60 * 1000,
+    enabled,
+  })
+}
+
+/** Registry data — it only changes on deploy. */
+export function useTrackingCarriers(enabled = true) {
+  return useQuery({
+    queryKey: useResourceKey('seller-tracking-carriers'),
+    queryFn: () => sellerClient().trackingCarriers.list(),
+    staleTime: Number.POSITIVE_INFINITY,
+    enabled,
+  })
+}

package/src/hooks/use-stock-locations.ts

@@ -0,0 +1,23 @@
+import { useResourceKey } from '@spree/dashboard-core'
+import { useQuery } from '@tanstack/react-query'
+import { sellerClient } from '../api-client'
+
+/**
+ * Where this seller keeps stock.
+ *
+ * Deliberately not `useStockLocations` from `@spree/dashboard-core`: that one
+ * reads the admin client and would answer with the marketplace's warehouses
+ * too, so a seller moving a parcel could pick a shelf that is not theirs. The
+ * seller endpoint is rooted in `current_seller.stock_locations`, so the list
+ * is theirs by construction rather than by filtering here.
+ *
+ * Slow-moving, so one fetch serves every dialog on the page.
+ */
+export function useStockLocations(enabled = true) {
+  return useQuery({
+    queryKey: useResourceKey('seller-stock-locations'),
+    queryFn: () => sellerClient().stockLocations.list({ limit: 100 }),
+    staleTime: 5 * 60 * 1000,
+    enabled,
+  })
+}

package/src/hooks/use-store-timezone.ts

@@ -0,0 +1,26 @@
+import { useQuery } from '@tanstack/react-query'
+import { useParams } from '@tanstack/react-router'
+import { sellerClient } from '../api-client'
+
+/**
+ * The marketplace's timezone, as every date in this panel is read in.
+ *
+ * A seller keeps no clock of their own — a settlement period is decided by
+ * the marketplace's day, so a timestamp rendered in whichever zone the
+ * seller's browser sits in would put an earning on the wrong date for
+ * anyone trading away from the marketplace.
+ *
+ * Falls back to the browser's zone only until the profile arrives, matching
+ * what the operator dashboard's `useStore` does.
+ */
+export function useStoreTimezone(): string {
+  const { sellerId } = useParams({ from: '/_authenticated/$sellerId' })
+
+  const { data: profile } = useQuery({
+    queryKey: ['seller', sellerId, 'profile'],
+    queryFn: () => sellerClient().profile.get(),
+    enabled: Boolean(sellerId),
+  })
+
+  return profile?.preferred_timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC'
+}

package/src/i18n.ts

@@ -0,0 +1,26 @@
+// Extends the framework's i18n rather than standing up a second instance.
+//
+// The side-effect import initialises i18next and registers the framework's
+// own copy — the strings baked into shared components like `RowActions` and
+// the confirm dialog. A panel that called `init()` itself would win the race
+// and leave those components rendering raw keys
+// (`admin.row_actions.menu_label`) wherever they appear. It must come first:
+// side-effect imports are ordering barriers.
+import '@spree/dashboard-core/lib/i18n'
+// The instance comes from core too, not a bare `i18next` import: a bundled
+// build can resolve a second copy of the package, and `addResourceBundle` on
+// that one throws. Core re-exports the object it initialised for exactly this.
+import { i18n } from '@spree/dashboard-core'
+import en from './locales/en.json'
+
+/**
+ * The panel's own copy, layered on top.
+ *
+ * Deliberately separate from the admin dashboard's: sellers and marketplace
+ * staff read different words for the same records — "your products" rather
+ * than "products", "your payouts" rather than a seller's. The deep + overwrite
+ * flags merge these in without dropping the framework keys underneath.
+ */
+i18n.addResourceBundle('en', 'translation', en, true, true)
+
+export default i18n

package/src/index.ts

@@ -0,0 +1,27 @@
+// The i18n bootstrap runs on import and must come first: route modules and
+// table definitions call `i18n.t(...)` at module load, so a bundler that
+// evaluated them before this would bake raw keys into the UI. Side-effect
+// imports are ordering barriers, which is exactly what this relies on.
+import './i18n'
+// The built-in sidebar entries. Registered on import — after i18n, since the
+// labels are translated at registration time — and before any host plugin
+// runs, so a plugin's `nav.remove('team')` finds the entry to remove.
+import './nav/default'
+import './nav/settings'
+
+// Plugin facade re-export — lets a marketplace register in-app customisations
+// (nav entries, slot widgets, table columns) without declaring
+// @spree/dashboard-core as a direct dependency. Same facade the operator's
+// dashboard exposes: one API for extending either panel.
+export * from '@spree/dashboard-core/plugin'
+
+export {
+  createSellerApiClient,
+  rememberedSeller,
+  rememberSeller,
+  setActiveSeller,
+} from './api-client'
+export { CenteredMessage } from './components/centered-message'
+export type { SellerRouterOptions } from './create-router'
+export { createSellerRouter } from './create-router'
+export { SellerDashboard } from './seller-dashboard'