naro-js 0.1.0

package/dist/index.js

@@ -0,0 +1,1733 @@
+// src/errors.ts
+var INVALID_QUERY_MESSAGE = "The query is not a valid Naro query.";
+var INVALID_SESSION_MESSAGE = "The session is expired or not valid. Sign in again.";
+function networkError(cause) {
+  return {
+    code: "NETWORK_ERROR",
+    message: "The request did not reach the Naro backend. Check the url and the network.",
+    details: { cause: describe(cause) }
+  };
+}
+function requestTimeout(ms) {
+  return {
+    code: "TIMEOUT",
+    message: `The Naro backend did not answer within ${String(Math.round(ms / 1e3))} seconds. Check the network and try again.`
+  };
+}
+function invalidResponse(status) {
+  return {
+    code: "INVALID_RESPONSE",
+    message: `The server did not answer like a Naro backend (HTTP ${String(status)}).`,
+    details: { status }
+  };
+}
+function invalidQuery(path, reason) {
+  return {
+    code: "INVALID_QUERY",
+    message: INVALID_QUERY_MESSAGE,
+    details: { path, reason }
+  };
+}
+function invalidSession() {
+  return { code: "INVALID_SESSION", message: INVALID_SESSION_MESSAGE };
+}
+function codeVerifierMissing() {
+  return {
+    code: "CODE_VERIFIER_MISSING",
+    message: "This browser did not start this sign-in, so it cannot finish it. Sign in again here."
+  };
+}
+function passwordRecoveryRequired() {
+  return {
+    code: "PASSWORD_RECOVERY_REQUIRED",
+    message: "updateUser({ password }) works in the password recovery flow: open the link resetPasswordForEmail sent, then call it on that page."
+  };
+}
+function invalidProvider() {
+  return {
+    code: "VALIDATION_ERROR",
+    message: "provider must be google or github."
+  };
+}
+function cryptoUnavailable() {
+  return {
+    code: "CRYPTO_UNAVAILABLE",
+    message: "This runtime has no crypto.subtle, which signing in with a provider needs (https or localhost)."
+  };
+}
+function describe(cause) {
+  if (cause instanceof Error) return `${cause.name}: ${cause.message}`;
+  return String(cause);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asError(value) {
+  if (!isRecord(value)) return null;
+  const { code, message } = value;
+  if (typeof code !== "string" || code === "") return null;
+  if (typeof message !== "string") return null;
+  const error = { code, message };
+  if (value.details !== void 0) error.details = value.details;
+  return error;
+}
+function errorFromBody(status, body) {
+  if (isRecord(body) && body.error !== void 0 && body.error !== null)
+    return asError(body.error) ?? invalidResponse(status);
+  if (status >= 200 && status < 300) return null;
+  return invalidResponse(status);
+}
+
+// src/http.ts
+async function receive(config, options, init) {
+  const controller = options.timeoutMs !== void 0 && typeof AbortController === "function" ? new AbortController() : null;
+  if (controller) init.signal = controller.signal;
+  const request = (async () => {
+    try {
+      const fetchImpl = config.fetch ?? globalThis.fetch;
+      const response = await fetchImpl(
+        `${config.baseUrl}/_naro/v1${options.path}`,
+        init
+      );
+      return {
+        status: response.status,
+        headers: response.headers,
+        text: await response.text()
+      };
+    } catch (error) {
+      return { error: networkError(error) };
+    }
+  })();
+  const { timeoutMs } = options;
+  if (timeoutMs === void 0) return request;
+  let timer;
+  const expired = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller?.abort();
+      resolve({ error: requestTimeout(timeoutMs) });
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([request, expired]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function call(config, options) {
+  let payload;
+  if (options.body !== void 0) {
+    try {
+      payload = JSON.stringify(options.body);
+    } catch {
+      return { error: invalidQuery("", "is not JSON"), answer: null };
+    }
+  }
+  const token = options.withToken ? await config.tokens.get() : null;
+  const headers = { apikey: config.apiKey };
+  if (token !== null) headers.Authorization = `Bearer ${token}`;
+  const init = {
+    method: options.method,
+    headers,
+    // Identity is the bearer token alone. Better Auth also sets a session
+    // cookie (spec §13); a request that carried it would let any site act
+    // as the user. Workers accept the field (measured on workerd 1.20260815).
+    credentials: "omit"
+  };
+  if (payload !== void 0) {
+    headers["Content-Type"] = "application/json";
+    init.body = payload;
+  }
+  const received = await receive(config, options, init);
+  if ("error" in received) return { error: received.error, answer: null };
+  const { status, headers: responseHeaders, text } = received;
+  let body;
+  if (text.trim() !== "") {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      return { error: invalidResponse(status), answer: null };
+    }
+  }
+  const answer = { status, headers: responseHeaders, body, token };
+  const error = errorFromBody(status, body);
+  if (error === null) return { error: null, answer };
+  if (error.code === "INVALID_SESSION" && token !== null)
+    await config.tokens.clearIf(token);
+  if (RETRY_AFTER_CODES.has(error.code))
+    return { error: withRetryAfter(error, responseHeaders), answer };
+  return { error, answer };
+}
+var RETRY_AFTER_CODES = /* @__PURE__ */ new Set([
+  "RATE_LIMITED",
+  "WRITE_QUOTA_EXCEEDED"
+]);
+function withRetryAfter(error, headers) {
+  const header = headers.get("x-retry-after")?.trim() ?? "";
+  if (!/^\d{1,9}$/.test(header)) return error;
+  const { details } = error;
+  if (details !== void 0 && !isRecord(details)) return error;
+  return {
+    ...error,
+    details: { ...details, retryAfter: Number(header) }
+  };
+}
+
+// src/runtime.ts
+function isBrowser(scope = globalThis) {
+  const g = scope;
+  return g.window !== void 0 && g.document !== void 0;
+}
+function isWorkerd(g) {
+  return g.navigator?.userAgent === "Cloudflare-Workers";
+}
+function hasServerSignal(g) {
+  return isWorkerd(g) || // Vercel's edge runtime and Next.js's edge (middleware, edge routes).
+  typeof g.EdgeRuntime === "string" || typeof g.Deno?.version?.deno === "string" || typeof g.Bun?.version === "string" || // Node, and so the Next.js server. Browser polyfills of `process` leave
+  // `versions.node` out.
+  typeof g.process?.versions?.node === "string";
+}
+function hasDeviceSignal(g) {
+  if (g.window !== void 0 || g.document !== void 0) return true;
+  if (g.navigator?.product === "ReactNative") return true;
+  return !isWorkerd(g) && (g.WorkerGlobalScope !== void 0 || g.ServiceWorkerGlobalScope !== void 0);
+}
+function isKnownServer(scope = globalThis) {
+  const g = scope;
+  return hasServerSignal(g) && !hasDeviceSignal(g);
+}
+
+// src/auth/flow-errors.ts
+var CODE = /^[A-Z0-9_]{1,64}$/;
+var INVALID_CONFIRMATION = "The confirmation link is not valid. Ask for a new one.";
+var MESSAGES = {
+  INVALID_STATE: "This sign-in link is not valid or has expired. Start signing in again.",
+  OAUTH_BROWSER_MISMATCH: "This sign-in was started in another browser, or this browser did not keep its cookie. Start signing in again here.",
+  OAUTH_ACCESS_DENIED: "Signing in with the provider was cancelled.",
+  OAUTH_PROVIDER_EMAIL_NOT_VERIFIED: "Your email address is not verified with the provider. Verify it there, then sign in again.",
+  OAUTH_ACCOUNT_NOT_LINKED: "An account with this email already exists and is not linked to this provider. Sign in the way you signed up.",
+  PROVIDER_NOT_CONFIGURED: "Signing in with this provider is not set up for this project.",
+  RATE_LIMITED: "Too many sign-in attempts. Wait a few seconds and try again.",
+  INTERNAL_ERROR: "Something went wrong. Try again.",
+  PASSWORD_RESET_REQUIRED: "Your email is confirmed. Someone else also signed up with it before it was confirmed, so its password was cleared: choose a new one with a password reset.",
+  TOKEN_EXPIRED: "The confirmation link has expired. Ask for a new one.",
+  USER_NOT_FOUND: INVALID_CONFIRMATION
+};
+function flowError(type, raw) {
+  if (!CODE.test(raw))
+    return {
+      code: "AUTH_ERROR",
+      message: "Signing in did not finish. Try again."
+    };
+  if (raw === "INVALID_TOKEN")
+    return {
+      code: raw,
+      message: type === "recovery" ? "The password reset link is not valid, has expired or was already used. Ask for a new one." : INVALID_CONFIRMATION
+    };
+  const message = MESSAGES[raw];
+  if (message !== void 0) return { code: raw, message };
+  if (raw.startsWith("OAUTH_"))
+    return {
+      code: raw,
+      message: `Signing in with the provider did not finish (${raw}). Try again.`
+    };
+  return {
+    code: raw,
+    message: `Signing in did not finish (${raw}). Try again.`
+  };
+}
+
+// src/auth/pkce.ts
+function base64url(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+async function createPkcePair() {
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle === void 0) return null;
+  const verifier = base64url(
+    globalThis.crypto.getRandomValues(new Uint8Array(32))
+  );
+  const digest = await subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(verifier)
+  );
+  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+}
+
+// src/auth/client.ts
+var TOKEN_HEADER = "set-auth-token";
+var FRAGMENT_PREFIX = "naro_";
+var OAUTH_PROVIDERS = ["google", "github"];
+var FLOW_TYPES = [
+  "oauth",
+  "email_verification",
+  "recovery"
+];
+function defaultName(email) {
+  if (typeof email !== "string") return "";
+  const at = email.lastIndexOf("@");
+  return at > 0 ? email.slice(0, at) : email;
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value !== "" ? value : null;
+}
+function tokenFrom(answer) {
+  return nonEmpty(answer.headers.get(TOKEN_HEADER));
+}
+function userFrom(body) {
+  return isRecord(body) && isRecord(body.user) ? body.user : null;
+}
+function currentLocation() {
+  if (!isBrowser()) return null;
+  return globalThis.location ?? null;
+}
+function currentPage() {
+  const location = currentLocation();
+  if (!location) return void 0;
+  return `${location.origin}${location.pathname}${location.search}`;
+}
+function naroFragment() {
+  const hash = currentLocation()?.hash ?? "";
+  if (!hash.startsWith("#")) return null;
+  const params = new URLSearchParams(hash.slice(1));
+  const found = {};
+  for (const [key, value] of params)
+    if (key.startsWith(FRAGMENT_PREFIX)) found[key] = value;
+  return Object.keys(found).length > 0 ? found : null;
+}
+function clearFragment() {
+  const location = currentLocation();
+  const history = globalThis.history;
+  if (!location || !history?.replaceState) return;
+  try {
+    history.replaceState(
+      history.state,
+      "",
+      `${location.pathname}${location.search}`
+    );
+  } catch {
+  }
+}
+var EXCHANGE_TIMEOUT_MS = 15e3;
+var inFlight = /* @__PURE__ */ new WeakMap();
+function sharedInFlight(shared) {
+  return inFlight.get(shared.storage)?.get(shared.key) ?? null;
+}
+function share(shared, pending) {
+  let entries = inFlight.get(shared.storage);
+  if (!entries) {
+    entries = /* @__PURE__ */ new Map();
+    inFlight.set(shared.storage, entries);
+  }
+  entries.set(shared.key, pending);
+  void pending.finally(() => {
+    if (entries.get(shared.key) === pending) entries.delete(shared.key);
+  });
+}
+var AuthClient = class {
+  #http;
+  #flow;
+  /** The last `getSessionFromUrl()`, for callers after detection ran it. */
+  #fromUrl = null;
+  constructor(http, flow) {
+    this.#http = http;
+    this.#flow = flow;
+    if (flow.detectSessionInUrl) {
+      if (naroFragment() !== null) void this.getSessionFromUrl();
+      else this.#fromUrl = sharedInFlight(flow.shared);
+    }
+  }
+  /**
+   * Creates the account and signs in; the token is stored for later calls.
+   * When the project requires a confirmed email there is no session yet —
+   * `user` comes back, and after the confirmation link the user signs in.
+   */
+  async signUp(credentials) {
+    const { email, password } = credentials;
+    const name = credentials.name ?? defaultName(email);
+    const body = { email, password, name };
+    if (credentials.redirectTo !== void 0)
+      body.callbackURL = credentials.redirectTo;
+    return this.#signIn("/auth/sign-up/email", body, false);
+  }
+  async signIn(credentials) {
+    const { email, password } = credentials;
+    return this.#signIn("/auth/sign-in/email", { email, password }, true);
+  }
+  /**
+   * Starts a Google or GitHub sign-in: sends the browser, with a top-level
+   * navigation, to the worker's `GET /_naro/v1/auth/authorize/<provider>`,
+   * which checks `redirectTo`, binds the flow to this browser with a cookie
+   * and goes on to the provider (adversarial review I1). The provider sends
+   * the browser back to `redirectTo`, where `getSessionFromUrl()` (run by
+   * `createClient` on its own) finishes the sign-in. No request is made
+   * here: anything that goes wrong comes back in that page's URL.
+   */
+  async signInWithOAuth(options) {
+    const { provider } = options;
+    const failed = (error) => ({
+      data: { provider, url: null },
+      error
+    });
+    if (!OAUTH_PROVIDERS.includes(provider)) return failed(invalidProvider());
+    await this.#flow.recovery.forget();
+    const pair = await createPkcePair();
+    if (!pair) return failed(cryptoUnavailable());
+    await this.#flow.verifiers.add(pair.challenge, pair.verifier);
+    const redirectTo = options.redirectTo ?? currentPage();
+    const url = new URL(
+      `${this.#http.baseUrl}/_naro/v1/auth/authorize/${provider}`
+    );
+    if (redirectTo !== void 0)
+      url.searchParams.set("redirectTo", redirectTo);
+    url.searchParams.set("code_challenge", pair.challenge);
+    const location = currentLocation();
+    if (location && !options.skipBrowserRedirect) location.assign(url.href);
+    return { data: { provider, url: url.href }, error: null };
+  }
+  /**
+   * Trades the one-time code a sign-in redirect brought for the session,
+   * with the verifier this browser kept when it began that flow — `flow` is
+   * the redirect's `naro_flow`; without it, the newest flow's. Most apps
+   * never call it: `getSessionFromUrl()` does.
+   */
+  async exchangeCodeForSession(code, flow) {
+    const signedOut = { session: null, user: null };
+    const verifier = await this.#flow.verifiers.take(flow);
+    if (verifier === null)
+      return { data: signedOut, error: codeVerifierMissing() };
+    const result = await call(this.#http, {
+      method: "POST",
+      path: "/auth/exchange-code",
+      body: { code, codeVerifier: verifier },
+      withToken: false,
+      // The page's queries wait on this; they must not wait forever.
+      timeoutMs: EXCHANGE_TIMEOUT_MS
+    });
+    if (result.error !== null) return { data: signedOut, error: result.error };
+    const { body } = result.answer;
+    const token = tokenFrom(result.answer);
+    const user = userFrom(body);
+    if (token === null || user === null || !isRecord(body) || !isRecord(body.session))
+      return { data: signedOut, error: invalidResponse(result.answer.status) };
+    await this.#http.tokens.set(token);
+    await this.#flow.recovery.forget();
+    return { data: { session: body.session, user }, error: null };
+  }
+  /**
+   * Reads what a sign-in redirect left in this page's URL fragment, then
+   * clears it: a provider sign-in or a confirmation link hands over a
+   * session (traded here), a reset link a recovery token (kept for
+   * `updateUser`), and a failure its `code` and `message`. With nothing of
+   * Naro's in the URL, `type` is null — or, after `createClient` already
+   * read it, the answer it got.
+   */
+  getSessionFromUrl() {
+    const fragment = naroFragment();
+    if (fragment === null)
+      return this.#fromUrl ?? Promise.resolve({
+        data: { session: null, user: null, type: null },
+        error: null
+      });
+    clearFragment();
+    const answer = this.#answerOf(fragment);
+    this.#fromUrl = answer;
+    share(this.#flow.shared, answer);
+    return answer;
+  }
+  async #answerOf(fragment) {
+    const named = fragment.naro_type;
+    const type = named && FLOW_TYPES.includes(named) ? named : null;
+    const none = { session: null, user: null, type };
+    if (fragment.naro_error) {
+      if (fragment.naro_flow)
+        await this.#flow.verifiers.take(fragment.naro_flow);
+      return { data: none, error: flowError(type, fragment.naro_error) };
+    }
+    if (type === "recovery" && fragment.naro_token) {
+      await this.#http.tokens.clear();
+      await this.#flow.recovery.keep(fragment.naro_token);
+      return { data: none, error: null };
+    }
+    if (fragment.naro_code) {
+      const traded = await this.exchangeCodeForSession(
+        fragment.naro_code,
+        fragment.naro_flow
+      );
+      return { data: { ...traded.data, type }, error: traded.error };
+    }
+    return { data: none, error: null };
+  }
+  /**
+   * Emails a password reset link, when the address has an account. The
+   * answer is the same either way — it does not say whether it had one.
+   */
+  async resetPasswordForEmail(email, options = {}) {
+    const body = { email };
+    if (options.redirectTo !== void 0) body.redirectTo = options.redirectTo;
+    const result = await call(this.#http, {
+      method: "POST",
+      path: "/auth/request-password-reset",
+      body,
+      withToken: false
+    });
+    return { data: null, error: result.error };
+  }
+  /**
+   * Sets a new password in the recovery flow: on the page the reset link
+   * opened, after `getSessionFromUrl()` read its token. Signing in with the
+   * new password comes after — a reset ends every session of the account.
+   * (Changing the password of a signed-in user is not offered: spec §14
+   * "(P1-2 리뷰 반영)".)
+   *
+   * Like supabase-js, it acts on the recovery link's account, which took the
+   * place of any signed-in session when the link was read — so the token is
+   * used only while no session is signed in on this browser, for 15 minutes
+   * after the link was opened, and never after a sign-in, sign-up or
+   * sign-out forgot it (PR #68 review 6). Otherwise PASSWORD_RECOVERY_REQUIRED,
+   * with no request.
+   */
+  async updateUser(attributes) {
+    await this.#pendingUrl();
+    if (await this.#http.tokens.get() !== null)
+      return { data: null, error: passwordRecoveryRequired() };
+    const token = await this.#flow.recovery.current();
+    if (token === null)
+      return { data: null, error: passwordRecoveryRequired() };
+    const result = await call(this.#http, {
+      method: "POST",
+      path: "/auth/reset-password",
+      body: { newPassword: attributes.password, token },
+      withToken: false
+    });
+    if (result.error === null || result.error.code === "INVALID_TOKEN")
+      await this.#flow.recovery.forgetIf(token);
+    return { data: null, error: result.error };
+  }
+  /**
+   * Emails the confirmation link again, when the address has an account that
+   * is not confirmed yet. The answer does not say which.
+   */
+  async resendVerification(email, options = {}) {
+    const body = { email };
+    if (options.redirectTo !== void 0) body.callbackURL = options.redirectTo;
+    const result = await call(this.#http, {
+      method: "POST",
+      path: "/auth/send-verification-email",
+      body,
+      withToken: false
+    });
+    return { data: null, error: result.error };
+  }
+  /**
+   * Ends the session on the worker and forgets the token. The token is
+   * forgotten even when the worker cannot be reached — the error still comes
+   * back, since the session then lives on until it expires.
+   */
+  async signOut() {
+    await this.#pendingUrl();
+    await this.#flow.recovery.forget();
+    const tokens = this.#http.tokens;
+    const token = await tokens.get();
+    if (token === null) return { data: null, error: null };
+    const result = await call(this.#http, {
+      method: "POST",
+      path: "/auth/sign-out",
+      withToken: true
+    });
+    await tokens.clearIf(result.answer?.token ?? token);
+    return { data: null, error: result.error };
+  }
+  /**
+   * The signed-in session and user. Signed out: both null, no request. A
+   * stored token the worker no longer accepts is forgotten and reported as
+   * INVALID_SESSION once (spec §11.1: a session never quietly turns anon).
+   * Waits for a sign-in the page URL carried, if `createClient` found one.
+   */
+  async getSession() {
+    await this.#pendingUrl();
+    const signedOut = { session: null, user: null };
+    const tokens = this.#http.tokens;
+    if (await tokens.get() === null) return { data: signedOut, error: null };
+    const result = await call(this.#http, {
+      method: "GET",
+      path: "/auth/get-session",
+      withToken: true
+    });
+    if (result.error !== null) return { data: signedOut, error: result.error };
+    const { body, token } = result.answer;
+    if (body === null) {
+      if (token !== null) await tokens.clearIf(token);
+      return { data: signedOut, error: invalidSession() };
+    }
+    const user = userFrom(body);
+    if (!isRecord(body) || !isRecord(body.session) || user === null)
+      return { data: signedOut, error: invalidResponse(result.answer.status) };
+    const renewed = tokenFrom(result.answer);
+    if (renewed !== null && token !== null && renewed !== token)
+      await tokens.replaceIf(token, renewed);
+    return { data: { session: body.session, user }, error: null };
+  }
+  /** `{ data: { user } }`; `user` is null when signed out. */
+  async getUser() {
+    const { data, error } = await this.getSession();
+    return { data: { user: data.user }, error };
+  }
+  /**
+   * Resolves once a sign-in the page URL carried has been traded for its
+   * session (or failed), with its error. Queries wait for it, so the first
+   * one after a provider's redirect goes out signed in rather than as anon.
+   * The exchange gives up after 15 seconds (TIMEOUT, PR #68 review 10):
+   * then the queries go out as anon rather than wait forever.
+   */
+  async ready() {
+    if (!this.#fromUrl) return { error: null };
+    return { error: (await this.#fromUrl).error };
+  }
+  /** Waits for a URL sign-in in flight; its outcome is not this call's. */
+  async #pendingUrl() {
+    if (this.#fromUrl) await this.#fromUrl;
+  }
+  async #signIn(path, body, needsToken) {
+    await this.#flow.recovery.forget();
+    const result = await call(this.#http, {
+      method: "POST",
+      path,
+      body,
+      withToken: false
+    });
+    if (result.error !== null)
+      return { data: { user: null }, error: result.error };
+    const { body: answerBody } = result.answer;
+    const user = userFrom(answerBody);
+    const token = tokenFrom(result.answer);
+    const opened = isRecord(answerBody) && nonEmpty(answerBody.token) !== null;
+    if (user === null || (needsToken || opened) && token === null)
+      return {
+        data: { user: null },
+        error: invalidResponse(result.answer.status)
+      };
+    if (token !== null) await this.#http.tokens.set(token);
+    return { data: { user }, error: null };
+  }
+};
+
+// src/auth/flows.ts
+var FLOW_TTL_MS = 10 * 6e4;
+var MAX_FLOWS = 10;
+function isEntry(value) {
+  return typeof value === "object" && value !== null && typeof value.verifier === "string" && typeof value.expiresAt === "number";
+}
+function live(text, now) {
+  if (text === null) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null) return {};
+  const entries = {};
+  for (const [flow, entry] of Object.entries(parsed))
+    if (isEntry(entry) && entry.expiresAt > now) entries[flow] = entry;
+  return entries;
+}
+function pick(entries, oldest) {
+  let found;
+  for (const pair of Object.entries(entries))
+    if (found === void 0 || (oldest ? pair[1].expiresAt < found[1].expiresAt : pair[1].expiresAt > found[1].expiresAt))
+      found = pair;
+  return found?.[0];
+}
+function serialize(entries) {
+  return Object.keys(entries).length > 0 ? JSON.stringify(entries) : null;
+}
+var FlowVerifiers = class {
+  #store;
+  #now;
+  constructor(store, now = Date.now) {
+    this.#store = store;
+    this.#now = now;
+  }
+  /** Keeps `verifier` for the flow `flow`, for ten minutes. */
+  async add(flow, verifier) {
+    const now = this.#now();
+    await this.#store.update((text) => {
+      const entries = live(text, now);
+      entries[flow] = { verifier, expiresAt: now + FLOW_TTL_MS };
+      while (Object.keys(entries).length > MAX_FLOWS) {
+        const oldest = pick(entries, true);
+        if (oldest === void 0) break;
+        delete entries[oldest];
+      }
+      return serialize(entries);
+    });
+  }
+  /**
+   * The verifier of `flow`, taken — one flow, one use. Without a flow id
+   * (a code traded by hand), the newest one. Null when there is none, or it
+   * expired.
+   */
+  async take(flow) {
+    const now = this.#now();
+    let taken = null;
+    await this.#store.update((text) => {
+      const entries = live(text, now);
+      const id = flow ?? pick(entries, false);
+      if (id !== void 0 && Object.hasOwn(entries, id)) {
+        taken = entries[id]?.verifier ?? null;
+        delete entries[id];
+      }
+      return serialize(entries);
+    });
+    return taken;
+  }
+};
+
+// src/auth/recovery.ts
+var RECOVERY_TTL_MS = 15 * 6e4;
+function parse(text) {
+  if (text === null) return null;
+  try {
+    const value = JSON.parse(text);
+    if (typeof value === "object" && value !== null && typeof value.token === "string" && value.token !== "" && typeof value.expiresAt === "number")
+      return value;
+  } catch {
+  }
+  return null;
+}
+var RecoveryToken = class {
+  #store;
+  #now;
+  constructor(store, now = () => Date.now()) {
+    this.#store = store;
+    this.#now = now;
+  }
+  /** Keeps the token a recovery link brought, for 15 minutes. */
+  async keep(token) {
+    const kept = { token, expiresAt: this.#now() + RECOVERY_TTL_MS };
+    await this.#store.set(JSON.stringify(kept));
+  }
+  /** The token, while it lasts; an expired or unreadable one is cleared. */
+  async current() {
+    const now = this.#now();
+    let token = null;
+    await this.#store.update((text) => {
+      const kept = parse(text);
+      if (kept === null || kept.expiresAt <= now) return null;
+      token = kept.token;
+      return text;
+    });
+    return token;
+  }
+  /** Forgets it: a sign-in, a sign-up, a sign-out. */
+  async forget() {
+    await this.#store.clear();
+  }
+  /** Forgets it if it is still `token` — used, or refused as used. */
+  async forgetIf(token) {
+    await this.#store.update(
+      (text) => parse(text)?.token === token ? null : text
+    );
+  }
+};
+
+// src/auth/storage.ts
+function memoryStorage() {
+  const items2 = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => items2.get(key) ?? null,
+    setItem: (key, value) => {
+      items2.set(key, value);
+    },
+    removeItem: (key) => {
+      items2.delete(key);
+    }
+  };
+}
+function defaultStorage() {
+  if (!isBrowser()) return memoryStorage();
+  try {
+    const storage = globalThis.localStorage;
+    if (storage === void 0 || storage === null) return memoryStorage();
+    const probe = "naro-storage-probe";
+    storage.setItem(probe, probe);
+    storage.removeItem(probe);
+    return storage;
+  } catch {
+    return memoryStorage();
+  }
+}
+function storageKey(baseUrl) {
+  return `naro-auth-token:${baseUrl}`;
+}
+function verifierKey(baseUrl) {
+  return `naro-auth-code-verifiers:${baseUrl}`;
+}
+function recoveryKey(baseUrl) {
+  return `naro-auth-recovery:${baseUrl}`;
+}
+var TokenStore = class {
+  #storage;
+  #key;
+  #fallback = null;
+  /** Settles when the last queued operation has finished. */
+  #queue = Promise.resolve();
+  constructor(storage, key) {
+    this.#storage = storage;
+    this.#key = key;
+  }
+  get() {
+    return this.#serial(() => this.#get());
+  }
+  set(token) {
+    return this.#serial(() => this.#set(token));
+  }
+  clear() {
+    return this.#serial(() => this.#clear());
+  }
+  /**
+   * Clears only if the stored token is still the one that was rejected. A
+   * request that left with an old token can come back after the user signed
+   * in again; its INVALID_SESSION must not sign the new session out. The
+   * read and the removal are one operation: with an async storage, a sign-in
+   * that lands between them would otherwise be the token removed.
+   */
+  clearIf(token) {
+    return this.#serial(async () => {
+      if (await this.#get() === token) await this.#clear();
+    });
+  }
+  /**
+   * Reads the value, hands it to `transform` and stores what that returns
+   * (null clears it), as one operation — the per-flow verifiers
+   * (`flows.ts`) change one entry of a JSON object this way.
+   */
+  update(transform) {
+    return this.#serial(async () => {
+      const next = transform(await this.#get());
+      if (next === null) await this.#clear();
+      else await this.#set(next);
+    });
+  }
+  /** Stores `next` only if `expected` is still stored, as one operation. */
+  replaceIf(expected, next) {
+    return this.#serial(async () => {
+      if (await this.#get() === expected) await this.#set(next);
+    });
+  }
+  /**
+   * Runs `operation` once every earlier one has finished. The operations
+   * below never reject, and none of them calls a public method (that would
+   * wait on itself).
+   */
+  #serial(operation) {
+    const result = this.#queue.then(operation);
+    this.#queue = result.catch(() => void 0);
+    return result;
+  }
+  async #get() {
+    if (this.#fallback) return this.#fallback.token;
+    try {
+      const token = await this.#storage.getItem(this.#key);
+      return typeof token === "string" && token !== "" ? token : null;
+    } catch {
+      await this.#fallBack(null, true);
+      return null;
+    }
+  }
+  async #set(token) {
+    if (this.#fallback) {
+      this.#fallback.token = token;
+      return;
+    }
+    try {
+      await this.#storage.setItem(this.#key, token);
+    } catch {
+      await this.#fallBack(token, true);
+    }
+  }
+  async #clear() {
+    if (this.#fallback) {
+      this.#fallback.token = null;
+      return;
+    }
+    try {
+      await this.#storage.removeItem(this.#key);
+    } catch {
+      await this.#fallBack(null, false);
+    }
+  }
+  /**
+   * Stops using the storage, keeping `token` in memory. The token the storage
+   * still holds is removed once, if it lets us: left there it comes back on
+   * the next load — after a sign-out that could not read it, or over a
+   * sign-in whose write failed (the previous user's session).
+   */
+  async #fallBack(token, removeStored) {
+    this.#fallback = { token };
+    if (!removeStored) return;
+    try {
+      await this.#storage.removeItem(this.#key);
+    } catch {
+    }
+  }
+};
+
+// src/query/columns.ts
+function isSpace(char) {
+  return char.trim() === "";
+}
+function tokenize(input) {
+  const tokens = [];
+  let index = 0;
+  const at = () => input[index] ?? "";
+  for (; ; ) {
+    while (index < input.length && isSpace(at())) index++;
+    let token;
+    if (at() === '"') {
+      index++;
+      let name = "";
+      for (; ; ) {
+        if (index >= input.length)
+          return `has an unclosed quote in column ${String(tokens.length + 1)}`;
+        const char = at();
+        index++;
+        if (char !== '"') name += char;
+        else if (at() === '"') {
+          name += '"';
+          index++;
+        } else break;
+      }
+      while (index < input.length && isSpace(at())) index++;
+      if (index < input.length && at() !== ",")
+        return `has text after the closing quote of column ${String(tokens.length + 1)}`;
+      token = { name, quoted: true };
+    } else {
+      let name = "";
+      while (index < input.length && at() !== ",") {
+        if (at() === '"')
+          return `has a quote inside column ${String(tokens.length + 1)}; quote the whole name`;
+        name += at();
+        index++;
+      }
+      token = { name: name.trim(), quoted: false };
+    }
+    tokens.push(token);
+    if (index >= input.length) return tokens;
+    index++;
+  }
+}
+function parseColumns(input) {
+  if (input === void 0) return { ok: true, columns: "*" };
+  if (typeof input !== "string")
+    return { ok: false, reason: "must be a string of column names" };
+  const tokens = tokenize(input);
+  if (typeof tokens === "string") return { ok: false, reason: tokens };
+  const star = tokens.findIndex((token) => !token.quoted && token.name === "*");
+  if (star >= 0) {
+    if (tokens.length === 1) return { ok: true, columns: "*" };
+    return { ok: false, reason: '"*" cannot be combined with column names' };
+  }
+  const empty = tokens.findIndex((token) => token.name === "");
+  if (empty >= 0)
+    return {
+      ok: false,
+      reason: tokens.length === 1 ? "must name at least one column" : `has an empty column name at position ${String(empty + 1)}`
+    };
+  return { ok: true, columns: tokens.map((token) => token.name) };
+}
+
+// src/query/filters.ts
+var MAX_FILTER_DEPTH = 4;
+var OPERATORS = {
+  eq: "eq",
+  neq: "neq",
+  gt: "gt",
+  gte: "gte",
+  lt: "lt",
+  lte: "lte",
+  in: "in",
+  is: "is",
+  like: "like",
+  ilike: "ilike",
+  contains: "contains",
+  containedBy: "containedBy",
+  overlaps: "overlaps",
+  cs: "contains",
+  cd: "containedBy",
+  ov: "overlaps"
+};
+function operatorOf(name) {
+  return typeof name === "string" && Object.hasOwn(OPERATORS, name) ? OPERATORS[name] : void 0;
+}
+var Refusal = class extends Error {
+};
+function refuse(reason) {
+  throw new Refusal(reason);
+}
+var LIST_HINT = {
+  in: ["(", ")", "needs a list in parentheses, like in.(a,b),"],
+  array: ["{", "}", "needs a list in braces, like cs.{a,b},"]
+};
+function isSpace2(char) {
+  return char !== "" && char.trim() === "";
+}
+function looseWord(text) {
+  return text.replace(/\s+/g, "").toLowerCase().replace(/\(\)$/, "");
+}
+var Parser = class {
+  constructor(text, tokens = {}) {
+    this.text = text;
+    this.tokens = tokens;
+  }
+  index = 0;
+  /**
+   * A token at the next value, followed only by spaces and then one of
+   * `stops` or the end — `auth.uid()x` is text, not the token.
+   */
+  token(stops) {
+    this.skipSpaces();
+    const at = this.index;
+    for (const [word, value] of Object.entries(this.tokens)) {
+      if (!this.text.startsWith(word, at)) continue;
+      let end = at + word.length;
+      while (isSpace2(this.text[end] ?? "")) end++;
+      const next = this.text[end] ?? "";
+      if (next !== "" && !stops.includes(next)) continue;
+      this.index = end;
+      return { value, word, at };
+    }
+    return void 0;
+  }
+  at() {
+    return this.text[this.index] ?? "";
+  }
+  /**
+   * An unquoted value that is one of the tokens misspelled — `auth.uid`,
+   * `AUTH.UID` — is refused: read as text it would compare with the words
+   * themselves (사용자 리뷰 반영). Quoted, it is the text.
+   */
+  notNearToken(value, at) {
+    const loose = looseWord(value);
+    for (const word of Object.keys(this.tokens))
+      if (loose !== "" && loose === looseWord(word))
+        refuse(
+          `has ${JSON.stringify(value)} ${this.where(at)}: did you mean ${word}? Quote it to mean the text`
+        );
+  }
+  /** `scalar`, with an unquoted value held to notNearToken. */
+  bareOrQuoted(stops) {
+    this.skipSpaces();
+    const at = this.index;
+    const quoted = this.at() === '"';
+    const text = this.scalar(stops);
+    if (!quoted) this.notNearToken(text, at);
+    return { text, quoted };
+  }
+  where(index = this.index) {
+    return `at character ${String(index + 1)}`;
+  }
+  skipSpaces() {
+    while (isSpace2(this.at())) this.index++;
+  }
+  /** `item ("," item)*`, up to a `)` or the end, inside `level` groups. */
+  list(level) {
+    const nodes = [];
+    for (; ; ) {
+      nodes.push(this.item(level));
+      this.skipSpaces();
+      const char = this.at();
+      if (char === ",") this.index++;
+      else if (char === ")" || char === "") return nodes;
+      else refuse(`has unexpected text ${this.where()}`);
+    }
+  }
+  item(level) {
+    this.skipSpaces();
+    const start = this.index;
+    const char = this.at();
+    if (char === "" || char === "," || char === ")")
+      refuse(`has an empty item ${this.where()}`);
+    const group = /^(not\.)?(and|or)\(/.exec(this.text.slice(start));
+    if (!group) return this.leaf(level);
+    const negated = group[1] !== void 0;
+    const inner = level + (negated ? 2 : 1);
+    if (inner > MAX_FILTER_DEPTH)
+      refuse(`nests deeper than ${String(MAX_FILTER_DEPTH)} groups`);
+    const open = start + group[0].length - 1;
+    this.index = open + 1;
+    const children = this.list(inner);
+    if (this.at() !== ")") refuse(`has an unclosed "(" ${this.where(open)}`);
+    this.index++;
+    const node = group[2] === "or" ? { or: children } : { and: children };
+    return negated ? { not: node } : node;
+  }
+  /** `column.[not.]operator.value`. */
+  leaf(level) {
+    const start = this.index;
+    const column = this.at() === '"' ? this.quoted() : this.word().trim();
+    if (column === "" || this.at() !== ".")
+      refuse(`needs column.operator.value ${this.where(start)}`);
+    this.index++;
+    let nameAt = this.index;
+    let name = this.word();
+    let negated = false;
+    if (name === "not" && this.at() === ".") {
+      if (level + 1 > MAX_FILTER_DEPTH)
+        refuse(`nests deeper than ${String(MAX_FILTER_DEPTH)} groups`);
+      negated = true;
+      this.index++;
+      nameAt = this.index;
+      name = this.word();
+    }
+    const operator = operatorOf(name);
+    if (this.at() !== ".") {
+      if (name !== "" && operator === void 0)
+        refuse(`has an unknown operator "${name}" ${this.where(nameAt)}`);
+      refuse(`needs column.operator.value ${this.where(start)}`);
+    }
+    if (operator === void 0)
+      refuse(`has an unknown operator "${name}" ${this.where(nameAt)}`);
+    this.index++;
+    const leaf = { operator, column, value: this.value(operator) };
+    return negated ? { not: leaf } : leaf;
+  }
+  /** Up to the next `.`, `,`, `(`, `)` or the end. */
+  word() {
+    const start = this.index;
+    while (this.index < this.text.length && !".,()".includes(this.at()))
+      this.index++;
+    return this.text.slice(start, this.index);
+  }
+  /** `"…"`, with `\` making the next character literal. */
+  quoted() {
+    const start = this.index;
+    this.index++;
+    let text = "";
+    for (; ; ) {
+      if (this.index >= this.text.length)
+        refuse(`has an unclosed quote ${this.where(start)}`);
+      const char = this.at();
+      this.index++;
+      if (char === '"') return text;
+      if (char === "\\" && this.index < this.text.length) {
+        text += this.at();
+        this.index++;
+      } else text += char;
+    }
+  }
+  /** A quoted value, or everything up to `stops`, trimmed. */
+  scalar(stops) {
+    this.skipSpaces();
+    if (this.at() === '"') {
+      const text = this.quoted();
+      this.skipSpaces();
+      if (this.at() !== "" && !stops.includes(this.at()))
+        refuse(`has text after a closing quote ${this.where()}`);
+      return text;
+    }
+    const start = this.index;
+    while (this.index < this.text.length && !stops.includes(this.at()))
+      this.index++;
+    return this.text.slice(start, this.index).trim();
+  }
+  /**
+   * `(a,b)` for `in`: text values, except that an unquoted `true` or `false`
+   * is a boolean (사용자 리뷰 반영, as in `eq`). `{a,b}` for the array
+   * operators: text, except that an unquoted exact decimal is a number
+   * (적대적 리뷰 반영, narrowed by 사용자 리뷰 반영) — json_each's values
+   * have no type affinity to turn the text "1" into 1, so as text `cs.{1}`
+   * matched no numeric array and `not.ov.{1}` matched every row. Quoted,
+   * `"1"` and `"true"` stay text.
+   */
+  listValue(kind) {
+    const [open, close, hint] = LIST_HINT[kind];
+    this.skipSpaces();
+    const openAt = this.index;
+    if (this.at() !== open) refuse(`${hint} ${this.where()}`);
+    this.index++;
+    this.skipSpaces();
+    const values = [];
+    if (this.at() === close) {
+      this.index++;
+      return values;
+    }
+    for (; ; ) {
+      this.skipSpaces();
+      const itemAt = this.index;
+      const token = this.token(`,${close}`);
+      if (token) values.push(token.value);
+      else {
+        const { text: value, quoted } = this.bareOrQuoted(`,${close}`);
+        if (!quoted && value === "") {
+          if (this.index >= this.text.length)
+            refuse(`has an unclosed "${open}" ${this.where(openAt)}`);
+          refuse(`has an empty item ${this.where(itemAt)}`);
+        }
+        values.push(
+          quoted ? value : kind === "array" ? exactNumber(value) : truth(value)
+        );
+      }
+      if (this.index >= this.text.length)
+        refuse(`has an unclosed "${open}" ${this.where(openAt)}`);
+      const char = this.at();
+      this.index++;
+      if (char === close) return values;
+    }
+  }
+  /** The value after `operator.`. */
+  value(operator) {
+    const start = this.index;
+    switch (operator) {
+      case "in":
+        return this.listValue("in");
+      case "contains":
+      case "containedBy":
+      case "overlaps":
+        return this.listValue("array");
+      case "is":
+        return keyword(this.scalar(",)"), start);
+      case "like":
+      case "ilike": {
+        const token = this.token(",)");
+        if (token)
+          refuse(
+            `cannot use ${token.word} with ${operator} ${this.where(token.at)}`
+          );
+        return likePattern(this.bareOrQuoted(",)").text);
+      }
+      case "eq":
+      case "neq": {
+        const token = this.token(",)");
+        if (token) return token.value;
+        const { text, quoted } = this.bareOrQuoted(",)");
+        return quoted ? text : truth(text);
+      }
+      default: {
+        const token = this.token(",)");
+        return token ? token.value : this.bareOrQuoted(",)").text;
+      }
+    }
+  }
+};
+function likePattern(pattern) {
+  return pattern.replaceAll("*", "%");
+}
+function truth(text) {
+  const word = text.toLowerCase();
+  if (word === "true") return true;
+  if (word === "false") return false;
+  return text;
+}
+var DECIMAL = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+function exactNumber(text) {
+  if (!DECIMAL.test(text)) return text;
+  const number = Number(text);
+  if (!text.includes(".")) return Number.isSafeInteger(number) ? number : text;
+  const trimmed = text.replace(/\.?0+$/, "");
+  return String(number) === trimmed ? number : text;
+}
+function quoteFilterValue(value) {
+  const text = String(value);
+  return `"${text.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function keyword(text, at) {
+  const word = text.toLowerCase();
+  if (word === "null") return null;
+  if (word === "true") return true;
+  if (word === "false") return false;
+  return refuse(
+    `needs null, true or false after is at character ${String(at + 1)}`
+  );
+}
+function attempt(parse2) {
+  try {
+    return { ok: true, node: parse2() };
+  } catch (error) {
+    if (error instanceof Refusal) return { ok: false, reason: error.message };
+    throw error;
+  }
+}
+function parseLogic(text, kind, options = {}) {
+  if (typeof text !== "string")
+    return { ok: false, reason: "must be a filter string or a function" };
+  if (text.trim() === "") return { ok: false, reason: "must not be empty" };
+  return attempt(() => {
+    if (options.group === false) {
+      const alone = items(text, options.tokens, 0);
+      if (alone.length === 1 && alone[0]) return alone[0];
+    }
+    const nodes = items(text, options.tokens, 1);
+    return kind === "or" ? { or: nodes } : { and: nodes };
+  });
+}
+function items(text, tokens, level) {
+  const parser = new Parser(text, tokens);
+  const nodes = parser.list(level);
+  if (parser.at() === ")") refuse(`has an unmatched ")" ${parser.where()}`);
+  return nodes;
+}
+function conditionOf(column, name, value) {
+  const operator = operatorOf(name);
+  if (operator === void 0)
+    return { ok: false, reason: `has an unknown operator "${String(name)}"` };
+  if (typeof value !== "string")
+    return {
+      ok: true,
+      node: {
+        operator,
+        column,
+        value: Array.isArray(value) ? [...value] : value
+      }
+    };
+  return attempt(() => {
+    const parser = new Parser(value);
+    let parsed = value;
+    if (["in", "contains", "containedBy", "overlaps", "is"].includes(operator)) {
+      parsed = parser.value(operator);
+      parser.skipSpaces();
+      if (parser.at() !== "") refuse(`has unexpected text ${parser.where()}`);
+    } else if (operator === "like" || operator === "ilike")
+      parsed = likePattern(value);
+    else if (operator === "eq" || operator === "neq") parsed = truth(value);
+    return { operator, column, value: parsed };
+  });
+}
+
+// src/query/builder.ts
+function patternOf(pattern) {
+  return typeof pattern === "string" ? likePattern(pattern) : pattern;
+}
+var MAX_LIMIT = 1e3;
+var CAP = `one select reads at most ${String(MAX_LIMIT)} rows, by limit() or range()`;
+function initialState(table) {
+  return { table, problem: null, filters: [], columns: "*", order: [] };
+}
+function copyRow(row) {
+  return { ...row };
+}
+var Builder = class {
+  run;
+  state;
+  constructor(run, state) {
+    this.run = run;
+    this.state = state;
+  }
+  /** A new builder of the same kind with `patch` applied. */
+  next(patch) {
+    const Next = this.constructor;
+    return new Next(this.run, { ...this.state, ...patch });
+  }
+  fail(path, reason) {
+    return this.failWith(invalidQuery(path, reason));
+  }
+  /** Keeps the first problem: it is the one the user has to fix first. */
+  failWith(problem) {
+    if (this.state.problem !== null) return this;
+    return this.next({ problem });
+  }
+  /**
+   * Runs the query. Every `await` sends a new request with the same AST.
+   * Never rejects: failures resolve as `{ data: null, error }`.
+   */
+  // oxlint-disable-next-line unicorn/no-thenable -- awaitable builders are the API (spec §15)
+  then(onfulfilled, onrejected) {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  async execute() {
+    if (this.state.problem !== null)
+      return { data: null, error: this.state.problem };
+    return await this.run(this.build());
+  }
+  /** A mutation's `.select()`: RETURNING these columns. */
+  withReturning(columns) {
+    const parsed = parseColumns(columns);
+    if (!parsed.ok) return this.fail("returning", parsed.reason);
+    return this.next({ returning: parsed.columns });
+  }
+};
+function copyList(values) {
+  return Array.isArray(values) ? [...values] : values;
+}
+var FilterBuilder = class _FilterBuilder extends Builder {
+  /** One more entry in the top-level list, which is an AND. */
+  add(node) {
+    return this.next({ filters: [...this.state.filters, node] });
+  }
+  condition(operator, column, value) {
+    return this.add({ operator, column, value });
+  }
+  eq(column, value) {
+    return this.condition("eq", column, value);
+  }
+  neq(column, value) {
+    return this.condition("neq", column, value);
+  }
+  gt(column, value) {
+    return this.condition("gt", column, value);
+  }
+  gte(column, value) {
+    return this.condition("gte", column, value);
+  }
+  lt(column, value) {
+    return this.condition("lt", column, value);
+  }
+  lte(column, value) {
+    return this.condition("lte", column, value);
+  }
+  /** An empty list matches nothing. */
+  in(column, values) {
+    return this.condition("in", column, copyList(values));
+  }
+  /** `IS NULL`, `IS TRUE` or `IS FALSE` — any non-zero number is true, NULL neither. */
+  is(column, value) {
+    return this.condition("is", column, value);
+  }
+  /**
+   * Case-sensitive, `%` and `_` as in SQL; `*` is `%` too, as in PostgREST,
+   * so a literal `*` cannot be matched.
+   */
+  like(column, pattern) {
+    return this.condition("like", column, patternOf(pattern));
+  }
+  /** Case-insensitive for ASCII letters; `%`, `_` and `*` as in `like`. */
+  ilike(column, pattern) {
+    return this.condition("ilike", column, patternOf(pattern));
+  }
+  /**
+   * The column — TEXT holding a JSON array — has every one of the values.
+   * A row that is not a JSON array is no match; NULL is neither.
+   */
+  contains(column, values) {
+    return this.condition("contains", column, copyList(values));
+  }
+  /** Every element of the column's JSON array is one of the values (`[]` is). */
+  containedBy(column, values) {
+    return this.condition("containedBy", column, copyList(values));
+  }
+  /** The column's JSON array has at least one of the values. */
+  overlaps(column, values) {
+    return this.condition("overlaps", column, copyList(values));
+  }
+  /** An `eq` for each key, in key order. */
+  match(query) {
+    const conditions = Object.entries(query).map(
+      ([column, value]) => ({
+        operator: "eq",
+        column,
+        value
+      })
+    );
+    return this.next({ filters: [...this.state.filters, ...conditions] });
+  }
+  /**
+   * Any operator by name, Supabase's escape hatch: `filter("id", "in",
+   * "(1,2)")`, `filter("tags", "cs", "{a}")`, `filter("n", "not.gte", 10)`.
+   * A string value is PostgREST syntax where the operator needs one, and text
+   * otherwise.
+   */
+  filter(column, operator, value) {
+    const name = operator;
+    const negated = typeof name === "string" && name.startsWith("not.");
+    const parsed = conditionOf(
+      column,
+      negated ? name.slice(4) : name,
+      value
+    );
+    if (!parsed.ok) return this.fail("filter", parsed.reason);
+    return this.add(negated ? { not: parsed.node } : parsed.node);
+  }
+  not(target, operator, value) {
+    if (typeof target === "function") {
+      const nodes = this.group("not", target);
+      if (!Array.isArray(nodes)) return this.failWith(nodes);
+      const [only] = nodes;
+      return this.add({
+        not: nodes.length === 1 && only ? only : { and: nodes }
+      });
+    }
+    const parsed = conditionOf(target, operator, value);
+    if (!parsed.ok) return this.fail("not", parsed.reason);
+    return this.add({ not: parsed.node });
+  }
+  /**
+   * Rows matching at least one of the conditions: a callback,
+   * `or((q) => q.eq("status", "draft").lt("price", 10))`, or Supabase's
+   * string, `or("status.eq.draft,price.lt.10")`, whose values are text.
+   */
+  or(filters) {
+    return this.logic("or", filters);
+  }
+  /** Rows matching all of the conditions, as a group: for use inside `or`. */
+  and(filters) {
+    return this.logic("and", filters);
+  }
+  logic(kind, filters) {
+    if (typeof filters === "function") {
+      const nodes = this.group(kind, filters);
+      if (!Array.isArray(nodes)) return this.failWith(nodes);
+      return this.add(kind === "or" ? { or: nodes } : { and: nodes });
+    }
+    const parsed = parseLogic(filters, kind);
+    if (!parsed.ok) return this.fail(kind, parsed.reason);
+    return this.add(parsed.node);
+  }
+  /**
+   * The conditions `build` adds, or why there are none to use. `build` gets
+   * a builder of this kind with no filters; FilterGroup shows only its filter
+   * methods, and only its conditions and first problem are read back.
+   */
+  group(path, build) {
+    const built = build(this.next({ filters: [], problem: null }));
+    if (!(built instanceof _FilterBuilder))
+      return invalidQuery(path, "must return the filter builder it was given");
+    const { filters, problem } = built.state;
+    if (problem !== null) return problem;
+    if (filters.length === 0) return invalidQuery(path, "must not be empty");
+    return [...filters];
+  }
+  filtersPart() {
+    return this.state.filters.length === 0 ? {} : { filters: [...this.state.filters] };
+  }
+};
+var SelectBuilder = class extends FilterBuilder {
+  /** Call again to sort by more columns, in call order. */
+  order(column, options = {}) {
+    const term = { column, ascending: options.ascending ?? true };
+    if (options.nullsFirst !== void 0) term.nullsFirst = options.nullsFirst;
+    return this.next({ order: [...this.state.order, term] });
+  }
+  /** At most `count` rows (1–1,000; a select without one reads up to 1,000). */
+  limit(count) {
+    if (!Number.isSafeInteger(count) || count < 1 || count > MAX_LIMIT)
+      return this.fail(
+        "limit",
+        `must be an integer from 1 to ${String(MAX_LIMIT)}; ${CAP}`
+      );
+    return this.next({ limit: count });
+  }
+  offset(count) {
+    return this.next({ offset: count });
+  }
+  /**
+   * Rows `from` to `to`, both inclusive and counted from 0 — at most 1,000
+   * of them. Sent as `offset` and `limit`, so it is checked here: past the
+   * cap the worker would name `limit`, which the app never called.
+   */
+  range(from, to) {
+    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 0 || to < from)
+      return this.fail("range", "must be two integers with 0 <= from <= to");
+    const rows = to - from + 1;
+    if (rows > MAX_LIMIT)
+      return this.fail(
+        "range",
+        `spans ${String(rows)} rows (to - from + 1); ${CAP}`
+      );
+    return this.next({ offset: from, limit: rows });
+  }
+  /** Exactly one row, or NOT_SINGLE_ROW. */
+  single() {
+    return this.next({ single: "one" });
+  }
+  /** One row or null; more than one is NOT_SINGLE_ROW. */
+  maybeSingle() {
+    return this.next({ single: "maybe" });
+  }
+  build() {
+    const { table, columns, order, limit, offset, single } = this.state;
+    return {
+      version: 1,
+      action: "select",
+      table,
+      columns: columns === "*" ? "*" : [...columns],
+      ...this.filtersPart(),
+      ...order.length === 0 ? {} : { order: order.map((term) => ({ ...term })) },
+      ...limit === void 0 ? {} : { limit },
+      ...offset === void 0 ? {} : { offset },
+      ...single === void 0 ? {} : { single }
+    };
+  }
+};
+var InsertBuilder = class extends Builder {
+  /** Return the inserted rows (all columns, or the ones named). */
+  select(columns) {
+    return this.withReturning(columns);
+  }
+  build() {
+    const { table, rows = [], returning } = this.state;
+    return {
+      version: 1,
+      action: "insert",
+      table,
+      rows: rows.map(copyRow),
+      ...returning === void 0 ? {} : { returning }
+    };
+  }
+};
+var MutationBuilder = class extends FilterBuilder {
+  /** Return the changed rows (all columns, or the ones named). */
+  select(columns) {
+    return this.withReturning(columns);
+  }
+  /** Apply to every row with no filter at all. Service key only. */
+  all() {
+    return this.next({ allowUnfiltered: true });
+  }
+  build() {
+    const {
+      table,
+      action,
+      values = {},
+      returning,
+      allowUnfiltered
+    } = this.state;
+    const tail = {
+      ...this.filtersPart(),
+      ...returning === void 0 ? {} : { returning },
+      ...allowUnfiltered === void 0 ? {} : { allowUnfiltered }
+    };
+    return action === "delete" ? { version: 1, action: "delete", table, ...tail } : {
+      version: 1,
+      action: "update",
+      table,
+      values: copyRow(values),
+      ...tail
+    };
+  }
+};
+var TableBuilder = class {
+  #run;
+  #table;
+  constructor(run, table) {
+    this.#run = run;
+    this.#table = table;
+  }
+  /** `"*"` (the default) or `"id, title"`. */
+  select(columns) {
+    const state = initialState(this.#table);
+    const parsed = parseColumns(columns);
+    return new SelectBuilder(
+      this.#run,
+      parsed.ok ? { ...state, columns: parsed.columns } : { ...state, problem: invalidQuery("columns", parsed.reason) }
+    );
+  }
+  /** One row or several; one request, one transaction. */
+  insert(rows) {
+    const list = Array.isArray(rows) ? rows : [rows];
+    return new InsertBuilder(this.#run, {
+      ...initialState(this.#table),
+      rows: list.map(copyRow)
+    });
+  }
+  update(values) {
+    return new MutationBuilder(this.#run, {
+      ...initialState(this.#table),
+      action: "update",
+      values: copyRow(values)
+    });
+  }
+  delete() {
+    return new MutationBuilder(this.#run, {
+      ...initialState(this.#table),
+      action: "delete"
+    });
+  }
+};
+
+// src/client.ts
+var CONFIG_MESSAGES = {
+  url: "createClient needs the project url, like https://my-app.naro.sh.",
+  urlNotOrigin: "createClient needs the project url alone, like https://my-app.naro.sh: no path, no ? or #, no user:password@. Naro serves its API at /_naro/v1 on that origin.",
+  key: "createClient needs an anonKey (or, on a server, a serviceKey).",
+  bothKeys: "Pass createClient an anonKey or a serviceKey, not both.",
+  serviceKeyOffServer: "A Naro service key (naro_sk_\u2026) skips every policy, so createClient accepts it only on a server (Node, Deno, Bun, Cloudflare Workers, an edge runtime), never in a browser, a web worker or a React Native app. Use the anon key (naro_pk_\u2026) here and keep the service key on your server.",
+  fetch: "This runtime has no fetch. Pass one to createClient({ fetch })."
+};
+var SERVICE_KEY_PREFIX = "naro_sk_";
+function baseUrlOf(url) {
+  if (typeof url !== "string") throw new Error(CONFIG_MESSAGES.url);
+  const trimmed = url.trim();
+  let parsed;
+  try {
+    parsed = new URL(trimmed.replace(/\/+$/, ""));
+  } catch {
+    throw new Error(CONFIG_MESSAGES.url);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+    throw new Error(CONFIG_MESSAGES.url);
+  if (trimmed.includes("?") || trimmed.includes("#") || parsed.pathname !== "/" || parsed.username !== "" || parsed.password !== "")
+    throw new Error(CONFIG_MESSAGES.urlNotOrigin);
+  return parsed.origin;
+}
+function apiKeyOf(options) {
+  const { anonKey, serviceKey } = options;
+  const hasAnon = typeof anonKey === "string" && anonKey !== "";
+  const hasService = typeof serviceKey === "string" && serviceKey !== "";
+  if (hasAnon && hasService) throw new Error(CONFIG_MESSAGES.bothKeys);
+  const key = hasService ? serviceKey : hasAnon ? anonKey : void 0;
+  if (key === void 0) throw new Error(CONFIG_MESSAGES.key);
+  if ((hasService || key.startsWith(SERVICE_KEY_PREFIX)) && !isKnownServer())
+    throw new Error(CONFIG_MESSAGES.serviceKeyOffServer);
+  return key;
+}
+function queryRunner(http, auth) {
+  return async (query) => {
+    await auth.ready();
+    const result = await call(http, {
+      method: "POST",
+      path: "/data/query",
+      body: query,
+      withToken: true
+    });
+    if (result.error !== null) return { data: null, error: result.error };
+    const { body, status } = result.answer;
+    if (!isRecord(body) || !Object.hasOwn(body, "data"))
+      return { data: null, error: invalidResponse(status) };
+    return { data: body.data, error: null };
+  };
+}
+var NaroClient = class {
+  /** Sign-up, sign-in, sign-out and the current user (spec §13). */
+  auth;
+  #run;
+  // naro.storage — Phase 3 (spec §18): R2 storage lands here, beside `auth`
+  // and `from()`. Deliberately absent in Phase 1: not implemented, not typed.
+  constructor(options) {
+    const baseUrl = baseUrlOf(options.url);
+    const apiKey = apiKeyOf(options);
+    if (options.fetch === void 0 && typeof globalThis.fetch !== "function")
+      throw new Error(CONFIG_MESSAGES.fetch);
+    const storage = options.auth?.storage ?? defaultStorage();
+    const http = {
+      baseUrl,
+      apiKey,
+      fetch: options.fetch,
+      tokens: new TokenStore(storage, storageKey(baseUrl))
+    };
+    this.auth = new AuthClient(http, {
+      verifiers: new FlowVerifiers(
+        new TokenStore(storage, verifierKey(baseUrl))
+      ),
+      recovery: new RecoveryToken(
+        new TokenStore(storage, recoveryKey(baseUrl))
+      ),
+      detectSessionInUrl: options.auth?.detectSessionInUrl ?? true,
+      shared: { storage, key: storageKey(baseUrl) }
+    });
+    this.#run = queryRunner(http, this.auth);
+  }
+  /** Start a query on `table`: `.select()`, `.insert()`, `.update()` or `.delete()`. */
+  from(table) {
+    return new TableBuilder(this.#run, table);
+  }
+};
+function createClient(options) {
+  return new NaroClient(options);
+}
+export {
+  NaroClient,
+  createClient,
+  quoteFilterValue
+};