@smounters/kit 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 2.2.0 - 2026-07-30
+
+### Added
+- Первая версия `@smounters/kit` — батарейки к `@smounters/core`, собранные из кода
+  `smounters-apps`, который к этому моменту был переписан заново в трёх проектах:
+  `kit/log` (журнал), `kit/redis` (подключение, pub/sub, кеш, распределённый лок),
+  `kit/http` (реальный IP клиента, сквозной id запроса, точные байты тела, лимит частоты),
+  `kit/net` (SSRF-проверки и `safeFetch`), `kit/config` (zod-препроцессоры env),
+  `kit/money` (decimal, масштабы, округление, проверка проводки), `kit/rpc`
+  (`ProtoValidateInterceptor`), `kit/util` (`ulid`, `redactSecrets`).
+- Тесты на чистые части: 24 теста (деньги, диапазоны адресов и `assertPublicUrl`, ulid и сокрытие
+  секретов).
+
+### Добавлено по ходу внедрения
+- `RedisConnectionOptions.awaitReady` — ждать подключения на старте и НЕ поднимать процесс без Redis.
+  Два защитимых поведения, поэтому это выбор, а не умолчание: api, который отдаёт ещё и страницы,
+  должен стартовать и предупредить (недоступный кеш — не недоступный продукт), а воркер, вся работа
+  которого идёт из очереди, честнее не стартовать вовсе. Понадобилось второму потребителю.
+- `kit/log` переизлучает типы ядра (`LogTransport` и рядом): приложению, объявляющему возвращаемый тип
+  транспортов, не нужен второй импорт из `@smounters/core` ради имени.
+
+### Обобщения при выносе
+- Политика вынесена наружу: лимитер частоты получает `bucketFor(req)` вместо захардкоженных адресов,
+  `RedisService` — строку подключения значением-провайдером (`REDIS_CONNECTION`), журнал — имя сервиса
+  и окружение параметрами, хук контекста — имя заголовка.
+- `RedisService` очищен от доменных методов (мягкий лок заказа уехал в свою фичу приложения).
+- Добавлено `quantizeToDecimals` — квантование по знакам АКТИВА, а не по масштабу книги: без него
+  «ожидаемая» сумма может оказаться неоплатной точно у токена с шестью знаками.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio (@smounters)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @smounters/kit
+
+Батарейки к [`@smounters/core`](https://www.npmjs.com/package/@smounters/core): структурный журнал,
+Redis с распределённым локом, защита от SSRF, деньги на decimal, сквозной id запроса, схемы для env.
+
+```bash
+npm i @smounters/kit @smounters/core
+```
+
+Каждая часть — отдельный подпуть, а тяжёлые зависимости объявлены **необязательными** peer-зависимостями:
+ставится только то, чем пользуетесь. Взяли `kit/money` — `ioredis` и `fastify` не нужны.
+
+| подпуть | что внутри | нужны |
+|---|---|---|
+| `kit/log` | транспорты для `configureLogger()` + автономный логгер: одна строка JSON вне local, цветная строка локально | `@smounters/core` |
+| `kit/redis` | `RedisService`: подключение, pub/sub, кеш «чтение сквозь», распределённый лок | `@smounters/core`, `ioredis` |
+| `kit/http` | реальный IP клиента, сквозной id запроса, точные байты тела, лимит частоты | `fastify` |
+| `kit/net` | `isPrivateIp`, `assertPublicUrl`, `safeFetch` | — |
+| `kit/config` | zod-препроцессоры для разбора env | `zod` |
+| `kit/money` | decimal-арифметика, масштабы, округление, проверка сбалансированности проводки | — |
+| `kit/rpc` | `ProtoValidateInterceptor` — правила `buf.validate` из контракта, enforced транспортом | `@smounters/core`, `@connectrpc/connect`, `@bufbuild/*` |
+| `kit/util` | `ulid`, `redactSecrets` | — |
+
+## Что здесь НЕ лежит и почему
+
+**Механизм — здесь, политика — в приложении.** Это правило видно в подписях: лимитер частоты не знает
+ваших адресов, он получает `bucketFor(req)`; `RedisService` не знает, откуда взялась строка подключения,
+она приходит значением-провайдером; журнал не знает имени сервиса, оно передаётся.
+
+Поэтому сюда сознательно **не** попали: словарь ваших HTTP-заголовков (это словарь продукта, не
+инфраструктура), план счетов и любые доменные ключи Redis, матрицы прав.
+
+## Журнал
+
+```ts
+import { createTransports, createLogger } from "@smounters/kit/log";
+
+app.configureLogger({ transports: createTransports({ service: "api" }) });
+const logger = createLogger({ service: "api" }); // для кода вне DI: старт процесса, скрипты
+```
+
+Вне `local` каждая запись — один объект JSON в строку, поэтому сборщик логов достаёт поля без разбора
+регулярками. Структурный первый аргумент раскладывается в поля верхнего уровня:
+
+```ts
+this.logger.info({ type: "payment", event: "credited", amount, currency });
+```
+
+Если в приложении зарегистрирован `requestContextHook`, к КАЖДОЙ строке сам подмешивается `reqId` —
+вызывающий код о нём не знает.
+
+## Redis
+
+Пакет не решает, откуда берётся конфигурация: подключение приходит значением-провайдером.
+
+```ts
+import { REDIS_CONNECTION, RedisService } from "@smounters/kit/redis";
+
+@Module({
+  providers: [{ provide: REDIS_CONNECTION, useValue: { url: appConfig.REDIS_URL } }, RedisService],
+  exports: [RedisService],
+  global: true,
+})
+export class RedisModule {}
+```
+
+`withLock(key, ttlSec, fn)` — для периодических задач при нескольких репликах: работа делается **один
+раз на кластер**, а не по разу на процесс. Освобождение — сравнение-и-удаление по случайному токену,
+поэтому лок, истёкший на середине и перехваченный другим процессом, не будет снят предыдущим владельцем.
+`ttlSec` обязан превышать худшее время работы `fn`.
+
+## Сквозной id запроса
+
+```ts
+import { clientIpNormalizeHook, requestContextHook } from "@smounters/kit/http";
+
+app.addHook("onRequest", clientIpNormalizeHook());              // ПЕРВЫМ
+app.addHook("onRequest", requestContextHook({ headerName: "X-Request-Id" }));
+```
+
+Порядок обязателен: нормализация IP должна быть первой (на `req.ip` опираются журнал и лимитер), а
+контекст — до всего остального, потому что он продолжает цепочку внутри `AsyncLocalStorage` и его видят
+только зарегистрированные ПОЗЖЕ хуки.
+
+Зачем вообще: связать «пришёл вебхук → поставлена задача → воркер сделал внешний вызов» иначе нечем,
+кроме метки времени, — процессы разные, а логи в одном потоке. Протаскивать id параметром через все
+слои значило бы править сигнатуру каждой функции ради поля, которое нужно только журналу.
+
+## Деньги
+
+Ни одна функция не принимает и не возвращает JS-число: `double` не представляет 0.1 точно, а книга,
+которая не может представить свои же суммы, перестаёт сходиться в первый же день. Суммы ходят
+десятичными **строками**.
+
+```ts
+import { isBalanced, quantizeToDecimals, ROUND_UP, toMoneyAmount } from "@smounters/kit/money";
+
+toMoneyAmount("10.00001");            // null — точнее, чем хранит колонка: отклонить, а не округлить
+isBalanced(lines);                    // ≥2 строки, без нулевых, сумма знаковых РОВНО 0
+quantizeToDecimals(due, 6, ROUND_UP); // сумма, достижимая у токена с 6 знаками
+```
+
+`quantizeToDecimals` нужен, когда сумма должна быть **достижима на другой стороне**: токен с шестью
+знаками не переведёт значение с восемью, и «ожидаемая» сумма, скруглённая до масштаба книги, окажется
+неоплатной точно — а строгое сравнение назовёт это недоплатой, которой плательщик не мог избежать.
+
+## Защита от SSRF
+
+```ts
+import { safeFetch, SsrfBlockedError } from "@smounters/kit/net";
+```
+
+`assertPublicUrl` в одиночку проверяет только ПЕРВЫЙ адрес, а `fetch` по умолчанию идёт по
+перенаправлениям — публичный хост мог ответить 302 на приватный адрес, и проверка обходилась.
+`safeFetch` идёт по перенаправлениям вручную и проверяет каждый шаг. `SsrfBlockedError` отделён от
+сетевых ошибок намеренно: это ПОСТОЯННАЯ ошибка настройки, её нельзя перевыкладывать в очередь на
+повтор.
+
+Известный предел: гонку DNS-rebinding между проверкой и подключением так не закрыть — для этого нужна
+фиксация адреса на момент соединения. Отсекаются реальные случаи: ошибка настройки и попытка достать
+адрес метаданных облака.

package/dist/config/index.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+/** Accepts true/1/yes/on and false/0/no/off (case-insensitive); anything else is a validation error. */
+export declare const booleanSchema: () => z.ZodPreprocess<z.ZodBoolean>;
+/** Parses a numeric string. An empty or non-numeric value passes through so zod reports it clearly. */
+export declare const numberSchema: () => z.ZodPreprocess<z.ZodNumber>;
+/** String enum with optional normalization (e.g. lower-casing `ENVIRONMENT` before matching). */
+export declare const enumSchema: <const T extends readonly [string, ...string[]]>(values: T, normalize?: (v: string) => string) => z.ZodPreprocess<z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>>;

package/dist/config/index.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+// Preprocessors for parsing the environment: every `process.env` value is a string, so a schema that
+// expects a boolean or a number has to coerce first. Used with a single top-level schema so a malformed
+// value fails at startup with a per-field report instead of turning into a silent default at runtime.
+const TRUE_VALUES = new Set(["true", "1", "yes", "on"]);
+const FALSE_VALUES = new Set(["false", "0", "no", "off"]);
+/** Accepts true/1/yes/on and false/0/no/off (case-insensitive); anything else is a validation error. */
+export const booleanSchema = () => z.preprocess((v) => {
+    if (typeof v === "boolean")
+        return v;
+    if (typeof v === "string") {
+        const n = v.toLowerCase().trim();
+        if (TRUE_VALUES.has(n))
+            return true;
+        if (FALSE_VALUES.has(n))
+            return false;
+    }
+    return v;
+}, z.boolean());
+/** Parses a numeric string. An empty or non-numeric value passes through so zod reports it clearly. */
+export const numberSchema = () => z.preprocess((v) => {
+    if (typeof v === "number")
+        return v;
+    if (typeof v === "string") {
+        const n = v.trim();
+        if (!n)
+            return v;
+        const num = Number(n);
+        if (!Number.isNaN(num))
+            return num;
+    }
+    return v;
+}, z.number());
+/** String enum with optional normalization (e.g. lower-casing `ENVIRONMENT` before matching). */
+export const enumSchema = (values, normalize) => z.preprocess((v) => (typeof v === "string" && normalize ? normalize(v) : v), z.enum(values));

package/dist/http/index.d.ts

@@ -0,0 +1,104 @@
+import { Readable } from "node:stream";
+import type { FastifyReply, FastifyRequest } from "fastify";
+type HeaderValue = string | string[] | null | undefined;
+export type HeaderGetter = (name: string) => HeaderValue;
+/**
+ * The real external client IP behind a CDN → own edge → ingress → pod chain.
+ *
+ * Trust order (first non-empty wins) and why it matters: with `trustProxy` enabled the app trusts every
+ * hop, so `X-Forwarded-For` is client-controllable end to end — a caller can prepend a forged left-most
+ * entry that the CDN only appends to. `CF-Connecting-IP` (set by Cloudflare) and `X-Real-IP` (set by your
+ * own edge) are OVERWRITTEN by that infrastructure and therefore cannot be spoofed from outside, so they
+ * win; XFF is the last resort. Empty string when nothing usable is present (local dev, health checks).
+ *
+ * Pass a getter that reads by lower-case name: works for Fastify `req.headers` and for WHATWG
+ * `Headers.get` alike.
+ */
+export declare function clientIp(get: HeaderGetter): string;
+/**
+ * Fastify `onRequest`: rewrite the raw `x-forwarded-for` so that Fastify's own `req.ip` — and everything
+ * built on it (framework access logs, rate-limit keys, stored remote addresses) — resolves to the real
+ * client instead of a spoofable left-most entry. Only rewrites when a trustworthy infrastructure header
+ * is present, so local development and non-CDN hosts keep default behaviour.
+ *
+ * MUST be registered FIRST: Fastify runs `onRequest` hooks in registration order, and everything reading
+ * `req.ip` afterwards depends on this.
+ */
+export declare function clientIpNormalizeHook(): (req: FastifyRequest, _reply: FastifyReply) => Promise<void>;
+export interface RequestContext {
+    requestId: string;
+    /**
+     * Where the chain started: `http` — an external call, `job` — a queue worker, `event` — a message
+     * consumer, `cron` — a scheduled tick. Lets a log query tell "someone called us" from "we started it".
+     */
+    source: "http" | "job" | "event" | "cron";
+}
+/**
+ * `req_<hex>` — one shape of id across every process, safe to hand to a caller for a support request.
+ */
+export declare function newRequestId(): string;
+export declare function currentRequestContext(): RequestContext | undefined;
+export declare function currentRequestId(): string | undefined;
+/** Run work inside a context. Everything asynchronous started inside sees the same id. */
+export declare function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T;
+export declare function acceptRequestId(inbound: string | undefined): string;
+/**
+ * Fastify `onRequest`: open a context for the whole request and echo the id back in a header.
+ *
+ * Why AsyncLocalStorage and not a parameter: threading an id through every layer (RPC → service →
+ * service → repository) would mean changing every signature for a field only the logs care about. The log
+ * transport reads the context itself, so calling code stays unaware.
+ *
+ * Register AFTER `clientIpNormalizeHook` and BEFORE everything else: this hook continues the chain inside
+ * `storage.run`, so only hooks registered later see the context.
+ */
+export declare function requestContextHook(options?: {
+    headerName?: string;
+}): (req: FastifyRequest, reply: FastifyReply, done: () => void) => void;
+/** Body over the limit. `statusCode` is the Fastify idiom — the default error handler renders 413. */
+export declare class PayloadTooLargeError extends Error {
+    readonly statusCode = 413;
+    constructor(limit: number);
+}
+/**
+ * Drain a stream into one Buffer, ABORTING as soon as the limit is passed: the offending chunk is not
+ * kept and no further chunks are pulled, so an oversized body never sits in the heap in full.
+ */
+export declare function bufferCapped(payload: AsyncIterable<Buffer | string>, limit: number): Promise<Buffer>;
+/**
+ * Capture the EXACT request bytes on `req.rawBody` and return a fresh equivalent stream so the normal
+ * parser still fills `req.body` for the handler.
+ *
+ * Needed wherever a signature is computed over the raw bytes: a re-serialized object produces different
+ * bytes (key order, spacing, number formatting) and the verification fails for a legitimate caller.
+ */
+export declare function stashRawBodyStream(req: FastifyRequest, payload: Readable, limit: number): Promise<Readable>;
+/** Minimal shape of the counter store — structural, so this module needs no Redis dependency. */
+export interface RateLimitStore {
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<unknown>;
+}
+export interface RateLimitBucket {
+    /** Bucket name; part of the counter key, so two buckets never share a counter. */
+    name: string;
+    limit: number;
+}
+export interface RateLimitOptions {
+    store: () => RateLimitStore;
+    /** Window length in seconds. A getter, because a limit is a business setting that may change live. */
+    windowSec: () => Promise<number> | number;
+    /** Which bucket a request belongs to — the POLICY, and it stays in the application. null = exempt. */
+    bucketFor: (req: FastifyRequest) => Promise<RateLimitBucket | null> | RateLimitBucket | null;
+}
+/**
+ * Fastify `onRequest`: fixed-window counter per (bucket, IP), kept in the shared store so the limit is
+ * global across replicas rather than per-process.
+ *
+ * FAIL-OPEN by design: a store outage must not become an outage of the product. A limiter that blocks
+ * everything when Redis blinks is worse than one that briefly stops limiting.
+ *
+ * Requires `clientIpNormalizeHook` to be registered earlier, otherwise the key is built from a
+ * spoofable address and the limit can be evaded by forging a header.
+ */
+export declare function rateLimitHook(options: RateLimitOptions): (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+export {};

package/dist/http/index.js

@@ -0,0 +1,155 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { Readable } from "node:stream";
+/** Left-most token of a (possibly comma-joined or repeated) header value, trimmed. */
+function firstHop(v) {
+    const s = Array.isArray(v) ? v[0] : v;
+    return (s ?? "").split(",")[0]?.trim() ?? "";
+}
+/**
+ * The real external client IP behind a CDN → own edge → ingress → pod chain.
+ *
+ * Trust order (first non-empty wins) and why it matters: with `trustProxy` enabled the app trusts every
+ * hop, so `X-Forwarded-For` is client-controllable end to end — a caller can prepend a forged left-most
+ * entry that the CDN only appends to. `CF-Connecting-IP` (set by Cloudflare) and `X-Real-IP` (set by your
+ * own edge) are OVERWRITTEN by that infrastructure and therefore cannot be spoofed from outside, so they
+ * win; XFF is the last resort. Empty string when nothing usable is present (local dev, health checks).
+ *
+ * Pass a getter that reads by lower-case name: works for Fastify `req.headers` and for WHATWG
+ * `Headers.get` alike.
+ */
+export function clientIp(get) {
+    return firstHop(get("cf-connecting-ip")) || firstHop(get("x-real-ip")) || firstHop(get("x-forwarded-for")) || "";
+}
+/**
+ * Fastify `onRequest`: rewrite the raw `x-forwarded-for` so that Fastify's own `req.ip` — and everything
+ * built on it (framework access logs, rate-limit keys, stored remote addresses) — resolves to the real
+ * client instead of a spoofable left-most entry. Only rewrites when a trustworthy infrastructure header
+ * is present, so local development and non-CDN hosts keep default behaviour.
+ *
+ * MUST be registered FIRST: Fastify runs `onRequest` hooks in registration order, and everything reading
+ * `req.ip` afterwards depends on this.
+ */
+export function clientIpNormalizeHook() {
+    return async (req, _reply) => {
+        const h = req.raw.headers;
+        const trusted = firstHop(h["cf-connecting-ip"]) || firstHop(h["x-real-ip"]);
+        if (trusted)
+            h["x-forwarded-for"] = trusted;
+    };
+}
+const storage = new AsyncLocalStorage();
+/**
+ * `req_<hex>` — one shape of id across every process, safe to hand to a caller for a support request.
+ */
+export function newRequestId() {
+    return `req_${randomUUID().replace(/-/g, "")}`;
+}
+export function currentRequestContext() {
+    return storage.getStore();
+}
+export function currentRequestId() {
+    return storage.getStore()?.requestId;
+}
+/** Run work inside a context. Everything asynchronous started inside sees the same id. */
+export function runWithRequestContext(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+// An inbound id is only accepted if it LOOKS like an id: the value ends up in log lines and in a response
+// header, so an arbitrary caller-supplied string is log injection plus noise in the log store.
+const ID_RE = /^[\w.-]{1,80}$/;
+export function acceptRequestId(inbound) {
+    return inbound && ID_RE.test(inbound) ? inbound : newRequestId();
+}
+/**
+ * Fastify `onRequest`: open a context for the whole request and echo the id back in a header.
+ *
+ * Why AsyncLocalStorage and not a parameter: threading an id through every layer (RPC → service →
+ * service → repository) would mean changing every signature for a field only the logs care about. The log
+ * transport reads the context itself, so calling code stays unaware.
+ *
+ * Register AFTER `clientIpNormalizeHook` and BEFORE everything else: this hook continues the chain inside
+ * `storage.run`, so only hooks registered later see the context.
+ */
+export function requestContextHook(options = {}) {
+    const headerName = options.headerName ?? "X-Request-Id";
+    const lower = headerName.toLowerCase();
+    return (req, reply, done) => {
+        const raw = req.headers[lower];
+        const inbound = Array.isArray(raw) ? raw[0] : raw;
+        const requestId = acceptRequestId(inbound?.trim() ? inbound.trim() : undefined);
+        reply.header(headerName, requestId);
+        runWithRequestContext({ requestId, source: "http" }, done);
+    };
+}
+/** Body over the limit. `statusCode` is the Fastify idiom — the default error handler renders 413. */
+export class PayloadTooLargeError extends Error {
+    constructor(limit) {
+        super(`Request body exceeds the ${limit}-byte limit`);
+        this.statusCode = 413;
+        this.name = "PayloadTooLargeError";
+    }
+}
+/**
+ * Drain a stream into one Buffer, ABORTING as soon as the limit is passed: the offending chunk is not
+ * kept and no further chunks are pulled, so an oversized body never sits in the heap in full.
+ */
+export async function bufferCapped(payload, limit) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of payload) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > limit)
+            throw new PayloadTooLargeError(limit);
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Capture the EXACT request bytes on `req.rawBody` and return a fresh equivalent stream so the normal
+ * parser still fills `req.body` for the handler.
+ *
+ * Needed wherever a signature is computed over the raw bytes: a re-serialized object produces different
+ * bytes (key order, spacing, number formatting) and the verification fails for a legitimate caller.
+ */
+export async function stashRawBodyStream(req, payload, limit) {
+    const raw = await bufferCapped(payload, limit);
+    req.rawBody = raw;
+    const stream = new Readable();
+    stream.push(raw);
+    stream.push(null);
+    stream.receivedEncodedLength = raw.length;
+    return stream;
+}
+/**
+ * Fastify `onRequest`: fixed-window counter per (bucket, IP), kept in the shared store so the limit is
+ * global across replicas rather than per-process.
+ *
+ * FAIL-OPEN by design: a store outage must not become an outage of the product. A limiter that blocks
+ * everything when Redis blinks is worse than one that briefly stops limiting.
+ *
+ * Requires `clientIpNormalizeHook` to be registered earlier, otherwise the key is built from a
+ * spoofable address and the limit can be evaded by forging a header.
+ */
+export function rateLimitHook(options) {
+    return async (req, reply) => {
+        try {
+            const bucket = await options.bucketFor(req);
+            if (!bucket)
+                return;
+            const win = await options.windowSec();
+            const key = `rl:${bucket.name}:${req.ip}`;
+            const store = options.store();
+            const n = await store.incr(key);
+            if (n === 1)
+                await store.expire(key, win);
+            if (n > bucket.limit) {
+                await reply.code(429).header("retry-after", String(win)).send({ error: "rate_limited" });
+            }
+        }
+        catch {
+            // fail-open
+        }
+    };
+}

package/dist/log/index.d.ts

@@ -0,0 +1,28 @@
+import type { LogEntry, LogLevel, LogTransport } from "@smounters/core/core";
+export type { LogEntry, LogLevel, LogTransport };
+export interface LogOptions {
+    /** Deployment environment; also decides the format — `local` renders colour, everything else JSON. */
+    env?: string;
+    /** Which process this is. Surface the same name as the container/deployment so queries can group by it. */
+    service?: string;
+    /** Minimum level that reaches stdout. */
+    minLevel?: LogLevel;
+    /** Render colour even outside local (rarely wanted; a collector reads escape codes as noise). */
+    colorize?: boolean;
+}
+/**
+ * Transports for `app.configureLogger()` — covers the injected logger service, the framework access log
+ * and every structured call across the application.
+ */
+export declare function createTransports(options?: LogOptions): LogTransport[];
+export interface StandaloneLogger {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+}
+/**
+ * Emitter for code that runs OUTSIDE dependency injection — entrypoint startup and fatal lines, a script.
+ * Same format as the transports, so both kinds of line sit in one stream.
+ */
+export declare function createLogger(options?: LogOptions): StandaloneLogger;

package/dist/log/index.js

@@ -0,0 +1,152 @@
+import { currentRequestContext } from "../http/index.js";
+// Structured logging.
+//
+// Outside local development every entry is ONE single-line JSON object
+//   {"ts","level","env","service","type", ...fields}
+// so a log collector ingests container stdout and exposes the fields without regex parsing. Locally a
+// coloured human line is rendered instead. Container stdout IS the log source — nothing is shipped over
+// HTTP from here, and nothing is filtered beyond the minimum level.
+const LEVEL_PRIORITY = {
+    silly: 0,
+    trace: 1,
+    debug: 2,
+    info: 3,
+    warn: 4,
+    error: 5,
+    fatal: 6,
+};
+function resolve(options) {
+    const env = (options.env ?? process.env.ENVIRONMENT ?? "local").toLowerCase();
+    return {
+        env,
+        service: (options.service ?? process.env.APP_MODE ?? "api").toLowerCase(),
+        min: LEVEL_PRIORITY[options.minLevel ?? (process.env.LOG_LEVEL ?? "info").toLowerCase()] ?? 3,
+        colorize: options.colorize ?? env === "local",
+    };
+}
+const PALETTE = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    green: "\x1b[32m",
+    cyan: "\x1b[36m",
+    gray: "\x1b[90m",
+    white: "\x1b[37m",
+};
+const NO_COLOR = { reset: "", dim: "", red: "", yellow: "", green: "", cyan: "", gray: "", white: "" };
+const LEVEL_COLOR = {
+    debug: "gray",
+    info: "green",
+    warn: "yellow",
+    error: "red",
+    fatal: "red",
+};
+function toJson(cfg, ts, level, type, rest) {
+    return JSON.stringify({ ts, level, env: cfg.env, service: cfg.service, type, ...rest });
+}
+function toColorized(cfg, ts, level, type, rest) {
+    const C = cfg.colorize ? PALETTE : NO_COLOR;
+    const lc = C[LEVEL_COLOR[level] ?? "white"];
+    const parts = [];
+    for (const [k, v] of Object.entries(rest)) {
+        if (v === undefined || v === null)
+            continue;
+        if (k === "message") {
+            parts.push(String(v));
+            continue;
+        }
+        parts.push(`${C.dim}${k}=${C.reset}${typeof v === "object" ? JSON.stringify(v) : String(v)}`);
+    }
+    return `${C.dim}${ts}${C.reset} ${lc}${level.toUpperCase().padEnd(5)}${C.reset} ${C.cyan}${type.padEnd(7)}${C.reset} ${parts.join(" ")}`;
+}
+// The chain id is mixed into EVERY line automatically — calling code never passes it. An explicit field
+// in the entry itself (rare) is not overwritten.
+function withRequestFields(rest) {
+    const ctx = currentRequestContext();
+    if (!ctx || rest.reqId !== undefined)
+        return rest;
+    return { ...rest, reqId: ctx.requestId, src: ctx.source };
+}
+function emit(level, line) {
+    if (level === "error" || level === "fatal")
+        console.error(line);
+    else if (level === "warn")
+        console.warn(line);
+    else
+        console.log(line);
+}
+function serialize(a) {
+    if (a instanceof Error)
+        return `${a.name}: ${a.message}`;
+    if (typeof a === "object" && a !== null) {
+        try {
+            return JSON.stringify(a);
+        }
+        catch {
+            return String(a);
+        }
+    }
+    return String(a);
+}
+// Split args into a log `type` plus a flat field bag. A structured first argument ({type, ...}) is
+// hoisted to top-level JSON fields (so a log query can filter on them); plain args collapse into
+// `message`.
+function shape(defaultType, args) {
+    const first = args[0];
+    const structured = typeof first === "object" &&
+        first !== null &&
+        !(first instanceof Error) &&
+        "type" in first;
+    if (structured) {
+        const obj = { ...first };
+        const type = String(obj.type);
+        delete obj.type;
+        if (args.length > 1)
+            obj.extra = args.slice(1).map(serialize).join(" ");
+        return { type, rest: obj };
+    }
+    return { type: defaultType, rest: { message: args.map(serialize).join(" ") } };
+}
+function format(cfg, ts, level, type, rest) {
+    const withCtx = withRequestFields(rest);
+    return cfg.colorize ? toColorized(cfg, ts, level, type, withCtx) : toJson(cfg, ts, level, type, withCtx);
+}
+/**
+ * Transports for `app.configureLogger()` — covers the injected logger service, the framework access log
+ * and every structured call across the application.
+ */
+export function createTransports(options = {}) {
+    const cfg = resolve(options);
+    return [
+        {
+            log(entry) {
+                if ((LEVEL_PRIORITY[entry.level] ?? 0) < cfg.min)
+                    return;
+                const ts = entry.timestamp.toISOString().slice(0, 23);
+                const { type, rest } = shape("app", entry.message ? [entry.message, ...entry.args] : entry.args);
+                emit(entry.level, format(cfg, ts, entry.level, type, rest));
+            },
+        },
+    ];
+}
+/**
+ * Emitter for code that runs OUTSIDE dependency injection — entrypoint startup and fatal lines, a script.
+ * Same format as the transports, so both kinds of line sit in one stream.
+ */
+export function createLogger(options = {}) {
+    const cfg = resolve(options);
+    const log = (level, ...args) => {
+        if ((LEVEL_PRIORITY[level] ?? 0) < cfg.min)
+            return;
+        const ts = new Date().toISOString().slice(0, 23);
+        const { type, rest } = shape("app", args);
+        emit(level, format(cfg, ts, level, type, rest));
+    };
+    return {
+        info: (...args) => log("info", ...args),
+        warn: (...args) => log("warn", ...args),
+        error: (...args) => log("error", ...args),
+        debug: (...args) => log("debug", ...args),
+    };
+}