@smounters/kit 2.23.0 → 2.25.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 2.25.0 - 2026-09-11
+
+### Added
+- `kit/text` — подстановка `{{ path.to.value }}` с экранированием ПО ЗНАЧЕНИЮ под получателя
+  (`html`, `url`, `markdownv2`), экранирование для SQL `LIKE` (поиск по «100%» не должен находить
+  всё подряд) и наивный разбор ФИО. Подпуть был в плане пакета с самого начала и закрывает третью
+  переписанную копию этих же функций.
+  Словаря предметной области здесь нет: канал отправки в режим экранирования переводит потребитель.
+
+## 2.24.0 - 2026-09-11
+
+### Added
+- `kit/money`: `createMoney({ scale, pad })` — арифметика, привязанная к масштабу хранения, который
+  выбирает ПРИЛОЖЕНИЕ. Прежние `MONEY_SCALE`/`toMoneyAmount`/`applyDelta` остались как масштаб-4 по
+  умолчанию и ничего не меняют для тех, кто выбора не делал. Понадобилось потребителю, расширившему
+  денежные колонки до `numeric(40,20)`: на четырёх знаках срезалась точность токенов.
+  Добивки нулями у новой формы по умолчанию нет — при широком масштабе она отдаёт стену нулей, а
+  `"0.00000000000000000000" !== "0"` ломает сравнения ниже по течению.
+
+### Changed
+- `kit/money`: `Decimal.set` поднят с `precision: 50` до `80`. У самой decimal.js умолчание — 20
+  ЗНАЧАЩИХ цифр, и она молча округляет до них даже обычное сложение; на 18–20 знаках после запятой
+  это теряет хвост каждой суммы. Самая широкая колонка потребителя — 40 значащих цифр, и две такие
+  встречаются в одном умножении, поэтому запас взят двойной.
+
 ## 2.2.0 - 2026-07-30
 
 ### Added

package/README.md

@@ -19,6 +19,7 @@ npm i @smounters/kit @smounters/core
 | `kit/config` | zod-препроцессоры для разбора env | `zod` |
 | `kit/money` | decimal-арифметика, масштабы, округление, проверка сбалансированности проводки | — |
 | `kit/rpc` | `ProtoValidateInterceptor` — правила `buf.validate` из контракта, enforced транспортом | `@smounters/core`, `@connectrpc/connect`, `@bufbuild/*` |
+| `kit/text` | подстановка `{{ }}` с экранированием под получателя, экранирование для SQL `LIKE`, разбор ФИО | — |
 | `kit/util` | `ulid`, `redactSecrets` | — |
 
 ## Что здесь НЕ лежит и почему
@@ -104,6 +105,26 @@ quantizeToDecimals(due, 6, ROUND_UP); // сумма, достижимая у т
 знаками не переведёт значение с восемью, и «ожидаемая» сумма, скруглённая до масштаба книги, окажется
 неоплатной точно — а строгое сравнение назовёт это недоплатой, которой плательщик не мог избежать.
 
