grm-shared-library 1.1.210 → 1.1.212

package/dist/types/modules/notification/dtos/organization-notification-settings.dto.d.ts

@@ -0,0 +1,64 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { IncidentAppId } from '../../incident/enums/incident-app-id.enum';
+import { NotificationSenderStatus } from '../enums/notification-sender-status.enum';
+import { SmsProviderName } from '../enums/sms-provider-name.enum';
+import { SmsSenderType } from '../enums/sms-sender-type.enum';
+export declare class NotificationSocialLinksDto {
+    facebook?: string | null;
+    x?: string | null;
+    instagram?: string | null;
+    linkedin?: string | null;
+}
+/**
+ * Saves an organization's branding. A PUT of the whole profile: a field sent as
+ * null (or "") stops overriding and inherits again; a field left out is untouched.
+ */
+export declare class UpsertOrganizationNotificationBrandingDto {
+    appId?: IncidentAppId | null;
+    companyName?: string | null;
+    appName?: string | null;
+    logoUrl?: string | null;
+    primaryColour?: string | null;
+    primaryColourDark?: string | null;
+    accentColour?: string | null;
+    physicalAddress?: string | null;
+    phoneNumber?: string | null;
+    contactEmail?: string | null;
+    supportEmail?: string | null;
+    websiteUrl?: string | null;
+    clientBaseUrl?: string | null;
+    social?: NotificationSocialLinksDto | null;
+}
+export declare class CreateOrganizationEmailSenderDto {
+    fromEmail: string;
+    fromName?: string | null;
+    replyTo?: string | null;
+    isDefault?: boolean;
+}
+export declare class UpdateOrganizationEmailSenderDto {
+    fromName?: string | null;
+    replyTo?: string | null;
+    isDefault?: boolean;
+    active?: boolean;
+}
+export declare class CreateOrganizationSmsSenderDto {
+    provider: SmsProviderName;
+    countryCode?: CountryCode | null;
+    senderType: SmsSenderType;
+    senderId: string;
+    notes?: string | null;
+}
+export declare class UpdateOrganizationSmsSenderDto {
+    countryCode?: CountryCode | null;
+    senderType?: SmsSenderType;
+    senderId?: string;
+    notes?: string | null;
+}
+/** Platform operators only: records the outcome of registering the sender with the provider. */
+export declare class ReviewOrganizationSmsSenderDto {
+    status: NotificationSenderStatus;
+    notes?: string | null;
+}
+export declare class SendTestNotificationEmailDto {
+    to: string;
+}

