fix: throw SdkError for invalid arguments

[JuroUhlar]

• Throw SdkError for invalid arguments: a missing API key, eventId, visitorId, or body, an eventId or visitorId of . or .., and an unsupported region.
• Messages name the function argument (eventId is not valid: .., eventId is not set) instead of a path parameter.
• RequestError is unchanged. It still means an HTTP error response.

Discussion point: patch for a thrown-type change

Callers who catch TypeError for a missing eventId will no longer match. instanceof SdkError will. This is a patch because those values were already rejected. Push back if it should be a minor.

[changeset-bot]

🦋 Changeset detected

Latest commit: 950addc

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	98.25% (+0.03% 🔼)	168/171
🟢	Branches	97.03%	98/101
🟢	Functions	100%	37/37
🟢	Lines	98.21% (+0.02% 🔼)	165/168

Test suite run success

132 tests passing in 30 suites.

Report generated by 🧪jest coverage report action from 950addc

Show full coverage report

St	File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
🟢	All files	98.24	97.02	100	98.21
🟢	src	98.54	98.76	100	98.51
🔴	...edApiTypes.ts	0	0	0	0
🔴	index.ts	0	0	0	0
🟢	sealedResults.ts	100	100	100	100
🟢	...rApiClient.ts	96.15	97.22	100	96.15	360,364
🟢	types.ts	100	100	100	100
🟢	urlUtils.ts	100	100	100	100
🟢	webhook.ts	100	100	100	100
🟢	src/errors	97.05	90	100	96.96
🟢	apiErrors.ts	100	100	100	100
🟢	...orResponse.ts	100	100	100	100
🟢	toError.ts	87.5	88.88	100	87.5	21
🟢	unsealError.ts	100	50	100	100	14

[Copilot]

Copilot review overview

🟡 Changes recommended

Guard omitted or null options, use a minor release, and strengthen assertions to verify the SdkError class.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 2

Open (3)

• Use a minor release for the error-type API change · New
• Assert SdkError type separately from the error message · New
• Explicitly verify the thrown error is an SdkError · New

What changed in this PR

Standardizes invalid-argument failures on SdkError, updates messages, tests, documentation, and release metadata.

Changes:

• Converts validation failures to SdkError.
• Updates argument-specific messages and related tests.
• Clarifies error documentation and adds a changeset.

File	Review summary
tests/​unit-tests/​urlUtilsTests.spec.ts	Updated URL validation tests; error-class assertions should be explicit.
tests/​unit-tests/​serverApiClientTests.spec.ts	Updated client validation tests; error-class assertions should be explicit.
tests/​mocked-responses-tests/​pathParamEncodingTests.spec.ts	Updated wire-level tests; assert the SdkError class separately.
src/​urlUtils.ts	Converts URL validation failures to SdkError.
src/​serverApiClient.ts	Uses SdkError for invalid arguments; omitted or null options can still trigger native TypeError.
src/​sealedResults.ts	Clarifies thrown error documentation.
src/​errors/​unsealError.ts	Updates error documentation and cause handling.
src/​errors/​apiErrors.ts	Clarifies the error hierarchy.
readme.md	Updates public error-handling guidance.
.changeset/​sdk-error-for-invalid-arguments.md	Records the runtime error-class change; should use a minor release.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[JuroUhlar]

Omitted and null constructor options now throw SdkError. Fixed in 950addc.

[github-actions]

🚀 Following releases will be created using changesets from this PR:

@fingerprint/node-sdk@7.7.2

Patch Changes

• Throw SdkError instead of TypeError or Error for invalid API client arguments. (8f70309)