grm-shared-library 1.1.213 → 1.1.215

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

@@ -0,0 +1,230 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { AlertIntakeChannel, AlertIntakeEmergencyPolicy, AlertIntakeMessageState, AlertIntakeProvider, AlertIntakeRejectionReason, AlertIntakeRouteMatch, AlertIntakeSecretSource, AlertIntakeWebhookVerification } from '../enums/alert-intake.enum';
+/**
+ * Alert intake settings.
+ *
+ * `organizationId` is the single source of truth. A CONNECTION is one
+ * organization's link to one provider on one channel (its short code, its WhatsApp
+ * number, its mailbox). A message that arrives on a connection belongs to the
+ * connection's organization, and everything the incident needs - app id, incident
+ * class, workflow queue, country - is read from that organization's record in
+ * clarion-organization rather than from a table in code.
+ *
+ * The fallback is a PLATFORM connection (no organization): a shared short code or a
+ * shared mailbox whose messages are routed to an organization by keyword, or to a
+ * default organization.
+ *
+ * Owned by clarion-alerts, proxied by the gateway, rendered by the admin. No shape
+ * here ever carries a credential: secrets are write-only.
+ */
+export type AlertIntakeFieldType = 'text' | 'number' | 'boolean' | 'select';
+/** One value a provider needs from the operator. */
+export interface AlertIntakeProviderFieldDescriptor {
+    key: string;
+    label: string;
+    type: AlertIntakeFieldType;
+    required: boolean;
+    /** Secret fields are write-only, and are stored encrypted or as a reference. */
+    secret: boolean;
+    placeholder?: string;
+    description?: string;
+    defaultValue?: string | number | boolean;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** `text` fields only. */
+    maxLength?: number;
+    /** `number` fields only; inclusive. */
+    min?: number;
+    max?: number;
+    /** Only a platform operator may set this (e.g. switching off TLS verification). */
+    operatorOnly?: boolean;
+}
+/**
+ * Self-description of an intake provider, published by clarion-alerts. Same idea as
+ * the tracking and SMS provider descriptors: the service that owns the adapter is
+ * the source of truth for what it needs, so adding a provider changes no client code.
+ * Static metadata - never a credential, never anything tenant-specific.
+ */
+export interface AlertIntakeProviderDescriptor {
+    provider: AlertIntakeProvider;
+    channel: AlertIntakeChannel;
+    displayName: string;
+    description: string;
+    /** What identifies the connection to the provider: the number people text, the mailbox. */
+    address: {
+        label: string;
+        placeholder?: string;
+        description?: string;
+    };
+    fields: AlertIntakeProviderFieldDescriptor[];
+    /** Null for a provider that is polled rather than called (IMAP). */
+    webhook: {
+        verification: AlertIntakeWebhookVerification;
+        /** Steps the operator performs in the PROVIDER's console, in order. */
+        setup: string[];
+    } | null;
+    /** Whether `POST .../test` does something for this provider. */
+    testable: boolean;
+    documentationUrl?: string;
+}
+export interface AlertIntakeConnection {
+    id: string;
+    /** Null = a platform connection, shared between organizations through routes. */
+    organizationId: number | null;
+    channel: AlertIntakeChannel;
+    provider: AlertIntakeProvider;
+    name: string;
+    /** The short code / number / WhatsApp phone-number id / mailbox messages are sent TO. */
+    address: string;
+    enabled: boolean;
+    /** Non-secret provider settings, as described by the provider's descriptor. */
+    config: Record<string, string | number | boolean>;
+    secretSource: AlertIntakeSecretSource;
+    /** Which secret fields have a value. The values themselves are never returned. */
+    secretsConfigured: Record<string, boolean>;
+    emergencyPolicy: AlertIntakeEmergencyPolicy;
+    /**
+     * The URL to paste into the provider's console. Null for a polled provider.
+     * It embeds an unguessable key: treat it as a credential.
+     */
+    webhookUrl: string | null;
+    /** When the provider last completed its verification handshake (WhatsApp). */
+    webhookVerifiedAt: string | null;
+    lastReceivedAt: string | null;
+    lastError: string | null;
+    lastErrorAt: string | null;
+    /** Set on the connections created from the pre-organization, per-tenant setup. */
+    legacyKey: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Sends the messages of a PLATFORM connection to an organization. */
+export interface AlertIntakeRoute {
+    id: string;
+    connectionId: string;
+    match: AlertIntakeRouteMatch;
+    /** Upper-cased. Null for the DEFAULT route. */
+    keyword: string | null;
+    organizationId: number;
+    enabled: boolean;
+    createdAt: string;
+}
+/** What the incident will be created with, derived from the organization record. */
+export interface AlertIntakeOrganizationContext {
+    organizationId: number;
+    name: string;
+    appId: string;
+    incidentClass: string;
+    workflowTaskQueueName: string;
+    countryCode: CountryCode;
+    /** False when the organization is not ACTIVE: its messages are held, not raised. */
+    active: boolean;
+}
+/** What an organization without a connection of its own falls back to, per channel. */
+export interface AlertIntakePlatformFallback {
+    channel: AlertIntakeChannel;
+    /** The shared address to publish, e.g. the platform short code. */
+    address: string;
+    provider: AlertIntakeProvider;
+    /** The keyword that routes to this organization, when it has one. */
+    keyword: string | null;
+    /** True when this organization is the connection's DEFAULT route. */
+    isDefault: boolean;
+}
+/** Everything the settings page needs, in one read. */
+export interface OrganizationAlertIntakeSettings {
+    organizationId: number;
+    /** Null when clarion-organization could not be reached or the id is unknown. */
+    organization: AlertIntakeOrganizationContext | null;
+    connections: AlertIntakeConnection[];
+    platformFallbacks: AlertIntakePlatformFallback[];
+    /** False when the service has no key to encrypt credentials with: only secret references can be used. */
+    encryptedSecretsAvailable: boolean;
+    /** What arrived for this organization recently, and what needs someone's attention. */
+    activity?: AlertIntakeActivitySummary;
+}
+/** Counts over the last `windowHours` - except `parked` and `failingConnections`, which are as of now. */
+export interface AlertIntakeActivitySummary {
+    windowHours: number;
+    received: number;
+    raised: number;
+    duplicates: number;
+    retrying: number;
+    /** Waiting for an operator: out of attempts, or held for a reason (no organization, organization inactive). */
+    parked: number;
+    /** Enabled connections whose last attempt failed (a rejected call, a mailbox that could not be read). */
+    failingConnections: number;
+}
+/** What is kept of a file that came with a message. Never its contents. */
+export interface AlertIntakeMessageAttachment {
+    fileName: string;
+    mimeType: string;
+    size: number;
+    /** True once the file is stored in DMS and linked to the incident. */
+    attached: boolean;
+    /** Why it was not attached, when it was not. */
+    error: string | null;
+}
+/**
+ * A stored message, as an operator sees it in a list. `preview` is the start of the
+ * text; the whole of it is only in the detail.
+ */
+export interface AlertIntakeMessage {
+    id: string;
+    /** Null while no organization has been found for it. */
+    organizationId: number | null;
+    connectionId: string | null;
+    connectionName: string | null;
+    channel: AlertIntakeChannel;
+    /** Phone number, WhatsApp number or email address, as stored. */
+    sender: string | null;
+    senderName: string | null;
+    subject: string | null;
+    preview: string;
+    /** The keyword that routed it, on a platform connection. */
+    routeKeyword: string | null;
+    state: AlertIntakeMessageState;
+    rejectionReason: AlertIntakeRejectionReason | null;
+    /** The last error, for RETRYING and PARKED. */
+    error: string | null;
+    attempts: number;
+    nextAttemptAt: string | null;
+    /** The incident it raised. */
+    incidentId: number | null;
+    attachmentCount: number;
+    /** When the sender was told their message was received, if they were. */
+    acknowledgedAt: string | null;
+    receivedAt: string;
+    updatedAt: string;
+    /** What the CALLER may do with it now. */
+    actions: {
+        /** Try again: a PARKED message that ran out of attempts, or whose organization is active again. */
+        retry: boolean;
+        /** Raise a message that was taken for a duplicate. */
+        raiseAnyway: boolean;
+        /** Give a message no route claimed to an organization (platform operators). */
+        assign: boolean;
+    };
+}
+export interface AlertIntakeMessageDetail extends AlertIntakeMessage {
+    /** What the incident is raised from (a routing keyword removed). */
+    content: string;
+    /** Exactly as received. */
+    originalContent: string;
+    attachments: AlertIntakeMessageAttachment[];
+    acknowledgementError: string | null;
+}
+export interface AlertIntakeMessagePage {
+    items: AlertIntakeMessage[];
+    total: number;
+    page: number;
+    limit: number;
+}
+export interface AlertIntakeConnectionTestResult {
+    success: boolean;
+    /** Operator-facing. Never contains a credential. */
+    message: string;
+    latencyMs?: number;
+}

package/dist/types/modules/alert-intake/utils/alert-intake.util.d.ts

@@ -0,0 +1,24 @@
+/** A routing keyword: 2-20 letters or digits, stored upper-cased. */
+export declare const ALERT_INTAKE_KEYWORD_PATTERN: RegExp;
+/** Upper bounds that keep one organization's settings a form rather than a list to page through. */
+export declare const MAX_ALERT_INTAKE_CONNECTIONS_PER_ORGANIZATION = 20;
+export declare const MAX_ALERT_INTAKE_ROUTES_PER_CONNECTION = 200;
+/** One settings value (config or secret). An access token is the longest thing that goes here. */
+export declare const MAX_ALERT_INTAKE_SETTING_LENGTH = 4096;
+/** Normalises what an operator typed into the stored form. Null when it is not a valid keyword. */
+export declare function normaliseAlertIntakeKeyword(value: string | null | undefined): string | null;
+/**
+ * The routing keyword of a message: its first word, upper-cased, punctuation
+ * stripped - `g4s, fire at the gate` and `G4S: fire` both give `G4S`.
+ * Null when the first word could not be a keyword.
+ *
+ * Deliberately only the FIRST word. Matching a keyword anywhere in the text would
+ * route "I was robbed near the G4S office" to G4S.
+ */
+export declare function extractAlertIntakeKeyword(text: string | null | undefined): string | null;
+/**
+ * The message with its routing keyword removed, so "G4S fire at the gate" is
+ * analysed as "fire at the gate". Returns the text unchanged when it does not start
+ * with that keyword.
+ */
+export declare function stripAlertIntakeKeyword(text: string, keyword: string): string;

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

@@ -0,0 +1,17 @@
+import { SmsSendResult } from '../interfaces/sms-send-result';
+/**
+ * clarion-alerts -> clarion-notification: tell the person who texted an alert that it
+ * was received (POST /alert-intake/notifications/sms). Sent under the ORGANIZATION's
+ * SMS sender ID, so the reply comes from the organization they reached.
+ *
+ * One recipient: an acknowledgement answers one message. The caller decides whether
+ * one is due (opt-in per connection, throttled per sender); this route only sends.
+ */
+export declare class AlertAcknowledgementSmsDto {
+    phoneNumber: string;
+    message: string;
+    organizationId: number;
+    reference?: string;
+}
+/** 200 sent · 422 can never be sent (e.g. the number) · 502 not sent, safe to retry · 503 no provider. */
+export type AlertAcknowledgementSmsResult = SmsSendResult;

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

@@ -22,3 +22,4 @@ export * from './utils/notification-sender.util';
 export * from './enums/billing-notification.enum';
 export * from './dtos/billing-notification.dto';
 export * from './interfaces/billing-notification-result';
+export * from './dtos/alert-acknowledgement.dto';

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

@@ -149,5 +149,8 @@ export declare enum PermissionActions {
     DELETE_NEWSFEED_POST = "delete:newsfeed-post",
     READ_NOTIFICATION_SETTINGS = "read:notification-settings",
     MANAGE_NOTIFICATION_SETTINGS = "manage:notification-settings",
-    APPROVE_NOTIFICATION_SENDER = "approve:notification-sender"
+    APPROVE_NOTIFICATION_SENDER = "approve:notification-sender",
+    READ_ALERT_INTAKE = "read:alert-intake",
+    MANAGE_ALERT_INTAKE = "manage:alert-intake",
+    MANAGE_ALERT_INTAKE_PLATFORM = "manage:alert-intake-platform"
 }

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

@@ -11,5 +11,6 @@ export declare enum PermissionsModule {
     BILLING = "Billing",
     NEWSFEED = "Newsfeed",
     SUPPORT = "Support",
-    NOTIFICATION = "Notification"
+    NOTIFICATION = "Notification",
+    ALERT_INTAKE = "Alert Intake"
 }

package/package.json

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