clarion-shared-types 1.0.81 → 1.0.83

package/dist/esm/modules/entitlement/enums/entitlement-decision-reason.enum.js

@@ -0,0 +1,31 @@
+/**
+ * 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 var EntitlementDecisionReason;
+(function (EntitlementDecisionReason) {
+    /** An active subscription entitlement covers the requested incident type. */
+    EntitlementDecisionReason["ACTIVE_SUBSCRIPTION"] = "ACTIVE_SUBSCRIPTION";
+    /** No subscription, but an active premium trial with alerts remaining. */
+    EntitlementDecisionReason["ACTIVE_TRIAL"] = "ACTIVE_TRIAL";
+    /** The user has never held a subscription or trial for this organization. */
+    EntitlementDecisionReason["NO_ENTITLEMENT"] = "NO_ENTITLEMENT";
+    /** An entitlement exists but its package does not cover this incident type. */
+    EntitlementDecisionReason["INCIDENT_TYPE_NOT_COVERED"] = "INCIDENT_TYPE_NOT_COVERED";
+    /** The user's subscription lapsed — drives the "renew" banner on mobile. */
+    EntitlementDecisionReason["SUBSCRIPTION_EXPIRED"] = "SUBSCRIPTION_EXPIRED";
+    /** The trial period is still open but every trial alert has been used. */
+    EntitlementDecisionReason["TRIAL_EXHAUSTED"] = "TRIAL_EXHAUSTED";
+    /** The trial window elapsed. */
+    EntitlementDecisionReason["TRIAL_EXPIRED"] = "TRIAL_EXPIRED";
+    /** The trial was revoked by an operator. */
+    EntitlementDecisionReason["TRIAL_REVOKED"] = "TRIAL_REVOKED";
+    /** Trials are switched off for this organization/deployment. */
+    EntitlementDecisionReason["TRIAL_DISABLED"] = "TRIAL_DISABLED";
+    /** Entitlement does not gate this record (e.g. grievance class). */
+    EntitlementDecisionReason["NOT_APPLICABLE"] = "NOT_APPLICABLE";
+    /** Billing could not be reached; the configured fail-open/closed default applied. */
+    EntitlementDecisionReason["EVALUATION_UNAVAILABLE"] = "EVALUATION_UNAVAILABLE";
+})(EntitlementDecisionReason || (EntitlementDecisionReason = {}));
+//# sourceMappingURL=entitlement-decision-reason.enum.js.map

package/dist/esm/modules/entitlement/enums/entitlement-decision-reason.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlement-decision-reason.enum.js","sourceRoot":"","sources":["../../../../../src/modules/entitlement/enums/entitlement-decision-reason.enum.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAN,IAAY,yBAuBX;AAvBD,WAAY,yBAAyB;IACjC,6EAA6E;IAC7E,wEAA2C,CAAA;IAC3C,0EAA0E;IAC1E,0DAA6B,CAAA;IAC7B,6EAA6E;IAC7E,8DAAiC,CAAA;IACjC,+EAA+E;IAC/E,oFAAuD,CAAA;IACvD,4EAA4E;IAC5E,0EAA6C,CAAA;IAC7C,0EAA0E;IAC1E,gEAAmC,CAAA;IACnC,gCAAgC;IAChC,4DAA+B,CAAA;IAC/B,4CAA4C;IAC5C,4DAA+B,CAAA;IAC/B,gEAAgE;IAChE,8DAAiC,CAAA;IACjC,oEAAoE;IACpE,8DAAiC,CAAA;IACjC,qFAAqF;IACrF,8EAAiD,CAAA;AACrD,CAAC,EAvBW,yBAAyB,KAAzB,yBAAyB,QAuBpC"}

package/dist/esm/modules/entitlement/enums/incident-entitlement-scope.enum.js

