npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@processengine/nominal-beneficiaries-rules

v2.0.16

Published

Пакет правил проверок бенефициаров номинальных счетов для jsonspecs

Readme

nominal-beneficiaries-rules

Пакет правил проверки бенефициаров номинальных счетов для @jsonspecs/rules 4.0.1 и спецификации jsonspecs/spec 1.0.0-rc.7.

Последний опубликованный выпуск: 2.0.14. Рабочие изменения PAY-995 ещё не опубликованы. Версию и архив опубликованного выпуска не заменяем локальной сборкой.

Состав пакета

  • 13 экспортируемых сценариев для регистрации, обновления и отвязки бенефициара;
  • 547 исполняемых артефактов в полном замыкании exports рабочей сборки;
  • справочники и переиспользуемые условия;
  • семь доменных операторов с закрытыми схемами и эталонными тестами;
  • 196 исполняемых примеров с полным покрытием 245 кодов ошибок;
  • воспроизводимый snapshot.json формата fv2.

Быстрый старт

Требуется Node.js 20 или новее.

npm ci
npm test

Канонические команды проекта предоставляет jsonspecs-cli 4:

jsonspecs validate --fail-on-warning
jsonspecs test
jsonspecs build --fail-on-warning
jsonspecs sandbox

npm test последовательно запускает эти проверки, эталонные векторы операторов, собирает dist/ и проверяет согласованность готового пакета.

Экспортируемые сценарии

| pipelineId | Сценарий | | --- | --- | | entrypoints.fl_resident.full_validation | ФЛ-резидент | | entrypoints.fl_nonresident.full_validation | ФЛ-нерезидент | | entrypoints.ip_resident.full_validation | ИП-резидент | | entrypoints.ip_nonresident.full_validation | ИП-нерезидент | | entrypoints.ul_resident.full_validation | ЮЛ-резидент | | entrypoints.ul_nonresident.full_validation | ЮЛ-нерезидент | | entrypoints.beneficiary.unbind.type_supported | допустимость типа при отвязке | | entrypoints.beneficiary.unbind.field_validation | поля заявки на отвязку | | entrypoints.fl_resident.update_validation | частичное обновление ФЛ-резидента | | entrypoints.fl_nonresident.update_validation | частичное обновление ФЛ-нерезидента | | entrypoints.ip_resident.update_validation | частичное обновление ИП-резидента | | entrypoints.ul_resident.update_validation | частичное обновление ЮЛ-резидента | | entrypoints.ul_nonresident.update_validation | частичное обновление ЮЛ-нерезидента |

Все сценарии *.full_validation и *.update_validation требуют context.currentDate. Отсутствие даты возвращает структурированную ошибку бизнес-проверки уровня EXCEPTION с кодом CONTEXT.CURRENT_DATE.REQUIRED.

Сценарии *.update_validation проверяют только присланные на обновление поля. Для FL_NONRESIDENT адрес регистрации всегда считается российским: countryCode не требуется и не влияет на результат, fullAddress необязателен, а структурные поля российского адреса обязательны. Один countryCode не считается переданным адресом. Для FL_RESIDENT код страны при передаче адреса должен быть RU, а для IP_RESIDENT сохраняется прежнее значение в контракте. Полную строку российского адреса собирает процессор после нормализации. Для этих типов также проверяются оба варианта телефона: российский phone и международный foreignPhone. Для UL_NONRESIDENT частично проверяются переданные сведения об организации, регистрации и иностранном налоговом резидентстве.

Гражданство и регистрационный адрес FL_NONRESIDENT

С версии 2.0.4 полная регистрационная проверка FL_NONRESIDENT отклоняет citizenshipCode = RU: тип резидента/нерезидента определяется гражданством. US остаётся отдельным регуляторным отказом, допустимый иностранный код принимается. Та же проверка гражданства применяется, если поле передано в частичном update.

При регистрации код страны адреса обязателен. RU требует российскую ФИАС-структуру, разрешённая иностранная страна — непустой fullAddress, а US даёт регуляторный отказ. Свободный текст адреса не используется для определения страны. Совместимый адресный контракт частичного update в этой версии не меняется.

Регистрационный адрес FL_RESIDENT

