grm-shared-library 1.1.211 → 1.1.213

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

@@ -0,0 +1,35 @@
+import { NotificationChannel } from '../enums/notification-channel.enum';
+import { EmailSendResult } from './email-send-result';
+import { SmsSendResult } from './sms-send-result';
+/**
+ * What `POST /billing/notifications/*` answers with.
+ *
+ * The status code is the confirmation; the body is the detail:
+ *
+ *   200  everything asked for was handed to a provider
+ *   207  (sms only) some recipients were, some were not - NOT retried by the
+ *        caller, because a retry would message the ones that succeeded again
+ *   422  the request can never succeed as sent (bad number, expired document URL)
+ *   502  a provider or the document store failed; nothing was sent; retry is safe
+ *   503  no provider is configured for the channel
+ *
+ * On 4xx/5xx the same result object is the error body.
+ */
+export interface BillingEmailNotificationResult extends EmailSendResult {
+    documents: {
+        /** File names attached to the email. */
+        attached: string[];
+        /** Documents named in the email but not attached (no signed URL was supplied). */
+        referenced: string[];
+    };
+}
+export type BillingSmsNotificationResult = SmsSendResult;
+export interface BillingPushNotificationResult {
+    channel: NotificationChannel.PUSH;
+    /** True when no send failed. A user with no registered device is not a failure. */
+    success: boolean;
+    /** Devices a send was attempted to. Zero means none of the users has the app registered. */
+    totalAttempted: number;
+    successCount: number;
+    failureCount: number;
+}

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

@@ -146,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/package.json

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