grm-shared-library 1.1.191 → 1.1.193

package/dist/esm/modules/system-user/constants/system-user.const.js

@@ -0,0 +1,28 @@
+/**
+ * Canonical environment variable that carries the platform "system user" id.
+ *
+ * The system user is a real row in the clarion-authentication `users` table
+ * that services stamp on records they create or mutate on their own behalf —
+ * i.e. when there is no authenticated human in the request (auto-assignment,
+ * automated status changes, service-to-service document uploads).
+ *
+ * It is deliberately NOT a compile-time constant: it is an environment-specific
+ * database row id, so dev / staging / production each carry their own value.
+ * The library owns the *contract* (key name, parsing, validation, fallback
+ * policy); the deployment owns the *value* (see clarion-deployment configmap).
+ */
+export const SYSTEM_USER_ID_ENV_KEY = 'SYSTEM_USER_ID';
+/**
+ * Per-service keys that predate {@link SYSTEM_USER_ID_ENV_KEY}.
+ *
+ * Still read — in order — when the canonical key is absent, so that a rollback
+ * to an older ConfigMap does not take a service down. Remove once every
+ * environment has been migrated to the canonical key.
+ *
+ * @deprecated Set {@link SYSTEM_USER_ID_ENV_KEY} instead.
+ */
+export const LEGACY_SYSTEM_USER_ID_ENV_KEYS = [
+    'BILLING_DMS_SERVICE_USER_ID',
+    'NEWSFEED_DMS_SERVICE_USER_ID',
+];
+//# sourceMappingURL=system-user.const.js.map

package/dist/esm/modules/system-user/constants/system-user.const.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-user.const.js","sourceRoot":"","sources":["../../../../../src/modules/system-user/constants/system-user.const.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,gBAAgB,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAsB;IAC7D,6BAA6B;IAC7B,8BAA8B;CACjC,CAAC"}

package/dist/esm/modules/system-user/index.js

@@ -0,0 +1,11 @@
+// Constants
+export * from './constants/system-user.const';
+// Interfaces
+export * from './interfaces/system-user-env-source';
+// Utilities
+export * from './utils/system-user.util';
+// Services
+export * from './services/system-user.service';
+// Module
+export * from './system-user.module';
+//# sourceMappingURL=index.js.map

package/dist/esm/modules/system-user/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/system-user/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,cAAc,+BAA+B,CAAC;AAE9C,aAAa;AACb,cAAc,qCAAqC,CAAC;AAEpD,YAAY;AACZ,cAAc,0BAA0B,CAAC;AAEzC,WAAW;AACX,cAAc,gCAAgC,CAAC;AAE/C,SAAS;AACT,cAAc,sBAAsB,CAAC"}

package/dist/esm/modules/system-user/interfaces/system-user-env-source.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=system-user-env-source.js.map

package/dist/esm/modules/system-user/interfaces/system-user-env-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-user-env-source.js","sourceRoot":"","sources":["../../../../../src/modules/system-user/interfaces/system-user-env-source.ts"],"names":[],"mappings":""}

package/dist/esm/modules/system-user/services/system-user.service.js