С версии 2.0.5 полная и частичная проверка адреса FL_RESIDENT допускает только beneficiary.address.registration.countryCode = RU. Российский адрес передаётся структурированно для последующей проверки по ФИАС. Корректный иностранный код возвращает обычную ошибку данных BEN.ADDR.REG.COUNTRY.MUST_BE_RU, а US сохраняет отдельный регуляторный отказ. Строковый иностранный регистрационный адрес относится только к FL_NONRESIDENT.

Дополнительный документ FL_NONRESIDENT

С версии 2.0.6 при передаче любого поля beneficiary.addDoc требуется технический typeCode: 005 для ВНЖ, 006 для РВП и 007 для миграционной карты. При регистрации у дополнительного документа обязательны номер и дата начала действия. Для ВНЖ и РВП серия передаётся при наличии, а дата окончания требуется только когда она предусмотрена самим документом.

Номер миграционной карты принимается в одной из трёх форм: 7 цифр без серии, 11 цифр без серии либо отдельная серия из 4 цифр и номер из 7 цифр. Прочая длина, нецифровые символы и сочетание отдельной серии с 11-значным номером отклоняются. Для миграционной карты при регистрации дата окончания остаётся обязательной.

В entrypoints.fl_nonresident.update_validation сохраняется частичный контракт: отсутствующие поля не становятся обязательными, однако при изменении addDoc необходимо повторить typeCode, а переданные номер, серия и даты проверяются по своему формату.

Налоговые признаки ФЛ и ИП

Полные проверки ФЛ и ИП требуют три логических поля: beneficiary.tax.foreignTaxResident, beneficiary.tax.usTaxResident и beneficiary.tax.usResident. Отсутствие поля, null и пустая строка дают ошибку .REQUIRED; значение другого типа даёт ошибку .BOOL. Логическое значение false считается заполненным.

В частичных проверках обновления отсутствие поддерживаемого налогового поля по-прежнему означает «не изменять». Если поле передано, null и значение другого типа отклоняются. Проверки конкретных значений признаков сохраняют прежнюю семантику для резидентов и нерезидентов.

PAY-996 / BEN-BUG-001: девять общих проверок заполнения возвращают ERROR: три .REQUIRED и три .BOOL для налоговых признаков, а также BEN.TAX.FOREIGN_COUNTRY.REQUIRED, BEN.TAX.FOREIGN_TIN.OR_REASON и BEN.TAX.TIN_ABSENCE_REASON.DICT. Это позволяет собрать подробные ошибки анкеты, не подставляя отсутствующие признаки как false. При отсутствии всего tax перечисляются все три признака, а в применимом иностранном блоке — также страна и альтернатива ИНН/причина. Иностранный ИНН можно заменить причиной A, B или C; неизвестный код причины остаётся ошибкой даже при переданном ИНН. У ошибки альтернативы ИНН/причина нет единственного поля.

Реальные запрещающие значения (usTaxResident=true, usResident=true, налоговая страна US и действующие ограничения foreignTaxResident) сохраняют EXCEPTION. Смешанная анкета с ошибкой данных и реальным запретом по-прежнему имеет итог EXCEPTION; приоритеты и конфиденциальность комплаенс-отказа не меняются. Состав exports, issue codes, сообщения, операторы, предикаты и обязательность полей сохранены. Новые поля и IP_NONRESIDENT update не добавлены.

Источники признаков США для ФЛ и ИП

Если передан beneficiary.contacts.postalAddress, вместе с ним требуется beneficiary.contacts.postalAddressCountryCode в формате ISO 3166-1 alpha-2. Значение US возвращает регуляторный отказ BEN.CONTACTS.POSTAL.NOT_US. Страна определяется по отдельному коду; слова в свободном тексте postalAddress не участвуют в этой проверке.

Тот же принцип действует для адресов и налоговых данных ФЛ и ИП. Код гражданства проверяется по beneficiary.fl.citizenshipCode, страна иностранного налогового резидентства — по beneficiary.tax.foreignTaxResidency.countryCode, а американские налоговые и резидентские признаки — по логическим полям налогового блока. Для регистрации FL_NONRESIDENT также проверяется beneficiary.address.registration.countryCode. Свободные строки почтового и иностранного налогового адреса не используются для определения страны.

Для beneficiary.fl.birthPlace действует отдельное ограничение регистрации: явные обозначения США распознаются по закрытому словарю целых Unicode-токенов и точечных аббревиатур. Проверка отклоняет США, USA, U.S., U.S.A., United States, United States of America, Соединенные Штаты и Соединенные Штаты Америки, включая варианты регистра и ё. Подстроки внутри других слов не совпадают: RUSSIA, AUSTRALIA, AUSTIN и United Statesville принимаются. Название города без явного обозначения страны, например Нью-Йорк, само по себе не классифицируется как США. Частичное обновление карточки этим регистрационным решением не изменено.

