@heavybit/shared-lib 2.1.0 → 2.7.0

package/dist/esm/common/money.js

@@ -0,0 +1,207 @@
+import Decimal from 'decimal.js';
+/**
+ * Exact money arithmetic. Amounts travel and persist as decimal strings (`"1250.00"`) and are only ever
+ * computed with a decimal type, never JS numbers. The currency is always passed in: shared-lib has no
+ * default currency.
+ *
+ * Rounding is half-up (half away from zero) to the currency's minor unit, after every operation that can
+ * produce extra digits (`mul`), so a `Money` value always holds a whole number of minor units.
+ */
+/** A decimal.js constructor with enough precision for any realistic amount and half-up rounding. */
+const Dec = Decimal.clone({ precision: 40, rounding: Decimal.ROUND_HALF_UP, toExpNeg: -40, toExpPos: 40 });
+const CODE_PATTERN = /^[A-Z]{3}$/;
+const AMOUNT_PATTERN = /^-?\d+(\.\d+)?$/;
+/**
+ * Resolves a currency code or spec, validating both.
+ *
+ * @param currency ISO 4217 code (minor units from `Intl`) or `{ code, minorUnits }`.
+ * @returns The spec.
+ * @throws RangeError for a malformed code or minor-unit count.
+ * @example resolveCurrency('USD') // { code: 'USD', minorUnits: 2 }
+ */
+export function resolveCurrency(currency) {
+    if (typeof currency !== 'string') {
+        if (!CODE_PATTERN.test(currency.code))
+            throw new RangeError(`Invalid currency code "${currency.code}"`);
+        if (!Number.isInteger(currency.minorUnits) || currency.minorUnits < 0 || currency.minorUnits > 6) {
+            throw new RangeError(`Invalid minor units ${currency.minorUnits} for ${currency.code}`);
+        }
+        return { code: currency.code, minorUnits: currency.minorUnits };
+    }
+    if (!CODE_PATTERN.test(currency))
+        throw new RangeError(`Invalid currency code "${currency}"`);
+    const minorUnits = new Intl.NumberFormat('en', { style: 'currency', currency }).resolvedOptions().maximumFractionDigits ?? 2;
+    return { code: currency, minorUnits };
+}
+function toDecimal(value, what) {
+    if (typeof value === 'number' && !Number.isFinite(value))
+        throw new RangeError(`${what} must be finite`);
+    const text = String(value).trim();
+    if (!AMOUNT_PATTERN.test(text))
+        throw new RangeError(`${what} must be a decimal number, got "${value}"`);
+    return new Dec(text);
+}
+/** An immutable amount of one currency, always a whole number of minor units. */
+export class Money {
+    value;
+    currency;
+    constructor(value, 
+    /** The amount's currency. */
+    currency) {
+        this.value = value;
+        this.currency = currency;
+        Object.freeze(this);
+    }
+    /**
+     * Parses a decimal string. Strict: no thousands separators, symbols or more decimals than the
+     * currency allows (D5), so a stored value is never silently rounded on the way in.
+     *
+     * @param amount e.g. `"1250.5"` or `"-3.25"`.
+     * @param currency Code or spec.
+     * @returns The amount.
+     * @throws RangeError for anything else.
+     * @example Money.fromDecimalString('19.99', 'USD')
+     */
+    static fromDecimalString(amount, currency) {
+        const spec = resolveCurrency(currency);
+        if (typeof amount !== 'string')
+            throw new RangeError('Amount must be a decimal string');
+        const value = toDecimal(amount, 'Amount');
+        if (value.decimalPlaces() > spec.minorUnits) {
+            throw new RangeError(`Amount "${amount}" has more than ${spec.minorUnits} decimal places for ${spec.code}`);
+        }
+        return new Money(value, spec);
+    }
+    /**
+     * Builds an amount from an integer count of minor units (e.g. cents).
+     *
+     * @param units Integer (number within the safe range, or bigint).
+     * @param currency Code or spec.
+     * @returns The amount.
+     * @example Money.fromMinorUnits(1999, 'USD').toDecimalString() // '19.99'
+     */
+    static fromMinorUnits(units, currency) {
+        const spec = resolveCurrency(currency);
+        if (typeof units === 'number' && !Number.isSafeInteger(units))
+            throw new RangeError('Minor units must be a safe integer');
+        return new Money(new Dec(units.toString()).div(new Dec(10).pow(spec.minorUnits)), spec);
+    }
+    /**
+     * Zero in a currency.
+     *
+     * @param currency Code or spec.
+     * @returns `0` of that currency.
+     */
+    static zero(currency) {
+        return new Money(new Dec(0), resolveCurrency(currency));
+    }
+    /** The amount with exactly the currency's decimal places, e.g. `"1250.00"` — the wire and storage form. */
+    toDecimalString() {
+        return this.value.toFixed(this.currency.minorUnits);
+    }
+    /** The amount as an integer count of minor units. */
+    toMinorUnits() {
+        return BigInt(this.value.times(new Dec(10).pow(this.currency.minorUnits)).toFixed(0));
+    }
+    /** Serialises as the decimal string, so an amount never becomes a JSON number by accident. */
+    toJSON() {
+        return this.toDecimalString();
+    }
+    /** Same as {@link toDecimalString}. */
+    toString() {
+        return this.toDecimalString();
+    }
+    /** Sum of two amounts of the same currency. */
+    add(other) {
+        return new Money(this.value.plus(this.same(other).value), this.currency);
+    }
+    /** Difference of two amounts of the same currency. */
+    sub(other) {
+        return new Money(this.value.minus(this.same(other).value), this.currency);
+    }
+    /**
+     * Multiplies by a rate (tax, fee, quantity), rounding half-up to the minor unit.
+     *
+     * @param rate e.g. `"0.16"` or `3`.
+     * @returns The rounded product.
+     * @example Money.fromDecimalString('10.05', 'USD').mul('0.5').toDecimalString() // '5.03'
+     */
+    mul(rate) {
+        return new Money(this.round(this.value.times(toDecimal(rate, 'Rate'))), this.currency);
+    }
+    /**
+     * Splits the amount in proportion to `ratios`; the parts always sum to the amount exactly. Each part is
+     * rounded down to the minor unit and the left-over units go, one each, to the parts with the largest
+     * remainders (earlier parts win ties). A negative amount is split like its absolute value, then negated.
+     *
+     * @param ratios Non-negative weights with a positive sum, e.g. `['1', '1', '1']` or `[70, 30]`.
+     * @returns One amount per ratio, in order.
+     * @throws RangeError for an empty list, a negative ratio or a zero sum.
+     * @example Money.fromDecimalString('100.00', 'USD').allocate([1, 1, 1]).map(String) // ['33.34', '33.33', '33.33']
+     */
+    allocate(ratios) {
+        if (ratios.length === 0)
+            throw new RangeError('allocate needs at least one ratio');
+        const weights = ratios.map((r) => toDecimal(r, 'Ratio'));
+        if (weights.some((w) => w.isNegative()))
+            throw new RangeError('Ratios must not be negative');
+        const sum = weights.reduce((acc, w) => acc.plus(w), new Dec(0));
+        if (sum.isZero())
+            throw new RangeError('Ratios must not all be zero');
+        const scale = new Dec(10).pow(this.currency.minorUnits);
+        const total = this.value.abs().times(scale);
+        const exact = weights.map((w) => total.times(w).div(sum));
+        const floors = exact.map((e) => e.floor());
+        let leftover = total.minus(floors.reduce((acc, f) => acc.plus(f), new Dec(0))).toNumber();
+        const order = exact.map((e, i) => ({ i, rem: e.minus(floors[i]) })).sort((a, b) => b.rem.comparedTo(a.rem) || a.i - b.i);
+        for (const { i } of order) {
+            if (leftover <= 0)
+                break;
+            floors[i] = floors[i].plus(1);
+            leftover -= 1;
+        }
+        const sign = this.value.isNegative() ? -1 : 1;
+        return floors.map((units) => new Money(units.div(scale).times(sign), this.currency));
+    }
+    /**
+     * Rounds up (toward +∞) to a multiple of `unit`, e.g. whole units for a payment rail that rejects cents.
+     *
+     * @param unit Positive step in major units, e.g. `"1"` or `"0.05"`; defaults to `"1"`.
+     * @returns The rounded-up amount.
+     * @example Money.fromDecimalString('99.01', 'USD').ceilToUnit().toDecimalString() // '100.00'
+     */
+    ceilToUnit(unit = '1') {
+        const step = toDecimal(unit, 'Unit');
+        if (step.lte(0))
+            throw new RangeError('Unit must be positive');
+        if (step.decimalPlaces() > this.currency.minorUnits)
+            throw new RangeError(`Unit is finer than the ${this.currency.code} minor unit`);
+        return new Money(this.value.div(step).ceil().times(step), this.currency);
+    }
+    /** -1, 0 or 1 comparing this amount with `other` (same currency). */
+    compare(other) {
+        return this.value.comparedTo(this.same(other).value);
+    }
+    /** True when both amounts have the same currency and value. */
+    equals(other) {
+        return this.currency.code === other.currency.code && this.value.equals(other.value);
+    }
+    /** True for zero. */
+    isZero() {
+        return this.value.isZero();
+    }
+    /** True below zero. */
+    isNegative() {
+        return this.value.isNegative() && !this.value.isZero();
+    }
+    same(other) {
+        if (other.currency.code !== this.currency.code) {
+            throw new RangeError(`Currency mismatch: ${this.currency.code} vs ${other.currency.code}`);
+        }
+        return other;
+    }
+    round(value) {
+        return value.toDecimalPlaces(this.currency.minorUnits, Decimal.ROUND_HALF_UP);
+    }
+}
+//# sourceMappingURL=money.js.map

