@streamoid/errors

Zero-dependency, browser-safe public error normalization. This package never retries a request. Apps supply operation context and decide which supported recovery action to render.

import { responseError, UserFacingError, isCancellation } from '@streamoid/errors';
let response;
try { response = await fetch(url, options); }
catch (cause) {
  if (isCancellation(cause)) throw cause;
  throw new UserFacingError(cause, { method: options.method });
}
if (!response.ok) throw await responseError(response, { method: options.method });

Existing envelopes remain valid. Services may add publicError: { version: 1, code, message, recovery, operation, safeToRetry, reference }. Only this deliberately public envelope can supply bespoke text; raw exception messages, HTML and provider responses are diagnostic-only. Field validation paths are retained without echoing submitted values. Keep the original cause in protected diagnostics.

Use normalizeError(error) for persistent UI and errorMessage(error) for existing string interfaces (includes a support reference). Pass the request method when known. A missing method is treated conservatively as an unknown write, rather than assuming a read. Never infer retry safety from a 5xx status. Writes with unknown outcomes retain safe authored context and append guidance to check status; only a durable failed/not-started state plus explicit retry safety permits repeat submission. fieldErrors paths must be mapped to visible form labels. Pass intentional cancellation through unchanged and do not display it.

Run npm test --workspace @streamoid/errors. Publish through the repository's reviewed package release workflow, then update consumers; never commit local file dependencies.