grm-shared-library 1.1.181 → 1.1.183

package/dist/types/modules/country/interfaces/geo-coordinates.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A simple latitude/longitude pair (WGS84 decimal degrees).
+ *
+ * Used for country-level map defaults (e.g. the default map center). Kept
+ * dependency-free so it is reusable across backend, admin and mobile.
+ */
+export interface GeoCoordinates {
+    /** Latitude in decimal degrees, range -90..90. */
+    lat: number;
+    /** Longitude in decimal degrees, range -180..180. */
+    lng: number;
+}

package/dist/types/modules/country/interfaces/map-bounds.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A rectangular geographic bounding box.
+ *
+ * Field names match the Google Maps `LatLngBoundsLiteral` shape so the value
+ * can be passed straight to the Maps JS SDK / Flutter map bounds restriction.
+ */
+export interface MapBounds {
+    /** Northernmost latitude (max lat). */
+    north: number;
+    /** Southernmost latitude (min lat). */
+    south: number;
+    /** Easternmost longitude (max lng). */
+    east: number;
+    /** Westernmost longitude (min lng). */
+    west: number;
+}

package/dist/types/modules/country/interfaces/supported-country-config.d.ts

@@ -0,0 +1,39 @@
+import { CountryCode } from '../enums/country-code.enum';
+import { CurrencyCode } from '../enums/currency-code.enum';
+import { GeoCoordinates } from './geo-coordinates';
+import { MapBounds } from './map-bounds';
+/**
+ * Full platform configuration for a supported country/market.
+ *
+ * This is the single source of truth that country-aware features (billing,
+ * newsfeed, notifications, maps, admin, mobile) should read from instead of
+ * hard-coding Kenya-specific values.
+ */
+export interface SupportedCountryConfig {
+    /** ISO 3166-1 alpha-2 country code, e.g. 'KE'. */
+    code: CountryCode;
+    /** Human-readable country name, e.g. 'Kenya'. */
+    name: string;
+    /** E.164 calling code, e.g. '+254'. */
+    callingCode: string;
+    /** ISO 4217 currency code used in this country. */
+    currencyCode: CurrencyCode;
+    /** Currency display symbol, e.g. 'KSh'. */
+    currencySymbol: string;
+    /** Number of minor-unit decimal digits for the currency. */
+    currencyDecimalPlaces: number;
+    /** IANA timezone identifier, e.g. 'Africa/Nairobi'. */
+    timezone: string;
+    /** BCP-47 default locale, e.g. 'en-KE'. */
+    defaultLocale: string;
+    /** Google Maps region bias (ccTLD), e.g. 'KE'. */
+    googleMapsRegion: string;
+    /** Default map center (typically the capital city). */
+    defaultMapCenter: GeoCoordinates;
+    /** Default map zoom level for a country-wide view. */
+    defaultMapZoom: number;
+    /** Approximate geographic bounding box for the country. */
+    mapBounds: MapBounds;
+    /** Whether the country is currently enabled for use. */
+    enabled: boolean;
+}

package/dist/types/modules/country/interfaces/supported-currency-config.d.ts

@@ -0,0 +1,19 @@
+import { CurrencyCode } from '../enums/currency-code.enum';
+/**
+ * Configuration describing a currency the platform supports.
+ *
+ * `decimalPlaces` is the number of minor-unit digits (e.g. KES has 2, UGX/TZS
+ * have 0) and should drive money formatting and minor-unit conversions.
+ */
+export interface SupportedCurrencyConfig {
+    /** ISO 4217 currency code. */
+    code: CurrencyCode;
+    /** Human-readable currency name, e.g. 'Kenyan Shilling'. */
+    name: string;
+    /** Display symbol, e.g. 'KSh'. */
+    symbol: string;
+    /** Number of minor-unit decimal digits, e.g. 2 for KES, 0 for UGX/TZS. */
+    decimalPlaces: number;
+    /** Whether the currency is currently enabled for use. */
+    enabled: boolean;
+}

package/dist/types/modules/country/utils/country.util.d.ts

