`ReactAuthWhitelabelError`

Purpose

ReactAuthWhitelabelError is the canonical error class for every error thrown by @suaveplan/react-auth-whitelabel. It extends SuaveplanError so the error participates in the project-wide error substrate (cause-chain traversal, redaction-aware wire format, OTel span-event adapter, i18n message resolver). Every instance is stamped with context.tier === "react-auth-whitelabel" so log sinks and dashboards can group white-label auth failures without inspecting error.constructor.name, which is unstable across minified bundles. Construction always carries a messageKey so the i18n resolver can localise the user-visible error string at the boundary.

Features

Type-narrowed .code of ReactAuthWhitelabelCode.
Auto-injected context.tier for log/dashboard grouping.
Carries a translation key, not a baked English string.
Compatible with SuaveplanError's cause-chain walker, wire serialiser, and OTel span-event adapter.

Usage: Basic

import { ReactAuthWhitelabelError } from "@suaveplan/react-auth-whitelabel/errors";
import { REACT_AUTH_WL_CODES } from "@suaveplan/react-auth-whitelabel/errors";

throw new ReactAuthWhitelabelError(
    REACT_AUTH_WL_CODES.PROVIDER_OUTSIDE_TREE,
    "react_auth_wl.error.provider_outside_tree",
    { context: { hook: "useAuth" } }
);

Usage: Advanced

try {
    await login(email, password);
} catch (cause) {
    throw new ReactAuthWhitelabelError(
        REACT_AUTH_WL_CODES.AUTH_NETWORK_FAILED,
        "react_auth_wl.error.network",
        { cause, context: { authUrl: config.authUrl } }
    );
}

The thrown error retains the original cause chain so monitoring sinks can correlate transport errors with the user-facing failure.

API Reference

new ReactAuthWhitelabelError(code, messageKey, options?) — constructs an error. options.context.tier is always set to "react-auth-whitelabel", even if the caller passes a different value (the helper merges, then overrides tier).
.code — ReactAuthWhitelabelCode literal.
.message — short English description sourced from messageKey (the i18n resolver substitutes a localised translation when available).

Implementation Notes

The constructor merges caller-supplied context with the canonical tier stamp. Callers must NOT pass a different tier — it will silently win at merge time, but the contract is that this package's errors are always tagged "react-auth-whitelabel".

2.5 KiB Raw Blame History

ReactAuthWhitelabelError