@heavybit/shared-lib 0.0.0-stage → 1.2.0

package/dist/esm/cache/index.js

@@ -0,0 +1,163 @@
+import { Redis } from 'ioredis';
+import { silentLogger } from '../logging/index.js';
+const NULL_SENTINEL = '__null__';
+class MemoryStore {
+    max;
+    map = new Map();
+    constructor(max) {
+        this.max = max;
+    }
+    get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt < Date.now()) {
+            this.map.delete(key);
+            return undefined;
+        }
+        // Refresh recency for LRU eviction.
+        this.map.delete(key);
+        this.map.set(key, entry);
+        return entry.value;
+    }
+    set(key, value, ttlSec) {
+        if (this.map.size >= this.max)
+            this.map.delete(this.map.keys().next().value);
+        this.map.set(key, { value, expiresAt: Date.now() + ttlSec * 1000 });
+    }
+    del(key) {
+        this.map.delete(key);
+    }
+}
+/**
+ * Redis-backed cache with tag invalidation. If Redis errors, reads fall through to the loader
+ * and writes go to a bounded in-memory store, so a cache outage degrades latency rather than
+ * availability.
+ */
+export function createCache(options) {
+    const logger = options.logger ?? silentLogger;
+    const defaultTtl = options.defaultTtlSec ?? 60;
+    const memory = new MemoryStore(options.memoryMaxEntries ?? 5000);
+    const inflight = new Map();
+    const k = (key) => `${options.namespace}:${key}`;
+    const tagKey = (tag) => `${options.namespace}:tag:${tag}`;
+    let warned = false;
+    const redisFailed = (error) => {
+        if (!warned)
+            logger.warn('Cache backend unavailable; using in-memory fallback', { error: error.message });
+        warned = true;
+    };
+    const readRaw = async (key) => {
+        if (options.redis) {
+            try {
+                const value = await options.redis.get(k(key));
+                warned = false;
+                return value ?? undefined;
+            }
+            catch (error) {
+                redisFailed(error);
+            }
+        }
+        return memory.get(k(key));
+    };
+    const writeRaw = async (key, raw, opts = {}) => {
+        const ttl = opts.ttlSec ?? defaultTtl;
+        if (options.redis) {
+            try {
+                const pipeline = options.redis.multi().set(k(key), raw, 'EX', ttl);
+                for (const tag of opts.tags ?? [])
+                    pipeline.sadd(tagKey(tag), k(key)).expire(tagKey(tag), Math.max(ttl, 86_400));
+                await pipeline.exec();
+                return;
+            }
+            catch (error) {
+                redisFailed(error);
+            }
+        }
+        memory.set(k(key), raw, ttl);
+    };
+    const cache = {
+        async get(key) {
+            const raw = await readRaw(key);
+            if (raw === undefined || raw === NULL_SENTINEL)
+                return undefined;
+            return JSON.parse(raw);
+        },
+        async set(key, value, opts) {
+            await writeRaw(key, value === null ? NULL_SENTINEL : JSON.stringify(value), opts);
+        },
+        async del(...keys) {
+            for (const key of keys)
+                memory.del(k(key));
+            if (options.redis && keys.length)
+                await options.redis.del(...keys.map(k)).catch(redisFailed);
+        },
+        async wrap(key, loader, opts = {}) {
+            const raw = await readRaw(key);
+            if (raw !== undefined) {
+                if (raw === NULL_SENTINEL)
+                    return null;
+                return JSON.parse(raw);
+            }
+            const existing = inflight.get(key);
+            if (existing)
+                return existing;
+            const load = (async () => {
+                try {
+                    const value = await loader();
+                    if (value !== null && value !== undefined)
+                        await writeRaw(key, JSON.stringify(value), opts);
+                    else if (opts.cacheNull)
+                        await writeRaw(key, NULL_SENTINEL, { ...opts, ttlSec: Math.min(opts.ttlSec ?? defaultTtl, 30) });
+                    return value;
+                }
+                finally {
+                    inflight.delete(key);
+                }
+            })();
+            inflight.set(key, load);
+            return load;
+        },
+        async invalidateTags(...tags) {
+            if (!options.redis)
+                return;
+            try {
+                for (const tag of tags) {
+                    const members = await options.redis.smembers(tagKey(tag));
+                    for (const member of members)
+                        memory.del(member);
+                    if (members.length)
+                        await options.redis.del(...members);
+                    await options.redis.del(tagKey(tag));
+                }
+            }
+            catch (error) {
+                redisFailed(error);
+            }
+        },
+    };
+    return cache;
+}
+/** ioredis client that never crashes the process on connection errors and retries forever. */
+export function createRedisClient(opts) {
+    const logger = opts.logger ?? silentLogger;
+    const base = {
+        db: opts.db ?? 0,
+        keyPrefix: opts.keyPrefix || undefined,
+        lazyConnect: false,
+        enableOfflineQueue: false,
+        maxRetriesPerRequest: 1,
+        retryStrategy: (times) => Math.min(times * 500, 10_000),
+        ...opts.options,
+    };
+    const client = opts.url ? new Redis(opts.url, base) : new Redis(base);
+    let lastError = '';
+    client.on('error', (error) => {
+        if (error.message !== lastError)
+            logger.warn('Redis error', { error: error.message });
+        lastError = error.message;
+    });
+    client.on('ready', () => { lastError = ''; logger.info('Redis connected', { db: base.db }); });
+    return client;
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cache/index.js.map

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

package/dist/esm/common/async.js

@@ -0,0 +1,33 @@
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Runs `fn`, retrying failures with exponential back-off. */
+export async function retry(fn, options) {
+    const delay = options.delayMs ?? ((n) => Math.min(5000, 200 * 2 ** (n - 1)));
+    let attempt = 0;
+    for (;;) {
+        try {
+            return await fn(attempt);
+        }
+        catch (error) {
+            attempt += 1;
+            if (attempt > options.retries || (options.shouldRetry && !options.shouldRetry(error)))
+                throw error;
+            await sleep(delay(attempt));
+        }
+    }
+}
+/** Rejects with `onTimeout()` if `promise` does not settle within `ms`. */
+export function withTimeout(promise, ms, onTimeout) {
+    let timer;
+    return Promise.race([
+        promise.finally(() => clearTimeout(timer)),
+        new Promise((_, reject) => { timer = setTimeout(() => reject(onTimeout()), ms); }),
+    ]);
+}
+/** Splits `items` into arrays of at most `size`. */
+export function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+//# sourceMappingURL=async.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../../../src/common/async.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAStG,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,KAAK,CAAI,EAAmC,EAAE,OAAqB;IACvF,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,SAAS,CAAC;QACR,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAI,CAAC,CAAC;YACb,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;gBAAE,MAAM,KAAK,CAAC;YACnG,MAAM,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW,CAAI,OAAmB,EAAE,EAAU,EAAE,SAAsB;IACpF,IAAI,KAAoC,CAAC;IACzC,OAAO,OAAO,CAAC,IAAI,CAAC;QAClB,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;KAC1F,CAAC,CAAC;AACL,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,KAAK,CAAI,KAAmB,EAAE,IAAY;IACxD,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI;QAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAChF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/esm/common/audit.js

@@ -0,0 +1,18 @@
+import { newId } from './id.js';
+/**
+ * Builds the row for a `*_audits` sibling table: a copy of the parent row plus `action`,
+ * `parentId`, and a fresh `id`. The parent's timestamps are dropped so the audit row records
+ * when the change happened. The actor lands in `createdBy`/`updatedBy` exactly as on the parent
+ * (null for system operations). Strip secrets (e.g. password hashes) before calling.
+ */
+export function buildAuditRow(row, action, actorId = null) {
+    const { id: parentId, createdAt: _createdAt, updatedAt: _updatedAt, ...rest } = row;
+    return {
+        ...rest,
+        id: newId(),
+        parentId,
+        action,
+        ...(action === 'create' ? { createdBy: actorId, updatedBy: actorId } : { updatedBy: actorId }),
+    };
+}
+//# sourceMappingURL=audit.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/common/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAMhC;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAA2B,GAAM,EAAE,MAAmB,EAAE,UAAyB,IAAI;IAChH,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,GAAuD,CAAC;IACxI,OAAO;QACL,GAAI,IAAkD;QACtD,EAAE,EAAE,KAAK,EAAE;QACX,QAAQ;QACR,MAAM;QACN,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;KAC/F,CAAC;AACJ,CAAC"}

package/dist/esm/common/crypto.js

@@ -0,0 +1,64 @@
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, randomInt, timingSafeEqual } from 'node:crypto';
+export function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function hmacSha256(secret, value) {
+    return createHmac('sha256', secret).update(value).digest('hex');
+}
+/** Constant-time string comparison (false when lengths differ). */
+export function safeEqual(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/** URL-safe random token (default 32 bytes of entropy). */
+export function randomToken(bytes = 32) {
+    return randomBytes(bytes).toString('base64url');
+}
+/** Numeric one-time code, e.g. `'042917'`. Uses a CSPRNG. */
+export function randomNumericCode(length = 6) {
+    let code = '';
+    for (let i = 0; i < length; i += 1)
+        code += String(randomInt(0, 10));
+    return code;
+}
+/**
+ * Hash a value that must be looked up later (refresh tokens, reset tokens, OTPs) with a
+ * server-side pepper so a database leak alone cannot be replayed.
+ */
+export function hashToken(token, pepper) {
+    return hmacSha256(pepper, token);
+}
+const CIPHER = 'aes-256-gcm';
+const IV_BYTES = 12;
+const FORMAT_VERSION = 'v1';
+/** Accepts a 32-byte key as hex/base64, or any passphrase (derived with SHA-256). */
+function resolveKey(key) {
+    if (/^[0-9a-f]{64}$/i.test(key))
+        return Buffer.from(key, 'hex');
+    const b64 = Buffer.from(key, 'base64');
+    if (b64.length === 32 && /^[A-Za-z0-9+/=_-]+$/.test(key))
+        return b64;
+    return createHash('sha256').update(key).digest();
+}
+/** AES-256-GCM encrypt. Output: `v1:<iv>:<tag>:<ciphertext>` (base64url parts). */
+export function encryptSecret(plaintext, key) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv(CIPHER, resolveKey(key), iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [FORMAT_VERSION, iv.toString('base64url'), tag.toString('base64url'), encrypted.toString('base64url')].join(':');
+}
+export function decryptSecret(payload, key) {
+    const [version, iv, tag, data] = payload.split(':');
+    if (version !== FORMAT_VERSION || !iv || !tag || data === undefined) {
+        throw new Error('Unsupported encrypted payload format');
+    }
+    const decipher = createDecipheriv(CIPHER, resolveKey(key), Buffer.from(iv, 'base64url'));
+    decipher.setAuthTag(Buffer.from(tag, 'base64url'));
+    return Buffer.concat([decipher.update(Buffer.from(data, 'base64url')), decipher.final()]).toString('utf8');
+}
+export function isEncryptedSecret(value) {
+    return typeof value === 'string' && value.startsWith(`${FORMAT_VERSION}:`) && value.split(':').length === 4;
+}
+//# sourceMappingURL=crypto.js.map

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

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

package/dist/esm/common/errors.js

@@ -0,0 +1,75 @@
+/**
+ * Base class for errors that map to an HTTP status. Throw these from services; the shared
+ * error middleware turns them into the standard envelope. Anything that is not an AppError is
+ * reported as a 500 with a generic message so internals never leak.
+ */
+export class AppError extends Error {
+    statusCode;
+    code;
+    errors;
+    /** Consumers dead-letter immediately instead of retrying when this is false. */
+    retryable;
+    constructor(statusCode, message, options = {}) {
+        super(message, options.cause ? { cause: options.cause } : undefined);
+        this.name = new.target.name;
+        this.statusCode = statusCode;
+        this.code = options.code ?? defaultCode(statusCode);
+        this.errors = options.errors;
+        this.retryable = options.retryable ?? statusCode >= 500;
+    }
+}
+function defaultCode(status) {
+    switch (status) {
+        case 400: return 'BAD_REQUEST';
+        case 401: return 'UNAUTHENTICATED';
+        case 403: return 'FORBIDDEN';
+        case 404: return 'NOT_FOUND';
+        case 409: return 'CONFLICT';
+        case 422: return 'VALIDATION_FAILED';
+        case 429: return 'RATE_LIMITED';
+        case 503: return 'SERVICE_UNAVAILABLE';
+        default: return status >= 500 ? 'INTERNAL_ERROR' : 'ERROR';
+    }
+}
+export class BadRequestError extends AppError {
+    constructor(message = 'Bad request', options = {}) { super(400, message, options); }
+}
+export class UnauthorizedError extends AppError {
+    constructor(message = 'Authentication required', options = {}) { super(401, message, options); }
+}
+export class ForbiddenError extends AppError {
+    constructor(message = 'You do not have permission to perform this action', options = {}) { super(403, message, options); }
+}
+export class NotFoundError extends AppError {
+    constructor(message = 'Resource not found', options = {}) { super(404, message, options); }
+}
+export class ConflictError extends AppError {
+    constructor(message = 'Resource already exists', options = {}) { super(409, message, options); }
+}
+export class ValidationError extends AppError {
+    constructor(errors, message = 'Validation failed') { super(422, message, { errors }); }
+}
+export class TooManyRequestsError extends AppError {
+    constructor(message = 'Too many requests. Please try again later.', options = {}) { super(429, message, options); }
+}
+export class ServiceUnavailableError extends AppError {
+    constructor(message = 'Service temporarily unavailable', options = {}) { super(503, message, options); }
+}
+/** A failure that will never succeed on retry (bad payload, unknown template, …). */
+export class NonRetryableError extends AppError {
+    constructor(message, options = {}) {
+        super(422, message, { ...options, retryable: false });
+    }
+}
+export function isAppError(error) {
+    return error instanceof AppError;
+}
+/** Message safe to show a caller; hides internals for unexpected errors. */
+export function publicMessage(error) {
+    if (isAppError(error) && error.statusCode < 500)
+        return error.message;
+    if (isAppError(error) && error.statusCode === 503)
+        return error.message;
+    return 'Internal server error';
+}
+//# sourceMappingURL=errors.js.map

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

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

package/dist/esm/common/id.js

@@ -0,0 +1,33 @@
+import { monotonicFactory, decodeTime } from 'ulid';
+/**
+ * Primary keys are ULIDs: 26-char Crockford base32, lexicographically sortable by creation
+ * time, so B-tree inserts stay append-only (unlike random UUIDv4) and IDs double as a coarse
+ * creation timestamp. Store them in `CHAR(26)` columns.
+ */
+const nextUlid = monotonicFactory();
+export const ID_LENGTH = 26;
+export const ID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+/** A new time-ordered, monotonic ULID. */
+export function newId() {
+    return nextUlid();
+}
+export function isId(value) {
+    return typeof value === 'string' && ID_PATTERN.test(value);
+}
+/** Creation time encoded in a ULID. */
+export function idTimestamp(id) {
+    return new Date(decodeTime(id));
+}
+const FIXTURE_PREFIX = '01K6SEED';
+/**
+ * A stable, valid ID for seed/fixture rows: the same `(namespace, n)` always yields the same ID, so
+ * seeds in different services can reference each other's rows without sharing a database.
+ * `namespace` is two Crockford characters (e.g. `PR` for profiles).
+ */
+export function fixtureId(namespace, n) {
+    const id = `${FIXTURE_PREFIX}${namespace.toUpperCase()}${String(n).padStart(ID_LENGTH - FIXTURE_PREFIX.length - namespace.length, '0')}`;
+    if (!ID_PATTERN.test(id))
+        throw new Error(`Invalid fixture id namespace/sequence: ${namespace}/${n}`);
+    return id;
+}
+//# sourceMappingURL=id.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../../src/common/id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEpD;;;;GAIG;AACH,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;AAEpC,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC;AAC5B,MAAM,CAAC,MAAM,UAAU,GAAG,0BAA0B,CAAC;AAErD,0CAA0C;AAC1C,MAAM,UAAU,KAAK;IACnB,OAAO,QAAQ,EAAE,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,cAAc,GAAG,UAAU,CAAC;AAElC;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,SAAiB,EAAE,CAAS;IACpD,MAAM,EAAE,GAAG,GAAG,cAAc,GAAG,SAAS,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,GAAG,cAAc,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IACzI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,SAAS,IAAI,CAAC,EAAE,CAAC,CAAC;IACtG,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/esm/common/index.js

@@ -0,0 +1,12 @@
+export * from './id.js';
+export * from './errors.js';
+export * from './response.js';
+export * from './crypto.js';
+export * from './password.js';
+export * from './jwt.js';
+export * from './text.js';
+export * from './async.js';
+export * from './phone.js';
+export * from './time.js';
+export * from './audit.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/esm/common/jwt.js

@@ -0,0 +1,49 @@
+import jwt from 'jsonwebtoken';
+export function signJwt(payload, secret, options) {
+    return jwt.sign(payload, secret, {
+        algorithm: 'HS256',
+        expiresIn: options.expiresIn,
+        ...(options.issuer ? { issuer: options.issuer } : {}),
+        ...(options.audience ? { audience: options.audience } : {}),
+        ...(options.jwtId ? { jwtid: options.jwtId } : {}),
+    });
+}
+/** Verifies signature, expiry and (when given) issuer/audience. Throws on any failure. */
+export function verifyJwt(token, secret, options = {}) {
+    const decoded = jwt.verify(token, secret, {
+        algorithms: ['HS256'],
+        ...(options.issuer ? { issuer: options.issuer } : {}),
+        ...(options.audience ? { audience: options.audience } : {}),
+    });
+    if (typeof decoded === 'string' || !decoded.sub)
+        throw new Error('Invalid token payload');
+    return decoded;
+}
+export function decodeJwt(token) {
+    const decoded = jwt.decode(token);
+    return decoded && typeof decoded !== 'string' ? decoded : null;
+}
+export function extractBearerToken(header) {
+    if (!header)
+        return null;
+    const [scheme, token] = header.split(' ');
+    return scheme?.toLowerCase() === 'bearer' && token ? token.trim() : null;
+}
+/** Converts `'15m'`, `'30d'`, `3600` into seconds. */
+export function durationToSeconds(value) {
+    if (typeof value === 'number')
+        return value;
+    const match = /^(\d+)\s*(ms|s|m|h|d|w)?$/.exec(value.trim());
+    if (!match)
+        throw new Error(`Invalid duration: ${value}`);
+    const amount = Number(match[1]);
+    switch (match[2]) {
+        case 'ms': return Math.ceil(amount / 1000);
+        case 'm': return amount * 60;
+        case 'h': return amount * 3600;
+        case 'd': return amount * 86_400;
+        case 'w': return amount * 604_800;
+        default: return amount;
+    }
+}
+//# sourceMappingURL=jwt.js.map

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

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

package/dist/esm/common/password.js

@@ -0,0 +1,30 @@
+import argon2 from 'argon2';
+import bcrypt from 'bcryptjs';
+/**
+ * Passwords are hashed with argon2id. Legacy bcrypt hashes (`$2a$`, `$2b$`, `$2y$`) still
+ * verify so migrated accounts can sign in; callers should re-hash on success when
+ * `needsRehash()` is true.
+ */
+const ARGON2_OPTIONS = { type: argon2.argon2id, memoryCost: 19_456, timeCost: 2, parallelism: 1 };
+const BCRYPT_PREFIX = /^\$2[aby]\$/;
+export async function hashPassword(password) {
+    return argon2.hash(password, ARGON2_OPTIONS);
+}
+export async function verifyPassword(password, hash) {
+    if (!hash)
+        return false;
+    try {
+        if (BCRYPT_PREFIX.test(hash))
+            return await bcrypt.compare(password, hash);
+        return await argon2.verify(hash, password);
+    }
+    catch {
+        return false;
+    }
+}
+export function needsRehash(hash) {
+    if (BCRYPT_PREFIX.test(hash))
+        return true;
+    return argon2.needsRehash(hash, ARGON2_OPTIONS);
+}
+//# sourceMappingURL=password.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"password.js","sourceRoot":"","sources":["../../../src/common/password.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,MAAM,MAAM,UAAU,CAAC;AAE9B;;;;GAIG;AACH,MAAM,cAAc,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAW,CAAC;AAE3G,MAAM,aAAa,GAAG,aAAa,CAAC;AAEpC,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB,EAAE,IAA+B;IACpF,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,CAAC;QACH,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,MAAM,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1E,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;AAClD,CAAC"}

package/dist/esm/common/phone.js

@@ -0,0 +1,33 @@
+import libphonenumber from 'google-libphonenumber';
+const util = libphonenumber.PhoneNumberUtil.getInstance();
+const { PhoneNumberFormat } = libphonenumber;
+/**
+ * Normalises a phone number to E.164 (`+254712345678`). Returns null for anything that is not a
+ * valid number for the given default region.
+ */
+export function toE164(phone, defaultRegion = 'KE') {
+    try {
+        const parsed = util.parseAndKeepRawInput(phone.trim(), defaultRegion);
+        return util.isValidNumber(parsed) ? util.format(parsed, PhoneNumberFormat.E164) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** E.164 without the plus sign, as most SMS gateways expect (`254712345678`). */
+export function toMsisdn(phone, defaultRegion = 'KE') {
+    const e164 = toE164(phone, defaultRegion);
+    return e164 ? e164.slice(1) : null;
+}
+export function phoneRegion(phone, defaultRegion = 'KE') {
+    try {
+        return util.getRegionCodeForNumber(util.parse(phone, defaultRegion)) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function maskPhone(phone) {
+    return phone.length <= 4 ? '****' : `${phone.slice(0, 4)}****${phone.slice(-2)}`;
+}
+//# sourceMappingURL=phone.js.map

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

@@ -0,0 +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;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,aAAa,GAAG,IAAI;IACxD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,aAAa,CAAC,CAAC;QACtE,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,iFAAiF;AACjF,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,aAAa,GAAG,IAAI;IAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,aAAa,GAAG,IAAI;IAC7D,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,IAAI,IAAI,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACnF,CAAC"}

package/dist/esm/common/response.js

@@ -0,0 +1,24 @@
+/** Standard success envelope: `{ success, message, data }`. */
+export function successResponse(data, message = 'Success') {
+    return { success: true, message, data };
+}
+/** Standard error envelope: `{ success: false, message, code?, errors? }`. */
+export function errorResponse(message, errors, code) {
+    return { success: false, message, ...(code ? { code } : {}), ...(errors ? { errors } : {}) };
+}
+export function buildPaginationMeta(total, page, limit) {
+    const totalPages = limit > 0 ? Math.max(1, Math.ceil(total / limit)) : 1;
+    return { page, limit, total, totalPages, hasNext: page < totalPages, hasPrev: page > 1 };
+}
+/** Paginated envelope: `{ success, message, data: T[], meta }`. */
+export function paginatedResponse(data, total, page, limit, message = 'Success') {
+    return { success: true, message, data, meta: buildPaginationMeta(total, page, limit) };
+}
+export function buildPaginatedResult(data, total, page, limit) {
+    return { data, meta: buildPaginationMeta(total, page, limit) };
+}
+/** SQL offset for 1-based pages. */
+export function pageOffset(page, limit) {
+    return Math.max(0, (Math.max(1, page) - 1) * limit);
+}
+//# sourceMappingURL=response.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../../src/common/response.ts"],"names":[],"mappings":"AAEA,+DAA+D;AAC/D,MAAM,UAAU,eAAe,CAAI,IAAO,EAAE,OAAO,GAAG,SAAS;IAC7D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,MAAiC,EAAE,IAAa;IAC7F,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,IAAY,EAAE,KAAa;IAC5E,MAAM,UAAU,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,GAAG,UAAU,EAAE,OAAO,EAAE,IAAI,GAAG,CAAC,EAAE,CAAC;AAC3F,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAAI,IAAS,EAAE,KAAa,EAAE,IAAY,EAAE,KAAa,EAAE,OAAO,GAAG,SAAS;IAC7G,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;AACzF,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAI,IAAS,EAAE,KAAa,EAAE,IAAY,EAAE,KAAa;IAC3F,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;AACjE,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAa;IACpD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;AACtD,CAAC"}