@alizadefaig/pos-server 1.2.26 → 1.2.27

package/app/core/services/TelegramService.js

@@ -0,0 +1,162 @@
+const telegram = require('../support/telegram');
+const {round, toFloat} = require('../support/num');
+const {isUuid} = require('../support/ids');
+const {trans: transField} = require('../support/lang');
+
+/**
+ * Уведомления о событиях чека в Telegram команды — порт OrderService::sendEventTelegram.
+ *
+ * Работает только в облачном контуре (`CORE_MODE=cloud` на Postgres): там ядро заменяет
+ * Laravel, и без этого сервиса уведомления о чеках, которые обслужил Node, пропали бы. На кассе
+ * это no-op — события касса досылает наверх, и облако шлёт их само при приёме (SyncService).
+ *
+ * Текст собирается сразу, тем же подключением к БД (внутри транзакции мутации видно её
+ * состояние — как у PHP, где отправка шла прямо в saveEvents). Отправка — в очередь чата
+ * (`support/telegram.js`), запрос кассы её не ждёт.
+ */
+const moneyCast = (value) => (value === null || value === undefined ? null : round(toFloat(value), 3));
+
+/** round($x, 2) по значению, которое в PHP могло быть null (null → 0). */
+const round2 = (value) => round(toFloat(value), 2);
+
+class TelegramService {
+    constructor({db, context}) {
+        this.db = db;
+        this.context = context;
+    }
+
+    /** Лениво: ядро (index.js) само требует сервисы заказа, прямой require замкнул бы цикл. */
+    active() {
+        return require('../index').mode() === 'cloud' && this.db.dialect === 'pgsql';
+    }
+
+    /**
+     * Уведомления по пачке событий saveEvents. Никогда не бросает: уведомление не должно
+     * срывать мутацию чека (в PHP каждое событие шло в своём try/catch).
+     */
+    async notifyEvents(events) {
+        if (!this.active() || !Array.isArray(events) || !events.length) {
+            return;
+        }
+        let settings;
+        try {
+            settings = this.context.settings();
+        } catch (e) {
+            return;
+        }
+        const chatId = telegram.chatIdOf(settings);
+        if (!chatId) {
+            return;
+        }
+        const locale = this.context.locale();
+        for (const event of events) {
+            try {
+                const text = await TelegramService.eventText(this.db, event, settings, this.context.employeeId, locale);
+                if (text !== null) {
+                    telegram.send(chatId, text);
+                }
+            } catch (e) {
+                console.warn(`[telegram] событие ${event && event.event}: текст не собран — ${e.message}`);
+            }
+        }
+    }
+
+    /**
+     * Текст уведомления или null (события нет в lang/az/telegram.php либо это группа ключей).
+     * Статический: тот же текст нужен приёму чеков с кассы, где сотрудник — из события.
+     */
+    static async eventText(db, event, settings, employeeId, locale) {
+        const messageKey = `telegram.${String((event && event.event) || '').replace(/:/g, '.')}`;
+        if (!telegram.has(messageKey, locale)) {
+            return null;
+        }
+
+        const owner = employeeId && isUuid(employeeId)
+            ? await db.value(
+                `SELECT u.name FROM team_users tu
+                   JOIN users u ON u.id = tu.user_id AND u.deleted_at IS NULL
+                  WHERE tu.id = ? AND tu.deleted_at IS NULL`,
+                [employeeId]
+            )
+            : null;
+
+        const orderId = event.order_id || null;
+        // withTrashed чек, связи зала и стола — без удалённых (как with(['hall', 'table'])).
+        const order = orderId && isUuid(orderId)
+            ? await db.get(
+                `SELECT o.subtotal, o.discount_amount, o.service_charge_amount, o.discount,
+                        o.discount_type, o.total, CAST(o.service_charge AS TEXT) AS service_charge_text,
+                        h.name AS hall_name, t.label AS table_label
+                   FROM orders o
+                   LEFT JOIN halls h ON h.id = o.hall_id AND h.deleted_at IS NULL
+                   LEFT JOIN tables t ON t.id = o.table_id AND t.deleted_at IS NULL
+                  WHERE o.id = ?`,
+                [orderId]
+            )
+            : null;
+
+        const settingsMode = settings && settings.terminal_settings
+            ? settings.terminal_settings.service_charge_calculate_mode
+            : null;
+        const mode = settingsMode || 'after_discount';
+        const isServiceCharge = messageKey.includes('service_charge');
+
+        let productName = null;
+        let quantity = 0;
+        let amount;
+        if (event.product_id !== undefined && event.product_id !== null) {
+            const raw = isUuid(event.product_id)
+                ? await db.value('SELECT full_name FROM products WHERE id = ?', [event.product_id])
+                : null;
+            productName = raw === null || raw === undefined
+                ? null
+                : transField(raw, locale, process.env.APP_FALLBACK_LOCALE || 'en');
+            quantity = event.quantity !== undefined && event.quantity !== null ? event.quantity : 0;
+            let price = event.price !== undefined ? event.price : null;
+            if (price === null) {
+                const stored = orderId && isUuid(orderId) && isUuid(event.product_id)
+                    ? await db.value(
+                        `SELECT price FROM order_products
+                          WHERE order_id = ? AND product_id = ? AND deleted_at IS NULL LIMIT 1`,
+                        [orderId, event.product_id]
+                    )
+                    : null;
+                price = moneyCast(stored);
+            }
+            amount = toFloat(quantity) * toFloat(price === null ? 0 : price);
+        } else if (order) {
+            amount = moneyCast(isServiceCharge ? order.service_charge_amount : order.discount_amount);
+        } else {
+            amount = null;
+        }
+
+        const discount = order ? moneyCast(order.discount) : null;
+        const percent = isServiceCharge
+            ? (order ? order.service_charge_text : null)
+            : discount;
+        const serviceCharge = order ? order.service_charge_text : null;
+        const tableLabel = order ? order.table_label : null;
+
+        const receipt = telegram.trans(`telegram.receipt.${mode}`, {
+            subtotal: round2(order && moneyCast(order.subtotal)),
+            discount: telegram.phpString(round2(order && moneyCast(order.discount_amount)))
+                + ((order ? order.discount_type : null) !== 'amount' ? ` (${telegram.phpString(discount)}%)` : ''),
+            service: `(${telegram.phpString(serviceCharge)}%) ${telegram.phpString(round2(order && moneyCast(order.service_charge_amount)))}`,
+            total: round2(order && moneyCast(order.total)),
+        }, locale);
+
+        return telegram.trans(messageKey, {
+            hall: order ? order.hall_name : null,
+            table: tableLabel,
+            owner,
+            product: productName,
+            quantity,
+            amount,
+            percent,
+            locative: telegram.azLocativeSuffix(tableLabel === null || tableLabel === undefined ? '' : tableLabel),
+            receipt: receipt === null ? '' : receipt,
+        }, locale);
+    }
+}
+
+module.exports = TelegramService;