@@ -0,0 +1,27 @@
+import { CountryCode } from '../enums/country-code.enum';
+import { CurrencyCode } from '../enums/currency-code.enum';
+import { SupportedCountryConfig } from '../interfaces/supported-country-config';
+import { SupportedCurrencyConfig } from '../interfaces/supported-currency-config';
+/**
+ * Country / currency helper utilities.
+ *
+ * These are intentionally simple, synchronous and dependency-free so they can
+ * be reused across every backend microservice without pulling in extra deps.
+ */
+/** Type guard: is `value` a supported ISO 3166-1 alpha-2 country code? */
+export declare function isSupportedCountryCode(value: unknown): value is CountryCode;
+/** Type guard: is `value` a supported ISO 4217 currency code? */
+export declare function isSupportedCurrencyCode(value: unknown): value is CurrencyCode;
+/** Get the full config for a supported country, or `undefined` if unsupported. */
+export declare function getSupportedCountryConfig(countryCode: string | null | undefined): SupportedCountryConfig | undefined;
+/** Get the full config for a supported currency, or `undefined` if unsupported. */
+export declare function getSupportedCurrencyConfig(currencyCode: string | null | undefined): SupportedCurrencyConfig | undefined;
+/** Resolve the currency used by a supported country, or `undefined`. */
+export declare function getCurrencyForCountry(countryCode: string | null | undefined): CurrencyCode | undefined;
+/** Resolve the E.164 calling code (e.g. '+254') for a supported country, or `undefined`. */
+export declare function getCallingCodeForCountry(countryCode: string | null | undefined): string | undefined;
+/**
+ * Reverse lookup: find the supported country whose E.164 calling code matches
+ * `callingCode` (e.g. '+254' -> Kenya), or `undefined` if none match.
+ */
+export declare function getCountryByCallingCode(callingCode: string | null | undefined): SupportedCountryConfig | undefined;

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

