clarion-shared-types 1.0.101 → 1.0.102

package/dist/cjs/modules/alert-intake/index.js

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./enums/alert-intake.enum"), exports);
 // Response shapes + plain request interfaces
 __exportStar(require("./interfaces/alert-intake"), exports);
+__exportStar(require("./interfaces/alert-intake-analytics"), exports);
 // Utilities
 __exportStar(require("./utils/alert-intake.util"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/modules/alert-intake/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/alert-intake/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,QAAQ;AACR,4DAA0C;AAE1C,6CAA6C;AAC7C,4DAA0C;AAE1C,YAAY;AACZ,4DAA0C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/alert-intake/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,QAAQ;AACR,4DAA0C;AAE1C,6CAA6C;AAC7C,4DAA0C;AAC1C,sEAAoD;AAEpD,YAAY;AACZ,4DAA0C"}

package/dist/cjs/modules/alert-intake/interfaces/alert-intake-analytics.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=alert-intake-analytics.js.map

package/dist/cjs/modules/alert-intake/interfaces/alert-intake-analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-intake-analytics.js","sourceRoot":"","sources":["../../../../../src/modules/alert-intake/interfaces/alert-intake-analytics.ts"],"names":[],"mappings":""}

package/dist/esm/modules/alert-intake/index.js

@@ -2,6 +2,7 @@
 export * from './enums/alert-intake.enum';
 // Response shapes + plain request interfaces
 export * from './interfaces/alert-intake';
+export * from './interfaces/alert-intake-analytics';
 // Utilities
 export * from './utils/alert-intake.util';
 //# sourceMappingURL=index.js.map

package/dist/esm/modules/alert-intake/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/alert-intake/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,cAAc,2BAA2B,CAAC;AAE1C,6CAA6C;AAC7C,cAAc,2BAA2B,CAAC;AAE1C,YAAY;AACZ,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/alert-intake/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,cAAc,2BAA2B,CAAC;AAE1C,6CAA6C;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qCAAqC,CAAC;AAEpD,YAAY;AACZ,cAAc,2BAA2B,CAAC"}

package/dist/esm/modules/alert-intake/interfaces/alert-intake-analytics.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=alert-intake-analytics.js.map

package/dist/esm/modules/alert-intake/interfaces/alert-intake-analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-intake-analytics.js","sourceRoot":"","sources":["../../../../../src/modules/alert-intake/interfaces/alert-intake-analytics.ts"],"names":[],"mappings":""}

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

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

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

@@ -0,0 +1,254 @@
+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[];
+}
+/**
+ * The period an analytics read covers (query string). Both ends optional: no `from` is
+ * "forever", no `to` is now. ISO 8601 instants; `timeZone` is an IANA name.
+ */
+export interface AlertIntakeAnalyticsQuery {
+    from?: string;
+    to?: string;
+    timeZone?: string;
+}
+/** Platform operators: every organization's analytics, or one organization's. */
+export interface PlatformAlertIntakeAnalyticsQuery extends AlertIntakeAnalyticsQuery {
+    organizationId?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clarion-shared-types",
-  "version": "1.0.101",
+  "version": "1.0.102",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",