package/dist/types/modules/notification/enums/email-sender-verification.enum.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Whether an email provider will accept mail FROM an organization's address.
+ *
+ * Tracked per provider because the answer differs per provider: an address can be
+ * a verified sender in Twilio SendGrid while its domain is unknown to Mailgun.
+ * A provider only ever sends from an address it has VERIFIED; for every other
+ * state that provider falls back to the platform sender (keeping the
+ * organization's display name and reply-to), so a half-configured organization
+ * never loses mail to an "unverified sender" rejection.
+ */
+export declare enum EmailSenderVerificationStatus {
+    /** The provider does not know this address or its domain. */
+    UNVERIFIED = "UNVERIFIED",
+    /** Verification was started and is waiting on the owner (inbox click or DNS records). */
+    PENDING = "PENDING",
+    /** The provider accepts mail from this address. */
+    VERIFIED = "VERIFIED",
+    /** The last check could not be completed (provider error); the previous answer no longer holds. */
+    FAILED = "FAILED"
+}
+/** How the provider recognises the address. */
+export declare enum EmailSenderVerificationMethod {
+    /** The exact address was verified on its own (SendGrid Single Sender Verification). */
+    SINGLE_SENDER = "SINGLE_SENDER",
+    /** The whole domain is authenticated (SendGrid domain authentication, Mailgun domain). */
+    DOMAIN = "DOMAIN"
+}

package/dist/types/modules/notification/enums/notification-branding-source.enum.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where one resolved branding value came from. Branding is resolved field by
+ * field, highest precedence first, so a half-filled profile still produces a
+ * complete email:
+ *
+ *   PROFILE            the organization's notification settings
+ *   ORGANIZATION       the organization record (clarion-organization)
+ *   APP_DEFAULT        the legacy per-app defaults (deprecated; kept so nothing
+ *                      changes for an organization that has configured nothing)
+ *   PLATFORM_DEFAULT   the platform's own branding
+ */
+export declare enum NotificationBrandingSource {
+    PROFILE = "PROFILE",
+    ORGANIZATION = "ORGANIZATION",
+    APP_DEFAULT = "APP_DEFAULT",
+    PLATFORM_DEFAULT = "PLATFORM_DEFAULT"
+}

package/dist/types/modules/notification/enums/notification-sender-source.enum.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whose identity a message actually went out under. Recorded on every delivery
+ * log so "why did this customer get an Upesy-branded SMS?" is a query, not a guess.
+ */
+export declare enum NotificationSenderSource {
+    /** The organization's own verified email address / active SMS sender. */
+    ORGANIZATION = "ORGANIZATION",
+    /** The platform's default (country-aware) sender. */
+    PLATFORM_DEFAULT = "PLATFORM_DEFAULT"
+}

package/dist/types/modules/notification/enums/notification-sender-status.enum.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Lifecycle of an organization-owned SMS sender.
+ *
+ * A sender ID only works once the provider (and, behind it, the telco) has
+ * registered it, which happens outside Clarion. So an organization REQUESTS a
+ * sender and a platform operator ACTIVATES it after the registration is real.
+ * Only ACTIVE senders are ever used to send; every other state falls back to the
+ * platform's country-aware default sender.
+ */
+export declare enum NotificationSenderStatus {
+    /** Requested by the organization; not yet confirmed as registered with the provider. */
+    PENDING = "PENDING",
+    /** Registered with the provider and in use. */
+    ACTIVE = "ACTIVE",
+    /** Temporarily taken out of use (e.g. the telco suspended it). Kept for history. */
+    SUSPENDED = "SUSPENDED",
+    /** The provider or the operator refused the registration. */
+    REJECTED = "REJECTED"
+}

package/dist/types/modules/notification/enums/sms-provider-name.enum.d.ts

@@ -1,9 +1,14 @@
 /**
  * Identifiers for the SMS providers the notification service can dispatch through.
  * Provider order/fallback is configuration-driven; new providers can be appended.
+ *
+ * A code here only RESERVES the name. Whether a provider can actually be used is
+ * answered by the notification service's provider catalog
+ * (`SmsProviderDescriptor`), which lists only providers with a registered adapter.
  */
 export declare enum SmsProviderName {
     TWILIO = "twilio",
     UWAZII = "uwazii",
-    AFRICASTALKING = "africastalking"
+    AFRICASTALKING = "africastalking",
+    CELCOM = "celcom"
 }

package/dist/types/modules/notification/enums/sms-sender-type.enum.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What kind of identity an SMS is sent from.
+ *
+ * The type decides how the value is validated and how a provider is handed it:
+ * an alphanumeric name and a phone number both travel as the provider's "from",
+ * while a Twilio Messaging Service SID replaces the from entirely.
+ */
+export declare enum SmsSenderType {
+    /** A registered alphanumeric sender name, e.g. `G4S`. At most 11 characters. */
+    ALPHANUMERIC = "ALPHANUMERIC",
+    /** An E.164 long number, e.g. `+254711000000`. */
+    PHONE_NUMBER = "PHONE_NUMBER",
+    /** A telco short code, e.g. `22384`. */
+    SHORT_CODE = "SHORT_CODE",
+    /** A provider-side sender pool (Twilio Messaging Service SID, `MG…`). */
+    MESSAGING_SERVICE = "MESSAGING_SERVICE"
+}

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

@@ -3,6 +3,11 @@ export * from './enums/sms-provider-name.enum';
 export * from './enums/email-provider-name.enum';
 export * from './enums/notification-overall-status.enum';
 export * from './enums/provider-failure-reason.enum';
+export * from './enums/sms-sender-type.enum';
+export * from './enums/notification-sender-status.enum';
+export * from './enums/email-sender-verification.enum';
+export * from './enums/notification-sender-source.enum';
+export * from './enums/notification-branding-source.enum';
 export * from './interfaces/provider-attempt';
 export * from './interfaces/per-channel-result';
 export * from './interfaces/sms-send-result';
@@ -10,3 +15,7 @@ export * from './interfaces/email-send-result';
 export * from './interfaces/notification-dispatch-result';
 export * from './interfaces/sms-send-request';
 export * from './interfaces/email-send-request';
+export * from './interfaces/organization-notification-settings';
+export * from './dtos/organization-notification-settings.dto';
+export * from './constants/notification-sender.const';
+export * from './utils/notification-sender.util';

package/dist/types/modules/notification/interfaces/email-send-request.d.ts

@@ -32,4 +32,10 @@ export interface EmailSendRequest {
     /** Provider-level categorization tags. */
     tags?: string[];
     metadata?: Record<string, any>;
+    /**
+     * The organization this email is sent on behalf of. Drives sender identity: the
+     * orchestrator resolves the organization's verified address per provider and
+     * falls back to the platform sender when there is none.
+     */
+    organizationId?: number;
 }

package/dist/types/modules/notification/interfaces/email-send-result.d.ts

@@ -1,6 +1,7 @@
 import { NotificationChannel } from '../enums/notification-channel.enum';
 import { EmailProviderName } from '../enums/email-provider-name.enum';
 import { ProviderFailureReason } from '../enums/provider-failure-reason.enum';
+import { NotificationSenderSource } from '../enums/notification-sender-source.enum';
 import { ProviderAttempt } from './provider-attempt';
 /**
  * Normalized result of an email send across the configured provider chain.
@@ -19,4 +20,10 @@ export interface EmailSendResult {
     failureReason?: ProviderFailureReason;
     /** Internal, safe-to-log error summary. */
     errorMessage?: string;
+    /** The organization the message was sent on behalf of, when known. */
+    organizationId?: number;
+    /** The identity the successful attempt sent from: an email address, or an SMS sender ID. */
+    sender?: string;
+    /** Whether that identity was the organization's own or the platform default. */
+    senderSource?: NotificationSenderSource;
 }

