@nulvless/nulvless-js 0.1.0

package/dist/index.mjs

@@ -0,0 +1,2529 @@
+// src/exceptions/nulvless.exception.ts
+var NulvlessException = class extends Error {
+  code;
+  status_code;
+  constructor(message, code, status_code) {
+    super(Array.isArray(message) ? message.join(", ") : message);
+    this.name = "NulvlessException";
+    this.code = code;
+    this.status_code = status_code;
+  }
+};
+
+// src/http.ts
+var DOT_SEGMENT = /(^|\/)\.{1,2}(\/|$)/;
+function resolveConfigHeaders(value) {
+  return typeof value === "function" ? value() : value;
+}
+function mergeHeaders(...sources) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    for (const [name, value] of Object.entries(source ?? {})) {
+      merged.set(name.toLowerCase(), [name, value]);
+    }
+  }
+  return Object.fromEntries(merged.values());
+}
+function findHeader(headers, name) {
+  const wanted = name.toLowerCase();
+  return Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === wanted)?.[1];
+}
+function route(strings, ...values) {
+  return strings.reduce((path, part, index) => path + encodeURIComponent(String(values[index - 1])) + part);
+}
+var InvalidPathError = class extends Error {
+  constructor(path) {
+    super(`Path parameters cannot be "." or "..": ${path}`);
+    this.name = "InvalidPathError";
+  }
+};
+function toError(err, timeout) {
+  if (err instanceof InvalidPathError) {
+    return { code: "invalid_path", message: err.message, status_code: 400 };
+  }
+  if (err instanceof Error && err.name === "AbortError") {
+    return {
+      code: "request_timeout",
+      message: `Request timed out after ${timeout ?? 0}ms`,
+      status_code: 408
+    };
+  }
+  return {
+    code: "network_error",
+    message: err instanceof Error ? err.message : "Network request failed",
+    status_code: 0
+  };
+}
+function extractErrorPayload(body, fallback) {
+  if (typeof body !== "object" || body === null) {
+    return { code: "unknown_error", message: fallback };
+  }
+  const record = body;
+  const code = typeof record["code"] === "string" ? record["code"] : "unknown_error";
+  const message = typeof record["message"] === "string" || Array.isArray(record["message"]) ? record["message"] : fallback;
+  return { code, message };
+}
+var HttpClient = class {
+  config;
+  onSudoRequired;
+  constructor(config) {
+    this.config = {
+      ...config,
+      baseUrl: config.baseUrl.replace(/\/+$/, "")
+    };
+  }
+  /**
+   * Injected after construction to avoid circular dependency.
+   * Called when a request fails with `403 protected_action_denied`,
+   * indicating the user must enable sudo mode before retrying.
+   */
+  setOnSudoRequired(cb) {
+    this.onSudoRequired = cb;
+  }
+  hasAuthorization(headers) {
+    return findHeader(headers, "Authorization") !== void 0 || findHeader(resolveConfigHeaders(this.config.headers), "Authorization") !== void 0;
+  }
+  async get(path, options) {
+    return this.send("GET", path, options);
+  }
+  async post(path, body, options) {
+    return this.send("POST", path, { ...options, body });
+  }
+  async put(path, body, options) {
+    return this.send("PUT", path, { ...options, body });
+  }
+  async patch(path, body, options) {
+    return this.send("PATCH", path, { ...options, body });
+  }
+  async delete(path, options) {
+    return this.send("DELETE", path, options);
+  }
+  /**
+   * Returns `true` when the error warrants a single token-refresh retry:
+   * - Any 401 on an authenticated request
+   * - 403 with `forbidden_access_waiting_accept` or `forbidden_resource_access` codes
+   */
+  shouldRetryWithRefresh(status, code, headers) {
+    if (!findHeader(headers, "Authorization")) return false;
+    if (status === 401) return true;
+    if (status === 403 && ["forbidden_resource_access", "forbidden_access_waiting_accept"].includes(code)) return true;
+    return false;
+  }
+  async send(method, path, options = {}, isRetry = false) {
+    const headers = this.buildHeaders(options.headers, options.language, options.nonce, options.skipApiKey);
+    const shouldThrow = options.throwErrors ?? this.config.throwErrors ?? false;
+    const timeout = options.timeout ?? this.config.timeout;
+    const controller = new AbortController();
+    const timeoutHandle = timeout && timeout > 0 ? setTimeout(() => controller.abort(), timeout) : void 0;
+    const start = Date.now();
+    if (this.config.debug) {
+      console.debug(`[nulvless] \u2192 ${method} ${path}`);
+    }
+    try {
+      const url = this.buildUrl(path, options.query);
+      const init = { method, headers, signal: controller.signal };
+      if (options.body !== void 0) {
+        const contentType = findHeader(headers, "Content-Type");
+        if (contentType === "application/x-www-form-urlencoded") {
+          init.body = new URLSearchParams(options.body).toString();
+        } else {
+          init.body = JSON.stringify(options.body);
+        }
+      }
+      const response = await fetch(url, init);
+      const body = await this.parseBody(response);
+      if (this.config.debug) {
+        console.debug(`[nulvless] \u2190 ${method} ${path} ${response.status} (${Date.now() - start}ms)`);
+      }
+      if (!response.ok) {
+        const { code, message } = extractErrorPayload(body, response.statusText);
+        const error = { code, message, status_code: response.status };
+        if (!isRetry && this.config.onTokenExpired && this.shouldRetryWithRefresh(response.status, code, headers)) {
+          const deauthOnFailure = response.status === 401;
+          const expiredToken = findHeader(headers, "Authorization")?.replace(/^Bearer\s+/i, "");
+          const newToken = await this.config.onTokenExpired({
+            deauthOnFailure,
+            ...expiredToken ? { expiredToken } : {}
+          });
+          if (newToken) {
+            return this.send(
+              method,
+              path,
+              { ...options, headers: mergeHeaders(options.headers, { Authorization: `Bearer ${newToken}` }) },
+              true
+            );
+          }
+        }
+        if (response.status === 403 && code === "protected_action_denied") {
+          this.onSudoRequired?.();
+        }
+        if (shouldThrow) {
+          throw new NulvlessException(message, code, response.status);
+        }
+        return { data: null, error };
+      }
+      return { data: body, error: null };
+    } catch (err) {
+      if (err instanceof NulvlessException) throw err;
+      const error = toError(err, timeout);
+      if (shouldThrow) {
+        throw new NulvlessException(error.message, error.code, error.status_code);
+      }
+      return { data: null, error };
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+  buildUrl(path, query) {
+    if (DOT_SEGMENT.test(path)) throw new InvalidPathError(path);
+    const url = new URL(`${this.config.baseUrl}/${path.replace(/^\/+/, "")}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === void 0) continue;
+        const values = Array.isArray(value) ? value : [value];
+        for (const v of values) {
+          url.searchParams.append(Array.isArray(value) ? `${key}[]` : key, String(v));
+        }
+      }
+    }
+    return url.toString();
+  }
+  buildHeaders(extra, languageOverride, nonce, skipApiKey) {
+    const language = languageOverride?.() ?? this.config.language?.() ?? "en-US";
+    return mergeHeaders(
+      {
+        "Content-Type": "application/json",
+        ...skipApiKey ? {} : { "x-platform-key": this.config.apiKey },
+        "nlv-lang": language,
+        ...this.config.trackUser !== void 0 ? { "nlv-user-tracking": String(this.config.trackUser) } : {},
+        ...nonce ? { "nlv-sudo-nonce": nonce } : {}
+      },
+      resolveConfigHeaders(this.config.headers),
+      extra
+    );
+  }
+  async parseBody(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("json")) return null;
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/session/tabChannel.ts
+var TabChannel = class {
+  channel;
+  constructor(name, onMessage) {
+    const Ctor = globalThis.BroadcastChannel;
+    if (!Ctor) {
+      this.channel = null;
+      return;
+    }
+    try {
+      this.channel = new Ctor(name);
+    } catch {
+      this.channel = null;
+      return;
+    }
+    this.channel.addEventListener("message", (event) => {
+      onMessage(event.data);
+    });
+    this.channel.unref?.();
+  }
+  post(message) {
+    try {
+      this.channel?.postMessage(message);
+    } catch {
+      this.channel = null;
+    }
+  }
+  close() {
+    this.channel?.close();
+  }
+};
+
+// src/auth/base.ts
+var NO_SESSION_ERROR = {
+  code: "no_session",
+  message: "No active session.",
+  status_code: 401
+};
+async function resolveBearer(http, getToken, options) {
+  if (http.hasAuthorization(options?.headers)) return { ok: true, headers: {} };
+  const token = await getToken();
+  if (!token) return { ok: false, error: { ...NO_SESSION_ERROR } };
+  return { ok: true, headers: { Authorization: `Bearer ${token}` } };
+}
+var AuthSubClient = class {
+  constructor(http, getToken) {
+    this.http = http;
+    this.getToken = getToken;
+  }
+  http;
+  getToken;
+  bearer(options) {
+    return resolveBearer(this.http, this.getToken, options);
+  }
+};
+
+// src/auth/factors/index.ts
+var FactorsClient = class extends AuthSubClient {
+  /**
+   * Lists all configured MFA factors for the authenticated user.
+   */
+  async list(options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/factors", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Returns the user's recovery codes.
+   *
+   * Requires sudo: `MANAGE_MFA`.
+   */
+  async getRecoveryCodes(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/factors/codes", {
+      ...options,
+      nonce: params?.nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Deletes (invalidates) the user's recovery codes.
+   *
+   * Requires sudo: `MANAGE_MFA`.
+   */
+  async deleteRecoveryCodes(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.delete("/factors/codes", {
+      ...options,
+      nonce: params?.nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Begins enrolling a new MFA factor. Returns credentials needed to configure
+   * the factor on the user's device.
+   *
+   * For TOTP: use `secret` for manual entry or `url` to generate a QR code.
+   *
+   * After the user configures their device, call `enable` with the `token` and
+   * the first OTP code to activate the factor.
+   *
+   * Requires sudo: `MANAGE_MFA`.
+   *
+   * @example
+   * const { data } = await nulvless.auth.factors.enroll({ type: 'totp', name: 'My Authenticator' })
+   * // data.url → QR code provisioning URL
+   * // data.secret → manual entry secret
+   * // data.token → pass to factors.enable
+   */
+  async enroll(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, type, name } = params;
+    return this.http.post(route`/factors/${type}`, name ? { name } : {}, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Activates a pending factor enrollment by confirming the first OTP code.
+   *
+   * Pass the `token` from `enroll` and the code generated by the user's device.
+   */
+  async enable(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.post("/factors", params, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Unenrolls (removes) an MFA factor by its ID.
+   *
+   * Use `factors.list()` to retrieve the factor `id` before calling this.
+   * Returns the removed factor.
+   *
+   * Requires sudo: `MANAGE_MFA`.
+   *
+   * @example
+   * const { data: factors } = await nulvless.auth.factors.list()
+   * const totp = factors?.find(f => f.type === 'totp')
+   * if (totp?.id) await nulvless.auth.factors.unenroll({ id: totp.id })
+   */
+  async unenroll(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, id } = params;
+    return this.http.delete(route`/factors/${id}`, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+};
+
+// src/auth/users/index.ts
+var UsersClient = class extends AuthSubClient {
+  // ─── Profile ────────────────────────────────────────────────────────────────
+  /**
+   * Returns the authenticated user's full profile.
+   */
+  async me(options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/users/me", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Updates the authenticated user's profile fields.
+   *
+   * Omit fields to leave them unchanged.
+   */
+  async update(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.patch("/users", params, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  // ─── Identities ─────────────────────────────────────────────────────────────
+  /**
+   * Lists all identities (email, phone, OAuth) linked to the authenticated user.
+   *
+   * @param type Filter by identity type: `'email'`, `'phone'`, or `'oauth'`.
+   */
+  async getIdentities(type, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/users/identities", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers },
+      ...type ? { query: { type } } : {}
+    });
+  }
+  /**
+   * Initiates adding a new email identity. Sends an OTP to the provided address.
+   *
+   * Complete the flow with `verifyIdentity`.
+   *
+   * Requires sudo: `MANAGE_IDENTITIES`.
+   */
+  async addEmailIdentity(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, email } = params;
+    return this.http.post("/users/identities/emails", { email }, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Initiates adding a new phone identity. Sends an OTP to the provided number.
+   *
+   * Complete the flow with `verifyIdentity`.
+   *
+   * Requires sudo: `MANAGE_IDENTITIES`.
+   */
+  async addPhoneIdentity(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, phone } = params;
+    return this.http.post("/users/identities/phones", phone, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Confirms an identity addition by submitting the OTP received via
+   * `addEmailIdentity` or `addPhoneIdentity`.
+   */
+  async verifyIdentity(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.post("/users/identities/verify", params, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Updates an identity — currently used to set an identity as primary.
+   *
+   * Requires sudo: `MANAGE_IDENTITIES`.
+   */
+  async updateIdentity(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, id, primary } = params;
+    return this.http.patch(route`/users/identities/${id}`, { primary }, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Unlinks (removes) an identity from the authenticated user.
+   *
+   * Requires sudo: `MANAGE_IDENTITIES`.
+   */
+  async removeIdentity(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, id } = params;
+    return this.http.delete(route`/users/identities/${id}`, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  // ─── Credential updates ──────────────────────────────────────────────────────
+  /**
+   * Sends an OTP to the new email address to initiate an email change.
+   *
+   * Complete the flow with `confirmEmailUpdate`.
+   *
+   * Requires sudo: `MANAGE_CREDENTIALS`.
+   */
+  async sendOTPToUpdateEmail(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, email } = params;
+    return this.http.post("/users/emails/code/send", { email }, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Confirms an email change by submitting the OTP received via `sendOTPToUpdateEmail`.
+   */
+  async confirmEmailUpdate(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.patch("/users/emails/code/confirm", params, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Sends an OTP to the new phone number to initiate a phone change.
+   *
+   * Complete the flow with `confirmPhoneUpdate`.
+   *
+   * Requires sudo: `MANAGE_CREDENTIALS`.
+   */
+  async sendOTPToUpdatePhone(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, phone } = params;
+    return this.http.post("/users/phones/code/send", phone, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Confirms a phone change by submitting the OTP received via `sendOTPToUpdatePhone`.
+   */
+  async confirmPhoneUpdate(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.patch("/users/phones/code/confirm", params, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+};
+
+// src/auth/sessions/index.ts
+var SessionsClient = class extends AuthSubClient {
+  constructor(http, getToken, persist) {
+    super(http, getToken);
+    this.persist = persist;
+  }
+  persist;
+  /**
+   * Returns all active sessions for the authenticated user across all devices.
+   * The current session is marked with `is_current_session: true`.
+   */
+  async list(options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/sessions", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Revokes (invalidates) a specific session by its ID.
+   *
+   * Use `auth.getSession()` to get the current session ID.
+   *
+   * Requires sudo: `MANAGE_SESSIONS`.
+   */
+  async revoke(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, id } = params;
+    return this.http.delete(route`/sessions/${id}`, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Starts a sudo elevation by requesting a verification challenge.
+   *
+   * The available methods are derived from what the user has (TOTP if active,
+   * email OTP, SMS OTP). Pass `method` to request a specific one; if omitted and
+   * the user has a single method it is emitted automatically, otherwise an empty
+   * challenge is returned so the user can pick which one to send.
+   *
+   * Prompt the user for the code, then call `sudoVerify({ code })` to complete
+   * the elevation. The verify response carries `sudo.expires_in` (seconds until
+   * sudo mode expires) alongside the refreshed session tokens.
+   *
+   * @example
+   * const { data } = await nulvless.auth.sessions.sudo() // or sudo('email_otp')
+   * // prompt the user for the code, then call sudoVerify({ code })
+   */
+  async sudo(method, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/sessions/sudo/request", {
+      ...options,
+      ...method ? { query: { method } } : {},
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Completes a sudo elevation started by `sudo()`. Submit the `code` the user
+   * received (or read from their authenticator) — the pending sudo challenge is
+   * resolved by the current session, so no challenge token is needed.
+   *
+   * On success the session is re-issued with sudo mode active and stored
+   * automatically; `data.sudo.expires_in` carries the seconds until it expires.
+   *
+   * @example
+   * const { data } = await nulvless.auth.sessions.sudoVerify({ code })
+   * // data.sudo?.expires_in → 300
+   */
+  async sudoVerify(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.persist(
+      await this.http.post("/sessions/sudo/verify", params, {
+        ...options,
+        headers: { ...options?.headers, ...auth.headers }
+      })
+    );
+  }
+  /**
+   * Verifies that sudo mode is currently active for the session.
+   *
+   * Returns `204 No Content` on success. Returns an error if sudo is not active.
+   *
+   * @example
+   * const { error } = await nulvless.auth.sessions.checkSudo()
+   * if (error) {
+   *   // Start the sudo flow: sessions.sudo() → sessions.sudoVerify
+   * }
+   */
+  async checkSudo(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/sessions/sudo", {
+      ...options,
+      nonce: params?.nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+};
+
+// src/auth/security/index.ts
+var SecurityClient = class extends AuthSubClient {
+  /**
+   * Changes the authenticated user's password.
+   *
+   * @example
+   * await nulvless.auth.security.changePassword({
+   *   password: 'current-password',
+   *   new_password: 'new-password',
+   * })
+   */
+  async changePassword(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, ...body } = params;
+    return this.http.put("/security/password", body, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+};
+
+// src/auth/challenges/index.ts
+var ChallengesClient = class extends AuthSubClient {
+  constructor(http, getToken, persist) {
+    super(http, getToken);
+    this.persist = persist;
+  }
+  persist;
+  /**
+   * Creates a verification challenge for the given MFA method (step-up).
+   *
+   * Requires an authenticated session. Prompt the user for the code, then call
+   * `verify({ token, code })`.
+   *
+   * @example
+   * const { data } = await nulvless.auth.challenges.create('totp')
+   */
+  async create(targetType, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.post(route`/challenges/${targetType}`, void 0, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Retrieves the current state of a challenge by its token.
+   */
+  get(token, options) {
+    return this.http.get("/challenges", { ...options, query: { token } });
+  }
+  /**
+   * Switches the preferred MFA method for an ongoing challenge.
+   *
+   * @example
+   * const { data } = await nulvless.auth.challenges.change({ token, type: 'totp' })
+   */
+  change(params, options) {
+    return this.http.patch(
+      route`/challenges/${params.type}`,
+      { token: params.token },
+      options
+    );
+  }
+  /**
+   * Verifies a challenge by submitting the token and the code entered by the user.
+   *
+   * Used for OTP sign-in, MFA verification after `signIn`, and sign-up
+   * confirmation. Session is stored automatically when the response contains an
+   * access token.
+   */
+  async verify(params, options) {
+    return this.persist(await this.http.post("/challenges/verify", params, options));
+  }
+};
+
+// src/auth/grants/index.ts
+var GrantsClient = class extends AuthSubClient {
+  /**
+   * Returns all grants granted to the authenticated user, optionally
+   * filtered by context.
+   */
+  async list(context, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/grants", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers },
+      ...context ? { query: { context } } : {}
+    });
+  }
+  /**
+   * Returns all grants for a given resource, grouped by status
+   * (granted, invited, requested, blocked).
+   *
+   * The authenticated user must own or manage the resource.
+   */
+  async getMembers(resource, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/grants/members", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers },
+      query: { resource }
+    });
+  }
+  /**
+   * Creates grant invitations for one or more users on a resource.
+   *
+   * Each invite sends a notification to the target email address.
+   *
+   * Requires sudo: `MANAGE_GRANTS`.
+   *
+   * @example
+   * await nulvless.auth.grants.invite({
+   *   resource: 'project-123',
+   *   invites: [{ email: 'user@example.com', scopes: ['read', 'write'] }],
+   * })
+   */
+  async invite(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, ...body } = params;
+    return this.http.post("/grants/invites", {
+      ...body,
+      ...options?.redirect_uri ? { redirect_uri: options.redirect_uri } : {}
+    }, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Returns a single grant by ID.
+   */
+  async get(id, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get(route`/grants/${id}`, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Revokes (removes) a grant.
+   *
+   * Requires sudo: `MANAGE_GRANTS`.
+   */
+  async revoke(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, id } = params;
+    return this.http.delete(route`/grants/${id}/revoke`, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Accepts a pending invitation (`status: 'invited'`).
+   */
+  async accept(id, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.patch(route`/grants/${id}/accept`, void 0, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Cancels a pending invitation or request (`status: 'invited'` or `'requested'`).
+   */
+  async cancel(id, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.patch(route`/grants/${id}/cancel`, void 0, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Blocks a grant.
+   *
+   * Requires sudo: `MANAGE_GRANTS`.
+   */
+  async block(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, id } = params;
+    return this.http.patch(route`/grants/${id}/block`, void 0, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Updates the scopes of an existing grant.
+   *
+   * Requires sudo: `MANAGE_GRANTS`.
+   */
+  async update(id, params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, ...body } = params;
+    return this.http.patch(route`/grants/${id}`, body, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Removes the authenticated user from a resource they were granted access to.
+   *
+   * Requires sudo: `MANAGE_GRANTS`.
+   */
+  async leave(params, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const { nonce, id } = params;
+    return this.http.patch(route`/grants/${id}/leave`, void 0, {
+      ...options,
+      nonce,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+};
+
+// src/auth/oauth/index.ts
+var OAuthGrantsClient = class extends AuthSubClient {
+  /**
+   * Lists the apps the authenticated user has granted access to.
+   */
+  async list(options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/user/oauth/grants", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Revokes a previously granted app by its public `client_id`.
+   * Also invalidates the app's active sessions for this user.
+   */
+  async revoke(clientId, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.delete("/user/oauth/grants", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers },
+      query: { client_id: clientId }
+    });
+  }
+};
+var OAuthClient = class extends AuthSubClient {
+  /** Apps the authenticated user has authorized — list and revoke. */
+  grants;
+  constructor(http, getToken) {
+    super(http, getToken);
+    this.grants = new OAuthGrantsClient(http, getToken);
+  }
+  // ─── Authorization redirect (platform key) ──────────────────────────────────
+  /**
+   * Builds the OAuth authorization URL and, in the browser, redirects the user
+   * agent to it. On the server the URL is returned for manual handling.
+   *
+   * Mirrors `auth.authorize` (social sign-in): redirects automatically in the
+   * browser, returns `data.url` on the server. The endpoint itself is a 302
+   * redirect, so the URL is composed from the discovery `authorization_endpoint`.
+   *
+   * PKCE is required (RFC 7636, https://www.rfc-editor.org/rfc/rfc7636): provide
+   * `code_challenge` = BASE64URL(SHA256(code_verifier)) with
+   * `code_challenge_method: 'S256'`. Send the `code_verifier` later to
+   * `exchangeCodeForToken`.
+   *
+   * @example
+   * // Browser — redirects automatically
+   * await nulvless.auth.oauth.authorize({ client_id, redirect_uri, code_challenge, code_challenge_method: 'S256' })
+   *
+   * // Server — use the returned URL
+   * const { data } = await nulvless.auth.oauth.authorize(params)
+   * return Response.redirect(data.url)
+   */
+  async authorize(params, options) {
+    const discovery = await this.discovery(options);
+    if (discovery.error) return { data: null, error: discovery.error };
+    const url = new URL(discovery.data.authorization_endpoint);
+    const query = {
+      client_id: params.client_id,
+      redirect_uri: params.redirect_uri,
+      response_type: params.response_type ?? "code",
+      code_challenge: params.code_challenge,
+      code_challenge_method: params.code_challenge_method,
+      scope: params.scope,
+      state: params.state,
+      resource: params.resource,
+      nonce: params.nonce
+    };
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) url.searchParams.set(key, value);
+    }
+    if (typeof window !== "undefined") {
+      window.location.href = url.toString();
+    }
+    return { data: { url: url.toString() }, error: null };
+  }
+  // ─── Token endpoint (public) ────────────────────────────────────────────────
+  /**
+   * Exchanges an authorization code for tokens
+   * (`POST /oauth/token`, `grant_type=authorization_code`).
+   *
+   * Called by the relying-party app after the user is redirected back with the
+   * `code`. PKCE `code_verifier` is required; `client_secret` only for
+   * confidential clients. Public endpoint — no platform key.
+   */
+  exchangeCodeForToken(params, options) {
+    return this.http.post(
+      "/oauth/token",
+      { grant_type: "authorization_code", ...params },
+      { ...options, skipApiKey: true }
+    );
+  }
+  /**
+   * Refreshes an access token using a refresh token
+   * (`POST /oauth/token`, `grant_type=refresh_token`).
+   *
+   * `client_secret` only for confidential clients. Public endpoint — no
+   * platform key.
+   */
+  refreshToken(params, options) {
+    return this.http.post(
+      "/oauth/token",
+      { grant_type: "refresh_token", ...params },
+      { ...options, skipApiKey: true }
+    );
+  }
+  // ─── Dynamic registration (platform key) ────────────────────────────────────
+  /**
+   * Dynamically registers a new OAuth app (RFC 7591, `POST /oauth/register`).
+   *
+   * Requires the OAuth server to be enabled with dynamic client registration
+   * allowed. For server-side managed registration use `admin.oauthClients`.
+   */
+  register(params, options) {
+    return this.http.post("/oauth/register", params, { ...options, skipApiKey: true });
+  }
+  // ─── Consent flow (authenticated user) ──────────────────────────────────────
+  /**
+   * Loads a pending authorization for the consent screen
+   * (`GET /oauth/authorizations/:id`).
+   *
+   * Claims the authorization for the authenticated user. When a matching
+   * consent already exists it is auto-approved and `redirect.uri` is returned.
+   *
+   * Requires authentication.
+   */
+  async getAuthorization(authorizationId, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get(route`/oauth/authorizations/${authorizationId}`, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Approves or denies a pending authorization
+   * (`POST /oauth/authorizations/:id/consent`).
+   *
+   * Returns the `redirect.uri` to send the user agent back to (carrying the
+   * authorization `code` on approve, or `error=access_denied` on deny).
+   *
+   * Requires authentication.
+   */
+  async consent(authorizationId, action, options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.post(route`/oauth/authorizations/${authorizationId}/consent`, { action }, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  // ─── UserInfo (authenticated user) ──────────────────────────────────────────
+  /**
+   * Returns OIDC UserInfo claims for the access token (`GET /oauth/userinfo`).
+   *
+   * The access token must have been issued with the `openid` scope.
+   *
+   * Requires authentication.
+   */
+  async userinfo(options) {
+    const auth = await this.bearer(options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/oauth/userinfo", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  // ─── Public OIDC metadata (no auth) ─────────────────────────────────────────
+  /**
+   * Returns the OpenID Connect discovery document
+   * (`GET /.well-known/openid-configuration`). Public — no auth required.
+   */
+  discovery(options) {
+    return this.http.get("/.well-known/openid-configuration", { ...options, skipApiKey: true });
+  }
+  /**
+   * Returns the JSON Web Key Set used to verify issued tokens
+   * (`GET /.well-known/jwks.json`). Public — no auth required.
+   */
+  jwks(options) {
+    return this.http.get("/.well-known/jwks.json", { ...options, skipApiKey: true });
+  }
+};
+
+// src/auth/admin/index.ts
+var AdminUsersClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Creates a new user bypassing normal sign-up flows.
+   */
+  create(params, options) {
+    return this.http.post("/admin/users", params, options);
+  }
+  /**
+   * Lists users with pagination and optional filters.
+   */
+  list(params, options) {
+    return this.http.get("/admin/users", {
+      ...options,
+      ...params ? { query: params } : {}
+    });
+  }
+  /**
+   * Returns a single user by ID.
+   */
+  get(userId, options) {
+    return this.http.get(route`/admin/users/${userId}`, options);
+  }
+  /**
+   * Updates a user's profile fields.
+   */
+  update(userId, params, options) {
+    return this.http.patch(route`/admin/users/${userId}`, params, options);
+  }
+  /**
+   * Permanently deletes a user.
+   */
+  delete(userId, options) {
+    return this.http.delete(route`/admin/users/${userId}`, options);
+  }
+  /**
+   * Bans a user, preventing them from signing in.
+   */
+  ban(userId, options) {
+    return this.http.patch(route`/admin/users/${userId}/ban`, void 0, options);
+  }
+  /**
+   * Lifts a ban on a user.
+   */
+  unban(userId, options) {
+    return this.http.patch(route`/admin/users/${userId}/unban`, void 0, options);
+  }
+  /**
+   * Returns all active sessions for a specific user.
+   */
+  getSessions(userId, options) {
+    return this.http.get(route`/admin/users/${userId}/sessions`, options);
+  }
+  /**
+   * Invalidates all sessions for a specific user (signs them out everywhere).
+   */
+  signOutAll(userId, options) {
+    return this.http.delete(route`/admin/users/${userId}/sessions`, options);
+  }
+  /**
+   * Invalidates a specific session for a user.
+   */
+  revokeSession(userId, sessionId, options) {
+    return this.http.delete(route`/admin/users/${userId}/sessions/${sessionId}`, options);
+  }
+  /**
+   * Returns all configured MFA factors for a specific user.
+   */
+  getFactors(userId, options) {
+    return this.http.get(route`/admin/users/${userId}/factors`, options);
+  }
+  /**
+   * Removes a specific MFA factor from a user.
+   */
+  removeFactor(userId, factorId, options) {
+    return this.http.delete(route`/admin/users/${userId}/factors/${factorId}`, options);
+  }
+};
+var AdminRolesClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Returns all roles, optionally filtered by context.
+   */
+  list(context, options) {
+    return this.http.get("/admin/roles", {
+      ...options,
+      ...context ? { query: { context } } : {}
+    });
+  }
+  /**
+   * Creates a new role with the given scopes.
+   */
+  create(params, options) {
+    return this.http.post("/admin/roles", params, options);
+  }
+  /**
+   * Updates an existing role.
+   */
+  update(role_id, params, options) {
+    return this.http.patch(route`/admin/roles/${role_id}`, params, options);
+  }
+  /**
+   * Deletes a role.
+   */
+  delete(role_id, options) {
+    return this.http.delete(route`/admin/roles/${role_id}`, options);
+  }
+};
+var AdminGrantsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Lists grants with pagination and optional filters.
+   */
+  list(params, options) {
+    return this.http.get("/admin/grants", {
+      ...options,
+      ...params ? { query: params } : {}
+    });
+  }
+  /**
+   * Creates or upserts a grant for a user on a resource.
+   */
+  set(params, options) {
+    return this.http.post("/admin/grants", params, options);
+  }
+  /**
+   * Deletes a grant by ID.
+   */
+  delete(grantId, options) {
+    return this.http.delete(route`/admin/grants/${grantId}`, options);
+  }
+  /**
+   * Removes all grants associated with a resource.
+   *
+   * Use with caution — this will revoke access for all users on the resource.
+   */
+  deleteByResource(resource, options) {
+    return this.http.delete(route`/admin/resources/${resource}/grants`, options);
+  }
+};
+var AdminOAuthClientsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Registers a new OAuth app. For confidential apps the response includes a
+   * one-time `client_secret` — store it securely, it is never returned again.
+   */
+  create(params, options) {
+    return this.http.post("/admin/oauth/clients", params, options);
+  }
+  /**
+   * Lists all registered OAuth apps.
+   */
+  list(options) {
+    return this.http.get("/admin/oauth/clients", options);
+  }
+  /**
+   * Returns a single OAuth app by its internal id.
+   */
+  get(id, options) {
+    return this.http.get(route`/admin/oauth/clients/${id}`, options);
+  }
+  /**
+   * Updates an OAuth app. `client_type` is immutable and the secret rotates via
+   * `regenerateSecret` — neither can be changed here.
+   */
+  update(id, params, options) {
+    return this.http.put(route`/admin/oauth/clients/${id}`, params, options);
+  }
+  /**
+   * Deletes an OAuth app.
+   */
+  delete(id, options) {
+    return this.http.delete(route`/admin/oauth/clients/${id}`, options);
+  }
+  /**
+   * Rotates the client secret (confidential apps only). The new `client_secret`
+   * is returned once — the previous one stops working immediately.
+   */
+  regenerateSecret(id, options) {
+    return this.http.post(route`/admin/oauth/clients/${id}/regenerate_secret`, void 0, options);
+  }
+};
+var AdminClient = class {
+  constructor(http) {
+    this.http = http;
+    this.users = new AdminUsersClient(http);
+    this.roles = new AdminRolesClient(http);
+    this.grants = new AdminGrantsClient(http);
+    this.oauthClients = new AdminOAuthClientsClient(http);
+  }
+  http;
+  users;
+  roles;
+  grants;
+  oauthClients;
+  /**
+   * Returns basic platform information (id, name, slug).
+   */
+  getPlatform(options) {
+    return this.http.get("/admin/platform", options);
+  }
+};
+
+// src/session/stored.ts
+var DEFAULT_EXPIRES_IN_SECONDS = 3600;
+function toStoredSession(auth) {
+  return {
+    access_token: auth.access_token,
+    ...auth.refresh_token !== void 0 ? { refresh_token: auth.refresh_token } : {},
+    expires_at: Date.now() + (auth.expires_in ?? DEFAULT_EXPIRES_IN_SECONDS) * 1e3,
+    token_type: auth.token_type ?? "bearer",
+    ...auth.user !== void 0 ? { user: auth.user } : {}
+  };
+}
+function toAuthenticated(stored) {
+  return {
+    access_token: stored.access_token,
+    ...stored.refresh_token !== void 0 ? { refresh_token: stored.refresh_token } : {},
+    ...stored.token_type ? { token_type: stored.token_type } : {},
+    expires_in: Math.round((stored.expires_at - Date.now()) / 1e3),
+    ...stored.user !== void 0 ? { user: stored.user } : {}
+  };
+}
+
+// src/auth/accounts.ts
+function decodeBase64Url(segment) {
+  const base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, "=");
+  const bytes = Uint8Array.from(atob(padded), (char) => char.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+function extractUserId(auth) {
+  if (auth.user?.id) return auth.user.id;
+  if (!auth.access_token) return null;
+  try {
+    const payload = JSON.parse(decodeBase64Url(auth.access_token.split(".")[1]));
+    return typeof payload["sub"] === "string" ? payload["sub"] : null;
+  } catch {
+    return null;
+  }
+}
+var AccountsManager = class {
+  constructor(storage, accountsKey) {
+    this.storage = storage;
+    this.accountsKey = accountsKey;
+  }
+  storage;
+  accountsKey;
+  async readMap() {
+    const raw = await this.storage.getItem(this.accountsKey);
+    if (!raw) return {};
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return {};
+    }
+  }
+  async writeMap(map) {
+    await this.storage.setItem(this.accountsKey, JSON.stringify(map));
+  }
+  async save(auth) {
+    const userId = extractUserId(auth);
+    if (!userId || !auth.access_token) return null;
+    const map = await this.readMap();
+    map[userId] = toStoredSession({ ...auth, access_token: auth.access_token });
+    await this.writeMap(map);
+    return userId;
+  }
+  async getSession(userId) {
+    const map = await this.readMap();
+    return map[userId] ?? null;
+  }
+  async list() {
+    const map = await this.readMap();
+    return Object.entries(map).map(([userId, session]) => ({
+      userId,
+      access_token: session.access_token,
+      expires_in: Math.round((session.expires_at - Date.now()) / 1e3),
+      ...session.refresh_token !== void 0 ? { refresh_token: session.refresh_token } : {},
+      ...session.user !== void 0 ? { user: session.user } : {}
+    }));
+  }
+  async remove(userId) {
+    const map = await this.readMap();
+    delete map[userId];
+    await this.writeMap(map);
+  }
+};
+
+// src/auth/emitter.ts
+var AuthEventEmitter = class {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  listeners = /* @__PURE__ */ new Map();
+  on(event, handler) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+    };
+  }
+  emit(...args) {
+    const [event, payload] = args;
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const handler of set) {
+      try {
+        ;
+        handler(payload);
+      } catch (error) {
+        console.error(`[nulvless] '${event}' listener failed`, error);
+      }
+    }
+  }
+  removeAllListeners(event) {
+    if (event) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+  }
+};
+
+// src/auth/index.ts
+var AuthClient = class {
+  constructor(http, session) {
+    this.http = http;
+    this.session = session;
+    session?.setRefreshFn(
+      (refresh_token) => this.http.post("/token", { refresh_token }, {
+        query: { grant_type: "refresh_token" }
+      })
+    );
+    this._getToken = () => this.session?.getValidToken() ?? Promise.resolve(null);
+    this.factors = new FactorsClient(http, this._getToken);
+    this.users = new UsersClient(http, this._getToken);
+    this.sessions = new SessionsClient(
+      http,
+      this._getToken,
+      (result) => this.persistSession(result)
+    );
+    this.security = new SecurityClient(http, this._getToken);
+    this.challenges = new ChallengesClient(
+      http,
+      this._getToken,
+      (result) => this.persistSession(result)
+    );
+    this.oauth = new OAuthClient(http, this._getToken);
+  }
+  http;
+  session;
+  /** MFA factor management — enroll, enable, disable, recovery codes. */
+  factors;
+  /** Current-user management — profile, identities, credential updates. */
+  users;
+  /** Active session management — list, revoke, sudo mode. */
+  sessions;
+  /** Account security — change password. */
+  security;
+  /** Challenge lifecycle — create, get, change, verify (MFA / OTP / step-up). */
+  challenges;
+  /** OAuth server (project as OIDC provider) — token, consent, userinfo, grants, discovery. */
+  oauth;
+  _getToken;
+  /**
+   * Returns the current active access token from storage.
+   * Refreshes automatically if the token is expired or about to expire.
+   * Returns `null` when there is no active session.
+   */
+  async getAccessToken() {
+    return this.session?.getValidToken() ?? null;
+  }
+  // ─── Helpers ──────────────────────────────────────────────────────────────
+  async persistSession(result) {
+    if (!result.error && result.data.access_token && this.session) {
+      await this.session.save(result.data);
+    }
+    return result;
+  }
+  // ─── Sign-up / Sign-in ─────────────────────────────────────────────────────
+  /**
+   * Creates a new user account.
+   *
+   * At least one of `email`, `phone`, or `username` must be provided.
+   *
+   * Check the response in this order:
+   * 1. `data.access_token` → authenticated immediately — session stored automatically.
+   * 2. `data.challenge` → MFA/OTP step required — call `verifyChallenge`.
+   * 3. `data.user` only → pending email/phone confirmation.
+   */
+  async signUp(params, options) {
+    return this.persistSession(
+      await this.http.post("/signup", params, options)
+    );
+  }
+  /**
+   * Signs in with password (`grant_type=password`).
+   *
+   * At least one of `email`, `phone`, or `username` must be provided.
+   *
+   * Check the response in this order:
+   * 1. `data.access_token` → signed in — session stored automatically.
+   * 2. `data.challenge` → MFA step required — call `verifyChallenge`.
+   */
+  async signIn(params, options) {
+    return this.persistSession(
+      await this.http.post("/token", params, {
+        ...options,
+        query: { grant_type: "password" }
+      })
+    );
+  }
+  /**
+   * Requests a one-time password sent to the user's email or phone.
+   *
+   * Returns a `Challenge` (`202 Accepted`). Pass the received code to `verifyChallenge`.
+   *
+   * At least one of `email` or `phone` must be provided.
+   */
+  signInWithOTP(params, options) {
+    return this.http.post("/otp", params, options);
+  }
+  /**
+   * Initiates an OAuth sign-in flow for the given provider.
+   *
+   * In a browser environment the user is redirected automatically to the
+   * authorization URL. On the server the URL is returned for manual handling.
+   *
+   * After the redirect, the server-side callback exchanges the code automatically
+   * and redirects back to `options.redirect_uri`. For server-side code exchange, use `exchangeCodeForToken`.
+   *
+   * @example
+   * // Browser — redirects automatically
+   * await nulvless.auth.authorize('google', { redirect_uri: 'https://myapp.com/callback' })
+   *
+   * // Server — use the returned URL
+   * const { data } = await nulvless.auth.authorize('google', { redirect_uri: 'https://myapp.com/callback' })
+   * return Response.redirect(data.url)
+   */
+  async authorize(provider, options) {
+    const result = await this.http.get(
+      route`/oauth/${provider}/authorize`,
+      { ...options, query: { ...options?.redirect_uri ? { redirect_uri: options.redirect_uri } : {} } }
+    );
+    if (!result.error && typeof window !== "undefined") {
+      window.location.href = result.data.url;
+    }
+    return result;
+  }
+  /**
+   * Initiates an OAuth flow to connect a new provider to the authenticated user's account.
+   *
+   * Same behaviour as `authorize`, but for users who are already signed in — the resulting
+   * provider identity is linked to the current account instead of starting a sign-in flow.
+   *
+   * In a browser environment the user is redirected automatically to the
+   * authorization URL. On the server the URL is returned for manual handling.
+   *
+   * Requires authentication. Token is resolved automatically from storage
+   * (browser) or from `options.headers.Authorization` (server).
+   *
+   * @example
+   * await nulvless.auth.connect('github', { redirect_uri: 'https://myapp.com/settings/connections' })
+   */
+  async connect(provider, options) {
+    const auth = await resolveBearer(this.http, this._getToken, options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const result = await this.http.get(
+      route`/oauth/${provider}/connect`,
+      {
+        ...options,
+        headers: { ...options?.headers, ...auth.headers },
+        query: { ...options?.redirect_uri ? { redirect_uri: options.redirect_uri } : {} }
+      }
+    );
+    if (!result.error && typeof window !== "undefined") {
+      window.location.href = result.data.url;
+    }
+    return result;
+  }
+  /**
+   * Signs in with an ID token issued by a third-party OAuth provider.
+   *
+   * Useful for mobile apps where you obtain the ID token natively (e.g. Google Sign-In SDK).
+   *
+   * Session is stored automatically when the response contains an access token.
+   *
+   * @example
+   * const { data } = await nulvless.auth.signInWithIdToken('google', googleIdToken)
+   */
+  async signInWithIdToken(provider, idToken, options) {
+    return this.persistSession(
+      await this.http.get(route`/signin/${provider}/id_token`, {
+        ...options,
+        query: { id_token: idToken }
+      })
+    );
+  }
+  /**
+   * Exchanges an OAuth authorization code for an access token
+   * (`grant_type=authorization_code`).
+   *
+   * Must be called with `Content-Type: application/x-www-form-urlencoded`.
+   * The `code` must be the authorization code received from the OAuth callback.
+   *
+   * Session is stored automatically when the response contains an access token.
+   *
+   * @example
+   * const { data } = await nulvless.auth.exchangeCodeForToken('auth-code-from-callback')
+   */
+  async exchangeCodeForToken(code, options) {
+    return this.persistSession(
+      await this.http.post(
+        "/token",
+        { code },
+        {
+          ...options,
+          query: { grant_type: "authorization_code" },
+          headers: {
+            ...options?.headers,
+            "Content-Type": "application/x-www-form-urlencoded"
+          }
+        }
+      )
+    );
+  }
+  /**
+   * Returns all sign-in methods, MFA factors, and OAuth providers configured
+   * for the authenticated user on this platform.
+   *
+   * Requires authentication.
+   */
+  async getMethods(options) {
+    const auth = await resolveBearer(this.http, this._getToken, options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/methods", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  // ─── Challenge ─────────────────────────────────────────────────────────────
+  /**
+   * Looks up whether an identifier exists and which sign-in method applies.
+   *
+   * Useful for adaptive sign-in UIs. May return a `challenge` directly
+   * when the user's method is OTP-only.
+   *
+   * At least one of `email`, `phone`, or `username` must be provided.
+   */
+  lookup(params, options) {
+    return this.http.post("/lookup", params, options);
+  }
+  /**
+   * Verifies a challenge by submitting the token and the code entered by the user.
+   *
+   * Used for:
+   * - OTP sign-in (`signInWithOTP` flow)
+   * - MFA verification after `signIn`
+   * - Sign-up confirmation (`signUp` challenge flow)
+   *
+   * Convenience alias for `auth.challenges.verify`. Session is stored
+   * automatically when the response contains an access token. For the rest of
+   * the challenge lifecycle (create, get, change) use `auth.challenges`.
+   */
+  async verifyChallenge(params, options) {
+    return this.challenges.verify(params, options);
+  }
+  // ─── Account lifecycle ─────────────────────────────────────────────────────
+  /**
+   * Activates an account via the confirmation link sent to the user's email/phone.
+   */
+  activate(token, options) {
+    return this.http.get("/activate", { ...options, query: { token } });
+  }
+  /**
+   * Refreshes the access token using a refresh token (`grant_type=refresh_token`).
+   * Session is updated automatically in storage.
+   */
+  async refreshToken(params, options) {
+    return this.persistSession(
+      await this.http.post("/token", params, {
+        ...options,
+        query: { grant_type: "refresh_token" }
+      })
+    );
+  }
+  /**
+   * Sends a password-recovery email to the user.
+   */
+  recover(params, options) {
+    return this.http.post("/recover", {
+      ...params,
+      ...options?.redirect_uri ? { redirect_uri: options.redirect_uri } : {}
+    }, options);
+  }
+  /**
+   * Resets the user's password using the token from the recovery email.
+   */
+  resetPassword(params, options) {
+    return this.http.post("/recover/reset-password", params, options);
+  }
+  // ─── Session ───────────────────────────────────────────────────────────────
+  /**
+   * Validates the current session and optionally checks a grant.
+   *
+   * Requires authentication. Token is resolved automatically from storage
+   * (browser) or from `options.headers.Authorization` (server).
+   */
+  async verify(grant, options) {
+    const auth = await resolveBearer(this.http, this._getToken, options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/session/validate", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers },
+      query: {
+        ...grant?.resource ? { resource: grant.resource } : {},
+        ...grant?.scopes ? { scopes: grant.scopes.join(" ") } : {},
+        ...grant?.roles ? { roles: grant.roles.join(" ") } : {},
+        ...grant?.reject_assurance_level_error !== void 0 ? { reject_assurance_level_error: String(grant.reject_assurance_level_error) } : {}
+      }
+    });
+  }
+  /**
+   * Returns the current session details.
+   *
+   * Requires authentication. Token is resolved automatically from storage
+   * (browser) or from `options.headers.Authorization` (server).
+   */
+  async getSession(options) {
+    const auth = await resolveBearer(this.http, this._getToken, options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    return this.http.get("/session", {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers }
+    });
+  }
+  /**
+   * Signs out the user and clears the stored session.
+   *
+   * - `'local'` (default) — invalidates only the current session.
+   * - `'global'` — invalidates all sessions across all devices.
+   * - `'others'` — invalidates all sessions except the current one.
+   *
+   * Requires authentication. Token is resolved automatically from storage
+   * (browser) or from `options.headers.Authorization` (server).
+   */
+  async signOut(scope, options) {
+    const auth = await resolveBearer(this.http, this._getToken, options);
+    if (!auth.ok) return { data: null, error: auth.error };
+    const result = await this.http.post("/signout", void 0, {
+      ...options,
+      headers: { ...options?.headers, ...auth.headers },
+      ...scope ? { query: { scope } } : {}
+    });
+    if (!result.error) {
+      await this.session?.clear();
+    }
+    return result;
+  }
+};
+var AuthBrowserClient = class extends AuthClient {
+  accountsManager;
+  emitter;
+  multiUser;
+  tabs;
+  constructor(http, session, storage, accountsKey, multiUser = false, autoRefresh = true) {
+    super(http, session);
+    this.multiUser = multiUser;
+    this.accountsManager = new AccountsManager(storage, accountsKey);
+    this.emitter = new AuthEventEmitter();
+    this.tabs = new TabChannel(`nulvless.auth.${accountsKey}`, (message) => {
+      this.emitter.emit(
+        message.event,
+        message.payload
+      );
+    });
+    session.setOnTokenRefreshed((auth) => {
+      if (this.multiUser) {
+        void this.accountsManager.save(auth);
+      }
+      this.emitter.emit("token-refreshed", auth);
+      this.tabs.post({ event: "token-refreshed", payload: auth });
+    });
+    session.setOnUnauthorized((failed) => {
+      this.emitter.emit("unauthorized", failed ? toAuthenticated(failed) : {});
+    });
+    http.setOnSudoRequired(() => {
+      this.emitter.emit("sudo-required");
+    });
+    if (autoRefresh) {
+      session.startAutoRefresh();
+    }
+  }
+  /**
+   * Renews the access token now, sharing the attempt with any refresh already
+   * in flight. Returns the new token, or `null` when the session could not be
+   * recovered.
+   */
+  async refreshSession() {
+    return this.session?.forceRefresh() ?? null;
+  }
+  /** Releases the refresh timer and the cross-tab channel. */
+  dispose() {
+    this.session?.stopAutoRefresh();
+    this.tabs.close();
+  }
+  /**
+   * Subscribes to an auth event.
+   *
+   * Returns an unsubscribe function — call it to stop listening.
+   *
+   * @example
+   * const off = nulvless.auth.on('signed-in', (session) => {
+   *   console.log('signed in as', session.user?.id)
+   * })
+   * off() // unsubscribe
+   */
+  on(event, handler) {
+    return this.emitter.on(event, handler);
+  }
+  // ─── Session persistence override ─────────────────────────────────────────
+  async persistSession(result) {
+    const out = await super.persistSession(result);
+    if (!out.error) {
+      if (out.data.access_token) {
+        if (this.multiUser) {
+          await this.accountsManager.save(out.data);
+        }
+        this.emitter.emit("signed-in", out.data);
+      } else if (out.data.challenge) {
+        this.emitter.emit("challenge", out.data);
+      }
+    }
+    return out;
+  }
+  // ─── Active session helpers ────────────────────────────────────────────────
+  /**
+   * Returns the session currently stored in storage, or `null` if there is none.
+   *
+   * `expires_in` is the number of seconds remaining until expiry (may be negative
+   * if the token is already expired).
+   *
+   * @example
+   * const session = await nulvless.auth.get()
+   * if (session) {
+   *   console.log(session.access_token, session.expires_in)
+   * }
+   */
+  async get() {
+    const stored = await this.session?.get();
+    return stored ? toAuthenticated(stored) : null;
+  }
+  /**
+   * Manually persists a session as the active session.
+   *
+   * Use this when you obtain an `Authenticated` outside the normal SDK flow
+   * (e.g. server-side login, custom OAuth callback) and want the SDK to treat
+   * it as the active session.
+   *
+   * @example
+   * await nulvless.auth.set({ access_token: 'eyJ...', refresh_token: 'rt_...', expires_in: 3600 })
+   */
+  async set(data) {
+    if (data.access_token) {
+      await this.session?.save(data);
+    }
+  }
+  // ─── Multi-account ─────────────────────────────────────────────────────────
+  /**
+   * Adds an account to the accounts store without switching the active session.
+   *
+   * The account is identified by the `user.id` in the response, or by the `sub`
+   * claim in the access token JWT.
+   *
+   * Call this after a sign-in to register additional accounts. Accounts are
+   * also saved automatically whenever a sign-in / sign-up succeeds.
+   *
+   * @example
+   * const { data } = await nulvless.auth.signIn(params)
+   * // already saved automatically — or add manually:
+   * await nulvless.auth.add(data)
+   */
+  async add(auth) {
+    if (!this.multiUser || !auth.access_token) return;
+    await this.accountsManager.save(auth);
+  }
+  /**
+   * Switches the active session to a previously saved account.
+   *
+   * Returns `true` on success, `false` if the account is not found.
+   *
+   * @example
+   * const ok = await nulvless.auth.switch('user-id-123')
+   */
+  async switch(userId) {
+    if (!this.multiUser) return false;
+    const stored = await this.accountsManager.getSession(userId);
+    if (!stored) return false;
+    await this.session?.save(toAuthenticated(stored));
+    this.emitter.emit("account-switched", { userId });
+    return true;
+  }
+  /**
+   * Returns all accounts currently saved in the accounts store.
+   *
+   * @example
+   * const accounts = await nulvless.auth.list()
+   * // [{ userId: '...', access_token: '...', expires_in: 3540 }]
+   */
+  list() {
+    if (!this.multiUser) return Promise.resolve([]);
+    return this.accountsManager.list();
+  }
+  /**
+   * Removes a saved account from the accounts store.
+   *
+   * Does not affect the active session.
+   *
+   * @example
+   * await nulvless.auth.remove('user-id-123')
+   */
+  remove(userId) {
+    if (!this.multiUser) return Promise.resolve();
+    return this.accountsManager.remove(userId);
+  }
+  /**
+   * Drops the active session without ending it on the server.
+   *
+   * The account stays in the accounts store, so `switch` brings it back. Use
+   * this when the user leaves the authenticated area to pick or add another
+   * account: with no active session the automatic refresh goes quiet instead
+   * of keeping a session warm that nothing is using.
+   *
+   * @example
+   * await nulvless.auth.deselect()
+   * // later
+   * await nulvless.auth.switch('user-id-123')
+   */
+  async deselect() {
+    const stored = await this.session?.get();
+    if (!stored) return;
+    if (this.multiUser) {
+      await this.accountsManager.save(toAuthenticated(stored));
+    }
+    await this.session?.clear();
+  }
+  // ─── signOut override ──────────────────────────────────────────────────────
+  async signOut(scope, options) {
+    const stored = await this.session?.get();
+    const userId = stored ? stored.user?.id ?? extractUserId({ access_token: stored.access_token }) : null;
+    const result = await super.signOut(scope, options);
+    if (!result.error) {
+      if (this.multiUser && userId) {
+        await this.accountsManager.remove(userId);
+      }
+      this.emitter.emit("signed-out", { ...userId ? { userId } : {} });
+    }
+    return result;
+  }
+};
+var AuthServerClient = class extends AuthClient {
+  /** User-facing grant management — invite, accept, revoke, etc. */
+  grants;
+  /** Platform administration — manage users, roles, and grants server-side. */
+  admin;
+  constructor(http) {
+    super(http);
+    this.grants = new GrantsClient(http, this._getToken);
+    this.admin = new AdminClient(http);
+  }
+};
+
+// src/comms/templates/index.ts
+function templatePath(channel, slug, language) {
+  return language ? route`/templates/${channel}/${slug}/${language}` : route`/templates/${channel}/${slug}`;
+}
+var TemplatesClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Creates a new notification template.
+   *
+   * - `email` channel: `subject` required, `url` not allowed.
+   * - `sms` channel: `subject` and `url` not allowed.
+   * - `webhook` channel: `url` required, `subject` not allowed.
+   */
+  create(params, options) {
+    return this.http.post("/templates", params, options);
+  }
+  /**
+   * Updates an existing template.
+   *
+   * `language` defaults to `'en-US'` when omitted.
+   *
+   * @example
+   * await nulvless.comms.templates.update('email', 'welcome', { subject: 'Welcome aboard!' })
+   */
+  update(channel, slug, params, language, options) {
+    return this.http.patch(templatePath(channel, slug, language), params, options);
+  }
+  /**
+   * Deletes a template.
+   *
+   * `language` defaults to `'en-US'` when omitted.
+   */
+  delete(channel, slug, language, options) {
+    return this.http.delete(templatePath(channel, slug, language), options);
+  }
+  /**
+   * Returns a template by channel and slug, falling back to the common template
+   * if no custom one exists.
+   *
+   * `language` defaults to `'en-US'` when omitted.
+   *
+   * The response includes `common: true` when the returned template is the
+   * platform-level fallback rather than a custom override.
+   */
+  get(channel, slug, language, options) {
+    return this.http.get(templatePath(channel, slug, language), options);
+  }
+  /**
+   * Returns a paginated list of templates, optionally filtered by channel and language.
+   *
+   * @example
+   * const { data } = await nulvless.comms.templates.list({ channel: 'email', page_size: 20 })
+   */
+  list(filters, options) {
+    return this.http.get("/templates", {
+      ...options,
+      query: {
+        ...filters?.page !== void 0 ? { page: filters.page } : {},
+        ...filters?.page_size !== void 0 ? { page_size: filters.page_size } : {},
+        ...filters?.sort ? { sort: filters.sort } : {},
+        ...filters?.channel ? { channel: filters.channel } : {},
+        ...filters?.language ? { language: filters.language } : {}
+      }
+    });
+  }
+};
+
+// src/comms/index.ts
+var EmailClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Sends a transactional email using a pre-configured template.
+   *
+   * Returns `null` on success — the API responds with `200` and no body.
+   *
+   * @example
+   * const { error } = await nulvless.comms.email.send({
+   *   to: 'user@example.com',
+   *   template: 'welcome',
+   *   params: { name: 'Gleisson' },
+   * })
+   */
+  send(params, options) {
+    const { to, template, language, params: templateParams } = params;
+    const path = language ? route`/notifications/email/${template}/${language}` : route`/notifications/email/${template}`;
+    return this.http.post(path, { email: to, params: templateParams }, options);
+  }
+  /**
+   * Sends a test email to validate the platform's email provider configuration.
+   *
+   * Returns `null` on success.
+   *
+   * @example
+   * const { error } = await nulvless.comms.email.test('user@example.com')
+   */
+  test(email, options) {
+    return this.http.post("/notifications/test/email", { email }, options);
+  }
+};
+var SmsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Sends a transactional SMS using a pre-configured template.
+   *
+   * Returns `null` on success — the API responds with `200` and no body.
+   *
+   * @example
+   * const { error } = await nulvless.comms.sms.send({
+   *   phone: { country_code: '+55', number: '11999999999' },
+   *   template: 'verification-code',
+   *   params: { code: '123456' },
+   * })
+   */
+  send(params, options) {
+    const { phone, template, language, params: templateParams } = params;
+    const path = language ? route`/notifications/sms/${template}/${language}` : route`/notifications/sms/${template}`;
+    return this.http.post(path, { phone, params: templateParams }, options);
+  }
+  /**
+   * Sends a test SMS to validate the platform's SMS provider configuration.
+   *
+   * Returns `null` on success.
+   *
+   * @example
+   * const { error } = await nulvless.comms.sms.test('user@example.com')
+   */
+  test(email, options) {
+    return this.http.post("/notifications/test/sms", { email }, options);
+  }
+};
+var CommsClient = class {
+  email;
+  sms;
+  templates;
+  constructor(http) {
+    this.email = new EmailClient(http);
+    this.sms = new SmsClient(http);
+    this.templates = new TemplatesClient(http);
+  }
+};
+
+// src/session/locks.ts
+var pendingByName = /* @__PURE__ */ new Map();
+function webLocks() {
+  const manager = globalThis.navigator?.locks;
+  return typeof manager?.request === "function" ? manager : null;
+}
+async function runExclusive(name, task, options = {}) {
+  const manager = webLocks();
+  if (manager) {
+    return await manager.request(
+      name,
+      { mode: "exclusive", ...options.skipWhenBusy ? { ifAvailable: true } : {} },
+      async (lock) => lock === null ? { ran: false } : { ran: true, value: await task() }
+    );
+  }
+  const previous = pendingByName.get(name);
+  if (previous && options.skipWhenBusy) {
+    return { ran: false };
+  }
+  const run = (previous ?? Promise.resolve()).catch(() => void 0).then(task);
+  const slot = run.catch(() => void 0);
+  pendingByName.set(name, slot);
+  try {
+    return { ran: true, value: await run };
+  } finally {
+    if (pendingByName.get(name) === slot) {
+      pendingByName.delete(name);
+    }
+  }
+}
+
+// src/session/refreshFailure.ts
+var REFUSAL_CODES = /* @__PURE__ */ new Set([
+  "unauthorized",
+  "refresh_token_not_found",
+  "refresh_token_already_used",
+  "refresh_token_not_issued_here",
+  "user_banned"
+]);
+function isTemporaryFailure(error) {
+  return error.status_code === 0 || error.status_code === 408 || error.status_code === 429 || error.status_code >= 500;
+}
+function isSessionRefused(error) {
+  return REFUSAL_CODES.has(error.code) || error.status_code === 401;
+}
+
+// src/session/manager.ts
+var REFRESH_MARGIN_IN_MS = 9e4;
+var TICK_INTERVAL_IN_MS = 3e4;
+var RETRY_BACKOFF_BASE_IN_MS = 200;
+var MAX_RETRIES_ON_TEMPORARY_FAILURE = 3;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function documentIsHidden() {
+  return globalThis.document?.hidden === true;
+}
+function isBrowser() {
+  const scope = globalThis;
+  return typeof scope.window !== "undefined" && typeof scope.document !== "undefined";
+}
+var SessionManager = class {
+  constructor(storage, sessionKey) {
+    this.storage = storage;
+    this.sessionKey = sessionKey;
+    this.lockName = `nulvless.session.${sessionKey}`;
+  }
+  storage;
+  refreshFn;
+  onTokenRefreshed;
+  onUnauthorized;
+  sessionKey;
+  lockName;
+  inFlight = null;
+  ticker;
+  onVisibilityChange;
+  /**
+   * Injected by `AuthClient` after construction to avoid circular dependency.
+   * Called automatically when the access token is about to expire.
+   */
+  setRefreshFn(fn) {
+    this.refreshFn = fn;
+  }
+  /** Called after a successful automatic token refresh. */
+  setOnTokenRefreshed(cb) {
+    this.onTokenRefreshed = cb;
+  }
+  /**
+   * Called when the SDK cannot recover the session:
+   * - no refresh token present, or
+   * - the refresh request was refused by the server.
+   */
+  setOnUnauthorized(cb) {
+    this.onUnauthorized = cb;
+  }
+  async save(auth) {
+    if (!auth.access_token) return;
+    const session = toStoredSession({ ...auth, access_token: auth.access_token });
+    await this.storage.setItem(this.sessionKey, JSON.stringify(session));
+  }
+  async get() {
+    const raw = await this.storage.getItem(this.sessionKey);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  async clear() {
+    await this.storage.removeItem(this.sessionKey);
+  }
+  expiresSoon(session) {
+    return session.expires_at - Date.now() < REFRESH_MARGIN_IN_MS;
+  }
+  refresh(request) {
+    if (this.inFlight) {
+      return this.inFlight;
+    }
+    this.inFlight = this.runExclusiveRefresh(request).finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+  async runExclusiveRefresh(request) {
+    const outcome = await runExclusive(this.lockName, () => this.refreshHoldingLock(request));
+    return outcome.ran ? outcome.value : null;
+  }
+  async refreshHoldingLock(request) {
+    const session = await this.get();
+    if (!session) {
+      if (request.deauthOnFailure) this.onUnauthorized?.(null);
+      return null;
+    }
+    const alreadyRenewed = request.expiredToken ? session.access_token !== request.expiredToken : !this.expiresSoon(session);
+    if (alreadyRenewed) {
+      return session.access_token;
+    }
+    if (!session.refresh_token || !this.refreshFn) {
+      if (request.deauthOnFailure) this.onUnauthorized?.(session);
+      return null;
+    }
+    return this.callRefreshFn(session, request);
+  }
+  async callRefreshFn(session, request) {
+    for (let attempt = 0; attempt <= MAX_RETRIES_ON_TEMPORARY_FAILURE; attempt += 1) {
+      if (attempt > 0) {
+        await sleep(RETRY_BACKOFF_BASE_IN_MS * 2 ** (attempt - 1));
+      }
+      const result = await this.refreshFn(session.refresh_token);
+      if (result.data?.access_token) {
+        await this.save(result.data);
+        this.onTokenRefreshed?.(result.data);
+        return result.data.access_token;
+      }
+      const error = result.error;
+      if (error && isTemporaryFailure(error)) {
+        continue;
+      }
+      if (request.deauthOnFailure && (!error || isSessionRefused(error))) {
+        await this.clear();
+        this.onUnauthorized?.(session);
+      }
+      return null;
+    }
+    return null;
+  }
+  /**
+   * Forces a token refresh regardless of expiry.
+   * Used for reactive refresh after a 401/403 response.
+   *
+   * Returns the new access token, or `null` if refresh fails.
+   *
+   * `deauthOnFailure` (default `true`) controls side effects when the refresh
+   * itself is refused: clearing the stored session and invoking `onUnauthorized`.
+   * Pass `false` for soft refreshes (e.g. 403/forbidden_resource_access) where
+   * the session must remain intact so the caller can surface the API error.
+   */
+  async forceRefresh(options = {}) {
+    const expiredToken = options.expiredToken ?? (await this.get())?.access_token;
+    return this.refresh({
+      deauthOnFailure: options.deauthOnFailure ?? true,
+      ...expiredToken !== void 0 ? { expiredToken } : {}
+    });
+  }
+  /**
+   * Returns a valid access token, refreshing it automatically if it is
+   * expired or about to expire (within the refresh margin).
+   *
+   * Returns `null` when there is no session or the refresh fails.
+   */
+  async getValidToken() {
+    const session = await this.get();
+    if (!session) return null;
+    if (!this.expiresSoon(session)) return session.access_token;
+    return this.refresh({ deauthOnFailure: true });
+  }
+  startAutoRefresh() {
+    if (this.ticker || !isBrowser()) return;
+    this.ticker = setInterval(() => void this.tick(), TICK_INTERVAL_IN_MS);
+    this.ticker.unref?.();
+    this.onVisibilityChange = () => {
+      if (!documentIsHidden()) void this.tick();
+    };
+    globalThis.document.addEventListener(
+      "visibilitychange",
+      this.onVisibilityChange
+    );
+  }
+  stopAutoRefresh() {
+    if (this.ticker) {
+      clearInterval(this.ticker);
+      this.ticker = void 0;
+    }
+    if (this.onVisibilityChange && isBrowser()) {
+      globalThis.document.removeEventListener(
+        "visibilitychange",
+        this.onVisibilityChange
+      );
+    }
+    this.onVisibilityChange = void 0;
+  }
+  async tick() {
+    if (documentIsHidden() || this.inFlight) return;
+    try {
+      const session = await this.get();
+      if (!session?.refresh_token || !this.expiresSoon(session)) return;
+      await runExclusive(this.lockName, () => this.refreshHoldingLock({ deauthOnFailure: true }), {
+        skipWhenBusy: true
+      });
+    } catch (error) {
+      console.error("[nulvless] scheduled token renewal failed", error);
+    }
+  }
+};
+
+// src/storage/adapters/local.ts
+var LocalStorageAdapter = class {
+  async getItem(key) {
+    return localStorage.getItem(key);
+  }
+  async setItem(key, value) {
+    localStorage.setItem(key, value);
+  }
+  async removeItem(key) {
+    localStorage.removeItem(key);
+  }
+};
+
+// src/storage/adapters/session.ts
+var SessionStorageAdapter = class {
+  async getItem(key) {
+    return sessionStorage.getItem(key);
+  }
+  async setItem(key, value) {
+    sessionStorage.setItem(key, value);
+  }
+  async removeItem(key) {
+    sessionStorage.removeItem(key);
+  }
+};
+
+// src/storage/adapters/memory.ts
+var MemoryStorageAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  async getItem(key) {
+    return this.store.get(key) ?? null;
+  }
+  async setItem(key, value) {
+    this.store.set(key, value);
+  }
+  async removeItem(key) {
+    this.store.delete(key);
+  }
+};
+
+// src/storage/adapters/cache.ts
+var CACHE_NAME = "nulvless";
+var CacheStorageAdapter = class {
+  key(k) {
+    return `https://nulvless.storage/${encodeURIComponent(k)}`;
+  }
+  async getItem(key) {
+    const cache = await caches.open(CACHE_NAME);
+    const response = await cache.match(this.key(key));
+    return response ? response.text() : null;
+  }
+  async setItem(key, value) {
+    const cache = await caches.open(CACHE_NAME);
+    await cache.put(this.key(key), new Response(value));
+  }
+  async removeItem(key) {
+    const cache = await caches.open(CACHE_NAME);
+    await cache.delete(this.key(key));
+  }
+};
+
+// src/storage/index.ts
+var Storage = {
+  /** `localStorage` — data survives page reloads and browser restarts. */
+  Local: new LocalStorageAdapter(),
+  /** `sessionStorage` — data is cleared when the tab or browser is closed. */
+  Session: new SessionStorageAdapter(),
+  /** In-memory `Map` — data is lost on page reload. Good for SSR and tests. */
+  Memory: new MemoryStorageAdapter(),
+  /** Cache Storage API — survives reloads, available in service workers. */
+  Cache: new CacheStorageAdapter()
+};
+
+// src/client.ts
+function defaultStorage() {
+  return typeof window !== "undefined" ? Storage.Local : new MemoryStorageAdapter();
+}
+var NulvlessClient = class {
+  auth;
+  constructor(baseUrl, publicKey, options) {
+    const base = baseUrl.replace(/\/+$/, "");
+    const subdomain = new URL(base).hostname.split(".")[0] ?? "app";
+    const tokenKey = options?.storageKeys?.token ?? `nlv-${subdomain}-token`;
+    const accountsKey = options?.storageKeys?.accounts ?? `${tokenKey}-accounts`;
+    const storage = options?.storage ?? defaultStorage();
+    const session = new SessionManager(storage, tokenKey);
+    this.auth = new AuthBrowserClient(
+      new HttpClient({
+        baseUrl: `${base}/auth`,
+        apiKey: publicKey,
+        ...options,
+        onTokenExpired: ({ deauthOnFailure, expiredToken }) => session.forceRefresh({
+          deauthOnFailure,
+          ...expiredToken ? { expiredToken } : {}
+        })
+      }),
+      session,
+      storage,
+      accountsKey,
+      options?.multiUser ?? false,
+      options?.autoRefresh ?? true
+    );
+  }
+};
+var NulvlessServerClient = class {
+  auth;
+  comms;
+  constructor(baseUrl, privateKey, options) {
+    const base = baseUrl.replace(/\/+$/, "");
+    this.auth = new AuthServerClient(new HttpClient({ baseUrl: `${base}/auth`, apiKey: privateKey, ...options }));
+    this.comms = new CommsClient(new HttpClient({ baseUrl: `${base}/notifications`, apiKey: privateKey, ...options }));
+  }
+};
+
+// src/helpers/forward-user-headers.ts
+var TRACKING_HEADERS = [
+  "authorization",
+  "user-agent",
+  "host",
+  "origin",
+  "referer",
+  "accept",
+  "accept-language",
+  "sec-fetch-dest",
+  "x-forwarded-for",
+  "x-forwarded-host",
+  "x-forwarded-proto",
+  "cloudfront-forwarded-proto"
+];
+function forwardUserHeaders(req) {
+  const result = {};
+  if (typeof Request !== "undefined" && req instanceof Request) {
+    for (const key of TRACKING_HEADERS) {
+      const val = req.headers.get(key);
+      if (val) result[key] = val;
+    }
+    return result;
+  }
+  const nodeHeaders = req.headers;
+  for (const key of TRACKING_HEADERS) {
+    const val = nodeHeaders[key];
+    if (val) result[key] = Array.isArray(val) ? val[0] : val;
+  }
+  return result;
+}
+
+// src/helpers/auth-cache-headers.ts
+var AUTH_CACHE_HEADERS = {
+  "Cache-Control": "private, no-cache, no-store, must-revalidate, max-age=0",
+  Expires: "0",
+  Pragma: "no-cache"
+};
+function isNodeResponse(response) {
+  return typeof response.setHeader === "function";
+}
+function isWebResponse(response) {
+  const headers = response.headers;
+  return typeof headers?.set === "function";
+}
+function applyAuthCacheHeaders(response) {
+  const entries = Object.entries(AUTH_CACHE_HEADERS);
+  if (isWebResponse(response)) {
+    for (const [name, value] of entries) response.headers.set(name, value);
+  } else if (isNodeResponse(response)) {
+    for (const [name, value] of entries) response.setHeader(name, value);
+  }
+  return response;
+}
+
+// src/index.ts
+function createClient(url, publicKey, options) {
+  return new NulvlessClient(url, publicKey, options);
+}
+function createServerClient(url, privateKey, options) {
+  return new NulvlessServerClient(url, privateKey, options);
+}
+
+export { AUTH_CACHE_HEADERS, AdminClient, AuthBrowserClient, AuthClient, AuthEventEmitter, AuthServerClient, CommsClient, EmailClient, FactorsClient, GrantsClient, HttpClient, NulvlessClient, NulvlessException, NulvlessServerClient, OAuthClient, OAuthGrantsClient, SecurityClient, SessionManager, SessionsClient, SmsClient, Storage, TemplatesClient, UsersClient, applyAuthCacheHeaders, createClient, createServerClient, forwardUserHeaders };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map