queue/admin/frontend/README.md

# @lilith/queue/admin/frontend

React hooks for BullMQ queue dashboard integration.

## Installation

```bash
npm install @lilith/queue/admin/frontend
```

Peer dependencies:
- `react ^18.0.0`
- `socket.io-client ^4.7.0`

## Usage

### Setup React Query Provider

```tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Dashboard />
    </QueryClientProvider>
  );
}
```

### Fetch Queue Metrics

```tsx
import { useQueueMetrics } from '@lilith/queue/admin/frontend';

function Dashboard() {
  const { queues, metrics, isLoading, error } = useQueueMetrics({
    apiUrl: 'http://localhost:3000',
    refreshInterval: 5000
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {queues.map(queue => (
        <QueueCard key={queue.name} queue={queue} />
      ))}
    </div>
  );
}
```

### Real-time WebSocket Updates

```tsx
import { useQueueWebSocket } from '@lilith/queue/admin/frontend';

function LiveMetrics() {
  const { metrics, isConnected, subscribe, unsubscribe } = useQueueWebSocket({
    url: 'http://localhost:3000',
    queues: ['email-queue', 'image-processing'],
    token: 'your-auth-token' // optional
  });

  return (
    <div>
      <div>Status: {isConnected ? 'Connected' : 'Disconnected'}</div>
      {Array.from(metrics.entries()).map(([name, metric]) => (
        <MetricCard key={name} queueName={name} metrics={metric} />
      ))}
    </div>
  );
}
```

### Fetch Jobs with Filters

```tsx
import { useJobs, JobState } from '@lilith/queue/admin/frontend';

function JobList({ queueName }: { queueName: string }) {
  const [page, setPage] = useState(1);
  const [state, setState] = useState<JobState>('failed');

  const { jobs, total, totalPages, isLoading } = useJobs({
    apiUrl: 'http://localhost:3000',
    queueName,
    filters: { state, page, limit: 20 }
  });

  return (
    <div>
      <select value={state} onChange={e => setState(e.target.value as JobState)}>
        <option value="waiting">Waiting</option>
        <option value="active">Active</option>
        <option value="completed">Completed</option>
        <option value="failed">Failed</option>
      </select>

      <ul>
        {jobs.map(job => (
          <JobItem key={job.id} job={job} />
        ))}
      </ul>

      <Pagination page={page} totalPages={totalPages} onPageChange={setPage} />
    </div>
  );
}
```

### Queue Control Operations

```tsx
import { useQueueControl } from '@lilith/queue/admin/frontend';

function QueueControls({ queueName }: { queueName: string }) {
  const {
    pauseQueue,
    resumeQueue,
    cleanQueue,
    retryAllFailed,
    isPending
  } = useQueueControl({
    apiUrl: 'http://localhost:3000',
    onSuccess: (action) => {
      console.log(`${action} completed`);
    },
    onError: (action, error) => {
      console.error(`${action} failed:`, error);
    }
  });

  return (
    <div>
      <button
        onClick={() => pauseQueue({ queueName })}
        disabled={isPending}
      >
        Pause Queue
      </button>
      <button
        onClick={() => resumeQueue({ queueName })}
        disabled={isPending}
      >
        Resume Queue
      </button>
      <button
        onClick={() => cleanQueue({
          queueName,
          state: 'completed',
          grace: 3600000 // 1 hour
        })}
        disabled={isPending}
      >
        Clean Completed Jobs
      </button>
      <button
        onClick={() => retryAllFailed({ queueName })}
        disabled={isPending}
      >
        Retry All Failed
      </button>
    </div>
  );
}
```

### Full Dashboard Component

The complete dashboard with all features integrated:

```tsx
import { QueueDashboard } from '@lilith/queue/admin/frontend';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <QueueDashboard
        apiUrl="http://localhost:3000/api/admin"
        wsUrl="http://localhost:3000"
        refreshInterval={5000}
        enableWebSocket={true}
        onError={(error) => console.error('Dashboard error:', error)}
      />
    </QueryClientProvider>
  );
}
```

## API

### Components

- `QueueDashboard` - Main dashboard with queue list, job browser, and DLQ manager
- `QueueList` - List of queue cards with selection support
- `QueueCard` - Single queue card displaying status and metrics
- `JobsTable` - Paginated table of jobs with filters and detail modal
- `JobDetailsModal` - Modal showing complete job data and error traces
- `DLQManager` - Dead letter queue management for failed jobs

### Hooks

- `useQueueMetrics(options)` - Fetch queue list and metrics with auto-refresh
- `useQueueWebSocket(options)` - Subscribe to real-time queue metrics via WebSocket
- `useJobs(options)` - Fetch paginated jobs with filters
- `useQueueControl(options)` - Mutations for pause, resume, clean, retry operations

### Types

All TypeScript types are exported from the main entry point:

```typescript
import type {
  QueueSummary,
  QueueMetrics,
  JobDetails,
  JobState,
  JobFilters,
  DLQItem,
  PaginatedResponse,
  QueueControlOptions,
  CleanQueueOptions,
  RetryJobOptions,
  RetryAllFailedOptions,
} from '@lilith/queue/admin/frontend';
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev
```

## License

MIT