@@ -0,0 +1,57 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var SystemUserService_1;
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { SYSTEM_USER_ID_ENV_KEY } from '../constants/system-user.const';
+import { resolveSystemUserId } from '../utils/system-user.util';
+/**
+ * Single source of truth for the platform system user id inside a service.
+ *
+ * Resolution happens once, on module init, so a mis-set `SYSTEM_USER_ID`
+ * fails the pod's startup probe instead of surfacing later as records stamped
+ * with a user id that clarion-authentication cannot resolve.
+ *
+ * @example
+ * constructor(private readonly systemUser: SystemUserService) {}
+ * ...
+ * const actorId = userContext?.userId ?? this.systemUser.id;
+ */
+let SystemUserService = SystemUserService_1 = class SystemUserService {
+    constructor(configService) {
+        this.configService = configService;
+        this.logger = new Logger(SystemUserService_1.name);
+        this.resolvedId = null;
+    }
+    onModuleInit() {
+        this.resolvedId = resolveSystemUserId(this.configService, {
+            onLegacyKeyUsed: (key) => this.logger.warn(`Resolved the system user id from deprecated env key "${key}". ` +
+                `Set ${SYSTEM_USER_ID_ENV_KEY} instead — legacy keys will be removed.`),
+        });
+        this.logger.log(`System user id resolved to ${this.resolvedId}`);
+    }
+    /**
+     * The system user id. Throws if read before module init completed, which
+     * only happens if a provider resolves it inside its own constructor.
+     */
+    get id() {
+        if (this.resolvedId === null) {
+            // Resolve on demand so constructor-time reads still work.
+            this.resolvedId = resolveSystemUserId(this.configService);
+        }
+        return this.resolvedId;
+    }
+};
+SystemUserService = SystemUserService_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [ConfigService])
+], SystemUserService);
+export { SystemUserService };
+//# sourceMappingURL=system-user.service.js.map

package/dist/esm/modules/system-user/services/system-user.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-user.service.js","sourceRoot":"","sources":["../../../../../src/modules/system-user/services/system-user.service.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAgB,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;;;;;;;GAWG;AAEI,IAAM,iBAAiB,yBAAvB,MAAM,iBAAiB;IAI1B,YAA6B,aAA4B;QAA5B,kBAAa,GAAb,aAAa,CAAe;QAHxC,WAAM,GAAG,IAAI,MAAM,CAAC,mBAAiB,CAAC,IAAI,CAAC,CAAC;QACrD,eAAU,GAAkB,IAAI,CAAC;IAEoB,CAAC;IAE9D,YAAY;QACR,IAAI,CAAC,UAAU,GAAG,mBAAmB,CAAC,IAAI,CAAC,aAAa,EAAE;YACtD,eAAe,EAAE,CAAC,GAAG,EAAE,EAAE,CACrB,IAAI,CAAC,MAAM,CAAC,IAAI,CACZ,wDAAwD,GAAG,KAAK;gBAChE,OAAO,sBAAsB,yCAAyC,CACzE;SACR,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,8BAA8B,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;;OAGG;IACH,IAAI,EAAE;QACF,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YAC3B,0DAA0D;YAC1D,IAAI,CAAC,UAAU,GAAG,mBAAmB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;CACJ,CAAA;AA5BY,iBAAiB;IAD7B,UAAU,EAAE;qCAKmC,aAAa;GAJhD,iBAAiB,CA4B7B"}

package/dist/esm/modules/system-user/system-user.module.js

@@ -0,0 +1,30 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Global, Module } from '@nestjs/common';
+import { SystemUserService } from './services/system-user.service';
+/**
+ * Global module exposing {@link SystemUserService} to every provider in the
+ * host application. Import once in the service's root `AppModule`:
+ *
+ * @example
+ * @Module({ imports: [ConfigModule.forRoot({ ... }), SystemUserModule] })
+ * export class AppModule {}
+ *
+ * Requires `ConfigModule` to be global (the convention across clarion
+ * services) or otherwise available where this module is imported.
+ */
+let SystemUserModule = class SystemUserModule {
+};
+SystemUserModule = __decorate([
+    Global(),
+    Module({
+        providers: [SystemUserService],
+        exports: [SystemUserService],
+    })
+], SystemUserModule);
+export { SystemUserModule };
+//# sourceMappingURL=system-user.module.js.map

package/dist/esm/modules/system-user/system-user.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-user.module.js","sourceRoot":"","sources":["../../../../src/modules/system-user/system-user.module.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE;;;;;;;;;;GAUG;AAMI,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;CAAI,CAAA;AAApB,gBAAgB;IAL5B,MAAM,EAAE;IACR,MAAM,CAAC;QACJ,SAAS,EAAE,CAAC,iBAAiB,CAAC;QAC9B,OAAO,EAAE,CAAC,iBAAiB,CAAC;KAC/B,CAAC;GACW,gBAAgB,CAAI"}

