grm-shared-library 1.1.235 → 1.1.237

package/dist/types/modules/notification/interfaces/notification-analytics.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Notification analytics (the admin's Notification Analytics): what Clarion sent people
+ * over a period, on every channel - push to the app, the console's in-app notifications,
+ * SMS and email - whether it got through, whether it was opened, and how many people a
+ * push can reach at all.
+ *
+ * One read, computed by clarion-notification from one consistent snapshot, with who each
+ * recipient is from clarion-authentication. Counts, rates and durations only: never a
+ * title, a message, a phone number or an address.
+ *
+ * DURATIONS ARE IN SECONDS, like every analytics contract.
+ *
+ * How it is counted:
+ *  - Everything by when it was CREATED - the moment Clarion decided to tell somebody.
+ *  - Whose it is: the organization recorded on it; for a push, the organization of the
+ *    post it announces, then the recipient's; for an SMS, the recipient's. Older SMS and
+ *    email (before 21 September 2026) recorded no organization and often no recipient:
+ *    those are counted only in the platform view (`unattributed`).
+ *  - Got through: accepted by the provider - Firebase for a push, the SMS gateway, the
+ *    mail service - or, in the console, delivered. Nothing reports whether an SMS or an
+ *    email was read, so only push (tapped) and in-app (read) have an open rate.
+ *  - A country narrows push, in-app and devices by the recipient's country and SMS by
+ *    the number's; email has no country and is never narrowed.
+ */
+/** How the period is cut into points for the charts. Chosen by the service from the length of the period. */
+export type NotificationAnalyticsBucket = 'hour' | 'day' | 'week' | 'month';
+/** The four ways Clarion tells somebody something. */
+export type NotificationAnalyticsChannel = 'PUSH' | 'IN_APP' | 'SMS' | 'EMAIL';
+export interface NotificationAnalyticsRange {
+    /** Inclusive, ISO 8601. The first notification when the period asked for was "forever". */
+    from: string;
+    /** Exclusive, ISO 8601. */
+    to: string;
+    bucket: NotificationAnalyticsBucket;
+    /** IANA time zone the buckets and the hour-of-week grid are cut in. */
+    timeZone: string;
+}
+/** A count by a key (a kind, a provider, a reason), largest first unless the section says otherwise. */
+export interface NotificationAnalyticsCount<K extends string = string> {
+    key: K;
+    count: number;
+}
+/** Median and 90th percentile of one duration, in seconds; null when nothing was measured. */
+export interface NotificationAnalyticsDuration {
+    median: number | null;
+    p90: number | null;
+    /** How many were measured. */
+    count: number;
+}
+/** One channel over the period. */
+export interface NotificationAnalyticsChannelRow {
+    channel: NotificationAnalyticsChannel;
+    /** Created in the period. */
+    total: number;
+    /** Got through: accepted by the provider, or delivered to the console. */
+    succeeded: number;
+    failed: number;
+    /** No outcome yet: waiting, or cancelled before it was sent. */
+    pending: number;
+    /** succeeded / (succeeded + failed), as a percentage. */
+    successRate: number | null;
+    /** Push tapped, in-app read; null for SMS and email - nothing reports it. */
+    opened: number | null;
+    /** opened / succeeded, as a percentage. */
+    openRate: number | null;
+}
+/** One kind of push - what it announced - and how it went. */
+export interface NotificationAnalyticsPushKindRow {
+    /** The event it announced (NEWSFEED_POST_PUBLISHED, GUARDIAN_INCIDENT_ALERT...), else its category (INCIDENT, ALERT...). */
+    kind: string;
+    total: number;
+    failed: number;
+    opened: number;
+    /** opened / those that got through, as a percentage. */
+    openRate: number | null;
+    medianSecondsToOpen: number | null;
+}
+/** Push notifications to the app. */
+export interface NotificationAnalyticsPush {
+    /** One per device: a notification to somebody with two phones is two. */
+    total: number;
+    succeeded: number;
+    failed: number;
+    pending: number;
+    opened: number;
+    successRate: number | null;
+    openRate: number | null;
+    /** Different people pushed to. */
+    recipients: number;
+    /** Notifications as Clarion decided them, each fanned out to its recipients' devices. */
+    sends: number;
+    /** Created to accepted by Firebase - seconds, with decimals. */
+    toSend: NotificationAnalyticsDuration;
+    /** Created to tapped. */
+    toOpen: NotificationAnalyticsDuration;
+    byKind: NotificationAnalyticsPushKindRow[];
+    /** Critical, High, Normal, Low - in that order, zeros included. */
+    byPriority: NotificationAnalyticsCount[];
+    /** The Android channel it rang on (urgent, incidents...); DEFAULT when none. */
+    byChannel: NotificationAnalyticsCount[];
+    /** Why pushes failed, as the provider said it - ids, numbers and addresses masked. The eight commonest. */
+    failureReasons: NotificationAnalyticsCount[];
+}
+/** The phones and browsers a push can reach - NOW, whatever the period, apart from `registered`. */
+export interface NotificationAnalyticsDevices {
+    activeNow: number;
+    /** Switched off: signed out, replaced by a newer registration, or refused by the provider. */
+    inactiveNow: number;
+    /** People with at least one active device: who a push can reach. */
+    reachableNow: number;
+    /** Registered in the period. */
+    registered: number;
+    /** Active devices by kind (android, ios, web). */
+    byType: NotificationAnalyticsCount[];
+    /** Active devices by app version; NONE when not recorded. */
+    byAppVersion: NotificationAnalyticsCount[];
+    byLanguage: NotificationAnalyticsCount[];
+}
+/** The console's own notifications, to the staff using it. */
+export interface NotificationAnalyticsInApp {
+    total: number;
+    succeeded: number;
+    failed: number;
+    pending: number;
+    read: number;
+    /** read / total, as a percentage. */
+    readRate: number | null;
+    /** Different people notified. */
+    recipients: number;
+    /** INCIDENT, ALERT, MESSAGE... */
+    byType: NotificationAnalyticsCount[];
+    /** What happened (Created, Auto-Stopped, CHAT_MESSAGE...). */
+    byAction: NotificationAnalyticsCount[];
+    /** NOW: notifications nobody has read yet, whenever created. */
+    unreadNow: number;
+}
+/** Cost recorded on SMS, per currency. */
+export interface NotificationAnalyticsSmsCost {
+    currency: string;
+    amount: number;
+    /** Messages with a cost recorded. */
+    messages: number;
+}
+/** SMS. */
+export interface NotificationAnalyticsSms {
+    total: number;
+    succeeded: number;
+    failed: number;
+    pending: number;
+    successRate: number | null;
+    /** Created to accepted by the gateway. */
+    toSend: NotificationAnalyticsDuration;
+    /** What it was for: otp:verify_phone, otp:reset_password, guardian_incident_notification...; NOT_RECORDED for the oldest. */
+    byPurpose: NotificationAnalyticsCount[];
+    /** The gateway that took it (uwazii, twilio, africastalking); NOT_RECORDED for the oldest. */
+    byProvider: NotificationAnalyticsCount[];
+    /** Whose sender ID it went out under (PLATFORM_DEFAULT, ORGANIZATION); NOT_RECORDED for the oldest. */
+    bySenderSource: NotificationAnalyticsCount[];
+    /** The number's country; UNKNOWN when not recorded. */
+    byCountry: NotificationAnalyticsCount[];
+    /** Why messages failed - ids, numbers and addresses masked. The eight commonest. */
+    failureReasons: NotificationAnalyticsCount[];
+    cost: NotificationAnalyticsSmsCost[];
+}
+/** Email. */
+export interface NotificationAnalyticsEmail {
+    total: number;
+    succeeded: number;
+    failed: number;
+    successRate: number | null;
+    /** Verification, Password Reset, Notification, Acknowledgement... */
+    byType: NotificationAnalyticsCount[];
+    /** The mail service that took it; NOT_RECORDED for the oldest. */
+    byProvider: NotificationAnalyticsCount[];
+    bySenderSource: NotificationAnalyticsCount[];
+}
+/** One point on the charts: a bucket of the period. */
+export interface NotificationAnalyticsPoint {
+    /** Local wall-clock start of the bucket, in `range.timeZone` (no offset). */
+    bucket: string;
+    push: number;
+    pushFailed: number;
+    /** Of the pushes created in the bucket, those tapped (whenever). */
+    pushOpened: number;
+    inApp: number;
+    inAppRead: number;
+    sms: number;
+    smsFailed: number;
+    email: number;
+    emailFailed: number;
+}
+/** One hour of the week. Weekday 1 is Monday. */
+export interface NotificationAnalyticsHeatCell {
+    weekday: number;
+    hour: number;
+    /** Notifications created in it, every channel. */
+    sent: number;
+    /** Pushes tapped in it - when people look. */
+    opened: number;
+}
+/** The previous period of the same length, for the change on each headline figure. */
+export interface NotificationAnalyticsPrevious {
+    from: string;
+    to: string;
+    total: number;
+    push: number;
+    pushFailed: number;
+    pushOpened: number;
+    pushOpenRate: number | null;
+    pushSuccessRate: number | null;
+    inApp: number;
+    inAppRead: number;
+    sms: number;
+    smsFailed: number;
+    smsSuccessRate: number | null;
+    email: number;
+    emailFailed: number;
+    devicesRegistered: number;
+}
+/** A Super-Admin's view of every organization: one row each, busiest first. */
+export interface NotificationAnalyticsOrganizationRow {
+    organizationId: number;
+    total: number;
+    push: number;
+    pushFailed: number;
+    pushOpenRate: number | null;
+    inApp: number;
+    inAppReadRate: number | null;
+    sms: number;
+    smsFailed: number;
+    email: number;
+    /** NOW. */
+    activeDevices: number;
+}
+/** Notifications of the period no organization could be found for - the platform view only. */
+export interface NotificationAnalyticsUnattributed {
+    push: number;
+    sms: number;
+    email: number;
+}
+export interface NotificationAnalytics {
+    /** Whose figures: one organization, or null for every organization. */
+    organizationId: number | null;
+    /** The one country the figures are narrowed to, or null for every country. */
+    countryCode: string | null;
+    range: NotificationAnalyticsRange;
+    generatedAt: string;
+    previous: NotificationAnalyticsPrevious | null;
+    /** Countries with notifications or devices in scope, whatever country is chosen - for narrowing to one. */
+    countryOptions: NotificationAnalyticsCount[];
+    /** PUSH, IN_APP, SMS, EMAIL - in that order. */
+    channels: NotificationAnalyticsChannelRow[];
+    push: NotificationAnalyticsPush;
+    devices: NotificationAnalyticsDevices;
+    inApp: NotificationAnalyticsInApp;
+    sms: NotificationAnalyticsSms;
+    email: NotificationAnalyticsEmail;
+    timeline: NotificationAnalyticsPoint[];
+    /** All 168 hours of the week, Monday first, zeros included. */
+    heatmap: NotificationAnalyticsHeatCell[];
+    /** A Super-Admin looking at every organization only. */
+    byOrganization?: NotificationAnalyticsOrganizationRow[];
+    /** A Super-Admin looking at every organization only. */
+    unattributed?: NotificationAnalyticsUnattributed;
+}
+/** What a dashboard asks: the period, one country - and, for a Super-Admin, whose figures. */
+export interface NotificationAnalyticsQuery {
+    from?: string;
+    to?: string;
+    timeZone?: string;
+    organizationId?: number;
+    countryCode?: string;
+}

package/dist/types/modules/permission/enums/permission-actions.enum.d.ts

@@ -95,6 +95,9 @@ export declare enum PermissionActions {
     READ_TRACKING_HISTORY = "read:tracking-history",
     READ_TRACKING_OPERATIONS = "read:tracking-operations",
     MANAGE_TRACKING_OPERATIONS = "manage:tracking-operations",
+    READ_RESPONSE_UNIT_DISPATCH = "read:response-unit-dispatch",
+    CREATE_RESPONSE_UNIT_DISPATCH = "create:response-unit-dispatch",
+    UPDATE_RESPONSE_UNIT_DISPATCH = "update:response-unit-dispatch",
     CREATE_BENEFICIARY = "create:beneficiary",
     READ_BENEFICIARY = "read:beneficiary",
     UPDATE_BENEFICIARY = "update:beneficiary",
@@ -165,6 +168,7 @@ export declare enum PermissionActions {
     MODERATE_NEWSFEED_COMMENT = "moderate:newsfeed-comment",
     READ_NEWSFEED_ANALYTICS = "read:newsfeed-analytics",
     READ_NOTIFICATION_BRANDING = "read:notification-branding",
+    READ_NOTIFICATION_ANALYTICS = "read:notification-analytics",
     UPDATE_NOTIFICATION_BRANDING = "update:notification-branding",
     CREATE_NOTIFICATION_EMAIL_SENDER = "create:notification-email-sender",
     READ_NOTIFICATION_EMAIL_SENDER = "read:notification-email-sender",

package/dist/types/modules/permission/enums/permissions-module.enum.d.ts

@@ -8,6 +8,7 @@ export declare enum PermissionsModule {
     INCIDENT = "Grievance",
     RESPONSE_UNIT = "Response Unit",
     TRACKING = "Tracking",
+    RESPONSE_UNIT_DISPATCH = "Response Unit Dispatch",
     BILLING = "Billing",
     NEWSFEED = "Newsfeed",
     SUPPORT = "Support",

package/dist/types/modules/response-unit/dtos/response-unit/base-response-unit.dto.d.ts

@@ -1,4 +1,5 @@
 import { ResponseUnitType } from "../../enums/response-unit/response-unit-type.enum";
+import { ResponseCapability } from "../../enums/response-unit/response-capability.enum";
 import { MapLocationDto } from "../../../common";
 import { StationDto } from "./station.dto";
 export declare class BaseResponseUnitDto {
@@ -9,6 +10,12 @@ export declare class BaseResponseUnitDto {
     isActive: boolean;
     location: MapLocationDto;
     station: StationDto;
+    /**
+     * What this unit can respond to. Optional: empty means "whatever the unit's
+     * type implies" (an ambulance is MEDICAL_RESPONSE), so a unit only needs
+     * this when it differs from its type - see effectiveResponseCapabilities.
+     */
+    capabilities?: ResponseCapability[];
     controlCentreId: number;
     organizationId: number;
     createdAt?: Date;

package/dist/types/modules/response-unit/enums/response-unit/response-capability.enum.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What kind of emergency a response unit can answer.
+ *
+ * Deliberately the platform's existing vocabulary and nothing more: each value
+ * is what one {@link VehicleUnitType} already says about a vehicle (Ambulance,
+ * Security, Fire, Road Rescue), named the way {@link PartnerServiceCapability}
+ * names the same services for third-party responders. A unit with no explicit
+ * capabilities gets these derived from its vehicle type (or a person unit from
+ * its category) - see `deriveResponseCapabilities` - so every existing unit is
+ * classified on day one without anybody configuring anything.
+ *
+ * Stored as plain strings (varchar[]) wherever it is persisted, so adding a
+ * value here never needs a database migration.
+ */
+export declare enum ResponseCapability {
+    /** Ambulances and medical officers. */
+    MEDICAL_RESPONSE = "MEDICAL_RESPONSE",
+    /** Security response vehicles, patrols and police officers. */
+    SECURITY_RESPONSE = "SECURITY_RESPONSE",
+    /** Fire and rescue appliances. */
+    FIRE_RESPONSE = "FIRE_RESPONSE",
+    /** Breakdown, recovery and towing. */
+    ROADSIDE_ASSISTANCE = "ROADSIDE_ASSISTANCE"
+}

package/dist/types/modules/response-unit/enums/response-unit/response-unit-availability.enum.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Can this unit be sent to an incident right now?
+ *
+ * Two sources decide it and neither is enough alone:
+ *
+ *  - clarion-organization's MANUAL statuses (`isActive`, `vehicleStatus`,
+ *    `personStatus`, `teamStatus`) - what somebody set on the unit. Read by
+ *    `resolveResponseUnitAvailability`.
+ *  - clarion-incident's ACTIVE DISPATCHES - the authoritative record of a unit
+ *    being out on a job. A unit with one is ENGAGED whatever its manual status
+ *    says, and that is enforced by a unique index, not by this enum.
+ */
+export declare enum ResponseUnitAvailability {
+    /** On duty / operational, enabled, and not out on a job. */
+    AVAILABLE = "AVAILABLE",
+    /** Out on a job: an active dispatch, or a manual Engaged / On Mission status. */
+    ENGAGED = "ENGAGED",
+    /** Enabled but not able to respond: non-operational, off duty, on leave, training. */
+    UNAVAILABLE = "UNAVAILABLE",
+    /** Switched off in the organization (`isActive = false`). */
+    INACTIVE = "INACTIVE"
+}

package/dist/types/modules/response-unit/index.d.ts

@@ -65,3 +65,7 @@ export * from './enums/vehicle-unit/vehicle-type/fire-vehicle-type.enum';
 export * from './enums/vehicle-unit/vehicle-crew/fire-vehicle-role.enum';
 export * from './enums/vehicle-unit/vehicle-type/road-rescue-vehicle-type.enum';
 export * from './enums/vehicle-unit/vehicle-crew/road-rescue-vehicle-role.enum';
+export * from './enums/response-unit/response-capability.enum';
+export * from './enums/response-unit/response-unit-availability.enum';
+export * from './utils/response-capability.util';
+export * from './utils/response-unit-availability.util';

package/dist/types/modules/response-unit/interfaces/response-unit/response-unit.d.ts

@@ -1,5 +1,6 @@
 import { MapAddressDto, MapLocation } from "../../../common";
 import { ResponseUnitType } from "../../enums/response-unit/response-unit-type.enum";
+import { ResponseCapability } from "../../enums/response-unit/response-capability.enum";
 export interface ResponseUnit {
     id: number;
     name: string;
@@ -11,6 +12,8 @@ export interface ResponseUnit {
         name: string;
         address: MapAddressDto;
     };
+    /** Configured capabilities; empty means "derived from the unit's type". */
+    capabilities?: ResponseCapability[];
     controlCentreId: number;
     organizationId: number;
     createdAt?: Date;

package/dist/types/modules/response-unit/utils/response-capability.util.d.ts

@@ -0,0 +1,31 @@
+import { ResponseCapability } from '../enums/response-unit/response-capability.enum';
+/** The most capabilities one unit or one incident type may carry. */
+export declare const MAX_RESPONSE_CAPABILITIES = 10;
+/**
+ * Keep only known capabilities, once each, in a stable order.
+ *
+ * Accepts anything because it reads values back from jsonb, varchar[] and
+ * request bodies alike; an unknown value is dropped rather than thrown, so a
+ * capability retired from the enum can never make a stored unit unreadable.
+ */
+export declare function normalizeResponseCapabilities(values: unknown): ResponseCapability[];
+/** The parts of a response unit that say what it is. */
+export interface ResponseCapabilitySource {
+    /** Configured on the unit. When non-empty it is the whole answer. */
+    capabilities?: unknown;
+    vehicleType?: string | null;
+    /** A person unit's category. */
+    category?: string | null;
+}
+/**
+ * What a unit's TYPE says it can do - ignoring anything configured on it.
+ * Empty when the type says nothing (a team, a volunteer).
+ */
+export declare function deriveResponseCapabilities(source: ResponseCapabilitySource): ResponseCapability[];
+/**
+ * The capabilities a unit is treated as having: what was configured on it when
+ * anything was, otherwise what its type implies. Configured capabilities
+ * REPLACE the derived ones rather than adding to them - an ambulance that has
+ * been re-equipped as a patient-transport-only vehicle must be able to say so.
+ */
+export declare function effectiveResponseCapabilities(source: ResponseCapabilitySource): ResponseCapability[];

package/dist/types/modules/response-unit/utils/response-unit-availability.util.d.ts

@@ -0,0 +1,21 @@
+import { ResponseUnitAvailability } from '../enums/response-unit/response-unit-availability.enum';
+/** The manual status fields of a response unit, whichever subtype it is. */
+export interface ResponseUnitStatusSource {
+    isActive?: boolean | null;
+    vehicleStatus?: string | null;
+    personStatus?: string | null;
+    teamStatus?: string | null;
+}
+/**
+ * Availability from the unit's own MANUAL status - not from dispatches, which
+ * clarion-incident layers on top (a unit with an active dispatch is ENGAGED
+ * whatever this returns).
+ *
+ * A missing status is AVAILABLE: a person unit's `personStatus` is nullable and
+ * every unit created before statuses existed has none, and refusing to dispatch
+ * a unit because nobody filled a field in would make the feature useless for
+ * the organizations that configured least.
+ */
+export declare function resolveResponseUnitAvailability(unit: ResponseUnitStatusSource): ResponseUnitAvailability;
+/** The unit's manual operational status as one string, whichever field holds it. */
+export declare function responseUnitOperationalStatus(unit: ResponseUnitStatusSource): string | null;

package/dist/types/modules/sms/enums/sms-template.enum.d.ts

@@ -10,6 +10,7 @@ export declare enum SmsTemplateType {
     SAFETY_CHECK_GUARDIAN_ENDED = "safety_check_guardian_ended",
     FOLLOW_ME_GUARDIAN_REQUEST = "follow_me_guardian_request",
     FOLLOW_ME_GUARDIAN_ENDED = "follow_me_guardian_ended",
+    RESPONSE_UNIT_DISPATCH = "response_unit_dispatch",
     APPOINTMENT_REMINDER = "appointment_reminder",
     GENERAL_NOTIFICATION = "general_notification"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grm-shared-library",
-  "version": "1.1.235",
+  "version": "1.1.237",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",