@@ -0,0 +1,16 @@
+/**
+ * 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 var IncidentEntitlementScope;
+(function (IncidentEntitlementScope) {
+    IncidentEntitlementScope["ALL"] = "ALL";
+    IncidentEntitlementScope["ENTITLED"] = "ENTITLED";
+    IncidentEntitlementScope["FREE"] = "FREE";
+})(IncidentEntitlementScope || (IncidentEntitlementScope = {}));
+//# sourceMappingURL=incident-entitlement-scope.enum.js.map

package/dist/esm/modules/entitlement/enums/incident-entitlement-scope.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incident-entitlement-scope.enum.js","sourceRoot":"","sources":["../../../../../src/modules/entitlement/enums/incident-entitlement-scope.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,wBAIX;AAJD,WAAY,wBAAwB;IAChC,uCAAW,CAAA;IACX,iDAAqB,CAAA;IACrB,yCAAa,CAAA;AACjB,CAAC,EAJW,wBAAwB,KAAxB,wBAAwB,QAInC"}

package/dist/esm/modules/entitlement/enums/incident-entitlement-tier.enum.js

@@ -0,0 +1,24 @@
+/**
+ * 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 var IncidentEntitlementTier;
+(function (IncidentEntitlementTier) {
+    IncidentEntitlementTier["PREMIUM"] = "PREMIUM";
+    IncidentEntitlementTier["TRIAL"] = "TRIAL";
+    IncidentEntitlementTier["FREE"] = "FREE";
+    IncidentEntitlementTier["NOT_APPLICABLE"] = "NOT_APPLICABLE";
+})(IncidentEntitlementTier || (IncidentEntitlementTier = {}));
+//# sourceMappingURL=incident-entitlement-tier.enum.js.map

package/dist/esm/modules/entitlement/enums/incident-entitlement-tier.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incident-entitlement-tier.enum.js","sourceRoot":"","sources":["../../../../../src/modules/entitlement/enums/incident-entitlement-tier.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,uBAKX;AALD,WAAY,uBAAuB;IAC/B,8CAAmB,CAAA;IACnB,0CAAe,CAAA;IACf,wCAAa,CAAA;IACb,4DAAiC,CAAA;AACrC,CAAC,EALW,uBAAuB,KAAvB,uBAAuB,QAKlC"}

package/dist/esm/modules/entitlement/enums/premium-trial-source.enum.js

@@ -0,0 +1,9 @@
+/** How a premium trial came to exist. */
+export var PremiumTrialSource;
+(function (PremiumTrialSource) {
+    /** Created lazily the first time entitlement was evaluated for the user. */
+    PremiumTrialSource["AUTO_ENROLL"] = "AUTO_ENROLL";
+    /** Granted explicitly by an operator/admin. */
+    PremiumTrialSource["MANUAL_GRANT"] = "MANUAL_GRANT";
+})(PremiumTrialSource || (PremiumTrialSource = {}));
+//# sourceMappingURL=premium-trial-source.enum.js.map

package/dist/esm/modules/entitlement/enums/premium-trial-source.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"premium-trial-source.enum.js","sourceRoot":"","sources":["../../../../../src/modules/entitlement/enums/premium-trial-source.enum.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,MAAM,CAAN,IAAY,kBAKX;AALD,WAAY,kBAAkB;IAC1B,4EAA4E;IAC5E,iDAA2B,CAAA;IAC3B,+CAA+C;IAC/C,mDAA6B,CAAA;AACjC,CAAC,EALW,kBAAkB,KAAlB,kBAAkB,QAK7B"}

package/dist/esm/modules/entitlement/enums/premium-trial-status.enum.js

@@ -0,0 +1,15 @@
+/** Lifecycle of a user's premium trial within one organization. */
+export var PremiumTrialStatus;
+(function (PremiumTrialStatus) {
+    /** Within the trial window with at least one alert remaining. */
+    PremiumTrialStatus["ACTIVE"] = "ACTIVE";
+    /** Within the trial window but every allotted alert has been used. */
+    PremiumTrialStatus["EXHAUSTED"] = "EXHAUSTED";
+    /** The trial window elapsed. */
+    PremiumTrialStatus["EXPIRED"] = "EXPIRED";
+    /** Cancelled by an operator before it ran its course. */
+    PremiumTrialStatus["REVOKED"] = "REVOKED";
+    /** Superseded because the user took out a paid subscription. */
+    PremiumTrialStatus["CONVERTED"] = "CONVERTED";
+})(PremiumTrialStatus || (PremiumTrialStatus = {}));
+//# sourceMappingURL=premium-trial-status.enum.js.map