package/dist/esm/modules/system-user/utils/system-user.util.js

@@ -0,0 +1,53 @@
+import { LEGACY_SYSTEM_USER_ID_ENV_KEYS, SYSTEM_USER_ID_ENV_KEY } from '../constants/system-user.const';
+/**
+ * Parses a raw environment value into a usable user id.
+ *
+ * Returns `null` for anything that is not a positive integer — including
+ * `'0'`, `'-1'`, `'abc'` and the empty string — so that a typo'd ConfigMap
+ * entry surfaces as a clear failure rather than silently stamping user `0`
+ * onto production records.
+ */
+export function parseSystemUserId(raw) {
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    const text = String(raw).trim();
+    if (!text || !/^\d+$/.test(text)) {
+        return null;
+    }
+    const parsed = Number(text);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+/**
+ * Resolves the platform system user id from the environment.
+ *
+ * Precedence: {@link SYSTEM_USER_ID_ENV_KEY} → each legacy key in order →
+ * `options.fallback`. Throws when nothing resolves and no fallback is given,
+ * which is the intended behaviour at startup: a service that stamps records
+ * with the system user should refuse to boot rather than write a wrong id.
+ *
+ * @example
+ * // In a Nest provider that already injects ConfigService:
+ * this.systemUserId = resolveSystemUserId(this.configService);
+ */
+export function resolveSystemUserId(source, options = {}) {
+    const { legacyKeys = LEGACY_SYSTEM_USER_ID_ENV_KEYS, fallback, onLegacyKeyUsed } = options;
+    const canonical = parseSystemUserId(source.get(SYSTEM_USER_ID_ENV_KEY));
+    if (canonical !== null) {
+        return canonical;
+    }
+    for (const key of legacyKeys) {
+        const legacy = parseSystemUserId(source.get(key));
+        if (legacy !== null) {
+            onLegacyKeyUsed === null || onLegacyKeyUsed === void 0 ? void 0 : onLegacyKeyUsed(key);
+            return legacy;
+        }
+    }
+    if (fallback !== undefined) {
+        return fallback;
+    }
+    throw new Error(`${SYSTEM_USER_ID_ENV_KEY} is not set to a positive integer. ` +
+        `Set it to the id of the platform system user in clarion-authentication ` +
+        `(checked legacy keys: ${legacyKeys.length ? legacyKeys.join(', ') : 'none'}).`);
+}
+//# sourceMappingURL=system-user.util.js.map

package/dist/esm/modules/system-user/utils/system-user.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-user.util.js","sourceRoot":"","sources":["../../../../../src/modules/system-user/utils/system-user.util.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,8BAA8B,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAqBxG;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC1C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAC/B,MAA2B,EAC3B,UAAsC,EAAE;IAExC,MAAM,EAAE,UAAU,GAAG,8BAA8B,EAAE,QAAQ,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC;IAE3F,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC;IACxE,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAClB,eAAe,aAAf,eAAe,uBAAf,eAAe,CAAG,GAAG,CAAC,CAAC;YACvB,OAAO,MAAM,CAAC;QAClB,CAAC;IACL,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED,MAAM,IAAI,KAAK,CACX,GAAG,sBAAsB,qCAAqC;QAC9D,yEAAyE;QACzE,yBAAyB,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAClF,CAAC;AACN,CAAC"}

package/dist/types/index.d.ts

@@ -19,6 +19,8 @@ export * from './modules/chat/index';
 export * from './modules/country/index';
 export * from './modules/phone/index';
 export * from './modules/tracking/index';
+export * from './modules/entitlement/index';
+export * from './modules/system-user/index';
 export * from './interfaces/server-message';
 export * from './interfaces/i-request-with-user';
 export * from './interfaces/validated-user';

package/dist/types/interfaces/pagination.d.ts

@@ -5,6 +5,7 @@ import { Organization } from "../modules/organization";
 import { ResponseUnit } from "../modules/response-unit";
 import { User } from "../modules/user";
 import { WebNotification } from "../modules/web-notification";
+import { IncidentEntitlementScope } from "../modules/entitlement/enums/incident-entitlement-scope.enum";
 export interface CursorPaginatedResponse<T> {
     data: T[];
     nextCursor: string | null;
@@ -17,6 +18,15 @@ export interface PaginationParams {
     sortBy?: string;
     sortOrder?: 'ASC' | 'DESC';
 }
+/**
+ * Incident list query. Extends the generic pagination contract with the premium
+ * entitlement filter: the primary admin views ask for `ENTITLED` so Free-user
+ * incidents stay hidden, and the dedicated "Incident List - Free Users" view
+ * asks for `FREE`. Omitting it preserves the pre-entitlement behaviour (`ALL`).
+ */
+export interface IncidentQueryParams extends PaginationParams {
+    entitlementScope?: IncidentEntitlementScope;
+}
 export interface PaginatedResponse<T> {
     data: T[];
     meta: {

package/dist/types/modules/entitlement/constants/entitlement-defaults.const.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Platform defaults for the premium trial. A deployment overrides these with
+ * `BILLING_TRIAL_*` environment variables, and an organization can override them
+ * again through its billing config - so these are the last fallback, not policy.
+ */
+export declare const PREMIUM_TRIAL_DEFAULTS: {
+    /** Alerts a trial user may raise as if they were premium. */
+    readonly MAX_INCIDENTS: 2;
+    /** Days the trial window stays open from enrolment. */
+    readonly DURATION_DAYS: 30;
+};
+/**
+ * Header used to carry a caller-supplied idempotency key on entitlement
+ * mutations. Kept here so producer and consumer cannot drift.
+ */
+export declare const ENTITLEMENT_IDEMPOTENCY_HEADER = "x-entitlement-idempotency-key";

package/dist/types/modules/entitlement/dtos/consume-trial-alert.dto.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Records that one trial alert was spent. `incidentId` is the idempotency key:
+ * replaying the same incident never double-counts, so the caller can retry
+ * freely after a transient failure.
+ */
+export declare class ConsumeTrialAlertDto {
+    userId: number;
+    organizationId: number;
+    incidentId: number;
+    incidentTypeId?: number;
+}

package/dist/types/modules/entitlement/dtos/evaluate-entitlement.dto.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Service-to-service entitlement question. Sent by clarion-incident before an
+ * incident of class `Incident` is created, and by any other service that needs
+ * to know whether a user may reach the provider control room.
+ */
+export declare class EvaluateEntitlementDto {
+    userId: number;
+    organizationId: number;
+    incidentTypeId?: number;
+    autoEnrollTrial?: boolean;
+}

package/dist/types/modules/entitlement/dtos/grant-premium-trial.dto.d.ts

@@ -0,0 +1,8 @@
+/** Operator-initiated trial grant (or extension of an existing trial). */
+export declare class GrantPremiumTrialDto {
+    userId: number;
+    organizationId: number;
+    maxIncidents?: number;
+    durationDays?: number;
+    reason?: string;
+}

package/dist/types/modules/entitlement/dtos/revoke-premium-trial.dto.d.ts

@@ -0,0 +1,4 @@
+/** Operator-initiated trial revocation. */
+export declare class RevokePremiumTrialDto {
+    reason?: string;
+}

package/dist/types/modules/entitlement/enums/entitlement-decision-reason.enum.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Why an entitlement evaluation produced its tier. Persisted in the incident
+ * entitlement snapshot for audit/support and surfaced to the mobile client so it
+ * can pick the right subscription banner without a second round trip.
+ */
+export declare enum EntitlementDecisionReason {
+    /** An active subscription entitlement covers the requested incident type. */
+    ACTIVE_SUBSCRIPTION = "ACTIVE_SUBSCRIPTION",
+    /** No subscription, but an active premium trial with alerts remaining. */
+    ACTIVE_TRIAL = "ACTIVE_TRIAL",
+    /** The user has never held a subscription or trial for this organization. */
+    NO_ENTITLEMENT = "NO_ENTITLEMENT",
+    /** An entitlement exists but its package does not cover this incident type. */
+    INCIDENT_TYPE_NOT_COVERED = "INCIDENT_TYPE_NOT_COVERED",
+    /** The user's subscription lapsed — drives the "renew" banner on mobile. */
+    SUBSCRIPTION_EXPIRED = "SUBSCRIPTION_EXPIRED",
+    /** The trial period is still open but every trial alert has been used. */
+    TRIAL_EXHAUSTED = "TRIAL_EXHAUSTED",
+    /** The trial window elapsed. */
+    TRIAL_EXPIRED = "TRIAL_EXPIRED",
+    /** The trial was revoked by an operator. */
+    TRIAL_REVOKED = "TRIAL_REVOKED",
+    /** Trials are switched off for this organization/deployment. */
+    TRIAL_DISABLED = "TRIAL_DISABLED",
+    /** Entitlement does not gate this record (e.g. grievance class). */
+    NOT_APPLICABLE = "NOT_APPLICABLE",
+    /** Billing could not be reached; the configured fail-open/closed default applied. */
+    EVALUATION_UNAVAILABLE = "EVALUATION_UNAVAILABLE"
+}

package/dist/types/modules/entitlement/enums/incident-entitlement-scope.enum.d.ts

@@ -0,0 +1,14 @@
+/**
+ * List filter applied to incident queries.
+ *
+ *   ALL       — no entitlement filter (default; preserves legacy behaviour).
+ *   ENTITLED  — everything except Free-user incidents. Used by the primary admin
+ *               incident list, map and kanban views.
+ *   FREE      — only Free-user incidents. Backs the "Incident List - Free Users"
+ *               admin view.
+ */
+export declare enum IncidentEntitlementScope {
+    ALL = "ALL",
+    ENTITLED = "ENTITLED",
+    FREE = "FREE"
+}

package/dist/types/modules/entitlement/enums/incident-entitlement-tier.enum.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Premium entitlement classification stamped on every incident at creation time.
+ *
+ * The tier is derived server-side by clarion-billing and is NEVER accepted from a
+ * client payload. It drives three behaviours across the platform:
+ *
+ *   - `FREE` incidents are not published to the realtime (live-updates) channel,
+ *     are not auto-assigned to operators, and are hidden from the primary
+ *     admin incident list / map / kanban views.
+ *   - `PREMIUM` and `TRIAL` incidents behave exactly as incidents did before
+ *     entitlement enforcement (full provider routing + live updates).
+ *   - `NOT_APPLICABLE` covers everything entitlement does not gate: grievances,
+ *     incidents created before enforcement shipped, and any incident whose
+ *     entitlement could not be attributed to a user. It is treated as entitled
+ *     so historical and non-gated data keeps its existing behaviour.
+ */
+export declare enum IncidentEntitlementTier {
+    PREMIUM = "PREMIUM",
+    TRIAL = "TRIAL",
+    FREE = "FREE",
+    NOT_APPLICABLE = "NOT_APPLICABLE"
+}

package/dist/types/modules/entitlement/enums/premium-trial-source.enum.d.ts

@@ -0,0 +1,7 @@
+/** How a premium trial came to exist. */
+export declare enum PremiumTrialSource {
+    /** Created lazily the first time entitlement was evaluated for the user. */
+    AUTO_ENROLL = "AUTO_ENROLL",
+    /** Granted explicitly by an operator/admin. */
+    MANUAL_GRANT = "MANUAL_GRANT"
+}

package/dist/types/modules/entitlement/enums/premium-trial-status.enum.d.ts

@@ -0,0 +1,13 @@
+/** Lifecycle of a user's premium trial within one organization. */
+export declare enum PremiumTrialStatus {
+    /** Within the trial window with at least one alert remaining. */
+    ACTIVE = "ACTIVE",
+    /** Within the trial window but every allotted alert has been used. */
+    EXHAUSTED = "EXHAUSTED",
+    /** The trial window elapsed. */
+    EXPIRED = "EXPIRED",
+    /** Cancelled by an operator before it ran its course. */
+    REVOKED = "REVOKED",
+    /** Superseded because the user took out a paid subscription. */
+    CONVERTED = "CONVERTED"
+}

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

@@ -0,0 +1,12 @@
+export * from './enums/incident-entitlement-tier.enum';
+export * from './enums/incident-entitlement-scope.enum';
+export * from './enums/entitlement-decision-reason.enum';
+export * from './enums/premium-trial-status.enum';
+export * from './enums/premium-trial-source.enum';
+export * from './interfaces/entitlement-evaluation';
+export * from './constants/entitlement-defaults.const';
+export * from './dtos/evaluate-entitlement.dto';
+export * from './dtos/consume-trial-alert.dto';
+export * from './dtos/grant-premium-trial.dto';
+export * from './dtos/revoke-premium-trial.dto';
+export * from './utils/entitlement.util';

package/dist/types/modules/entitlement/interfaces/entitlement-evaluation.d.ts

@@ -0,0 +1,91 @@
+import { EntitlementDecisionReason } from '../enums/entitlement-decision-reason.enum';
+import { IncidentEntitlementTier } from '../enums/incident-entitlement-tier.enum';
+import { PremiumTrialSource } from '../enums/premium-trial-source.enum';
+import { PremiumTrialStatus } from '../enums/premium-trial-status.enum';
+/** Compact view of the subscription entitlement backing a premium decision. */
+export interface EntitlementSubscriptionSummary {
+    subscriptionId?: number | null;
+    packageId?: number | null;
+    packageName?: string | null;
+    /** `EntitlementSourceType` from clarion-billing (primary / member / beneficiary). */
+    sourceType?: string | null;
+    startsAt?: string | null;
+    expiresAt?: string | null;
+    /** Incident type ids the package covers. An empty array means "every type". */
+    incidentTypeIds?: number[];
+}
+/** Compact view of a user's premium trial within one organization. */
+export interface EntitlementTrialSummary {
+    trialId: number;
+    status: PremiumTrialStatus;
+    source: PremiumTrialSource;
+    /** Alerts the trial grants in total (default 2). */
+    maxIncidents: number;
+    incidentsUsed: number;
+    /** Never negative - clamped at zero once the allotment is spent. */
+    incidentsRemaining: number;
+    startsAt: string;
+    expiresAt: string;
+    /** Whole days left in the trial window; zero once elapsed. */
+    daysRemaining: number;
+}
+/**
+ * The single answer every caller needs about a user's premium standing.
+ *
+ * Produced by clarion-billing (`POST /billing/entitlements/evaluate` for
+ * service-to-service calls, `GET /billing/entitlements/me` for the mobile app)
+ * and consumed by clarion-incident to stamp the incident, and by the mobile app
+ * to pick its subscription banner.
+ */
+export interface EntitlementEvaluation {
+    userId: number;
+    organizationId: number;
+    tier: IncidentEntitlementTier;
+    /** True for PREMIUM/TRIAL/NOT_APPLICABLE - i.e. the alert reaches the provider. */
+    canAlertProvider: boolean;
+    reason: EntitlementDecisionReason;
+    evaluatedAt: string;
+    /** Echoes the incident type the decision was scoped to, when one was supplied. */
+    incidentTypeId?: number | null;
+    /**
+     * True when the answer was produced without a live billing decision (the
+     * caller's configured fail-open/fail-closed default applied). Never set by
+     * billing itself - only by clients that had to degrade.
+     */
+    degraded?: boolean;
+    /** Present when an ACTIVE subscription entitlement backs the decision. */
+    subscription?: EntitlementSubscriptionSummary | null;
+    /** Present whenever the user has a trial record, whatever its status. */
+    trial?: EntitlementTrialSummary | null;
+    /**
+     * Present when the user holds no active entitlement but previously had one
+     * that lapsed. Drives the mobile "your subscription expired - renew" banner,
+     * which must be distinguishable from a never-subscribed free user.
+     */
+    expiredSubscription?: EntitlementSubscriptionSummary | null;
+}
+/**
+ * Audit trail persisted alongside every incident (jsonb). Deliberately a
+ * point-in-time copy: re-evaluating later can produce a different answer, and
+ * incident history must reflect what was true when the alert was raised.
+ */
+export interface IncidentEntitlementSnapshot {
+    tier: IncidentEntitlementTier;
+    reason: EntitlementDecisionReason;
+    evaluatedAt: string;
+    /** The user the decision was made for (creator, or the reporter's system user). */
+    evaluatedUserId?: number | null;
+    degraded?: boolean;
+    subscriptionId?: number | null;
+    packageId?: number | null;
+    sourceType?: string | null;
+    trialId?: number | null;
+    /** Alerts left on the trial AFTER this incident consumed one, when applicable. */
+    trialIncidentsRemaining?: number | null;
+}
+/** Result of consuming one trial alert; idempotent per (trial, incident). */
+export interface TrialConsumptionResult {
+    /** False when the incident had already been counted against the trial. */
+    consumed: boolean;
+    trial: EntitlementTrialSummary | null;
+}

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

@@ -0,0 +1,22 @@
+import { IncidentEntitlementScope } from '../enums/incident-entitlement-scope.enum';
+import { IncidentEntitlementTier } from '../enums/incident-entitlement-tier.enum';
+import { PremiumTrialStatus } from '../enums/premium-trial-status.enum';
+/**
+ * Whether a tier reaches the provider control room.
+ *
+ * Everything except `FREE` counts as entitled: `NOT_APPLICABLE` covers
+ * grievances and pre-enforcement incidents, which must keep behaving exactly as
+ * they did before entitlement gating existed.
+ */
+export declare function isEntitledTier(tier?: IncidentEntitlementTier | string | null): boolean;
+/** Whether an incident was raised by a Free user (no subscription, no trial). */
+export declare function isFreeUserTier(tier?: IncidentEntitlementTier | string | null): boolean;
+/** True while the trial still grants premium behaviour. */
+export declare function isTrialUsable(status?: PremiumTrialStatus | string | null): boolean;
+/**
+ * Parses a client-supplied entitlement scope. Unknown/absent values fall back to
+ * `ALL` so an unrecognised query string never silently hides incidents.
+ */
+export declare function parseIncidentEntitlementScope(value?: string | null): IncidentEntitlementScope;
+/** Whole days remaining until `expiresAt`, floored at zero. */
+export declare function trialDaysRemaining(expiresAt: Date | string, now?: Date): number;

package/dist/types/modules/incident/intefaces/incident.d.ts

@@ -14,6 +14,8 @@ import { IncidentResponseUnitAssignment } from "./incident-response-unit-assignm
 import { IncidentType } from "./incident-type";
 import { IncidentReport } from "./incident-report";
 import { IncidentEmergencyType } from "../enums/incident-emergency-type.enum";
+import { IncidentEntitlementSnapshot } from "../../entitlement/interfaces/entitlement-evaluation";
+import { IncidentEntitlementTier } from "../../entitlement/enums/incident-entitlement-tier.enum";
 export interface Incident {
     id?: number;
     appId: IncidentAppId;
@@ -46,6 +48,15 @@ export interface Incident {
     workflowTaskQueueName: IncidentWorkflowTaskQueueName;
     controlCentreId: number;
     organizationId: number;
+    /**
+     * Premium standing of the reporting user at the moment the incident was
+     * raised. Derived server-side by clarion-billing - never accepted from a
+     * client payload. `FREE` incidents are withheld from live updates and from
+     * the primary admin list/map/kanban views.
+     */
+    entitlementTier?: IncidentEntitlementTier;
+    /** Point-in-time audit of how `entitlementTier` was decided. */
+    entitlementSnapshot?: IncidentEntitlementSnapshot | null;
     createdAt?: string;
     updatedAt?: string;
     category?: IncidentCategory;

package/dist/types/modules/system-user/constants/system-user.const.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Canonical environment variable that carries the platform "system user" id.
+ *
+ * The system user is a real row in the clarion-authentication `users` table
+ * that services stamp on records they create or mutate on their own behalf —
+ * i.e. when there is no authenticated human in the request (auto-assignment,
+ * automated status changes, service-to-service document uploads).
+ *
+ * It is deliberately NOT a compile-time constant: it is an environment-specific
+ * database row id, so dev / staging / production each carry their own value.
+ * The library owns the *contract* (key name, parsing, validation, fallback
+ * policy); the deployment owns the *value* (see clarion-deployment configmap).
+ */
+export declare const SYSTEM_USER_ID_ENV_KEY = "SYSTEM_USER_ID";
+/**
+ * Per-service keys that predate {@link SYSTEM_USER_ID_ENV_KEY}.
+ *
+ * Still read — in order — when the canonical key is absent, so that a rollback
+ * to an older ConfigMap does not take a service down. Remove once every
+ * environment has been migrated to the canonical key.
+ *
+ * @deprecated Set {@link SYSTEM_USER_ID_ENV_KEY} instead.
+ */
+export declare const LEGACY_SYSTEM_USER_ID_ENV_KEYS: readonly string[];

package/dist/types/modules/system-user/index.d.ts

@@ -0,0 +1,5 @@
+export * from './constants/system-user.const';
+export * from './interfaces/system-user-env-source';
+export * from './utils/system-user.util';
+export * from './services/system-user.service';
+export * from './system-user.module';

package/dist/types/modules/system-user/interfaces/system-user-env-source.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Minimal read surface needed to resolve the system user id.
+ *
+ * Structurally satisfied by `ConfigService` from `@nestjs/config`, so callers
+ * can pass their existing config service straight through without the shared
+ * library taking a hard dependency on it.
+ */
+export interface SystemUserEnvSource {
+    get<T = string>(key: string): T | undefined;
+}

package/dist/types/modules/system-user/services/system-user.service.d.ts

@@ -0,0 +1,26 @@
+import { OnModuleInit } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+/**
+ * Single source of truth for the platform system user id inside a service.
+ *
+ * Resolution happens once, on module init, so a mis-set `SYSTEM_USER_ID`
+ * fails the pod's startup probe instead of surfacing later as records stamped
+ * with a user id that clarion-authentication cannot resolve.
+ *
+ * @example
+ * constructor(private readonly systemUser: SystemUserService) {}
+ * ...
+ * const actorId = userContext?.userId ?? this.systemUser.id;
+ */
+export declare class SystemUserService implements OnModuleInit {
+    private readonly configService;
+    private readonly logger;
+    private resolvedId;
+    constructor(configService: ConfigService);
+    onModuleInit(): void;
+    /**
+     * The system user id. Throws if read before module init completed, which
+     * only happens if a provider resolves it inside its own constructor.
+     */
+    get id(): number;
+}

package/dist/types/modules/system-user/system-user.module.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Global module exposing {@link SystemUserService} to every provider in the
+ * host application. Import once in the service's root `AppModule`:
+ *
+ * @example
+ * @Module({ imports: [ConfigModule.forRoot({ ... }), SystemUserModule] })
+ * export class AppModule {}
+ *
+ * Requires `ConfigModule` to be global (the convention across clarion
+ * services) or otherwise available where this module is imported.
+ */
+export declare class SystemUserModule {
+}