grm-shared-library 1.1.192 → 1.1.194

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 {
+}

package/dist/types/modules/system-user/utils/system-user.util.d.ts

@@ -0,0 +1,41 @@
+import { SystemUserEnvSource } from '../interfaces/system-user-env-source';
+export interface ResolveSystemUserIdOptions {
+    /**
+     * Deprecated keys to fall back to, in order, when the canonical key is
+     * unset. Defaults to {@link LEGACY_SYSTEM_USER_ID_ENV_KEYS}; pass `[]` to
+     * disable legacy support entirely.
+     */
+    legacyKeys?: readonly string[];
+    /**
+     * Value to return when nothing resolves, instead of throwing. Use only
+     * where a missing system user must not stop the process from booting.
+     */
+    fallback?: number;
+    /**
+     * Invoked once per legacy-key hit so the service can surface the
+     * deprecation in its own logger.
+     */
+    onLegacyKeyUsed?: (key: string) => void;
+}
+/**
+ * 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 declare function parseSystemUserId(raw: unknown): number | 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 declare function resolveSystemUserId(source: SystemUserEnvSource, options?: ResolveSystemUserIdOptions): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grm-shared-library",
-  "version": "1.1.192",
+  "version": "1.1.194",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -57,7 +57,8 @@
     "grm-shared-library": "^1.1.101",
     "libphonenumber-js": "^1.13.8",
     "rxjs": "^7.8.2",
-    "swagger-ui-express": "^5.0.1"
+    "swagger-ui-express": "^5.0.1",
+    "@nestjs/config": "^4.0.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",
@@ -65,6 +66,7 @@
     "@nestjs/microservices": "^11.0.0",
     "@sentry/node": "^8.0.0",
     "class-transformer": "^0.5.0",
-    "class-validator": "^0.14.0"
+    "class-validator": "^0.14.0",
+    "@nestjs/config": "^4.0.0"
   }
 }