package/app/core/support/db.js

@@ -0,0 +1,48 @@
+/**
+ * Диалектные мелочи записи.
+ *
+ * SQLite хранит флаги как INTEGER 0/1, Postgres — как настоящий BOOLEAN и отказывается
+ * принимать 0/1 («column is of type boolean but expression is of type integer»). Ядро
+ * пишет флаги как попало (0/1/true/false), поэтому приводим их к boolean в одном месте —
+ * на границе записи. Обратно в 0/1 для SQLite приводит driver.js.
+ *
+ * Чтение уже нормализовано: модели прогоняют флаги через toBool().
+ */
+const BOOLEAN_COLUMNS = new Set([
+    // orders
+    'payed_by_third_party_application', 'is_closed_without_payment', 'should_send_to_kitchen',
+    // order_products
+    'is_gift', 'is_stopped', 'is_fixed',
+    // products (создание «свободного» товара в addExtra)
+    'is_giftable', 'is_available', 'is_active', 'is_hidden', 'is_weight_item', 'is_not_discount',
+    'is_with_modification',
+    // kds_tickets
+    'tracked',
+    // printers / printer_workshop / product_workshops
+    'bill', 'bell', 'cashdraw', 'print_ticket',
+]);
+
+const toDbBool = (value) => {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        return value === '1' || value.toLowerCase() === 'true';
+    }
+    return Boolean(Number(value) || value === true);
+};
+
+/** Приводит значение к типу колонки, если та булева; иначе отдаёт как есть. */
+const castColumn = (column, value) => (BOOLEAN_COLUMNS.has(column) ? toDbBool(value) : value);
+
+/** Приводит булевы поля во всём payload перед insert/update. */
+const castRow = (payload) => {
+    for (const column of Object.keys(payload)) {
+        if (BOOLEAN_COLUMNS.has(column)) {
+            payload[column] = toDbBool(payload[column]);
+        }
+    }
+    return payload;
+};
+
+module.exports = {BOOLEAN_COLUMNS, toDbBool, castColumn, castRow};