При регистрации FL_NONRESIDENT и IP_NONRESIDENT иностранный налоговый адрес и почтовый адрес необязательны и могут отсутствовать одновременно. При этом страна иностранного налогового резидентства, иностранный ИНН или причина его отсутствия остаются обязательными, а структурированный код US по-прежнему возвращает регуляторный отказ.

Контакты FL_NONRESIDENT

С версии 2.0.9 общий минимум контактов FL_NONRESIDENT снова требует российский beneficiary.contacts.phone или beneficiary.contacts.email. foreignPhone не может быть единственным контактом: процессор не передаёт его в телефонное поле карточки, поскольку ЦФТ принимает там только российский формат номера. Поле остаётся условно обязательным при применимом иностранном блоке и отсутствии российского телефона; при наличии оно всегда проверяется по международному формату. Контактные правила FL_RESIDENT и ИП этим изменением не затрагиваются.

Юридический адрес при регистрации UL_RESIDENT

С версии 2.0.0 entrypoints.ul_resident.full_validation требует в beneficiary.address.legal код страны RU, regionCode, postalCode, city или locality, streetType, street, house. fullAddress необязателен; одной строки недостаточно. Значения составных полей должны быть строками с непробельными символами. Адреса без улицы не входят в этот контракт. Идентификаторы ФИАС от мерчанта не требуются.

Проверки расположены в internal.ul_resident.address.* и вызываются только регистрационным блоком ЮЛ-резидента. Общая библиотека адресов, обновление ЮЛ-резидента и остальные 12 экспортов не меняются. Обновление ЮЛ по-прежнему требует полную строку при передаче адресного блока.

Отсутствующие поля дают UL.ADDRESS.LEGAL.FIAS.<PART>.REQUIRED уровня ERROR. Нестрочные значения и строки из пробелов дают .FORMAT. У общей ошибки CITY_OR_LOCALITY.REQUIRED поле field равно null; сервис может опускать его в мерчантском ответе. Эта проверка полноты не заменяет проверку адреса ЦФТ.

Это несовместимое изменение: ранее принятая заявка только с countryCode и fullAddress теперь отклоняется. Потребитель должен явно обновить точную версию зависимости и согласовать переход для незавершённых заявок.

Российский почтовый индекс, PAY-995, с версии 2.0.15

Для российского регистрационного адреса ФЛ/ИП переданный индекс должен быть строкой ровно из шести ASCII-цифр. Проверка не обрезает значение, не удаляет пробелы и не преобразует JSON-число в строку. Ведущий ноль сохраняется. Обязательность индекса и отсутствие адреса в частичном update не меняются.

Страну определяет адрес, не гражданство клиента. Иностранная регистрация ФЛ-нерезидента сохраняет прежний лимит 32 символа без российской маски. Совместимый update ФЛ-нерезидента по-прежнему использует российский маршрут, даже без countryCode или со старым игнорируемым значением страны.

Новый код BEN.ADDR.REG.POSTAL.FORMAT имеет уровень ERROR. Прежний BEN.ADDR.REG.POSTAL.LENGTH сохраняется для строк длиннее 32 символов. Для юридического адреса регистрации ЮЛ-резидента отдельное правило сохраняет код UL.ADDRESS.LEGAL.FIAS.POSTAL_CODE.FORMAT, но требует шесть цифр. Update ЮЛ и иностранный адрес ЮЛ-нерезидента не наследуют эту обязательность.

Маска уточняет формат в PAY-995 по поручению пользователя от 11.11.2026 и описанию ВПС. Исходное БТ требует контроля адреса, но не задаёт числовую маску индекса. Изменение входит в версии 2.0.15 и 2.0.16 и не заменяет опубликованный пакет 2.0.14. Версия 2.0.16 сохраняет правила 2.0.15 и исправляет проверку доставки. Сервис подключает точную версию после проверки публикации и содержимого registry. Источник идентичности сборки указан в build-info.

Использование в сервисе

const { createEngine } = require("@jsonspecs/rules");
const snapshot = require("@processengine/nominal-beneficiaries-rules/dist/snapshot.json");
const operators = require("@processengine/nominal-beneficiaries-rules/operators/node");