package/dist/types/modules/notification/interfaces/organization-notification-settings.d.ts

@@ -0,0 +1,163 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { EmailProviderName } from '../enums/email-provider-name.enum';
+import { EmailSenderVerificationMethod, EmailSenderVerificationStatus } from '../enums/email-sender-verification.enum';
+import { NotificationBrandingSource } from '../enums/notification-branding-source.enum';
+import { NotificationSenderStatus } from '../enums/notification-sender-status.enum';
+import { SmsProviderName } from '../enums/sms-provider-name.enum';
+import { SmsSenderType } from '../enums/sms-sender-type.enum';
+/**
+ * Organization notification settings.
+ *
+ * Clarion is multi-tenant, and what a customer sees in a notification - the logo
+ * and colours of an email, the address it came from, the name an SMS arrives
+ * under - belongs to the ORGANIZATION that serves them. These contracts describe
+ * that identity. `organizationId` is the single key; the legacy `appId` survives
+ * only as an alias that lets an event which still carries nothing but an app id
+ * find its organization.
+ *
+ * Owned by clarion-notification, proxied by the gateway, rendered by the admin.
+ * Nothing here is a secret: provider credentials stay in the notification
+ * service's own configuration and never appear in these shapes.
+ */
+export interface NotificationSocialLinks {
+    facebook?: string | null;
+    x?: string | null;
+    instagram?: string | null;
+    linkedin?: string | null;
+}
+/** The values a notification template can brand itself with. */
+export interface NotificationBrandingFields {
+    /** Legal/trading name shown in the footer, e.g. `G4S Kenya Ltd`. */
+    companyName: string;
+    /** Product name the customer knows, e.g. `G4S Kenya`. Used in subjects and sign-offs. */
+    appName: string;
+    /** HTTPS URL of the logo. Email clients will not load anything else. */
+    logoUrl: string;
+    /** `#RRGGBB`. Buttons, links and accents. */
+    primaryColour: string;
+    /** `#RRGGBB`. Hover/pressed shade; derived from the primary when not chosen. */
+    primaryColourDark: string;
+    /** `#RRGGBB`. Secondary highlight. */
+    accentColour: string;
+    physicalAddress: string;
+    phoneNumber: string;
+    /** General contact address printed in the footer. Not the address mail is sent FROM. */
+    contactEmail: string;
+    supportEmail: string;
+    websiteUrl: string;
+    /** Base URL that links in a notification point at (the organization's web client). */
+    clientBaseUrl: string;
+    social: NotificationSocialLinks;
+}
+/** What an organization has chosen to override. Every field is optional: gaps are resolved, not rejected. */
+export interface OrganizationNotificationBranding extends Partial<NotificationBrandingFields> {
+    organizationId: number;
+    /**
+     * Legacy alias. An event that carries only an `appId` resolves to the
+     * organization whose profile claims it. At most one organization per app id.
+     */
+    appId?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    updatedBy?: number | null;
+}
+/**
+ * Branding after resolution: complete, and honest about where each value came
+ * from so the admin can show "inherited from the organization record" instead of
+ * an empty field.
+ */
+export interface ResolvedNotificationBranding extends NotificationBrandingFields {
+    organizationId: number | null;
+    sources: Record<keyof NotificationBrandingFields, NotificationBrandingSource>;
+}
+/** One provider's answer to "will you send mail from this address?". */
+export interface EmailSenderProviderVerification {
+    provider: EmailProviderName;
+    status: EmailSenderVerificationStatus;
+    method?: EmailSenderVerificationMethod | null;
+    /** Operator-facing explanation, e.g. "Domain ke.g4s.com is not added to Mailgun". */
+    detail?: string | null;
+    checkedAt?: string | null;
+}
+export interface OrganizationEmailSender {
+    id: string;
+    organizationId: number;
+    /** The address mail is sent FROM, e.g. `notifications@ke.g4s.com`. */
+    fromEmail: string;
+    /** Display name. Falls back to the resolved company name. */
+    fromName?: string | null;
+    /** Falls back to `fromEmail`. */
+    replyTo?: string | null;
+    /** The sender used when a notification does not ask for a specific one. One per organization. */
+    isDefault: boolean;
+    active: boolean;
+    verifications: EmailSenderProviderVerification[];
+    /** True when at least one configured provider has VERIFIED the address. */
+    usable: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface OrganizationSmsSender {
+    id: string;
+    organizationId: number;
+    /** The provider account this sender is registered with. */
+    provider: SmsProviderName;
+    /** The destination country it is registered for. Null = every country the provider serves. */
+    countryCode?: CountryCode | null;
+    senderType: SmsSenderType;
+    senderId: string;
+    status: NotificationSenderStatus;
+    /** Registration reference, telco ticket, anything the operator needs later. */
+    notes?: string | null;
+    reviewedBy?: number | null;
+    reviewedAt?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** A sender type a provider accepts, with everything a form needs to collect it. */
+export interface SmsProviderSenderTypeDescriptor {
+    type: SmsSenderType;
+    label: string;
+    placeholder?: string;
+    description?: string;
+}
+/**
+ * Self-description of an SMS provider, published by clarion-notification.
+ *
+ * Same idea as the tracking provider descriptor: the service that owns the
+ * adapter is the source of truth for what it supports, so adding a provider
+ * (Celcom, Africa's Talking, ...) changes no client code. Only providers with a
+ * registered adapter are described.
+ */
+export interface SmsProviderDescriptor {
+    provider: SmsProviderName;
+    displayName: string;
+    description: string;
+    /** Countries the adapter can deliver to. */
+    supportedCountries: CountryCode[];
+    senderTypes: SmsProviderSenderTypeDescriptor[];
+    /** Whether the platform's account for this provider is configured and enabled right now. */
+    configured: boolean;
+    documentationUrl?: string;
+}
+/** The platform senders an organization falls back to. Display-only. */
+export interface PlatformNotificationDefaults {
+    email: {
+        fromEmail: string | null;
+        fromName: string | null;
+    };
+    /** Per-country default SMS provider chain, e.g. `{ KE: ['twilio', 'uwazii'] }`. */
+    smsProviderChains: Partial<Record<CountryCode, SmsProviderName[]>>;
+    /** Email providers currently able to send, in order. */
+    emailProviders: EmailProviderName[];
+}
+/** Everything the settings page needs, in one read. */
+export interface OrganizationNotificationSettings {
+    organizationId: number;
+    /** Null until the organization saves a profile. */
+    branding: OrganizationNotificationBranding | null;
+    effectiveBranding: ResolvedNotificationBranding;
+    emailSenders: OrganizationEmailSender[];
+    smsSenders: OrganizationSmsSender[];
+    platformDefaults: PlatformNotificationDefaults;
+}

package/dist/types/modules/notification/interfaces/provider-attempt.d.ts

@@ -1,5 +1,6 @@
 import { NotificationChannel } from '../enums/notification-channel.enum';
 import { ProviderFailureReason } from '../enums/provider-failure-reason.enum';
+import { NotificationSenderSource } from '../enums/notification-sender-source.enum';
 /**
  * Record of a single provider send attempt within a channel.
  * One channel may produce several attempts (primary + fallbacks).
@@ -22,4 +23,8 @@ export interface ProviderAttempt {
     statusCode?: number;
     startedAt?: string;
     durationMs?: number;
+    /** The identity this attempt sent from: an email address, or an SMS sender ID. */
+    sender?: string;
+    /** Whether that identity was the organization's own or the platform default. */
+    senderSource?: NotificationSenderSource;
 }

package/dist/types/modules/notification/interfaces/sms-send-result.d.ts

@@ -1,6 +1,7 @@
 import { NotificationChannel } from '../enums/notification-channel.enum';
 import { ProviderFailureReason } from '../enums/provider-failure-reason.enum';
 import { SmsProviderName } from '../enums/sms-provider-name.enum';
+import { NotificationSenderSource } from '../enums/notification-sender-source.enum';
 import { ProviderAttempt } from './provider-attempt';
 /**
  * Normalized result of an SMS send across the configured provider chain.
@@ -19,4 +20,10 @@ export interface SmsSendResult {
     failureReason?: ProviderFailureReason;
     /** Internal, safe-to-log error summary. */
     errorMessage?: string;
+    /** The organization the message was sent on behalf of, when known. */
+    organizationId?: number;
+    /** The identity the successful attempt sent from: an email address, or an SMS sender ID. */
+    sender?: string;
+    /** Whether that identity was the organization's own or the platform default. */
+    senderSource?: NotificationSenderSource;
 }

