feat: add isNotFound, isConflict and isMalformedId error predicates

[lmjabreu]

Why

Consumers keep re-implementing the same checks on top of CommsRequestError. comms-cli has its own copies, added in comms-cli#66, and the MCP needs the same ones for checking ids. @scottlovegrove raised it on that PR: they belong here, next to the error they inspect.

Change

Five exports in types/errors.ts, beside CommsRequestError:

• isNotFound(error) and isConflict(error), 404 and 409.
• getCommsErrorCode(error) and getCommsErrorString(error), the error_code and error_string from the response body, or null. Branch on the code, display the string.
• isMalformedId(error), a 409 carrying error_code 217, which is a bad reference rather than a conflict.

isMalformedId keys on the code rather than the message, because the API pairs 217 with two different strings: one for an id that does not base58-decode to 16 bytes, and one for a version nibble that is not 7. comms-cli originally matched on the prose and missed the second.

They narrow with instanceof CommsRequestError, matching migration.ts and fetch-with-retry.ts rather than duck-typing the shape.

Not included: comms-cli's 401 and 403 helpers. isForbidden is defined there as "a 403 that is not an OAuth-scope failure", which is CLI policy rather than a property of the response, so it stays there for now.

Checks

• npm run check, npm run type-check, npm test: passed (246 tests, 19 new).
• npm run build, npm run attw: passed. All five are exported from the package root.
• Mutation-tested, six mutations, 1-line diff each, each failing at least one test: isMalformedId ignoring the code, getCommsErrorCode coercing a string, getCommsErrorString coercing a non-string, getCommsErrorString falling back to error.message, and instanceof relaxed to duck-typing in both readers.

Follow-up: a comms-cli PR deleting its copies once this is released. comms-cli#67 does the same for the id validator.

🤖 Generated with Claude Code

[lmjabreu]

@doistbot /review

[doistbot]

Adds five focused exports beside CommsRequestError — isNotFound, isConflict, getCommsErrorCode, getCommsErrorString, and isMalformedId — giving consumers a single home for response-error checks instead of per-repo copies, with isMalformedId sensibly keyed on error code 217 rather than prose. The helpers narrow via instanceof, guard the response-body shapes, are re-exported through the package root, and come with solid edge-case coverage plus mutation testing. No inline issues were flagged; the security and reuse passes found no concerns, noting the functions are pure read-only inspectors with no duplicated existing utility.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (2)

• src/types/errors.ts:62: The TSDoc example calls api.threads.getThread({ id }), but ThreadsClient.getThread is declared as getThread(id: string). Passing an object will not type-check. Change the example to api.threads.getThread(id).
• src/types/errors.test.ts:84: This assertion duplicates line 71 exactly: both call getCommsErrorString(requestError(409)), and requestError always supplies the same 'request failed' message. The block therefore adds no regression signal beyond the earlier "no error_string" case. Either delete this it block or make the intended scenario distinct, e.g. construct new CommsRequestError('server text', 409) so the test explicitly shows the message is not used as a fallback.

_{Share Feedback • Review Logs}

[lmjabreu]

The TSDoc example calls api.threads.getThread({ id }), but ThreadsClient.getThread is declared as getThread(id: string).

Fixed. It's getThread(id: string) at threads-client.ts:106, so the example wouldn't have compiled.

This assertion duplicates line 71 exactly

Fixed. Now builds its own new CommsRequestError('server text', 409), so the message it must not return is visible in the test.

[doist-release-bot]

🎉 This PR is included in version 3.3.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