Added plugin interface methods

docs/src/develop/plugins/server_plugin_api.md

@@ -652,6 +652,225 @@ in the specified direction and starting at the specified point.
 
 ---
 
+### Alerts API Interface
+
+The Alert API interface exposes methods to allow interaction with the Alert Manager to raise and take action on alerts.
+
+#### `app.alertsApi.getAlert(alertId)`
+
+Retrieve the current value of the supplied alert.
+
+- `alertid`: Identifier of the alert
+
+- returns:  `AlertValue` object representing the current value of the alert.
+
+_Example:_
+```javascript
+app.resourcesApi.getAlert(
+  'ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a'
+)
+```
+_Response:_
+```json
+{
+  "id": "ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a",
+  "created": "2025-01-02T08:19:58.676Z",
+  "priority": "alarm",
+  "process": "abnormal",
+  "alarmState": "active",
+  "acknowledged": false,
+  "silenced": false,
+  "metaData": {
+      "sourceRef": "alertsApi",
+      "name": "My Alert",
+      "message": "My alert message"
+  }
+}
+```
+
+#### `app.alertsApi.raiseAlert(priority, metaData?)`
+
+Create / raise an alert.
+
+- `priority`: Signal K alert priority _`emergency`,`alarm`, `warning`, `caution`_
+
+- `metaData` (optional): Additional alert properties _e.g. name, message, etc_.
+
+
+- returns:  `string` containing the identifier of the alert.
+
+_Example:_
+```javascript
+const alertId = app.resourcesApi.raiseAlert(
+  'alarm',
+  {
+    "name": "My Alert",
+    "message": "My alert message."
+  }
+)
+```
+
+#### `app.alertsApi.setAlertPriority(alertId, priority)`
+
+Set / change the priority of an alert.
+
+
+- `alertid`: Identifier of the alert
+
+- `priority`: Signal K alert priority _`emergency`,`alarm`, `warning`, `caution`_
+
+
+- returns:  `void`
+
+_Example:_
+```javascript
+app.resourcesApi.setAlertPriority(
+  'ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a',
+  'warning'
+)
+```
+
+#### `app.alertsApi.setAlertProperties(alertId, metaData)`
+
+Set / change the alert properties.
+
+
+- `alertid`: Identifier of the alert
+
+- `metaData`: Alert properties _e.g. name, message, etc_.
+
+
+- returns:  `void`
+
+_Example:_
+```javascript
+app.resourcesApi.setAlertProperties(
+  'ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a',
+  {
+    "name": "My updated Alert",
+    "message": "My updated alert message."
+  }
+)
+```
+
+#### `app.alertsApi.resolveAlert(alertId)`
+
+Resolve the alert and eturn to 'normal' condition.
+
+
+- `alertid`: Identifier of the alert
+
+
+- returns:  `void`
+
+_Example:_
+```javascript
+app.resourcesApi.resolveAlert(
+  'ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a'
+)
+```
+
+#### `app.alertsApi.ackAlert(alertId)`
+
+Acknowledge the alert.
+
+
+- `alertid`: Identifier of the alert
+
+
+- returns:  `void`
+
+_Example:_
+```javascript
+app.resourcesApi.ackAlert(
+  'ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a'
+)
+```
+
+#### `app.alertsApi.unackAlert(alertId)`
+
+Unacknowledge the alert.
+
+
+- `alertid`: Identifier of the alert
+
+
+- returns:  `void`
+
+_Example:_
+```javascript
+app.resourcesApi.unackAlert(
+  'ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a'
+)
+```
+
+#### `app.alertsApi.silenceAlert(alertId)`
+
+Silences the audible alarm associated with the alert for 30 seconds.
+
+
+- `alertid`: Identifier of the alert
+
+
+- returns:  `boolean` Returns `true` if alert was silenced or `false` if alert could not be silenced.
+
+_Example:_
+```javascript
+app.resourcesApi.silenceAlert(
+  'ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a'
+)
+```
+
+#### `app.alertsApi.removeAlert(alertId)`
+
+Remove the alert from the alert list.
+
+
+- `alertid`: Identifier of the alert
+
+
+- returns:  `boolean` Returns `true` if alert was silenced or `false` if alert could not be silenced.
+
+_Example:_
+```javascript
+app.resourcesApi.removeAlert(
+  'ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a'
+)
+```
+
+### Special Alerts
+
+#### `app.alertsApi.mob(properties?)`
+
+Raise a man / person overboard alert which has **priority** = `emergency` and properties set to the following pre-defined values (if no properties are supplied):
+
+| Property | Value |
+|--- |--- |
+| **path** | `mob` _(i.e. `notifications.mob.{id}`)_ |
+| **position** | Set to the vessel position at the time the alert was raised |
+| **name** | MOB |
+| **message** | Person Overboard! |
+| **sourceRef** | alarmApi |
+
+- `properties` (optional): Allows the `name`, `message` and `sourceRef` properties to have their pre-defined values overridden.
+
+- returns:  `string` containing the identifier of the alert.
+
+_Example:_
+```javascript
+// raise MOB with default property values
+const mobId = app.resourcesApi.mob()
+
+// raise MOB with overriden property values
+const mobId = app.resourcesApi.mob(
+  {
+    "name": "My MOB Alert",
+    "message": "My MOB alert message."
+  }
+)
+```
+
+
 ### PropertyValues
 
 The _PropertyValues_ mechanism provides a means for passing configuration type values between different components running in the server process such as plugins and input connections.

