grm-shared-library 1.1.190 → 1.1.192

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

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