@atlasauth/js 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @atlasauth/js changelog
 
+## 0.9.0
+- **Added `reason?: string` and `meta?: Record<string, unknown>` to `FieldError`**, parsed from the Frontend API
+  error envelope (`{ code, message, reason?, param?, meta? }`). `code` is unchanged. A network failure now carries
+  the client-side reason `network`.
+- **Added `reason?: string` and `meta?: Record<string, unknown>` to `ApiKeyRequestError`** (new optional
+  constructor arguments `reason`, `meta` after `param`). `reauthenticate()` errors carry `.reason` too.
+- **New: `localizedErrorMessage(error, strings?, fallback?)`** → the text to show for a server error: the catalog
+  string `error.<reason>` (placeholders filled from `meta`), else the server's `message`, else `error.generic`,
+  else an English generic sentence — never blank. `strings` is a flat catalog or a `(key) => string | undefined`
+  lookup (a lookup that echoes the key counts as missing). `ErrorStrings` accepts any object, so an
+  `interface`-typed bundle such as `esES` from `@atlasauth/localizations` passes without a cast.
+- **New: `ERROR_REASONS`** (the 38 reasons the shipped catalogs translate), type **`ErrorReason`**,
+  **`errorReasonKey(reason)`** (`error.<reason>`), types **`ErrorLike`** and **`ErrorStrings`**, and
+  **`catalogLocale(catalog)`** (a bundle's own `locale` tag).
+- **New: `FapiClientOptions.locale?: string`** — sent as `Accept-Language` on every request so the server's
+  `message` comes back in that language; `FapiClient.locale` getter and **`acceptLanguageFor(tag)`** (normalises
+  `pt_BR` → `pt-BR`, rejects anything that is not a plain BCP-47 tag). **`ReauthOptions.locale?: string`** does the
+  same for `reauthenticate()`.
+
+
+## 0.8.0
+- **New: `SignOutGuard`** — the safer sign-out every framework provider now drives, so they all behave like
+  `@atlasauth/react`: `new SignOutGuard({ request, frontendApi?, store?, tombstones?, retryDelaysMs?,
+  frontChannelLogout? })` (`SignOutGuardOptions`). Methods: `revoke(sessionId, { frontchannel?, request? })` →
+  `SignOutAttempt` (`{ sessionId, outcome }`; finds the cookie session with `GET /v1/client` when the id is unknown,
+  tombstones it before revoking, revokes with one retry, runs front-channel logout, and re-tries a failed revoke in
+  the background after 15 s, 1 min and 5 min); `settle(attempt, { strict? })` → `SignOutResult` (throws
+  `SignOutError` under `strict`); `promoted(attempt)` → the server-promoted session id to adopt, or null;
+  `refuse(sessionId)` → whether a booted session must not be adopted (re-tries its revoke in the background and
+  removes the tombstone once it lands); `isSignedOut(id)`; `signal(attempt)` / `learn(message)` for the cross-tab
+  `{ signedOut: string[] }` message; `watch(current, onSignedOut)` (another tab signed out of this session);
+  `ready`; `dispose()`; `tombstones`. **Added types** `FapiRequest`, `SignOutGuardOptions`, `SignOutAttempt`,
+  `SignedOutSignal`.
+- **Tombstones on platforms without `localStorage`.** `SessionTombstonesOptions.store?: TombstoneStore` (new type:
+  `{ getItem(key), setItem(key, value) }`, sync or async) keeps the tombstones in the platform's own store
+  (AsyncStorage, `expo-secure-store`, `chrome.storage`, Capacitor Preferences…). **Added**
+  `SessionTombstones.ready: Promise<void>` (settles once the store has been read; immediate for `localStorage`).
+- **Email delivery.** `InstanceSettings.emailDelivery: EmailDelivery` (new type: `{ available, passwordReset,
+  passwordSignUp }`, read from `email_delivery` on `GET /v1/appearance`; all `true` on a server that does not send
+  it). **New helpers:** `emailDeliveryFrom(body)` (an environment / appearance body or the object itself),
+  `offeredFirstFactors(strategies, delivery)` (drops `email_code` / `email_link` while email can't be delivered),
+  and the constants `EMAIL_DELIVERY_UNKNOWN`, `EMAIL_UNAVAILABLE_MESSAGE`, `EMAIL_FIRST_FACTORS`.
+- **New: typed client environment.** `fetchClientEnvironment(client)` → `ClientEnvironment | null` and
+  `clientEnvironmentFrom(body)` for `GET /v1/client/environment`: `{ firstFactors, strategies, emailDelivery,
+  socialProviders }`, with the new `EnvironmentSocialProvider` type (`provider`, `native`, `mode`, `label`,
+  `display_name`, `icon`, `allow_sign_in`, `allow_sign_up`, `client_id?`, `bot_username?`).
+
 ## 0.7.0
 - **Popup OAuth completes when the opener page sends `Cross-Origin-Opener-Policy: same-origin`.** That
   header puts the provider popup in another browsing-context group: `popup.closed` reads `true` at once and

package/dist/api-keys.d.ts

@@ -62,7 +62,15 @@ export declare class ApiKeyRequestError extends Error {
     readonly code: string;
     readonly status: number;
     readonly param?: string;
-    constructor(status: number, code: string, message: string, param?: string);
+    /**
+     * The server's stable reason (`too_many_attempts`, …), when it sent one: the
+     * catalog key `error.<reason>` a UI shows instead of `message`. See
+     * `localizedErrorMessage`.
+     */
+    readonly reason?: string;
+    /** The server's `meta` detail for this error, when it sent one. */
+    readonly meta?: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, param?: string, reason?: string, meta?: Record<string, unknown>);
     /** True when the action needs a fresh re-authentication first. */
     get needsReverification(): boolean;
 }

package/dist/api-keys.js

@@ -10,12 +10,24 @@ class ApiKeyRequestError extends Error {
     code;
     status;
     param;
-    constructor(status, code, message, param) {
+    /**
+     * The server's stable reason (`too_many_attempts`, …), when it sent one: the
+     * catalog key `error.<reason>` a UI shows instead of `message`. See
+     * `localizedErrorMessage`.
+     */
+    reason;
+    /** The server's `meta` detail for this error, when it sent one. */
+    meta;
+    constructor(status, code, message, param, reason, meta) {
         super(message);
         this.name = 'ApiKeyRequestError';
         this.status = status;
         this.code = code;
         this.param = param;
+        if (reason)
+            this.reason = reason;
+        if (meta)
+            this.meta = meta;
     }
     /** True when the action needs a fresh re-authentication first. */
     get needsReverification() {
@@ -28,7 +40,7 @@ async function call(client, path, init = {}) {
     const res = await client.request(path, init);
     if (!res.ok || !res.data) {
         const first = res.errors[0];
-        throw new ApiKeyRequestError(res.status, first?.code ?? 'UNKNOWN', first?.message ?? 'The request failed.', first?.param);
+        throw new ApiKeyRequestError(res.status, first?.code ?? 'UNKNOWN', first?.message ?? 'The request failed.', first?.param, first?.reason, first?.meta);
     }
     return res.data;
 }

package/dist/api-keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-keys.js","sourceRoot":"","sources":["../src/api-keys.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-keys.js","sourceRoot":"","sources":["../src/api-keys.ts"],"names":[],"mappings":"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"}

package/dist/attempt.d.ts

@@ -78,6 +78,19 @@ export interface FieldError {
     code: string;
     message: string;
     param?: string;
+    /**
+     * The server's stable, machine-readable reason for this error
+     * (`form_password_incorrect`, `too_many_attempts`, …), finer-grained than
+     * `code`. Prebuilt UIs look it up as the catalog key `error.<reason>` to show
+     * the message in the app's language; see `localizedErrorMessage`. Absent on
+     * servers that predate it and on errors raised client-side.
+     */
+    reason?: string;
+    /**
+     * Extra machine-readable detail the server attached (`min_length`,
+     * `providers`, …); also the interpolation values for `error.<reason>`.
+     */
+    meta?: Record<string, unknown>;
 }
 export declare function fieldErrors(body: unknown): FieldError[];
 /** Errors for one field, so a form can render them inline. */

package/dist/attempt.js

@@ -76,7 +76,16 @@ function fieldErrors(body) {
         .filter((error) => {
         return Boolean(error) && typeof error.message === 'string';
     })
-        .map((error) => ({ code: error.code, message: error.message, param: error.param }));
+        .map((error) => {
+        const out = { code: error.code, message: error.message, param: error.param };
+        const reason = error.reason;
+        if (typeof reason === 'string' && reason !== '')
+            out.reason = reason;
+        const meta = error.meta;
+        if (meta && typeof meta === 'object' && !Array.isArray(meta))
+            out.meta = meta;
+        return out;
+    });
 }
 /** Errors for one field, so a form can render them inline. */
 function errorsFor(errors, param) {

package/dist/attempt.js.map

@@ -1 +1 @@
-{"version":3,"file":"attempt.js","sourceRoot":"","sources":["../src/attempt.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAkDH,4BAqDC;AAGD,gCAEC;AAgBD,kCAUC;AAGD,8BAEC;AAGD,gCAEC;AA9FD,SAAgB,QAAQ,CAAC,OAAoB;IAC3C,QAAQ,OAAO,CAAC,MAAuB,EAAE,CAAC;QACxC,KAAK,kBAAkB;YACrB,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QAExC,KAAK,oBAAoB;YACvB,OAAO;gBACL,IAAI,EAAE,sBAAsB;gBAC5B,sEAAsE;gBACtE,qEAAqE;gBACrE,uEAAuE;gBACvE,wCAAwC;gBACxC,UAAU,EAAE,OAAO,CAAC,uBAAuB,IAAI,EAAE;aAClD,CAAC;QAEJ,KAAK,qBAAqB;YACxB,OAAO,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;QAE3C;;;;;WAKG;QACH,KAAK,sBAAsB;YACzB,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;QAE1C,KAAK,0BAA0B;YAC7B,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QAExC,KAAK,eAAe;YAClB,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;QAErC,KAAK,sBAAsB;YACzB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;QAEjC,KAAK,oBAAoB;YACvB,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;QAE1C,KAAK,UAAU;YACb,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,kBAAkB,IAAI,IAAI,EAAE,CAAC;QAEzE,KAAK,WAAW;YACd,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAElD;YACE;;;;eAIG;YACH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IACvD,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,SAAgB,UAAU,CAAC,OAAoB;IAC7C,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,CAAC;AACzE,CAAC;AAgBD,SAAgB,WAAW,CAAC,IAAa;IACvC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACjD,MAAM,MAAM,GAAI,IAA6B,CAAC,MAAM,CAAC;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IAEtC,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,KAAK,EAAuB,EAAE;QACrC,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,OAAQ,KAAoB,CAAC,OAAO,KAAK,QAAQ,CAAC;IAC7E,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,8DAA8D;AAC9D,SAAgB,SAAS,CAAC,MAA6B,EAAE,KAAa;IACpE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;AACzD,CAAC;AAED,iEAAiE;AACjE,SAAgB,UAAU,CAAC,MAA6B;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"attempt.js","sourceRoot":"","sources":["../src/attempt.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAkDH,4BAqDC;AAGD,gCAEC;AA6BD,kCAiBC;AAGD,8BAEC;AAGD,gCAEC;AAlHD,SAAgB,QAAQ,CAAC,OAAoB;IAC3C,QAAQ,OAAO,CAAC,MAAuB,EAAE,CAAC;QACxC,KAAK,kBAAkB;YACrB,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QAExC,KAAK,oBAAoB;YACvB,OAAO;gBACL,IAAI,EAAE,sBAAsB;gBAC5B,sEAAsE;gBACtE,qEAAqE;gBACrE,uEAAuE;gBACvE,wCAAwC;gBACxC,UAAU,EAAE,OAAO,CAAC,uBAAuB,IAAI,EAAE;aAClD,CAAC;QAEJ,KAAK,qBAAqB;YACxB,OAAO,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;QAE3C;;;;;WAKG;QACH,KAAK,sBAAsB;YACzB,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;QAE1C,KAAK,0BAA0B;YAC7B,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QAExC,KAAK,eAAe;YAClB,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;QAErC,KAAK,sBAAsB;YACzB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;QAEjC,KAAK,oBAAoB;YACvB,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;QAE1C,KAAK,UAAU;YACb,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,kBAAkB,IAAI,IAAI,EAAE,CAAC;QAEzE,KAAK,WAAW;YACd,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAElD;YACE;;;;eAIG;YACH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IACvD,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,SAAgB,UAAU,CAAC,OAAoB;IAC7C,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,CAAC;AACzE,CAAC;AA6BD,SAAgB,WAAW,CAAC,IAAa;IACvC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACjD,MAAM,MAAM,GAAI,IAA6B,CAAC,MAAM,CAAC;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IAEtC,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,KAAK,EAAuB,EAAE;QACrC,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,OAAQ,KAAoB,CAAC,OAAO,KAAK,QAAQ,CAAC;IAC7E,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,GAAG,GAAe,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QACzF,MAAM,MAAM,GAAI,KAA8B,CAAC,MAAM,CAAC;QACtD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,EAAE;YAAE,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;QACrE,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAC;QAChD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,GAAG,IAA+B,CAAC;QACzG,OAAO,GAAG,CAAC;IACb,CAAC,CAAC,CAAC;AACP,CAAC;AAED,8DAA8D;AAC9D,SAAgB,SAAS,CAAC,MAA6B,EAAE,KAAa;IACpE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;AACzD,CAAC;AAED,iEAAiE;AACjE,SAAgB,UAAU,CAAC,MAA6B;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/dist/environment.d.ts

@@ -0,0 +1,79 @@
+import type { FapiClient } from './fapi';
+/**
+ * The client environment (`GET /v1/client/environment`) and the email-delivery
+ * facts both it and `GET /v1/appearance` publish.
+ *
+ * An app that cannot deliver email (a production instance with no email
+ * provider) cannot send a reset code, an email sign-in code or link, or a
+ * sign-up verification code. The server already stops offering email code / link
+ * and refuses those requests; `email_delivery` lets a sign-in UI say so up front
+ * instead: hide "Forgot password?" and email-code options, and show a "can't
+ * send email" state where a sign-up would need one.
+ */
+/** `email_delivery`: what works given whether the app can deliver email. */
+export interface EmailDelivery {
+    /** The app can send email (its own provider, or the shared development sender). */
+    available: boolean;
+    /** "Forgot password?" can work: password sign-in is on and reset emails can be delivered. */
+    passwordReset: boolean;
+    /** Email + password sign-up can complete (email can be delivered, or verification is not required). */
+    passwordSignUp: boolean;
+}
+/**
+ * What an older server (no `email_delivery`) is taken to mean: everything works.
+ * The server still refuses whatever it cannot deliver.
+ */
+export declare const EMAIL_DELIVERY_UNKNOWN: Readonly<EmailDelivery>;
+/** The default English copy for the "can't send email" state. */
+export declare const EMAIL_UNAVAILABLE_MESSAGE = "This app can't send email right now. Try another sign-in method or contact the app owner.";
+/** The first factors that need the app to deliver email. */
+export declare const EMAIL_FIRST_FACTORS: readonly string[];
+/**
+ * Read `email_delivery` from a `/v1/client/environment` or `/v1/appearance`
+ * body — or from the `email_delivery` object itself. A missing object or field
+ * reads as available (see {@link EMAIL_DELIVERY_UNKNOWN}).
+ */
+export declare function emailDeliveryFrom(body: unknown): EmailDelivery;
+/**
+ * The first factors a sign-in UI should offer: `strategies` without email code /
+ * link while the app cannot deliver email. A capability of the app, not of the
+ * user, so it never narrows the server's uniform list per identifier. With no
+ * `delivery` (not loaded yet) the list is returned unchanged.
+ */
+export declare function offeredFirstFactors(strategies: readonly string[], delivery: EmailDelivery | null | undefined): string[];
+/** One entry of the environment's `social_providers`. */
+export interface EnvironmentSocialProvider {
+    provider: string;
+    /** Whether the provider signs in natively (One Tap etc.) on this instance. */
+    native: boolean;
+    mode: 'native' | 'redirect';
+    /** The full button text, or null for the SDK's own label. */
+    label: string | null;
+    display_name: string | null;
+    icon: {
+        type: 'url' | 'svg';
+        value: string;
+    } | null;
+    allow_sign_in: boolean;
+    allow_sign_up: boolean;
+    /** Public client id, for native providers only. */
+    client_id?: string;
+    /** Telegram's bot username. */
+    bot_username?: string;
+}
+/** `GET /v1/client/environment`, typed. */
+export interface ClientEnvironment {
+    /** The enabled first factors (`password`, `email_code`, `passkey`, …). */
+    firstFactors: string[];
+    /**
+     * The offered strategies, camelCase as the server sends them (`password`,
+     * `emailCode`, `emailLink`, `passkey`, `phoneCode`, …, `oauthProviders`).
+     */
+    strategies: Record<string, unknown>;
+    emailDelivery: EmailDelivery;
+    socialProviders: EnvironmentSocialProvider[];
+}
+/** Read a `/v1/client/environment` body. Defensive: malformed parts read as empty. */
+export declare function clientEnvironmentFrom(body: unknown): ClientEnvironment;
+/** Fetch the client environment. Null when the server can't be reached or errors. */
+export declare function fetchClientEnvironment(client: FapiClient): Promise<ClientEnvironment | null>;

package/dist/environment.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMAIL_FIRST_FACTORS = exports.EMAIL_UNAVAILABLE_MESSAGE = exports.EMAIL_DELIVERY_UNKNOWN = void 0;
+exports.emailDeliveryFrom = emailDeliveryFrom;
+exports.offeredFirstFactors = offeredFirstFactors;
+exports.clientEnvironmentFrom = clientEnvironmentFrom;
+exports.fetchClientEnvironment = fetchClientEnvironment;
+/**
+ * What an older server (no `email_delivery`) is taken to mean: everything works.
+ * The server still refuses whatever it cannot deliver.
+ */
+exports.EMAIL_DELIVERY_UNKNOWN = Object.freeze({
+    available: true,
+    passwordReset: true,
+    passwordSignUp: true,
+});
+/** The default English copy for the "can't send email" state. */
+exports.EMAIL_UNAVAILABLE_MESSAGE = "This app can't send email right now. Try another sign-in method or contact the app owner.";
+/** The first factors that need the app to deliver email. */
+exports.EMAIL_FIRST_FACTORS = ['email_code', 'email_link'];
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/**
+ * Read `email_delivery` from a `/v1/client/environment` or `/v1/appearance`
+ * body — or from the `email_delivery` object itself. A missing object or field
+ * reads as available (see {@link EMAIL_DELIVERY_UNKNOWN}).
+ */
+function emailDeliveryFrom(body) {
+    const raw = isRecord(body) && isRecord(body.email_delivery) ? body.email_delivery : body;
+    if (!isRecord(raw) || !('available' in raw || 'password_reset' in raw || 'password_sign_up' in raw)) {
+        return { ...exports.EMAIL_DELIVERY_UNKNOWN };
+    }
+    const flag = (v) => (typeof v === 'boolean' ? v : true);
+    return {
+        available: flag(raw.available),
+        passwordReset: flag(raw.password_reset),
+        passwordSignUp: flag(raw.password_sign_up),
+    };
+}
+/**
+ * The first factors a sign-in UI should offer: `strategies` without email code /
+ * link while the app cannot deliver email. A capability of the app, not of the
+ * user, so it never narrows the server's uniform list per identifier. With no
+ * `delivery` (not loaded yet) the list is returned unchanged.
+ */
+function offeredFirstFactors(strategies, delivery) {
+    if (!delivery || delivery.available)
+        return [...strategies];
+    return strategies.filter((s) => !exports.EMAIL_FIRST_FACTORS.includes(s));
+}
+/** Read a `/v1/client/environment` body. Defensive: malformed parts read as empty. */
+function clientEnvironmentFrom(body) {
+    const root = isRecord(body) ? body : {};
+    return {
+        firstFactors: Array.isArray(root.first_factors)
+            ? root.first_factors.filter((f) => typeof f === 'string')
+            : [],
+        strategies: isRecord(root.strategies) ? { ...root.strategies } : {},
+        emailDelivery: emailDeliveryFrom(root),
+        socialProviders: Array.isArray(root.social_providers)
+            ? root.social_providers.filter((p) => isRecord(p) && typeof p.provider === 'string')
+            : [],
+    };
+}
+/** Fetch the client environment. Null when the server can't be reached or errors. */
+async function fetchClientEnvironment(client) {
+    try {
+        const response = await client.get('/v1/client/environment');
+        return response.ok ? clientEnvironmentFrom(response.data) : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=environment.js.map

package/dist/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Server errors in the app's language.
+ *
+ * A Frontend API error carries a human `message` (in English unless the request
+ * sent an `Accept-Language` the server has strings for) and, on current
+ * servers, a stable `reason` such as `form_password_incorrect`. A prebuilt form
+ * looks the reason up as the catalog key `error.<reason>`, so a Spanish form
+ * shows a Spanish sentence even when the server answered in English, and an
+ * app can reword any error by overriding that one key.
+ */
+/**
+ * The reasons the Frontend API sends that every shipped catalog translates, as
+ * `error.<reason>` keys. Listed for docs and coverage checks; a reason missing
+ * from this list still renders (as the server's `message`).
+ */
+export declare const ERROR_REASONS: readonly ["form_password_incorrect", "form_code_incorrect", "form_code_already_used", "form_code_expired", "form_code_max_attempts", "form_link_invalid", "form_identifier_not_found", "form_identifier_exists", "form_password_pwned", "form_password_too_short", "form_password_too_long", "form_password_requires_uppercase", "form_password_requires_lowercase", "form_password_requires_number", "form_password_requires_symbol", "form_password_not_allowed", "form_password_contains_identifier", "form_password_same_as_current", "form_password_reused", "password_expired", "email_not_verified", "sign_in_token_invalid", "too_many_attempts", "too_many_requests", "captcha_required", "captcha_failed", "captcha_unavailable", "email_delivery_unavailable", "strategy_disabled", "sign_up_restricted", "waitlisted", "identifier_not_allowed", "disposable_email_blocked", "sso_required", "sign_ins_disabled", "sign_ups_disabled", "high_risk_blocked", "sms_region_blocked"];
+/** A reason with a string in every shipped catalog. */
+export type ErrorReason = (typeof ERROR_REASONS)[number];
+/** The catalog key for a reason: `error.<reason>`. */
+export declare function errorReasonKey(reason: string): string;
+/**
+ * What {@link localizedErrorMessage} reads strings from: a flat catalog object
+ * (`{ 'error.too_many_attempts': '…' }`, or a bundle such as `esES` from
+ * `@atlasauth/localizations`) or a lookup function. A function may answer a
+ * missing key with `undefined`, `null`, `''` or the key itself (the convention
+ * of the prebuilt UIs' `translate`); all four count as "no string". Typed as
+ * `object` so an `interface`-typed bundle is accepted without a cast.
+ */
+export type ErrorStrings = ((key: string) => string | null | undefined) | object;
+/** Anything error-shaped: a `FieldError`, an `ApiKeyRequestError`, an `Error`, a server error object. */
+export interface ErrorLike {
+    reason?: string | null;
+    message?: string | null;
+    code?: string | null;
+    /** Interpolation values for the catalog string (`{min_length}` ← `meta.min_length`). */
+    meta?: Readonly<Record<string, unknown>> | null;
+}
+/**
+ * The message to show for a server error, in the app's language:
+ *
+ * 1. the catalog string `error.<reason>`, when the error has a reason and
+ *    `strings` has that key, with `{placeholders}` filled from the error's
+ *    `meta` (a placeholder `meta` cannot fill skips to step 2);
+ * 2. else the server's `message` (localised by the server when the client sent
+ *    `Accept-Language` — see `FapiClientOptions.locale`);
+ * 3. else the catalog's `error.generic`, else an English generic sentence.
+ *
+ * Never returns an empty string. `fallback`, when given, is consulted for
+ * `error.generic` after `strings` — handy when `strings` is a language layer
+ * without the English defaults underneath it.
+ */
+export declare function localizedErrorMessage(error: ErrorLike | string | null | undefined, strings?: ErrorStrings | null, fallback?: ErrorStrings | null): string;
+/**
+ * The BCP-47 tag a catalog declares for itself (`@atlasauth/localizations`
+ * bundles carry `locale: 'es-ES'`), or undefined. Prebuilt UIs that take a
+ * `localization` bundle use it as the `Accept-Language` they send.
+ */
+export declare function catalogLocale(catalog: object | null | undefined): string | undefined;

package/dist/errors.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Server errors in the app's language.
+ *
+ * A Frontend API error carries a human `message` (in English unless the request
+ * sent an `Accept-Language` the server has strings for) and, on current
+ * servers, a stable `reason` such as `form_password_incorrect`. A prebuilt form
+ * looks the reason up as the catalog key `error.<reason>`, so a Spanish form
+ * shows a Spanish sentence even when the server answered in English, and an
+ * app can reword any error by overriding that one key.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_REASONS = void 0;
+exports.errorReasonKey = errorReasonKey;
+exports.localizedErrorMessage = localizedErrorMessage;
+exports.catalogLocale = catalogLocale;
+/**
+ * The reasons the Frontend API sends that every shipped catalog translates, as
+ * `error.<reason>` keys. Listed for docs and coverage checks; a reason missing
+ * from this list still renders (as the server's `message`).
+ */
+exports.ERROR_REASONS = Object.freeze([
+    'form_password_incorrect',
+    'form_code_incorrect',
+    'form_code_already_used',
+    'form_code_expired',
+    'form_code_max_attempts',
+    'form_link_invalid',
+    'form_identifier_not_found',
+    'form_identifier_exists',
+    'form_password_pwned',
+    'form_password_too_short',
+    'form_password_too_long',
+    'form_password_requires_uppercase',
+    'form_password_requires_lowercase',
+    'form_password_requires_number',
+    'form_password_requires_symbol',
+    'form_password_not_allowed',
+    'form_password_contains_identifier',
+    'form_password_same_as_current',
+    'form_password_reused',
+    'password_expired',
+    'email_not_verified',
+    'sign_in_token_invalid',
+    'too_many_attempts',
+    'too_many_requests',
+    'captcha_required',
+    'captcha_failed',
+    'captcha_unavailable',
+    'email_delivery_unavailable',
+    'strategy_disabled',
+    'sign_up_restricted',
+    'waitlisted',
+    'identifier_not_allowed',
+    'disposable_email_blocked',
+    'sso_required',
+    'sign_ins_disabled',
+    'sign_ups_disabled',
+    'high_risk_blocked',
+    'sms_region_blocked',
+]);
+/** The catalog key for a reason: `error.<reason>`. */
+function errorReasonKey(reason) {
+    return `error.${reason}`;
+}
+/** The English fallback of last resort, so the result is never blank. */
+const GENERIC_ERROR = 'Something went wrong. Please try again.';
+/** A reason is a lower-case token; anything else is never used as a key. */
+const REASON = /^[a-z][a-z0-9_]{0,63}$/;
+/**
+ * Fill `{name}` from `meta` (string or finite-number values). Null when a
+ * placeholder has no usable value: a sentence with a hole in it is worse than
+ * the server's own message, which the server has already filled.
+ */
+function interpolate(template, meta) {
+    let complete = true;
+    const text = template.replace(/\{(\w+)\}/g, (match, name) => {
+        const value = meta && Object.prototype.hasOwnProperty.call(meta, name) ? meta[name] : undefined;
+        if (typeof value === 'string' && value !== '')
+            return value;
+        if (typeof value === 'number' && Number.isFinite(value))
+            return String(value);
+        complete = false;
+        return match;
+    });
+    return complete ? text : null;
+}
+function lookup(strings, key) {
+    if (!strings)
+        return null;
+    let value;
+    if (typeof strings === 'function') {
+        value = strings(key);
+    }
+    else {
+        value = Object.prototype.hasOwnProperty.call(strings, key)
+            ? strings[key]
+            : undefined;
+    }
+    if (typeof value !== 'string')
+        return null;
+    const text = value.trim();
+    return text === '' || text === key ? null : value;
+}
+/**
+ * The message to show for a server error, in the app's language:
+ *
+ * 1. the catalog string `error.<reason>`, when the error has a reason and
+ *    `strings` has that key, with `{placeholders}` filled from the error's
+ *    `meta` (a placeholder `meta` cannot fill skips to step 2);
+ * 2. else the server's `message` (localised by the server when the client sent
+ *    `Accept-Language` — see `FapiClientOptions.locale`);
+ * 3. else the catalog's `error.generic`, else an English generic sentence.
+ *
+ * Never returns an empty string. `fallback`, when given, is consulted for
+ * `error.generic` after `strings` — handy when `strings` is a language layer
+ * without the English defaults underneath it.
+ */
+function localizedErrorMessage(error, strings, fallback) {
+    const err = typeof error === 'string' ? { message: error } : (error ?? {});
+    const reason = typeof err.reason === 'string' ? err.reason : '';
+    if (reason && REASON.test(reason)) {
+        const template = lookup(strings, errorReasonKey(reason));
+        const text = template ? interpolate(template, err.meta) : null;
+        if (text)
+            return text;
+    }
+    if (typeof err.message === 'string' && err.message.trim() !== '')
+        return err.message;
+    return lookup(strings, 'error.generic') ?? lookup(fallback, 'error.generic') ?? GENERIC_ERROR;
+}
+/**
+ * The BCP-47 tag a catalog declares for itself (`@atlasauth/localizations`
+ * bundles carry `locale: 'es-ES'`), or undefined. Prebuilt UIs that take a
+ * `localization` bundle use it as the `Accept-Language` they send.
+ */
+function catalogLocale(catalog) {
+    if (!catalog || typeof catalog !== 'object')
+        return undefined;
+    const tag = catalog.locale;
+    return typeof tag === 'string' && tag.trim() !== '' ? tag : undefined;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/fapi.d.ts

@@ -18,7 +18,22 @@ export interface FapiClientOptions {
     /** The instance's FAPI origin. Empty for same-origin. */
     baseUrl?: string;
     fetchImpl?: typeof fetch;
+    /**
+     * The app's UI language as a BCP-47 tag (`"es"`, `"pt-BR"`). When set, every
+     * request carries it as `Accept-Language`, so the server writes its error
+     * `message`s in that language — the fallback a prebuilt form shows for an
+     * error whose `reason` its catalog has no string for. Unset sends no header
+     * (the browser's own `Accept-Language` applies). A malformed tag is ignored.
+     */
+    locale?: string;
 }
+/**
+ * A locale tag normalised for the `Accept-Language` header (`pt_BR` → `pt-BR`),
+ * or null when it is not a plausible BCP-47 tag. Restricting it to letters,
+ * digits and hyphens keeps the header CORS-safelisted, so sending it never adds
+ * a preflight to a cross-origin Frontend API call.
+ */
+export declare function acceptLanguageFor(locale: string | null | undefined): string | null;
 export interface FapiResponse<T> {
     ok: boolean;
     status: number;
@@ -28,6 +43,8 @@ export interface FapiResponse<T> {
 export declare class FapiClient {
     private readonly options;
     constructor(options: FapiClientOptions);
+    /** The `Accept-Language` this client sends, or null when it sends none. */
+    get locale(): string | null;
     /**
      * The origin FAPI serves from — where an OAuth popup's callback page lives, so
      * the popup flow can pin `postMessage`'s `event.origin` to it. Empty `baseUrl`

package/dist/fapi.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initialFlow = exports.FapiClient = void 0;
+exports.acceptLanguageFor = acceptLanguageFor;
 exports.getProviderToken = getProviderToken;
 exports.requestForStep = requestForStep;
 exports.flowFromPending = flowFromPending;
@@ -10,11 +11,27 @@ exports.prepareFactor = prepareFactor;
 exports.pollAttempt = pollAttempt;
 exports.shouldKeepPolling = shouldKeepPolling;
 const attempt_1 = require("./attempt");
+/**
+ * A locale tag normalised for the `Accept-Language` header (`pt_BR` → `pt-BR`),
+ * or null when it is not a plausible BCP-47 tag. Restricting it to letters,
+ * digits and hyphens keeps the header CORS-safelisted, so sending it never adds
+ * a preflight to a cross-origin Frontend API call.
+ */
+function acceptLanguageFor(locale) {
+    if (typeof locale !== 'string')
+        return null;
+    const tag = locale.trim().replace(/_/g, '-');
+    return /^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/.test(tag) ? tag : null;
+}
 class FapiClient {
     options;
     constructor(options) {
         this.options = options;
     }
+    /** The `Accept-Language` this client sends, or null when it sends none. */
+    get locale() {
+        return acceptLanguageFor(this.options.locale);
+    }
     /**
      * The origin FAPI serves from — where an OAuth popup's callback page lives, so
      * the popup flow can pin `postMessage`'s `event.origin` to it. Empty `baseUrl`
@@ -33,6 +50,7 @@ class FapiClient {
     }
     async request(path, init = {}) {
         const doFetch = this.options.fetchImpl ?? fetch;
+        const language = this.locale;
         let response;
         try {
             response = await doFetch(`${this.options.baseUrl ?? ''}${path}`, {
@@ -42,6 +60,7 @@ class FapiClient {
                 credentials: 'include',
                 headers: {
                     'x-publishable-key': this.options.publishableKey,
+                    ...(language ? { 'accept-language': language } : {}),
                     ...(init.body ? { 'content-type': 'application/json' } : {}),
                     ...init.headers,
                 },
@@ -57,7 +76,7 @@ class FapiClient {
                 ok: false,
                 status: 0,
                 data: null,
-                errors: [{ code: 'NETWORK', message: 'We could not reach the server.' }],
+                errors: [{ code: 'NETWORK', reason: 'network', message: 'We could not reach the server.' }],
             };
         }
         let body = null;