package/dist/types/modules/notification/utils/notification-sender.util.d.ts

@@ -0,0 +1,25 @@
+import { SmsSenderType } from '../enums/sms-sender-type.enum';
+/**
+ * Validates an SMS sender value against its declared type.
+ * Returns null when valid, otherwise a message fit to show an operator.
+ */
+export declare function validateSmsSenderId(senderType: SmsSenderType, senderId: string): string | null;
+/** The domain part of an email address, lower-cased. Null when there is none. */
+export declare function emailDomainOf(address: string | null | undefined): string | null;
+/**
+ * WCAG contrast ratio of a `#RRGGBB` colour against white, from 1 (white) to 21
+ * (black). The email templates put WHITE text on the primary colour (buttons) and
+ * on the accent colour (header banner, footer), so a pale brand colour produces
+ * an email nobody can read. Returns 0 for anything that is not a hex colour.
+ */
+export declare function contrastRatioWithWhite(hex: string): number;
+/** Large text and UI components (WCAG 1.4.11): buttons and links in the primary colour. */
+export declare const MIN_PRIMARY_COLOUR_CONTRAST = 3;
+/** Body-size white text sits on the accent colour (WCAG 1.4.3). */
+export declare const MIN_ACCENT_COLOUR_CONTRAST = 4.5;
+/**
+ * Darkens a `#RRGGBB` colour by a fraction (0-1). Used to derive the hover/pressed
+ * shade of a brand colour so an organization only has to choose one.
+ * Returns the input unchanged when it is not a valid hex colour.
+ */
+export declare function darkenHexColour(hex: string, fraction?: number): string;

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

