smpp-js/todo.md

todo.md

Remaining work for the @larvit/smpp 1.0.0 rewrite. Read AGENTS.md first — the hard rules there constrain every item below.

Status

The rewrite is feature complete and green: 236 tests, lint and typecheck clean, verified on Node 18, 20, 22 and 24. What is left is release work and a few things worth adding before or after 1.0.0.

docker compose run --rm node npm install
docker compose run --rm node npm test

The agreed API

Settled with the maintainer before implementation. Do not change any of it without asking. The public surface is documented in README.md; this is the short form.

import { client, server } from '@larvit/smpp';

const { err, session } = await client({ host, password, port, username });
const { err: sendErr, pduObjs, smsIds } = await session.sendSms({ dlr, from, message, to });
await session.unbind();

const { err: serverErr, server: smpp } = await server({ authenticate, port });
smpp.on('session', session => {
	session.on('sms', async sms => {
		await sms.sendResp();
		if (sms.dlr) await sms.sendDlr('DELIVERED');
	});
});
await smpp.close();

Rules the API follows:

• Never throws. Everything fallible resolves to { err?, … }. See AGENTS.md rule 1.
• Named exports only, no default export. defs is exported as a group alongside the individual tables.
• The PDU codec is synchronous and returns { err?, pduObj? } / { err?, buffer? }.
• Low-level surface stays public, including session.sock, session.send() and session.sendReturn().

Done

	Covered by
Definition tables: constants, errors, encodings, wire types, TLVs, commands	test/encodings.test.ts, test/types.test.ts, test/commands.test.ts
Message helpers: splitting, bit counting, SMPP dates and times	test/message.test.ts
PDU codec: parse, build, respond, per-command typing, bounds checks	test/pdu.test.ts
Stream framing	test/pdu-framer.test.ts
Delivery receipt parsing, TLV and text	test/dlr.test.ts
Session, client, server: bind, auth, send, reassembly, DLRs, timeouts, abort, send window	test/session.test.ts
Merged multipart DLRs including across a reconnect, reassembly bounds, per-send abort, the segment cap	test/session-extras.test.ts
Every runnable README example	test/readme.test.ts
Receipt-versus-message classification by esm_class	test/dlr.test.ts, test/session.test.ts
A listener that throws, or rejects, reaching sessionError/serverError rather than the process	test/session.test.ts, test/error-from.test.ts
Cross-checked against node-smpp both ways and over a live session	test/interop.test.ts
CI on Node 18/20/22/24, Renovate, tag-triggered publish	.github/workflows/

Every defect listed in the AGENTS.md table has a regression test naming the behaviour.

The GitHub backlog, once this branch is master

Nothing below is closed while master is still 0.4.0 — declining a security bump on a live default branch is worse than leaving it open. Work through this immediately after the merge.

Close as fixed by 1.0.0, naming the replacement in the comment:

	Fixed by
#4 DLR errors with message_state missing	dlrFromPdu() parses the stat: receipt text when the TLVs are absent
#33 Large inbound text arrives as raw Buffer segments	IncomingRequests reassembles a UDH-carrying deliver_sm into one sms event
#3 Tests for flash messages	test/session.test.ts
#20 Tests fail on current dependency versions	The mocha suite is gone; node:test on Node 18/20/22/24
#2 Tests for the README examples	test/readme.test.ts
#17 addr_ton/addr_npi should be settable	sendSms() takes all four, documented and tested
#16 Support all three bind types	Bound and enforced in both directions
#13 Limit a long SMS to fewer segments	The maxSegments send option
#68 message_id in submit_sm_resp, spec DLR codes	All four hold: sendResp() always answers a message_id, per segment; stat:UNDELIV is the 7-character code. Credit the reporter — the fork found real defects.

Close as superseded, all against 0.4.0 dependencies the rewrite does not have — async, coveralls, eslint, iconv-lite, larvitutils, mocha, mocha-eslint, portfinder, uuid: #40, #41, #42, #45, #46, #47, #59, #63, #64, #65, #67, #70. #70 is the open uuid advisory GitHub reports on the default branch; it disappears with the runtime dependencies rather than being fixed.

#60 is Renovate's dashboard — leave it, it re-baselines itself against the new package.json.

Leave open: #8, the socket's remote host and port on log messages. Only server - incoming connection carries them today; putting them on every session message is a change to every call site.

Before publishing 1.0.0