@@ -0,0 +1,10 @@
+/**
+ * Identifiers for the email providers the notification service can dispatch through.
+ * TWILIO_SENDGRID is the Twilio email provider (SendGrid API).
+ * Provider order/fallback is configuration-driven; new providers can be appended.
+ */
+export declare enum EmailProviderName {
+    TWILIO_SENDGRID = "twilio_sendgrid",
+    MAILGUN = "mailgun",
+    SES = "ses"
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Delivery channels supported by the clarion-notification service.
+ * Used to key per-channel dispatch results.
+ */
+export declare enum NotificationChannel {
+    SMS = "SMS",
+    EMAIL = "EMAIL",
+    PUSH = "PUSH",
+    WEB = "WEB"
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Aggregate status for a multi-channel notification dispatch.
+ * - SUCCESS: every attempted channel succeeded.
+ * - PARTIAL_SUCCESS: at least one channel succeeded and at least one failed.
+ * - FAILED: no attempted channel succeeded.
+ */
+export declare enum NotificationOverallStatus {
+    SUCCESS = "SUCCESS",
+    PARTIAL_SUCCESS = "PARTIAL_SUCCESS",
+    FAILED = "FAILED"
+}

package/dist/types/modules/notification/enums/provider-failure-reason.enum.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Normalized classification of why a provider attempt failed.
+ * Drives fallback behaviour: VALIDATION / CONFIG_MISSING are non-retryable
+ * (no fallback), the remainder are provider-level failures that trigger fallback.
+ */
+export declare enum ProviderFailureReason {
+    /** Malformed/invalid request (bad recipient, missing body/subject). Do not fall back. */
+    VALIDATION = "VALIDATION",
+    /** Provider is not configured/enabled. Skip provider (try next), not a send failure. */
+    CONFIG_MISSING = "CONFIG_MISSING",
+    /** Authentication/authorization failure with the provider. */
+    AUTH = "AUTH",
+    /** Provider rate limited the request. */
+    RATE_LIMIT = "RATE_LIMIT",
+    /** Request timed out. */
+    TIMEOUT = "TIMEOUT",
+    /** Network/connection error reaching the provider. */
+    NETWORK = "NETWORK",
+    /** Provider returned a server-side/processing error. */
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    /** Unclassified failure. */
+    UNKNOWN = "UNKNOWN"
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Identifiers for the SMS providers the notification service can dispatch through.
+ * Provider order/fallback is configuration-driven; new providers can be appended.
+ */
+export declare enum SmsProviderName {
+    TWILIO = "twilio",
+    UWAZII = "uwazii",
+    AFRICASTALKING = "africastalking"
+}

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

@@ -0,0 +1,12 @@
+export * from './enums/notification-channel.enum';
+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 './interfaces/provider-attempt';
+export * from './interfaces/per-channel-result';
+export * from './interfaces/sms-send-result';
+export * from './interfaces/email-send-result';
+export * from './interfaces/notification-dispatch-result';
+export * from './interfaces/sms-send-request';
+export * from './interfaces/email-send-request';

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

@@ -0,0 +1,35 @@
+/**
+ * Provider-agnostic email attachment. `content` is base64-encoded; `path` points to
+ * a file on disk. `cid` marks an inline attachment referenced from the HTML body.
+ */
+export interface EmailAttachment {
+    filename: string;
+    content?: string;
+    path?: string;
+    contentType?: string;
+    /** Content-ID for inline images referenced via cid: in the HTML body. */
+    cid?: string;
+}
+/**
+ * Provider-agnostic email send request handed to an EmailProvider implementation.
+ * Templating/rendering happens upstream; providers receive final subject/html/text.
+ * Backend/service-level contract (not consumed by the web admin).
+ */
+export interface EmailSendRequest {
+    to: string[];
+    subject: string;
+    /** Rendered HTML body. */
+    html: string;
+    /** Optional rendered plain-text body. */
+    text?: string;
+    /** From email address. Provider falls back to its configured default when absent. */
+    from?: string;
+    fromName?: string;
+    replyTo?: string;
+    cc?: string[];
+    bcc?: string[];
+    attachments?: EmailAttachment[];
+    /** Provider-level categorization tags. */
+    tags?: string[];
+    metadata?: Record<string, any>;
+}

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

@@ -0,0 +1,22 @@
+import { NotificationChannel } from '../enums/notification-channel.enum';
+import { EmailProviderName } from '../enums/email-provider-name.enum';
+import { ProviderFailureReason } from '../enums/provider-failure-reason.enum';
+import { ProviderAttempt } from './provider-attempt';
+/**
+ * Normalized result of an email send across the configured provider chain.
+ */
+export interface EmailSendResult {
+    channel: NotificationChannel.EMAIL;
+    success: boolean;
+    /** Provider that ultimately succeeded. */
+    provider?: EmailProviderName | string;
+    /** Normalized provider message/reference id. */
+    messageId?: string;
+    /** Recipients targeted. */
+    to?: string[];
+    /** Ordered attempts (primary first, then fallbacks). */
+    attempts: ProviderAttempt[];
+    failureReason?: ProviderFailureReason;
+    /** Internal, safe-to-log error summary. */
+    errorMessage?: string;
+}

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

@@ -0,0 +1,26 @@
+import { NotificationChannel } from '../enums/notification-channel.enum';
+import { NotificationOverallStatus } from '../enums/notification-overall-status.enum';
+import { PerChannelResult } from './per-channel-result';
+import { ProviderAttempt } from './provider-attempt';
+/**
+ * Aggregate outcome of a multi-channel notification dispatch.
+ *
+ * NOTE: In the current architecture most dispatches are triggered by fire-and-forget
+ * Kafka events, so this object is produced for internal logging/persistence and
+ * observability rather than being returned synchronously to the original API caller.
+ * It is display-safe (no secrets) and can back a future synchronous notification
+ * endpoint or an admin-facing view.
+ */
+export interface NotificationDispatchResult {
+    overallStatus: NotificationOverallStatus;
+    successfulChannels: NotificationChannel[];
+    failedChannels: NotificationChannel[];
+    /** Per-channel outcomes including provider attempts. */
+    perChannelResults: PerChannelResult[];
+    /** Flattened list of every provider attempt across all channels. */
+    providerAttempts: ProviderAttempt[];
+    /** Internal, safe-to-log error summaries. */
+    errors: string[];
+    /** Correlation/trace id linking this dispatch to the originating event. */
+    correlationId?: string;
+}

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

@@ -0,0 +1,22 @@
+import { NotificationChannel } from '../enums/notification-channel.enum';
+import { ProviderFailureReason } from '../enums/provider-failure-reason.enum';
+import { ProviderAttempt } from './provider-attempt';
+/**
+ * Normalized outcome for a single notification channel, including every provider
+ * attempt made (primary and fallbacks) and which provider ultimately succeeded.
+ */
+export interface PerChannelResult {
+    channel: NotificationChannel;
+    success: boolean;
+    /** Provider that ultimately succeeded (undefined when the channel failed). */
+    provider?: string;
+    /** Normalized provider reference id from the successful provider. */
+    messageId?: string;
+    /** Ordered attempts (primary first, then fallbacks). */
+    attempts: ProviderAttempt[];
+    /** True when the channel was intentionally not attempted (e.g. no recipient). */
+    skipped?: boolean;
+    failureReason?: ProviderFailureReason;
+    /** Internal, safe-to-log error summary. */
+    errorMessage?: string;
+}

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

@@ -0,0 +1,25 @@
+import { NotificationChannel } from '../enums/notification-channel.enum';
+import { ProviderFailureReason } from '../enums/provider-failure-reason.enum';
+/**
+ * Record of a single provider send attempt within a channel.
+ * One channel may produce several attempts (primary + fallbacks).
+ * Error details here are intended for internal logging/observability, not for
+ * public API clients.
+ */
+export interface ProviderAttempt {
+    /** Provider identifier (SmsProviderName | EmailProviderName value). */
+    provider: string;
+    channel: NotificationChannel;
+    success: boolean;
+    /** Whether the failure was provider-level and eligible for fallback. */
+    retryable?: boolean;
+    failureReason?: ProviderFailureReason;
+    /** Normalized provider message/reference id when the send succeeded. */
+    messageId?: string;
+    /** Internal, safe-to-log error summary (never surfaced to public clients). */
+    errorMessage?: string;
+    /** Provider HTTP/status code when available. */
+    statusCode?: number;
+    startedAt?: string;
+    durationMs?: number;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Provider-agnostic SMS send request handed to an SmsProvider implementation.
+ * Backend/service-level contract (not consumed by the web admin).
+ */
+export interface SmsSendRequest {
+    /** Recipients in E.164 format. */
+    to: string[];
+    /** Message body. */
+    body: string;
+    /** Sender id / from (alphanumeric sender name or number). Provider may override. */
+    senderId?: string;
+    /** Optional provider message type hint. */
+    type?: string;
+    metadata?: Record<string, any>;
+    incidentId?: number;
+    userId?: number;
+    organizationId?: number;
+}

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

@@ -0,0 +1,22 @@
+import { NotificationChannel } from '../enums/notification-channel.enum';
+import { ProviderFailureReason } from '../enums/provider-failure-reason.enum';
+import { SmsProviderName } from '../enums/sms-provider-name.enum';
+import { ProviderAttempt } from './provider-attempt';
+/**
+ * Normalized result of an SMS send across the configured provider chain.
+ */
+export interface SmsSendResult {
+    channel: NotificationChannel.SMS;
+    success: boolean;
+    /** Provider that ultimately succeeded. */
+    provider?: SmsProviderName | string;
+    /** Normalized provider message/reference id. */
+    messageId?: string;
+    /** Recipients targeted (E.164). */
+    to?: string[];
+    /** Ordered attempts (primary first, then fallbacks). */
+    attempts: ProviderAttempt[];
+    failureReason?: ProviderFailureReason;
+    /** Internal, safe-to-log error summary. */
+    errorMessage?: string;
+}

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

@@ -34,5 +34,61 @@ export declare enum PermissionActions {
     CREATE_RESPONSE_UNIT = "create:response-unit",
     READ_RESPONSE_UNIT = "read:response-unit",
     UPDATE_RESPONSE_UNIT = "update:response-unit",
-    DELETE_RESPONSE_UNIT = "delete:response-unit"
+    DELETE_RESPONSE_UNIT = "delete:response-unit",
+    CREATE_BENEFICIARY = "create:beneficiary",
+    READ_BENEFICIARY = "read:beneficiary",
+    UPDATE_BENEFICIARY = "update:beneficiary",
+    DELETE_BENEFICIARY = "delete:beneficiary",
+    CREATE_BILLING_CONFIG = "create:billing-config",
+    READ_BILLING_CONFIG = "read:billing-config",
+    UPDATE_BILLING_CONFIG = "update:billing-config",
+    DELETE_BILLING_CONFIG = "delete:billing-config",
+    CREATE_CORPORATE_CLIENT = "create:corporate-client",
+    READ_CORPORATE_CLIENT = "read:corporate-client",
+    UPDATE_CORPORATE_CLIENT = "update:corporate-client",
+    DELETE_CORPORATE_CLIENT = "delete:corporate-client",
+    CREATE_CORPORATE_CLIENT_MEMBER = "create:corporate-client-member",
+    READ_CORPORATE_CLIENT_MEMBER = "read:corporate-client-member",
+    UPDATE_CORPORATE_CLIENT_MEMBER = "update:corporate-client-member",
+    DELETE_CORPORATE_CLIENT_MEMBER = "delete:corporate-client-member",
+    CREATE_INDIVIDUAL_CLIENT = "create:individual-client",
+    READ_INDIVIDUAL_CLIENT = "read:individual-client",
+    UPDATE_INDIVIDUAL_CLIENT = "update:individual-client",
+    DELETE_INDIVIDUAL_CLIENT = "delete:individual-client",
+    READ_ENTITLEMENT = "read:entitlement",
+    CREATE_INVOICE = "create:invoice",
+    READ_INVOICE = "read:invoice",
+    MARK_INVOICE_PAID = "mark:invoice-paid",
+    CREATE_ORDER = "create:order",
+    READ_ORDER = "read:order",
+    CONFIRM_ORDER = "confirm:order",
+    CREATE_RECEIPT = "create:receipt",
+    READ_RECEIPT = "read:receipt",
+    CREATE_PACKAGE = "create:package",
+    READ_PACKAGE = "read:package",
+    UPDATE_PACKAGE = "update:package",
+    ACTIVATE_PACKAGE = "activate:package",
+    DEACTIVATE_PACKAGE = "deactivate:package",
+    DELETE_PACKAGE = "delete:package",
+    INITIALIZE_PAYMENT = "initialize:payment",
+    VERIFY_PAYMENT = "verify:payment",
+    READ_PAYMENT = "read:payment",
+    INITIALIZE_INDIVIDUAL_SUBSCRIPTION = "initialize:individual-subscription",
+    READ_INDIVIDUAL_SUBSCRIPTION = "read:individual-subscription",
+    APPROVE_INDIVIDUAL_SUBSCRIPTION_MANUALLY = "approve:individual-subscription-manually",
+    CANCEL_INDIVIDUAL_SUBSCRIPTION = "cancel:individual-subscription",
+    INITIALIZE_CORPORATE_SUBSCRIPTION = "initialize:corporate-subscription",
+    READ_CORPORATE_SUBSCRIPTION = "read:corporate-subscription",
+    APPROVE_CORPORATE_SUBSCRIPTION_MANUALLY = "approve:corporate-subscription-manually",
+    CANCEL_CORPORATE_SUBSCRIPTION = "cancel:corporate-subscription",
+    CREATE_SETTLEMENT = "create:settlement",
+    READ_SETTLEMENT = "read:settlement",
+    SEND_SETTLEMENT_INVOICE = "send:settlement-invoice",
+    MARK_SETTLEMENT_PAID = "mark:settlement-paid",
+    CREATE_NEWSFEED_POST = "create:newsfeed-post",
+    READ_NEWSFEED_POST = "read:newsfeed-post",
+    UPDATE_NEWSFEED_POST = "update:newsfeed-post",
+    PUBLISH_NEWSFEED_POST = "publish:newsfeed-post",
+    ARCHIVE_NEWSFEED_POST = "archive:newsfeed-post",
+    DELETE_NEWSFEED_POST = "delete:newsfeed-post"
 }

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

@@ -5,5 +5,7 @@ export declare enum PermissionsModule {
     USER = "User",
     ROLE = "Role",
     INCIDENT = "Grievance",
-    RESPONSE_UNIT = "Response Unit"
+    RESPONSE_UNIT = "Response Unit",
+    BILLING = "Billing",
+    NEWSFEED = "Newsfeed"
 }

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

@@ -3,6 +3,8 @@ export declare enum Roles {
     ORGANIZATION_OWNER = "Organization:Owner",
     ORGANIZATION_ADMIN = "Organization:Admin",
     ORGANIZATION_USER = "Organization:User",
+    ORGANIZATION_BILLING_ADMIN = "Organization:Billing-Admin",
+    ORGANIZATION_NEWSFEED_ADMIN = "Organization:Newsfeed-Admin",
     CONTROL_CENTRE_ADMIN = "Control-Centre:Admin",
     CONTROL_CENTRE_USER = "Control-Centre:User",
     RESPONDER = "Responder",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grm-shared-library",
-  "version": "1.1.181",
+  "version": "1.1.183",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -20,13 +20,14 @@
     "dist/**/*"
   ],
   "scripts": {
-    "clean": "rimraf dist",
+    "clean": "rimraf dist dist-test",
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "build:esm": "tsc -p tsconfig.esm.json",
     "build:types": "tsc -p tsconfig.types.json",
     "build": "npm run clean && npm run build:types && npm run build:cjs && npm run build:esm",
     "prepublishOnly": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "pretest": "rimraf dist-test",
+    "test": "tsc -p tsconfig.spec.json && node dist-test/modules/country/__tests__/country.spec.js"
   },
   "keywords": [],
   "author": "",