@heavybit/shared-lib 0.0.0-stage → 1.2.0

package/dist/esm/scheduling/index.js

@@ -0,0 +1,83 @@
+import { randomUUID } from 'node:crypto';
+import { silentLogger } from '../logging/index.js';
+const RELEASE_SCRIPT = "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end";
+/** Redis lock (SET NX PX + token-checked release). Without Redis, a per-process lock. */
+export function createLock(redis, prefix = 'lock:') {
+    const local = new Set();
+    return {
+        async runExclusive(key, ttlMs, fn) {
+            if (!redis) {
+                if (local.has(key))
+                    return false;
+                local.add(key);
+                try {
+                    await fn();
+                }
+                finally {
+                    local.delete(key);
+                }
+                return true;
+            }
+            const token = randomUUID();
+            const acquired = await redis.set(prefix + key, token, 'PX', ttlMs, 'NX').catch(() => null);
+            if (acquired !== 'OK')
+                return false;
+            try {
+                await fn();
+            }
+            finally {
+                await redis.eval(RELEASE_SCRIPT, 1, prefix + key, token).catch(() => undefined);
+            }
+            return true;
+        },
+    };
+}
+/**
+ * Interval job that never overlaps itself, can be triggered early by events (`trigger()`), and
+ * optionally runs on one replica at a time.
+ */
+export class ScheduledJob {
+    options;
+    timer = null;
+    running = false;
+    logger;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? silentLogger;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => { void this.trigger(); }, this.options.intervalMs);
+        this.timer.unref?.();
+        if (this.options.runOnStart)
+            void this.trigger();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    async trigger() {
+        if (this.running)
+            return;
+        this.running = true;
+        try {
+            const run = async () => { await this.options.work(); };
+            if (this.options.lock)
+                await this.options.lock.runExclusive(`job:${this.options.name}`, Math.max(this.options.intervalMs, 30_000), run);
+            else
+                await run();
+        }
+        catch (error) {
+            this.logger.error('Scheduled job failed', { job: this.options.name, error: error.message });
+        }
+        finally {
+            this.running = false;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

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

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

package/dist/esm/security/index.js

@@ -0,0 +1,36 @@
+import { hmacSha256, safeEqual } from '../common/crypto.js';
+/** HMAC-SHA256 expiring URL signatures for private files (streams, downloads, originals). */
+export function createUrlSigner(secret) {
+    if (!secret || secret.length < 16)
+        throw new Error('URL signing secret must be at least 16 characters');
+    const expiry = (ttlSec) => Math.floor(Date.now() / 1000) + ttlSec;
+    const mac = (target, exp) => hmacSha256(secret, `${target}|${exp}`);
+    const signer = {
+        sign(path, ttlSec) {
+            const exp = expiry(ttlSec);
+            return { exp, sig: mac(path, exp) };
+        },
+        signPrefix(prefix, ttlSec) {
+            const exp = expiry(ttlSec);
+            return { exp, sig: mac(`prefix:${prefix}`, exp), sp: prefix };
+        },
+        signedPath(path, ttlSec, options = {}) {
+            const params = options.prefix ? signer.signPrefix(options.prefix, ttlSec) : signer.sign(path, ttlSec);
+            const qs = new URLSearchParams({ exp: String(params.exp), sig: params.sig, ...(params.sp ? { sp: params.sp } : {}) });
+            return `${path}${path.includes('?') ? '&' : '?'}${qs.toString()}`;
+        },
+        verify(path, params, now = Date.now()) {
+            const exp = Number(params.exp);
+            if (!params.sig || !Number.isFinite(exp) || exp * 1000 < now)
+                return false;
+            if (params.sp) {
+                if (!path.startsWith(params.sp))
+                    return false;
+                return safeEqual(params.sig, mac(`prefix:${params.sp}`, exp));
+            }
+            return safeEqual(params.sig, mac(path, exp));
+        },
+    };
+    return signer;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/security/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAmB5D,6FAA6F;AAC7F,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACxG,MAAM,MAAM,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;IAC1E,MAAM,GAAG,GAAG,CAAC,MAAc,EAAE,GAAW,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;IAEpF,MAAM,MAAM,GAAc;QACxB,IAAI,CAAC,IAAI,EAAE,MAAM;YACf,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3B,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACtC,CAAC;QACD,UAAU,CAAC,MAAM,EAAE,MAAM;YACvB,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3B,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,UAAU,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;QAChE,CAAC;QACD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAG,EAAE;YACnC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACtG,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACtH,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;QACpE,CAAC;QACD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;YACnC,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,IAAI,GAAG,GAAG;gBAAE,OAAO,KAAK,CAAC;YAC3E,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACd,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBAAE,OAAO,KAAK,CAAC;gBAC9C,OAAO,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;YAChE,CAAC;YACD,OAAO,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/esm/socket/index.js

@@ -0,0 +1,47 @@
+import { Server } from 'socket.io';
+import { verifyIdentityHeaders } from '../identity/index.js';
+import { silentLogger } from '../logging/index.js';
+export const userRoom = (userId) => `user:${userId}`;
+export function createSocketServer(httpServer, options) {
+    const logger = options.logger ?? silentLogger;
+    const io = new Server(httpServer, {
+        path: options.path,
+        cors: { origin: options.corsOrigins?.length ? options.corsOrigins : false, credentials: true },
+        ...(options.adapter ? { adapter: options.adapter } : {}),
+        ...options.serverOptions,
+    });
+    io.use(async (socket, next) => {
+        try {
+            const user = await options.authenticate(socket);
+            if (!user)
+                return next(new Error('Authentication failed'));
+            socket.data.user = user;
+            next();
+        }
+        catch (error) {
+            logger.warn('Socket authentication rejected', { error: error.message });
+            next(new Error('Authentication failed'));
+        }
+    });
+    io.on('connection', (socket) => {
+        const user = socket.data.user;
+        const rooms = options.rooms ? options.rooms(user) : [userRoom(user.id)];
+        void socket.join(rooms);
+        logger.debug('Socket connected', { userId: user.id, rooms });
+        socket.on('disconnect', (reason) => logger.debug('Socket disconnected', { userId: user.id, reason }));
+    });
+    return {
+        io,
+        emitToUser: (userId, event, payload) => { io.to(userRoom(userId)).emit(event, payload); },
+        emitToRoom: (room, event, payload) => { io.to(room).emit(event, payload); },
+        close: () => new Promise((resolve) => { io.close(() => resolve()); }),
+    };
+}
+/** Trusts the gateway-signed identity headers forwarded on the WebSocket upgrade request. */
+export function gatewaySocketAuth(secret) {
+    return (socket) => {
+        const result = verifyIdentityHeaders(socket.handshake.headers, secret);
+        return result.status === 'authenticated' ? result.user : null;
+    };
+}
+//# sourceMappingURL=index.js.map

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

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

package/dist/esm/testing/index.js

@@ -0,0 +1,66 @@
+import { newId } from '../common/id.js';
+import { signIdentityHeaders } from '../identity/index.js';
+import { buildEnvelope } from '../messaging/envelope.js';
+/** A logger spy: records every line (level, message, meta) so tests can assert on log context. */
+export class RecordingLogger {
+    lines = [];
+    debug(message, meta = {}) { this.lines.push({ level: 'debug', message, meta }); }
+    info(message, meta = {}) { this.lines.push({ level: 'info', message, meta }); }
+    warn(message, meta = {}) { this.lines.push({ level: 'warn', message, meta }); }
+    error(message, meta = {}) { this.lines.push({ level: 'error', message, meta }); }
+}
+/** An AuthUser for tests. */
+export function makeAuthUser(overrides = {}) {
+    return { id: newId(), email: 'user@example.com', roles: [], permissions: [], scopes: {}, attrs: {}, ...overrides };
+}
+/** Gateway-signed identity headers for route tests (use with supertest `.set()`). */
+export function identityHeaders(user, secret) {
+    return signIdentityHeaders(user, secret);
+}
+/** Records everything published/sent so tests can assert on events, commands and direct queue sends. */
+export class RecordingBus {
+    source;
+    events = [];
+    commands = [];
+    queued = [];
+    failWith = null;
+    constructor(source = 'test') {
+        this.source = source;
+    }
+    async publish(type, data, meta) {
+        if (this.failWith)
+            throw this.failWith;
+        const envelope = buildEnvelope(type, data, this.source, meta);
+        this.events.push(envelope);
+        return envelope;
+    }
+    async publishEnvelope(envelope) {
+        if (this.failWith)
+            throw this.failWith;
+        this.events.push(envelope);
+    }
+    async send(command, data, meta) {
+        if (this.failWith)
+            throw this.failWith;
+        const envelope = buildEnvelope(command, data, this.source, meta);
+        this.commands.push(envelope);
+        return envelope;
+    }
+    async sendEnvelope(envelope) {
+        if (this.failWith)
+            throw this.failWith;
+        this.commands.push(envelope);
+    }
+    async sendToQueue(queue, payload, options = {}) {
+        if (this.failWith)
+            throw this.failWith;
+        this.queued.push({ queue, payload, options });
+    }
+    eventsOfType(type) {
+        return this.events.filter((e) => e.type === type);
+    }
+    commandsOfType(command) {
+        return this.commands.filter((e) => e.type === command);
+    }
+}
+//# sourceMappingURL=index.js.map

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

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

package/dist/esm/types/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":""}

package/dist/esm/validation/index.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { ID_PATTERN } from '../common/id.js';
+import { ValidationError } from '../common/errors.js';
+export const idSchema = z.string().regex(ID_PATTERN, 'Invalid id');
+export const idParamSchema = z.object({ id: idSchema });
+export const paginationSchema = z.object({
+    page: z.coerce.number().int().min(1).default(1),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+export const sortOrderSchema = z.enum(['asc', 'desc']).default('desc');
+export const emailSchema = z.string().trim().toLowerCase().email('Invalid email address').max(191);
+export const slugSchema = z.string().trim().min(1).max(120).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Invalid slug');
+/** Length-first password rule (NIST 800-63B): 8–128 chars, no composition rules. Tighten per app if needed. */
+export const passwordSchema = z.string().min(8, 'Password must be at least 8 characters').max(128, 'Password is too long');
+/** Accepts `true/false/1/0/yes/no` from query strings. */
+export const booleanish = z.union([z.boolean(), z.enum(['true', 'false', '1', '0', 'yes', 'no'])]).transform((v) => v === true || v === 'true' || v === '1' || v === 'yes');
+/** Comma list or repeated query param → string[]. */
+export const csvList = z.union([z.string(), z.array(z.string())]).transform((v) => (Array.isArray(v) ? v : v.split(',')).map((s) => s.trim()).filter(Boolean));
+/** Converts Zod issues into the `{ field: [messages] }` shape used by the error envelope. */
+export function zodIssuesToErrors(error) {
+    const errors = {};
+    for (const issue of error.issues) {
+        const key = issue.path.join('.') || '_';
+        (errors[key] ??= []).push(issue.message);
+    }
+    return errors;
+}
+/** Parses `input` or throws a ValidationError (422). */
+export function parseOrThrow(schema, input) {
+    const result = schema.safeParse(input);
+    if (!result.success)
+        throw new ValidationError(zodIssuesToErrors(result.error));
+    return result.data;
+}
+export { z };
+//# sourceMappingURL=index.js.map

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

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

package/dist/types/access/index.d.ts

@@ -0,0 +1,50 @@
+import type { AuthUser } from '../types/index.js';
+/**
+ * Permission and ownership checks. Keep every authorization decision in these helpers (not
+ * inline in controllers) so the rules are identical across endpoints and services.
+ *
+ * Permission strings are dotted (`users.manage`, `media.manage.any`). Grants may use
+ * wildcards: `*` grants everything; `media.*` grants any permission starting with `media.`.
+ */
+export declare const WILDCARD_PERMISSION = "*";
+/** True when the user holds at least one of `required`. */
+export declare function hasPermission(user: Pick<AuthUser, 'permissions'> | null | undefined, ...required: string[]): boolean;
+export declare function hasAllPermissions(user: Pick<AuthUser, 'permissions'> | null | undefined, ...required: string[]): boolean;
+export declare function hasRole(user: Pick<AuthUser, 'roles'> | null | undefined, ...roles: string[]): boolean;
+export declare function requireUser(user: AuthUser | null | undefined): AuthUser;
+export declare function assertPermission(user: AuthUser | null | undefined, ...required: string[]): AuthUser;
+/** IDs the user may act on within a scope (e.g. profiles they are a member of). */
+export declare function scopeIds(user: Pick<AuthUser, 'scopes'> | null | undefined, scope: string): string[];
+/**
+ * Self-owned data: allow when the caller *is* `ownerUserId`, or holds `bypassPermission`.
+ * Throws ForbiddenError otherwise.
+ */
+export declare function assertSelfOrPermission(user: AuthUser | null | undefined, ownerUserId: string, bypassPermission?: string): AuthUser;
+/**
+ * Scoped data: allow when `resourceScopeId` is one of the caller's scope IDs, or the caller holds
+ * `bypassPermission`.
+ */
+export declare function assertInScope(user: AuthUser | null | undefined, scope: string, resourceScopeId: string, bypassPermission?: string): AuthUser;
+/**
+ * Resolves the single scope ID a request acts on. With one membership it is implicit; with
+ * several the client names one (e.g. `x-active-profile-id`), which must be a member ID.
+ * IDs from request bodies are never trusted — only the gateway-signed scopes.
+ */
+export declare function resolveActiveScopeId(user: AuthUser | null | undefined, scope: string, requested?: string | null): string;
+/**
+ * Like `resolveActiveScopeId`, for screens that work without a selector: with several memberships
+ * and none named, the first (primary) one is used. A named ID must still be a member ID.
+ */
+export declare function resolvePrimaryScopeId(user: AuthUser | null | undefined, scope: string, requested?: string | null): string;
+export type OwnerFilter = {
+    all: true;
+} | {
+    all: false;
+    ids: string[];
+};
+/**
+ * Repository filter for list queries: `{ all: true }` for callers holding `bypassPermission`,
+ * otherwise the caller's own scope IDs (possibly empty → return nothing).
+ */
+export declare function ownerFilter(user: AuthUser | null | undefined, scope: string, bypassPermission?: string): OwnerFilter;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/access/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/access/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAOvC,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAGpH;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAGxH;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAErG;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,CAGvE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,QAAQ,CAInG;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAEnG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAKlI;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAK5I;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASxH;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGzH;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,CAIpH"}

package/dist/types/alerting/index.d.ts

@@ -0,0 +1,43 @@
+import type { Logger } from '../types/index.js';
+/** Sends operator alerts (DLQ depth, stalled queues…). Never throws: alerting must not break its caller. */
+export interface AlertSender {
+    /** True when the alert was accepted; false when it was not sent (not configured, or the hook failed). */
+    send(messages: string[], options?: {
+        alertType?: string;
+    }): Promise<boolean>;
+}
+/** The body the platform's Slack notification app accepts (the same one `health-monitor.sh` posts). */
+export interface SlackAlertPayload {
+    messages: string[];
+    alert_type: string;
+    app_name: string;
+    environment: string;
+    consolidate: boolean;
+}
+export interface SlackAlerterOptions {
+    /** The notification app's URL. Empty = not configured: alerts are logged and skipped. */
+    url: string;
+    /** Product name shown on the alert, e.g. `Showbiz`. */
+    app: string;
+    /** `staging`, `production`… */
+    environment: string;
+    logger?: Logger;
+    timeoutMs?: number;
+    /** Injected in tests; defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Posts alerts to a Slack notification webhook as `{ messages, alert_type, app_name, environment, consolidate }`.
+ * An unset URL is a valid "alerts off" configuration: the first skipped alert is warned about once, then silently.
+ */
+export declare class SlackAlerter implements AlertSender {
+    private readonly options;
+    private warnedUnconfigured;
+    private readonly logger;
+    constructor(options: SlackAlerterOptions);
+    get configured(): boolean;
+    send(messages: string[], options?: {
+        alertType?: string;
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/alerting/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/alerting/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,4GAA4G;AAC5G,MAAM,WAAW,WAAW;IAC1B,yGAAyG;IACzG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9E;AAED,uGAAuG;AACvG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,WAAW;IAIlC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,OAAO,EAAE,mBAAmB;IAIzD,IAAI,UAAU,IAAI,OAAO,CAExB;IAEK,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAgCvF"}

package/dist/types/cache/index.d.ts

@@ -0,0 +1,45 @@
+import { Redis, type RedisOptions } from 'ioredis';
+import type { Logger } from '../types/index.js';
+export interface CacheSetOptions {
+    ttlSec?: number;
+    /** Tags let one call invalidate every key derived from an entity (e.g. `user:01J…`). */
+    tags?: string[];
+}
+export interface Cache {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    del(...keys: string[]): Promise<void>;
+    /** Cache-aside: returns the cached value or loads, stores and returns it. Concurrent misses share one load. */
+    wrap<T>(key: string, loader: () => Promise<T>, options?: CacheSetOptions & {
+        cacheNull?: boolean;
+    }): Promise<T>;
+    invalidateTags(...tags: string[]): Promise<void>;
+}
+export interface CacheOptions {
+    /** Null → in-memory only (tests, local tooling). */
+    redis: Redis | null;
+    /** Key namespace, e.g. `auth` → keys `auth:<key>`. Combine with the client-level env prefix. */
+    namespace: string;
+    defaultTtlSec?: number;
+    /** Upper bound for the in-memory layer / fallback. */
+    memoryMaxEntries?: number;
+    logger?: Logger;
+}
+/**
+ * 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 declare function createCache(options: CacheOptions): Cache;
+export interface RedisClientOptions {
+    url?: string;
+    db?: number;
+    /** Prepended to every key by ioredis, e.g. `showbiz:prod:`. */
+    keyPrefix?: string;
+    logger?: Logger;
+    options?: RedisOptions;
+}
+/** ioredis client that never crashes the process on connection errors and retries forever. */
+export declare function createRedisClient(opts: RedisClientOptions): Redis;
+export type { Redis };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,+GAA+G;IAC/G,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChH,cAAc,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,gGAAgG;IAChG,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA+BD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CA+FxD;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,KAAK,CAmBjE;AAED,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/types/common/async.d.ts

@@ -0,0 +1,14 @@
+export declare const sleep: (ms: number) => Promise<void>;
+export interface RetryOptions {
+    retries: number;
+    /** Delay before attempt n (1-based retry number). Default: 200ms × 2^(n-1), capped at 5s. */
+    delayMs?: (attempt: number) => number;
+    shouldRetry?: (error: unknown) => boolean;
+}
+/** Runs `fn`, retrying failures with exponential back-off. */
+export declare function retry<T>(fn: (attempt: number) => Promise<T>, options: RetryOptions): Promise<T>;
+/** Rejects with `onTimeout()` if `promise` does not settle within `ms`. */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, onTimeout: () => Error): Promise<T>;
+/** Splits `items` into arrays of at most `size`. */
+export declare function chunk<T>(items: readonly T[], size: number): T[][];
+//# sourceMappingURL=async.d.ts.map

package/dist/types/common/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../../src/common/async.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CAAsD,CAAC;AAEtG,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC3C;AAED,8DAA8D;AAC9D,wBAAsB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAYrG;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAMlG;AAED,oDAAoD;AACpD,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAIjE"}

package/dist/types/common/audit.d.ts

@@ -0,0 +1,17 @@
+export type AuditAction = 'create' | 'update' | 'delete';
+type AuditRow<T> = Omit<T, 'id' | 'createdAt' | 'updatedAt'> & {
+    id: string;
+    parentId: string;
+    action: AuditAction;
+};
+/**
+ * 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 declare function buildAuditRow<T extends {
+    id: string;
+}>(row: T, action: AuditAction, actorId?: string | null): AuditRow<T>;
+export {};
+//# sourceMappingURL=audit.d.ts.map

package/dist/types/common/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/common/audit.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEzD,KAAK,QAAQ,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC;AAErH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,MAAM,GAAG,IAAW,GAAG,QAAQ,CAAC,CAAC,CAAC,CAS/H"}

package/dist/types/common/crypto.d.ts

@@ -0,0 +1,18 @@
+export declare function sha256(value: string | Buffer): string;
+export declare function hmacSha256(secret: string | Buffer, value: string): string;
+/** Constant-time string comparison (false when lengths differ). */
+export declare function safeEqual(a: string, b: string): boolean;
+/** URL-safe random token (default 32 bytes of entropy). */
+export declare function randomToken(bytes?: number): string;
+/** Numeric one-time code, e.g. `'042917'`. Uses a CSPRNG. */
+export declare function randomNumericCode(length?: number): string;
+/**
+ * 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 declare function hashToken(token: string, pepper: string): string;
+/** AES-256-GCM encrypt. Output: `v1:<iv>:<tag>:<ciphertext>` (base64url parts). */
+export declare function encryptSecret(plaintext: string, key: string): string;
+export declare function decryptSecret(payload: string, key: string): string;
+export declare function isEncryptedSecret(value: unknown): value is string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/types/common/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/common/crypto.ts"],"names":[],"mappings":"AAEA,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAIvD;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,KAAK,SAAK,GAAG,MAAM,CAE9C;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,MAAM,SAAI,GAAG,MAAM,CAIpD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/D;AAcD,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQlE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEjE"}

package/dist/types/common/errors.d.ts

@@ -0,0 +1,71 @@
+export type ErrorDetails = Record<string, string[]>;
+/**
+ * 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 declare class AppError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly errors?: ErrorDetails;
+    /** Consumers dead-letter immediately instead of retrying when this is false. */
+    readonly retryable: boolean;
+    constructor(statusCode: number, message: string, options?: {
+        code?: string;
+        errors?: ErrorDetails;
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+export declare class BadRequestError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+        errors?: ErrorDetails;
+    });
+}
+export declare class UnauthorizedError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+    });
+}
+export declare class ForbiddenError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+    });
+}
+export declare class NotFoundError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+    });
+}
+export declare class ConflictError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+        errors?: ErrorDetails;
+    });
+}
+export declare class ValidationError extends AppError {
+    constructor(errors: ErrorDetails, message?: string);
+}
+export declare class TooManyRequestsError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+    });
+}
+export declare class ServiceUnavailableError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+/** A failure that will never succeed on retry (bad payload, unknown template, …). */
+export declare class NonRetryableError extends AppError {
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+export declare function isAppError(error: unknown): error is AppError;
+/** Message safe to show a caller; hides internals for unexpected errors. */
+export declare function publicMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/common/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/common/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAQ9I;AAgBD,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,SAAgB,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAO;CAC5F;AACD,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,SAA4B,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CACjF;AACD,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,SAAsD,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CAC3G;AACD,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,SAAuB,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CAC5E;AACD,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,SAA4B,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAO;CACxG;AACD,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,MAAM,EAAE,YAAY,EAAE,OAAO,SAAsB;CAChE;AACD,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,SAA+C,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CACpG;AACD,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,SAAoC,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAC1G;AAED,qFAAqF;AACrF,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAG9E;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIpD"}

package/dist/types/common/id.d.ts

@@ -0,0 +1,14 @@
+export declare const ID_LENGTH = 26;
+export declare const ID_PATTERN: RegExp;
+/** A new time-ordered, monotonic ULID. */
+export declare function newId(): string;
+export declare function isId(value: unknown): value is string;
+/** Creation time encoded in a ULID. */
+export declare function idTimestamp(id: string): Date;
+/**
+ * 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 declare function fixtureId(namespace: string, n: number): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/types/common/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../../src/common/id.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,eAAO,MAAM,UAAU,QAA6B,CAAC;AAErD,0CAA0C;AAC1C,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEpD;AAED,uCAAuC;AACvC,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5C;AAID;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9D"}