package/dist/esm/modules/entitlement/enums/premium-trial-status.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"premium-trial-status.enum.js","sourceRoot":"","sources":["../../../../../src/modules/entitlement/enums/premium-trial-status.enum.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,CAAN,IAAY,kBAWX;AAXD,WAAY,kBAAkB;IAC1B,iEAAiE;IACjE,uCAAiB,CAAA;IACjB,sEAAsE;IACtE,6CAAuB,CAAA;IACvB,gCAAgC;IAChC,yCAAmB,CAAA;IACnB,yDAAyD;IACzD,yCAAmB,CAAA;IACnB,gEAAgE;IAChE,6CAAuB,CAAA;AAC3B,CAAC,EAXW,kBAAkB,KAAlB,kBAAkB,QAW7B"}

package/dist/esm/modules/entitlement/index.js

@@ -0,0 +1,13 @@
+// Enums
+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';
+// Interfaces
+export * from './interfaces/entitlement-evaluation';
+// Constants
+export * from './constants/entitlement-defaults.const';
+// Utilities
+export * from './utils/entitlement.util';
+//# sourceMappingURL=index.js.map

package/dist/esm/modules/entitlement/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/entitlement/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,cAAc,wCAAwC,CAAC;AACvD,cAAc,yCAAyC,CAAC;AACxD,cAAc,0CAA0C,CAAC;AACzD,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAElD,aAAa;AACb,cAAc,qCAAqC,CAAC;AAEpD,YAAY;AACZ,cAAc,wCAAwC,CAAC;AAEvD,YAAY;AACZ,cAAc,0BAA0B,CAAC"}

package/dist/esm/modules/entitlement/interfaces/entitlement-evaluation.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entitlement-evaluation.js.map

package/dist/esm/modules/entitlement/interfaces/entitlement-evaluation.js.map

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

package/dist/esm/modules/entitlement/utils/entitlement.util.js

@@ -0,0 +1,42 @@
+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 function isEntitledTier(tier) {
+    return tier !== IncidentEntitlementTier.FREE;
+}
+/** Whether an incident was raised by a Free user (no subscription, no trial). */
+export function isFreeUserTier(tier) {
+    return tier === IncidentEntitlementTier.FREE;
+}
+/** True while the trial still grants premium behaviour. */
+export function isTrialUsable(status) {
+    return status === PremiumTrialStatus.ACTIVE;
+}
+/**
+ * Parses a client-supplied entitlement scope. Unknown/absent values fall back to
+ * `ALL` so an unrecognised query string never silently hides incidents.
+ */
+export function parseIncidentEntitlementScope(value) {
+    if (!value)
+        return IncidentEntitlementScope.ALL;
+    const normalized = value.trim().toUpperCase();
+    return Object.values(IncidentEntitlementScope).includes(normalized)
+        ? normalized
+        : IncidentEntitlementScope.ALL;
+}
+/** Whole days remaining until `expiresAt`, floored at zero. */
+export function trialDaysRemaining(expiresAt, now = new Date()) {
+    const end = expiresAt instanceof Date ? expiresAt : new Date(expiresAt);
+    const ms = end.getTime() - now.getTime();
+    if (!Number.isFinite(ms) || ms <= 0)
+        return 0;
+    return Math.ceil(ms / (24 * 60 * 60 * 1000));
+}
+//# sourceMappingURL=entitlement.util.js.map

package/dist/esm/modules/entitlement/utils/entitlement.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlement.util.js","sourceRoot":"","sources":["../../../../../src/modules/entitlement/utils/entitlement.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAA8C;IACzE,OAAO,IAAI,KAAK,uBAAuB,CAAC,IAAI,CAAC;AACjD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,IAA8C;IACzE,OAAO,IAAI,KAAK,uBAAuB,CAAC,IAAI,CAAC;AACjD,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,MAA2C;IACrE,OAAO,MAAM,KAAK,kBAAkB,CAAC,MAAM,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CACzC,KAAqB;IAErB,IAAI,CAAC,KAAK;QAAE,OAAO,wBAAwB,CAAC,GAAG,CAAC;IAChD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,OAAQ,MAAM,CAAC,MAAM,CAAC,wBAAwB,CAAc,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC7E,CAAC,CAAE,UAAuC;QAC1C,CAAC,CAAC,wBAAwB,CAAC,GAAG,CAAC;AACvC,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,kBAAkB,CAAC,SAAwB,EAAE,MAAY,IAAI,IAAI,EAAE;IAC/E,MAAM,GAAG,GAAG,SAAS,YAAY,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IACxE,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;IACzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/dist/types/index.d.ts

