# @toolctrl/queue

BullMQ-oriented queue contracts and producer helpers for web/API enqueue paths and the opt-in worker runtime.

This package defines stable queue names, typed payloads, job descriptors, producer helpers and small BullMQ factory helpers. Processors live in `apps/worker`; queues only run when the worker is enabled and the related runtime flags/services are configured.

## Queues

| Queue                         | Purpose                                                         |
| ----------------------------- | --------------------------------------------------------------- |
| `toolctrl.email`              | Transactional email and webhook delivery jobs.                  |
| `toolctrl.notifications`      | User notification delivery jobs.                                |
| `toolctrl.maintenance`        | Background cleanup and retention jobs.                          |
| `toolctrl.ai-chatbot`         | Contract for admin-managed AI chat completion jobs.             |
| `toolctrl.browser-automation` | Contract for browser session run, cleanup and usage flush jobs. |
| `toolctrl.file-scan`          | Storage file scan jobs.                                         |
| `toolctrl.exports`            | Export job execution.                                           |
| `toolctrl.imports`            | Import job execution.                                           |
| `toolctrl.plugin-invoke`      | Isolated third-party plugin invocation jobs.                    |

## AI/Browser Jobs

Stable job names:

- `chat-completion`
- `browser-session-run`
- `browser-session-cleanup`
- `usage-flush`
- `scan-file`
- `run-export`
- `run-import`

These are typed contracts and descriptors. Concrete processing is owned by `apps/worker` handlers and may still be disabled until the matching service flag or provider configuration is present.

## Redis

Queue workers resolve Redis from `BULLMQ_REDIS_URL` first. `REDIS_URL` is fallback only when `BULLMQ_REDIS_URL` is absent, so new deployments should prefer the BullMQ-specific variable and keep generic platform Redis bindings optional.

Supported URL schemes:

- `redis://localhost:6379/0`
- `rediss://user:password@example.redis:6379/0`

## Usage

```ts
import { createQueue, queueNames, resolveRedisConnectionOptions } from "@toolctrl/queue";

const emailQueue = createQueue(queueNames.email, {
  connection: resolveRedisConnectionOptions({ required: true }),
});

await emailQueue.add("send-email", {
  kind: "mail.transactional",
  recipientEmail: "user@example.com",
  templateId: "welcome",
});
```