docs/src/develop/rest-api/alerts_api.md

@@ -13,6 +13,32 @@ become abnormal and measured values fall outside of acceptable thresholds.
 
 The Alerts API requests are sent to `/signalk/v2/api/alerts`.
 
+Alerts are assigned a unique identifier when created, which is used when undertaking subsequent operations e.g. silencing, acknkowledging, etc.
+
+Additionally, _Notifications_ raised by an alert will also contain the alert identifer in both their `path` and `value`.
+
+_Example:_
+```javascript
+// Alert ID:
+"74dbf514-ff33-4a3f-b212-fd28bd106a88"
+
+// Notification path
+"notifications.74dbf514-ff33-4a3f-b212-fd28bd106a88"
+
+// Notification value
+{
+  "id": "74dbf514-ff33-4a3f-b212-fd28bd106a88",
+  "method": ["visual","sound"],
+  "state": "alarm",
+  "message": "My Alert Message!",
+  "metaData": {
+    "name": "My Alert",
+    "created": "2025-01-10T02:49:13.080Z"
+  }
+}
+```
+
+
 ## Supported Operations
 
 ### Individual Alert
@@ -57,7 +83,7 @@ HTTP GET "/signalk/v2/api/alerts" {
     }
 }
 ```
-The `properties` attribute is an object containing key | value pairs, noting that the following pre-defined keys have been defined:
+The `properties` attribute is an object containing key | value pairs, which can be used to hold relevant data for an alert. It should be noted that the following keys have been defined by the Alerts API:
 ```javascript
 {
   name: //string value representing the alert name

packages/server-api/src/alertsapi.ts

@@ -0,0 +1,34 @@
+import { Path, Position, SourceRef } from '.'
+
+export type AlertPriority = 'emergency' | 'alarm' | 'warning' | 'caution'
+export type AlertProcess = 'normal' | 'abnormal'
+export type AlertAlarmState = 'active' | 'inactive'
+
+interface AlertAdditionalProperties {
+  name?: string
+  message?: string
+  position?: Position
+  path?: Path
+  sourceRef?: SourceRef
+}
+export interface AlertMetaData extends AlertAdditionalProperties {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [index: string]: any
+}
+
+export interface AlertValue {
+  id: string
+  created: Date
+  resolved: Date
+  priority: AlertPriority
+  process: AlertProcess
+  alarmState: AlertAlarmState
+  acknowledged: boolean
+  silenced: boolean
+  metaData: AlertMetaData
+}
+
+export const isAlertPriority = (value: AlertPriority) => {
+  return ['emergency', 'alarm', 'warning', 'caution'].includes(value)
+}
+

packages/server-api/src/index.ts

@@ -33,6 +33,8 @@ import { AutopilotProviderRegistry } from './autopilotapi'
 export { AutopilotProviderRegistry } from './autopilotapi'
 export * from './autopilotapi.guard'
 import { PointDestination, RouteDestination, CourseInfo } from './coursetypes'
+import { AlertMetaData, AlertPriority, AlertValue } from './alertsapi'
+export * from './alertsapi'
 
 export type SignalKApiId =
   | 'resources'
@@ -207,6 +209,19 @@ export interface ServerAPI extends PluginServerApp {
   ) => Promise<void>
   activateRoute: (dest: RouteDestination | null) => Promise<void>
 
+  alertsApi: {
+    mob: (properties?: AlertMetaData) => string
+    raiseAlert: (priority: AlertPriority, properties?: AlertMetaData) => string
+    setAlertPriority: (alertId: string, priority: AlertPriority) => void
+    setAlertProperties: (alertId: string, properties: AlertMetaData) => void
+    resolveAlert: (alertId: string) => void
+    ackAlert: (alertId: string) => void
+    unackAlert: (alertId: string) => void
+    silenceAlert: (alertId: string) => boolean
+    removeAlert: (alertId: string) => void
+    getAlert: (alertId: string) => AlertValue
+  }
+
   /**
    * A plugin can report that it has handled output messages. This will
    * update the output message rate and icon in the Dashboard.