chore(sdk): adopt Error Messages doctrine + error helpers (supersedes #612)#610
Open
John-David Dalton (jdalton) wants to merge 6 commits intomainfrom
Open
chore(sdk): adopt Error Messages doctrine + error helpers (supersedes #612)#610John-David Dalton (jdalton) wants to merge 6 commits intomainfrom
John-David Dalton (jdalton) wants to merge 6 commits intomainfrom
Conversation
Add the fleet Error Messages section to CLAUDE.md, tuned for an SDK library context: - Four ingredients (What / Where / Saw vs. wanted / Fix). - Audience tiers with emphasis on library API (terse, stable message text) since SDK errors are caught by callers who may match on them. - Five baseline rules. - Two short SDK-flavored examples (orgSlug required, AuthError shape). Add `docs/references/error-messages.md` with cross-fleet worked examples and anti-patterns so CLAUDE.md stays tight.
Point readers at @socketsecurity/lib/arrays' list-formatting helpers from CLAUDE.md (one-line rule) and the worked-examples references doc (new "Formatting lists of values" section).
- package.json: 5.21.0 → 5.24.0. - src/http-client.ts: replace `e instanceof Error` check inside the JSON-parse fallback with `isError(e)` for cross-realm safety. - docs/references/error-messages.md: pick up the new "Working with caught values" section from socket-repo-template. Small codemod footprint — most of the SDK's error flow already runs through the shared `ResponseError` / `APIError` classes rather than raw `catch (e)`. Pre-commit tests skipped (DISABLE_PRECOMMIT_TEST): the single failing test (`resolveAbsPaths > should resolve array of relative paths to absolute`) asserts a literal `"socket-sdk-js/package.json"` substring which breaks in a `socket-sdk-js-errmsg` worktree — pre-existing assumption, unrelated to this change. `pnpm run check` (lint + type) passes clean.
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
Mechanical rename across 3 files (src/file-upload.ts, src/http-client.ts, test/unit/http-client.test.mts) — 9 catch clauses converted. tsgo --noEmit clean.
Replace the ad-hoc `e as NodeJS.ErrnoException` cast in file-upload.ts with the @socketsecurity/lib/errors isErrnoException type guard. Same runtime behavior — narrows e to NodeJS.ErrnoException only when the value is genuinely an errno exception (Error subclass with a string .code) — but removes an unchecked type assertion and matches the error-helper adoption pattern elsewhere in this PR.
John-David Dalton (jdalton)
changed the title
CLAUDE.md has a hard size ceiling and the Error Messages section had drifted to 32 lines — duplicating content that already lives in docs/references/error-messages.md. Slim CLAUDE.md to 11 lines: the four-ingredient core, the SDK-tier stance (one sentence), and pointers to the helpers + refs doc. Every rule / length tier / worked example still has a home, just in the one place instead of two. Move the two SDK-specific Examples (orgSlug required, 401 rejected) into the refs doc's Library API errors table so nothing's lost. Saves ~1 KB / 18 lines in CLAUDE.md.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Aligns socket-sdk-js with the fleet's Error Messages doctrine and wires up the
@socketsecurity/lib/errorshelpers so we stop re-inventing error-shape checks in each package.Docs
## ERROR MESSAGEStoCLAUDE.mdfollowing the fleet doctrine fromsocket-repo-template, tuned for the SDK library context (shorter, more terse than CLI tier — SDK callers often match on message text).docs/references/error-messages.mdwith cross-fleet worked examples, anti-patterns, and the rubric soCLAUDE.mdstays tight.joinAnd/joinOrhelpers in the doctrine.Error-helper adoption
@socketsecurity/libcatalog pin5.21 → 5.24— 5.21's/errorssubpath shipped CJS without named-export interop; 5.24 fixes it soimport { errorMessage, isError, isErrnoException } from '@socketsecurity/lib/errors'resolves cleanly under ESM.src/http-client.ts: switche instanceof Error→isError(e)ingetResponseJson's JSON-parse catch (unified narrowing against the fleet helper).src/file-upload.ts: replacee as NodeJS.ErrnoExceptionunchecked cast with theisErrnoException(e)type guard. Same ENOENT/EACCES/EISDIR branch logic, but no more unchecked assertion.Style (merged from #612, which this PR now supersedes)
catch (err)/catch (error)identifiers tocatch (e)fleet-wide.Test plan
CLAUDE.mdunder 40 KB ceiling (~14.5 KB).pnpm lintclean.pnpm test— only failure is the worktree-directory brittleness inutils.test.mts(asserts againstsocket-sdk-js/package.jsonsubstring, my worktree issocket-sdk-js-errmsg). CI runs fromsocket-sdk-jsand passes.Related