fix(pull)!: report every way a send can fail, instead of hiding four of them

[IgorShevchik]

Why

Running /pull-lab (#554) against a live portal turned up a defect it was not
looking for: PullClient.sendMessage() resolved as if the message had been
accepted, nothing ever arrived, and nothing anywhere said why.

Four separate ways for a send to go nowhere quietly, found one at a time — the
last three by a five-reviewer panel over the first revision:

1. sendMessageBatch started the channel lookup and dropped the promise, so
   the method resolved before the lookup had answered.
2. ChannelManager.getPublicIds caught the portal's refusal and resolved an
   empty channel map — a valid input to the encoder, which then built a
   message addressed to nobody.
3. The connector's send() returns false when the frame does not leave, and
   that boolean was passed to the caller as a resolved value — the same
   defect one layer further out. Same on the JSON-RPC branch, which dropped the
   boolean and resolved true unconditionally.
4. The publishing gate threw a bare Error with no code to branch on.

What it does now

One contract: resolve true when the transport accepted the frame, reject
otherwise.

Code	When
JSSDK_PULL_PUBLIC_IDS_UNAVAILABLE	The recipients' channels could not be resolved. sendMessage() only.
JSSDK_PULL_SEND_REFUSED	The transport would not take the frame.
JSSDK_PULL_PUBLISHING_DISABLED	The portal has not enabled client publishing.

true is not a delivery receipt, and the JSDoc and the Error Codes page say
so: send() hands the frame to the socket, and long-polling fires its request
without awaiting the response.

The cause is not a fault

pull.channel.public.list is not part of the application REST surface.
Bitrix24's documentation states an application's Pull client is receive-only
— the back end publishes with pull.application.event.add. The SDK's own Pull
page already said exactly that; it just also exposed a method that could not
honour it.

The spec that pinned the old behaviour

An existing case asserted the empty resolve, because "a failed channel lookup
must not reject into the caller's pull loop". That path does not exist —
verified independently by two reviewers: getPublicIds is reached only from
sendMessageBatch, reached only from the two public methods, neither of which
has an internal caller, and ChannelManager is not exported from the package
index. The case is inverted rather than deleted, with the reasoning recorded on
it, and its file header no longer asserts the behaviour it drops.

What the panel changed

The fix had a hole the tests could not see. A refusal reaches
ChannelManager in two shapes — a thrown AjaxError, and a RESOLVED
non-success AjaxResult on the isSoftError() path. The rejection only
happened on the second because reading .result off getData()'s undefined
threw a TypeError: it worked by accident, and logged that TypeError rather
than the portal's message — so on that path it still did not say why. Both
deliveries are handled explicitly now, the cause travels in originalError, and
a successful answer yielding no channel for any requested user rejects rather
than resolving an empty map.

The tests could not see it because they faked actions.v2.call.make wholesale.
The seam is now vi.spyOn(httpClient.ajaxClient, 'post') as testing.md
specifies, so the real HttpV2.call() builds what the SDK would hand over.

sendMessageToChannels() does not raise the lookup error, and two documents
said it did. It carries channelList and no userList, so the lookup is
never reached. Corrected, and pinned by a case. The same short-circuit means
sendMessage() does not reject when every channel is cached either.

The real-frames test was green on a real divergence. Its normaliser
coalesced every field with ??, erasing proto2 presence — the one property a
proto2 codec gets wrong. Sender.id is absent on the wire in every frame:
protobuf.js reports it absent, the lite codec materialises an empty
Uint8Array. Deleting the lite codec's entire default initialiser also left
1145 tests green. The comparison no longer defaults the scalars, the known
divergence has its own case, and the defaults are pinned by a synthetic frame in
the differential spec — no recorded frame can cover them, because every real
message carries all four fields.

Documentation

Swept rather than spot-fixed.

• 3.within-2x.md is written around what the caller has to do: four
  numbered steps with compiled examples — publish from the back end in an
  application; branch on the three codes, because only one is worth retrying;
  attach the catch at the call site in a timer; stop reading the resolved
  value.
• Error Codes gains both new codes, each saying what it replaced.
• The Pull page states all three rejections and links to the migration note.
• b24jssdk-helpers/SKILL.md gains a "the Pull client only RECEIVES"
  section with the pull.application.event.add example. It taught subscription
  only, so nothing it generated was broken — but nothing steered a model away
  from reaching for sendMessage() either.
• Checked and unchanged: no example page and no other skill calls either
  send method.

The recorded-frame fixture

pull-protobuf.md set the exit criterion for deleting the vendored protobuf.js:
a ResponseBatch recorded from a live portal, committed as a fixture, decoded
by both codecs. It is here, on the decode side — two frames, one small and
one whose body passes the three-byte length prefix. They agree.

The fixture carries its own knownGaps and regenerating fields. The gaps,
stated rather than implied: decode-side only (encode is unreachable from an
application); no stats frame was ever emitted, so the oneof rests on the
differential suite; every message carries all four scalars, so the decode
defaults need a synthetic case; the bodies are ASCII, so multi-byte UTF-8
decoding is not exercised by real bytes at all.

One substitution, in place and equal in length: the portal hostname in
extra.server_name. Equal length is mandatory and regenerating says so — a
shorter replacement invalidates four nested length prefixes and the frame stops
parsing.

Compatibility

Breaking, and marked as such. Two things a caller can be relying on:

A loop with no catch can now take the process down. A heartbeat calling
sendMessage() on a timer without handling the promise, on a portal where the
lookup fails transiently, used to lose that one message and carry on. Now
the call rejects, and an unhandled rejection terminates the process by default
in Node 15 and later. For that caller the old behaviour was better — it was
not better for anyone who needed to know their messages were not arriving.

The success path changed too: sendMessage() used to resolve undefined
immediately, effectively fire-and-forget. It now awaits the lookup and the send.
Step 3 of the migration note is the fix for the first; step 4 for the second.

Testing

publish-failure-is-reported.unit.spec.ts — 12 cases: both refusal deliveries,
the cause, the message, the no-value-interpolation rule, the rejection path with
a lookup assertion, the success path with a connector.send spy,
sendMessageToChannels(), a refused send, a missing connector, and the
publishing gate.

real-portal-frames.unit.spec.ts — 6 cases, including the pinned divergence and
a body-length assertion that checks the decoded body rather than the frame.

Mutation-checked throughout, including the panel's own false-green
demonstrations: restoring the soft-error swallow, deleting the send, deleting
the codec defaults, ignoring a refused send and reading created as a varint
all redden now.

Unit suite 92 files / 1152 tests; lint, lint:md, lint:md-links, all 11
typecheck passes, docs-lint --strict and docs:lint-links clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr