@heavybit/pendoadmin-shared-lib 1.4.0 → 1.6.0

package/dist/common/index.d.ts

@@ -3,4 +3,6 @@ export * from './phone.utils.js';
 export * from './password.utils.js';
 export * from './uuid.utils.js';
 export * from './response.utils.js';
+export * from './timezone.utils.js';
+export * from './permission.utils.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC"}

package/dist/common/index.js

@@ -3,4 +3,6 @@ export * from './phone.utils.js';
 export * from './password.utils.js';
 export * from './uuid.utils.js';
 export * from './response.utils.js';
+export * from './timezone.utils.js';
+export * from './permission.utils.js';
 //# sourceMappingURL=index.js.map

package/dist/common/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC"}

package/dist/common/permission.utils.d.ts

@@ -0,0 +1,11 @@
+import type { IAuthUser } from '../types/index.js';
+/** The API-key scope that grants every permission the key's company has. */
+export declare const ALL_PERMISSIONS_SCOPE = "*";
+export type PermissionHolder = Pick<IAuthUser, 'isSuperAdmin' | 'permissions'>;
+/**
+ * True when the user may act with ANY of the listed permissions: super admins always,
+ * API keys holding the '*' scope always, otherwise when one of the permissions is granted.
+ * This is the rule `requirePermission` enforces; use it for in-service checks so the two never drift.
+ */
+export declare function hasPermission(user: PermissionHolder | null | undefined, ...permissions: string[]): boolean;
+//# sourceMappingURL=permission.utils.d.ts.map

package/dist/common/permission.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.utils.d.ts","sourceRoot":"","sources":["../../src/common/permission.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC;AAE/E;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAK1G"}

package/dist/common/permission.utils.js

@@ -0,0 +1,16 @@
+/** The API-key scope that grants every permission the key's company has. */
+export const ALL_PERMISSIONS_SCOPE = '*';
+/**
+ * True when the user may act with ANY of the listed permissions: super admins always,
+ * API keys holding the '*' scope always, otherwise when one of the permissions is granted.
+ * This is the rule `requirePermission` enforces; use it for in-service checks so the two never drift.
+ */
+export function hasPermission(user, ...permissions) {
+    if (!user)
+        return false;
+    if (user.isSuperAdmin)
+        return true;
+    const granted = user.permissions ?? [];
+    return granted.includes(ALL_PERMISSIONS_SCOPE) || permissions.some(p => granted.includes(p));
+}
+//# sourceMappingURL=permission.utils.js.map

package/dist/common/permission.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.utils.js","sourceRoot":"","sources":["../../src/common/permission.utils.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAIzC;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAyC,EAAE,GAAG,WAAqB;IAC/F,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;IACvC,OAAO,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/F,CAAC"}

package/dist/common/timezone.utils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * IANA timezone helpers.
+ *
+ * The database stores UTC; these helpers convert only at display time using
+ * the zone's own DST rules via Intl. Never pass a fixed offset ("+03:00",
+ * "GMT+3") as a timezone — those are rejected.
+ */
+/**
+ * Canonical casing of a valid IANA zone (e.g. "africa/nairobi" → "Africa/Nairobi"),
+ * or null when the value is not a valid IANA zone.
+ */
+export declare function normalizeTimezone(tz: unknown): string | null;
+/** True when `tz` is an IANA timezone identifier Intl can format with. */
+export declare function isValidIanaTimezone(tz: unknown): tz is string;
+/**
+ * Platform default for users whose timezone has never been observed.
+ * Overridable with DEFAULT_USER_TIMEZONE; an invalid override is ignored.
+ */
+export declare const DEFAULT_TIMEZONE: string;
+/** Returns `tz` (canonicalised) when valid, otherwise `fallback`. Never throws. */
+export declare function resolveTimezone(tz: unknown, fallback?: string): string;
+export interface FormatInTimezoneOptions {
+    /** Zone used when `tz` is missing or invalid. Defaults to DEFAULT_TIMEZONE. */
+    fallback?: string;
+    /** 12-hour clock ("2:05 PM") instead of the default 24-hour ("14:05"). */
+    hour12?: boolean;
+}
+export interface FormattedInTimezone {
+    /** e.g. "26 Sep 2026, 14:05 GMT+3 (Africa/Nairobi)" or "26 Oct 2026, 09:00 GMT"; '' for an invalid instant. */
+    text: string;
+    /** The IANA zone actually used. */
+    timezone: string;
+    /** True when `tz` was missing/invalid and the fallback zone was used. */
+    usedFallback: boolean;
+}
+/**
+ * Formats a UTC instant as local time in `tz`, including the zone.
+ * Invalid `tz` → fallback zone with `usedFallback: true`. Invalid instant → `text: ''`. Never throws.
+ */
+export declare function formatInTimezone(instant: Date | string | number, tz: unknown, opts?: FormatInTimezoneOptions): FormattedInTimezone;
+//# sourceMappingURL=timezone.utils.d.ts.map

package/dist/common/timezone.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezone.utils.d.ts","sourceRoot":"","sources":["../../src/common/timezone.utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAa5D;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAE7D;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAER,CAAC;AAExB,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAyB,GAAG,MAAM,CAExF;AAED,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,YAAY,EAAE,OAAO,CAAC;CACvB;AAsBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAC/B,EAAE,EAAE,OAAO,EACX,IAAI,GAAE,uBAA4B,GACjC,mBAAmB,CA4BrB"}

package/dist/common/timezone.utils.js

@@ -0,0 +1,106 @@
+/**
+ * IANA timezone helpers.
+ *
+ * The database stores UTC; these helpers convert only at display time using
+ * the zone's own DST rules via Intl. Never pass a fixed offset ("+03:00",
+ * "GMT+3") as a timezone — those are rejected.
+ */
+const MAX_TIMEZONE_LENGTH = 100;
+const HARD_DEFAULT_TIMEZONE = 'Africa/Nairobi';
+/** Raw UTC offsets are not IANA zones, even where some Intl builds accept them. */
+const RAW_OFFSET_PATTERN = /^(?:[+-]\d|(?:GMT|UTC)\s*[+-]\s*\d)/i;
+/** A zone abbreviation Intl could not name, e.g. "GMT+3" or "GMT-04:30". */
+const OFFSET_ABBREVIATION_PATTERN = /^(?:GMT|UTC)[+-]/;
+let supportedZones;
+function getSupportedZones() {
+    if (supportedZones === undefined) {
+        const supportedValuesOf = Intl.supportedValuesOf;
+        supportedZones = typeof supportedValuesOf === 'function' ? new Set(supportedValuesOf('timeZone')) : null;
+    }
+    return supportedZones;
+}
+/**
+ * Canonical casing of a valid IANA zone (e.g. "africa/nairobi" → "Africa/Nairobi"),
+ * or null when the value is not a valid IANA zone.
+ */
+export function normalizeTimezone(tz) {
+    if (typeof tz !== 'string')
+        return null;
+    const value = tz.trim();
+    if (!value || value.length > MAX_TIMEZONE_LENGTH || RAW_OFFSET_PATTERN.test(value))
+        return null;
+    if (getSupportedZones()?.has(value))
+        return value;
+    // Not in the canonical list: still accept aliases Intl understands (e.g. "UTC", "Asia/Calcutta").
+    try {
+        return new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `tz` is an IANA timezone identifier Intl can format with. */
+export function isValidIanaTimezone(tz) {
+    return normalizeTimezone(tz) !== null;
+}
+/**
+ * Platform default for users whose timezone has never been observed.
+ * Overridable with DEFAULT_USER_TIMEZONE; an invalid override is ignored.
+ */
+export const DEFAULT_TIMEZONE = normalizeTimezone(typeof process !== 'undefined' ? process.env?.DEFAULT_USER_TIMEZONE : undefined) ??
+    HARD_DEFAULT_TIMEZONE;
+/** Returns `tz` (canonicalised) when valid, otherwise `fallback`. Never throws. */
+export function resolveTimezone(tz, fallback = DEFAULT_TIMEZONE) {
+    return normalizeTimezone(tz) ?? normalizeTimezone(fallback) ?? HARD_DEFAULT_TIMEZONE;
+}
+function toDate(instant) {
+    const date = instant instanceof Date ? instant : new Date(instant);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+function zoneAbbreviation(date, timeZone) {
+    // en-US names US zones (EDT, PST), en-GB names UK ones (BST, GMT); other zones come back as "GMT+3".
+    for (const locale of ['en-US', 'en-GB']) {
+        const name = new Intl.DateTimeFormat(locale, { timeZone, timeZoneName: 'short' })
+            .formatToParts(date)
+            .find((part) => part.type === 'timeZoneName')?.value;
+        if (name && !OFFSET_ABBREVIATION_PATTERN.test(name))
+            return name;
+    }
+    const offset = new Intl.DateTimeFormat('en-GB', { timeZone, timeZoneName: 'short' })
+        .formatToParts(date)
+        .find((part) => part.type === 'timeZoneName')?.value;
+    // An offset alone is ambiguous across zones and DST, so name the zone too.
+    return offset ? `${offset} (${timeZone})` : timeZone;
+}
+/**
+ * Formats a UTC instant as local time in `tz`, including the zone.
+ * Invalid `tz` → fallback zone with `usedFallback: true`. Invalid instant → `text: ''`. Never throws.
+ */
+export function formatInTimezone(instant, tz, opts = {}) {
+    const requested = normalizeTimezone(tz);
+    const timezone = requested ?? resolveTimezone(opts.fallback);
+    const usedFallback = requested === null;
+    const date = toDate(instant);
+    if (!date)
+        return { text: '', timezone, usedFallback };
+    try {
+        const parts = Object.fromEntries(new Intl.DateTimeFormat('en-US', {
+            timeZone: timezone,
+            day: 'numeric',
+            month: 'short',
+            year: 'numeric',
+            hour: opts.hour12 ? 'numeric' : '2-digit',
+            minute: '2-digit',
+            hourCycle: opts.hour12 ? 'h12' : 'h23',
+        })
+            .formatToParts(date)
+            .map((part) => [part.type, part.value]));
+        const time = `${parts.hour}:${parts.minute}${opts.hour12 ? ` ${parts.dayPeriod}` : ''}`;
+        const text = `${parts.day} ${parts.month} ${parts.year}, ${time} ${zoneAbbreviation(date, timezone)}`;
+        return { text, timezone, usedFallback };
+    }
+    catch {
+        return { text: '', timezone, usedFallback };
+    }
+}
+//# sourceMappingURL=timezone.utils.js.map

package/dist/common/timezone.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezone.utils.js","sourceRoot":"","sources":["../../src/common/timezone.utils.ts"],"names":[],"mappings":"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"}

package/dist/express/permission.guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission.guard.d.ts","sourceRoot":"","sources":["../../src/express/permission.guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE/D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,IAChD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAoB/D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,IACpD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAmB/D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,IACpC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAe/D"}
+{"version":3,"file":"permission.guard.d.ts","sourceRoot":"","sources":["../../src/express/permission.guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG/D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,IAChD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAgB/D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,IACpD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAmB/D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,IACpC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAe/D"}

package/dist/express/permission.guard.js

@@ -1,3 +1,4 @@
+import { hasPermission } from '../common/permission.utils.js';
 /**
  * Require a specific permission. Superadmins bypass all checks.
  */
@@ -7,11 +8,7 @@ export function requirePermission(...permissions) {
             res.status(401).json({ success: false, message: 'Authentication required' });
             return;
         }
-        if (req.user.isSuperAdmin)
-            return next();
-        // API keys may hold the '*' scope meaning all permissions the key's company has.
-        const hasPermission = req.user.permissions.includes('*') || permissions.some(p => req.user.permissions.includes(p));
-        if (!hasPermission) {
+        if (!hasPermission(req.user, ...permissions)) {
             res.status(403).json({
                 success: false,
                 message: 'Insufficient permissions',

package/dist/express/permission.guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"permission.guard.js","sourceRoot":"","sources":["../../src/express/permission.guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"permission.guard.js","sourceRoot":"","sources":["../../src/express/permission.guard.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE9D;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAG,WAAqB;IACxD,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAQ,EAAE;QAC/D,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YACd,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAC;YAC7E,OAAO;QACT,CAAC;QAED,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC;YAC7C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,OAAO,EAAE,0BAA0B;gBACnC,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE;aAClC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAG,WAAqB;IAC5D,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAQ,EAAE;QAC/D,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YACd,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAC;YAC7E,OAAO;QACT,CAAC;QAED,IAAI,GAAG,CAAC,IAAI,CAAC,YAAY;YAAE,OAAO,IAAI,EAAE,CAAC;QAEzC,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,IAAK,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,OAAO,EAAE,0BAA0B;gBACnC,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE;aAClC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG,KAAe;IAC5C,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAQ,EAAE;QAC/D,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YACd,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAC;YAC7E,OAAO;QACT,CAAC;QAED,IAAI,GAAG,CAAC,IAAI,CAAC,YAAY;YAAE,OAAO,IAAI,EAAE,CAAC;QAEzC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,IAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC,CAAC;YACvE,OAAO;QACT,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heavybit/pendoadmin-shared-lib",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Shared library for PendoAdmin microservices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,7 +28,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test": "npm run build && node --test tests/"
   },
   "exports": {
     ".": "./dist/index.js",

package/src/common/index.ts

@@ -3,3 +3,5 @@ export * from './phone.utils.js';
 export * from './password.utils.js';
 export * from './uuid.utils.js';
 export * from './response.utils.js';
+export * from './timezone.utils.js';
+export * from './permission.utils.js';

package/src/common/permission.utils.ts

@@ -0,0 +1,18 @@
+import type { IAuthUser } from '../types/index.js';
+
+/** The API-key scope that grants every permission the key's company has. */
+export const ALL_PERMISSIONS_SCOPE = '*';
+
+export type PermissionHolder = Pick<IAuthUser, 'isSuperAdmin' | 'permissions'>;
+
+/**
+ * True when the user may act with ANY of the listed permissions: super admins always,
+ * API keys holding the '*' scope always, otherwise when one of the permissions is granted.
+ * This is the rule `requirePermission` enforces; use it for in-service checks so the two never drift.
+ */
+export function hasPermission(user: PermissionHolder | null | undefined, ...permissions: string[]): boolean {
+  if (!user) return false;
+  if (user.isSuperAdmin) return true;
+  const granted = user.permissions ?? [];
+  return granted.includes(ALL_PERMISSIONS_SCOPE) || permissions.some(p => granted.includes(p));
+}

package/src/common/timezone.utils.ts

@@ -0,0 +1,137 @@
+/**
+ * IANA timezone helpers.
+ *
+ * The database stores UTC; these helpers convert only at display time using
+ * the zone's own DST rules via Intl. Never pass a fixed offset ("+03:00",
+ * "GMT+3") as a timezone — those are rejected.
+ */
+
+const MAX_TIMEZONE_LENGTH = 100;
+const HARD_DEFAULT_TIMEZONE = 'Africa/Nairobi';
+
+/** Raw UTC offsets are not IANA zones, even where some Intl builds accept them. */
+const RAW_OFFSET_PATTERN = /^(?:[+-]\d|(?:GMT|UTC)\s*[+-]\s*\d)/i;
+
+/** A zone abbreviation Intl could not name, e.g. "GMT+3" or "GMT-04:30". */
+const OFFSET_ABBREVIATION_PATTERN = /^(?:GMT|UTC)[+-]/;
+
+let supportedZones: Set<string> | null | undefined;
+
+function getSupportedZones(): Set<string> | null {
+  if (supportedZones === undefined) {
+    const supportedValuesOf = (Intl as { supportedValuesOf?: (key: string) => string[] }).supportedValuesOf;
+    supportedZones = typeof supportedValuesOf === 'function' ? new Set(supportedValuesOf('timeZone')) : null;
+  }
+  return supportedZones;
+}
+
+/**
+ * Canonical casing of a valid IANA zone (e.g. "africa/nairobi" → "Africa/Nairobi"),
+ * or null when the value is not a valid IANA zone.
+ */
+export function normalizeTimezone(tz: unknown): string | null {
+  if (typeof tz !== 'string') return null;
+  const value = tz.trim();
+  if (!value || value.length > MAX_TIMEZONE_LENGTH || RAW_OFFSET_PATTERN.test(value)) return null;
+
+  if (getSupportedZones()?.has(value)) return value;
+
+  // Not in the canonical list: still accept aliases Intl understands (e.g. "UTC", "Asia/Calcutta").
+  try {
+    return new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone;
+  } catch {
+    return null;
+  }
+}
+
+/** True when `tz` is an IANA timezone identifier Intl can format with. */
+export function isValidIanaTimezone(tz: unknown): tz is string {
+  return normalizeTimezone(tz) !== null;
+}
+
+/**
+ * Platform default for users whose timezone has never been observed.
+ * Overridable with DEFAULT_USER_TIMEZONE; an invalid override is ignored.
+ */
+export const DEFAULT_TIMEZONE: string =
+  normalizeTimezone(typeof process !== 'undefined' ? process.env?.DEFAULT_USER_TIMEZONE : undefined) ??
+  HARD_DEFAULT_TIMEZONE;
+
+/** Returns `tz` (canonicalised) when valid, otherwise `fallback`. Never throws. */
+export function resolveTimezone(tz: unknown, fallback: string = DEFAULT_TIMEZONE): string {
+  return normalizeTimezone(tz) ?? normalizeTimezone(fallback) ?? HARD_DEFAULT_TIMEZONE;
+}
+
+export interface FormatInTimezoneOptions {
+  /** Zone used when `tz` is missing or invalid. Defaults to DEFAULT_TIMEZONE. */
+  fallback?: string;
+  /** 12-hour clock ("2:05 PM") instead of the default 24-hour ("14:05"). */
+  hour12?: boolean;
+}
+
+export interface FormattedInTimezone {
+  /** e.g. "26 Sep 2026, 14:05 GMT+3 (Africa/Nairobi)" or "26 Oct 2026, 09:00 GMT"; '' for an invalid instant. */
+  text: string;
+  /** The IANA zone actually used. */
+  timezone: string;
+  /** True when `tz` was missing/invalid and the fallback zone was used. */
+  usedFallback: boolean;
+}
+
+function toDate(instant: Date | string | number): Date | null {
+  const date = instant instanceof Date ? instant : new Date(instant);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function zoneAbbreviation(date: Date, timeZone: string): string {
+  // en-US names US zones (EDT, PST), en-GB names UK ones (BST, GMT); other zones come back as "GMT+3".
+  for (const locale of ['en-US', 'en-GB']) {
+    const name = new Intl.DateTimeFormat(locale, { timeZone, timeZoneName: 'short' })
+      .formatToParts(date)
+      .find((part) => part.type === 'timeZoneName')?.value;
+    if (name && !OFFSET_ABBREVIATION_PATTERN.test(name)) return name;
+  }
+  const offset = new Intl.DateTimeFormat('en-GB', { timeZone, timeZoneName: 'short' })
+    .formatToParts(date)
+    .find((part) => part.type === 'timeZoneName')?.value;
+  // An offset alone is ambiguous across zones and DST, so name the zone too.
+  return offset ? `${offset} (${timeZone})` : timeZone;
+}
+
+/**
+ * Formats a UTC instant as local time in `tz`, including the zone.
+ * Invalid `tz` → fallback zone with `usedFallback: true`. Invalid instant → `text: ''`. Never throws.
+ */
+export function formatInTimezone(
+  instant: Date | string | number,
+  tz: unknown,
+  opts: FormatInTimezoneOptions = {},
+): FormattedInTimezone {
+  const requested = normalizeTimezone(tz);
+  const timezone = requested ?? resolveTimezone(opts.fallback);
+  const usedFallback = requested === null;
+
+  const date = toDate(instant);
+  if (!date) return { text: '', timezone, usedFallback };
+
+  try {
+    const parts = Object.fromEntries(
+      new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        day: 'numeric',
+        month: 'short',
+        year: 'numeric',
+        hour: opts.hour12 ? 'numeric' : '2-digit',
+        minute: '2-digit',
+        hourCycle: opts.hour12 ? 'h12' : 'h23',
+      })
+        .formatToParts(date)
+        .map((part) => [part.type, part.value]),
+    );
+    const time = `${parts.hour}:${parts.minute}${opts.hour12 ? ` ${parts.dayPeriod}` : ''}`;
+    const text = `${parts.day} ${parts.month} ${parts.year}, ${time} ${zoneAbbreviation(date, timezone)}`;
+    return { text, timezone, usedFallback };
+  } catch {
+    return { text: '', timezone, usedFallback };
+  }
+}

package/src/express/permission.guard.ts

@@ -1,4 +1,5 @@
 import type { Request, Response, NextFunction } from 'express';
+import { hasPermission } from '../common/permission.utils.js';
 
 /**
  * Require a specific permission. Superadmins bypass all checks.
@@ -10,11 +11,7 @@ export function requirePermission(...permissions: string[]) {
       return;
     }
 
-    if (req.user.isSuperAdmin) return next();
-
-    // API keys may hold the '*' scope meaning all permissions the key's company has.
-    const hasPermission = req.user!.permissions.includes('*') || permissions.some(p => req.user!.permissions.includes(p));
-    if (!hasPermission) {
+    if (!hasPermission(req.user, ...permissions)) {
       res.status(403).json({
         success: false,
         message: 'Insufficient permissions',

package/tests/permission.utils.test.mjs

@@ -0,0 +1,59 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { hasPermission, ALL_PERMISSIONS_SCOPE } from '../dist/common/index.js';
+import { requirePermission } from '../dist/express/index.js';
+
+const user = (permissions, isSuperAdmin = false) => ({ permissions, isSuperAdmin });
+
+describe('hasPermission', () => {
+  test('grants when any listed permission is held', () => {
+    assert.equal(hasPermission(user(['users:read']), 'users.security:read', 'users:read'), true);
+  });
+
+  test('denies when none of the permissions is held', () => {
+    assert.equal(hasPermission(user(['users:read']), 'users.security:read'), false);
+    assert.equal(hasPermission(user([]), 'users:read'), false);
+  });
+
+  test('super admins always pass', () => {
+    assert.equal(hasPermission(user([], true), 'anything'), true);
+  });
+
+  test("the '*' API-key scope grants every permission", () => {
+    assert.equal(ALL_PERMISSIONS_SCOPE, '*');
+    assert.equal(hasPermission(user(['*']), 'users.security:read'), true);
+  });
+
+  test('no user, or missing permissions array, is denied', () => {
+    assert.equal(hasPermission(null, 'users:read'), false);
+    assert.equal(hasPermission(undefined, 'users:read'), false);
+    assert.equal(hasPermission({ isSuperAdmin: false }, 'users:read'), false);
+  });
+
+  test('no permissions listed is denied for a normal user', () => {
+    assert.equal(hasPermission(user(['users:read'])), false);
+  });
+});
+
+describe('requirePermission uses the same rule', () => {
+  function run(reqUser, ...perms) {
+    const res = { code: 200, status(c) { this.code = c; return this; }, json() { return this; } };
+    let nextCalled = false;
+    requirePermission(...perms)({ user: reqUser }, res, () => { nextCalled = true; });
+    return { nextCalled, code: res.code };
+  }
+
+  test('401 without a user', () => {
+    assert.deepEqual(run(undefined, 'x'), { nextCalled: false, code: 401 });
+  });
+
+  test('403 without the permission', () => {
+    assert.deepEqual(run(user(['y']), 'x'), { nextCalled: false, code: 403 });
+  });
+
+  test('passes with the permission, the * scope, or as super admin', () => {
+    assert.equal(run(user(['x']), 'x').nextCalled, true);
+    assert.equal(run(user(['*']), 'x').nextCalled, true);
+    assert.equal(run(user([], true), 'x').nextCalled, true);
+  });
+});

package/tests/timezone.utils.test.mjs

@@ -0,0 +1,141 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import {
+  isValidIanaTimezone,
+  normalizeTimezone,
+  resolveTimezone,
+  formatInTimezone,
+  DEFAULT_TIMEZONE,
+} from '../dist/common/index.js';
+
+describe('isValidIanaTimezone', () => {
+  test('accepts canonical IANA zones and Intl-accepted aliases', () => {
+    for (const tz of ['Africa/Nairobi', 'Europe/London', 'America/New_York', 'UTC', 'Etc/UTC', 'Asia/Calcutta']) {
+      assert.equal(isValidIanaTimezone(tz), true, tz);
+    }
+  });
+
+  test('rejects raw offsets', () => {
+    for (const tz of ['+03:00', '-05:00', '+3', 'GMT+3', 'GMT-04:30', 'UTC+3', 'utc - 5']) {
+      assert.equal(isValidIanaTimezone(tz), false, tz);
+    }
+  });
+
+  test('rejects empty, non-string, unknown and over-long values', () => {
+    for (const tz of ['', '   ', null, undefined, 3, {}, 'Mars/Olympus_Mons', `Africa/${'x'.repeat(100)}`]) {
+      assert.equal(isValidIanaTimezone(tz), false, String(tz));
+    }
+  });
+});
+
+describe('normalizeTimezone', () => {
+  test('canonicalises casing and whitespace', () => {
+    assert.equal(normalizeTimezone(' africa/nairobi '), 'Africa/Nairobi');
+  });
+
+  test('returns null for invalid values', () => {
+    assert.equal(normalizeTimezone('+03:00'), null);
+  });
+});
+
+describe('resolveTimezone', () => {
+  test('returns the zone when valid', () => {
+    assert.equal(resolveTimezone('Europe/London'), 'Europe/London');
+  });
+
+  test('returns the fallback when invalid, never throws', () => {
+    assert.equal(resolveTimezone('nope', 'America/New_York'), 'America/New_York');
+    assert.equal(resolveTimezone(undefined), DEFAULT_TIMEZONE);
+  });
+
+  test('an invalid fallback resolves to the platform default', () => {
+    assert.equal(resolveTimezone('nope', 'also-nope'), 'Africa/Nairobi');
+  });
+});
+
+describe('DEFAULT_TIMEZONE', () => {
+  const load = (env) =>
+    spawnSync(
+      process.execPath,
+      ['--input-type=module', '-e', "import('./dist/common/index.js').then(m => process.stdout.write(m.DEFAULT_TIMEZONE))"],
+      { cwd: new URL('..', import.meta.url), env: { ...process.env, ...env }, encoding: 'utf8' },
+    ).stdout;
+
+  test('defaults to Africa/Nairobi', () => {
+    assert.equal(load({ DEFAULT_USER_TIMEZONE: '' }), 'Africa/Nairobi');
+  });
+
+  test('honours a valid DEFAULT_USER_TIMEZONE override', () => {
+    assert.equal(load({ DEFAULT_USER_TIMEZONE: 'Europe/London' }), 'Europe/London');
+  });
+
+  test('ignores an invalid DEFAULT_USER_TIMEZONE override', () => {
+    assert.equal(load({ DEFAULT_USER_TIMEZONE: '+03:00' }), 'Africa/Nairobi');
+  });
+});
+
+describe('formatInTimezone', () => {
+  test('UTC → Nairobi names the zone alongside its offset', () => {
+    const r = formatInTimezone('2026-09-26T11:05:00Z', 'Africa/Nairobi');
+    assert.deepEqual(r, {
+      text: '26 Sep 2026, 14:05 GMT+3 (Africa/Nairobi)',
+      timezone: 'Africa/Nairobi',
+      usedFallback: false,
+    });
+  });
+
+  test('UTC → London before and after the BST start (2026-03-29)', () => {
+    assert.equal(formatInTimezone('2026-03-28T12:00:00Z', 'Europe/London').text, '28 Mar 2026, 12:00 GMT');
+    assert.equal(formatInTimezone('2026-03-29T12:00:00Z', 'Europe/London').text, '29 Mar 2026, 13:00 BST');
+  });
+
+  test('UTC → London before and after the BST end (2026-10-25)', () => {
+    assert.equal(formatInTimezone('2026-10-24T12:00:00Z', 'Europe/London').text, '24 Oct 2026, 13:00 BST');
+    assert.equal(formatInTimezone('2026-10-25T12:00:00Z', 'Europe/London').text, '25 Oct 2026, 12:00 GMT');
+  });
+
+  test('America/New_York follows DST', () => {
+    assert.equal(formatInTimezone('2026-07-01T16:00:00Z', 'America/New_York').text, '1 Jul 2026, 12:00 EDT');
+    assert.equal(formatInTimezone('2026-12-01T16:00:00Z', 'America/New_York').text, '1 Dec 2026, 11:00 EST');
+  });
+
+  test('crosses midnight into the next and previous day', () => {
+    assert.equal(formatInTimezone('2026-09-26T22:30:00Z', 'Africa/Nairobi').text, '27 Sep 2026, 01:30 GMT+3 (Africa/Nairobi)');
+    assert.equal(formatInTimezone('2026-09-27T02:30:00Z', 'America/New_York').text, '26 Sep 2026, 22:30 EDT');
+  });
+
+  test('accepts Date, ISO string and epoch millis', () => {
+    const iso = '2026-09-26T11:05:00Z';
+    const expected = formatInTimezone(iso, 'UTC').text;
+    assert.equal(expected, '26 Sep 2026, 11:05 UTC');
+    assert.equal(formatInTimezone(new Date(iso), 'UTC').text, expected);
+    assert.equal(formatInTimezone(Date.parse(iso), 'UTC').text, expected);
+  });
+
+  test('supports a 12-hour clock', () => {
+    assert.equal(formatInTimezone('2026-09-26T11:05:00Z', 'UTC', { hour12: true }).text, '26 Sep 2026, 11:05 AM UTC');
+  });
+
+  test('invalid tz uses the fallback and flags it', () => {
+    const r = formatInTimezone('2026-09-26T11:05:00Z', '+03:00', { fallback: 'Europe/London' });
+    assert.equal(r.timezone, 'Europe/London');
+    assert.equal(r.usedFallback, true);
+    assert.equal(r.text, '26 Sep 2026, 12:05 BST');
+  });
+
+  test('missing tz falls back to DEFAULT_TIMEZONE', () => {
+    const r = formatInTimezone('2026-09-26T11:05:00Z', null);
+    assert.equal(r.timezone, DEFAULT_TIMEZONE);
+    assert.equal(r.usedFallback, true);
+  });
+
+  test('invalid instant returns empty text and never throws', () => {
+    for (const instant of ['not a date', NaN, new Date('x')]) {
+      const r = formatInTimezone(instant, 'Africa/Nairobi');
+      assert.equal(r.text, '');
+      assert.equal(r.timezone, 'Africa/Nairobi');
+      assert.equal(r.usedFallback, false);
+    }
+  });
+});