const engine = createEngine({ operators });
const prepared = engine.compileSnapshot(snapshot);

const result = engine.runPipeline(prepared, {
  pipelineId: "entrypoints.fl_resident.full_validation",
  payload,
  context: { currentDate: "2026-07-22" },
});

Сервис компилирует snapshot один раз при старте. pipelineId всегда передаётся явно на верхнем уровне. Ограничение транспортного размера, аутентификация, авторизация и доставка одобренной версии пакета остаются обязанностью сервиса.

Авторская модель

manifest.json          версия спеки, exports, пути и единый UI-каталог
rules/                 один JSON-артефакт на файл
operators/node/        доменные операторы Rules v4
tests/                 эталонные векторы операторов
samples/               входы и ожидаемые бизнес-результаты
scripts/               проверки пакета и релизного состояния
dist/                  результат jsonspecs build, не источник истины

manifest.catalog является единственным источником редакторских метаданных. Исполняемые артефакты не содержат description, а отдельные контракты полей, привязанные к конкретному обработчику, в пакете не поддерживаются.

Правила, создающие ошибки, содержат issue.meta со ссылками на разделы и пункты бизнес-требований, справочной страницей и SHA-256 исходного DOCX. Этот блок входит в sourceHash и возвращается Rules v4 вместе с ошибкой.

У правила нет роли check|predicate: оператор возвращает PASS, FAIL или SKIP. Объект issue определяет последствия FAIL в исполняемом шаге и игнорируется при использовании правила внутри when.

Доменные операторы

  • valid_inn проверяет контрольные разряды ИНН ФЛ и ЮЛ;
  • inn_not_repeated запрещает 12-значный ИНН из одной повторяющейся цифры;
  • is_iso_date проверяет существующую календарную дату в формате YYYY-MM-DD;
  • migration_card_number_format проверяет формы номера миграционной карты 7, 11 и 4+7 цифр;
  • not_contains_normalized_phrases проверяет отсутствие заданных целых фраз, регистрозависимых токенов и точечных аббревиатур после Unicode-нормализации;
  • passport_rf_issued_at_or_after_age проверяет минимальный возраст выдачи;
  • passport_rf_valid_after_replacement_age проверяет возраст замены и льготный период.

Операторы экспортируются напрямую как карта {schema, evaluate}. Ядро разрешает пути из field и inputs; оператор получает только значения и постоянные params, не видит payload, context или текущий pipeline.

Документация

История миграции с прежнего движка остаётся в Git. Начиная с версии 1.0.0 регрессионным контрактом являются актуальные правила, примеры и эталонные векторы.

Район и планировочная структура (2.0.12)

Добавлены типы кв-л и кв-л. и признаки наличия regionArea при обновлении регистрационного адреса. Район regionArea необязателен: отсутствие допустимо, а переданное значение проверяется как непустая строка. Для ФЛ/ИП проверяется beneficiary.address.registration.regionArea, для регистрации ЮЛ-резидента — beneficiary.address.legal.regionArea. При частичном обновлении передача района включает действующие проверки полноты регистрационного адреса; отсутствующий адрес не становится обязательным.

Ошибки формата: BEN.ADDR.REG.REGION_AREA.FORMAT и BEN.ADDR.LEGAL.REGION_AREA.FORMAT. Они не означают, что район обязателен для любого адреса. Район не заменяет regionCode/regionName субъекта РФ.

Точная flat-проекция Rules не возвращает непустые контейнеры по пути самого поля. Поэтому проверка пакета не заменяет входную проверку JSON-типа адреса потребителем: перед VALIDATE_ADDRESS процессор дополнительно отклоняет объекты и массивы вместо района. Изменений движка Rules в этом релизе нет.

Версия выпускается штатным exact-tag релизом. Потребитель подключает точный опубликованный registry-архив; локальная сборка не доказывает публикацию.

Адрес без улицы (2.0.13)

В российских адресах ФЛ/ИП и юридическом адресе ЮЛ-резидента можно опустить оба поля street и streetType. Если передано одно, требуется второе. Регион, населённый пункт, дом и индекс остаются обязательными; допустимость адреса подтверждает ЦФТ. Район regionArea остаётся необязательным для общего контракта; для Краснообска нужен Новосибирский. Обновление ЮЛ-резидента сохраняет реестровый сценарий.