grm-shared-library 1.1.216 → 1.1.218

package/dist/esm/modules/role/enums/role.enum.js

@@ -18,6 +18,14 @@ export var Roles;
      * concerns, so this role is scoped there rather than to a control centre.
      */
     Roles["ORGANIZATION_SUPPORT_ADMIN"] = "Organization:Support-Admin";
+    /**
+     * Sets up and runs the organization's alert channels - the SMS short codes,
+     * WhatsApp numbers and mailboxes the public reaches it on without the app
+     * (clarion-alerts) - and works what arrives on them: the messages, the review
+     * queue of what screening held back, and the channels' analytics. Configuring
+     * a channel is an organization-level decision, so the role is scoped there.
+     */
+    Roles["ORGANIZATION_ALERT_CHANNELS_ADMIN"] = "Organization:Alert-Channels-Admin";
     Roles["CONTROL_CENTRE_ADMIN"] = "Control-Centre:Admin";
     Roles["CONTROL_CENTRE_USER"] = "Control-Centre:User";
     /** The same job, confined to one control centre. */

package/dist/esm/modules/role/enums/role.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"role.enum.js","sourceRoot":"","sources":["../../../../../src/modules/role/enums/role.enum.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,KAyBX;AAzBD,WAAY,KAAK;IACb,oCAA2B,CAAA;IAC3B,kDAAyC,CAAA;IACzC,kDAAyC,CAAA;IACzC,gDAAuC,CAAA;IACvC,kEAAyD,CAAA;IACzD,oEAA2D,CAAA;IAC3D,4EAAmE,CAAA;IACnE;;;OAGG;IACH,gFAAuE,CAAA;IACvE;;;;OAIG;IACH,kEAAyD,CAAA;IACzD,sDAA6C,CAAA;IAC7C,oDAA2C,CAAA;IAC3C,oDAAoD;IACpD,oFAA2E,CAAA;IAC3E,gCAAuB,CAAA;IACvB,oCAA2B,CAAA;AAC/B,CAAC,EAzBW,KAAK,KAAL,KAAK,QAyBhB;AAED;;;;;;;;;;;GAWG"}
+{"version":3,"file":"role.enum.js","sourceRoot":"","sources":["../../../../../src/modules/role/enums/role.enum.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,KAiCX;AAjCD,WAAY,KAAK;IACb,oCAA2B,CAAA;IAC3B,kDAAyC,CAAA;IACzC,kDAAyC,CAAA;IACzC,gDAAuC,CAAA;IACvC,kEAAyD,CAAA;IACzD,oEAA2D,CAAA;IAC3D,4EAAmE,CAAA;IACnE;;;OAGG;IACH,gFAAuE,CAAA;IACvE;;;;OAIG;IACH,kEAAyD,CAAA;IACzD;;;;;;OAMG;IACH,gFAAuE,CAAA;IACvE,sDAA6C,CAAA;IAC7C,oDAA2C,CAAA;IAC3C,oDAAoD;IACpD,oFAA2E,CAAA;IAC3E,gCAAuB,CAAA;IACvB,oCAA2B,CAAA;AAC/B,CAAC,EAjCW,KAAK,KAAL,KAAK,QAiChB;AAED;;;;;;;;;;;GAWG"}

package/dist/types/modules/alert-intake/dtos/alert-intake.dto.d.ts

@@ -63,6 +63,20 @@ export declare class ListAlertIntakeScreenedMessagesQueryDto {
     page?: number;
     limit?: number;
 }
+/**
+ * The period an analytics read covers. Both ends optional: no `from` is "forever" (from
+ * the first message), no `to` is now. The service chooses how finely to cut the period for
+ * the charts, and counts arrivals by weekday and hour in `timeZone` (default Africa/Nairobi).
+ */
+export declare class AlertIntakeAnalyticsQueryDto {
+    from?: string;
+    to?: string;
+    timeZone?: string;
+}
+/** Platform operators: every organization's analytics, or one organization's. */
+export declare class PlatformAlertIntakeAnalyticsQueryDto extends AlertIntakeAnalyticsQueryDto {
+    organizationId?: number;
+}
 /**
  * A reviewer's decision on one or more screened messages. ELEVATE raises each as an
  * incident (a grievance, for a grievance desk) without screening it again; DISMISS

package/dist/types/modules/alert-intake/index.d.ts

@@ -1,4 +1,5 @@
 export * from './enums/alert-intake.enum';
 export * from './interfaces/alert-intake';
+export * from './interfaces/alert-intake-analytics';
 export * from './dtos/alert-intake.dto';
 export * from './utils/alert-intake.util';

package/dist/types/modules/alert-intake/interfaces/alert-intake-analytics.d.ts

@@ -0,0 +1,241 @@
+import { AlertIntakeChannel, AlertIntakeMessageState, AlertIntakeScreeningReason, AlertIntakeScreeningSource, AlertIntakeScreeningStatus } from '../enums/alert-intake.enum';
+/**
+ * Alert intake analytics: what arrived on an organization's channels over a period, what
+ * became of it, what the AI made of it and what that cost. One read, computed by
+ * clarion-alerts from one consistent snapshot, so every number on a dashboard agrees with
+ * every other.
+ *
+ * Counts only: no message text, sender or credential is ever part of it.
+ */
+/** How the period is cut into points for the charts. Chosen by the service from the length of the period. */
+export type AlertIntakeAnalyticsBucket = 'hour' | 'day' | 'week' | 'month';
+/** The AI tasks whose calls are metered. */
+export type AlertIntakeAiTask = 'triage' | 'analysis' | 'transcription';
+export interface AlertIntakeAnalyticsRange {
+    /** Inclusive, ISO 8601. The first message received when the period asked for was "forever". */
+    from: string;
+    /** Exclusive, ISO 8601. */
+    to: string;
+    bucket: AlertIntakeAnalyticsBucket;
+    /** IANA time zone the buckets and the hour-of-week grid are cut in. */
+    timeZone: string;
+}
+/**
+ * The headline counts. Messages are counted by when they arrived.
+ *
+ * received = raised + screenedOut + duplicates + retrying + parked + queued: every message
+ * is in exactly one of those, as it stands now.
+ */
+export interface AlertIntakeAnalyticsTotals {
+    received: number;
+    /** Became incidents (grievances, for a grievance desk) - including screened messages a reviewer raised. */
+    raised: number;
+    /** Screened out as not a report and not raised since (waiting for review, or dismissed). */
+    screenedOut: number;
+    duplicates: number;
+    retrying: number;
+    parked: number;
+    /** Waiting for, or being worked on by, the pipeline. */
+    queued: number;
+    /** Distinct phone numbers, WhatsApp numbers and email addresses. Never the values themselves. */
+    uniqueSenders: number;
+    withAttachments: number;
+    sharedLocations: number;
+    /** Written in a language other than English, and translated. */
+    translated: number;
+    voiceNotes: number;
+    emergencies: number;
+    sensitive: number;
+    anonymous: number;
+    acknowledged: number;
+    acknowledgementFailed: number;
+    /** Median seconds from arrival to the incident being raised; null when nothing was raised. */
+    medianSecondsToIncident: number | null;
+    p90SecondsToIncident: number | null;
+    /** AI spend in the period, US dollars. */
+    aiCostUsd: number;
+}
+/** The previous period of the same length, for the change shown on each headline figure. Null for "forever". */
+export interface AlertIntakeAnalyticsComparison {
+    from: string;
+    to: string;
+    received: number;
+    raised: number;
+    screenedOut: number;
+    uniqueSenders: number;
+    medianSecondsToIncident: number | null;
+    aiCostUsd: number;
+}
+/** One point on the message timeline. `bucket` is the start of the point, local to `timeZone`, ISO 8601 without an offset. */
+export interface AlertIntakeAnalyticsTimelinePoint {
+    bucket: string;
+    received: number;
+    raised: number;
+    screenedOut: number;
+    duplicates: number;
+    failed: number;
+}
+/** Where messages stand now; the parts add up to `received`. `failed` is retrying and parked together. */
+export interface AlertIntakeAnalyticsOutcomes {
+    received: number;
+    raised: number;
+    screenedOut: number;
+    duplicates: number;
+    failed: number;
+    queued: number;
+}
+export interface AlertIntakeAnalyticsChannelRow extends AlertIntakeAnalyticsOutcomes {
+    channel: AlertIntakeChannel;
+    medianSecondsToIncident: number | null;
+}
+export interface AlertIntakeAnalyticsConnectionRow extends AlertIntakeAnalyticsOutcomes {
+    /** Null for messages received before connections existed. */
+    connectionId: string | null;
+    name: string;
+    channel: AlertIntakeChannel | null;
+    provider: string | null;
+    enabled: boolean | null;
+    lastReceivedAt: string | null;
+    /** The connection's current error, if it is failing. */
+    lastError: string | null;
+}
+export interface AlertIntakeAnalyticsCount<K extends string | number | null = string> {
+    key: K;
+    count: number;
+}
+/** Every screening decision on messages received in the period - including those a reviewer later raised. */
+export interface AlertIntakeAnalyticsScreening {
+    byReason: AlertIntakeAnalyticsCount<AlertIntakeScreeningReason>[];
+    byDecider: AlertIntakeAnalyticsCount<AlertIntakeScreeningSource>[];
+    byStatus: AlertIntakeAnalyticsCount<AlertIntakeScreeningStatus>[];
+    /** Mean confidence of the model's screening decisions (0-1); null without any. */
+    averageAiConfidence: number | null;
+    /** Median hours from being screened out to a person's decision; null without reviews. */
+    medianHoursToReview: number | null;
+    /** Screened messages still waiting for a person - now, whatever the period. */
+    awaitingReview: number;
+}
+export interface AlertIntakeAnalyticsLanguageRow {
+    /** ISO 639-1, or `und` when it could not be told. */
+    language: string;
+    count: number;
+    translated: number;
+}
+export interface AlertIntakeAnalyticsCategoryRow {
+    categoryId: number | null;
+    /** The organization's category name; "Uncategorised" for reports filed without one. */
+    name: string;
+    count: number;
+}
+export interface AlertIntakeAnalyticsLocations {
+    /** Reports placed on the map, by how: the sender's shared pin, or a place named in the message. */
+    shared: number;
+    geocoded: number;
+    unresolved: number;
+    byCountry: AlertIntakeAnalyticsCount[];
+}
+export interface AlertIntakeAnalyticsAttachments {
+    files: number;
+    attached: number;
+    failed: number;
+    /** `image`, `audio`, `video`, `document`. */
+    byKind: Array<{
+        kind: string;
+        files: number;
+        attached: number;
+        failed: number;
+    }>;
+}
+/** Arrivals by weekday (1 = Monday ... 7 = Sunday) and hour (0-23), in `timeZone`. All 168 cells, zeros included. */
+export interface AlertIntakeAnalyticsHeatCell {
+    weekday: number;
+    hour: number;
+    count: number;
+}
+export interface AlertIntakeAiTaskRow {
+    task: AlertIntakeAiTask;
+    calls: number;
+    failed: number;
+    cached: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    audioSeconds: number;
+    costUsd: number;
+    averageLatencyMs: number | null;
+    p90LatencyMs: number | null;
+}
+export interface AlertIntakeAiModelRow {
+    model: string;
+    task: AlertIntakeAiTask;
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    /** Calls whose model had no price in the service's price table: their cost is not in `costUsd`. */
+    unpricedCalls: number;
+}
+export interface AlertIntakeAiTimelinePoint {
+    bucket: string;
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+export interface AlertIntakeAnalyticsAi {
+    calls: number;
+    failed: number;
+    cached: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    audioSeconds: number;
+    costUsd: number;
+    /** AI spend divided by messages received / incidents raised in the period; null when there were none. */
+    costPerMessageUsd: number | null;
+    costPerIncidentUsd: number | null;
+    byTask: AlertIntakeAiTaskRow[];
+    byModel: AlertIntakeAiModelRow[];
+    timeline: AlertIntakeAiTimelinePoint[];
+    /** When the prices used were last reviewed (the service's price table), ISO date. */
+    pricesAsOf: string;
+}
+/** Platform view only: one row per organization. */
+export interface AlertIntakeAnalyticsOrganizationRow {
+    organizationId: number | null;
+    name: string;
+    received: number;
+    raised: number;
+    screenedOut: number;
+    aiCostUsd: number;
+}
+export interface AlertIntakeAnalytics {
+    /** Null for the platform view across every organization. */
+    organizationId: number | null;
+    range: AlertIntakeAnalyticsRange;
+    generatedAt: string;
+    totals: AlertIntakeAnalyticsTotals;
+    previous: AlertIntakeAnalyticsComparison | null;
+    timeline: AlertIntakeAnalyticsTimelinePoint[];
+    byState: AlertIntakeAnalyticsCount<AlertIntakeMessageState>[];
+    /** Every channel, zeros included. */
+    byChannel: AlertIntakeAnalyticsChannelRow[];
+    /**
+     * The organization's own connections - including those that received nothing - and any
+     * platform connection that carried its messages (without that connection's status).
+     */
+    byConnection: AlertIntakeAnalyticsConnectionRow[];
+    screening: AlertIntakeAnalyticsScreening;
+    languages: AlertIntakeAnalyticsLanguageRow[];
+    categories: AlertIntakeAnalyticsCategoryRow[];
+    /** Low, Medium, High, Critical. */
+    priorities: AlertIntakeAnalyticsCount[];
+    locations: AlertIntakeAnalyticsLocations;
+    attachments: AlertIntakeAnalyticsAttachments;
+    heatmap: AlertIntakeAnalyticsHeatCell[];
+    ai: AlertIntakeAnalyticsAi;
+    /** Platform view only. */
+    byOrganization?: AlertIntakeAnalyticsOrganizationRow[];
+}

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

@@ -147,10 +147,54 @@ export declare enum PermissionActions {
     PUBLISH_NEWSFEED_POST = "publish:newsfeed-post",
     ARCHIVE_NEWSFEED_POST = "archive:newsfeed-post",
     DELETE_NEWSFEED_POST = "delete:newsfeed-post",
+    READ_NOTIFICATION_BRANDING = "read:notification-branding",
+    UPDATE_NOTIFICATION_BRANDING = "update:notification-branding",
+    CREATE_NOTIFICATION_EMAIL_SENDER = "create:notification-email-sender",
+    READ_NOTIFICATION_EMAIL_SENDER = "read:notification-email-sender",
+    UPDATE_NOTIFICATION_EMAIL_SENDER = "update:notification-email-sender",
+    DELETE_NOTIFICATION_EMAIL_SENDER = "delete:notification-email-sender",
+    CREATE_NOTIFICATION_SMS_SENDER = "create:notification-sms-sender",
+    READ_NOTIFICATION_SMS_SENDER = "read:notification-sms-sender",
+    UPDATE_NOTIFICATION_SMS_SENDER = "update:notification-sms-sender",
+    DELETE_NOTIFICATION_SMS_SENDER = "delete:notification-sms-sender",
+    APPROVE_NOTIFICATION_SENDER = "approve:notification-sender",
+    /**
+     * @deprecated Split into the branding / email sender / SMS sender actions
+     * above, which the gateway now requires instead. Still granted to
+     * Organization:Owner and Organization:Admin for ONE release, so a gateway that
+     * has not yet been redeployed keeps working while clarion-authentication
+     * reseeds roles; remove it (and its grants) once every gateway requires the new
+     * actions. Grant it to nothing new.
+     */
     READ_NOTIFICATION_SETTINGS = "read:notification-settings",
+    /** @deprecated See READ_NOTIFICATION_SETTINGS. */
     MANAGE_NOTIFICATION_SETTINGS = "manage:notification-settings",
-    APPROVE_NOTIFICATION_SENDER = "approve:notification-sender",
+    CREATE_ALERT_INTAKE_CONNECTION = "create:alert-intake-connection",
+    READ_ALERT_INTAKE_CONNECTION = "read:alert-intake-connection",
+    UPDATE_ALERT_INTAKE_CONNECTION = "update:alert-intake-connection",
+    DELETE_ALERT_INTAKE_CONNECTION = "delete:alert-intake-connection",
+    TEST_ALERT_INTAKE_CONNECTION = "test:alert-intake-connection",
+    READ_ALERT_INTAKE_MESSAGE = "read:alert-intake-message",
+    RETRY_ALERT_INTAKE_MESSAGE = "retry:alert-intake-message",
+    READ_ALERT_INTAKE_SCREENED_MESSAGE = "read:alert-intake-screened-message",
+    REVIEW_ALERT_INTAKE_SCREENED_MESSAGE = "review:alert-intake-screened-message",
+    READ_ALERT_INTAKE_ANALYTICS = "read:alert-intake-analytics",
+    MANAGE_ALERT_INTAKE_PLATFORM = "manage:alert-intake-platform",
+    /**
+     * @deprecated Split into the connection / message / screened-message /
+     * analytics actions above, which the gateway now requires instead. Still
+     * granted to Organization:Owner and Organization:Admin for ONE release, so a
+     * gateway that has not yet been redeployed keeps working while
+     * clarion-authentication reseeds roles; remove it (and its grants) once every
+     * gateway requires the new actions. Grant it to nothing new.
+     */
     READ_ALERT_INTAKE = "read:alert-intake",
-    MANAGE_ALERT_INTAKE = "manage:alert-intake",
-    MANAGE_ALERT_INTAKE_PLATFORM = "manage:alert-intake-platform"
+    /** @deprecated See READ_ALERT_INTAKE. */
+    MANAGE_ALERT_INTAKE = "manage:alert-intake"
 }
+/**
+ * Actions kept only so a gateway that has not been redeployed keeps working through
+ * a release that replaced them. Nothing new may require or be granted them; the
+ * next release removes them from the enum, the catalogue and every role.
+ */
+export declare const RETIRING_PERMISSION_ACTIONS: readonly string[];

package/dist/types/modules/role/enums/role.enum.d.ts

@@ -17,6 +17,14 @@ export declare enum Roles {
      * concerns, so this role is scoped there rather than to a control centre.
      */
     ORGANIZATION_SUPPORT_ADMIN = "Organization:Support-Admin",
+    /**
+     * Sets up and runs the organization's alert channels - the SMS short codes,
+     * WhatsApp numbers and mailboxes the public reaches it on without the app
+     * (clarion-alerts) - and works what arrives on them: the messages, the review
+     * queue of what screening held back, and the channels' analytics. Configuring
+     * a channel is an organization-level decision, so the role is scoped there.
+     */
+    ORGANIZATION_ALERT_CHANNELS_ADMIN = "Organization:Alert-Channels-Admin",
     CONTROL_CENTRE_ADMIN = "Control-Centre:Admin",
     CONTROL_CENTRE_USER = "Control-Centre:User",
     /** The same job, confined to one control centre. */

package/package.json

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