package/dist/esm/common/money.js.map

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

package/dist/esm/common/phone.js

@@ -1,4 +1,5 @@
 import libphonenumber from 'google-libphonenumber';
+import { BadRequestError } from './errors.js';
 const util = libphonenumber.PhoneNumberUtil.getInstance();
 const { PhoneNumberFormat } = libphonenumber;
 /**
@@ -6,9 +7,9 @@ const { PhoneNumberFormat } = libphonenumber;
  * `0712345678` only make sense against a country, and that country is app configuration.
  *
  * @param phone Number as typed (local or international format).
- * @param region ISO 3166-1 alpha-2 region used for local formats (e.g. `KE`, `GB`).
- * @returns E.164 (`+254712345678`), or null when not a valid number for that region.
- * @example toE164('0712345678', 'KE') // '+254712345678'
+ * @param region ISO 3166-1 alpha-2 region used for local formats (e.g. `GB`, `US`).
+ * @returns E.164 (`+447400123456`), or null when not a valid number for that region.
+ * @example toE164('07400 123456', 'GB') // '+447400123456'
  */
 export function toE164(phone, region) {
     try {
@@ -19,17 +20,36 @@ export function toE164(phone, region) {
         return null;
     }
 }
+const MOBILE_TYPES = new Set([libphonenumber.PhoneNumberType.MOBILE, libphonenumber.PhoneNumberType.FIXED_LINE_OR_MOBILE]);
 /**
- * E.164 without the plus sign, as most SMS gateways expect.
+ * E.164 without the plus sign (an MSISDN), as SMS gateways and mobile-money rails expect. Throws instead of
+ * returning null so a bad number can never be stored or sent by mistake; use {@link toE164} to test input.
  *
- * @param phone Number as typed.
- * @param region ISO region for local formats.
- * @returns Digits only, or null when invalid.
- * @example toMsisdn('0712345678', 'KE') // '254712345678'
+ * @param phone Number as typed (local or international format).
+ * @param region ISO 3166-1 alpha-2 region used for local formats (required; no app default).
+ * @param options Mobile-only and same-region checks.
+ * @returns Digits only, country code first.
+ * @throws BadRequestError (`INVALID_PHONE`) when the number is invalid or fails an option.
+ * @example toMsisdn('07400 123456', 'GB') // '447400123456'
  */
-export function toMsisdn(phone, region) {
-    const e164 = toE164(phone, region);
-    return e164 ? e164.slice(1) : null;
+export function toMsisdn(phone, region, options = {}) {
+    const invalid = () => new BadRequestError('Enter a valid phone number', { code: 'INVALID_PHONE' });
+    if (typeof phone !== 'string' || !region)
+        throw invalid();
+    let parsed;
+    try {
+        parsed = util.parseAndKeepRawInput(phone.trim(), region);
+    }
+    catch {
+        throw invalid();
+    }
+    if (!util.isValidNumber(parsed))
+        throw invalid();
+    if (options.regionOnly && util.getRegionCodeForNumber(parsed) !== region.toUpperCase())
+        throw invalid();
+    if (options.mobileOnly && !MOBILE_TYPES.has(util.getNumberType(parsed)))
+        throw invalid();
+    return util.format(parsed, PhoneNumberFormat.E164).slice(1);
 }
 /**
  * The region a number belongs to.
@@ -37,7 +57,7 @@ export function toMsisdn(phone, region) {
  * @param phone Number as typed.
  * @param region ISO region used to interpret local formats.
  * @returns ISO region code, or null when it cannot be determined.
- * @example phoneRegion('+447400123456', 'KE') // 'GB'
+ * @example phoneRegion('+447400123456', 'US') // 'GB'
  */
 export function phoneRegion(phone, region) {
     try {
@@ -48,19 +68,18 @@ export function phoneRegion(phone, region) {
     }
 }
 /**
- * Masks a phone number for logs and UI, so a full number never lands in a log line or screen.
- * Never reveals more than about a third of the input: numbers of 10+ characters keep the first 4 and
- * last 2; shorter inputs keep only the last 2; 4 characters or fewer are fully masked.
+ * Masks a phone number for logs, audit metadata and UI: every digit except the last 4 becomes `*`, so a
+ * full number never lands in a log line or on a screen. Fewer than 5 digits are fully masked
+ * (the same rule the logger applies to phone-like values).
  *
  * @param phone Any phone string (normalised or not).
- * @returns The masked value.
- * @example maskPhone('254712345678') // '2547****78'
+ * @returns The masked digits.
+ * @example maskPhone('+44 7400 123456') // '********3456'
  */
 export function maskPhone(phone) {
-    if (phone.length <= 4)
-        return '****';
-    if (phone.length < 10)
-        return `****${phone.slice(-2)}`;
-    return `${phone.slice(0, 4)}****${phone.slice(-2)}`;
+    const digits = String(phone ?? '').replace(/\D/g, '');
+    if (digits.length < 5)
+        return '*'.repeat(digits.length || 4);
+    return `${'*'.repeat(digits.length - 4)}${digits.slice(-4)}`;
 }
 //# sourceMappingURL=phone.js.map

package/dist/esm/common/phone.js.map

@@ -1 +1 @@
-{"version":3,"file":"phone.js","sourceRoot":"","sources":["../../../src/common/phone.ts"],"names":[],"mappings":"AAAA,OAAO,cAAc,MAAM,uBAAuB,CAAC;AAEnD,MAAM,IAAI,GAAG,cAAc,CAAC,eAAe,CAAC,WAAW,EAAE,CAAC;AAC1D,MAAM,EAAE,iBAAiB,EAAE,GAAG,cAAc,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,MAAc;IAClD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,MAAc;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,MAAc;IACvD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IACrC,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACtD,CAAC"}
+{"version":3,"file":"phone.js","sourceRoot":"","sources":["../../../src/common/phone.ts"],"names":[],"mappings":"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"}

package/dist/esm/common/time.js

@@ -1,4 +1,4 @@
-/** True for IANA zones the runtime knows (`Africa/Nairobi`), false for garbage. */
+/** True for IANA zones the runtime knows (`Europe/Berlin`), false for garbage. */
 export function isValidTimeZone(zone) {
     try {
         new Intl.DateTimeFormat('en-US', { timeZone: zone });
@@ -68,8 +68,19 @@ export function zonedWallTimeToInstant(year, month, day, minutesOfDay, zone) {
     const estimate = wall - timeZoneOffsetMinutes(zone, new Date(wall)) * MS_PER_MINUTE;
     return new Date(wall - timeZoneOffsetMinutes(zone, new Date(estimate)) * MS_PER_MINUTE);
 }
-/** The local calendar day containing `at` in `zone`, as a half-open `[start, end)` UTC range (23–25 h on DST days). */
+/**
+ * The local calendar day containing `at` in `zone`, as a half-open `[start, end)` UTC range (23–25 h on
+ * DST days). Use it for "today" in reports, business days and daily limits.
+ *
+ * @param at Any instant in the day.
+ * @param zone IANA zone (required; no app default).
+ * @returns `{ start, end }` with `start` inclusive and `end` exclusive.
+ * @throws RangeError for an unknown zone.
+ * @example zonedDayBounds(new Date('2026-10-11T22:30:00Z'), 'Asia/Riyadh') // 2026-10-11T21:00Z → 2026-10-12T21:00Z
+ */
 export function zonedDayBounds(at, zone) {
+    if (!isValidTimeZone(zone))
+        throw new RangeError(`Unknown time zone "${zone}"`);
     const { year, month, day } = localDate(at, zone);
     return { start: zonedWallTimeToInstant(year, month, day, 0, zone), end: zonedWallTimeToInstant(year, month, day + 1, 0, zone) };
 }
@@ -93,4 +104,18 @@ export function quietWindowEndAt(at, zone, start, end) {
     const endsTomorrow = crossesMidnight && msOfDay >= startMs;
     return zonedWallTimeToInstant(year, month, day + (endsTomorrow ? 1 : 0), endMin, zone);
 }
+/**
+ * The instant as a UTC ISO-8601 string (`2026-11-13T09:00:00.000Z`), the form every timestamp travels in.
+ *
+ * @param instant A Date, an epoch-milliseconds number or a string `Date` can parse.
+ * @returns The `toISOString()` form.
+ * @throws RangeError when the input is not a valid instant (never returns `"Invalid Date"`).
+ * @example toUtcIso('2026-11-13T12:00:00+03:00') // '2026-11-13T09:00:00.000Z'
+ */
+export function toUtcIso(instant) {
+    const date = instant instanceof Date ? instant : new Date(instant);
+    if (Number.isNaN(date.getTime()))
+        throw new RangeError(`Not a valid instant: "${String(instant)}"`);
+    return date.toISOString();
+}
 //# sourceMappingURL=time.js.map

package/dist/esm/common/time.js.map

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

package/dist/esm/config/index.js

@@ -1,11 +1,14 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { z } from 'zod';
-/**
- * Environment building blocks. Services compose the pieces they need:
+import { MIN_INTERNAL_CREDENTIAL_LENGTH, SERVICE_NAME_PATTERN } from '../common/internal-constants.js';
+/*
+ * Environment building blocks. `loadEnv(schema)` merges a service's schema onto `baseEnv`;
+ * `parseEnv(schema)` validates any composition of the blocks without the base:
  *
- *   const env = loadEnv(serviceEnv.merge(databaseEnv).merge(messagingEnv).extend({ MY_VAR: z.string() }));
+ *   const config = loadEnv(z.object({ MY_VAR: z.string() }));
  */
+/** Service identity, logging, CORS and the gateway signing secret. */
 export const serviceEnv = z.object({
     NODE_ENV: z.enum(['development', 'test', 'staging', 'production']).default('development'),
     PORT: z.coerce.number().int().positive(),
@@ -14,11 +17,22 @@ export const serviceEnv = z.object({
     APP_NAME: z.string().min(1).default('app'),
     LOG_LEVEL: z.enum(['error', 'warn', 'info', 'http', 'debug']).optional(),
     CORS_ORIGINS: z.string().default(''),
-    /** Verifies gateway-signed identity headers. */
-    GATEWAY_SHARED_SECRET: z.string().min(16),
-    /** Authenticates service-to-service `/internal/*` calls. */
-    INTERNAL_SERVICE_SECRET: z.string().min(16),
+    /** Verifies gateway-signed identity headers (v2); at least 32 characters, same value on the gateway and every service. */
+    GATEWAY_SIGNING_SECRET: z.string().min(32),
 });
+/**
+ * Service-to-service credentials. Optional here because development may run without them;
+ * `assertInternalServiceAuthConfigured` enforces them in staging and production.
+ */
+export const internalServiceEnv = z.object({
+    /** This service's own name (its compose service name), sent with every internal call. */
+    INTERNAL_SERVICE_NAME: z.string().regex(SERVICE_NAME_PATTERN).optional(),
+    /** This service's own secret (at least 32 characters), sent with every internal call. */
+    INTERNAL_SERVICE_CREDENTIAL: z.string().min(MIN_INTERNAL_CREDENTIAL_LENGTH).optional(),
+    /** JSON map of caller name → secret this service accepts from that caller. */
+    INTERNAL_SERVICE_CREDENTIALS: z.string().optional(),
+});
+/** Database connection env vars (MySQL defaults). */
 export const databaseEnv = z.object({
     DB_HOST: z.string().default('127.0.0.1'),
     DB_PORT: z.coerce.number().int().positive().default(3306),
@@ -27,6 +41,7 @@ export const databaseEnv = z.object({
     DB_NAME: z.string().min(1),
     DB_POOL_MAX: z.coerce.number().int().positive().default(10),
 });
+/** RabbitMQ connection and queue-prefix env vars. */
 export const messagingEnv = z.object({
     RABBITMQ_URL: z.string().optional(),
     RABBITMQ_HOST: z.string().default('127.0.0.1'),
@@ -38,20 +53,39 @@ export const messagingEnv = z.object({
     QUEUE_PREFIX: z.string().default('dev'),
     RABBITMQ_ENABLED: z.enum(['true', 'false']).default('true').transform((v) => v === 'true'),
 });
+/** Redis connection env vars. Keys are prefixed by the keyspace (`createRedisKeyspace`), never by the client. */
 export const redisEnv = z.object({
+    /** Full connection URL; overrides host/port/password when set. */
     REDIS_URL: z.string().optional(),
+    REDIS_HOST: z.string().default('127.0.0.1'),
+    REDIS_PORT: z.coerce.number().int().positive().default(6379),
+    REDIS_PASSWORD: z.string().optional(),
     REDIS_DB: z.coerce.number().int().min(0).default(0),
-    /** Key prefix, e.g. `app:dev:` — never share one between apps or environments. */
-    REDIS_PREFIX: z.string().default(''),
+    /**
+     * Environment segment of every Redis key (`{app}:{env}:{service}:…`), e.g. `dev`, `staging`, `prod`.
+     * Required in staging and production; never share one between environments.
+     */
+    CACHE_KEY_PREFIX: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).optional(),
 });
-/** Builds an AMQP URL from discrete env vars (or returns RABBITMQ_URL when set). */
+/**
+ * Builds an AMQP URL from discrete env vars (or returns RABBITMQ_URL when set). User, password and vhost are URL-encoded.
+ *
+ * @param env Parsed {@link messagingEnv} values.
+ * @returns An `amqp://` URL.
+ * @example const url = amqpUrlFromEnv(parseEnv(messagingEnv));
+ */
 export function amqpUrlFromEnv(env) {
     if (env.RABBITMQ_URL)
         return env.RABBITMQ_URL;
     const vhost = env.RABBITMQ_VHOST === '/' ? '%2F' : encodeURIComponent(env.RABBITMQ_VHOST.replace(/^\//, ''));
     return `amqp://${encodeURIComponent(env.RABBITMQ_USER)}:${encodeURIComponent(env.RABBITMQ_PASSWORD)}@${env.RABBITMQ_HOST}:${env.RABBITMQ_PORT}/${vhost}`;
 }
-/** Reads `KEY=value` lines from a dotenv file into process.env without overriding set values. */
+/**
+ * Reads `KEY=value` lines from a dotenv file into process.env without overriding set values. Missing file is a no-op.
+ *
+ * @param path Dotenv file (default `./.env`).
+ * @example loadDotEnv(resolve(__dirname, '../.env.test'));
+ */
 export function loadDotEnv(path = resolve(process.cwd(), '.env')) {
     if (!existsSync(path))
         return;
@@ -70,19 +104,102 @@ export function loadDotEnv(path = resolve(process.cwd(), '.env')) {
             process.env[key] = value;
     }
 }
+/** Thrown by the env loader when required variables are missing or invalid; lists every problem. */
 export class ConfigError extends Error {
 }
-/** Loads `.env` (if present) and validates process.env. Throws ConfigError listing every problem. */
-export function loadEnv(schema, source = process.env, options = {}) {
+/**
+ * The base environment every service validates: service identity, gateway secret, database, Redis,
+ * RabbitMQ and internal-service credentials. `loadEnv` merges a service's own schema onto it.
+ */
+export const baseEnv = serviceEnv.merge(databaseEnv).merge(redisEnv).merge(messagingEnv).merge(internalServiceEnv);
+/** Variables that have a development default but must be set explicitly in staging and production. */
+export const DEPLOYED_REQUIRED_ENV = Object.freeze(['CACHE_KEY_PREFIX', 'QUEUE_PREFIX']);
+const DEPLOYED_NODE_ENVS = new Set(['staging', 'production']);
+/**
+ * True for NODE_ENV values that must name their environments explicitly (staging, production).
+ *
+ * @param nodeEnv NODE_ENV value (default `process.env.NODE_ENV`).
+ * @returns Whether it is a deployed environment.
+ * @example isDeployedNodeEnv('production') // true
+ */
+export function isDeployedNodeEnv(nodeEnv = process.env.NODE_ENV) {
+    return DEPLOYED_NODE_ENVS.has((nodeEnv ?? '').trim());
+}
+function collectProblems(issues, source) {
+    const byName = new Map();
+    for (const issue of issues) {
+        const name = String(issue.path[0] ?? '(root)');
+        const raw = source[name];
+        byName.set(name, { name, problem: raw === undefined || raw === '' ? 'missing' : 'invalid' });
+    }
+    return [...byName.values()];
+}
+function deployedProblems(source, required) {
+    if (!isDeployedNodeEnv(source.NODE_ENV))
+        return [];
+    return required.filter((name) => !source[name]?.trim()).map((name) => ({ name, problem: 'missing' }));
+}
+/**
+ * Formats problems as `NAME: missing|invalid` lines (names only — values are never printed, because
+ * Zod's own messages can echo them).
+ *
+ * @param problems Problems from validation.
+ * @returns A multi-line message.
+ * @example formatEnvProblems([{ name: 'DB_NAME', problem: 'missing' }]) // 'Invalid environment configuration:\n  DB_NAME: missing'
+ */
+export function formatEnvProblems(problems) {
+    return `Invalid environment configuration:\n${problems.map((p) => `  ${p.name}: ${p.problem}`).join('\n')}`;
+}
+/**
+ * Validates `source` against `schema` without merging the base or exiting. Use for partial configs
+ * (scripts, tests) and wherever the caller handles the error.
+ *
+ * @param schema Any Zod schema over the env object.
+ * @param source Values to validate (default process.env).
+ * @param options Dotenv and deployed-environment checks.
+ * @returns The parsed, typed config.
+ * @throws ConfigError listing every missing or invalid variable by name (never its value).
+ * @example const env = parseEnv(databaseEnv, { DB_NAME: 'app_test' });
+ */
+export function parseEnv(schema, source = process.env, options = {}) {
     if (options.dotenv !== false && source === process.env)
         loadDotEnv();
     const result = schema.safeParse(source);
-    if (!result.success) {
-        const lines = result.error.issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
-        throw new ConfigError(`Invalid environment configuration:\n${lines}`);
-    }
+    const problems = [...(result.success ? [] : collectProblems(result.error.issues, source)), ...deployedProblems(source, options.deployedRequired ?? DEPLOYED_REQUIRED_ENV)];
+    const unique = [...new Map(problems.map((p) => [p.name, p])).values()];
+    if (unique.length || !result.success)
+        throw new ConfigError(formatEnvProblems(unique));
     return result.data;
 }
-/** Comma-separated env value → trimmed, non-empty list. */
+/**
+ * Service startup config: merges the base env schema with the service's own, validates, and on
+ * failure prints the missing/invalid variable **names** (never values) and exits non-zero.
+ *
+ * @param schema The service's own variables (default none).
+ * @param options Source, base override and injectable write/exit for tests.
+ * @returns The parsed, typed config (base + service variables).
+ * @example
+ * export const config = loadEnv(z.object({ UPSTREAM_INTERNAL_URL: z.string().url() }));
+ */
+export function loadEnv(schema, options = {}) {
+    const base = (options.base ?? baseEnv);
+    const merged = schema ? base.merge(schema) : base;
+    try {
+        return parseEnv(merged, options.source ?? process.env, options);
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError))
+            throw error;
+        (options.write ?? ((text) => process.stderr.write(text)))(`${error.message}\n`);
+        return (options.exit ?? ((code) => process.exit(code)))(1);
+    }
+}
+/**
+ * Comma-separated env value → trimmed, non-empty list.
+ *
+ * @param value Raw env value.
+ * @returns The list (empty when unset).
+ * @example listFromEnv(' a, b ,,c') // ['a', 'b', 'c']
+ */
 export const listFromEnv = (value) => (value ?? '').split(',').map((s) => s.trim()).filter(Boolean);
 //# sourceMappingURL=index.js.map