@@ -17,5 +17,7 @@ export * from './modules/notification/index';
 export * from './modules/chat/index';
 export * from './modules/country/index';
 export * from './modules/tracking/index';
+export * from './modules/entitlement/index';
+export * from './modules/alert-dispatch/index';
 export * from './modules/common/interfaces/server-message';
 export * from './modules/common/interfaces/pagination';

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

@@ -0,0 +1,22 @@
+/**
+ * List filter applied to incident queries on the *dispatch* dimension - i.e.
+ * whether the reporter asked for the service provider to be alerted at all.
+ *
+ *   ALL         - no dispatch filter (default; preserves legacy behaviour).
+ *   DISPATCHED  - only incidents the provider was asked to receive. Used by the
+ *                 primary admin incident list, map and kanban views.
+ *   SUPPRESSED  - only incidents the reporter explicitly withheld from the
+ *                 provider. Backs the "Incident List - Marked Ignore" admin
+ *                 view.
+ *
+ * Deliberately separate from {@link IncidentEntitlementScope}: entitlement is a
+ * billing fact about the reporter, dispatch is a choice the reporter made on
+ * this one alert. The two compose - the control room asks for
+ * `ENTITLED` + `DISPATCHED`, "Marked Ignore" asks for `ENTITLED` + `SUPPRESSED`,
+ * and "Free Users" asks for `FREE` on the entitlement dimension alone.
+ */
+export declare enum IncidentDispatchScope {
+    ALL = "ALL",
+    DISPATCHED = "DISPATCHED",
+    SUPPRESSED = "SUPPRESSED"
+}

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

@@ -0,0 +1,3 @@
+export * from './enums/incident-dispatch-scope.enum';
+export * from './interfaces/alert-dispatch';
+export * from './utils/alert-dispatch.util';

package/dist/types/modules/alert-dispatch/interfaces/alert-dispatch.d.ts

@@ -0,0 +1,33 @@
+import { IncidentEntitlementTier } from '../../entitlement/enums/incident-entitlement-tier.enum';
+/**
+ * Who an incident's alert was actually dispatched to.
+ *
+ * Both flags are resolved server-side at creation and then stored on the
+ * incident, so every downstream consumer (realtime publisher, notification
+ * service, admin lists, the mobile confirmation dialog) reads one recorded fact
+ * rather than re-deriving policy. `undefined` means "not recorded" and is
+ * always treated as `true`, which is what every incident written before this
+ * existed implicitly did.
+ */
+export interface IncidentAlertDispatch {
+    /**
+     * False when the alert must not reach the provider control room: the
+     * reporter unchecked the option, or they are a Free user who never had it.
+     */
+    notifyServiceProvider?: boolean;
+    /**
+     * False when the reporter's guardians must not be pulled into the incident
+     * chat or notified about the alert.
+     */
+    notifyGuardians?: boolean;
+}
+/** The inputs {@link resolveIncidentAlertDispatch} decides from. */
+export interface AlertDispatchRequest extends IncidentAlertDispatch {
+    /** Entitlement tier already decided for this incident. */
+    tier?: IncidentEntitlementTier | string | null;
+    /**
+     * False for records that predate or sit outside the SOS flow (grievances,
+     * operator-created incidents), which keep both channels on.
+     */
+    applies?: boolean;
+}

package/dist/types/modules/alert-dispatch/utils/alert-dispatch.util.d.ts

