Alerts
API reference for @luxalgo/vela-pro-alerts, including the alerts plugin, controller, backend port, dialog, and widget.
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, Standalone widgets.
Functions
alerts
Alerts as a Vela Pro plugin. Its API opens the new-alert dialog for other plugins.
function alerts(opts?: EnableAlertsOptions): VelaProPlugin<AlertsApi>See also: AlertsApi, EnableAlertsOptions, VelaProPlugin.
alertsController
function alertsController(): AlertsController | nullSee also: AlertsController.
classifyAlert
The kind of an alert an engine raised (see the module note).
function classifyAlert(a: { id: string; title?: string }): Exclude<ScriptEvent, 'any'>See also: ScriptEvent.
createAlertsList
The alerts list as a widget: { el, update, destroy }.
function createAlertsList(props: AlertsListProps): AlertsListWidgetSee also: AlertsListProps, AlertsListWidget.
describeCondition
A readable summary of a rule's condition.
function describeCondition(rule: AlertRule, formatPrice: (p: number) => string): stringSee also: AlertRule.
enableAlerts
Enable ALERTS on every shell built afterwards. Returns the page's AlertsController. Call ONCE, before constructing shells. Idempotent.
function enableAlerts(opts?: EnableAlertsOptions): AlertsControllerSee also: AlertsController, EnableAlertsOptions.
openAlertDialog
function openAlertDialog(ctx: WidgetContext, alerts: AlertsController, seed: AlertDialogSeed): voidSee also: AlertDialogSeed, AlertsController. From @luxalgo/vela/plugin: WidgetContext.
priceConditionMet
Whether a price operator holds over one step.
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.
renderMessage
Fill a message template's placeholders. Unknown ones stay as written.
function renderMessage(
template: string,
values: Record<string, string | number | undefined>,
): stringscriptAlertSources
What source can alert on. Comments are ignored; dynamic titles are skipped.
function scriptAlertSources(source: string): ScriptAlertSourcesSee also: ScriptAlertSources.
Classes
AlertsController class
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, AlertRule, AlertsChange, AlertsControllerOptions, NewAlert.
AlertsListWidget
class AlertsListWidget {
constructor(props: AlertsListProps);
readonly el: HTMLElement;
update(next: Partial<Omit<AlertsListProps, 'controller'>>): void;
destroy(): void;
}See also: AlertsListProps.
LocalAlertsBackend
The browser's localStorage, under one key (default 'vela-pro.alerts').
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, AlertRule, AlertsBackend.
MemoryAlertsBackend
An in-memory backend (tests, or a host that persists through onFire and its own store).
class MemoryAlertsBackend implements AlertsBackend {
load(): { rules: AlertRule[]; events: AlertEvent[] };
save(state: { rules: readonly AlertRule[]; events: readonly AlertEvent[] }): void;
}See also: AlertEvent, AlertRule, AlertsBackend.
Interfaces and types
AlertCondition
type AlertCondition =
| { kind: 'price'; op: PriceOperator; value: number; upper?: number }
| { kind: 'script'; indicatorId: string; indicatorTitle: string; event: ScriptEvent; conditionTitle?: string; };See also: PriceOperator, ScriptEvent.
AlertDialogSeed
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.
AlertEvent
interface AlertEvent {
id: string;
ruleId: string;
name: string;
symbol: string;
time: number;
message: string;
price?: number;
}AlertFrequency
once fires a single time then stops; the others keep the alert active.
type AlertFrequency = 'once' | 'once-per-bar' | 'once-per-bar-close' | 'every-time';AlertNotify
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
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, AlertFrequency, AlertNotify, AlertStatus.
AlertsBackend
Where alerts and their history live. Default: the browser (LocalAlertsBackend).
interface AlertsBackend {
load(): { rules: AlertRule[]; events: AlertEvent[] };
save(state: { rules: readonly AlertRule[]; events: readonly AlertEvent[] }): void;
}See also: AlertEvent, AlertRule.
AlertsChange
type AlertsChange = 'rules' | 'events';AlertsControllerOptions
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, AlertRule, AlertsBackend.
AlertsListProps
The alerts list's props. controller is read once; the others can change through update.
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, AlertsController.
AlertStatus
type AlertStatus = 'active' | 'paused' | 'triggered' | 'expired';EnableAlertsOptions
Options for enableAlerts.
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, AlertRule, AlertsBackend.
NewAlert
interface NewAlert {
name?: string;
symbol: string;
condition: AlertCondition;
frequency?: AlertFrequency;
message?: string;
notify?: Partial<AlertNotify>;
expiresAt?: number | null;
}See also: AlertCondition, AlertFrequency, AlertNotify.
PriceOperator
type PriceOperator =
| 'crossing'
| 'crossing-up'
| 'crossing-down'
| 'greater-than'
| 'less-than'
| 'entering-channel'
| 'exiting-channel'
| 'inside-channel'
| 'outside-channel';ScriptAlertSources interface
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
type ScriptEvent = 'any' | 'alert' | 'condition' | 'order-fill';Constants
ALERTS_NATIVE_TYPE
const ALERTS_NATIVE_TYPE: 'vela-pro.alerts';ALERTS_PANEL_ID
const ALERTS_PANEL_ID: 'vela-pro.alerts';FREQUENCIES
const FREQUENCIES: ReadonlyArray<{ id: AlertFrequency; label: string; hint: string }>;See also: AlertFrequency.
PRICE_OPERATORS
const PRICE_OPERATORS: ReadonlyArray<{ id: PriceOperator; label: string; channel?: boolean }>;See also: PriceOperator.