npm package: @moum/mirakl-connect-seller-client
Description: A web-based order management tool for Mirakl marketplace sellers. Browse, accept, cancel, and refund orders through a clean UI — no backend setup required.
Latest version: 0.1.0

# Mirakl Connect Seller Client

A web-based order management tool for Mirakl marketplace sellers. Browse, accept, cancel, and refund orders through a clean UI — no backend setup required.

## Features

- **Order Management** — View, accept, cancel, and refund orders with real-time status tracking
- **Auto-Refresh** — Orders list refreshes automatically to stay up to date
- **Action Polling** — Async operations (accept, cancel, refund) are polled until completion
- **OAuth Configuration** — Configure credentials once on the Settings page; stored in `localStorage`
- **Built-in Proxy** — A Node.js HTTP proxy forwards API calls to Mirakl Connect, avoiding CORS issues
- **CLI** — Run instantly with `npx`, no cloning required

## Quick Start

### Run with npx (no install)

```bash
npx @moum/mirakl-connect-seller-client
```

This starts the server on port 4321 and opens the app in your browser.

```
Options:
  -p, --port <number>  Port to listen on (default: 4321)
  --no-open            Don't open the browser automatically
  -h, --help           Show this help message
```

### Run from source

```bash
git clone <repo-url>
cd mirakl-connect-seller-client
npm install
npm run dev
```

## Configuration

Open the **Settings** page in the app and fill in your Mirakl Connect OAuth credentials:

| Field                | Description                          |
|----------------------|--------------------------------------|
| **Client ID**        | OAuth client ID                      |
| **Client Secret**    | OAuth client secret                  |
| **Auth Server URL**  | Token endpoint base URL              |
| **Connect Env URL**  | Mirakl Connect environment base URL  |

Credentials are stored in your browser's `localStorage` and never leave your machine (requests go through the local proxy).

## Available Scripts

| Command           | Description                              |
|-------------------|------------------------------------------|
| `npm run dev`     | Start Vite dev server with hot reload    |
| `npm run build`   | Type-check and build for production      |
| `npm start`       | Serve the production build               |
| `npm run lint`    | Run ESLint                               |
| `npm run preview` | Preview the production build via Vite    |

## Tech Stack

- **React 19** + **React Router 7**
- **TypeScript 5.9**
- **Vite 7**
- **Tailwind CSS 4** + **DaisyUI 5**
- **Lucide React** (icons)
- **Node.js HTTP server** + **http-proxy** (built-in proxy)

## Project Structure

```
src/
├── api/            # HTTP client, auth token logic, orders API
├── components/
│   ├── common/     # Reusable fields (price, tax, reason select)
│   ├── dialogs/    # Accept, cancel, refund, and status dialogs
│   └── orders/     # Order table, rows, detail panel, status chips
├── context/        # Auth and notification React contexts
├── hooks/          # Data fetching and action hooks
├── pages/          # Orders list, order detail, settings
├── types/          # TypeScript interfaces (orders, auth, actions)
└── utils/          # Formatting helpers and localStorage wrapper
```

## Architecture Notes

### Proxy

The app ships with a lightweight Node.js HTTP server (`server.mjs`) that:

1. Serves the built SPA from `dist/`
2. Forwards any request to `/proxy` to the URL specified in the `X-Proxy-Target` header

This avoids CORS issues — the browser talks to `localhost`, and the server proxies requests to the Mirakl Connect API.

### OAuth Flow

Credentials are configured on the Settings page and persisted in `localStorage`. The API client (`src/api/auth.ts`) handles token acquisition and refresh transparently before each API call.

## Requirements

- Node.js >= 18