grm-shared-library 1.1.243 → 1.1.245

package/dist/types/modules/incident/intefaces/incident-dashboard-analytics.d.ts

@@ -0,0 +1,297 @@
+/**
+ * The incident analytics of the admin's Dashboard: the incidents (or grievances) raised
+ * over a period, where they stand now, how quickly they were answered and resolved, what
+ * kind they were, when and where they happened - computed by clarion-incident, with the
+ * county of each place from clarion-gis.
+ *
+ * Incidents belong to the period they were RAISED in and are shown as they stand now.
+ * "Open now" is every open incident in scope, whatever the period. Durations come from
+ * each incident's timeline (its actions). Geography follows GIS practice: places are
+ * aggregated - to counties (a choropleth, normalised by area) and to an equal-area
+ * hexagonal grid (density, and Getis-Ord Gi* hot spots) - and an incident's own position
+ * is never returned. Counts, rates and durations only - never a reporter, a description
+ * or an address.
+ */
+/** How the period is cut into points. Chosen by the service from the length of the period. */
+export type IncidentAnalyticsBucket = 'hour' | 'day' | 'week' | 'month';
+export interface IncidentAnalyticsRange {
+    /** Inclusive, ISO 8601. For "forever", the first incident in scope. */
+    from: string;
+    /** Exclusive, ISO 8601. */
+    to: string;
+    bucket: IncidentAnalyticsBucket;
+    /** IANA time zone the buckets and the hour-of-week grid are cut in. */
+    timeZone: string;
+}
+/** Whose incidents, as the service decided from the caller. */
+export interface IncidentAnalyticsScope {
+    /** Null: every organization (a Super-Admin's platform view). */
+    organizationId: number | null;
+    /** Null: every control centre of the organization. */
+    controlCentreId: number | null;
+    platform: boolean;
+}
+/** The filters applied, as the service understood them; null when not filtered on. */
+export interface IncidentAnalyticsFilters {
+    incidentClass: string | null;
+    priority: string | null;
+    emergencyType: string | null;
+    channel: string | null;
+    typeId: number | null;
+    categoryId: number | null;
+}
+/** A count by a key, largest first unless the section says otherwise. */
+export interface IncidentAnalyticsCount<K extends string = string> {
+    key: K;
+    count: number;
+}
+/** Median and 90th percentile of one duration, in seconds; null when nothing was measured. */
+export interface IncidentAnalyticsDuration {
+    samples: number;
+    medianSeconds: number | null;
+    p90Seconds: number | null;
+}
+/** The incidents raised in the period, as they stand now. */
+export interface IncidentAnalyticsTotals {
+    raised: number;
+    /** The previous period of the same length; null for "forever". */
+    previousRaised: number | null;
+    /** Raised as an emergency or a panic alert (SOS). */
+    emergencies: number;
+    /** Answered: an action by anybody but the reporter (a status change, an assignment, an edit, a dispatch). */
+    responded: number;
+    /** Reached Resolved or Closed, at any time since. */
+    resolved: number;
+    closed: number;
+    /** Ended Unresolved. */
+    unresolved: number;
+    /** Still open now: Received, In-Progress, In-Review, On-Hold, Escalated or Appealed. */
+    stillOpen: number;
+    /** Escalated, appealed, put on hold or reopened (back to work after being resolved or closed) at least once. */
+    escalated: number;
+    appealed: number;
+    heldOnHold: number;
+    reopened: number;
+    /** With somebody assigned now. */
+    assigned: number;
+    anonymous: number;
+    sensitive: number;
+    /** resolved / raised, as a percentage; and the same for the previous period (null for "forever"). */
+    resolutionRate: number | null;
+    previousResolutionRate: number | null;
+}
+/** Every open incident in scope NOW, whenever it was raised. */
+export interface IncidentAnalyticsOpenNow {
+    open: number;
+    unassigned: number;
+    byStatus: IncidentAnalyticsCount[];
+    byPriority: IncidentAnalyticsCount[];
+    /** How long they have been open: UNDER_1H, 1H_4H, 4H_24H, 1D_3D, 3D_7D, 7D_30D, OVER_30D - every band, in that order. */
+    ageBands: IncidentAnalyticsCount[];
+    /** When the oldest one was raised; null with none open. */
+    oldestRaisedAt: string | null;
+}
+export interface IncidentAnalyticsTimes {
+    /** From raised to the first action by anybody but the reporter. */
+    toFirstResponse: IncidentAnalyticsDuration;
+    /** From raised to somebody being assigned. */
+    toAssignment: IncidentAnalyticsDuration;
+    /** From raised to Resolved or Closed, whichever came first. */
+    toResolution: IncidentAnalyticsDuration;
+    /** From raised to Closed. */
+    toClosure: IncidentAnalyticsDuration;
+    /** The previous period's medians, for the change; null for "forever" or nothing measured. */
+    previousMedianSecondsToFirstResponse: number | null;
+    previousMedianSecondsToResolution: number | null;
+    /** How long the resolved ones took, in the same bands as `IncidentAnalyticsOpenNow.ageBands`. */
+    resolutionBands: IncidentAnalyticsCount[];
+}
+export interface IncidentAnalyticsBreakdowns {
+    /** Every status, in the order an incident lives through them, zero counts included. */
+    byStatus: IncidentAnalyticsCount[];
+    /** Critical, High, Medium, Low - every priority, in that order. */
+    byPriority: IncidentAnalyticsCount[];
+    /** emergency, panic, non-emergency. */
+    byEmergencyType: IncidentAnalyticsCount[];
+    /** How it reached the platform: App, Web, Phone, Chat... */
+    byChannel: IncidentAnalyticsCount[];
+    /** What raised it: MANUAL (a person), SAFETY_CHECK, FOLLOW_ME. */
+    byOrigin: IncidentAnalyticsCount[];
+    /** Incident or Grievance. */
+    byClass: IncidentAnalyticsCount[];
+    /** The reporter's entitlement when raised: PREMIUM, TRIAL, FREE, NOT_APPLICABLE. */
+    byEntitlementTier: IncidentAnalyticsCount[];
+    /** Whether it was sent to the control room (REACHED) or kept from it (NOT_SENT: a free user, or opted out). */
+    byControlRoom: IncidentAnalyticsCount[];
+    /** Third-party partner routing: NOT_ROUTED, ROUTED, ... */
+    byPartnerRouting: IncidentAnalyticsCount[];
+}
+export interface IncidentAnalyticsTimelinePoint {
+    /** Start of the bucket, ISO 8601. */
+    at: string;
+    raised: number;
+    emergencies: number;
+    /** Of those raised in the bucket: resolved since, and still open now. */
+    resolved: number;
+    open: number;
+    medianSecondsToFirstResponse: number | null;
+}
+export interface IncidentAnalyticsHourOfWeek {
+    /** 0 = Monday ... 6 = Sunday, in the period's time zone. */
+    day: number;
+    hour: number;
+    raised: number;
+}
+export interface IncidentAnalyticsTypeRow {
+    /** Null: raised without a type. */
+    typeId: number | null;
+    name: string;
+    categoryId: number | null;
+    categoryName: string | null;
+    raised: number;
+    previousRaised: number | null;
+    emergencies: number;
+    resolved: number;
+    resolutionRate: number | null;
+    medianSecondsToFirstResponse: number | null;
+    medianSecondsToResolution: number | null;
+}
+export interface IncidentAnalyticsCategoryRow {
+    categoryId: number | null;
+    name: string;
+    raised: number;
+    resolved: number;
+    resolutionRate: number | null;
+    medianSecondsToResolution: number | null;
+}
+/** A control centre in scope (named by the admin from its own list). */
+export interface IncidentAnalyticsControlCentreRow {
+    controlCentreId: number;
+    organizationId: number;
+    raised: number;
+    /** Open now, whenever raised. */
+    open: number;
+    resolved: number;
+    resolutionRate: number | null;
+    escalated: number;
+    medianSecondsToFirstResponse: number | null;
+    medianSecondsToResolution: number | null;
+}
+/** Platform view only: one row per organization. */
+export interface IncidentAnalyticsOrganizationRow {
+    organizationId: number;
+    raised: number;
+    previousRaised: number | null;
+    emergencies: number;
+    open: number;
+    resolutionRate: number | null;
+    medianSecondsToFirstResponse: number | null;
+}
+/** How many of the period's incidents could be placed. */
+export interface IncidentAnalyticsGeoQuality {
+    raised: number;
+    /** With a usable position. */
+    located: number;
+    withoutLocation: number;
+    /** Located, but in no county of the boundary data (another country, the sea, a test device). */
+    outsideMappedArea: number;
+    /** False when clarion-gis could not be asked: no county figures this time. */
+    countiesAvailable: boolean;
+}
+/** One county: the period's incidents in it, normalised by its area. */
+export interface IncidentAnalyticsCountyRow {
+    code: number;
+    name: string;
+    countryIso: string;
+    areaKm2: number;
+    incidents: number;
+    /** Null for "forever". */
+    previousIncidents: number | null;
+    /** Of the located incidents in mapped counties, as a percentage. */
+    share: number | null;
+    /** Incidents per 1,000 km² - what a choropleth should show: raw counts favour big counties. */
+    perThousandKm2: number;
+    emergencies: number;
+    resolved: number;
+    medianSecondsToFirstResponse: number | null;
+}
+/** Statistical significance of a hexagon's clustering (Getis-Ord Gi*). */
+export interface IncidentAnalyticsGiStar {
+    /** The Gi* z-score: high and positive, more incidents around here than chance would put. */
+    z: number;
+    /** Two-tailed p-value. */
+    p: number;
+    /** Hot spot at this confidence after the false-discovery-rate correction: 99, 95, 90 - or 0, not significant. */
+    confidence: 0 | 90 | 95 | 99;
+}
+/** One hexagon of the equal-area grid with incidents in it. */
+export interface IncidentAnalyticsHexCell {
+    /** Axial grid coordinates, "q:r". */
+    id: string;
+    centre: {
+        lat: number;
+        lng: number;
+    };
+    /** The six corners, [lat, lng], for drawing it. */
+    vertices: Array<[number, number]>;
+    incidents: number;
+    emergencies: number;
+    /** Null when hot spots were not computed (too few incidents). */
+    gi: IncidentAnalyticsGiStar | null;
+}
+/** How the hot-spot analysis was run, and what it found. */
+export interface IncidentAnalyticsHotSpots {
+    /** Whether it ran; it needs at least `minimumIncidents` placed incidents. */
+    available: boolean;
+    /** Why not, when it did not. */
+    reason: string | null;
+    method: 'Getis-Ord Gi*';
+    /** Each hexagon with its six neighbours (first-order contiguity, the hexagon itself included). */
+    neighbourhood: string;
+    /** Benjamini-Hochberg false-discovery-rate correction across the hexagons tested. */
+    fdrCorrected: boolean;
+    minimumIncidents: number;
+    /** Hexagons in the study area (the incidents' convex hull, one ring wider), empty ones included. */
+    studyAreaCells: number;
+    hot99: number;
+    hot95: number;
+    hot90: number;
+}
+export interface IncidentAnalyticsGeography {
+    quality: IncidentAnalyticsGeoQuality;
+    /** Side of the hexagons, in km on the ground: chosen from the spread of the incidents, never under 1 km. */
+    hexSideKm: number | null;
+    /** The hexagons with incidents, most first; capped (see `hexesTruncated`). */
+    hexes: IncidentAnalyticsHexCell[];
+    hexesTruncated: boolean;
+    hotSpots: IncidentAnalyticsHotSpots;
+    /** Every county of the countries the incidents fall in, zero counts included, most incidents first. */
+    counties: IncidentAnalyticsCountyRow[];
+    /** The placed incidents' extent, for framing a map; null with none. */
+    bounds: {
+        south: number;
+        west: number;
+        north: number;
+        east: number;
+    } | null;
+}
+export interface IncidentDashboardAnalytics {
+    generatedAt: string;
+    range: IncidentAnalyticsRange;
+    scope: IncidentAnalyticsScope;
+    filters: IncidentAnalyticsFilters;
+    totals: IncidentAnalyticsTotals;
+    openNow: IncidentAnalyticsOpenNow;
+    times: IncidentAnalyticsTimes;
+    breakdowns: IncidentAnalyticsBreakdowns;
+    timeline: IncidentAnalyticsTimelinePoint[];
+    /** Raised by weekday and hour; only cells with incidents. */
+    hourOfWeek: IncidentAnalyticsHourOfWeek[];
+    /** The types raised, most first; capped at 50. */
+    types: IncidentAnalyticsTypeRow[];
+    categories: IncidentAnalyticsCategoryRow[];
+    controlCentres: IncidentAnalyticsControlCentreRow[];
+    /** Platform view only; null otherwise. */
+    byOrganization: IncidentAnalyticsOrganizationRow[] | null;
+    geography: IncidentAnalyticsGeography;
+}

