# Alerts (/vela-pro/api/alerts)



This page documents `@luxalgo/vela-pro-alerts`, including the `alerts()` plugin factory, `AlertsController`, the alert backend port, the alert editor dialog, the standalone alerts list widget, and rule and trigger event types.

Import symbols on this page from `@luxalgo/vela-pro-alerts`. Related guides: [Alerts](/vela-pro/modules/catalog/alerts), [Standalone widgets](/vela-pro/modules/widgets).

## Functions [#functions]

### `alerts` [#alerts]

Alerts as a Vela Pro plugin. Its API opens the new-alert dialog for other plugins.

```typescript
function alerts(opts?: EnableAlertsOptions): VelaProPlugin<AlertsApi>
```

See also: [`AlertsApi`](/vela-pro/api/module-sdk#alertsapi), [`EnableAlertsOptions`](/vela-pro/api/alerts#enablealertsoptions), [`VelaProPlugin`](/vela-pro/api/module-sdk#velaproplugin).

### `alertsController` [#alertscontroller]

```typescript
function alertsController(): AlertsController | null
```

See also: [`AlertsController`](/vela-pro/api/alerts#alertscontroller-class).

### `classifyAlert` [#classifyalert]

The kind of an alert an engine raised (see the module note).

```typescript
function classifyAlert(a: { id: string; title?: string }): Exclude<ScriptEvent, 'any'>
```

See also: [`ScriptEvent`](/vela-pro/api/alerts#scriptevent).

### `createAlertsList` [#createalertslist]

The alerts list as a widget: `{ el, update, destroy }`.

```typescript
function createAlertsList(props: AlertsListProps): AlertsListWidget
```

See also: [`AlertsListProps`](/vela-pro/api/alerts#alertslistprops), [`AlertsListWidget`](/vela-pro/api/alerts#alertslistwidget).

### `describeCondition` [#describecondition]

A readable summary of a rule's condition.

```typescript
function describeCondition(rule: AlertRule, formatPrice: (p: number) => string): string
```

See also: [`AlertRule`](/vela-pro/api/alerts#alertrule).

### `enableAlerts` [#enablealerts]

Enable ALERTS on every shell built afterwards. Returns the page's [`AlertsController`](/vela-pro/api/alerts#alertscontroller-class). Call ONCE, before constructing shells. Idempotent.

```typescript
function enableAlerts(opts?: EnableAlertsOptions): AlertsController
```

See also: [`AlertsController`](/vela-pro/api/alerts#alertscontroller-class), [`EnableAlertsOptions`](/vela-pro/api/alerts#enablealertsoptions).

### `openAlertDialog` [#openalertdialog]

```typescript
function openAlertDialog(ctx: WidgetContext, alerts: AlertsController, seed: AlertDialogSeed): void
```

See also: [`AlertDialogSeed`](/vela-pro/api/alerts#alertdialogseed), [`AlertsController`](/vela-pro/api/alerts#alertscontroller-class). From `@luxalgo/vela/plugin`: `WidgetContext`.

### `priceConditionMet` [#priceconditionmet]

Whether a price operator holds over one step.

```typescript
function priceConditionMet(
    op: PriceOperator,
    value: number,
    upper: number | undefined,
    step: PriceStep,
): boolean

// Unexported supporting type referenced above
interface PriceStep {
    prev: number | undefined;
    curr: number;
}
```

See also: [`PriceOperator`](/vela-pro/api/alerts#priceoperator).

### `renderMessage` [#rendermessage]

Fill a message template's placeholders. Unknown ones stay as written.

```typescript
function renderMessage(
    template: string,
    values: Record<string, string | number | undefined>,
): string
```

### `scriptAlertSources` [#scriptalertsources]

What `source` can alert on. Comments are ignored; dynamic titles are skipped.

```typescript
function scriptAlertSources(source: string): ScriptAlertSources
```

See also: [`ScriptAlertSources`](/vela-pro/api/alerts#scriptalertsources-interface).

## Classes [#classes]

### `AlertsController` class [#alertscontroller-class]

```typescript
class AlertsController {
    constructor(opts: AlertsControllerOptions);
    readonly unreadCount: number;
    readonly webhooksAllowed: boolean;
    rules(): AlertRule[];
    rule(id: string): AlertRule | undefined;
    log(): readonly AlertEvent[];
    lastPrice(symbol: string): number | undefined;
    create(a: NewAlert): AlertRule;
    update(id: string, patch: Partial<Omit<AlertRule, 'id' | 'createdAt'>>): void;
    remove(id: string): void;
    setPaused(id: string, paused: boolean): void;
    moveLevel(id: string, value: number, which?: 'value' | 'upper'): void;
    markRead(): void;
    clearLog(): void;
    notePrice(symbol: string, price: number, barTime: number, interval?: string): void;
    noteScriptAlert(
        symbol: string,
        indicatorId: string,
        alert: { id: string; message: string; title?: string; time: number },
        interval?: string,
    ): void;
    onFire(cb: (e: AlertEvent, rule: AlertRule) => void): () => void;
    onChange(cb: (what: AlertsChange) => void): () => void;
    flush(): void;
}
```

| Member              | Type                                                                                                         | Description                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `constructor`       | `(opts: AlertsControllerOptions)`                                                                            |                                                                                   |
| `unreadCount`       | `number`                                                                                                     |                                                                                   |
| `webhooksAllowed`   | `boolean`                                                                                                    |                                                                                   |
| `rules()`           | `() => AlertRule[]`                                                                                          |                                                                                   |
| `rule()`            | `(id: string) => AlertRule \| undefined`                                                                     |                                                                                   |
| `log()`             | `() => readonly AlertEvent[]`                                                                                |                                                                                   |
| `lastPrice()`       | `(symbol: string) => number \| undefined`                                                                    |                                                                                   |
| `create()`          | `(a: NewAlert) => AlertRule`                                                                                 |                                                                                   |
| `update()`          | `(id: string, patch: Partial<Omit<AlertRule, 'id' \| 'createdAt'>>) => void`                                 |                                                                                   |
| `remove()`          | `(id: string) => void`                                                                                       |                                                                                   |
| `setPaused()`       | `(id: string, paused: boolean) => void`                                                                      |                                                                                   |
| `moveLevel()`       | `(id: string, value: number, which?: 'value' \| 'upper') => void`                                            | Move a price alert's level (its line was dragged). Default: `which = 'value'`.    |
| `markRead()`        | `() => void`                                                                                                 |                                                                                   |
| `clearLog()`        | `() => void`                                                                                                 |                                                                                   |
| `notePrice()`       | `(symbol: string, price: number, barTime: number, interval?: string) => void`                                | A chart's live bar: its open time and its latest close. Default: `interval = ''`. |
| `noteScriptAlert()` | `(symbol: string, indicatorId: string, alert: { id: string; message: string; …` (truncated; see declaration) | An indicator raised an alert (`handle.on('alert')`). Default: `interval = ''`.    |
| `onFire()`          | `(cb: (e: AlertEvent, rule: AlertRule) => void) => () => void`                                               |                                                                                   |
| `onChange()`        | `(cb: (what: AlertsChange) => void) => () => void`                                                           |                                                                                   |
| `flush()`           | `() => void`                                                                                                 | Write pending changes now (tests, page unload).                                   |

See also: [`AlertEvent`](/vela-pro/api/alerts#alertevent), [`AlertRule`](/vela-pro/api/alerts#alertrule), [`AlertsChange`](/vela-pro/api/alerts#alertschange), [`AlertsControllerOptions`](/vela-pro/api/alerts#alertscontrolleroptions), [`NewAlert`](/vela-pro/api/alerts#newalert).

### `AlertsListWidget` [#alertslistwidget]

```typescript
class AlertsListWidget {
    constructor(props: AlertsListProps);
    readonly el: HTMLElement;
    update(next: Partial<Omit<AlertsListProps, 'controller'>>): void;
    destroy(): void;
}
```

See also: [`AlertsListProps`](/vela-pro/api/alerts#alertslistprops).

### `LocalAlertsBackend` [#localalertsbackend]

The browser's localStorage, under one key (default `'vela-pro.alerts'`).

```typescript
class LocalAlertsBackend implements AlertsBackend {
    constructor(key?: string);
    load(): { rules: AlertRule[]; events: AlertEvent[] };
    save(state: { rules: readonly AlertRule[]; events: readonly AlertEvent[] }): void;
}
```

Default: `constructor(key = 'vela-pro.alerts')`.

See also: [`AlertEvent`](/vela-pro/api/alerts#alertevent), [`AlertRule`](/vela-pro/api/alerts#alertrule), [`AlertsBackend`](/vela-pro/api/alerts#alertsbackend).

### `MemoryAlertsBackend` [#memoryalertsbackend]

An in-memory backend (tests, or a host that persists through `onFire` and its own store).

```typescript
class MemoryAlertsBackend implements AlertsBackend {
    load(): { rules: AlertRule[]; events: AlertEvent[] };
    save(state: { rules: readonly AlertRule[]; events: readonly AlertEvent[] }): void;
}
```

See also: [`AlertEvent`](/vela-pro/api/alerts#alertevent), [`AlertRule`](/vela-pro/api/alerts#alertrule), [`AlertsBackend`](/vela-pro/api/alerts#alertsbackend).

## Interfaces and types [#interfaces-and-types]

### `AlertCondition` [#alertcondition]

```typescript
type AlertCondition =
    | { kind: 'price'; op: PriceOperator; value: number; upper?: number }
    | { kind: 'script'; indicatorId: string; indicatorTitle: string; event: ScriptEvent; conditionTitle?: string; };
```

See also: [`PriceOperator`](/vela-pro/api/alerts#priceoperator), [`ScriptEvent`](/vela-pro/api/alerts#scriptevent).

### `AlertDialogSeed` [#alertdialogseed]

```typescript
interface AlertDialogSeed {
    symbol: string;
    price?: number;
    indicatorId?: string;
    rule?: AlertRule;
}
```

| Member         | Type        | Description                               |
| -------------- | ----------- | ----------------------------------------- |
| `symbol`       | `string`    |                                           |
| `price?`       | `number`    | Prefill a price alert at this level.      |
| `indicatorId?` | `string`    | Prefill a script alert on this indicator. |
| `rule?`        | `AlertRule` | Edit an existing alert instead.           |

See also: [`AlertRule`](/vela-pro/api/alerts#alertrule).

### `AlertEvent` [#alertevent]

```typescript
interface AlertEvent {
    id: string;
    ruleId: string;
    name: string;
    symbol: string;
    time: number;
    message: string;
    price?: number;
}
```

### `AlertFrequency` [#alertfrequency]

`once` fires a single time then stops; the others keep the alert active.

```typescript
type AlertFrequency = 'once' | 'once-per-bar' | 'once-per-bar-close' | 'every-time';
```

### `AlertNotify` [#alertnotify]

```typescript
interface AlertNotify {
    toast: boolean;
    sound: boolean;
    webhook?: string;
}
```

| Member     | Type      | Description                                                       |
| ---------- | --------- | ----------------------------------------------------------------- |
| `toast`    | `boolean` |                                                                   |
| `sound`    | `boolean` |                                                                   |
| `webhook?` | `string`  | POST the alert to this URL (only where the host allows webhooks). |

### `AlertRule` [#alertrule]

```typescript
interface AlertRule {
    id: string;
    name: string;
    symbol: string;
    condition: AlertCondition;
    frequency: AlertFrequency;
    message: string;
    notify: AlertNotify;
    status: AlertStatus;
    expiresAt: number | null;
    createdAt: number;
    updatedAt: number;
    lastFiredAt?: number;
    fireCount: number;
}
```

| Member         | Type             | Description                                                                          |
| -------------- | ---------------- | ------------------------------------------------------------------------------------ |
| `id`           | `string`         |                                                                                      |
| `name`         | `string`         |                                                                                      |
| `symbol`       | `string`         |                                                                                      |
| `condition`    | `AlertCondition` |                                                                                      |
| `frequency`    | `AlertFrequency` |                                                                                      |
| `message`      | `string`         | Message template: `{{ticker}}`, `{{close}}`, `{{time}}`, `{{interval}}`, `{{name}}`. |
| `notify`       | `AlertNotify`    |                                                                                      |
| `status`       | `AlertStatus`    |                                                                                      |
| `expiresAt`    | `number \| null` | Epoch ms after which the alert stops; null never.                                    |
| `createdAt`    | `number`         |                                                                                      |
| `updatedAt`    | `number`         |                                                                                      |
| `lastFiredAt?` | `number`         |                                                                                      |
| `fireCount`    | `number`         |                                                                                      |

See also: [`AlertCondition`](/vela-pro/api/alerts#alertcondition), [`AlertFrequency`](/vela-pro/api/alerts#alertfrequency), [`AlertNotify`](/vela-pro/api/alerts#alertnotify), [`AlertStatus`](/vela-pro/api/alerts#alertstatus).

### `AlertsBackend` [#alertsbackend]

Where alerts and their history live. Default: the browser ([`LocalAlertsBackend`](/vela-pro/api/alerts#localalertsbackend)).

```typescript
interface AlertsBackend {
    load(): { rules: AlertRule[]; events: AlertEvent[] };
    save(state: { rules: readonly AlertRule[]; events: readonly AlertEvent[] }): void;
}
```

See also: [`AlertEvent`](/vela-pro/api/alerts#alertevent), [`AlertRule`](/vela-pro/api/alerts#alertrule).

### `AlertsChange` [#alertschange]

```typescript
type AlertsChange = 'rules' | 'events';
```

### `AlertsControllerOptions` [#alertscontrolleroptions]

```typescript
interface AlertsControllerOptions {
    backend: AlertsBackend;
    onFire?: (event: AlertEvent, rule: AlertRule) => void;
    webhooks?: boolean;
    now?: () => number;
}
```

| Member      | Type                                           | Description                                                |
| ----------- | ---------------------------------------------- | ---------------------------------------------------------- |
| `backend`   | `AlertsBackend`                                |                                                            |
| `onFire?`   | `(event: AlertEvent, rule: AlertRule) => void` | Called for every firing, after the built-in notifications. |
| `webhooks?` | `boolean`                                      | Let alerts POST to a webhook URL.                          |
| `now?`      | `() => number`                                 |                                                            |

See also: [`AlertEvent`](/vela-pro/api/alerts#alertevent), [`AlertRule`](/vela-pro/api/alerts#alertrule), [`AlertsBackend`](/vela-pro/api/alerts#alertsbackend).

### `AlertsListProps` [#alertslistprops]

The alerts list's props. `controller` is read once; the others can change through `update`.

```typescript
interface AlertsListProps {
    controller: AlertsController;
    symbol?: string;
    host?: HTMLElement;
    active?: boolean;
    onOpenAlert?: (seed: AlertDialogSeed) => void;
    onNotify?: (message: string, kind: 'info' | 'success' | 'error') => void;
}
```

| Member         | Type                                                              | Description                                                                                          |
| -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `controller`   | `AlertsController`                                                | The alerts and their log.                                                                            |
| `symbol?`      | `string`                                                          | The symbol "New alert" starts on.                                                                    |
| `host?`        | `HTMLElement`                                                     | Where overlays mount (default: the widget's own element).                                            |
| `active?`      | `boolean`                                                         | Shown or hidden: shown on the log, it marks the fired alerts read.                                   |
| `onOpenAlert?` | `(seed: AlertDialogSeed) => void`                                 | Open the alert editor ("New alert", a row, Edit). Without it, the list only shows and pauses alerts. |
| `onNotify?`    | `(message: string, kind: 'info' \| 'success' \| 'error') => void` | Tell the user something (no symbol to add an alert on).                                              |

See also: [`AlertDialogSeed`](/vela-pro/api/alerts#alertdialogseed), [`AlertsController`](/vela-pro/api/alerts#alertscontroller-class).

### `AlertStatus` [#alertstatus]

```typescript
type AlertStatus = 'active' | 'paused' | 'triggered' | 'expired';
```

### `EnableAlertsOptions` [#enablealertsoptions]

Options for [`enableAlerts`](/vela-pro/api/alerts#enablealerts).

```typescript
interface EnableAlertsOptions {
    backend?: AlertsBackend;
    onFire?: (event: AlertEvent, rule: AlertRule) => void;
    webhooks?: boolean;
    contextMenu?: boolean;
    shortcut?: boolean;
    legendAction?: boolean;
    topbarBell?: boolean;
}
```

| Member          | Type                                           | Description                                                                                                                      |
| --------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `backend?`      | `AlertsBackend`                                | Where alerts are kept. Default: the browser's localStorage.                                                                      |
| `onFire?`       | `(event: AlertEvent, rule: AlertRule) => void` | Called on every firing: route it to email, push, a server…                                                                       |
| `webhooks?`     | `boolean`                                      | Let users give an alert a webhook URL (POSTed the fired event). Default false.                                                   |
| `contextMenu?`  | `boolean`                                      | "Add alert" in the chart's right-click menu (default true).                                                                      |
| `shortcut?`     | `boolean`                                      | Alt+A opens the dialog at the last price (default true).                                                                         |
| `legendAction?` | `boolean`                                      | A bell on script indicators' legend rows (default true).                                                                         |
| `topbarBell?`   | `boolean`                                      | Keep the topbar's bell, opening the Alerts panel (default false: the bell is put away, the rail's Alerts entry takes its place). |

See also: [`AlertEvent`](/vela-pro/api/alerts#alertevent), [`AlertRule`](/vela-pro/api/alerts#alertrule), [`AlertsBackend`](/vela-pro/api/alerts#alertsbackend).

### `NewAlert` [#newalert]

```typescript
interface NewAlert {
    name?: string;
    symbol: string;
    condition: AlertCondition;
    frequency?: AlertFrequency;
    message?: string;
    notify?: Partial<AlertNotify>;
    expiresAt?: number | null;
}
```

See also: [`AlertCondition`](/vela-pro/api/alerts#alertcondition), [`AlertFrequency`](/vela-pro/api/alerts#alertfrequency), [`AlertNotify`](/vela-pro/api/alerts#alertnotify).

### `PriceOperator` [#priceoperator]

```typescript
type PriceOperator =
    | 'crossing'
    | 'crossing-up'
    | 'crossing-down'
    | 'greater-than'
    | 'less-than'
    | 'entering-channel'
    | 'exiting-channel'
    | 'inside-channel'
    | 'outside-channel';
```

### `ScriptAlertSources` interface [#scriptalertsources-interface]

```typescript
interface ScriptAlertSources {
    conditions: string[];
    alerts: boolean;
    strategy: boolean;
}
```

| Member       | Type       | Description                                                                 |
| ------------ | ---------- | --------------------------------------------------------------------------- |
| `conditions` | `string[]` | `alertcondition()` titles, in source order (an untitled one reads "Alert"). |
| `alerts`     | `boolean`  | The script calls `alert()`.                                                 |
| `strategy`   | `boolean`  | The script is a strategy (its order fills alert).                           |

### `ScriptEvent` [#scriptevent]

```typescript
type ScriptEvent = 'any' | 'alert' | 'condition' | 'order-fill';
```

## Constants [#constants]

### `ALERTS_NATIVE_TYPE` [#alerts_native_type]

```typescript
const ALERTS_NATIVE_TYPE: 'vela-pro.alerts';
```

### `ALERTS_PANEL_ID` [#alerts_panel_id]

```typescript
const ALERTS_PANEL_ID: 'vela-pro.alerts';
```

### `FREQUENCIES` [#frequencies]

```typescript
const FREQUENCIES: ReadonlyArray<{ id: AlertFrequency; label: string; hint: string }>;
```

See also: [`AlertFrequency`](/vela-pro/api/alerts#alertfrequency).

### `PRICE_OPERATORS` [#price_operators]

```typescript
const PRICE_OPERATORS: ReadonlyArray<{ id: PriceOperator; label: string; channel?: boolean }>;
```

See also: [`PriceOperator`](/vela-pro/api/alerts#priceoperator).