package/app/core/support/ids.js

@@ -0,0 +1,9 @@
+const {v7: uuidv7, validate: uuidValidate} = require('uuid');
+
+// UUID v7 — те же идентификаторы, что генерирует Laravel (HasUuids). Монотонность по времени
+// даёт заодно естественный порядок вставки, на который опирается сортировка позиций чека.
+const uuid = () => uuidv7();
+
+const isUuid = (value) => typeof value === 'string' && uuidValidate(value);
+
+module.exports = {uuid, isUuid};

package/app/core/support/imageData.js

@@ -0,0 +1,135 @@
+const axios = require('axios');
+const {diskUrl} = require('./images');
+const {isUuid} = require('./ids');
+const {toInt} = require('./num');
+
+/**
+ * Картинка из `images` как data URI — порт ImageService::toBase64 для облачного контура
+ * (логотип на счёте). Laravel читает файл из своего Storage, Node берёт тот же файл по публичному
+ * адресу диска картинки (`images.disk`, CDN для do_spaces).
+ *
+ * Отличие от PHP: Laravel читает путь с диска ПО УМОЛЧАНИЮ (`Storage::get($path)`), а не с диска
+ * картинки. При `FILESYSTEM_DISK=public` логотип с do_spaces он не находит и отдаёт пустой
+ * `data:;base64,`. Здесь — диск самой картинки.
+ *
+ * Кэш — в процессе, по id картинки: новый логотип — новая строка `images`, так что устаревшей
+ * копии не бывает, TTL нужен только чтобы память не держала логотипы ушедших команд. Провал
+ * запоминается ненадолго: счёт не должен ждать недоступный CDN на каждой печати.
+ *
+ * Env: TEAM_LOGO_TIMEOUT_MS (5000), TEAM_LOGO_CACHE_MS (3600000), TEAM_LOGO_MAX_BYTES (2 МБ).
+ */
+const FAILURE_TTL_MS = 60000;
+const MAX_ENTRIES = 500;
+
+const timeoutMs = () => toInt(process.env.TEAM_LOGO_TIMEOUT_MS, 0) || 5000;
+const cacheMs = () => toInt(process.env.TEAM_LOGO_CACHE_MS, 0) || 3600000;
+const maxBytes = () => toInt(process.env.TEAM_LOGO_MAX_BYTES, 0) || 2 * 1024 * 1024;
+
+const cache = new Map();
+
+/** Тип по сигнатуре файла — как finfo у локального диска Laravel. */
+const sniffMime = (buffer) => {
+    const head = buffer.subarray(0, 16);
+    if (head.length >= 8 && head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+        return 'image/png';
+    }
+    if (head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    const ascii = head.toString('latin1');
+    if (ascii.startsWith('GIF87a') || ascii.startsWith('GIF89a')) {
+        return 'image/gif';
+    }
+    if (ascii.startsWith('RIFF') && ascii.slice(8, 12) === 'WEBP') {
+        return 'image/webp';
+    }
+    if (ascii.startsWith('BM')) {
+        return 'image/bmp';
+    }
+    if (/^\s*(<\?xml|<svg)/i.test(buffer.subarray(0, 256).toString('utf8'))) {
+        return 'image/svg+xml';
+    }
+    return null;
+};
+
+/** Content-Type картинки из ответа (как mimeType у S3 — из метаданных объекта), иначе сигнатура. */
+const mimeOf = (contentType, buffer) => {
+    const declared = String(contentType || '').split(';')[0].trim().toLowerCase();
+    if (declared.startsWith('image/')) {
+        return declared;
+    }
+    return sniffMime(buffer);
+};
+
+const load = async (db, imageId) => {
+    const image = await db.get('SELECT disk, path FROM images WHERE id = ? AND deleted_at IS NULL', [imageId]);
+    if (!image) {
+        return null;
+    }
+    const url = diskUrl(image.disk, image.path);
+    if (!url || !/^https?:\/\//i.test(url)) {
+        console.warn(`[images] ${imageId}: у диска ${image.disk} нет публичного адреса — логотип пропущен`);
+        return null;
+    }
+    const response = await axios.get(url, {
+        responseType: 'arraybuffer',
+        timeout: timeoutMs(),
+        maxContentLength: maxBytes(),
+        maxRedirects: 3,
+        validateStatus: () => true,
+    });
+    if (response.status < 200 || response.status >= 300) {
+        console.warn(`[images] ${imageId}: HTTP ${response.status} — логотип пропущен`);
+        return null;
+    }
+    const buffer = Buffer.from(response.data);
+    const mime = buffer.length ? mimeOf(response.headers && response.headers['content-type'], buffer) : null;
+    if (!mime) {
+        // Пустой или не-картинка: PHP в таком случае отдал бы битый data URI, счёт — пустую рамку.
+        console.warn(`[images] ${imageId}: файл не похож на картинку — логотип пропущен`);
+        return null;
+    }
+    return `data:${mime};base64,${buffer.toString('base64')}`;
+};
+
+const prune = (now) => {
+    for (const [key, entry] of cache) {
+        if (entry.expires <= now) {
+            cache.delete(key);
+        }
+    }
+    while (cache.size > MAX_ENTRIES) {
+        cache.delete(cache.keys().next().value);
+    }
+};
+
+/**
+ * data URI картинки или null (нет картинки, нет публичного адреса, CDN не ответил). Никогда не
+ * бросает. Одновременные запросы одной картинки ждут одну загрузку.
+ */
+const imageDataUri = async (db, imageId) => {
+    if (!imageId || !isUuid(String(imageId))) {
+        return null;
+    }
+    const key = String(imageId);
+    const now = Date.now();
+    const hit = cache.get(key);
+    if (hit && hit.expires > now) {
+        return hit.promise;
+    }
+    const promise = load(db, key).catch((e) => {
+        console.warn(`[images] ${key}: не загружен — ${e && e.code ? `${e.code} ` : ''}${e && e.message}`);
+        return null;
+    });
+    cache.set(key, {promise, expires: now + cacheMs()});
+    const value = await promise;
+    if (value === null && cache.get(key)?.promise === promise) {
+        cache.set(key, {promise, expires: Date.now() + FAILURE_TTL_MS});
+    }
+    prune(Date.now());
+    return value;
+};
+
+const clearImageCache = () => cache.clear();
+
+module.exports = {imageDataUri, sniffMime, clearImageCache};

package/app/core/support/images.js

@@ -0,0 +1,92 @@
+/**
+ * URL картинки по id из `images` — порт ImageCast + ImageService::getUrl
+ * (`Storage::disk($image->disk)->url($image->path)`).
+ *
+ * Адреса дисков — как в cafepos-admin/config/filesystems.php, те же переменные окружения.
+ * Нестандартный диск можно описать в IMAGE_DISK_URLS (JSON `{"disk": "https://base"}`).
+ *
+ * Выборка пакетная: init отдаёт сотни товаров, по запросу на картинку — это сотни запросов.
+ */
+const GSTATIC = 'https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRlGIgmMH0w19G8Lz6KizIhfg1SMZAAJvkxSB9E5BYT9j7hPrardmF4lINneTRdokKNVBw&usqp=CAU';
+
+const CHUNK = 500;
+
+// Как принимает uuid-колонка Postgres (без проверки версии: у старых строк она любая).
+const UUID = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
+const isUuid = (value) => UUID.test(value);
+
+const join = (base, path) => `${String(base).replace(/\/+$/, '')}/${String(path).replace(/^\/+/, '')}`;
+
+let customDisks;
+const customDiskUrls = () => {
+    if (customDisks === undefined) {
+        customDisks = {};
+        try {
+            const parsed = JSON.parse(process.env.IMAGE_DISK_URLS || '{}');
+            if (parsed && typeof parsed === 'object') {
+                customDisks = parsed;
+            }
+        } catch (e) {
+            console.warn('[images] IMAGE_DISK_URLS is not valid JSON, ignored');
+        }
+    }
+    return customDisks;
+};
+
+const diskUrl = (disk, path) => {
+    if (path === null || path === undefined) {
+        return null;
+    }
+    const custom = customDiskUrls()[disk];
+    if (custom) {
+        return join(custom, path);
+    }
+    switch (disk) {
+        case 'do_spaces':
+            // root 'v2' — префикс пути внутри бакета.
+            return join(process.env.DO_SPACES_URL || 'https://cdn.cafepos.az', join('v2', path));
+        case 'public':
+            return join(`${process.env.APP_URL || ''}/storage`, path);
+        case 's3':
+            return join(process.env.AWS_URL || '', path);
+        default:
+            // Диск local без url: FilesystemAdapter::getLocalUrl → '/storage/<path>'.
+            return join('/storage', path);
+    }
+};
+
+/**
+ * Map<id, url|null> для набора id. Пустое значение и не-uuid (Postgres упал бы на uuid-колонке)
+ * в выборку не идут; не найденная или удалённая картинка → null, как Image::find.
+ */
+const imageUrls = async (db, values) => {
+    const ids = [...new Set(values.filter((value) => value && isUuid(String(value))).map(String))];
+    const urls = new Map();
+    for (let i = 0; i < ids.length; i += CHUNK) {
+        const chunk = ids.slice(i, i + CHUNK);
+        const rows = await db.all(
+            `SELECT id, disk, path FROM images WHERE id IN (${chunk.map(() => '?').join(', ')}) AND deleted_at IS NULL`,
+            chunk
+        );
+        for (const row of rows) {
+            urls.set(String(row.id), diskUrl(row.disk, row.path));
+        }
+    }
+    return urls;
+};
+
+/**
+ * Значение каста ImageCast: пустое — как есть, иначе URL или null.
+ * `urls` = null — таблицы images нет (снапшот кассы): значение колонки отдаётся как лежит.
+ */
+const castImage = (urls, value) => {
+    if (!value) {
+        return value === undefined ? null : value;
+    }
+    if (!urls) {
+        return value;
+    }
+    return urls.get(String(value)) ?? null;
+};
+
+module.exports = {GSTATIC, diskUrl, imageUrls, castImage};

package/app/core/support/lanHandoff.js

@@ -0,0 +1,105 @@
+const {now, toSql} = require('./time');
+const {iso8601} = require('./php');
+
+/**
+ * Порт App\Services\Platform\LanHandoffService (облачная часть LAN-перехода официанта):
+ * куда браузеру уйти по LAN, если пропадёт интернет. Флаги — те же, что у Laravel.
+ */
+const enabled = () => {
+    const value = String(process.env.LAN_HANDOFF_ENABLED || '').trim().toLowerCase();
+    // (bool) env(...): Laravel превращает 'false'/'(false)'/'null'/'empty' в false/null/'',
+    // остальные непустые строки кроме '0' истинны.
+    return !['', '0', 'false', '(false)', 'null', '(null)', 'empty', '(empty)'].includes(value);
+};
+
+const freshSeconds = () => Math.max(1, parseInt(process.env.LAN_HANDOFF_MASTER_FRESH_SECONDS, 10) || 600);
+
+const PRIVATE_URL = /^http:\/\/(\d{1,3}(?:\.\d{1,3}){3}):(\d{1,5})\/?$/;
+
+/**
+ * Только http://<приватный IPv4>:<порт> без пути: адрес уходит в браузер, и подменённый
+ * heartbeat не должен увести официанта на чужой сайт.
+ */
+const isPrivateUrl = (url) => {
+    const match = typeof url === 'string' ? PRIVATE_URL.exec(url) : null;
+    if (!match) {
+        return false;
+    }
+    const port = parseInt(match[2], 10);
+    if (port < 1 || port > 65535) {
+        return false;
+    }
+    const octets = match[1].split('.').map((octet) => parseInt(octet, 10));
+    if (octets.some((octet) => octet > 255)) {
+        return false;
+    }
+    const [a, b] = octets;
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+};
+
+const isObject = (value) => value !== null && typeof value === 'object';
+
+const parseJson = (value) => {
+    if (typeof value !== 'string') {
+        return value;
+    }
+    try {
+        return JSON.parse(value);
+    } catch (e) {
+        return null;
+    }
+};
+
+/** Блок lan из heartbeat кассы, если по нему можно уйти. */
+const lanOf = (terminal) => {
+    const status = parseJson(terminal.sync_status);
+    const lan = isObject(status) && isObject(status.lan) ? status.lan : null;
+    if (!lan || status.role !== 'master') {
+        return null;
+    }
+    const version = isObject(lan.front) ? lan.front.version : null;
+    if (typeof version !== 'string' || version === '') {
+        return null;
+    }
+    const urls = (isObject(lan.urls) ? Object.values(lan.urls) : [])
+        .filter((url) => typeof url === 'string' && isPrivateUrl(url));
+    if (!urls.length) {
+        return null;
+    }
+    return {
+        terminal_id: terminal.id,
+        urls: urls.slice(0, 4),
+        front_version: version,
+        seen_at: iso8601(terminal.sync_seen_at),
+    };
+};
+
+/** Назначенный мастер модели M главнее, иначе — самая свежая подходящая касса. */
+const masterFor = async (db, companyId) => {
+    if (!companyId) {
+        return null;
+    }
+    const fresh = toSql(new Date(now().getTime() - freshSeconds() * 1000));
+    const company = await db.get('SELECT pos_master_terminal_id FROM companies WHERE id = ?', [companyId]);
+    const assigned = company ? company.pos_master_terminal_id : null;
+    const candidates = await db.all(
+        `SELECT id, sync_status, sync_seen_at FROM terminals
+         WHERE company_id = ? AND sync_seen_at IS NOT NULL AND sync_seen_at >= ? AND deleted_at IS NULL
+         ORDER BY sync_seen_at DESC`,
+        [companyId, fresh]
+    );
+    let best = null;
+    for (const terminal of candidates) {
+        const lan = lanOf(terminal);
+        if (lan === null) {
+            continue;
+        }
+        if (assigned && String(terminal.id) === String(assigned)) {
+            return lan;
+        }
+        best = best || lan;
+    }
+    return best;
+};
+
+module.exports = {enabled, masterFor, isPrivateUrl, lanOf};

package/app/core/support/lang.js

@@ -0,0 +1,98 @@
+const FALLBACK_LOCALE = 'en';
+
+/**
+ * Переводимые поля (spatie/laravel-translatable) лежат в БД как JSON `{"az": "...", "ru": "..."}`.
+ * Достаём значение для локали команды; если её нет — fallback, если и его нет — первое непустое.
+ * Строка без JSON — это старое непереведённое значение, отдаём как есть.
+ */
+const translated = (value, locale = FALLBACK_LOCALE) => {
+    if (value === null || value === undefined) {
+        return null;
+    }
+
+    let map = value;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed.startsWith('{')) {
+            return value;
+        }
+        try {
+            map = JSON.parse(trimmed);
+        } catch (e) {
+            return value;
+        }
+    }
+
+    if (typeof map !== 'object' || map === null) {
+        return String(value);
+    }
+
+    if (map[locale]) {
+        return map[locale];
+    }
+    if (map[FALLBACK_LOCALE]) {
+        return map[FALLBACK_LOCALE];
+    }
+    const first = Object.values(map).find((item) => item !== null && item !== '');
+    return first === undefined ? null : first;
+};
+
+/**
+ * Строгий порт spatie/laravel-translatable v6 (`$model->name`, getAttributeValue) — для ответов,
+ * которые обязаны совпасть с Laravel поле в поле (app.init, справочники). В отличие от
+ * `translated`, здесь нет «первого непустого» и нет возврата сырой строки:
+ *   - NULL в БД → null;
+ *   - не JSON-объект (старое непереведённое значение) → '' (json_decode даёт не массив);
+ *   - пустые и null-переводы выкидываются, затем локаль → 'en' (app.fallback_locale) → ''.
+ */
+const translationsOf = (raw) => {
+    let map = raw;
+    if (typeof raw === 'string') {
+        try {
+            map = JSON.parse(raw);
+        } catch (e) {
+            map = null;
+        }
+    }
+    return map !== null && typeof map === 'object' ? map : {};
+};
+
+const trans = (raw, locale = FALLBACK_LOCALE, fallback = FALLBACK_LOCALE) => {
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    const map = translationsOf(raw);
+    const present = (key) => Object.prototype.hasOwnProperty.call(map, key) && map[key] !== null && map[key] !== '';
+    if (present(locale)) {
+        return map[locale];
+    }
+    if (present(fallback)) {
+        return map[fallback];
+    }
+    return '';
+};
+
+/**
+ * То же поле в `$model->toArray()` (App\Traits\HasTranslations): spatie кастует переводимое
+ * поле в array, и перевод берётся, только если json_decode дал массив. Невалидный JSON → null,
+ * JSON-скаляр ("123", "true") отдаётся как есть.
+ */
+const transArray = (raw, locale = FALLBACK_LOCALE) => {
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    let decoded = raw;
+    if (typeof raw === 'string') {
+        try {
+            decoded = JSON.parse(raw);
+        } catch (e) {
+            return null;
+        }
+    }
+    if (decoded !== null && typeof decoded === 'object') {
+        return trans(decoded, locale);
+    }
+    return decoded;
+};
+
+module.exports = {translated, trans, transArray, FALLBACK_LOCALE};