+### Свой масштаб хранения
+
+Функции выше привязаны к масштабу 4 — это фиат. Приложению, которое держит в той же книге токены,
+четырёх знаков мало, а масштаб — **политика**, поэтому его задаёт потребитель:
+
+```ts
+import { createMoney } from "@smounters/kit/money";
+
+const money = createMoney({ scale: 20 }); // numeric(40,20)
+
+money.toAmount("10.123456");              // "10.123456" — точность токена сохранена
+money.toAmount("0.123456789012345678901") // null — точнее, чем хранит колонка
+money.applyDelta("0", "100");             // "100", а не "100.00000000000000000000"
+money.quantize("10.126", ROUND_HALF_UP);  // "10.13" — округление, когда его ПОПРОСИЛИ
+```
+
+Добивки нулями по умолчанию нет намеренно: при широком масштабе она возвращала бы стену нулей, а
+`"0.00000000000000000000" !== "0"` ломает любое наивное сравнение ниже по течению. Нужна старая
+форма — `createMoney({ scale: 4, pad: true })`.
+
 ## Защита от SSRF
 
 ```ts

package/dist/money/index.d.ts

@@ -33,6 +33,32 @@ export declare function quantizeToDecimals(amount: string, decimals: number, rou
 export declare function sumAmounts(amounts: readonly string[]): Decimal;
 /** Apply a signed delta to a balance, at money scale. */
 export declare function applyDelta(balance: string, amount: string): string;
+export interface MoneyOptions {
+    /** Decimal places the storage column keeps. Anything more precise is rejected, never rounded away. */
+    scale: number;
+    /**
+     * Pad results to `scale` (`"100"` → `"100.0000"`). Off by default: a wide column (scale 20) would
+     * otherwise hand every caller a string of trailing zeros, and `"0.00000000000000000000" !== "0"`
+     * breaks every naive comparison downstream.
+     */
+    pad?: boolean;
+}
+export interface MoneyOps {
+    readonly scale: number;
+    readonly zero: string;
+    fits(amount: string): boolean;
+    toAmount(amount: string): string | null;
+    applyDelta(balance: string, amount: string): string;
+    quantize(amount: string, rounding?: Decimal.Rounding): string;
+}
+/**
+ * Money arithmetic bound to one storage scale.
+ *
+ * The scale is POLICY — a fiat-only ledger settles at 4 decimals, one that also holds tokens needs 18
+ * or more — so it belongs to the application, not to this package. The module-level `MONEY_SCALE`
+ * helpers remain as the scale-4 default for callers that never had to choose.
+ */
+export declare function createMoney({ scale, pad }: MoneyOptions): MoneyOps;
 export interface PostingLine {
     /** Signed decimal string: debit > 0, credit < 0. */
     amount: string;

package/dist/money/index.js

@@ -4,8 +4,12 @@ import { Decimal } from "decimal.js";
 // Nothing here may use a JS number: a double cannot represent 0.1 exactly, and a ledger that cannot
 // represent its own amounts stops balancing within a day. Amounts travel as decimal STRINGS end to end
 // (numeric in the database, string on the wire) and are only turned into Decimal for the arithmetic.
-// Precision must exceed the widest intermediate we produce (a 20-digit amount divided by an 18-dp rate).
-Decimal.set({ precision: 50, toExpNeg: -50, toExpPos: 50 });
+// Precision must exceed the widest intermediate we produce. The widest column a consumer stores is
+// numeric(40,20) — 40 significant digits — and two of those can meet in one multiplication, so the
+// library must carry twice that before it starts rounding. decimal.js defaults to 20 SIGNIFICANT
+// digits and rounds even a plain addition down to them, silently: at 18 decimal places that loses
+// the tail of every sum. Importing this module is what fixes it for the whole process.
+Decimal.set({ precision: 80, toExpNeg: -80, toExpPos: 80 });
 /** Money scale: `numeric(20,4)`. Four decimal places cover fiat and keep every posting exact. */
 export const MONEY_SCALE = 4;
 /** Ratio scale: `numeric(20,8)` — returns, coverage, shares of a fee. */
@@ -53,6 +57,30 @@ export function sumAmounts(amounts) {
 export function applyDelta(balance, amount) {
     return toDecimal(balance).plus(toDecimal(amount)).toFixed(MONEY_SCALE);
 }
+/**
+ * Money arithmetic bound to one storage scale.
+ *
+ * The scale is POLICY — a fiat-only ledger settles at 4 decimals, one that also holds tokens needs 18
+ * or more — so it belongs to the application, not to this package. The module-level `MONEY_SCALE`
+ * helpers remain as the scale-4 default for callers that never had to choose.
+ */
+export function createMoney({ scale, pad = false }) {
+    if (!Number.isInteger(scale) || scale < 0 || scale > 40) {
+        throw new RangeError(`Money scale must be an integer in 0..40, got ${scale}`);
+    }
+    const render = (d) => (pad ? d.toFixed(scale) : d.toFixed());
+    return {
+        scale,
+        zero: render(new Decimal(0)),
+        fits: (amount) => toDecimal(amount).decimalPlaces() <= scale,
+        toAmount: (amount) => {
+            const d = toDecimal(amount);
+            return d.decimalPlaces() > scale ? null : render(d);
+        },
+        applyDelta: (balance, amount) => render(toDecimal(balance).plus(toDecimal(amount))),
+        quantize: (amount, rounding = ROUND_HALF_UP) => toDecimal(amount).toFixed(scale, rounding),
+    };
+}
 /**
  * Is this a valid double-entry posting? At least two lines, no zero-amount line, and the signed amounts
  * sum to EXACTLY zero. This is the invariant that makes a ledger auditable, so it is checked in code

package/dist/text/index.d.ts

@@ -0,0 +1,32 @@
+/** Where the rendered value is about to land. Picking the wrong one is an injection, not a typo. */
+export type EscapeMode = "none" | "url" | "html" | "markdownv2" | "plain";
+/**
+ * Escape a value for a SQL `LIKE` pattern: a user searching for "100%" must not match everything.
+ *
+ * The backslash goes first — escaping it after `%`/`_` would double-escape the escapes. Postgres needs
+ * no `ESCAPE` clause with this, since backslash is the default.
+ */
+export declare function escapeLike(value: string): string;
+export declare function escapeHtml(str: string): string;
+/** Telegram MarkdownV2 reserves this whole set; one unescaped character fails the whole send. */
+export declare function escapeMarkdownV2(str: string): string;
+export declare function escapeValue(str: string, mode: EscapeMode): string;
+/** Read `a.b.c` out of a plain object, returning undefined instead of throwing on a missing branch. */
+export declare function resolvePath(context: Record<string, unknown>, path: string): unknown;
+/**
+ * Substitute `{{ path.to.value }}` placeholders, escaping each substituted value for the target.
+ *
+ * Escaping is per-VALUE, never over the finished string: the template itself is authored by us and may
+ * legitimately contain markup, while the values come from data and may contain anything. A missing key
+ * renders as an empty string rather than leaving the placeholder visible to a customer.
+ */
+export declare function renderTemplate(template: string, context: Record<string, unknown>, escape?: boolean | EscapeMode): string;
+/**
+ * Split a full name into first + rest. Deliberately naive: one word is a first name, everything after
+ * the first space is the last name. Anything smarter guesses wrong on the half of the world that writes
+ * the family name first.
+ */
+export declare function splitPersonName(full: string | undefined): {
+    firstName?: string;
+    lastName?: string;
+};

package/dist/text/index.js

@@ -0,0 +1,73 @@
+// Text mechanics that every service rewrites: placeholder substitution with the right escaping for the
+// channel it is going out on, escaping for a SQL LIKE pattern, splitting a person's full name.
+//
+// No product vocabulary lives here — no channel enum, no header names, no field names. The caller says
+// which escape mode it needs; the mapping from its own channel enum to a mode is the caller's policy.
+/**
+ * Escape a value for a SQL `LIKE` pattern: a user searching for "100%" must not match everything.
+ *
+ * The backslash goes first — escaping it after `%`/`_` would double-escape the escapes. Postgres needs
+ * no `ESCAPE` clause with this, since backslash is the default.
+ */
+export function escapeLike(value) {
+    return value.replace(/\\/g, "\\\\").replace(/[%_]/g, "\\$&");
+}
+export function escapeHtml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+/** Telegram MarkdownV2 reserves this whole set; one unescaped character fails the whole send. */
+export function escapeMarkdownV2(str) {
+    return str.replace(/[\\_*[\]()~`>#+\-=|{}.!]/g, (m) => `\\${m}`);
+}
+export function escapeValue(str, mode) {
+    switch (mode) {
+        case "url":
+            return encodeURIComponent(str);
+        case "html":
+            return escapeHtml(str);
+        case "markdownv2":
+            return escapeMarkdownV2(str);
+        default:
+            return str;
+    }
+}
+/** Read `a.b.c` out of a plain object, returning undefined instead of throwing on a missing branch. */
+export function resolvePath(context, path) {
+    let cur = context;
+    for (const key of path.split(".")) {
+        if (cur == null || typeof cur !== "object")
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+/**
+ * Substitute `{{ path.to.value }}` placeholders, escaping each substituted value for the target.
+ *
+ * Escaping is per-VALUE, never over the finished string: the template itself is authored by us and may
+ * legitimately contain markup, while the values come from data and may contain anything. A missing key
+ * renders as an empty string rather than leaving the placeholder visible to a customer.
+ */
+export function renderTemplate(template, context, escape = false) {
+    const mode = escape === true ? "url" : escape === false ? "none" : escape;
+    return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_match, path) => {
+        const value = resolvePath(context, path);
+        return escapeValue(value == null ? "" : String(value), mode);
+    });
+}
+/**
+ * Split a full name into first + rest. Deliberately naive: one word is a first name, everything after
+ * the first space is the last name. Anything smarter guesses wrong on the half of the world that writes
+ * the family name first.
+ */
+export function splitPersonName(full) {
+    const words = (full ?? "").trim().split(/\s+/).filter(Boolean);
+    if (!words.length)
+        return {};
+    return { firstName: words[0], lastName: words.slice(1).join(" ") || undefined };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smounters/kit",
-  "version": "2.23.0",
+  "version": "2.25.0",
   "description": "Batteries for Imperium services: structured logging, Redis module with a distributed lock, SSRF-safe fetch, decimal money, request context, env schemas",
   "keywords": [
     "imperium",
@@ -45,6 +45,10 @@
     "./util": {
       "types": "./dist/util/index.d.ts",
       "import": "./dist/util/index.js"
+    },
+    "./text": {
+      "types": "./dist/text/index.d.ts",
+      "import": "./dist/text/index.js"
     }
   },
   "files": [