package/dist/types/modules/organization/dtos/organization-analytics-query.dto.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The period an Organization analytics read covers (both halves: organizations and
+ * zones), and optionally one control centre. Both ends optional: no `from` is
+ * "forever", no `to` is now.
+ */
+export declare class OrganizationAnalyticsQueryDto {
+    from?: string;
+    to?: string;
+    timeZone?: string;
+    /** Super-Admin only: one organization's figures instead of every organization's. Ignored for anybody else. */
+    organizationId?: number;
+    /**
+     * One control centre's figures. Within the caller's own organization (a Super-Admin's
+     * pick of one); control-centre staff see their own centre whatever this says.
+     */
+    controlCentreId?: number;
+}

package/dist/types/modules/organization/index.d.ts

@@ -1,8 +1,10 @@
 export * from './dtos/create-organization.dto';
 export * from './dtos/update-organization.dto';
 export * from './dtos/organization-sla.dto';
+export * from './dtos/organization-analytics-query.dto';
 export * from './interfaces/organization';
 export * from './interfaces/organization-sla';
 export * from './interfaces/organization-created-event';
+export * from './interfaces/organization-analytics';
 export * from './enums/org-status.enum';
 export * from './enums/org-type.enum';

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

@@ -0,0 +1,189 @@
+/**
+ * Organization analytics, the organization half (the admin's Organization Analytics):
+ * the organizations, their control centres, the response units they have set up and
+ * what those can respond to, and the responders who crew them - computed by
+ * clarion-organization. The other half, the zones the control centres cover, is
+ * ZoneAnalytics (clarion-gis); both answer the same query.
+ *
+ * The structure - organizations, control centres, units, responders - is as it stands
+ * NOW. What the period adds: what was created in it, and the responders' duty in it.
+ * Counts, rates and durations only - never a phone number, an address, a person or a
+ * typed reason.
+ */
+/** How the period is cut into points. Chosen by the service from the length of the period. */
+export type OrganizationAnalyticsBucket = 'hour' | 'day' | 'week' | 'month';
+export interface OrganizationAnalyticsRange {
+    /** Inclusive, ISO 8601. For "forever", the start of the data in scope. */
+    from: string;
+    /** Exclusive, ISO 8601. */
+    to: string;
+    bucket: OrganizationAnalyticsBucket;
+    /** IANA time zone the buckets (and the hour-of-week grid) are cut in. */
+    timeZone: string;
+}
+/** Whose figures these are, as the service decided from the caller. */
+export interface OrganizationAnalyticsScope {
+    /** Null: every organization (a Super-Admin's platform view). */
+    organizationId: number | null;
+    /** Null: every control centre of the organization. */
+    controlCentreId: number | null;
+    platform: boolean;
+}
+/** A count by a key (a status, a type, a country), largest first unless the section says otherwise. */
+export interface OrganizationAnalyticsCount<K extends string = string> {
+    key: K;
+    count: number;
+}
+/** Median and 90th percentile of one duration, in seconds; null when nothing was measured. */
+export interface OrganizationAnalyticsDuration {
+    samples: number;
+    medianSeconds: number | null;
+    p90Seconds: number | null;
+}
+/** The organizations in scope: every one for the platform, otherwise the caller's own. */
+export interface OrganizationAnalyticsOrganizations {
+    total: number;
+    /** Created in the period, and in the previous period of the same length (null for "forever"). */
+    created: number;
+    previousCreated: number | null;
+    byStatus: OrganizationAnalyticsCount[];
+    /** ISO 3166-1 alpha-2. */
+    byCountry: OrganizationAnalyticsCount[];
+    /** The organization type it was registered with (Private, Public, ...). */
+    byType: OrganizationAnalyticsCount[];
+    /** The app (brand) it belongs to. */
+    byApp: OrganizationAnalyticsCount[];
+    /** Whether it handles incidents or grievances. */
+    byIncidentClass: OrganizationAnalyticsCount[];
+}
+export interface OrganizationAnalyticsControlCentres {
+    total: number;
+    active: number;
+    created: number;
+    previousCreated: number | null;
+    byStatus: OrganizationAnalyticsCount[];
+    /** Control centres with at least one unit in service, and with none. */
+    withUnits: number;
+    withoutUnits: number;
+    /** Control centres with at least one responder assigned to one of their units. */
+    withResponders: number;
+    /**
+     * For each capability (MEDICAL_RESPONSE, ...): the active control centres with no
+     * unit in service able to answer it. Every capability, zero counts included.
+     */
+    capabilityGaps: OrganizationAnalyticsCount[];
+}
+export interface OrganizationAnalyticsUnits {
+    total: number;
+    /** In service (`isActive`) and switched off. */
+    active: number;
+    inactive: number;
+    created: number;
+    previousCreated: number | null;
+    /** Vehicle, Person, Team. */
+    byType: OrganizationAnalyticsCount[];
+    /** What kind of each: the vehicle type (Ambulance, Security, ...), the person's category, or Team. */
+    byKind: OrganizationAnalyticsCount[];
+    /** As each was last set: a vehicle's status, a person's or a team's. */
+    byStatus: OrganizationAnalyticsCount[];
+    /**
+     * Units in service able to answer each capability - as configured on the unit, or
+     * as its type implies when nothing is configured. A unit can count under several.
+     * Every capability, zero counts included.
+     */
+    byCapability: OrganizationAnalyticsCount[];
+    /** Units whose capabilities were set on the unit rather than implied by its type. */
+    configuredCapabilities: number;
+    /** Units in service that answer nothing: none configured and none implied (a team, a volunteer). */
+    withoutCapability: number;
+}
+/** The responder app's people: who crews which unit, and their duty. */
+export interface OrganizationAnalyticsResponders {
+    /** Responder-to-unit assignments, the people behind them, and the units that have any. */
+    memberships: number;
+    responders: number;
+    unitsWithResponders: number;
+    /** Units in service with no responder assigned. */
+    unitsWithoutResponders: number;
+    /** On duty now: responders, and the units they are on duty with. */
+    onDutyNow: number;
+    unitsOnDutyNow: number;
+    /** Duty sessions started in the period, and in the previous period (null for "forever"). */
+    sessions: number;
+    previousSessions: number | null;
+    /** Different responders who were on duty at any time in the period. */
+    respondersOnDuty: number;
+    /** Hours on duty within the period, every session counted for the part of it inside the period. */
+    dutyHours: number;
+    /** Length of the sessions started in the period that have ended. */
+    sessionLength: OrganizationAnalyticsDuration;
+    /** Why the period's ended sessions ended. */
+    endReasons: OrganizationAnalyticsCount[];
+}
+export interface OrganizationAnalyticsTimelinePoint {
+    /** Start of the bucket, ISO 8601. */
+    at: string;
+    organizations: number;
+    controlCentres: number;
+    units: number;
+    /** Duty sessions started, and hours on duty within the bucket. */
+    dutySessions: number;
+    dutyHours: number;
+}
+export interface OrganizationAnalyticsHourOfWeek {
+    /** 0 = Monday ... 6 = Sunday, in the period's time zone. */
+    day: number;
+    hour: number;
+    /** Duty sessions started in that hour. */
+    sessions: number;
+}
+/** A control centre in scope, as it stands now, and its responders' duty in the period. */
+export interface OrganizationAnalyticsControlCentreRow {
+    controlCentreId: number;
+    organizationId: number;
+    name: string;
+    status: string;
+    createdAt: string;
+    units: number;
+    activeUnits: number;
+    responders: number;
+    onDutyNow: number;
+    dutyHours: number;
+    /** The capabilities its units in service can answer between them. */
+    capabilities: string[];
+}
+/** An organization in scope (the platform's every one, otherwise the caller's own). */
+export interface OrganizationAnalyticsOrganizationRow {
+    organizationId: number;
+    name: string;
+    countryCode: string | null;
+    type: string | null;
+    appId: string | null;
+    incidentClass: string | null;
+    status: string;
+    createdAt: string;
+    controlCentres: number;
+    activeControlCentres: number;
+    units: number;
+    activeUnits: number;
+    responders: number;
+    onDutyNow: number;
+    dutyHours: number;
+}
+export interface OrganizationAnalytics {
+    generatedAt: string;
+    range: OrganizationAnalyticsRange;
+    scope: OrganizationAnalyticsScope;
+    organizations: OrganizationAnalyticsOrganizations;
+    controlCentres: OrganizationAnalyticsControlCentres;
+    units: OrganizationAnalyticsUnits;
+    responders: OrganizationAnalyticsResponders;
+    timeline: OrganizationAnalyticsTimelinePoint[];
+    /** Duty sessions started, by weekday and hour; only cells with sessions. */
+    dutyHourOfWeek: OrganizationAnalyticsHourOfWeek[];
+    /** The control centres in scope, most units first; capped (see `controlCentreRowsTruncated`). */
+    controlCentreRows: OrganizationAnalyticsControlCentreRow[];
+    controlCentreRowsTruncated: boolean;
+    /** The organizations in scope: one row for an organization's own staff. */
+    organizationRows: OrganizationAnalyticsOrganizationRow[];
+}

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

@@ -3,6 +3,7 @@ export declare enum PermissionActions {
     READ_ORGANIZATION = "read:organization",
     UPDATE_ORGANIZATION = "update:organization",
     DELETE_ORGANIZATION = "delete:organization",
+    READ_ORGANIZATION_ANALYTICS = "read:organization-analytics",
     CREATE_PARTNER = "create:partner",
     READ_PARTNER = "read:partner",
     UPDATE_PARTNER = "update:partner",
@@ -74,6 +75,7 @@ export declare enum PermissionActions {
     READ_INCIDENT = "read:incident",
     UPDATE_INCIDENT = "update:incident",
     DELETE_INCIDENT = "delete:incident",
+    READ_INCIDENT_ANALYTICS = "read:incident-analytics",
     READ_CHAT_ANALYTICS = "read:chat-analytics",
     CREATE_INCIDENT_CATEGORY_TYPE = "create:incident-category-type",
     READ_INCIDENT_CATEGORY_TYPE = "read:incident-category-type",

package/package.json

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