@@ -24,7 +24,23 @@ export declare enum PermissionActions {
     CHANGE_PRIORITY_SUPPORT_TICKET = "change-priority:support-ticket",
     CLOSE_SUPPORT_TICKET = "close:support-ticket",
     REOPEN_SUPPORT_TICKET = "reopen:support-ticket",
+    /** Rate the support received on a resolved ticket. A customer action. */
+    RATE_SUPPORT_TICKET = "rate:support-ticket",
+    /**
+     * One ticket's audit trail. Deliberately separate from reading the ticket:
+     * the trail names the agents who touched it and what they changed, which is
+     * a deeper grant than the conversation itself.
+     */
+    READ_SUPPORT_AUDIT = "read:support-audit",
+    /**
+     * Submit customer feedback. A CUSTOMER action, distinct from raising a
+     * ticket: feedback is not a request for help and never leaves Clarion for a
+     * helpdesk unless somebody promotes it.
+     */
+    CREATE_SUPPORT_FEEDBACK = "create:support-feedback",
     READ_SUPPORT_FEEDBACK = "read:support-feedback",
+    /** A customer answering in their OWN feedback thread, not an agent replying. */
+    REPLY_SUPPORT_FEEDBACK = "reply:support-feedback",
     REVIEW_SUPPORT_FEEDBACK = "review:support-feedback",
     RESPOND_SUPPORT_FEEDBACK = "respond:support-feedback",
     CONVERT_SUPPORT_FEEDBACK = "convert:support-feedback",
@@ -130,5 +146,8 @@ export declare enum PermissionActions {
     UPDATE_NEWSFEED_POST = "update:newsfeed-post",
     PUBLISH_NEWSFEED_POST = "publish:newsfeed-post",
     ARCHIVE_NEWSFEED_POST = "archive:newsfeed-post",
-    DELETE_NEWSFEED_POST = "delete:newsfeed-post"
+    DELETE_NEWSFEED_POST = "delete:newsfeed-post",
+    READ_NOTIFICATION_SETTINGS = "read:notification-settings",
+    MANAGE_NOTIFICATION_SETTINGS = "manage:notification-settings",
+    APPROVE_NOTIFICATION_SENDER = "approve:notification-sender"
 }

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

@@ -10,5 +10,6 @@ export declare enum PermissionsModule {
     TRACKING = "Tracking",
     BILLING = "Billing",
     NEWSFEED = "Newsfeed",
-    SUPPORT = "Support"
+    SUPPORT = "Support",
+    NOTIFICATION = "Notification"
 }

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

@@ -11,6 +11,12 @@ export declare enum Roles {
      * device bindings, tracking operations - across the whole organization.
      */
     ORGANIZATION_RESPONSE_UNITS_ADMIN = "Organization:Response-Units-Admin",
+    /**
+     * Runs the support desk for an organization: tickets, customer feedback and
+     * the desk's own configuration. Support and feedback are organization-level
+     * concerns, so this role is scoped there rather than to a control centre.
+     */
+    ORGANIZATION_SUPPORT_ADMIN = "Organization:Support-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.210",
+  "version": "1.1.212",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",