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.

Added a simple Vite admin shell

Damian Legawieceb05fe18a396
diff --git a/packages/admin/.gitignore b/packages/admin/.gitignore
new file mode 100644
index 0000000000..7ceb59f89a
--- /dev/null
+++ b/packages/admin/.gitignore
@@ -0,0 +1,25 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+.env
diff --git a/packages/admin/ARCHITECTURE.md b/packages/admin/ARCHITECTURE.md
new file mode 100644
index 0000000000..5930b4a73a
--- /dev/null
+++ b/packages/admin/ARCHITECTURE.md
@@ -0,0 +1,64 @@
+# @spree/admin package
+
+## Overview
+
+This is the new admin dashboard for Spree using Spree Admin API (via Spree SDK package in `../sdk`) which will replace existing Rails (full-stack/monolith) admin dashboard located in `../../spree/admin`.
+
+This package will be installed as a dependency when developer creates a new Spree project using `create-spree-app`.
+
+Admin SDK documentation: `packages/sdk/ADMIN_SDK.md`
+
+## Authentication
+
+Authentication is handled by the Spree SDK package via the `secretKey` configuration option. You need a secreat key to use this package. Should read `SPREE_SECRET_KEY` environment variable by default. We also need to support `SPREE_API_URL` environment variable pointing to the Spree backend API (defaults to `http://localhost:3000`)
+
+User authentication is handled via JWT short lived tokens. Everything is built into the Spree SDK package.
+
+```typescript
+import { createSpreeClient } from '@spree/sdk';
+
+// Initialize the client
+const client = createSpreeClient({
+ baseUrl: process.env.SPREE_API_URL,
+ secretKey: process.env.SPREE_SECRET_KEY,
+});
+
+// Authentication
+const { token, user } = await client.admin.auth.login({
+ email: '[email protected]',
+ password: 'password123',
+});
+```
+
+## Conventions
+
+We should use conventions when handling forms, lists, and other UI components to reduce boilerplate and make it easier for developers to extend the admin dashboard.
+
+## Tech stack
+
+Let's remember to use the newest versions of each library (as of March 2026).
+
+* Build & Dev: Vite (obvious choice for a pure client-side SPA — fast HMR, clean config, outputs static files you can bundle into the Rails gem or deploy standalone)
+* Routing: TanStack Router — type-safe routes, file-based convention, built-in loader pattern pairs perfectly with TanStack Query for prefetching on navigation
+* Data Fetching: TanStack Query — handles caching, background refetches, optimistic updates. Your @spree/admin-sdk becomes the query function layer. Wrap SDK methods as custom hooks (useProducts, useOrder, etc.)
+* Forms: React Hook Form + Zod for validation schemas. Zod schemas can mirror your API contracts, and if you're auto-generating types from OpenAPI specs, you can derive Zod schemas from the same source
+* UI: shadcn/ui + Tailwind. Copy-paste ownership model means your plugin authors can extend or override components without fighting a component library's abstraction
+* Auth: For JWT — store the access token in memory (React context/state), refresh token in an httpOnly cookie if possible, or memory as fallback. TanStack Router's beforeLoad guards check auth state before rendering protected routes. A simple AuthProvider context that exposes login(), logout(), getToken() and injects the token into the SDK client instance
+* State: You likely don't need a global state library. TanStack Query covers server state, React Hook Form covers form state, and a small AuthContext covers the session. If something edges toward complex client-only state later, Zustand is the lightest option that won't fight you
+* Linting/Formatting: Biome — single tool, fast, no ESLint/Prettier config sprawl
+* Testing: Vitest + React Testing Library for unit/integration, Playwright for E2E
+
+## Extension points
+
+Developers will be able to extend the admin dashboard by adding custom pages, components, and logic.
+
+There are 3 main areas where developers can extend the admin dashboard:
+
+1. Navigation - needs to be configurable via registry
+2. Tables - record listing, eg. products, orders. Developers need to be able to customize table columns and filters.
+3. Pages - developers should be able to add custom pages, extend routes, and add custom logic.
+3. Components - developers should be able to add custom components and extend existing ones. Developers should be able to inject their own components into existing pages, eg. new fields on product form page.
+
+## Design
+
+We can inspire from the rails admin dashboard design, located at `../../spree/admin` (look for `spree_admin.html.erb` layout file and stylesheets located at `../../spree/admin/assets/tailwind`).
diff --git a/packages/admin/README.md b/packages/admin/README.md
new file mode 100644
index 0000000000..d2e77611fd
--- /dev/null
+++ b/packages/admin/README.md
@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+ globalIgnores(['dist']),
+ {
+ files: ['**/*.{ts,tsx}'],
+ extends: [
+ // Other configs...
+
+ // Remove tseslint.configs.recommended and replace with this
+ tseslint.configs.recommendedTypeChecked,
+ // Alternatively, use this for stricter rules
+ tseslint.configs.strictTypeChecked,
+ // Optionally, add this for stylistic rules
+ tseslint.configs.stylisticTypeChecked,
+
+ // Other configs...
+ ],
+ languageOptions: {
+ parserOptions: {
+ project: ['./tsconfig.node.json', './tsconfig.app.json'],
+ tsconfigRootDir: import.meta.dirname,
+ },
+ // other options...
+ },
+ },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+ globalIgnores(['dist']),
+ {
+ files: ['**/*.{ts,tsx}'],
+ extends: [
+ // Other configs...
+ // Enable lint rules for React
+ reactX.configs['recommended-typescript'],
+ // Enable lint rules for React DOM
+ reactDom.configs.recommended,
+ ],
+ languageOptions: {
+ parserOptions: {
+ project: ['./tsconfig.node.json', './tsconfig.app.json'],
+ tsconfigRootDir: import.meta.dirname,
+ },
+ // other options...
+ },
+ },
+])
+```
diff --git a/packages/admin/components.json b/packages/admin/components.json
new file mode 100644
index 0000000000..5c23ec4912
--- /dev/null
+++ b/packages/admin/components.json
@@ -0,0 +1,25 @@
+{
+ "$schema": "https://ui.shadcn.com/schema.json",
+ "style": "radix-nova",
+ "rsc": false,
+ "tsx": true,
+ "tailwind": {
+ "config": "",
+ "css": "src/index.css",
+ "baseColor": "neutral",
+ "cssVariables": true,
+ "prefix": ""
+ },
+ "iconLibrary": "lucide",
+ "rtl": false,
+ "aliases": {
+ "components": "@/components",
+ "utils": "@/lib/utils",
+ "ui": "@/components/ui",
+ "lib": "@/lib",
+ "hooks": "@/hooks"
+ },
+ "menuColor": "default",
+ "menuAccent": "subtle",
+ "registries": {}
+}
diff --git a/packages/admin/eslint.config.js b/packages/admin/eslint.config.js
new file mode 100644
index 0000000000..5e6b472f58
--- /dev/null
+++ b/packages/admin/eslint.config.js
@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+ globalIgnores(['dist']),
+ {
+ files: ['**/*.{ts,tsx}'],
+ extends: [
+ js.configs.recommended,
+ tseslint.configs.recommended,
+ reactHooks.configs.flat.recommended,
+ reactRefresh.configs.vite,
+ ],
+ languageOptions: {
+ ecmaVersion: 2020,
+ globals: globals.browser,
+ },
+ },
+])
diff --git a/packages/admin/index.html b/packages/admin/index.html
new file mode 100644
index 0000000000..70d00f720e
--- /dev/null
+++ b/packages/admin/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Spree Admin</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="/src/main.tsx"></script>
+ </body>
+</html>
diff --git a/packages/admin/package.json b/packages/admin/package.json
new file mode 100644
index 0000000000..e7f5dc16ad
--- /dev/null
+++ b/packages/admin/package.json
@@ -0,0 +1,53 @@
+{
+ "name": "@spree/admin",
+ "private": true,
+ "version": "0.0.0",
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "tsc -b && vite build",
+ "lint": "eslint .",
+ "preview": "vite preview"
+ },
+ "dependencies": {
+ "@fontsource-variable/geist": "^5.2.8",
+ "@hookform/resolvers": "^5.2.2",
+ "@spree/sdk": "workspace:^",
+ "@tanstack/react-query": "^5.90.21",
+ "@tanstack/react-router": "^1.166.2",
+ "class-variance-authority": "^0.7.1",
+ "clsx": "^2.1.1",
+ "lucide-react": "^0.577.0",
+ "radix-ui": "^1.4.3",
+ "react": "^19.2.0",
+ "react-dom": "^19.2.0",
+ "react-hook-form": "^7.71.2",
+ "shadcn": "^4.0.0",
+ "tailwind-merge": "^3.5.0",
+ "tw-animate-css": "^1.4.0",
+ "zod": "^4.3.6"
+ },
+ "devDependencies": {
+ "@biomejs/biome": "^2.4.6",
+ "@eslint/js": "^9.39.1",
+ "@tailwindcss/vite": "^4.2.1",
+ "@tanstack/router-plugin": "^1.166.2",
+ "@types/node": "^24.10.1",
+ "@types/react": "^19.2.7",
+ "@types/react-dom": "^19.2.3",
+ "@vitejs/plugin-react": "^5.1.1",
+ "eslint": "^9.39.1",
+ "eslint-plugin-react-hooks": "^7.0.1",
+ "eslint-plugin-react-refresh": "^0.4.24",
+ "globals": "^16.5.0",
+ "tailwindcss": "^4.2.1",
+ "typescript": "~5.9.3",
+ "typescript-eslint": "^8.48.0",
+ "vite": "^8.0.0-beta.13"
+ },
+ "pnpm": {
+ "overrides": {
+ "vite": "^8.0.0-beta.13"
+ }
+ }
+}
diff --git a/packages/admin/src/client.ts b/packages/admin/src/client.ts
new file mode 100644
index 0000000000..74a5f6f268
--- /dev/null
+++ b/packages/admin/src/client.ts
@@ -0,0 +1,6 @@
+import { createSpreeClient } from '@spree/sdk'
+
+export const spreeClient = createSpreeClient({
+ baseUrl: import.meta.env.VITE_SPREE_API_URL || 'http://localhost:3000',
+ secretKey: import.meta.env.VITE_SPREE_SECRET_KEY,
+})
diff --git a/packages/admin/src/components/app-sidebar.tsx b/packages/admin/src/components/app-sidebar.tsx
new file mode 100644
index 0000000000..4caf3c1a3e
--- /dev/null
+++ b/packages/admin/src/components/app-sidebar.tsx
@@ -0,0 +1,76 @@
+import { NavMain } from '@/components/nav-main'
+import { NavUser } from '@/components/nav-user'
+import { StoreSwitcher } from '@/components/store-switcher'
+import {
+ Sidebar,
+ SidebarContent,
+ SidebarFooter,
+ SidebarHeader,
+ SidebarRail,
+} from '@/components/ui/sidebar'
+import {
+ LayoutDashboardIcon,
+ PackageIcon,
+ ShoppingCartIcon,
+ UsersIcon,
+ TagIcon,
+ SettingsIcon,
+} from 'lucide-react'
+import type { ComponentProps } from 'react'
+
+const navigation = [
+ {
+ title: 'Dashboard',
+ url: '/',
+ icon: <LayoutDashboardIcon />,
+ },
+ {
+ title: 'Orders',
+ url: '/orders',
+ icon: <ShoppingCartIcon />,
+ },
+ {
+ title: 'Products',
+ url: '/products',
+ icon: <PackageIcon />,
+ isActive: true,
+ items: [
+ { title: 'All Products', url: '/products' },
+ ],
+ },
+ {
+ title: 'Categories',
+ url: '/categories',
+ icon: <TagIcon />,
+ },
+ {
+ title: 'Customers',
+ url: '/customers',
+ icon: <UsersIcon />,
+ },
+ {
+ title: 'Settings',
+ url: '/settings',
+ icon: <SettingsIcon />,
+ items: [
+ { title: 'General', url: '/settings' },
+ ],
+ },
+]
+
+export function AppSidebar(props: ComponentProps<typeof Sidebar>) {
+ return (
+ <Sidebar collapsible="icon" {...props}>
+ <SidebarHeader>
+ <StoreSwitcher />
+ </SidebarHeader>
+ <SidebarContent>
+ <NavMain items={navigation} />
+ </SidebarContent>
+ <SidebarFooter>
+ <NavUser />
+ </SidebarFooter>
+ <SidebarRail />
+ </Sidebar>
+ )
+}
diff --git a/packages/admin/src/components/nav-main.tsx b/packages/admin/src/components/nav-main.tsx
new file mode 100644
index 0000000000..f91ca46367
--- /dev/null
+++ b/packages/admin/src/components/nav-main.tsx
@@ -0,0 +1,83 @@
+import {
+ Collapsible,
+ CollapsibleContent,
+ CollapsibleTrigger,
+} from '@/components/ui/collapsible'
+import {
+ SidebarGroup,
+ SidebarGroupLabel,
+ SidebarMenu,
+ SidebarMenuButton,
+ SidebarMenuItem,
+ SidebarMenuSub,
+ SidebarMenuSubButton,
+ SidebarMenuSubItem,
+} from '@/components/ui/sidebar'
+import { Link } from '@tanstack/react-router'
+import { ChevronRightIcon } from 'lucide-react'
+import type { ReactNode } from 'react'
+
+export function NavMain({
+ items,
+}: {
+ items: {
+ title: string
+ url: string
+ icon?: ReactNode
+ isActive?: boolean
+ items?: {
+ title: string
+ url: string
+ }[]
+ }[]
+}) {
+ return (
+ <SidebarGroup>
+ <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+ <SidebarMenu>
+ {items.map((item) =>
+ item.items ? (
+ <Collapsible
+ key={item.title}
+ asChild
+ defaultOpen={item.isActive}
+ className="group/collapsible"
+ >
+ <SidebarMenuItem>
+ <CollapsibleTrigger asChild>
+ <SidebarMenuButton tooltip={item.title}>
+ {item.icon}
+ <span>{item.title}</span>
+ <ChevronRightIcon className="ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
+ </SidebarMenuButton>
+ </CollapsibleTrigger>
+ <CollapsibleContent>
+ <SidebarMenuSub>
+ {item.items.map((subItem) => (
+ <SidebarMenuSubItem key={subItem.title}>
+ <SidebarMenuSubButton asChild>
+ <Link to={subItem.url}>
+ <span>{subItem.title}</span>
+ </Link>
+ </SidebarMenuSubButton>
+ </SidebarMenuSubItem>
+ ))}
+ </SidebarMenuSub>
+ </CollapsibleContent>
+ </SidebarMenuItem>
+ </Collapsible>
+ ) : (
+ <SidebarMenuItem key={item.title}>
+ <SidebarMenuButton tooltip={item.title} asChild>
+ <Link to={item.url}>
+ {item.icon}
+ <span>{item.title}</span>
+ </Link>
+ </SidebarMenuButton>
+ </SidebarMenuItem>
+ ),
+ )}
+ </SidebarMenu>
+ </SidebarGroup>
+ )
+}
diff --git a/packages/admin/src/components/nav-user.tsx b/packages/admin/src/components/nav-user.tsx
new file mode 100644
index 0000000000..738dbff5b8
--- /dev/null
+++ b/packages/admin/src/components/nav-user.tsx
@@ -0,0 +1,82 @@
+import {
+ Avatar,
+ AvatarFallback,
+} from '@/components/ui/avatar'
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuLabel,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import {
+ SidebarMenu,
+ SidebarMenuButton,
+ SidebarMenuItem,
+ useSidebar,
+} from '@/components/ui/sidebar'
+import { useAuth } from '@/hooks/use-auth'
+import { ChevronsUpDownIcon, LogOutIcon } from 'lucide-react'
+
+export function NavUser() {
+ const { isMobile } = useSidebar()
+ const { user, logout } = useAuth()
+
+ if (!user) return null
+
+ const initials = [user.first_name, user.last_name]
+ .filter(Boolean)
+ .map((n) => n![0])
+ .join('')
+ .toUpperCase() || user.email[0]!.toUpperCase()
+
+ const displayName = [user.first_name, user.last_name].filter(Boolean).join(' ') || user.email
+
+ return (
+ <SidebarMenu>
+ <SidebarMenuItem>
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <SidebarMenuButton
+ size="lg"
+ className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
+ >
+ <Avatar className="h-8 w-8 rounded-lg">
+ <AvatarFallback className="rounded-lg">{initials}</AvatarFallback>
+ </Avatar>
+ <div className="grid flex-1 text-left text-sm leading-tight">
+ <span className="truncate font-medium">{displayName}</span>
+ <span className="truncate text-xs">{user.email}</span>
+ </div>
+ <ChevronsUpDownIcon className="ml-auto size-4" />
+ </SidebarMenuButton>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent
+ className="w-(--radix-dropdown-menu-trigger-width) min-w-56 rounded-lg"
+ side={isMobile ? 'bottom' : 'right'}
+ align="end"
+ sideOffset={4}
+ >
+ <DropdownMenuLabel className="p-0 font-normal">
+ <div className="flex items-center gap-2 px-1 py-1.5 text-left text-sm">
+ <Avatar className="h-8 w-8 rounded-lg">
+ <AvatarFallback className="rounded-lg">{initials}</AvatarFallback>
+ </Avatar>
+ <div className="grid flex-1 text-left text-sm leading-tight">
+ <span className="truncate font-medium">{displayName}</span>
+ <span className="truncate text-xs">{user.email}</span>
+ </div>
+ </div>
+ </DropdownMenuLabel>
+ <DropdownMenuSeparator />
+ <DropdownMenuItem onClick={logout}>
+ <LogOutIcon />
+ Log out
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </SidebarMenuItem>
+ </SidebarMenu>
+ )
+}
diff --git a/packages/admin/src/components/store-switcher.tsx b/packages/admin/src/components/store-switcher.tsx
new file mode 100644
index 0000000000..0422dd8383
--- /dev/null
+++ b/packages/admin/src/components/store-switcher.tsx
@@ -0,0 +1,24 @@
+import {
+ SidebarMenu,
+ SidebarMenuButton,
+ SidebarMenuItem,
+} from '@/components/ui/sidebar'
+import { StoreIcon } from 'lucide-react'
+
+export function StoreSwitcher() {
+ return (
+ <SidebarMenu>
+ <SidebarMenuItem>
+ <SidebarMenuButton size="lg">
+ <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+ <StoreIcon className="size-4" />
+ </div>
+ <div className="grid flex-1 text-left text-sm leading-tight">
+ <span className="truncate font-medium">Spree Store</span>
+ <span className="truncate text-xs text-muted-foreground">Admin</span>
+ </div>
+ </SidebarMenuButton>
+ </SidebarMenuItem>
+ </SidebarMenu>
+ )
+}
diff --git a/packages/admin/src/components/ui/avatar.tsx b/packages/admin/src/components/ui/avatar.tsx
new file mode 100644
index 0000000000..99f3ed25f0
--- /dev/null
+++ b/packages/admin/src/components/ui/avatar.tsx
@@ -0,0 +1,110 @@
+import * as React from "react"
+import { Avatar as AvatarPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Avatar({
+ className,
+ size = "default",
+ ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Root> & {
+ size?: "default" | "sm" | "lg"
+}) {
+ return (
+ <AvatarPrimitive.Root
+ data-slot="avatar"
+ data-size={size}
+ className={cn(
+ "group/avatar relative flex size-8 shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:border-border after:mix-blend-darken data-[size=lg]:size-10 data-[size=sm]:size-6 dark:after:mix-blend-lighten",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function AvatarImage({
+ className,
+ ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Image>) {
+ return (
+ <AvatarPrimitive.Image
+ data-slot="avatar-image"
+ className={cn(
+ "aspect-square size-full rounded-full object-cover",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function AvatarFallback({
+ className,
+ ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Fallback>) {
+ return (
+ <AvatarPrimitive.Fallback
+ data-slot="avatar-fallback"
+ className={cn(
+ "flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground group-data-[size=sm]/avatar:text-xs",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
+ return (
+ <span
+ data-slot="avatar-badge"
+ className={cn(
+ "absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground bg-blend-color ring-2 ring-background select-none",
+ "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
+ "group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
+ "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="avatar-group"
+ className={cn(
+ "group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function AvatarGroupCount({
+ className,
+ ...props
+}: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="avatar-group-count"
+ className={cn(
+ "relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ring-2 ring-background group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+export {
+ Avatar,
+ AvatarImage,
+ AvatarFallback,
+ AvatarGroup,
+ AvatarGroupCount,
+ AvatarBadge,
+}
diff --git a/packages/admin/src/components/ui/breadcrumb.tsx b/packages/admin/src/components/ui/breadcrumb.tsx
new file mode 100644
index 0000000000..db9afc0c0f
--- /dev/null
+++ b/packages/admin/src/components/ui/breadcrumb.tsx
@@ -0,0 +1,122 @@
+import * as React from "react"
+import { Slot } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+import { ChevronRightIcon, MoreHorizontalIcon } from "lucide-react"
+
+function Breadcrumb({ className, ...props }: React.ComponentProps<"nav">) {
+ return (
+ <nav
+ aria-label="breadcrumb"
+ data-slot="breadcrumb"
+ className={cn(className)}
+ {...props}
+ />
+ )
+}
+
+function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
+ return (
+ <ol
+ data-slot="breadcrumb-list"
+ className={cn(
+ "flex flex-wrap items-center gap-1.5 text-sm wrap-break-word text-muted-foreground",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
+ return (
+ <li
+ data-slot="breadcrumb-item"
+ className={cn("inline-flex items-center gap-1", className)}
+ {...props}
+ />
+ )
+}
+
+function BreadcrumbLink({
+ asChild,
+ className,
+ ...props
+}: React.ComponentProps<"a"> & {
+ asChild?: boolean
+}) {
+ const Comp = asChild ? Slot.Root : "a"
+
+ return (
+ <Comp
+ data-slot="breadcrumb-link"
+ className={cn("transition-colors hover:text-foreground", className)}
+ {...props}
+ />
+ )
+}
+
+function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
+ return (
+ <span
+ data-slot="breadcrumb-page"
+ role="link"
+ aria-disabled="true"
+ aria-current="page"
+ className={cn("font-normal text-foreground", className)}
+ {...props}
+ />
+ )
+}
+
+function BreadcrumbSeparator({
+ children,
+ className,
+ ...props
+}: React.ComponentProps<"li">) {
+ return (
+ <li
+ data-slot="breadcrumb-separator"
+ role="presentation"
+ aria-hidden="true"
+ className={cn("[&>svg]:size-3.5", className)}
+ {...props}
+ >
+ {children ?? (
+ <ChevronRightIcon />
+ )}
+ </li>
+ )
+}
+
+function BreadcrumbEllipsis({
+ className,
+ ...props
+}: React.ComponentProps<"span">) {
+ return (
+ <span
+ data-slot="breadcrumb-ellipsis"
+ role="presentation"
+ aria-hidden="true"
+ className={cn(
+ "flex size-5 items-center justify-center [&>svg]:size-4",
+ className
+ )}
+ {...props}
+ >
+ <MoreHorizontalIcon
+ />
+ <span className="sr-only">More</span>
+ </span>
+ )
+}
+
+export {
+ Breadcrumb,
+ BreadcrumbList,
+ BreadcrumbItem,
+ BreadcrumbLink,
+ BreadcrumbPage,
+ BreadcrumbSeparator,
+ BreadcrumbEllipsis,
+}
diff --git a/packages/admin/src/components/ui/button.tsx b/packages/admin/src/components/ui/button.tsx
new file mode 100644
index 0000000000..ec4be64ba7
--- /dev/null
+++ b/packages/admin/src/components/ui/button.tsx
@@ -0,0 +1,67 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { Slot } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+ "group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+ {
+ variants: {
+ variant: {
+ default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
+ outline:
+ "border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
+ secondary:
+ "bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
+ ghost:
+ "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
+ destructive:
+ "bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
+ link: "text-primary underline-offset-4 hover:underline",
+ },
+ size: {
+ default:
+ "h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+ xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+ sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+ lg: "h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3",
+ icon: "size-8",
+ "icon-xs":
+ "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+ "icon-sm":
+ "size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
+ "icon-lg": "size-9",
+ },
+ },
+ defaultVariants: {
+ variant: "default",
+ size: "default",
+ },
+ }
+)
+
+function Button({
+ className,
+ variant = "default",
+ size = "default",
+ asChild = false,
+ ...props
+}: React.ComponentProps<"button"> &
+ VariantProps<typeof buttonVariants> & {
+ asChild?: boolean
+ }) {
+ const Comp = asChild ? Slot.Root : "button"
+
+ return (
+ <Comp
+ data-slot="button"
+ data-variant={variant}
+ data-size={size}
+ className={cn(buttonVariants({ variant, size, className }))}
+ {...props}
+ />
+ )
+}
+
+export { Button, buttonVariants }
diff --git a/packages/admin/src/components/ui/card.tsx b/packages/admin/src/components/ui/card.tsx
new file mode 100644
index 0000000000..9bd5a2544b
--- /dev/null
+++ b/packages/admin/src/components/ui/card.tsx
@@ -0,0 +1,103 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Card({
+ className,
+ size = "default",
+ ...props
+}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
+ return (
+ <div
+ data-slot="card"
+ data-size={size}
+ className={cn(
+ "group/card flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-foreground/10 has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:py-3 data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="card-header"
+ className={cn(
+ "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-4 group-data-[size=sm]/card:px-3 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-4 group-data-[size=sm]/card:[.border-b]:pb-3",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="card-title"
+ className={cn(
+ "text-base leading-snug font-medium group-data-[size=sm]/card:text-sm",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="card-description"
+ className={cn("text-sm text-muted-foreground", className)}
+ {...props}
+ />
+ )
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="card-action"
+ className={cn(
+ "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="card-content"
+ className={cn("px-4 group-data-[size=sm]/card:px-3", className)}
+ {...props}
+ />
+ )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="card-footer"
+ className={cn(
+ "flex items-center rounded-b-xl border-t bg-muted/50 p-4 group-data-[size=sm]/card:p-3",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+export {
+ Card,
+ CardHeader,
+ CardFooter,
+ CardTitle,
+ CardAction,
+ CardDescription,
+ CardContent,
+}
diff --git a/packages/admin/src/components/ui/collapsible.tsx b/packages/admin/src/components/ui/collapsible.tsx
new file mode 100644
index 0000000000..63fc8eff3f
--- /dev/null
+++ b/packages/admin/src/components/ui/collapsible.tsx
@@ -0,0 +1,31 @@
+import { Collapsible as CollapsiblePrimitive } from "radix-ui"
+
+function Collapsible({
+ ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.Root>) {
+ return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />
+}
+
+function CollapsibleTrigger({
+ ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>) {
+ return (
+ <CollapsiblePrimitive.CollapsibleTrigger
+ data-slot="collapsible-trigger"
+ {...props}
+ />
+ )
+}
+
+function CollapsibleContent({
+ ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>) {
+ return (
+ <CollapsiblePrimitive.CollapsibleContent
+ data-slot="collapsible-content"
+ {...props}
+ />
+ )
+}
+
+export { Collapsible, CollapsibleTrigger, CollapsibleContent }
diff --git a/packages/admin/src/components/ui/dropdown-menu.tsx b/packages/admin/src/components/ui/dropdown-menu.tsx
new file mode 100644
index 0000000000..c263ad57ea
--- /dev/null
+++ b/packages/admin/src/components/ui/dropdown-menu.tsx
@@ -0,0 +1,269 @@
+"use client"
+
+import * as React from "react"
+import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+import { CheckIcon, ChevronRightIcon } from "lucide-react"
+
+function DropdownMenu({
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
+ return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />
+}
+
+function DropdownMenuPortal({
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+ return (
+ <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
+ )
+}
+
+function DropdownMenuTrigger({
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+ return (
+ <DropdownMenuPrimitive.Trigger
+ data-slot="dropdown-menu-trigger"
+ {...props}
+ />
+ )
+}
+
+function DropdownMenuContent({
+ className,
+ align = "start",
+ sideOffset = 4,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+ return (
+ <DropdownMenuPrimitive.Portal>
+ <DropdownMenuPrimitive.Content
+ data-slot="dropdown-menu-content"
+ sideOffset={sideOffset}
+ align={align}
+ className={cn("z-50 max-h-(--radix-dropdown-menu-content-available-height) w-(--radix-dropdown-menu-trigger-width) min-w-32 origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-lg bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:overflow-hidden data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
+ {...props}
+ />
+ </DropdownMenuPrimitive.Portal>
+ )
+}
+
+function DropdownMenuGroup({
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
+ return (
+ <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />
+ )
+}
+
+function DropdownMenuItem({
+ className,
+ inset,
+ variant = "default",
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+ inset?: boolean
+ variant?: "default" | "destructive"
+}) {
+ return (
+ <DropdownMenuPrimitive.Item
+ data-slot="dropdown-menu-item"
+ data-inset={inset}
+ data-variant={variant}
+ className={cn(
+ "group/dropdown-menu-item relative flex cursor-default items-center gap-1.5 rounded-md px-1.5 py-1 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function DropdownMenuCheckboxItem({
+ className,
+ children,
+ checked,
+ inset,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem> & {
+ inset?: boolean
+}) {
+ return (
+ <DropdownMenuPrimitive.CheckboxItem
+ data-slot="dropdown-menu-checkbox-item"
+ data-inset={inset}
+ className={cn(
+ "relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+ className
+ )}
+ checked={checked}
+ {...props}
+ >
+ <span
+ className="pointer-events-none absolute right-2 flex items-center justify-center"
+ data-slot="dropdown-menu-checkbox-item-indicator"
+ >
+ <DropdownMenuPrimitive.ItemIndicator>
+ <CheckIcon
+ />
+ </DropdownMenuPrimitive.ItemIndicator>
+ </span>
+ {children}
+ </DropdownMenuPrimitive.CheckboxItem>
+ )
+}
+
+function DropdownMenuRadioGroup({
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+ return (
+ <DropdownMenuPrimitive.RadioGroup
+ data-slot="dropdown-menu-radio-group"
+ {...props}
+ />
+ )
+}
+
+function DropdownMenuRadioItem({
+ className,
+ children,
+ inset,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem> & {
+ inset?: boolean
+}) {
+ return (
+ <DropdownMenuPrimitive.RadioItem
+ data-slot="dropdown-menu-radio-item"
+ data-inset={inset}
+ className={cn(
+ "relative flex cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+ className
+ )}
+ {...props}
+ >
+ <span
+ className="pointer-events-none absolute right-2 flex items-center justify-center"
+ data-slot="dropdown-menu-radio-item-indicator"
+ >
+ <DropdownMenuPrimitive.ItemIndicator>
+ <CheckIcon
+ />
+ </DropdownMenuPrimitive.ItemIndicator>
+ </span>
+ {children}
+ </DropdownMenuPrimitive.RadioItem>
+ )
+}
+
+function DropdownMenuLabel({
+ className,
+ inset,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+ inset?: boolean
+}) {
+ return (
+ <DropdownMenuPrimitive.Label
+ data-slot="dropdown-menu-label"
+ data-inset={inset}
+ className={cn(
+ "px-1.5 py-1 text-xs font-medium text-muted-foreground data-inset:pl-7",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function DropdownMenuSeparator({
+ className,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+ return (
+ <DropdownMenuPrimitive.Separator
+ data-slot="dropdown-menu-separator"
+ className={cn("-mx-1 my-1 h-px bg-border", className)}
+ {...props}
+ />
+ )
+}
+
+function DropdownMenuShortcut({
+ className,
+ ...props
+}: React.ComponentProps<"span">) {
+ return (
+ <span
+ data-slot="dropdown-menu-shortcut"
+ className={cn(
+ "ml-auto text-xs tracking-widest text-muted-foreground group-focus/dropdown-menu-item:text-accent-foreground",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function DropdownMenuSub({
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+ return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />
+}
+
+function DropdownMenuSubTrigger({
+ className,
+ inset,
+ children,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+ inset?: boolean
+}) {
+ return (
+ <DropdownMenuPrimitive.SubTrigger
+ data-slot="dropdown-menu-sub-trigger"
+ data-inset={inset}
+ className={cn(
+ "flex cursor-default items-center gap-1.5 rounded-md px-1.5 py-1 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-open:bg-accent data-open:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+ className
+ )}
+ {...props}
+ >
+ {children}
+ <ChevronRightIcon className="ml-auto" />
+ </DropdownMenuPrimitive.SubTrigger>
+ )
+}
+
+function DropdownMenuSubContent({
+ className,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+ return (
+ <DropdownMenuPrimitive.SubContent
+ data-slot="dropdown-menu-sub-content"
+ className={cn("z-50 min-w-[96px] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-lg bg-popover p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
+ {...props}
+ />
+ )
+}
+
+export {
+ DropdownMenu,
+ DropdownMenuPortal,
+ DropdownMenuTrigger,
+ DropdownMenuContent,
+ DropdownMenuGroup,
+ DropdownMenuLabel,
+ DropdownMenuItem,
+ DropdownMenuCheckboxItem,
+ DropdownMenuRadioGroup,
+ DropdownMenuRadioItem,
+ DropdownMenuSeparator,
+ DropdownMenuShortcut,
+ DropdownMenuSub,
+ DropdownMenuSubTrigger,
+ DropdownMenuSubContent,
+}
diff --git a/packages/admin/src/components/ui/input.tsx b/packages/admin/src/components/ui/input.tsx
new file mode 100644
index 0000000000..d763cd9ab0
--- /dev/null
+++ b/packages/admin/src/components/ui/input.tsx
@@ -0,0 +1,19 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+ return (
+ <input
+ type={type}
+ data-slot="input"
+ className={cn(
+ "h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+export { Input }
diff --git a/packages/admin/src/components/ui/label.tsx b/packages/admin/src/components/ui/label.tsx
new file mode 100644
index 0000000000..f752f82ba6
--- /dev/null
+++ b/packages/admin/src/components/ui/label.tsx
@@ -0,0 +1,22 @@
+import * as React from "react"
+import { Label as LabelPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Label({
+ className,
+ ...props
+}: React.ComponentProps<typeof LabelPrimitive.Root>) {
+ return (
+ <LabelPrimitive.Root
+ data-slot="label"
+ className={cn(
+ "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+export { Label }
diff --git a/packages/admin/src/components/ui/separator.tsx b/packages/admin/src/components/ui/separator.tsx
new file mode 100644
index 0000000000..ca11501513
--- /dev/null
+++ b/packages/admin/src/components/ui/separator.tsx
@@ -0,0 +1,26 @@
+import * as React from "react"
+import { Separator as SeparatorPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Separator({
+ className,
+ orientation = "horizontal",
+ decorative = true,
+ ...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+ return (
+ <SeparatorPrimitive.Root
+ data-slot="separator"
+ decorative={decorative}
+ orientation={orientation}
+ className={cn(
+ "shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+export { Separator }
diff --git a/packages/admin/src/components/ui/sheet.tsx b/packages/admin/src/components/ui/sheet.tsx
new file mode 100644
index 0000000000..bcb2527569
--- /dev/null
+++ b/packages/admin/src/components/ui/sheet.tsx
@@ -0,0 +1,144 @@
+"use client"
+
+import * as React from "react"
+import { Dialog as SheetPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { XIcon } from "lucide-react"
+
+function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
+ return <SheetPrimitive.Root data-slot="sheet" {...props} />
+}
+
+function SheetTrigger({
+ ...props
+}: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
+ return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />
+}
+
+function SheetClose({
+ ...props
+}: React.ComponentProps<typeof SheetPrimitive.Close>) {
+ return <SheetPrimitive.Close data-slot="sheet-close" {...props} />
+}
+
+function SheetPortal({
+ ...props
+}: React.ComponentProps<typeof SheetPrimitive.Portal>) {
+ return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />
+}
+
+function SheetOverlay({
+ className,
+ ...props
+}: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
+ return (
+ <SheetPrimitive.Overlay
+ data-slot="sheet-overlay"
+ className={cn(
+ "fixed inset-0 z-50 bg-black/10 duration-100 data-ending-style:opacity-0 data-starting-style:opacity-0 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function SheetContent({
+ className,
+ children,
+ side = "right",
+ showCloseButton = true,
+ ...props
+}: React.ComponentProps<typeof SheetPrimitive.Content> & {
+ side?: "top" | "right" | "bottom" | "left"
+ showCloseButton?: boolean
+}) {
+ return (
+ <SheetPortal>
+ <SheetOverlay />
+ <SheetPrimitive.Content
+ data-slot="sheet-content"
+ data-side={side}
+ className={cn(
+ "fixed z-50 flex flex-col gap-4 bg-background bg-clip-padding text-sm shadow-lg transition duration-200 ease-in-out data-[side=bottom]:inset-x-0 data-[side=bottom]:bottom-0 data-[side=bottom]:h-auto data-[side=bottom]:border-t data-[side=left]:inset-y-0 data-[side=left]:left-0 data-[side=left]:h-full data-[side=left]:w-3/4 data-[side=left]:border-r data-[side=right]:inset-y-0 data-[side=right]:right-0 data-[side=right]:h-full data-[side=right]:w-3/4 data-[side=right]:border-l data-[side=top]:inset-x-0 data-[side=top]:top-0 data-[side=top]:h-auto data-[side=top]:border-b data-[side=left]:sm:max-w-sm data-[side=right]:sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-[side=bottom]:data-open:slide-in-from-bottom-10 data-[side=left]:data-open:slide-in-from-left-10 data-[side=right]:data-open:slide-in-from-right-10 data-[side=top]:data-open:slide-in-from-top-10 data-closed:animate-out data-closed:fade-out-0 data-[side=bottom]:data-closed:slide-out-to-bottom-10 data-[side=left]:data-closed:slide-out-to-left-10 data-[side=right]:data-closed:slide-out-to-right-10 data-[side=top]:data-closed:slide-out-to-top-10",
+ className
+ )}
+ {...props}
+ >
+ {children}
+ {showCloseButton && (
+ <SheetPrimitive.Close data-slot="sheet-close" asChild>
+ <Button
+ variant="ghost"
+ className="absolute top-3 right-3"
+ size="icon-sm"
+ >
+ <XIcon
+ />
+ <span className="sr-only">Close</span>
+ </Button>
+ </SheetPrimitive.Close>
+ )}
+ </SheetPrimitive.Content>
+ </SheetPortal>
+ )
+}
+
+function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="sheet-header"
+ className={cn("flex flex-col gap-0.5 p-4", className)}
+ {...props}
+ />
+ )
+}
+
+function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="sheet-footer"
+ className={cn("mt-auto flex flex-col gap-2 p-4", className)}
+ {...props}
+ />
+ )
+}
+
+function SheetTitle({
+ className,
+ ...props
+}: React.ComponentProps<typeof SheetPrimitive.Title>) {
+ return (
+ <SheetPrimitive.Title
+ data-slot="sheet-title"
+ className={cn("text-base font-medium text-foreground", className)}
+ {...props}
+ />
+ )
+}
+
+function SheetDescription({
+ className,
+ ...props
+}: React.ComponentProps<typeof SheetPrimitive.Description>) {
+ return (
+ <SheetPrimitive.Description
+ data-slot="sheet-description"
+ className={cn("text-sm text-muted-foreground", className)}
+ {...props}
+ />
+ )
+}
+
+export {
+ Sheet,
+ SheetTrigger,
+ SheetClose,
+ SheetContent,
+ SheetHeader,
+ SheetFooter,
+ SheetTitle,
+ SheetDescription,
+}
diff --git a/packages/admin/src/components/ui/sidebar.tsx b/packages/admin/src/components/ui/sidebar.tsx
new file mode 100644
index 0000000000..e245caa3e8
--- /dev/null
+++ b/packages/admin/src/components/ui/sidebar.tsx
@@ -0,0 +1,700 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { Slot } from "radix-ui"
+
+import { useIsMobile } from "@/hooks/use-mobile"
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Separator } from "@/components/ui/separator"
+import {
+ Sheet,
+ SheetContent,
+ SheetDescription,
+ SheetHeader,
+ SheetTitle,
+} from "@/components/ui/sheet"
+import { Skeleton } from "@/components/ui/skeleton"
+import {
+ Tooltip,
+ TooltipContent,
+ TooltipTrigger,
+} from "@/components/ui/tooltip"
+import { PanelLeftIcon } from "lucide-react"
+
+const SIDEBAR_COOKIE_NAME = "sidebar_state"
+const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7
+const SIDEBAR_WIDTH = "16rem"
+const SIDEBAR_WIDTH_MOBILE = "18rem"
+const SIDEBAR_WIDTH_ICON = "3rem"
+const SIDEBAR_KEYBOARD_SHORTCUT = "b"
+
+type SidebarContextProps = {
+ state: "expanded" | "collapsed"
+ open: boolean
+ setOpen: (open: boolean) => void
+ openMobile: boolean
+ setOpenMobile: (open: boolean) => void
+ isMobile: boolean
+ toggleSidebar: () => void
+}
+
+const SidebarContext = React.createContext<SidebarContextProps | null>(null)
+
+function useSidebar() {
+ const context = React.useContext(SidebarContext)
+ if (!context) {
+ throw new Error("useSidebar must be used within a SidebarProvider.")
+ }
+
+ return context
+}
+
+function SidebarProvider({
+ defaultOpen = true,
+ open: openProp,
+ onOpenChange: setOpenProp,
+ className,
+ style,
+ children,
+ ...props
+}: React.ComponentProps<"div"> & {
+ defaultOpen?: boolean
+ open?: boolean
+ onOpenChange?: (open: boolean) => void
+}) {
+ const isMobile = useIsMobile()
+ const [openMobile, setOpenMobile] = React.useState(false)
+
+ // This is the internal state of the sidebar.
+ // We use openProp and setOpenProp for control from outside the component.
+ const [_open, _setOpen] = React.useState(defaultOpen)
+ const open = openProp ?? _open
+ const setOpen = React.useCallback(
+ (value: boolean | ((value: boolean) => boolean)) => {
+ const openState = typeof value === "function" ? value(open) : value
+ if (setOpenProp) {
+ setOpenProp(openState)
+ } else {
+ _setOpen(openState)
+ }
+
+ // This sets the cookie to keep the sidebar state.
+ document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`
+ },
+ [setOpenProp, open]
+ )
+
+ // Helper to toggle the sidebar.
+ const toggleSidebar = React.useCallback(() => {
+ return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open)
+ }, [isMobile, setOpen, setOpenMobile])
+
+ // Adds a keyboard shortcut to toggle the sidebar.
+ React.useEffect(() => {
+ const handleKeyDown = (event: KeyboardEvent) => {
+ if (
+ event.key === SIDEBAR_KEYBOARD_SHORTCUT &&
+ (event.metaKey || event.ctrlKey)
+ ) {
+ event.preventDefault()
+ toggleSidebar()
+ }
+ }
+
+ window.addEventListener("keydown", handleKeyDown)
+ return () => window.removeEventListener("keydown", handleKeyDown)
+ }, [toggleSidebar])
+
+ // We add a state so that we can do data-state="expanded" or "collapsed".
+ // This makes it easier to style the sidebar with Tailwind classes.
+ const state = open ? "expanded" : "collapsed"
+
+ const contextValue = React.useMemo<SidebarContextProps>(
+ () => ({
+ state,
+ open,
+ setOpen,
+ isMobile,
+ openMobile,
+ setOpenMobile,
+ toggleSidebar,
+ }),
+ [state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar]
+ )
+
+ return (
+ <SidebarContext.Provider value={contextValue}>
+ <div
+ data-slot="sidebar-wrapper"
+ style={
+ {
+ "--sidebar-width": SIDEBAR_WIDTH,
+ "--sidebar-width-icon": SIDEBAR_WIDTH_ICON,
+ ...style,
+ } as React.CSSProperties
+ }
+ className={cn(
+ "group/sidebar-wrapper flex min-h-svh w-full has-data-[variant=inset]:bg-sidebar",
+ className
+ )}
+ {...props}
+ >
+ {children}
+ </div>
+ </SidebarContext.Provider>
+ )
+}
+
+function Sidebar({
+ side = "left",
+ variant = "sidebar",
+ collapsible = "offcanvas",
+ className,
+ children,
+ dir,
+ ...props
+}: React.ComponentProps<"div"> & {
+ side?: "left" | "right"
+ variant?: "sidebar" | "floating" | "inset"
+ collapsible?: "offcanvas" | "icon" | "none"
+}) {
+ const { isMobile, state, openMobile, setOpenMobile } = useSidebar()
+
+ if (collapsible === "none") {
+ return (
+ <div
+ data-slot="sidebar"
+ className={cn(
+ "flex h-full w-(--sidebar-width) flex-col bg-sidebar text-sidebar-foreground",
+ className
+ )}
+ {...props}
+ >
+ {children}
+ </div>
+ )
+ }
+
+ if (isMobile) {
+ return (
+ <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
+ <SheetContent
+ dir={dir}
+ data-sidebar="sidebar"
+ data-slot="sidebar"
+ data-mobile="true"
+ className="w-(--sidebar-width) bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden"
+ style={
+ {
+ "--sidebar-width": SIDEBAR_WIDTH_MOBILE,
+ } as React.CSSProperties
+ }
+ side={side}
+ >
+ <SheetHeader className="sr-only">
+ <SheetTitle>Sidebar</SheetTitle>
+ <SheetDescription>Displays the mobile sidebar.</SheetDescription>
+ </SheetHeader>
+ <div className="flex h-full w-full flex-col">{children}</div>
+ </SheetContent>
+ </Sheet>
+ )
+ }
+
+ return (
+ <div
+ className="group peer hidden text-sidebar-foreground md:block"
+ data-state={state}
+ data-collapsible={state === "collapsed" ? collapsible : ""}
+ data-variant={variant}
+ data-side={side}
+ data-slot="sidebar"
+ >
+ {/* This is what handles the sidebar gap on desktop */}
+ <div
+ data-slot="sidebar-gap"
+ className={cn(
+ "relative w-(--sidebar-width) bg-transparent transition-[width] duration-200 ease-linear",
+ "group-data-[collapsible=offcanvas]:w-0",
+ "group-data-[side=right]:rotate-180",
+ variant === "floating" || variant === "inset"
+ ? "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]"
+ : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)"
+ )}
+ />
+ <div
+ data-slot="sidebar-container"
+ data-side={side}
+ className={cn(
+ "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear data-[side=left]:left-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] data-[side=right]:right-0 data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)] md:flex",
+ // Adjust the padding for floating and inset variants.
+ variant === "floating" || variant === "inset"
+ ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"
+ : "group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l",
+ className
+ )}
+ {...props}
+ >
+ <div
+ data-sidebar="sidebar"
+ data-slot="sidebar-inner"
+ className="flex size-full flex-col bg-sidebar group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:shadow-sm group-data-[variant=floating]:ring-1 group-data-[variant=floating]:ring-sidebar-border"
+ >
+ {children}
+ </div>
+ </div>
+ </div>
+ )
+}
+
+function SidebarTrigger({
+ className,
+ onClick,
+ ...props
+}: React.ComponentProps<typeof Button>) {
+ const { toggleSidebar } = useSidebar()
+
+ return (
+ <Button
+ data-sidebar="trigger"
+ data-slot="sidebar-trigger"
+ variant="ghost"
+ size="icon-sm"
+ className={cn(className)}
+ onClick={(event) => {
+ onClick?.(event)
+ toggleSidebar()
+ }}
+ {...props}
+ >
+ <PanelLeftIcon />
+ <span className="sr-only">Toggle Sidebar</span>
+ </Button>
+ )
+}
+
+function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
+ const { toggleSidebar } = useSidebar()
+
+ return (
+ <button
+ data-sidebar="rail"
+ data-slot="sidebar-rail"
+ aria-label="Toggle Sidebar"
+ tabIndex={-1}
+ onClick={toggleSidebar}
+ title="Toggle Sidebar"
+ className={cn(
+ "absolute inset-y-0 z-20 hidden w-4 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] hover:after:bg-sidebar-border sm:flex ltr:-translate-x-1/2 rtl:-translate-x-1/2",
+ "in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize",
+ "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
+ "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full hover:group-data-[collapsible=offcanvas]:bg-sidebar",
+ "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
+ "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
+ return (
+ <main
+ data-slot="sidebar-inset"
+ className={cn(
+ "relative flex w-full flex-1 flex-col bg-background md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function SidebarInput({
+ className,
+ ...props
+}: React.ComponentProps<typeof Input>) {
+ return (
+ <Input
+ data-slot="sidebar-input"
+ data-sidebar="input"
+ className={cn("h-8 w-full bg-background shadow-none", className)}
+ {...props}
+ />
+ )
+}
+
+function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="sidebar-header"
+ data-sidebar="header"
+ className={cn("flex flex-col gap-2 p-2", className)}
+ {...props}
+ />
+ )
+}
+
+function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="sidebar-footer"
+ data-sidebar="footer"
+ className={cn("flex flex-col gap-2 p-2", className)}
+ {...props}
+ />
+ )
+}
+
+function SidebarSeparator({
+ className,
+ ...props
+}: React.ComponentProps<typeof Separator>) {
+ return (
+ <Separator
+ data-slot="sidebar-separator"
+ data-sidebar="separator"
+ className={cn("mx-2 w-auto bg-sidebar-border", className)}
+ {...props}
+ />
+ )
+}
+
+function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="sidebar-content"
+ data-sidebar="content"
+ className={cn(
+ "no-scrollbar flex min-h-0 flex-1 flex-col gap-0 overflow-auto group-data-[collapsible=icon]:overflow-hidden",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="sidebar-group"
+ data-sidebar="group"
+ className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
+ {...props}
+ />
+ )
+}
+
+function SidebarGroupLabel({
+ className,
+ asChild = false,
+ ...props
+}: React.ComponentProps<"div"> & { asChild?: boolean }) {
+ const Comp = asChild ? Slot.Root : "div"
+
+ return (
+ <Comp
+ data-slot="sidebar-group-label"
+ data-sidebar="group-label"
+ className={cn(
+ "flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium text-sidebar-foreground/70 ring-sidebar-ring outline-hidden transition-[margin,opacity] duration-200 ease-linear group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function SidebarGroupAction({
+ className,
+ asChild = false,
+ ...props
+}: React.ComponentProps<"button"> & { asChild?: boolean }) {
+ const Comp = asChild ? Slot.Root : "button"
+
+ return (
+ <Comp
+ data-slot="sidebar-group-action"
+ data-sidebar="group-action"
+ className={cn(
+ "absolute top-3.5 right-3 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function SidebarGroupContent({
+ className,
+ ...props
+}: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="sidebar-group-content"
+ data-sidebar="group-content"
+ className={cn("w-full text-sm", className)}
+ {...props}
+ />
+ )
+}
+
+function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
+ return (
+ <ul
+ data-slot="sidebar-menu"
+ data-sidebar="menu"
+ className={cn("flex w-full min-w-0 flex-col gap-0", className)}
+ {...props}
+ />
+ )
+}
+
+function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
+ return (
+ <li
+ data-slot="sidebar-menu-item"
+ data-sidebar="menu-item"
+ className={cn("group/menu-item relative", className)}
+ {...props}
+ />
+ )
+}
+
+const sidebarMenuButtonVariants = cva(
+ "peer/menu-button group/menu-button flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-left text-sm ring-sidebar-ring outline-hidden transition-[width,height,padding] group-has-data-[sidebar=menu-action]/menu-item:pr-8 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground data-active:bg-sidebar-accent data-active:font-medium data-active:text-sidebar-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0 [&>span:last-child]:truncate",
+ {
+ variants: {
+ variant: {
+ default: "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+ outline:
+ "bg-background shadow-[0_0_0_1px_hsl(var(--sidebar-border))] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_hsl(var(--sidebar-accent))]",
+ },
+ size: {
+ default: "h-8 text-sm",
+ sm: "h-7 text-xs",
+ lg: "h-12 text-sm group-data-[collapsible=icon]:p-0!",
+ },
+ },
+ defaultVariants: {
+ variant: "default",
+ size: "default",
+ },
+ }
+)
+
+function SidebarMenuButton({
+ asChild = false,
+ isActive = false,
+ variant = "default",
+ size = "default",
+ tooltip,
+ className,
+ ...props
+}: React.ComponentProps<"button"> & {
+ asChild?: boolean
+ isActive?: boolean
+ tooltip?: string | React.ComponentProps<typeof TooltipContent>
+} & VariantProps<typeof sidebarMenuButtonVariants>) {
+ const Comp = asChild ? Slot.Root : "button"
+ const { isMobile, state } = useSidebar()
+
+ const button = (
+ <Comp
+ data-slot="sidebar-menu-button"
+ data-sidebar="menu-button"
+ data-size={size}
+ data-active={isActive}
+ className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
+ {...props}
+ />
+ )
+
+ if (!tooltip) {
+ return button
+ }
+
+ if (typeof tooltip === "string") {
+ tooltip = {
+ children: tooltip,
+ }
+ }
+
+ return (
+ <Tooltip>
+ <TooltipTrigger asChild>{button}</TooltipTrigger>
+ <TooltipContent
+ side="right"
+ align="center"
+ hidden={state !== "collapsed" || isMobile}
+ {...tooltip}
+ />
+ </Tooltip>
+ )
+}
+
+function SidebarMenuAction({
+ className,
+ asChild = false,
+ showOnHover = false,
+ ...props
+}: React.ComponentProps<"button"> & {
+ asChild?: boolean
+ showOnHover?: boolean
+}) {
+ const Comp = asChild ? Slot.Root : "button"
+
+ return (
+ <Comp
+ data-slot="sidebar-menu-action"
+ data-sidebar="menu-action"
+ className={cn(
+ "absolute top-1.5 right-1 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
+ showOnHover &&
+ "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 peer-data-active/menu-button:text-sidebar-accent-foreground aria-expanded:opacity-100 md:opacity-0",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function SidebarMenuBadge({
+ className,
+ ...props
+}: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="sidebar-menu-badge"
+ data-sidebar="menu-badge"
+ className={cn(
+ "pointer-events-none absolute right-1 flex h-5 min-w-5 items-center justify-center rounded-md px-1 text-xs font-medium text-sidebar-foreground tabular-nums select-none group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 peer-data-active/menu-button:text-sidebar-accent-foreground",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function SidebarMenuSkeleton({
+ className,
+ showIcon = false,
+ ...props
+}: React.ComponentProps<"div"> & {
+ showIcon?: boolean
+}) {
+ // Random width between 50 to 90%.
+ const [width] = React.useState(() => {
+ return `${Math.floor(Math.random() * 40) + 50}%`
+ })
+
+ return (
+ <div
+ data-slot="sidebar-menu-skeleton"
+ data-sidebar="menu-skeleton"
+ className={cn("flex h-8 items-center gap-2 rounded-md px-2", className)}
+ {...props}
+ >
+ {showIcon && (
+ <Skeleton
+ className="size-4 rounded-md"
+ data-sidebar="menu-skeleton-icon"
+ />
+ )}
+ <Skeleton
+ className="h-4 max-w-(--skeleton-width) flex-1"
+ data-sidebar="menu-skeleton-text"
+ style={
+ {
+ "--skeleton-width": width,
+ } as React.CSSProperties
+ }
+ />
+ </div>
+ )
+}
+
+function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
+ return (
+ <ul
+ data-slot="sidebar-menu-sub"
+ data-sidebar="menu-sub"
+ className={cn(
+ "mx-3.5 flex min-w-0 translate-x-px flex-col gap-1 border-l border-sidebar-border px-2.5 py-0.5 group-data-[collapsible=icon]:hidden",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+function SidebarMenuSubItem({
+ className,
+ ...props
+}: React.ComponentProps<"li">) {
+ return (
+ <li
+ data-slot="sidebar-menu-sub-item"
+ data-sidebar="menu-sub-item"
+ className={cn("group/menu-sub-item relative", className)}
+ {...props}
+ />
+ )
+}
+
+function SidebarMenuSubButton({
+ asChild = false,
+ size = "md",
+ isActive = false,
+ className,
+ ...props
+}: React.ComponentProps<"a"> & {
+ asChild?: boolean
+ size?: "sm" | "md"
+ isActive?: boolean
+}) {
+ const Comp = asChild ? Slot.Root : "a"
+
+ return (
+ <Comp
+ data-slot="sidebar-menu-sub-button"
+ data-sidebar="menu-sub-button"
+ data-size={size}
+ data-active={isActive}
+ className={cn(
+ "flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 text-sidebar-foreground ring-sidebar-ring outline-hidden group-data-[collapsible=icon]:hidden hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[size=md]:text-sm data-[size=sm]:text-xs data-active:bg-sidebar-accent data-active:text-sidebar-accent-foreground [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground",
+ className
+ )}
+ {...props}
+ />
+ )
+}
+
+export {
+ Sidebar,
+ SidebarContent,
+ SidebarFooter,
+ SidebarGroup,
+ SidebarGroupAction,
+ SidebarGroupContent,
+ SidebarGroupLabel,
+ SidebarHeader,
+ SidebarInput,
+ SidebarInset,
+ SidebarMenu,
+ SidebarMenuAction,
+ SidebarMenuBadge,
+ SidebarMenuButton,
+ SidebarMenuItem,
+ SidebarMenuSkeleton,
+ SidebarMenuSub,
+ SidebarMenuSubButton,
+ SidebarMenuSubItem,
+ SidebarProvider,
+ SidebarRail,
+ SidebarSeparator,
+ SidebarTrigger,
+ useSidebar,
+}
diff --git a/packages/admin/src/components/ui/skeleton.tsx b/packages/admin/src/components/ui/skeleton.tsx
new file mode 100644
index 0000000000..0118624f6e
--- /dev/null
+++ b/packages/admin/src/components/ui/skeleton.tsx
@@ -0,0 +1,13 @@
+import { cn } from "@/lib/utils"
+
+function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
+ return (
+ <div
+ data-slot="skeleton"
+ className={cn("animate-pulse rounded-md bg-muted", className)}
+ {...props}
+ />
+ )
+}
+
+export { Skeleton }
diff --git a/packages/admin/src/components/ui/tooltip.tsx b/packages/admin/src/components/ui/tooltip.tsx
new file mode 100644
index 0000000000..bb1ea52342
--- /dev/null
+++ b/packages/admin/src/components/ui/tooltip.tsx
@@ -0,0 +1,57 @@
+"use client"
+
+import * as React from "react"
+import { Tooltip as TooltipPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function TooltipProvider({
+ delayDuration = 0,
+ ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+ return (
+ <TooltipPrimitive.Provider
+ data-slot="tooltip-provider"
+ delayDuration={delayDuration}
+ {...props}
+ />
+ )
+}
+
+function Tooltip({
+ ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+ return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+}
+
+function TooltipTrigger({
+ ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+ return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+ className,
+ sideOffset = 0,
+ children,
+ ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+ return (
+ <TooltipPrimitive.Portal>
+ <TooltipPrimitive.Content
+ data-slot="tooltip-content"
+ sideOffset={sideOffset}
+ className={cn(
+ "z-50 inline-flex w-fit max-w-xs origin-(--radix-tooltip-content-transform-origin) items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+ className
+ )}
+ {...props}
+ >
+ {children}
+ <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" />
+ </TooltipPrimitive.Content>
+ </TooltipPrimitive.Portal>
+ )
+}
+
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger }
diff --git a/packages/admin/src/hooks/use-auth.ts b/packages/admin/src/hooks/use-auth.ts
new file mode 100644
index 0000000000..7d322fca03
--- /dev/null
+++ b/packages/admin/src/hooks/use-auth.ts
@@ -0,0 +1,10 @@
+import { useContext } from 'react'
+import { AuthContext } from '@/providers/auth-provider'
+
+export function useAuth() {
+ const context = useContext(AuthContext)
+ if (!context) {
+ throw new Error('useAuth must be used within an AuthProvider')
+ }
+ return context
+}
diff --git a/packages/admin/src/hooks/use-mobile.ts b/packages/admin/src/hooks/use-mobile.ts
new file mode 100644
index 0000000000..2b0fe1dfef
--- /dev/null
+++ b/packages/admin/src/hooks/use-mobile.ts
@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+ const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+ React.useEffect(() => {
+ const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+ const onChange = () => {
+ setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+ }
+ mql.addEventListener("change", onChange)
+ setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+ return () => mql.removeEventListener("change", onChange)
+ }, [])
+
+ return !!isMobile
+}
diff --git a/packages/admin/src/index.css b/packages/admin/src/index.css
new file mode 100644
index 0000000000..58dded2ad5
--- /dev/null
+++ b/packages/admin/src/index.css
@@ -0,0 +1,129 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@fontsource-variable/geist";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+ --background: oklch(1 0 0);
+ --foreground: oklch(0.145 0 0);
+ --card: oklch(1 0 0);
+ --card-foreground: oklch(0.145 0 0);
+ --popover: oklch(1 0 0);
+ --popover-foreground: oklch(0.145 0 0);
+ --primary: oklch(0.205 0 0);
+ --primary-foreground: oklch(0.985 0 0);
+ --secondary: oklch(0.97 0 0);
+ --secondary-foreground: oklch(0.205 0 0);
+ --muted: oklch(0.97 0 0);
+ --muted-foreground: oklch(0.556 0 0);
+ --accent: oklch(0.97 0 0);
+ --accent-foreground: oklch(0.205 0 0);
+ --destructive: oklch(0.58 0.22 27);
+ --border: oklch(0.922 0 0);
+ --input: oklch(0.922 0 0);
+ --ring: oklch(0.708 0 0);
+ --chart-1: oklch(0.809 0.105 251.813);
+ --chart-2: oklch(0.623 0.214 259.815);
+ --chart-3: oklch(0.546 0.245 262.881);
+ --chart-4: oklch(0.488 0.243 264.376);
+ --chart-5: oklch(0.424 0.199 265.638);
+ --radius: 0.625rem;
+ --sidebar: oklch(0.985 0 0);
+ --sidebar-foreground: oklch(0.145 0 0);
+ --sidebar-primary: oklch(0.205 0 0);
+ --sidebar-primary-foreground: oklch(0.985 0 0);
+ --sidebar-accent: oklch(0.97 0 0);
+ --sidebar-accent-foreground: oklch(0.205 0 0);
+ --sidebar-border: oklch(0.922 0 0);
+ --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+ --background: oklch(0.145 0 0);
+ --foreground: oklch(0.985 0 0);
+ --card: oklch(0.205 0 0);
+ --card-foreground: oklch(0.985 0 0);
+ --popover: oklch(0.205 0 0);
+ --popover-foreground: oklch(0.985 0 0);
+ --primary: oklch(0.87 0.00 0);
+ --primary-foreground: oklch(0.205 0 0);
+ --secondary: oklch(0.269 0 0);
+ --secondary-foreground: oklch(0.985 0 0);
+ --muted: oklch(0.269 0 0);
+ --muted-foreground: oklch(0.708 0 0);
+ --accent: oklch(0.371 0 0);
+ --accent-foreground: oklch(0.985 0 0);
+ --destructive: oklch(0.704 0.191 22.216);
+ --border: oklch(1 0 0 / 10%);
+ --input: oklch(1 0 0 / 15%);
+ --ring: oklch(0.556 0 0);
+ --chart-1: oklch(0.809 0.105 251.813);
+ --chart-2: oklch(0.623 0.214 259.815);
+ --chart-3: oklch(0.546 0.245 262.881);
+ --chart-4: oklch(0.488 0.243 264.376);
+ --chart-5: oklch(0.424 0.199 265.638);
+ --sidebar: oklch(0.205 0 0);
+ --sidebar-foreground: oklch(0.985 0 0);
+ --sidebar-primary: oklch(0.488 0.243 264.376);
+ --sidebar-primary-foreground: oklch(0.985 0 0);
+ --sidebar-accent: oklch(0.269 0 0);
+ --sidebar-accent-foreground: oklch(0.985 0 0);
+ --sidebar-border: oklch(1 0 0 / 10%);
+ --sidebar-ring: oklch(0.556 0 0);
+}
+
+@theme inline {
+ --font-sans: 'Geist Variable', sans-serif;
+ --color-sidebar-ring: var(--sidebar-ring);
+ --color-sidebar-border: var(--sidebar-border);
+ --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+ --color-sidebar-accent: var(--sidebar-accent);
+ --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+ --color-sidebar-primary: var(--sidebar-primary);
+ --color-sidebar-foreground: var(--sidebar-foreground);
+ --color-sidebar: var(--sidebar);
+ --color-chart-5: var(--chart-5);
+ --color-chart-4: var(--chart-4);
+ --color-chart-3: var(--chart-3);
+ --color-chart-2: var(--chart-2);
+ --color-chart-1: var(--chart-1);
+ --color-ring: var(--ring);
+ --color-input: var(--input);
+ --color-border: var(--border);
+ --color-destructive: var(--destructive);
+ --color-accent-foreground: var(--accent-foreground);
+ --color-accent: var(--accent);
+ --color-muted-foreground: var(--muted-foreground);
+ --color-muted: var(--muted);
+ --color-secondary-foreground: var(--secondary-foreground);
+ --color-secondary: var(--secondary);
+ --color-primary-foreground: var(--primary-foreground);
+ --color-primary: var(--primary);
+ --color-popover-foreground: var(--popover-foreground);
+ --color-popover: var(--popover);
+ --color-card-foreground: var(--card-foreground);
+ --color-card: var(--card);
+ --color-foreground: var(--foreground);
+ --color-background: var(--background);
+ --radius-sm: calc(var(--radius) * 0.6);
+ --radius-md: calc(var(--radius) * 0.8);
+ --radius-lg: var(--radius);
+ --radius-xl: calc(var(--radius) * 1.4);
+ --radius-2xl: calc(var(--radius) * 1.8);
+ --radius-3xl: calc(var(--radius) * 2.2);
+ --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+@layer base {
+ * {
+ @apply border-border outline-ring/50;
+ }
+ body {
+ @apply bg-background text-foreground;
+ }
+ html {
+ @apply font-sans;
+ }
+}
diff --git a/packages/admin/src/lib/query-client.ts b/packages/admin/src/lib/query-client.ts
new file mode 100644
index 0000000000..25dea8b5d6
--- /dev/null
+++ b/packages/admin/src/lib/query-client.ts
@@ -0,0 +1,11 @@
+import { QueryClient } from '@tanstack/react-query'
+
+export const queryClient = new QueryClient({
+ defaultOptions: {
+ queries: {
+ staleTime: 1000 * 60,
+ retry: 1,
+ refetchOnWindowFocus: false,
+ },
+ },
+})
diff --git a/packages/admin/src/lib/utils.ts b/packages/admin/src/lib/utils.ts
new file mode 100644
index 0000000000..bd0c391ddd
--- /dev/null
+++ b/packages/admin/src/lib/utils.ts
@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+ return twMerge(clsx(inputs))
+}
diff --git a/packages/admin/src/main.tsx b/packages/admin/src/main.tsx
new file mode 100644
index 0000000000..e735b5ec41
--- /dev/null
+++ b/packages/admin/src/main.tsx
@@ -0,0 +1,27 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { QueryClientProvider } from '@tanstack/react-query'
+import { RouterProvider } from '@tanstack/react-router'
+import { TooltipProvider } from '@/components/ui/tooltip'
+import { AuthProvider } from '@/providers/auth-provider'
+import { useAuth } from '@/hooks/use-auth'
+import { queryClient } from '@/lib/query-client'
+import { router } from '@/router'
+import './index.css'
+
+function InnerApp() {
+ const auth = useAuth()
+ return <RouterProvider router={router} context={{ auth }} />
+}
+
+createRoot(document.getElementById('root')!).render(
+ <StrictMode>
+ <QueryClientProvider client={queryClient}>
+ <AuthProvider>
+ <TooltipProvider>
+ <InnerApp />
+ </TooltipProvider>
+ </AuthProvider>
+ </QueryClientProvider>
+ </StrictMode>,
+)
diff --git a/packages/admin/src/providers/auth-provider.tsx b/packages/admin/src/providers/auth-provider.tsx
new file mode 100644
index 0000000000..d8d102158b
--- /dev/null
+++ b/packages/admin/src/providers/auth-provider.tsx
@@ -0,0 +1,80 @@
+import { createContext, useCallback, useEffect, useState, type ReactNode } from 'react'
+import { spreeClient } from '@/client'
+
+interface AuthUser {
+ id: string
+ email: string
+ first_name: string | null
+ last_name: string | null
+}
+
+interface AuthContextValue {
+ user: AuthUser | null
+ token: string | null
+ isAuthenticated: boolean
+ isLoading: boolean
+ login: (email: string, password: string) => Promise<void>
+ logout: () => void
+}
+
+export const AuthContext = createContext<AuthContextValue | null>(null)
+
+const TOKEN_KEY = 'spree_admin_token'
+const USER_KEY = 'spree_admin_user'
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+ const [token, setToken] = useState<string | null>(() =>
+ localStorage.getItem(TOKEN_KEY),
+ )
+ const [user, setUser] = useState<AuthUser | null>(() => {
+ const stored = localStorage.getItem(USER_KEY)
+ return stored ? JSON.parse(stored) : null
+ })
+ const [isLoading, setIsLoading] = useState(false)
+
+ const login = useCallback(async (email: string, password: string) => {
+ setIsLoading(true)
+ try {
+ const response = await spreeClient.admin.auth.login({ email, password })
+ setToken(response.token)
+ setUser(response.user)
+ localStorage.setItem(TOKEN_KEY, response.token)
+ localStorage.setItem(USER_KEY, JSON.stringify(response.user))
+ } finally {
+ setIsLoading(false)
+ }
+ }, [])
+
+ const logout = useCallback(() => {
+ setToken(null)
+ setUser(null)
+ localStorage.removeItem(TOKEN_KEY)
+ localStorage.removeItem(USER_KEY)
+ }, [])
+
+ useEffect(() => {
+ if (!token) return
+
+ spreeClient.admin.auth.refresh({ token }).then((response) => {
+ setToken(response.token)
+ localStorage.setItem(TOKEN_KEY, response.token)
+ }).catch(() => {
+ logout()
+ })
+ }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+ return (
+ <AuthContext.Provider
+ value={{
+ user,
+ token,
+ isAuthenticated: !!token,
+ isLoading,
+ login,
+ logout,
+ }}
+ >
+ {children}
+ </AuthContext.Provider>
+ )
+}
diff --git a/packages/admin/src/routeTree.gen.ts b/packages/admin/src/routeTree.gen.ts
new file mode 100644
index 0000000000..f798462875
--- /dev/null
+++ b/packages/admin/src/routeTree.gen.ts
@@ -0,0 +1,146 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as LoginRouteImport } from './routes/login'
+import { Route as AuthenticatedRouteImport } from './routes/_authenticated'
+import { Route as AuthenticatedIndexRouteImport } from './routes/_authenticated/index'
+import { Route as AuthenticatedProductsIndexRouteImport } from './routes/_authenticated/products/index'
+import { Route as AuthenticatedOrdersIndexRouteImport } from './routes/_authenticated/orders/index'
+
+const LoginRoute = LoginRouteImport.update({
+ id: '/login',
+ path: '/login',
+ getParentRoute: () => rootRouteImport,
+} as any)
+const AuthenticatedRoute = AuthenticatedRouteImport.update({
+ id: '/_authenticated',
+ getParentRoute: () => rootRouteImport,
+} as any)
+const AuthenticatedIndexRoute = AuthenticatedIndexRouteImport.update({
+ id: '/',
+ path: '/',
+ getParentRoute: () => AuthenticatedRoute,
+} as any)
+const AuthenticatedProductsIndexRoute =
+ AuthenticatedProductsIndexRouteImport.update({
+ id: '/products/',
+ path: '/products/',
+ getParentRoute: () => AuthenticatedRoute,
+ } as any)
+const AuthenticatedOrdersIndexRoute =
+ AuthenticatedOrdersIndexRouteImport.update({
+ id: '/orders/',
+ path: '/orders/',
+ getParentRoute: () => AuthenticatedRoute,
+ } as any)
+
+export interface FileRoutesByFullPath {
+ '/': typeof AuthenticatedIndexRoute
+ '/login': typeof LoginRoute
+ '/orders/': typeof AuthenticatedOrdersIndexRoute
+ '/products/': typeof AuthenticatedProductsIndexRoute
+}
+export interface FileRoutesByTo {
+ '/login': typeof LoginRoute
+ '/': typeof AuthenticatedIndexRoute
+ '/orders': typeof AuthenticatedOrdersIndexRoute
+ '/products': typeof AuthenticatedProductsIndexRoute
+}
+export interface FileRoutesById {
+ __root__: typeof rootRouteImport
+ '/_authenticated': typeof AuthenticatedRouteWithChildren
+ '/login': typeof LoginRoute
+ '/_authenticated/': typeof AuthenticatedIndexRoute
+ '/_authenticated/orders/': typeof AuthenticatedOrdersIndexRoute
+ '/_authenticated/products/': typeof AuthenticatedProductsIndexRoute
+}
+export interface FileRouteTypes {
+ fileRoutesByFullPath: FileRoutesByFullPath
+ fullPaths: '/' | '/login' | '/orders/' | '/products/'
+ fileRoutesByTo: FileRoutesByTo
+ to: '/login' | '/' | '/orders' | '/products'
+ id:
+ | '__root__'
+ | '/_authenticated'
+ | '/login'
+ | '/_authenticated/'
+ | '/_authenticated/orders/'
+ | '/_authenticated/products/'
+ fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+ AuthenticatedRoute: typeof AuthenticatedRouteWithChildren
+ LoginRoute: typeof LoginRoute
+}
+
+declare module '@tanstack/react-router' {
+ interface FileRoutesByPath {
+ '/login': {
+ id: '/login'
+ path: '/login'
+ fullPath: '/login'
+ preLoaderRoute: typeof LoginRouteImport
+ parentRoute: typeof rootRouteImport
+ }
+ '/_authenticated': {
+ id: '/_authenticated'
+ path: ''
+ fullPath: '/'
+ preLoaderRoute: typeof AuthenticatedRouteImport
+ parentRoute: typeof rootRouteImport
+ }
+ '/_authenticated/': {
+ id: '/_authenticated/'
+ path: '/'
+ fullPath: '/'
+ preLoaderRoute: typeof AuthenticatedIndexRouteImport
+ parentRoute: typeof AuthenticatedRoute
+ }
+ '/_authenticated/products/': {
+ id: '/_authenticated/products/'
+ path: '/products'
+ fullPath: '/products/'
+ preLoaderRoute: typeof AuthenticatedProductsIndexRouteImport
+ parentRoute: typeof AuthenticatedRoute
+ }
+ '/_authenticated/orders/': {
+ id: '/_authenticated/orders/'
+ path: '/orders'
+ fullPath: '/orders/'
+ preLoaderRoute: typeof AuthenticatedOrdersIndexRouteImport
+ parentRoute: typeof AuthenticatedRoute
+ }
+ }
+}
+
+interface AuthenticatedRouteChildren {
+ AuthenticatedIndexRoute: typeof AuthenticatedIndexRoute
+ AuthenticatedOrdersIndexRoute: typeof AuthenticatedOrdersIndexRoute
+ AuthenticatedProductsIndexRoute: typeof AuthenticatedProductsIndexRoute
+}
+
+const AuthenticatedRouteChildren: AuthenticatedRouteChildren = {
+ AuthenticatedIndexRoute: AuthenticatedIndexRoute,
+ AuthenticatedOrdersIndexRoute: AuthenticatedOrdersIndexRoute,
+ AuthenticatedProductsIndexRoute: AuthenticatedProductsIndexRoute,
+}
+
+const AuthenticatedRouteWithChildren = AuthenticatedRoute._addFileChildren(
+ AuthenticatedRouteChildren,
+)
+
+const rootRouteChildren: RootRouteChildren = {
+ AuthenticatedRoute: AuthenticatedRouteWithChildren,
+ LoginRoute: LoginRoute,
+}
+export const routeTree = rootRouteImport
+ ._addFileChildren(rootRouteChildren)
+ ._addFileTypes<FileRouteTypes>()
diff --git a/packages/admin/src/router.tsx b/packages/admin/src/router.tsx
new file mode 100644
index 0000000000..28ee8449af
--- /dev/null
+++ b/packages/admin/src/router.tsx
@@ -0,0 +1,15 @@
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export const router = createRouter({
+ routeTree,
+ context: {
+ auth: undefined!,
+ },
+})
+
+declare module '@tanstack/react-router' {
+ interface Register {
+ router: typeof router
+ }
+}
diff --git a/packages/admin/src/routes/__root.tsx b/packages/admin/src/routes/__root.tsx
new file mode 100644
index 0000000000..e0c513ea9a
--- /dev/null
+++ b/packages/admin/src/routes/__root.tsx
@@ -0,0 +1,16 @@
+import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
+
+interface RouterContext {
+ auth: {
+ isAuthenticated: boolean
+ token: string | null
+ }
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+ component: RootLayout,
+})
+
+function RootLayout() {
+ return <Outlet />
+}
diff --git a/packages/admin/src/routes/_authenticated.tsx b/packages/admin/src/routes/_authenticated.tsx
new file mode 100644
index 0000000000..6af8e4ce73
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated.tsx
@@ -0,0 +1,49 @@
+import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
+import { AppSidebar } from '@/components/app-sidebar'
+import {
+ SidebarInset,
+ SidebarProvider,
+ SidebarTrigger,
+} from '@/components/ui/sidebar'
+import { Separator } from '@/components/ui/separator'
+import {
+ Breadcrumb,
+ BreadcrumbItem,
+ BreadcrumbList,
+ BreadcrumbPage,
+} from '@/components/ui/breadcrumb'
+
+export const Route = createFileRoute('/_authenticated')({
+ beforeLoad: ({ context }) => {
+ if (!context.auth.isAuthenticated) {
+ throw redirect({ to: '/login' })
+ }
+ },
+ component: AuthenticatedLayout,
+})
+
+function AuthenticatedLayout() {
+ return (
+ <SidebarProvider>
+ <AppSidebar />
+ <SidebarInset>
+ <header className="flex h-16 shrink-0 items-center gap-2 transition-[width,height] ease-linear group-has-data-[collapsible=icon]/sidebar-wrapper:h-12">
+ <div className="flex items-center gap-2 px-4">
+ <SidebarTrigger className="-ml-1" />
+ <Separator orientation="vertical" className="mr-2 h-4" />
+ <Breadcrumb>
+ <BreadcrumbList>
+ <BreadcrumbItem>
+ <BreadcrumbPage>Dashboard</BreadcrumbPage>
+ </BreadcrumbItem>
+ </BreadcrumbList>
+ </Breadcrumb>
+ </div>
+ </header>
+ <div className="flex flex-1 flex-col gap-4 p-4 pt-0">
+ <Outlet />
+ </div>
+ </SidebarInset>
+ </SidebarProvider>
+ )
+}
diff --git a/packages/admin/src/routes/_authenticated/index.tsx b/packages/admin/src/routes/_authenticated/index.tsx
new file mode 100644
index 0000000000..f799bff514
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated/index.tsx
@@ -0,0 +1,16 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/')({
+ component: DashboardPage,
+})
+
+function DashboardPage() {
+ return (
+ <div className="space-y-4">
+ <h1 className="text-2xl font-bold">Dashboard</h1>
+ <p className="text-muted-foreground">
+ Welcome to the Spree Admin dashboard.
+ </p>
+ </div>
+ )
+}
diff --git a/packages/admin/src/routes/_authenticated/orders/index.tsx b/packages/admin/src/routes/_authenticated/orders/index.tsx
new file mode 100644
index 0000000000..bff147ce12
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated/orders/index.tsx
@@ -0,0 +1,18 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/orders/')({
+ component: OrdersPage,
+})
+
+function OrdersPage() {
+ return (
+ <div className="space-y-4">
+ <div className="flex items-center justify-between">
+ <h1 className="text-2xl font-bold">Orders</h1>
+ </div>
+ <p className="text-muted-foreground">
+ Order listing will be implemented here.
+ </p>
+ </div>
+ )
+}
diff --git a/packages/admin/src/routes/_authenticated/products/index.tsx b/packages/admin/src/routes/_authenticated/products/index.tsx
new file mode 100644
index 0000000000..c69d2ef67f
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated/products/index.tsx
@@ -0,0 +1,18 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/products/')({
+ component: ProductsPage,
+})
+
+function ProductsPage() {
+ return (
+ <div className="space-y-4">
+ <div className="flex items-center justify-between">
+ <h1 className="text-2xl font-bold">Products</h1>
+ </div>
+ <p className="text-muted-foreground">
+ Product listing will be implemented here.
+ </p>
+ </div>
+ )
+}
diff --git a/packages/admin/src/routes/login.tsx b/packages/admin/src/routes/login.tsx
new file mode 100644
index 0000000000..177cdee80f
--- /dev/null
+++ b/packages/admin/src/routes/login.tsx
@@ -0,0 +1,155 @@
+import { createFileRoute, redirect, useRouter } from '@tanstack/react-router'
+import { useAuth } from '@/hooks/use-auth'
+import { useForm } from 'react-hook-form'
+import { z } from 'zod/v4'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+
+const loginSchema = z.object({
+ email: z.email(),
+ password: z.string().min(1, 'Password is required'),
+})
+
+type LoginForm = z.infer<typeof loginSchema>
+
+export const Route = createFileRoute('/login')({
+ beforeLoad: ({ context }) => {
+ if (context.auth.isAuthenticated) {
+ throw redirect({ to: '/' })
+ }
+ },
+ component: LoginPage,
+})
+
+function LoginPage() {
+ const { login, isLoading } = useAuth()
+ const router = useRouter()
+
+ const form = useForm<LoginForm>({
+ resolver: zodResolver(loginSchema),
+ defaultValues: { email: '', password: '' },
+ })
+
+ const onSubmit = async (data: LoginForm) => {
+ try {
+ await login(data.email, data.password)
+ await router.invalidate()
+ await router.navigate({ to: '/' })
+ } catch {
+ form.setError('root', { message: 'Invalid email or password' })
+ }
+ }
+
+ return (
+ <div className="flex min-h-svh flex-col items-center justify-center gap-6 bg-muted p-6 md:p-10">
+ <div className="flex w-full max-w-sm flex-col gap-6">
+ <a href="/" className="flex items-center gap-2 self-center font-medium">
+ <div className="flex h-6 w-6 items-center justify-center rounded-md bg-primary text-primary-foreground">
+ <GalleryVerticalEnd className="size-4" />
+ </div>
+ Spree Admin
+ </a>
+ <LoginFormCard form={form} onSubmit={onSubmit} isLoading={isLoading} />
+ </div>
+ </div>
+ )
+}
+
+function LoginFormCard({
+ form,
+ onSubmit,
+ isLoading,
+ className,
+ ...props
+}: {
+ form: ReturnType<typeof useForm<LoginForm>>
+ onSubmit: (data: LoginForm) => Promise<void>
+ isLoading: boolean
+} & React.ComponentProps<'div'>) {
+ return (
+ <div className={cn('flex flex-col gap-6', className)} {...props}>
+ <Card>
+ <CardHeader className="text-center">
+ <CardTitle className="text-xl">Welcome back</CardTitle>
+ <CardDescription>
+ Sign in to your admin account
+ </CardDescription>
+ </CardHeader>
+ <CardContent>
+ <form onSubmit={form.handleSubmit(onSubmit)}>
+ <div className="grid gap-6">
+ {form.formState.errors.root && (
+ <p className="text-sm text-destructive text-center">
+ {form.formState.errors.root.message}
+ </p>
+ )}
+ <div className="grid gap-6">
+ <div className="grid gap-2">
+ <Label htmlFor="email">Email</Label>
+ <Input
+ id="email"
+ type="email"
+ placeholder="[email protected]"
+ {...form.register('email')}
+ />
+ {form.formState.errors.email && (
+ <p className="text-sm text-destructive">
+ {form.formState.errors.email.message}
+ </p>
+ )}
+ </div>
+ <div className="grid gap-2">
+ <Label htmlFor="password">Password</Label>
+ <Input
+ id="password"
+ type="password"
+ {...form.register('password')}
+ />
+ {form.formState.errors.password && (
+ <p className="text-sm text-destructive">
+ {form.formState.errors.password.message}
+ </p>
+ )}
+ </div>
+ <Button type="submit" className="w-full" disabled={isLoading}>
+ {isLoading ? 'Signing in...' : 'Login'}
+ </Button>
+ </div>
+ </div>
+ </form>
+ </CardContent>
+ </Card>
+ <div className="text-balance text-center text-xs text-muted-foreground">
+ Powered by{' '}
+ <a href="https://spreecommerce.org" className="underline underline-offset-4 hover:text-primary" target="_blank" rel="noreferrer">
+ Spree Commerce
+ </a>
+ </div>
+ </div>
+ )
+}
+
+function GalleryVerticalEnd(props: React.SVGProps<SVGSVGElement>) {
+ return (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ width="24"
+ height="24"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ {...props}
+ >
+ <path d="M7 2h10" />
+ <path d="M5 6h14" />
+ <rect width="18" height="12" x="3" y="10" rx="2" />
+ </svg>
+ )
+}
diff --git a/packages/admin/tsconfig.app.json b/packages/admin/tsconfig.app.json
new file mode 100644
index 0000000000..a132313037
--- /dev/null
+++ b/packages/admin/tsconfig.app.json
@@ -0,0 +1,32 @@
+{
+ "compilerOptions": {
+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+ "target": "ES2022",
+ "useDefineForClassFields": true,
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "module": "ESNext",
+ "types": ["vite/client"],
+ "skipLibCheck": true,
+
+ /* Bundler mode */
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "verbatimModuleSyntax": true,
+ "moduleDetection": "force",
+ "noEmit": true,
+ "jsx": "react-jsx",
+
+ /* Linting */
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "erasableSyntaxOnly": true,
+ "noFallthroughCasesInSwitch": true,
+ "noUncheckedSideEffectImports": true,
+ "baseUrl": ".",
+ "paths": {
+ "@/*": ["./src/*"]
+ }
+ },
+ "include": ["src"]
+}
diff --git a/packages/admin/tsconfig.json b/packages/admin/tsconfig.json
new file mode 100644
index 0000000000..59578c322c
--- /dev/null
+++ b/packages/admin/tsconfig.json
@@ -0,0 +1,13 @@
+{
+ "files": [],
+ "references": [
+ { "path": "./tsconfig.app.json" },
+ { "path": "./tsconfig.node.json" },
+ ],
+ "compilerOptions": {
+ "baseUrl": ".",
+ "paths": {
+ "@/*": ["./src/*"],
+ },
+ },
+}
diff --git a/packages/admin/tsconfig.node.json b/packages/admin/tsconfig.node.json
new file mode 100644
index 0000000000..8a67f62f4c
--- /dev/null
+++ b/packages/admin/tsconfig.node.json
@@ -0,0 +1,26 @@
+{
+ "compilerOptions": {
+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+ "target": "ES2023",
+ "lib": ["ES2023"],
+ "module": "ESNext",
+ "types": ["node"],
+ "skipLibCheck": true,
+
+ /* Bundler mode */
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "verbatimModuleSyntax": true,
+ "moduleDetection": "force",
+ "noEmit": true,
+
+ /* Linting */
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "erasableSyntaxOnly": true,
+ "noFallthroughCasesInSwitch": true,
+ "noUncheckedSideEffectImports": true
+ },
+ "include": ["vite.config.ts"]
+}
diff --git a/packages/admin/vite.config.ts b/packages/admin/vite.config.ts
new file mode 100644
index 0000000000..7dad18947b
--- /dev/null
+++ b/packages/admin/vite.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+import path from 'path'
+
+export default defineConfig({
+ plugins: [TanStackRouterVite(), react(), tailwindcss()],
+ resolve: {
+ alias: {
+ '@': path.resolve(__dirname, './src'),
+ },
+ },
+})
diff --git a/packages/sdk/ADMIN_SDK.md b/packages/sdk/ADMIN_SDK.md
new file mode 100644
index 0000000000..dba6d52cac
--- /dev/null
+++ b/packages/sdk/ADMIN_SDK.md
@@ -0,0 +1,1044 @@
+# Spree Admin SDK
+
+The Admin SDK provides TypeScript methods for the Spree Admin API (`/api/v3/admin`). It is accessed via the `admin` property on a `SpreeClient` instance.
+
+## Setup
+
+```ts
+import { createSpreeClient } from '@spree/sdk'
+
+const client = createSpreeClient({
+ baseUrl: 'https://mystore.com',
+ secretKey: 'spree_sk_...',
+})
+```
+
+The `secretKey` is a secret API key created in the Spree admin. It is sent as `x-spree-api-key` on every request.
+
+## Common Patterns
+
+### Pagination
+
+All `list` methods return a `PaginatedResponse<T>`:
+
+```ts
+interface PaginatedResponse<T> {
+ data: T[]
+ meta: {
+ page: number
+ limit: number
+ count: number
+ pages: number
+ from: number
+ to: number
+ in: number
+ previous: number | null
+ next: number | null
+ }
+}
+```
+
+```ts
+const { data, meta } = await client.admin.products.list({ page: 2, limit: 25 })
+```
+
+### Sorting
+
+Pass a `sort` string. Prefix with `-` for descending:
+
+```ts
+await client.admin.orders.list({ sort: '-created_at' })
+```
+
+### Filtering (Ransack)
+
+Filter keys are automatically wrapped in `q[...]`:
+
+```ts
+await client.admin.orders.list({ state_eq: 'complete', completed_at_gte: '2024-01-01' })
+// Sends: q[state_eq]=complete&q[completed_at_gte]=2024-01-01
+```
+
+### Expanding Associations
+
+Pass `expand` as a string array. Supports dot notation for nested expand (max 4 levels):
+
+```ts
+await client.admin.products.get('prod_abc', { expand: ['variants', 'variants.images'] })
+```
+
+### Authenticated Requests
+
+Admin user operations require a Bearer token (from `admin.auth.login`) passed via `RequestOptions`:
+
+```ts
+const { token } = await client.admin.auth.login({
+ email: '[email protected]',
+ password: 'password',
+})
+
+await client.admin.orders.list({}, { token })
+```
+
+### Idempotency
+
+Mutating requests accept an `idempotencyKey` for safe retries:
+
+```ts
+await client.admin.orders.create(params, { token, idempotencyKey: 'unique-key-123' })
+```
+
+### Prefixed IDs
+
+All IDs in the Admin API use Stripe-style prefixed IDs (e.g., `prod_86Rf07xd4z`, `or_m3Rp9wXz`). Use these prefixed IDs in all method parameters.
+
+---
+
+## Authentication
+
+### `admin.auth.login(credentials)`
+
+Login with email and password. Returns a JWT token for subsequent requests.
+
+```ts
+const { token, user } = await client.admin.auth.login({
+ email: '[email protected]',
+ password: 'password',
+ provider: 'spree', // optional
+})
+```
+
+**Response:** `AdminAuthTokens`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `token` | `string` | JWT Bearer token |
+| `user.id` | `string` | Admin user prefixed ID |
+| `user.email` | `string` | Admin email |
+| `user.first_name` | `string \| null` | |
+| `user.last_name` | `string \| null` | |
+| `user.created_at` | `string` | |
+| `user.updated_at` | `string` | |
+
+### `admin.auth.refresh(options)`
+
+Refresh an access token. Requires a valid Bearer token.
+
+```ts
+const newTokens = await client.admin.auth.refresh({ token: currentToken })
+```
+
+---
+
+## Products
+
+### `admin.products.list(params?, options?)`
+
+List products with pagination, sorting, and filtering.
+
+```ts
+const products = await client.admin.products.list({
+ page: 1,
+ limit: 25,
+ sort: '-created_at',
+ expand: ['variants'],
+}, { token })
+```
+
+### `admin.products.get(id, params?, options?)`
+
+Get a single product.
+
+```ts
+const product = await client.admin.products.get('prod_abc', {
+ expand: ['variants', 'variants.images', 'taxons', 'option_types'],
+}, { token })
+```
+
+### `admin.products.create(params, options?)`
+
+Create a product.
+
+```ts
+const product = await client.admin.products.create({
+ name: 'T-Shirt',
+ price: 29.99,
+ shipping_category_id: 'sc_abc',
+ description: 'A comfortable t-shirt',
+ status: 'draft',
+ sku: 'TSHIRT-001',
+ tax_category_id: 'tc_xyz',
+ taxon_ids: ['taxon_abc', 'taxon_def'],
+ tags: ['new', 'summer'],
+ variants: [
+ {
+ sku: 'TSHIRT-S',
+ price: 29.99,
+ options: [
+ { name: 'size', value: 'Small' },
+ { name: 'color', value: 'Red' },
+ ],
+ prices: [
+ { currency: 'USD', amount: 29.99 },
+ { currency: 'EUR', amount: 27.99 },
+ ],
+ stock_items: [
+ { location_id: 'loc_abc', quantity: 10, backorderable: true },
+ ],
+ },
+ ],
+}, { token })
+```
+
+**Params:** `AdminProductCreateParams`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | yes | |
+| `price` | `number` | yes | Default price (master variant) |
+| `shipping_category_id` | `string` | yes | Prefixed ID |
+| `description` | `string` | no | |
+| `slug` | `string` | no | Auto-generated from name if omitted |
+| `status` | `'draft' \| 'active' \| 'archived'` | no | Defaults to `draft` |
+| `sku` | `string` | no | Master variant SKU |
+| `tax_category_id` | `string` | no | Prefixed ID |
+| `taxon_ids` | `string[]` | no | Prefixed IDs |
+| `tags` | `string[]` | no | |
+| `variants` | `array` | no | Inline variant creation (see below) |
+
+**Inline variant params:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sku` | `string` | |
+| `price` | `number` | |
+| `option_type` | `string` | Auto-created if needed |
+| `option_value` | `string` | Auto-created if needed |
+| `total_on_hand` | `number` | |
+| `prices` | `array` | `{ currency, amount, compare_at_amount? }` |
+
+### `admin.products.update(id, params, options?)`
+
+Update a product.
+
+```ts
+await client.admin.products.update('prod_abc', {
+ name: 'Updated T-Shirt',
+ status: 'active',
+ tags: ['sale'],
+}, { token })
+```
+
+**Params:** `AdminProductUpdateParams` — same fields as create, all optional.
+
+### `admin.products.delete(id, options?)`
+
+Soft-delete a product.
+
+```ts
+await client.admin.products.delete('prod_abc', { token })
+```
+
+**Response:** `void` (204 No Content)
+
+### Response Type: `AdminProduct`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Prefixed ID (e.g., `prod_abc`) |
+| `name` | `string` | |
+| `description` | `string \| null` | |
+| `slug` | `string` | |
+| `status` | `string` | `draft`, `active`, or `archived` |
+| `variant_count` | `number` | Number of non-master variants |
+| `available_on` | `string \| null` | ISO 8601 timestamp |
+| `make_active_at` | `string \| null` | |
+| `discontinue_on` | `string \| null` | |
+| `purchasable` | `boolean` | |
+| `in_stock` | `boolean` | |
+| `backorderable` | `boolean` | |
+| `available` | `boolean` | |
+| `promotionable` | `boolean` | |
+| `default_variant_id` | `string` | Prefixed ID |
+| `thumbnail_url` | `string \| null` | |
+| `tags` | `string[]` | |
+| `price` | `AdminPrice` | Default variant price |
+| `original_price` | `AdminPrice \| null` | Compare-at price |
+| `shipping_category_id` | `string \| null` | |
+| `tax_category_id` | `string \| null` | |
+| `cost_price` | `string \| null` | |
+| `cost_currency` | `string \| null` | |
+| `meta_title` | `string \| null` | |
+| `meta_description` | `string \| null` | |
+| `meta_keywords` | `string \| null` | |
+| `deleted_at` | `string \| null` | |
+| `created_at` | `string` | |
+| `updated_at` | `string` | |
+| `variants?` | `AdminVariant[]` | Requires `expand: ['variants']` |
+| `default_variant?` | `AdminVariant` | Requires expand |
+| `master_variant?` | `AdminVariant` | Requires expand |
+| `images?` | `AdminImage[]` | Requires expand |
+| `option_types?` | `AdminOptionType[]` | Requires expand |
+| `taxons?` | `AdminTaxon[]` | Requires expand |
+| `metafields?` | `AdminMetafield[]` | Requires expand |
+| `shipping_category?` | `AdminShippingCategory` | Requires expand |
+| `tax_category?` | `AdminTaxCategory` | Requires expand |
+
+---
+
+## Product Variants
+
+Nested under `admin.products.variants`.
+
+### `admin.products.variants.list(productId, params?, options?)`
+
+```ts
+const variants = await client.admin.products.variants.list('prod_abc', {
+ expand: ['images', 'prices', 'stock_items'],
+}, { token })
+```
+
+### `admin.products.variants.get(productId, id, params?, options?)`
+
+```ts
+const variant = await client.admin.products.variants.get(
+ 'prod_abc',
+ 'variant_xyz',
+ { expand: ['prices', 'stock_items'] },
+ { token },
+)
+```
+
+### `admin.products.variants.create(productId, params, options?)`
+
+```ts
+const variant = await client.admin.products.variants.create('prod_abc', {
+ sku: 'TSHIRT-L',
+ price: 29.99,
+ options: [{ name: 'Size', value: 'Large' }],
+ track_inventory: true,
+ prices: [
+ { currency: 'USD', amount: 29.99, compare_at_amount: 39.99 },
+ { currency: 'EUR', amount: 27.99 },
+ ],
+ stock_items: [
+ { stock_location_id: 'sl_abc', count_on_hand: 50, backorderable: false },
+ ],
+}, { token })
+```
+
+**Params:** `AdminVariantCreateParams`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sku` | `string` | |
+| `price` | `number` | Default currency price |
+| `compare_at_price` | `number` | |
+| `cost_price` | `number` | |
+| `cost_currency` | `string` | |
+| `weight` | `number` | |
+| `height` | `number` | |
+| `width` | `number` | |
+| `depth` | `number` | |
+| `weight_unit` | `string` | `g`, `kg`, `lb`, `oz` |
+| `dimensions_unit` | `string` | `mm`, `cm`, `in`, `ft` |
+| `track_inventory` | `boolean` | |
+| `tax_category_id` | `string` | Prefixed ID |
+| `position` | `number` | |
+| `barcode` | `string` | |
+| `prices` | `array` | Multi-currency prices (upserted by currency) |
+| `stock_items` | `array` | Multi-location stock (upserted by location) |
+
+**Nested prices:**
+
+| Field | Type | Required |
+|-------|------|----------|
+| `currency` | `string` | yes |
+| `amount` | `number` | yes |
+| `compare_at_amount` | `number` | no |
+
+**Nested stock_items:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `stock_location_id` | `string` | Prefixed ID |
+| `count_on_hand` | `number` | |
+| `backorderable` | `boolean` | |
+
+### `admin.products.variants.update(productId, id, params, options?)`
+
+```ts
+await client.admin.products.variants.update('prod_abc', 'variant_xyz', {
+ sku: 'TSHIRT-L-UPDATED',
+ prices: [{ currency: 'USD', amount: 34.99 }],
+}, { token })
+```
+
+**Params:** `AdminVariantUpdateParams` — same fields as create, all optional.
+
+### `admin.products.variants.delete(productId, id, options?)`
+
+Soft-delete a variant.
+
+```ts
+await client.admin.products.variants.delete('prod_abc', 'variant_xyz', { token })
+```
+
+### Response Type: `AdminVariant`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Prefixed ID |
+| `product_id` | `string` | |
+| `sku` | `string \| null` | |
+| `is_master` | `boolean` | |
+| `options_text` | `string` | e.g., `"Size: Large, Color: Red"` |
+| `track_inventory` | `boolean` | |
+| `position` | `number` | |
+| `purchasable` | `boolean` | |
+| `in_stock` | `boolean` | |
+| `backorderable` | `boolean` | |
+| `weight` | `number \| null` | |
+| `height` | `number \| null` | |
+| `width` | `number \| null` | |
+| `depth` | `number \| null` | |
+| `weight_unit` | `string \| null` | |
+| `dimensions_unit` | `string \| null` | |
+| `barcode` | `string \| null` | |
+| `cost_price` | `string \| null` | |
+| `cost_currency` | `string \| null` | |
+| `tax_category_id` | `string \| null` | |
+| `total_on_hand` | `number \| null` | |
+| `thumbnail` | `string \| null` | Image URL |
+| `image_count` | `number` | |
+| `price` | `AdminPrice` | Default currency price |
+| `original_price` | `AdminPrice \| null` | Compare-at price |
+| `option_values` | `AdminOptionValue[]` | Always included |
+| `deleted_at` | `string \| null` | |
+| `discontinue_on` | `string \| null` | |
+| `created_at` | `string` | |
+| `updated_at` | `string` | |
+| `images?` | `AdminImage[]` | Requires expand |
+| `prices?` | `AdminPrice[]` | Requires expand |
+| `stock_items?` | `AdminStockItem[]` | Requires expand |
+| `product?` | `AdminProduct` | Requires expand |
+| `metafields?` | `AdminMetafield[]` | Requires expand |
+| `tax_category?` | `AdminTaxCategory` | Requires expand |
+
+---
+
+## Product Assets
+
+Nested under `admin.products.assets`. Manages images and other media for the product's master variant.
+
+### `admin.products.assets.list(productId, params?, options?)`
+
+### `admin.products.assets.create(productId, params, options?)`
+
+```ts
+await client.admin.products.assets.create('prod_abc', {
+ url: 'https://example.com/image.jpg',
+ alt: 'Product front view',
+ position: 1,
+ type: 'Spree::Image',
+}, { token })
+```
+
+**Params:** `AdminAssetCreateParams`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `url` | `string` | URL of the image |
+| `alt` | `string` | Alt text |
+| `position` | `number` | Sort order |
+| `type` | `string` | Asset type (e.g., `Spree::Image`) |
+
+### `admin.products.assets.update(productId, id, params, options?)`
+
+### `admin.products.assets.delete(productId, id, options?)`
+
+---
+
+## Variant Assets
+
+Nested under `admin.products.variants.assets`. Same interface as product assets, scoped to a specific variant.
+
+### `admin.products.variants.assets.list(productId, variantId, params?, options?)`
+
+### `admin.products.variants.assets.create(productId, variantId, params, options?)`
+
+### `admin.products.variants.assets.update(productId, variantId, id, params, options?)`
+
+### `admin.products.variants.assets.delete(productId, variantId, id, options?)`
+
+---
+
+## Option Types
+
+### `admin.optionTypes.list(params?, options?)`
+
+```ts
+const optionTypes = await client.admin.optionTypes.list({}, { token })
+```
+
+### `admin.optionTypes.get(id, params?, options?)`
+
+```ts
+const optionType = await client.admin.optionTypes.get('ot_abc', {
+ expand: ['metafields'],
+}, { token })
+```
+
+### `admin.optionTypes.create(params, options?)`
+
+```ts
+const optionType = await client.admin.optionTypes.create({
+ name: 'size',
+ presentation: 'Size',
+ position: 1,
+ filterable: true,
+ option_values: [
+ { name: 'small', presentation: 'S', position: 1 },
+ { name: 'medium', presentation: 'M', position: 2 },
+ { name: 'large', presentation: 'L', position: 3 },
+ ],
+}, { token })
+```
+
+**Params:** `AdminOptionTypeCreateParams`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | yes | Internal name |
+| `presentation` | `string` | yes | Display name |
+| `position` | `number` | no | Sort order |
+| `filterable` | `boolean` | no | Show in storefront filters |
+| `option_values` | `array` | no | Inline value creation |
+
+### `admin.optionTypes.update(id, params, options?)`
+
+```ts
+await client.admin.optionTypes.update('ot_abc', {
+ presentation: 'Clothing Size',
+ option_values: [
+ { id: 'ov_abc', presentation: 'Small' }, // update existing
+ { name: 'xl', presentation: 'XL', position: 4 }, // create new
+ ],
+}, { token })
+```
+
+### `admin.optionTypes.delete(id, options?)`
+
+### Response Type: `AdminOptionType`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Prefixed ID |
+| `name` | `string` | |
+| `presentation` | `string` | |
+| `position` | `number` | |
+| `filterable` | `boolean` | |
+| `created_at` | `string` | |
+| `updated_at` | `string` | |
+| `option_values` | `AdminOptionValue[]` | Always included |
+| `metafields?` | `AdminMetafield[]` | Requires expand |
+
+---
+
+## Orders
+
+### `admin.orders.list(params?, options?)`
+
+```ts
+const orders = await client.admin.orders.list({
+ sort: '-completed_at',
+ state_eq: 'complete',
+ completed_at_gte: '2024-01-01',
+ expand: ['line_items'],
+}, { token })
+```
+
+### `admin.orders.get(id, params?, options?)`
+
+```ts
+const order = await client.admin.orders.get('or_abc', {
+ expand: ['adjustments', 'return_authorizations', 'reimbursements'],
+}, { token })
+```
+
+### `admin.orders.create(params, options?)`
+
+Create a draft order.
+
+```ts
+const order = await client.admin.orders.create({
+ email: '[email protected]',
+ user_id: 'user_abc',
+ currency: 'USD',
+ channel: 'admin',
+ internal_note: 'Phone order',
+}, { token })
+```
+
+**Params:** `AdminOrderCreateParams`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `email` | `string` | Customer email |
+| `user_id` | `string` | Prefixed ID, link to existing user |
+| `currency` | `string` | Order currency |
+| `channel` | `string` | Sales channel |
+| `internal_note` | `string` | Internal staff note |
+
+### `admin.orders.update(id, params, options?)`
+
+```ts
+await client.admin.orders.update('or_abc', {
+ email: '[email protected]',
+ internal_note: 'Updated by admin',
+ ship_address: {
+ firstname: 'John',
+ lastname: 'Doe',
+ address1: '123 Main St',
+ city: 'New York',
+ zipcode: '10001',
+ country_iso: 'US',
+ state_abbr: 'NY',
+ phone: '555-1234',
+ },
+ line_items: [
+ { variant_id: 'variant_abc', quantity: 2 },
+ ],
+}, { token })
+```
+
+**Params:** `AdminOrderUpdateParams`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `email` | `string` | |
+| `special_instructions` | `string` | Customer note |
+| `internal_note` | `string` | Staff note |
+| `channel` | `string` | |
+| `ship_address` | `object` | Shipping address |
+| `bill_address` | `object` | Billing address |
+| `line_items` | `array` | `{ variant_id, quantity }` |
+
+### `admin.orders.delete(id, options?)`
+
+Delete a draft order (only works on incomplete orders).
+
+### `admin.orders.cancel(id, params?, options?)`
+
+Cancel a completed order.
+
+```ts
+await client.admin.orders.cancel('or_abc', {}, { token })
+```
+
+### `admin.orders.approve(id, params?, options?)`
+
+Approve an order.
+
+### `admin.orders.resume(id, params?, options?)`
+
+Resume a canceled order.
+
+### `admin.orders.resendConfirmation(id, params?, options?)`
+
+Resend the order confirmation email.
+
+### Response Type: `AdminOrder`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Prefixed ID |
+| `number` | `string` | Order number (e.g., `R123456`) |
+| `state` | `string` | `cart`, `address`, `delivery`, `payment`, `confirm`, `complete` |
+| `email` | `string \| null` | |
+| `currency` | `string` | |
+| `item_count` | `number` | |
+| `item_total` | `string` | |
+| `ship_total` | `string` | |
+| `tax_total` | `string` | |
+| `total` | `string` | |
+| `payment_total` | `string` | |
+| `payment_state` | `string \| null` | `balance_due`, `paid`, `credit_owed`, etc. |
+| `shipment_state` | `string \| null` | `pending`, `ready`, `shipped`, `partial` |
+| `channel` | `string \| null` | |
+| `internal_note` | `string \| null` | |
+| `completed_at` | `string \| null` | |
+| `canceled_at` | `string \| null` | |
+| `approved_at` | `string \| null` | |
+| `created_at` | `string` | |
+| `updated_at` | `string` | |
+| `line_items` | `AdminLineItem[]` | Always included |
+| `shipments` | `AdminShipment[]` | Always included |
+| `payments` | `AdminPayment[]` | Always included |
+| `bill_address` | `StoreAddress \| null` | |
+| `ship_address` | `StoreAddress \| null` | |
+| `payment_methods` | `StorePaymentMethod[]` | |
+| `user?` | `AdminCustomer` | Requires expand |
+| `adjustments?` | `AdminAdjustment[]` | Requires expand |
+| `return_authorizations?` | `AdminReturnAuthorization[]` | Requires expand |
+| `reimbursements?` | `AdminReimbursement[]` | Requires expand |
+
+---
+
+## Order Adjustments
+
+Nested under `admin.orders.adjustments`.
+
+### `admin.orders.adjustments.list(orderId, params?, options?)`
+
+### `admin.orders.adjustments.get(orderId, id, params?, options?)`
+
+### `admin.orders.adjustments.create(orderId, params, options?)`
+
+```ts
+await client.admin.orders.adjustments.create('or_abc', {
+ amount: -5.00,
+ label: 'Loyalty discount',
+}, { token })
+```
+
+**Params:** `AdminAdjustmentCreateParams`
+
+| Field | Type | Required |
+|-------|------|----------|
+| `amount` | `number` | yes |
+| `label` | `string` | yes |
+
+### `admin.orders.adjustments.update(orderId, id, params, options?)`
+
+**Params:** `AdminAdjustmentUpdateParams`
+
+| Field | Type |
+|-------|------|
+| `amount` | `number` |
+| `label` | `string` |
+| `eligible` | `boolean` |
+
+### `admin.orders.adjustments.delete(orderId, id, options?)`
+
+---
+
+## Order Line Items
+
+Nested under `admin.orders.lineItems`.
+
+### `admin.orders.lineItems.list(orderId, params?, options?)`
+
+### `admin.orders.lineItems.get(orderId, id, params?, options?)`
+
+### `admin.orders.lineItems.create(orderId, params, options?)`
+
+```ts
+await client.admin.orders.lineItems.create('or_abc', {
+ variant_id: 'variant_xyz',
+ quantity: 2,
+}, { token })
+```
+
+**Params:** `AdminLineItemCreateParams`
+
+| Field | Type | Required |
+|-------|------|----------|
+| `variant_id` | `string` | yes |
+| `quantity` | `number` | no (defaults to 1) |
+
+### `admin.orders.lineItems.update(orderId, id, params, options?)`
+
+**Params:** `AdminLineItemUpdateParams` — `{ quantity?: number }`
+
+### `admin.orders.lineItems.delete(orderId, id, options?)`
+
+---
+
+## Order Payments
+
+Nested under `admin.orders.payments`.
+
+### `admin.orders.payments.list(orderId, params?, options?)`
+
+### `admin.orders.payments.get(orderId, id, params?, options?)`
+
+### `admin.orders.payments.create(orderId, params, options?)`
+
+```ts
+await client.admin.orders.payments.create('or_abc', {
+ payment_method_id: 'pm_xyz',
+ amount: 49.99,
+ source_id: 'cc_abc',
+}, { token })
+```
+
+**Params:** `AdminPaymentCreateParams`
+
+| Field | Type | Required |
+|-------|------|----------|
+| `payment_method_id` | `string` | yes |
+| `amount` | `number` | no |
+| `source_id` | `string` | no |
+
+### `admin.orders.payments.capture(orderId, id, params?, options?)`
+
+Capture an authorized payment.
+
+### `admin.orders.payments.void(orderId, id, params?, options?)`
+
+Void a pending payment.
+
+---
+
+## Order Refunds
+
+Nested under `admin.orders.refunds`.
+
+### `admin.orders.refunds.list(orderId, params?, options?)`
+
+### `admin.orders.refunds.create(orderId, params, options?)`
+
+```ts
+await client.admin.orders.refunds.create('or_abc', {
+ payment_id: 'pay_xyz',
+ amount: 10.00,
+ refund_reason_id: 'rr_abc',
+}, { token })
+```
+
+**Params:** `AdminRefundCreateParams`
+
+| Field | Type | Required |
+|-------|------|----------|
+| `payment_id` | `string` | yes |
+| `amount` | `number` | yes |
+| `refund_reason_id` | `string` | no |
+
+---
+
+## Order Shipments
+
+Nested under `admin.orders.shipments`.
+
+### `admin.orders.shipments.list(orderId, params?, options?)`
+
+### `admin.orders.shipments.get(orderId, id, params?, options?)`
+
+### `admin.orders.shipments.update(orderId, id, params, options?)`
+
+```ts
+await client.admin.orders.shipments.update('or_abc', 'ship_xyz', {
+ tracking: '1Z999AA10123456784',
+ selected_shipping_rate_id: 'sr_abc',
+}, { token })
+```
+
+**Params:** `AdminShipmentUpdateParams`
+
+| Field | Type |
+|-------|------|
+| `tracking` | `string` |
+| `selected_shipping_rate_id` | `string` |
+
+### `admin.orders.shipments.ship(orderId, id, params?, options?)`
+
+Mark a shipment as shipped.
+
+### `admin.orders.shipments.cancel(orderId, id, params?, options?)`
+
+Cancel a shipment.
+
+### `admin.orders.shipments.resume(orderId, id, params?, options?)`
+
+Resume a canceled shipment.
+
+### `admin.orders.shipments.split(orderId, id, params?, options?)`
+
+Split a shipment.
+
+---
+
+## Taxonomies
+
+### `admin.taxonomies.list(params?, options?)`
+
+```ts
+const taxonomies = await client.admin.taxonomies.list({
+ expand: ['taxons', 'root'],
+}, { token })
+```
+
+### `admin.taxonomies.get(id, params?, options?)`
+
+### `admin.taxonomies.create(params, options?)`
+
+```ts
+const taxonomy = await client.admin.taxonomies.create({
+ name: 'Categories',
+ position: 1,
+}, { token })
+```
+
+**Params:** `AdminTaxonomyCreateParams`
+
+| Field | Type | Required |
+|-------|------|----------|
+| `name` | `string` | yes |
+| `position` | `number` | no |
+
+### `admin.taxonomies.update(id, params, options?)`
+
+### `admin.taxonomies.delete(id, options?)`
+
+### Response Type: `AdminTaxonomy`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Prefixed ID |
+| `name` | `string` | |
+| `position` | `number` | |
+| `store_id` | `string \| null` | |
+| `root_id` | `string \| null` | Root taxon ID |
+| `created_at` | `string` | |
+| `updated_at` | `string` | |
+| `root?` | `AdminTaxon` | Requires expand |
+| `taxons?` | `AdminTaxon[]` | Requires expand |
+| `metafields?` | `AdminMetafield[]` | Requires expand |
+
+---
+
+## Taxonomy Taxons
+
+Nested under `admin.taxonomies.taxons`. Manages taxons within a specific taxonomy.
+
+### `admin.taxonomies.taxons.list(taxonomyId, params?, options?)`
+
+### `admin.taxonomies.taxons.get(taxonomyId, id, params?, options?)`
+
+### `admin.taxonomies.taxons.create(taxonomyId, params, options?)`
+
+```ts
+const taxon = await client.admin.taxonomies.taxons.create('taxonomy_abc', {
+ name: 'T-Shirts',
+ parent_id: 'taxon_root',
+ position: 1,
+ description: 'All t-shirt products',
+ meta_title: 'T-Shirts',
+ hide_from_nav: false,
+}, { token })
+```
+
+**Params:** `AdminTaxonCreateParams`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | yes | |
+| `parent_id` | `string` | no | Prefixed ID of parent taxon |
+| `position` | `number` | no | |
+| `description` | `string` | no | |
+| `permalink` | `string` | no | Custom URL slug |
+| `meta_title` | `string` | no | |
+| `meta_description` | `string` | no | |
+| `meta_keywords` | `string` | no | |
+| `hide_from_nav` | `boolean` | no | |
+| `sort_order` | `string` | no | |
+
+### `admin.taxonomies.taxons.update(taxonomyId, id, params, options?)`
+
+### `admin.taxonomies.taxons.delete(taxonomyId, id, options?)`
+
+---
+
+## Taxons (Flat)
+
+A flat endpoint for listing and retrieving taxons across all taxonomies.
+
+### `admin.taxons.list(params?, options?)`
+
+```ts
+const taxons = await client.admin.taxons.list({
+ expand: ['taxonomy', 'children'],
+}, { token })
+```
+
+### `admin.taxons.get(id, params?, options?)`
+
+### Response Type: `AdminTaxon`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Prefixed ID |
+| `name` | `string` | |
+| `permalink` | `string` | URL path |
+| `position` | `number` | |
+| `depth` | `number` | Nesting depth (0 = root) |
+| `parent_id` | `string \| null` | |
+| `taxonomy_id` | `string` | |
+| `description` | `string` | |
+| `description_html` | `string` | |
+| `image_url` | `string \| null` | |
+| `square_image_url` | `string \| null` | |
+| `children_count` | `number` | |
+| `is_root` | `boolean` | |
+| `is_child` | `boolean` | |
+| `is_leaf` | `boolean` | |
+| `hide_from_nav` | `boolean` | |
+| `sort_order` | `string` | |
+| `automatic` | `boolean` | Auto-matching rules |
+| `rules_match_policy` | `string` | |
+| `lft` | `number` | Nested set left |
+| `rgt` | `number` | Nested set right |
+| `meta_title` | `string \| null` | |
+| `meta_description` | `string \| null` | |
+| `meta_keywords` | `string \| null` | |
+| `created_at` | `string` | |
+| `updated_at` | `string` | |
+| `parent?` | `AdminTaxon` | Requires expand |
+| `children?` | `AdminTaxon[]` | Requires expand |
+| `ancestors?` | `AdminTaxon[]` | Requires expand |
+| `taxonomy?` | `AdminTaxonomy` | Requires expand |
+| `metafields?` | `AdminMetafield[]` | Requires expand |
+
+---
+
+## Error Handling
+
+All methods throw `SpreeError` on failure:
+
+```ts
+import { SpreeError } from '@spree/sdk'
+
+try {
+ await client.admin.products.get('prod_nonexistent', {}, { token })
+} catch (error) {
+ if (error instanceof SpreeError) {
+ console.log(error.code) // 'not_found'
+ console.log(error.status) // 404
+ console.log(error.message) // "Couldn't find Spree::Product..."
+ console.log(error.details) // { field: ['message'] } for validation errors
+ }
+}
+```
+
+### Error Response Shape
+
+```ts
+interface ErrorResponse {
+ error: {
+ code: string // 'not_found', 'validation_error', 'unauthorized', etc.
+ message: string
+ details?: Record<string, string[]> // field-level errors for 422s
+ }
+}
+```
+
+Common error codes:
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `unauthorized` | 401 | Missing or invalid API key / token |
+| `forbidden` | 403 | Insufficient permissions |
+| `not_found` | 404 | Resource not found |
+| `validation_error` | 422 | Invalid params (see `details` for fields) |
+| `conflict` | 409 | Idempotency key conflict |
diff --git a/server/config/initializers/cors.rb b/server/config/initializers/cors.rb
new file mode 100644
index 0000000000..8c1c291570
--- /dev/null
+++ b/server/config/initializers/cors.rb
@@ -0,0 +1,16 @@
+# Be sure to restart your server when you modify this file.
+
+# Avoid CORS issues when API is called from the frontend app.
+# Handle://preflight `OPTIONS` requests.
+
+Rails.application.config.middleware.insert_before 0, Rack::Cors do
+ allow do
+ origins '*'
+
+ resource '/api/*',
+ headers: :any,
+ methods: [:get, :post, :put, :patch, :delete, :options, :head],
+ expose: ['X-Total-Count', 'X-Page', 'X-Per-Page'],
+ max_age: 7200
+ end
+end