• Create the @larvit/smpp package on npm and add NPM_TOKEN to the repository secrets, which .github/workflows/release.yaml needs.
• Tag v1.0.0 to publish.
• npm deprecate larvitsmpp pointing at @larvit/smpp. Maintainer's call to run it; not something CI should do.
• Decide what happens to master: this branch is an orphan, so merging it is a deliberate act.

Worth doing, not blocking

• In-flight sends across a reconnect. They currently fail with "Session closed before a response arrived" and the caller retries. Re-queueing them automatically would be friendlier but risks duplicate delivery, so it needs a decision before it is built.

• Merge state does not survive a process restart. A drop no longer discards it, but a restart loses every incomplete group, and a peer has no reason to resend a receipt it already had answered. Surviving one means exposing the merge state for the application to persist and hand back, which is a public-surface decision.

• close() and unbind() drop in-flight requests instead of draining them. teardown() settles every pending request with "Session closed before a response arrived" and destroys the socket in the same tick, so a submit the SMSC has already accepted is reported to the caller as a failure — the ambiguous outcome that produces a duplicate on retry. Give both a drain: refuse new sends, wait out the pending responses up to a shutdownTimeout, then tear down whatever is left. Distinct from re-queueing across a reconnect above — this is the deliberate shutdown path, where there is nothing to come back to.

• session.ts is 386 lines. The one seam left in it is a socket-to-PDU transport, which would move the deliberately public sock field out of Session or turn it into a getter — a public-surface change, so it waits for a decision.

• Group the session's collaborators under src/session/. Only session.ts imports reassembly, dlr-merger, send-window, link-timers, reconnect-loop, pending-requests and send-sms, so the directory would make that boundary visible. Do it on the next extraction out of session.ts, not as a move of its own.

• Does an intermediate delivery notification deserve to be a dlr? esm_class message type INTERMEDIATE_DELIVERY (0x20) is classified as a message today, so a peer that reports non-final states with it hands the application a raw id:… stat:ENROUTE text as an inbound SMS. Kannel treats 0x04, 0x08 and 0x20 alike as report-bearing. Against it: a non-final report would take a segment's slot in DlrMerger and complete the group early. Raised by review, 2026-08-27; needs a decision.

• A failing session test hangs the run rather than ending it. Every test that starts a server closes it on its last line, so an assertion that throws leaves the listener open and node --test never exits: all four CI legs burn the ten-minute cap instead of reporting the five-second failure. t.after(() => smpp.close()) fixes it, at every call site.

• submit_multi and the broadcast commands encode and decode, but nothing exercises them end to end. The interop suite is the natural place.

• Move to TypeScript 7 once typescript-eslint supports it; renovate.json pins TypeScript below 6.1 for exactly that reason.

• Coverage reporting. node --test --experimental-test-coverage works today; nothing publishes the numbers.

• Normalise the message id on both sides of a receipt. An SMSC that answers submit_sm_resp with a hex message_id and sends the receipt's id: in decimal — or pads it, or flips its case — leaves smsIds and dlr.smsId unequal, so correlation silently yields nothing and the application sees no receipts at all. A dlrIdFormat option ('hex' | 'decimal' | 'raw', or a function) applied to both ids before they are compared covers the whole class. The smallest change on this list for the most real-world breakage removed.

• An onReceipt hook. Receipt text is only loosely specified and operators disagree on it, but dlrFromPdu() is wired into IncomingRequests with no seam of its own: an application facing a format we do not parse has to take the whole PDU on onRequest and reimplement the dispatch, which owns the response as well. Mirror the onRequest seam — return a Dlr to own the receipt, undefined to fall through to the built-in parser.

• Turn reconnect on by default in client(). Surviving a dropped link is most of why the session layer exists, and it is opt-in behind an empty object today, so an application that does not read the options table gets none of it. A default change, so it needs a decision.

Declined

• Throughput throttling — a TPS cap, and backing off on ESME_RTHROTTLED. Two reasons, either sufficient. An operator's rate limit is scoped to the account, while the widest thing this library owns is a session: a bucket here cannot see a second process binding the same account, so it is wrong in exactly the case it exists for. And a rate limiter's queue drains at a fixed ceiling rather than at the peer's response rate, so a submit rate sustained above the limit grows it without bound — and a queue holding messages the caller was told were accepted loses them on restart, which is worse than refusing them up front. Pacing an account needs durable shared state this library deliberately has none of. sendSms() surfaces ESME_RTHROTTLED to the caller instead, and maxOutstanding stays: a window slot frees on the peer's next response, which is self-limiting in a way a rate ceiling is not.