Developer Docs

Payments History

The Payments History panel is a Murchase management dashboard accessible from the Admin Dashboard's Payments tab. It provides a paginated, filterable view of all Murchases across a Malet Owner's Malets, with a detail drawer for inspecting individual Murchases and a stubbed partial refund form for future backend wiring.

NOTE

Murchase data is fetched via the ordersByMalet GraphQL query, scoped to the Malet IDs owned by the current user. The backend returns flat arrays — pagination is handled client-side.

Architecture

┌─────────────────────────────────────────────────────┐
│         Admin Dashboard (+page.svelte)               │
│  Tab: "Payments" (lazy-loaded)                       │
│  ┌─────────────────────────────────────────────────┐ │
│  │       PaymentsHistory.svelte                     │ │
│  │ ┌──────────────┐ ┌─────────────────────────────┐│ │
│  │ │ Filter Bar   │ │ Detail Drawer (slide-in)    ││ │
│  │ │ (status,     │ │ (meta, line items,          ││ │
│  │ │  date, text) │ │  fulfillment, refund stub)  ││ │
│  │ ├──────────────┤ └─────────────────────────────┘│ │
│  │ │ Murchase     │                                │ │
│  │ │ Table        │                                │ │
│  │ │ (sortable,   │                                │ │
│  │ │  paginated)  │                                │ │
│  │ ├──────────────┤                                │ │
│  │ │ Pagination   │                                │ │
│  │ └──────────────┘                                │ │
│  └─────────────────────────────────────────────────┘ │
│                      ↕                                │
│      paymentsHistoryStore.svelte.ts                   │
│      (filtering, sorting, pagination, validation)     │
│      orders.ts (GraphQL queries)                      │
└─────────────────────────────────────────────────────┘

Store: `paymentsHistoryStore.svelte.ts`

Exports pure functions for testability:

Function Purpose
filterByStatus(orders, status) Filter by OrderStatus or 'ALL'
filterByDateRange(orders, from, to) Filter by ISO date range
filterBySearchText(orders, text) Match ID, item names, guest email
applyFilters(orders, filters) Compose all three filters
sortOrders(orders, field, direction) Sort by date or amount, asc/desc
totalPages(count, pageSize) Calculate page count
getPageSlice(items, page, pageSize) Extract current page slice
validateRefundInput(input) Zod-validate PartialRefundInput

Component: `PaymentsHistory.svelte`

Props: maletIds: string[] — Malet IDs to scope the ordersByMalet query.

Filter Bar:

  • Status pills: All, Pending, Authorized, Processing, Shipped, Delivered, Cancelled
  • Search input: debounced text matching across Murchase ID, item names, guest email
  • Date range: from/to date inputs

Murchase Table:

  • Columns: ID (monospace hash), Status (color badge), Items count, Total (formatted), Date
  • Sortable: click column headers to toggle date or amount sort
  • Paginated: 20 per page, Previous/Next controls + page number dots

Detail Drawer:

  • Slides in from the right (420px width)
  • Meta section: status badge, date, total, currency, buyer ID, guest email
  • Line items: item name × quantity
  • Fulfillment: tracking number (linked), estimated delivery date
  • Partial refund form (disabled, "Coming Soon" badge)

Order Statuses

Status Label Color Description
PENDING Pending Amber Order placed, awaiting payment
PAYMENT_AUTHORIZED Authorized Blue Payment authorized, not yet captured
PROCESSING Processing Purple Payment captured, order being prepared
SHIPPED Shipped Indigo Order shipped, tracking available
DELIVERED Delivered Green Order delivered to Visitor
CANCELLED Cancelled Red Order cancelled

Partial Refund (Stubbed)

The detail drawer includes a partial refund form with:

  • Amount input (smallest currency unit / cents)
  • Reason input (optional)
  • Submit button (disabled, labeled "Coming Soon")

The form validates input via PartialRefundInputSchema (Zod):

  • transactionId: required string
  • amount: positive integer ≥ 1
  • reason: optional string

IMPORTANT

The backend partialRefundPayment mutation exists in the payments subgraph and is fully functional. The frontend form is stubbed pending UX review of the refund confirmation flow. See docs/SUBGRAPH_ROADMAP.md for the wiring TODO.

Data Flow

1. Admin navigates to Payments tab
2. Component receives maletIds from admin page state
3. ordersByMalet query fetches all orders for owned Malets
4. Orders flattened into a single array with maletId attached
5. Filters/sort applied client-side (pure functions)
6. Page slice extracted for current page
7. User clicks row → detail drawer opens with full order data

File Map

File Purpose
src/stores/paymentsHistoryStore.svelte.ts Pure filtering/sorting/pagination + Zod validation
src/lib/components/admin/PaymentsHistory.svelte Table, filters, drawer, refund stub
src/lib/queries/orders.ts GET_ORDERS_BY_MALET query + Order types
src/routes/admin/+page.svelte Payments tab integration
tests/paymentsHistoryStore.test.ts 38 unit tests