@heavybit/shared-lib 0.0.0-stage → 1.1.0

package/dist/cjs/messaging/publisher.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopMessageBus = exports.MessagePublisher = exports.UnroutableMessageError = void 0;
+exports.isUnroutableError = isUnroutableError;
+const errors_js_1 = require("../common/errors.js");
+const id_js_1 = require("../common/id.js");
+const index_js_1 = require("../logging/index.js");
+const envelope_js_1 = require("./envelope.js");
+/**
+ * The broker accepted a `mandatory` message but no queue was bound to receive it (the consumer has never
+ * started, or its binding is wrong). Retryable: the message is not lost — the caller (or the outbox relay)
+ * keeps it and tries again, and it goes through once the owner declares its queue.
+ */
+class UnroutableMessageError extends errors_js_1.ServiceUnavailableError {
+    exchange;
+    routingKey;
+    constructor(exchange, routingKey) {
+        super(`No queue is bound for ${exchange || '(default exchange)'} → ${routingKey}`, { code: 'UNROUTABLE' });
+        this.exchange = exchange;
+        this.routingKey = routingKey;
+    }
+}
+exports.UnroutableMessageError = UnroutableMessageError;
+function isUnroutableError(error) {
+    return error instanceof UnroutableMessageError;
+}
+const envelopeProps = (envelope, mandatory) => ({
+    mandatory, messageId: envelope.eventId, correlationId: envelope.correlationId, type: envelope.type,
+});
+/**
+ * Event and command publisher on a confirm channel: `publish()` resolves only once the broker
+ * has persisted the message, and rejects with 503 when the broker is unreachable so callers
+ * (or the outbox relay) can retry.
+ *
+ * Commands and direct queue sends are `mandatory`: a command has exactly one owner, so one that no
+ * queue receives is a fault, not a no-op. The broker returns it (`basic.return`, always before its
+ * confirm), and the send rejects with `UnroutableMessageError` instead of resolving as if delivered.
+ * Events stay non-mandatory: a topic event with no subscriber yet is normal fan-out.
+ */
+class MessagePublisher {
+    options;
+    handle = null;
+    logger;
+    /** Message ids the broker returned as unroutable, awaiting their confirm. */
+    returned = new Set();
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? index_js_1.silentLogger;
+    }
+    async init() {
+        const { topology } = this.options;
+        this.handle = await this.options.connection.registerChannel('publisher', async (channel) => {
+            await channel.assertExchange(topology.eventsExchange, 'topic', { durable: true });
+            await channel.assertExchange(topology.commandsExchange, 'direct', { durable: true });
+            channel.on('return', (message) => {
+                const id = message.properties.messageId;
+                if (typeof id === 'string')
+                    this.returned.add(id);
+            });
+        }, { confirm: true });
+    }
+    async publish(type, data, meta = {}) {
+        const envelope = (0, envelope_js_1.buildEnvelope)(type, data, this.options.source, meta);
+        await this.publishEnvelope(envelope);
+        return envelope;
+    }
+    async publishEnvelope(envelope) {
+        await this.write(this.options.topology.eventsExchange, envelope.type, envelope, envelopeProps(envelope, false));
+    }
+    async send(command, data, meta = {}) {
+        const envelope = (0, envelope_js_1.buildEnvelope)(command, data, this.options.source, meta);
+        await this.sendEnvelope(envelope);
+        return envelope;
+    }
+    async sendEnvelope(envelope) {
+        await this.write(this.options.topology.commandsExchange, this.options.topology.queue(envelope.type), envelope, envelopeProps(envelope, true));
+    }
+    /**
+     * Sends `payload` as-is (no envelope) to `queue` through the default exchange. The queue is the
+     * consumer's to declare, so it is not asserted here; a missing queue rejects as unroutable.
+     */
+    async sendToQueue(queue, payload, options = {}) {
+        await this.write('', queue, payload, { mandatory: true, messageId: options.messageId ?? (0, id_js_1.newId)(), correlationId: options.correlationId });
+    }
+    write(exchange, routingKey, body, props) {
+        const channel = this.handle?.current();
+        if (!channel) {
+            return Promise.reject(new errors_js_1.ServiceUnavailableError('Message broker unavailable'));
+        }
+        const { messageId } = props;
+        return new Promise((resolve, reject) => {
+            channel.publish(exchange, routingKey, Buffer.from(JSON.stringify(body)), {
+                persistent: true,
+                mandatory: props.mandatory,
+                contentType: 'application/json',
+                messageId,
+                correlationId: props.correlationId,
+                type: props.type,
+                timestamp: Math.floor(Date.now() / 1000),
+                appId: this.options.source,
+            }, (error) => {
+                // The broker sends `basic.return` before the confirm, so a returned message is already recorded here.
+                const unroutable = this.returned.delete(messageId);
+                if (error) {
+                    this.logger.error('Broker rejected message', { routingKey, messageId, error: String(error) });
+                    reject(new errors_js_1.ServiceUnavailableError('Message broker rejected the message', { cause: error }));
+                }
+                else if (unroutable) {
+                    this.logger.warn('Broker could not route message: no queue is bound', { exchange, routingKey, messageId });
+                    reject(new UnroutableMessageError(exchange, routingKey));
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+}
+exports.MessagePublisher = MessagePublisher;
+/** Stand-in when messaging is disabled (local tooling, tests): logs and drops. */
+class NoopMessageBus {
+    source;
+    logger;
+    constructor(source, logger = index_js_1.silentLogger) {
+        this.source = source;
+        this.logger = logger;
+    }
+    async publish(type, data, meta = {}) {
+        const envelope = (0, envelope_js_1.buildEnvelope)(type, data, this.source, meta);
+        this.logger.debug('Messaging disabled; event dropped', { type, eventId: envelope.eventId });
+        return envelope;
+    }
+    async publishEnvelope(envelope) {
+        this.logger.debug('Messaging disabled; event dropped', { type: envelope.type, eventId: envelope.eventId });
+    }
+    async send(command, data, meta = {}) {
+        const envelope = (0, envelope_js_1.buildEnvelope)(command, data, this.source, meta);
+        this.logger.debug('Messaging disabled; command dropped', { command, eventId: envelope.eventId });
+        return envelope;
+    }
+    async sendEnvelope(envelope) {
+        this.logger.debug('Messaging disabled; command dropped', { command: envelope.type, eventId: envelope.eventId });
+    }
+    async sendToQueue(queue) {
+        this.logger.debug('Messaging disabled; queue message dropped', { queue });
+    }
+}
+exports.NoopMessageBus = NoopMessageBus;
+//# sourceMappingURL=publisher.js.map

package/dist/cjs/messaging/publisher.js.map

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

package/dist/cjs/messaging/rpc.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RpcClient = exports.RpcServer = void 0;
+const errors_js_1 = require("../common/errors.js");
+const id_js_1 = require("../common/id.js");
+const index_js_1 = require("../logging/index.js");
+const REPLY_TO = 'amq.rabbitmq.reply-to';
+/**
+ * Request/response over RabbitMQ for the few synchronous cross-service calls that must fail
+ * cleanly (e.g. "create the profile before committing the account"). Uses direct reply-to, so
+ * no reply queue is declared per call, and sets the request TTL to the caller's timeout so a
+ * request the caller has given up on is never executed late.
+ */
+class RpcServer {
+    connection;
+    topology;
+    handles = [];
+    logger;
+    constructor(connection, topology, logger) {
+        this.connection = connection;
+        this.topology = topology;
+        this.logger = logger ?? index_js_1.silentLogger;
+    }
+    async handle(method, handler, options = {}) {
+        const queue = this.topology.queue(method);
+        this.handles.push(await this.connection.registerChannel(`rpc-server:${queue}`, async (channel) => {
+            await channel.assertQueue(queue, { durable: true });
+            await channel.prefetch(options.prefetch ?? 5);
+            await channel.consume(queue, (msg) => { if (msg)
+                void this.respond(channel, msg, handler); });
+        }));
+        this.logger.info('RPC method registered', { queue });
+    }
+    async respond(channel, msg, handler) {
+        let reply;
+        try {
+            const payload = JSON.parse(msg.content.toString('utf8'));
+            const data = await handler(payload, { correlationId: msg.properties.correlationId, callerService: msg.properties.appId });
+            reply = { ok: true, data };
+        }
+        catch (error) {
+            const status = (0, errors_js_1.isAppError)(error) ? error.statusCode : 500;
+            const message = (0, errors_js_1.isAppError)(error) && status < 500 ? error.message : 'RPC handler failed';
+            if (status >= 500)
+                this.logger.error('RPC handler error', { queue: msg.fields.routingKey, error: error.message });
+            reply = { ok: false, error: { status, code: (0, errors_js_1.isAppError)(error) ? error.code : 'INTERNAL_ERROR', message } };
+        }
+        if (msg.properties.replyTo) {
+            channel.sendToQueue(msg.properties.replyTo, Buffer.from(JSON.stringify(reply)), { correlationId: msg.properties.correlationId, contentType: 'application/json' });
+        }
+        channel.ack(msg);
+    }
+}
+exports.RpcServer = RpcServer;
+class RpcClient {
+    connection;
+    topology;
+    callerService;
+    handle = null;
+    pending = new Map();
+    logger;
+    constructor(connection, topology, callerService, logger) {
+        this.connection = connection;
+        this.topology = topology;
+        this.callerService = callerService;
+        this.logger = logger ?? index_js_1.silentLogger;
+    }
+    async init() {
+        this.handle = await this.connection.registerChannel('rpc-client', async (channel) => {
+            // A reconnect invalidates every in-flight reply.
+            this.failAll(new errors_js_1.ServiceUnavailableError('RPC channel reset'));
+            await channel.consume(REPLY_TO, (msg) => { if (msg)
+                this.onReply(msg); }, { noAck: true });
+        });
+    }
+    call(method, payload, options = {}) {
+        const channel = this.handle?.current();
+        if (!channel)
+            return Promise.reject(new errors_js_1.ServiceUnavailableError('Message broker unavailable'));
+        const timeoutMs = options.timeoutMs ?? 5000;
+        const id = (0, id_js_1.newId)();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                this.logger.warn('RPC timed out', { method, timeoutMs });
+                reject(new errors_js_1.ServiceUnavailableError(`Upstream did not respond in time (${method})`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve: resolve, reject, timer });
+            channel.sendToQueue(this.topology.queue(method), Buffer.from(JSON.stringify(payload)), {
+                correlationId: id,
+                replyTo: REPLY_TO,
+                contentType: 'application/json',
+                expiration: String(timeoutMs),
+                appId: this.callerService,
+                headers: options.correlationId ? { 'x-correlation-id': options.correlationId } : undefined,
+            });
+        });
+    }
+    onReply(msg) {
+        const entry = this.pending.get(msg.properties.correlationId);
+        if (!entry)
+            return;
+        this.pending.delete(msg.properties.correlationId);
+        clearTimeout(entry.timer);
+        try {
+            const reply = JSON.parse(msg.content.toString('utf8'));
+            if (reply.ok)
+                entry.resolve(reply.data);
+            else
+                entry.reject(new errors_js_1.AppError(reply.error.status, reply.error.message, { code: reply.error.code }));
+        }
+        catch (error) {
+            entry.reject(new errors_js_1.ServiceUnavailableError('Malformed RPC reply', { cause: error }));
+        }
+    }
+    failAll(error) {
+        for (const [id, entry] of this.pending) {
+            clearTimeout(entry.timer);
+            entry.reject(error);
+            this.pending.delete(id);
+        }
+    }
+}
+exports.RpcClient = RpcClient;
+//# sourceMappingURL=rpc.js.map

package/dist/cjs/messaging/rpc.js.map

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

package/dist/cjs/messaging/staff-notifier.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staffEmailListSchema = exports.StaffNotifier = exports.ConfiguredStaffRecipients = void 0;
+const zod_1 = require("zod");
+const notification_dispatch_js_1 = require("../contracts/notification-dispatch.js");
+const index_js_1 = require("../logging/index.js");
+/** Recipients from configuration (env), keyed by the permission an alert targets. */
+class ConfiguredStaffRecipients {
+    byPermission;
+    constructor(byPermission) {
+        this.byPermission = byPermission;
+    }
+    async resolve(permission) {
+        return [...(this.byPermission[permission] ?? [])];
+    }
+}
+exports.ConfiguredStaffRecipients = ConfiguredStaffRecipients;
+/**
+ * Stages one `notification:dispatch` per recipient through the outbox, in the caller's transaction, so an
+ * alert is sent if and only if the state change that raised it commits. Never sends email itself.
+ * An alert that resolves to nobody is logged as a warning (an unconfigured list must not fail silently).
+ */
+class StaffNotifier {
+    outbox;
+    recipients;
+    logger;
+    constructor(outbox, recipients, logger = index_js_1.silentLogger) {
+        this.outbox = outbox;
+        this.recipients = recipients;
+        this.logger = logger;
+    }
+    /** Returns how many commands were staged. */
+    async alert(executor, alert, meta = {}) {
+        const targets = await this.recipients.resolve(alert.permission);
+        if (targets.length === 0) {
+            this.logger.warn('Staff alert not sent: no recipients are configured', { template: alert.template, permission: alert.permission });
+            return 0;
+        }
+        for (const recipient of targets) {
+            const dispatch = {
+                template: alert.template,
+                category: 'staff',
+                recipient,
+                channels: alert.channels ?? ['email'],
+                data: alert.data,
+                bypassPreferences: true,
+                targetPermission: alert.permission,
+            };
+            await this.outbox.command(executor, notification_dispatch_js_1.NOTIFICATION_DISPATCH, dispatch, { ...meta, actorId: null });
+        }
+        return targets.length;
+    }
+}
+exports.StaffNotifier = StaffNotifier;
+const emailSchema = zod_1.z.string().email().max(notification_dispatch_js_1.DISPATCH_LIMITS.email);
+/**
+ * A comma-separated staff address list from env (`"a@x.io, b@y.io"`): trimmed, blanks dropped,
+ * de-duplicated case-insensitively. An invalid address fails validation, so a typo is caught at boot
+ * instead of dead-lettering in notification-service when the alert finally fires.
+ */
+exports.staffEmailListSchema = zod_1.z
+    .string()
+    .optional()
+    .transform((csv) => {
+    const seen = new Set();
+    return (csv ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((email) => email && !seen.has(email.toLowerCase()) && seen.add(email.toLowerCase()));
+})
+    .superRefine((emails, ctx) => {
+    for (const email of emails) {
+        if (!emailSchema.safeParse(email).success)
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: `Not a valid email address: ${email}` });
+    }
+})
+    .transform((emails) => emails.map((email) => ({ email })));
+//# sourceMappingURL=staff-notifier.js.map

package/dist/cjs/messaging/staff-notifier.js.map

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

package/dist/cjs/messaging/topology.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deadLetterQueueName = exports.retryQueueName = void 0;
+exports.createTopology = createTopology;
+function createTopology(options) {
+    const app = options.app.trim();
+    const prefix = options.prefix.trim();
+    if (!app || !prefix)
+        throw new Error('Topology requires both app and prefix');
+    return {
+        app,
+        prefix,
+        eventsExchange: `${app}.${prefix}.events`,
+        commandsExchange: `${app}.${prefix}.commands`,
+        queue: (name) => (name.startsWith(`${prefix}.`) ? name : `${prefix}.${name}`),
+    };
+}
+const retryQueueName = (queue, delayMs) => `${queue}.retry.${delayMs}`;
+exports.retryQueueName = retryQueueName;
+const deadLetterQueueName = (queue) => `${queue}.dlq`;
+exports.deadLetterQueueName = deadLetterQueueName;
+//# sourceMappingURL=topology.js.map

package/dist/cjs/messaging/topology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.js","sourceRoot":"","sources":["../../../src/messaging/topology.ts"],"names":[],"mappings":";;;AAiBA,wCAWC;AAXD,SAAgB,cAAc,CAAC,OAAwC;IACrE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC9E,OAAO;QACL,GAAG;QACH,MAAM;QACN,cAAc,EAAE,GAAG,GAAG,IAAI,MAAM,SAAS;QACzC,gBAAgB,EAAE,GAAG,GAAG,IAAI,MAAM,WAAW;QAC7C,KAAK,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;KACtF,CAAC;AACJ,CAAC;AAEM,MAAM,cAAc,GAAG,CAAC,KAAa,EAAE,OAAe,EAAE,EAAE,CAAC,GAAG,KAAK,UAAU,OAAO,EAAE,CAAC;AAAjF,QAAA,cAAc,kBAAmE;AACvF,MAAM,mBAAmB,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,GAAG,KAAK,MAAM,CAAC;AAAxD,QAAA,mBAAmB,uBAAqC"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/rate-limit/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLimiter = createLimiter;
+exports.consumeOrThrow = consumeOrThrow;
+exports.rateLimitMiddleware = rateLimitMiddleware;
+const rate_limiter_flexible_1 = require("rate-limiter-flexible");
+const response_js_1 = require("../common/response.js");
+const errors_js_1 = require("../common/errors.js");
+const index_js_1 = require("../logging/index.js");
+/** Redis limiter with an in-memory insurance limiter so a Redis outage never blocks traffic. */
+function createLimiter(options) {
+    const memory = new rate_limiter_flexible_1.RateLimiterMemory({ keyPrefix: options.keyPrefix, points: options.points, duration: options.durationSec, blockDuration: options.blockDurationSec ?? 0 });
+    if (!options.redis)
+        return memory;
+    return new rate_limiter_flexible_1.RateLimiterRedis({
+        storeClient: options.redis,
+        keyPrefix: options.keyPrefix,
+        points: options.points,
+        duration: options.durationSec,
+        blockDuration: options.blockDurationSec ?? 0,
+        insuranceLimiter: memory,
+    });
+}
+/**
+ * Consumes one point for `key`; throws TooManyRequestsError (429) when exhausted.
+ * For in-service checks such as per-identifier login throttling.
+ */
+async function consumeOrThrow(limiter, key, message) {
+    try {
+        await limiter.consume(key);
+    }
+    catch (rejection) {
+        if (typeof rejection?.msBeforeNext === 'number')
+            throw new errors_js_1.TooManyRequestsError(message);
+        throw rejection;
+    }
+}
+function rateLimitMiddleware(options) {
+    const limiter = createLimiter(options);
+    const logger = options.logger ?? index_js_1.silentLogger;
+    const keyOf = options.keyOf ?? ((req) => req.user?.id ?? req.ip ?? 'unknown');
+    return async (req, res, next) => {
+        try {
+            const result = await limiter.consume(keyOf(req));
+            res.setHeader('X-RateLimit-Limit', options.points);
+            res.setHeader('X-RateLimit-Remaining', result.remainingPoints);
+            next();
+        }
+        catch (rejection) {
+            const ms = rejection?.msBeforeNext;
+            if (typeof ms !== 'number') {
+                logger.error('Rate limiter failure; allowing request', { keyPrefix: options.keyPrefix, error: String(rejection) });
+                next();
+                return;
+            }
+            res.setHeader('Retry-After', Math.ceil(ms / 1000));
+            res.status(429).json((0, response_js_1.errorResponse)('Too many requests. Please try again later.', undefined, 'RATE_LIMITED'));
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/rate-limit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rate-limit/index.ts"],"names":[],"mappings":";;AAoBA,sCAWC;AAMD,wCAOC;AAOD,kDAsBC;AAvED,iEAAsG;AACtG,uDAAsD;AACtD,mDAA2D;AAC3D,kDAAmD;AAcnD,gGAAgG;AAChG,SAAgB,aAAa,CAAC,OAAyB;IACrD,MAAM,MAAM,GAAG,IAAI,yCAAiB,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,CAAC,gBAAgB,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5K,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAClC,OAAO,IAAI,wCAAgB,CAAC;QAC1B,WAAW,EAAE,OAAO,CAAC,KAAK;QAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,WAAW;QAC7B,aAAa,EAAE,OAAO,CAAC,gBAAgB,IAAI,CAAC;QAC5C,gBAAgB,EAAE,MAAM;KACzB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,cAAc,CAAC,OAA4B,EAAE,GAAW,EAAE,OAAgB;IAC9F,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,SAAS,EAAE,CAAC;QACnB,IAAI,OAAQ,SAAuC,EAAE,YAAY,KAAK,QAAQ;YAAE,MAAM,IAAI,gCAAoB,CAAC,OAAO,CAAC,CAAC;QACxH,MAAM,SAAS,CAAC;IAClB,CAAC;AACH,CAAC;AAOD,SAAgB,mBAAmB,CAAC,OAAmC;IACrE,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,uBAAY,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,SAAS,CAAC,CAAC;IAEvF,OAAO,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAiB,EAAE;QAC9E,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YACjD,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YACnD,GAAG,CAAC,SAAS,CAAC,uBAAuB,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;YAC/D,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,SAAS,EAAE,CAAC;YACnB,MAAM,EAAE,GAAI,SAAuC,EAAE,YAAY,CAAC;YAClE,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;gBACnH,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YACD,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;YACnD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAA,2BAAa,EAAC,4CAA4C,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;QAC/G,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/cjs/scheduling/index.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScheduledJob = void 0;
+exports.createLock = createLock;
+const node_crypto_1 = require("node:crypto");
+const index_js_1 = require("../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. */
+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 = (0, node_crypto_1.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.
+ */
+class ScheduledJob {
+    options;
+    timer = null;
+    running = false;
+    logger;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? index_js_1.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;
+        }
+    }
+}
+exports.ScheduledJob = ScheduledJob;
+//# sourceMappingURL=index.js.map

package/dist/cjs/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/cjs/security/index.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUrlSigner = createUrlSigner;
+const crypto_js_1 = require("../common/crypto.js");
+/** HMAC-SHA256 expiring URL signatures for private files (streams, downloads, originals). */
+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) => (0, crypto_js_1.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 (0, crypto_js_1.safeEqual)(params.sig, mac(`prefix:${params.sp}`, exp));
+            }
+            return (0, crypto_js_1.safeEqual)(params.sig, mac(path, exp));
+        },
+    };
+    return signer;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/security/index.ts"],"names":[],"mappings":";;AAoBA,0CA8BC;AAlDD,mDAA4D;AAmB5D,6FAA6F;AAC7F,SAAgB,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,IAAA,sBAAU,EAAC,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,IAAA,qBAAS,EAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;YAChE,CAAC;YACD,OAAO,IAAA,qBAAS,EAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC"}