# todo.md Remaining work for `@larvit/smpp`. Read [AGENTS.md](AGENTS.md) first — the goals and hard rules there constrain every item below. This is a working file that sets its own rules. The documentation conventions in AGENTS.md do not govern it, and nothing here is a source anything else may cite. ## Status The rewrite is **feature complete and green**: the suite, lint and typecheck are clean on Node 18 to 26. What is left is release work and a few things worth adding before or after 1.0.0. ## 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](README.md); this is the short form. ```ts 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` | | `smsIdFormat`: a peer's `submit_sm_resp` and receipt ids read into one notation before they are compared | `test/dlr.test.ts`, `test/session-extras.test.ts` | | A draining `close()` and `unbind()`, bounded by `shutdownTimeout` or an abort | `test/session-extras.test.ts` | | A drain that also waits out the messages the application has not answered, with `sendDlr()` the one send that passes it | `test/session-extras.test.ts` | | `OutgoingRequests`: the gate, the window, the pending map and the retry under one owner, told when a link comes up or goes down | `test/session-extras.test.ts`, `test/session.test.ts` | | Held messages capped and expiring, so an application that answers nothing cannot grow them | `test/session-extras.test.ts` | | A send with no link held for the next one, and one the link dropped under counted as `unanswered` | `test/session-extras.test.ts` | | A message whose link dropped refused an answer, with its receipt still allowed out | `test/session-extras.test.ts` | | The hold released exactly when the peer was answered: a refused `sendResp()` keeps it, a listener that rejected drops it | `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` | | An intermediate delivery notification read as a report marked `intermediate`, as is a receipt reporting `ENROUTE` or `SCHEDULED`, and never counted into a merge | `test/dlr.test.ts`, `test/session.test.ts`, `test/session-extras.test.ts` | | A transient state sent under the marker the spec gives it, off the same list the reader uses | `test/session-extras.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 to 26, Renovate, tag-triggered publish | `.gitea/workflows/` | Every defect listed in the AGENTS.md table has a regression test naming the behaviour. ## Move the repository to Gitea `gitea.larvit.se/larvit/smpp-js` is the repository and `github.com/larvit/smpp-js` becomes a push mirror of it. Maintainer's call, 2026-09-13, to move before 1.0.0. - [x] `larvit/smpp-js` holds `main`, from `typescript`, and `v0.4.0`, from `master`. `rewrite-base` and the `renovate/*` branches stayed behind. - [x] Fast-forward is the only merge style. `main` takes no pushes, requires `Test / lint (pull_request)` and `Test / test (*) (pull_request)`, blocks an outdated branch, and gives admins no override. - [x] The workflows are in `.gitea/workflows/`. Tests run on pull requests only, the event the gate reads; Renovate runs as a scheduled workflow, as on adf-codec. - [x] The release publishes without provenance, which npm generates only on GitHub Actions and GitLab CI/CD. - [x] `package.json` names Gitea. The README links absolutely: npmjs.com resolves a relative link against itself when the `repository` is not on GitHub. Its test badge is gone, since Gitea reports a workflow's status per branch and no workflow runs on `main`. - [ ] Add `RENOVATE_GITHUB_TOKEN` as an organization secret. The Renovate workflow reads it for GitHub-hosted lookups, the actions included, and adf-codec has it as a repository secret only. - [ ] **Where issues are filed.** Gitea issues are off, so `package.json` names no `bugs` URL until this is decided. - [ ] **Review bot.** CodeRabbit does not support Gitea. ## Before publishing 1.0.0 - [x] `NPM_TOKEN`, which `.gitea/workflows/release.yaml` needs, is a Gitea organization secret. - [ ] Tag `v1.0.0` on Gitea to publish. The first publish creates `@larvit/smpp` on npm, provided the token can publish under `@larvit`. - [ ] `npm deprecate larvitsmpp` pointing at `@larvit/smpp`. Maintainer's call to run it; not something CI should do. ## Retire the GitHub repository In this order. The push mirror replaces GitHub's branches with Gitea's, which closes every pull request based on `master` without a reply, and GitHub refuses to delete the default branch it syncs over. - [ ] Close the backlog below. - [ ] Close [#71](https://github.com/larvit/larvitsmpp/pull/71), pointing at Gitea. - [ ] Rename `larvit/larvitsmpp` to `larvit/smpp-js`; GitHub redirects the old URLs. - [ ] Push `main` and make it GitHub's default branch. - [ ] Remove Renovate and CodeRabbit from the GitHub repository. - [ ] Add it to Gitea as a push mirror, with a GitHub credential that can write to it. ## Close the GitHub backlog **Answer and close as fixed by 1.0.0**, the reply naming what fixed it: - [ ] [#2](https://github.com/larvit/larvitsmpp/issues/2) Tests for the README examples: `test/readme.test.ts`. - [ ] [#3](https://github.com/larvit/larvitsmpp/issues/3) Tests for flash messages: `test/session.test.ts`. - [ ] [#4](https://github.com/larvit/larvitsmpp/issues/4) DLR errors with `message_state` missing: `dlrFromPdu()` parses the `stat:` receipt text when the TLVs are absent. - [ ] [#13](https://github.com/larvit/larvitsmpp/issues/13) Limit a long SMS to fewer segments: the `maxSegments` send option. - [ ] [#16](https://github.com/larvit/larvitsmpp/issues/16) Support all three bind types: bound and enforced in both directions. - [ ] [#17](https://github.com/larvit/larvitsmpp/issues/17) `addr_ton`/`addr_npi` should be settable: `sendSms()` takes all four, documented and tested. - [ ] [#20](https://github.com/larvit/larvitsmpp/issues/20) Tests fail on current dependency versions: the mocha suite is gone; `node:test` on Node 18 to 26. - [ ] [#33](https://github.com/larvit/larvitsmpp/issues/33) Large inbound text arrives as raw `Buffer` segments: `IncomingRequests` reassembles a UDH-carrying `deliver_sm` into one `sms` event. - [ ] [#68](https://github.com/larvit/larvitsmpp/pull/68), a pull request: `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](https://github.com/larvit/larvitsmpp/pull/40), [#41](https://github.com/larvit/larvitsmpp/pull/41), [#42](https://github.com/larvit/larvitsmpp/pull/42), [#45](https://github.com/larvit/larvitsmpp/pull/45), [#46](https://github.com/larvit/larvitsmpp/pull/46), [#47](https://github.com/larvit/larvitsmpp/pull/47), [#59](https://github.com/larvit/larvitsmpp/pull/59), [#63](https://github.com/larvit/larvitsmpp/pull/63), [#64](https://github.com/larvit/larvitsmpp/pull/64), [#67](https://github.com/larvit/larvitsmpp/pull/67), [#70](https://github.com/larvit/larvitsmpp/pull/70), [#77](https://github.com/larvit/larvitsmpp/pull/77). [#70](https://github.com/larvit/larvitsmpp/pull/70) is the open `uuid` advisory GitHub reports on the default branch; it disappears with the runtime dependencies rather than being fixed. [#60](https://github.com/larvit/larvitsmpp/issues/60) is Renovate's dashboard — close it with Renovate's removal from GitHub. **Leave open:** [#8](https://github.com/larvit/larvitsmpp/issues/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. ## Worth doing, not blocking - [ ] **A send the codec will refuse waits for a link and a window slot first.** `refuse()` in `outgoing-requests.ts` runs `misuse()` and the abort check before the wait, precisely so a call that can never go out does not queue for what it will never use; a body `objToPdu()` refuses on every attempt is the same case, and #98 made it a common one. On a down link the caller waits `responseTimeout` and is told the link failed rather than that the body could not be built — goal 2's wrong answer about what happened. The cheap fix builds the PDU twice, so the shape is the open half. Raised by the architecture review of [#98](https://github.com/larvit/larvitsmpp/pull/98), 2026-09-09. - [ ] **`message.ts` answers two questions.** Message coding and the SMPP time format (`smppDate`, `smppTime`) share the file, which the architecture map in AGENTS.md already spells out as four concerns. Nothing is wrong today; if the file has to move for another reason, `smpp-time.ts` is the split. Raised by the architecture review of [#98](https://github.com/larvit/larvitsmpp/pull/98), 2026-09-09. - [ ] **A gate that refuses a floating version anywhere in the repo.** Maintainer's ask on [#71](https://github.com/larvit/larvitsmpp/pull/71), 2026-09-06, on the `release.yaml` pinning thread. Pinning every action and runner by hand is what the ask followed; the gate is what keeps them pinned. It has to cover workflow `uses:` and `runs-on:`, compose `image:`, and Dockerfile `FROM`, and the conventions differ per kind — actions take a semver tag, images the full patch version — so one grep for `latest` is not it. - [ ] **A gate that fails when the test matrix misses the current Node.** Maintainer's ask on [#71](https://github.com/larvit/larvitsmpp/pull/71), 2026-09-06, on the Node 26 thread. Node 26 was added by hand; nothing notices when 27 ships. Needs a source for what Current is — the Node release schedule is published as JSON — and a decision on whether a new Current fails the build or opens a PR, which is what Renovate already does for everything else here. - [ ] **Group the session's collaborators under `src/session/`.** `session.ts` imports `dlr-merger`, `incoming-requests`, `link-timers`, `outgoing-requests`, `pdu-transport`, `reconnect-loop` and `send-sms`, and nothing else does, so the directory would make that boundary visible. The `OutgoingRequests` extraction this was to be done with landed on 2026-09-01, so it is the remaining half. Raised by review, 2026-09-01. - [ ] **`leftOf()` and the link gate's own budget are one concept counted twice.** `idle-waiters.ts` reads what is left of a budget as `Math.max(1, deadline - now)`, because 0 means "forever" there; `link-gate.ts` runs the same subtraction and calls `<= 0` expired. Neither is reachable from the other, so nothing can disagree today, but a reader who learns one and applies it to the other is wrong. A budget type both take would close it. Raised by review, 2026-09-01. - [ ] **`err:` on a receipt for a state that neither delivered nor failed.** `receiptText()` now writes `err:000` for `DELIVERED` and for the two transient states, and `err:001` for every other — so `ACCEPTED`, `SKIPPED`, `UNKNOWN` and `DELETED` still announce an error code the SMSC never had. Which of those are failures is the open half. Raised by review, 2026-09-03; needs a decision. - [ ] **`once()` is copied into four test files, and two copies never give up.** `session-extras.test.ts` and `readme.test.ts` reject after 5000 ms; `session.test.ts` and `tls.test.ts` wait forever, so an event that never fires still hangs the run the way an unclosed listener used to. One shared, guarded copy closes the rest of that class. - [ ] **A peer whose message ids share one base logs a refused merge on every send.** `smsc01-000123` and `smsc01-000124` carry the same base, so `DlrMerger` merges the first message and refuses every one after it, one log line per send. Left at `info` — nothing the operator can fix is wrong — but a rate guard or silence may suit it better. Raised by review, 2026-08-30. - [ ] **`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. - [ ] **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. ## Declined - **Merge state surviving a process restart.** Declined by AGENTS.md goal 7, maintainer's call, 2026-09-02. A restart loses every incomplete receipt group and a peer has no reason to resend one it already had answered, so the loss is real — but surviving it means handing the application the merge state to persist, which the scope floor covers as squarely as holding the state here would, and which publishes the shape of `DlrMerger`'s groups against goal 6. Nothing is foreclosed: the seam can still be added after 1.0.0 as a minor. - **Throughput throttling — a TPS cap, and backing off on `ESME_RTHROTTLED`.** Declined by AGENTS.md goal 7: an operator's rate limit is scoped to the account, while the widest thing this library owns is a session, so a bucket here cannot see a second process binding the same account and is wrong in exactly the case it exists for. `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.