@@ -0,0 +1,51 @@
+import { IncidentEntitlementTier } from '../../entitlement/enums/incident-entitlement-tier.enum';
+import { IncidentDispatchScope } from '../enums/incident-dispatch-scope.enum';
+import { AlertDispatchRequest, IncidentAlertDispatch } from '../interfaces/alert-dispatch';
+/**
+ * Whether an incident reaches the provider control room - live map, live list,
+ * kanban, operator assignment and operator notifications.
+ *
+ * Two independent reasons keep an alert out, and this is the single place both
+ * are expressed so no consumer can honour one and forget the other:
+ *
+ *   1. the reporter is a Free user, so the provider was never entitled to it;
+ *   2. the reporter explicitly unchecked the provider option ("Marked Ignore").
+ *
+ * A missing flag counts as dispatched: incidents written before this feature
+ * existed, and every operator-created record, keep their original behaviour.
+ */
+export declare function reachesControlRoom(incident: IncidentAlertDispatch & {
+    entitlementTier?: IncidentEntitlementTier | string | null;
+}): boolean;
+/** Whether the reporter's guardians should be pulled in and notified. */
+export declare function reachesGuardians(incident: IncidentAlertDispatch): boolean;
+/**
+ * Whether the reporter deliberately withheld this alert from the provider, as
+ * opposed to never having been entitled to send it. Only the former belongs in
+ * the "Marked Ignore" admin list; a Free user's alert belongs in
+ * "Incident List - Free Users".
+ */
+export declare function isMarkedIgnore(incident: IncidentAlertDispatch & {
+    entitlementTier?: IncidentEntitlementTier | string | null;
+}): boolean;
+/**
+ * Applies dispatch policy to what the client asked for.
+ *
+ * The client's checkboxes are an intent, never the decision: a Free user's
+ * provider option is unchecked and read-only in the app, and this is what makes
+ * that true even for a caller that ignores the UI. Anything the client omits
+ * defaults to "notify", so existing callers (web admin, older app builds) are
+ * unaffected.
+ *
+ * Returns resolved flags only - it deliberately does not reject the
+ * both-off combination, so callers can decide whether that is a validation
+ * error (the SOS path) or simply nobody to notify.
+ */
+export declare function resolveIncidentAlertDispatch(request: AlertDispatchRequest): Required<IncidentAlertDispatch>;
+/** True when an alert would reach nobody at all. */
+export declare function reachesNobody(dispatch: IncidentAlertDispatch): boolean;
+/**
+ * Parses a client-supplied dispatch scope. Unknown/absent values fall back to
+ * `ALL` so an unrecognised query string never silently hides incidents.
+ */
+export declare function parseIncidentDispatchScope(value?: string | null): IncidentDispatchScope;

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

@@ -5,6 +5,7 @@ import { Organization } from "../../organization";
 import { ResponseUnit } from "../../response-unit";
 import { User } from "../../user";
 import { WebNotification } from "../../web-notification";
+import { IncidentEntitlementScope } from "../../entitlement/enums/incident-entitlement-scope.enum";
 export interface PaginationParams {
     page?: number;
     limit?: number;
@@ -12,6 +13,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 returns everything.
+ */
+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/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,8 @@
+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 './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;
@@ -41,6 +43,25 @@ export interface Incident {
     workflowTaskQueueName: IncidentWorkflowTaskQueueName;
     controlCentreId: number;
     organizationId: number;
+    /**
+     * Premium standing of the reporting user when the alert was raised, decided
+     * server-side by clarion-billing. The primary incident list, map and kanban
+     * views exclude FREE incidents; the dedicated "Incident List - Free Users"
+     * view shows only those.
+     */
+    entitlementTier?: IncidentEntitlementTier;
+    /** Point-in-time audit of how `entitlementTier` was decided. */
+    entitlementSnapshot?: IncidentEntitlementSnapshot | null;
+    /**
+     * Who the reporter asked to be alerted, resolved against their entitlement
+     * at creation. `false` on the provider flag withholds the incident from the
+     * control room exactly as a FREE tier does, and lands it in the
+     * "Incident List - Marked Ignore" view instead; `false` on the guardian flag
+     * kept guardians out of the incident chat and its notifications. Absent on
+     * incidents raised before the options existed, which notified both.
+     */
+    notifyServiceProvider?: boolean;
+    notifyGuardians?: boolean;
     createdAt?: string;
     updatedAt?: string;
     category?: IncidentCategory;

package/package.json

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