naro-js 0.6.0 → 0.7.0

package/dist/index.js

@@ -127,6 +127,17 @@ function serviceKeyOffServer() {
     message: SERVICE_KEY_OFF_SERVER_MESSAGE
   };
 }
+function accessTokenUnavailable(cause) {
+  return {
+    code: "ACCESS_TOKEN_UNAVAILABLE",
+    message: "createClient's accessToken function failed or returned something that is not a string or null, so the request was not sent.",
+    details: { cause: describe(cause) }
+  };
+}
+function accessTokenAuthMessage(name) {
+  return `naro.auth.${name} is not available on a client made with accessToken: its token comes from your accessToken function. Use a client made without accessToken to sign in.`;
+}
+var ACCESS_TOKEN_CHANNEL_MESSAGE = "naro.channel() is not available on a client made with accessToken: Realtime signs in with a session, not an access token. Broadcast from a function with naroAdmin.";
 function notJoined(channel) {
   return {
     code: "NOT_JOINED",
@@ -194,9 +205,139 @@ var SESSION_PREFIXES = ["/auth/", "/realtime/"];
 function storeFor(config, path) {
   return SESSION_PREFIXES.some((prefix) => path.startsWith(prefix)) ? config.tokens : config.accessJwt ?? null;
 }
-async function receive(config, options, init) {
-  const controller = options.timeoutMs !== void 0 && typeof AbortController === "function" ? new AbortController() : null;
+var ACCESS_JWT_MARGIN_MS = 6e4;
+function deadlineOf(timeoutMs) {
+  return timeoutMs === void 0 ? null : { at: Date.now() + timeoutMs, ms: timeoutMs };
+}
+function remainingMs(deadline) {
+  return Math.max(0, deadline.at - Date.now());
+}
+var EXPIRED = Symbol("expired");
+function timedOut(deadline) {
+  return requestTimeout(deadline?.ms ?? 0);
+}
+function timesOf(jwt) {
+  const payload = jwt.split(".")[1];
+  if (payload === void 0 || payload === "") return null;
+  try {
+    const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+    const claims = JSON.parse(atob(padded));
+    if (!isRecord(claims)) return null;
+    const { exp, iat } = claims;
+    if (typeof exp !== "number" || !Number.isFinite(exp)) return null;
+    return {
+      exp: exp * 1e3,
+      iat: typeof iat === "number" && Number.isFinite(iat) ? iat * 1e3 : null
+    };
+  } catch {
+    return null;
+  }
+}
+function expiryOf(jwt) {
+  return timesOf(jwt)?.exp ?? null;
+}
+var skews = /* @__PURE__ */ new WeakMap();
+function localExpiry(config, jwt) {
+  const exp = expiryOf(jwt);
+  return exp === null ? null : exp - (skews.get(config.tokens) ?? 0);
+}
+var SESSION_GONE_CODES = /* @__PURE__ */ new Set([
+  "UNAUTHORIZED",
+  "INVALID_SESSION",
+  "FAILED_TO_GET_SESSION"
+]);
+var renewing = /* @__PURE__ */ new WeakMap();
+function renewAccessJwt(config, jwtStore, session) {
+  const pending = renewing.get(config.tokens);
+  if (pending?.session === session) return pending.done;
+  const done = (async () => {
+    const result = await callWith(
+      config,
+      { method: "GET", path: "/auth/token", withToken: true },
+      void 0,
+      session
+    );
+    if (result.error !== null) {
+      if (result.answer?.status !== 401 || !SESSION_GONE_CODES.has(result.error.code))
+        return result.error;
+      await config.tokens.clearIf(session);
+      await config.tokens.whileIs(null, () => jwtStore.clear());
+      return invalidSession();
+    }
+    const { body, status } = result.answer;
+    const jwt = isRecord(body) ? body.token : void 0;
+    if (typeof jwt !== "string" || jwt === "") return invalidResponse(status);
+    const arrived = Date.now();
+    await config.tokens.whileIs(session, async () => {
+      const iat = timesOf(jwt)?.iat;
+      if (iat !== void 0 && iat !== null)
+        skews.set(config.tokens, iat - arrived);
+      await jwtStore.set(jwt);
+    });
+    return null;
+  })();
+  const entry = { session, done };
+  renewing.set(config.tokens, entry);
+  void done.finally(() => {
+    if (renewing.get(config.tokens) === entry) renewing.delete(config.tokens);
+  });
+  return done;
+}
+async function accessJwtFor(config, jwtStore) {
+  for (let round = 0; round < 2; round += 1) {
+    const session = await config.tokens.get();
+    const jwt = await jwtStore.get();
+    if (session === null || config.service) return { token: jwt, session };
+    const expiry = jwt === null ? null : localExpiry(config, jwt);
+    if (jwt !== null && (expiry === null || expiry - ACCESS_JWT_MARGIN_MS > Date.now()))
+      return { token: jwt, session };
+    const error = await renewAccessJwt(config, jwtStore, session);
+    const stored = await config.tokens.get();
+    if (stored !== session) {
+      if (stored === null) return error ? { error } : { token: null, session };
+      continue;
+    }
+    if (error === null) {
+      const renewed = await jwtStore.get();
+      return renewed === null ? { error: invalidSession() } : { token: renewed, session };
+    }
+    if (jwt !== null && expiry !== null && expiry > Date.now())
+      return { token: jwt, session };
+    return { error };
+  }
+  return { error: invalidSession() };
+}
+async function bearerFor(config, path, withToken) {
+  if (!withToken) return { token: null, session: null };
+  const store = storeFor(config, path);
+  if (config.accessToken !== void 0 && store !== config.tokens) {
+    try {
+      return { token: await config.accessToken.get(), session: null };
+    } catch (cause) {
+      return { error: accessTokenUnavailable(cause) };
+    }
+  }
+  if (store === null) return { token: null, session: null };
+  if (store === config.tokens) {
+    const token = await store.get();
+    return { token, session: token };
+  }
+  return accessJwtFor(config, store);
+}
+async function retryBearer(config, path, error, first) {
+  if (error?.code !== "INVALID_SESSION" || first.token === null || first.session === null || config.accessJwt === void 0 || storeFor(config, path) !== config.accessJwt || await config.tokens.get() !== first.session)
+    return null;
+  const renewed = await bearerFor(config, path, true);
+  if ("error" in renewed) return renewed;
+  return renewed.token === null || renewed.token === first.token || renewed.session !== first.session ? null : renewed;
+}
+async function receive(config, options, init, deadline) {
+  if (deadline !== null && remainingMs(deadline) === 0)
+    return { error: timedOut(deadline) };
+  const controller = deadline !== null && typeof AbortController === "function" ? new AbortController() : null;
   if (controller) init.signal = controller.signal;
+  let gaveUp = false;
   const request = (async () => {
     try {
       const fetchImpl = config.fetch ?? globalThis.fetch;
@@ -204,6 +345,10 @@ async function receive(config, options, init) {
         `${config.baseUrl}/_naro/v1${options.path}`,
         init
       );
+      if (gaveUp) {
+        discard(response);
+        return { error: timedOut(deadline) };
+      }
       return {
         status: response.status,
         headers: response.headers,
@@ -213,14 +358,14 @@ async function receive(config, options, init) {
       return { error: networkError(error) };
     }
   })();
-  const { timeoutMs } = options;
-  if (timeoutMs === void 0) return request;
+  if (deadline === null) return request;
   let timer;
   const expired = new Promise((resolve) => {
     timer = setTimeout(() => {
+      gaveUp = true;
       controller?.abort();
-      resolve({ error: requestTimeout(timeoutMs) });
-    }, timeoutMs);
+      resolve({ error: timedOut(deadline) });
+    }, remainingMs(deadline));
   });
   try {
     return await Promise.race([request, expired]);
@@ -237,8 +382,35 @@ async function call(config, options) {
       return { error: invalidQuery("", "is not JSON"), answer: null };
     }
   }
+  const deadline = deadlineOf(options.timeoutMs);
+  const bearer = await untilStopped(
+    bearerFor(config, options.path, options.withToken),
+    void 0,
+    deadline
+  );
+  if (bearer === EXPIRED || bearer === ABORTED)
+    return { error: timedOut(deadline), answer: null };
+  if ("error" in bearer) return { error: bearer.error, answer: null };
+  const result = await callWith(
+    config,
+    options,
+    payload,
+    bearer.token,
+    deadline
+  );
+  const again = await untilStopped(
+    retryBearer(config, options.path, result.error, bearer),
+    void 0,
+    deadline
+  );
+  if (again === EXPIRED || again === ABORTED)
+    return { error: timedOut(deadline), answer: null };
+  if (again === null) return result;
+  if ("error" in again) return { error: again.error, answer: null };
+  return callWith(config, options, payload, again.token, deadline);
+}
+async function callWith(config, options, payload, token, deadline = null) {
   const store = storeFor(config, options.path);
-  const token = options.withToken && store ? await store.get() : null;
   const headers = {
     ...options.headers,
     apikey: config.apiKey
@@ -257,7 +429,7 @@ async function call(config, options) {
     headers["Content-Type"] = "application/json";
     init.body = payload;
   }
-  const received = await receive(config, options, init);
+  const received = await receive(config, options, init, deadline);
   if ("error" in received) return { error: received.error, answer: null };
   const { status, headers: responseHeaders, text } = received;
   let body;
@@ -282,8 +454,69 @@ async function settled(store, error, headers, token) {
   return RETRY_AFTER_CODES.has(error.code) ? withRetryAfter(error, headers) : error;
 }
 async function send(config, options) {
+  const bearer = await untilAborted(
+    bearerFor(config, options.path, options.withToken),
+    options.signal
+  );
+  if (bearer === ABORTED) return { error: uploadAborted(), status: null };
+  if ("error" in bearer) return { error: bearer.error, status: null };
+  const result = await sendWith(config, options, bearer.token);
+  if (result.error?.code !== "INVALID_SESSION" || isStream(options.body))
+    return result;
+  const again = await untilAborted(
+    retryBearer(config, options.path, result.error, bearer),
+    options.signal
+  );
+  if (again === ABORTED) return { error: uploadAborted(), status: null };
+  if (again === null) return result;
+  if ("error" in again) return { error: again.error, status: null };
+  return sendWith(config, options, again.token);
+}
+var ABORTED = Symbol("aborted");
+function untilAborted(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.resolve(ABORTED);
+  return new Promise((resolve, reject) => {
+    const stop = () => resolve(ABORTED);
+    signal.addEventListener("abort", stop, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", stop);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", stop);
+        reject(error);
+      }
+    );
+  });
+}
+function untilStopped(promise, signal, deadline) {
+  if (signal?.aborted) return Promise.resolve(ABORTED);
+  if (!signal && deadline === null) return promise;
+  return new Promise((resolve, reject) => {
+    let timer;
+    const stop = () => finish(ABORTED);
+    const finish = (value) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", stop);
+      resolve(value);
+    };
+    signal?.addEventListener("abort", stop, { once: true });
+    if (deadline !== null)
+      timer = setTimeout(() => finish(EXPIRED), remainingMs(deadline));
+    promise.then(finish, (error) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", stop);
+      reject(error);
+    });
+  });
+}
+function isStream(body) {
+  return typeof ReadableStream === "function" && body instanceof ReadableStream;
+}
+async function sendWith(config, options, token) {
   const store = storeFor(config, options.path);
-  const token = options.withToken && store ? await store.get() : null;
   const headers = {
     ...options.headers,
     apikey: config.apiKey
@@ -338,6 +571,143 @@ async function send(config, options) {
     status
   };
 }
+async function fetchUnread(config, options) {
+  const { signal } = options;
+  if (signal?.aborted) return { failed: "aborted", cause: signal.reason };
+  const deadline = deadlineOf(options.timeoutMs);
+  if (options.ready) {
+    const ready = await untilStopped(options.ready(), signal, deadline);
+    if (ready === ABORTED) return { failed: "aborted", cause: signal?.reason };
+    if (ready === EXPIRED) return { failed: "timeout", cause: null };
+  }
+  const own = options.headers.has("authorization");
+  const bearer = await untilStopped(
+    bearerFor(config, options.path, !own),
+    signal,
+    deadline
+  );
+  if (bearer === ABORTED) return { failed: "aborted", cause: signal?.reason };
+  if (bearer === EXPIRED) return { failed: "timeout", cause: null };
+  if ("error" in bearer) return { refused: bearer.error };
+  const first = await fetchOnce(config, options, bearer.token, deadline);
+  if (!("response" in first) || bearer.token === null) return first;
+  const refused = await refusesToken(first.response, signal, deadline);
+  if (refused === EXPIRED) {
+    discard(first.response);
+    return { failed: "timeout", cause: null };
+  }
+  if (refused === ABORTED) {
+    discard(first.response);
+    return { failed: "aborted", cause: signal?.reason };
+  }
+  if (!refused) return first;
+  await storeFor(config, options.path)?.clearIf(bearer.token);
+  if (isStream(options.body)) return first;
+  const again = await untilStopped(
+    retryBearer(config, options.path, invalidSession(), bearer),
+    signal,
+    deadline
+  );
+  if (again === EXPIRED) {
+    discard(first.response);
+    return { failed: "timeout", cause: null };
+  }
+  if (again === null || again !== ABORTED && "error" in again) return first;
+  discard(first.response);
+  if (again === ABORTED) return { failed: "aborted", cause: signal?.reason };
+  const second = await fetchOnce(config, options, again.token, deadline);
+  if (!("response" in second) || again.token === null) return second;
+  const refusedAgain = await refusesToken(second.response, signal, deadline);
+  if (refusedAgain === ABORTED) {
+    discard(second.response);
+    return { failed: "aborted", cause: signal?.reason };
+  }
+  if (refusedAgain === true || refusedAgain === EXPIRED)
+    await storeFor(config, options.path)?.clearIf(again.token);
+  return second;
+}
+async function refusesToken(response, signal, deadline) {
+  if (response.status !== 401 || response.headers.get("x-relay-error") !== "true")
+    return false;
+  let body;
+  try {
+    body = await untilStopped(response.clone().json(), signal, deadline);
+  } catch {
+    return signal?.aborted ? ABORTED : false;
+  }
+  if (body === ABORTED || body === EXPIRED) return body;
+  return isRecord(body) && isRecord(body.error) && body.error.code === "INVALID_SESSION";
+}
+var releases = /* @__PURE__ */ new WeakMap();
+function discard(response) {
+  releases.get(response)?.();
+  releases.delete(response);
+  response.body?.cancel().catch(() => {
+  });
+}
+async function fetchOnce(config, options, token, deadline) {
+  const { signal } = options;
+  if (signal?.aborted) return { failed: "aborted", cause: signal.reason };
+  if (deadline !== null && remainingMs(deadline) === 0)
+    return { failed: "timeout", cause: null };
+  const headers = new Headers(options.headers);
+  headers.set("apikey", config.apiKey);
+  if (token !== null) headers.set("authorization", `Bearer ${token}`);
+  const init = {
+    method: options.method,
+    headers,
+    credentials: "omit"
+  };
+  if (options.body !== void 0) init.body = options.body;
+  if (isStream(options.body)) init.duplex = "half";
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  if (controller) init.signal = controller.signal;
+  let timer;
+  let stop = () => {
+  };
+  const stopped = new Promise((resolve) => {
+    stop = resolve;
+  });
+  const onAbort = () => {
+    stop({ failed: "aborted", cause: signal?.reason });
+    controller?.abort(signal?.reason);
+  };
+  if (deadline !== null)
+    timer = setTimeout(() => {
+      stop({ failed: "timeout", cause: null });
+      controller?.abort();
+    }, remainingMs(deadline));
+  signal?.addEventListener("abort", onAbort, { once: true });
+  const request = (async () => {
+    try {
+      const fetchImpl = config.fetch ?? globalThis.fetch;
+      return {
+        response: await fetchImpl(
+          `${config.baseUrl}/_naro/v1${options.path}`,
+          init
+        )
+      };
+    } catch (cause) {
+      return { failed: "network", cause };
+    }
+  })();
+  const release = () => signal?.removeEventListener("abort", onAbort);
+  let outcome;
+  try {
+    outcome = await Promise.race([request, stopped]);
+    return outcome;
+  } finally {
+    clearTimeout(timer);
+    if (outcome !== void 0 && "response" in outcome)
+      releases.set(outcome.response, release);
+    else {
+      release();
+      void request.then((late) => {
+        if ("response" in late) discard(late.response);
+      });
+    }
+  }
+}
 var RETRY_AFTER_CODES = /* @__PURE__ */ new Set([
   "RATE_LIMITED",
   "WRITE_QUOTA_EXCEEDED",
@@ -346,7 +716,12 @@ var RETRY_AFTER_CODES = /* @__PURE__ */ new Set([
   "OBJECT_RATE_LIMITED",
   "STORAGE_OPS_QUOTA_EXCEEDED",
   // Realtime's REST broadcast over the project's message budget (x-retry-after: 1).
-  "TOO_MANY_MESSAGES"
+  "TOO_MANY_MESSAGES",
+  // Naro Functions (design F20): a team over its monthly function CPU, and
+  // the control plane's Cloudflare limit. `invoke` reads x-retry-after on
+  // every relay error anyway (invoke/client.ts).
+  "FUNCTIONS_QUOTA_EXCEEDED",
+  "FUNCTIONS_RATE_LIMITED"
 ]);
 function withRetryAfter(error, headers) {
   const header = headers.get("x-retry-after")?.trim() ?? "";
@@ -670,14 +1045,14 @@ var AuthClient = class {
    */
   async signInWithOAuth(options) {
     const { provider } = options;
-    const failed = (error) => ({
+    const failed2 = (error) => ({
       data: { provider, url: null },
       error
     });
-    if (!OAUTH_PROVIDERS.includes(provider)) return failed(invalidProvider());
+    if (!OAUTH_PROVIDERS.includes(provider)) return failed2(invalidProvider());
     await this.#flow.recovery.forget();
     const pair = await createPkcePair();
-    if (!pair) return failed(cryptoUnavailable());
+    if (!pair) return failed2(cryptoUnavailable());
     await this.#flow.verifiers.add(pair.challenge, pair.verifier);
     const redirectTo = options.redirectTo ?? currentPage();
     const url = new URL(
@@ -1153,6 +1528,23 @@ var TokenStore = class {
       this.#changed();
     });
   }
+  /**
+   * Runs `operation` only while `expected` is the stored token (null: none
+   * is stored), inside this
+   * store's queue, and says whether it ran: no write to this store lands
+   * between the check and the end of the operation. A refreshed access JWT
+   * is kept this way (`http.ts`), so one minted for a session that a
+   * sign-in replaced meanwhile never lands on top of the new session's.
+   * `operation` must not call this store's public methods (it would wait
+   * on itself); another store's are fine.
+   */
+  whileIs(expected, operation) {
+    return this.#serial(async () => {
+      if (await this.#get() !== expected) return false;
+      await operation();
+      return true;
+    });
+  }
   /**
    * Calls `listener` after every write of the token — a sign-in, a
    * sign-out, a renewed session, a cleared INVALID_SESSION — from inside the
@@ -1233,6 +1625,288 @@ var TokenStore = class {
   }
 };
 
+// src/invoke/body.ts
+function prepareBody(body) {
+  if (body === void 0) return { body: void 0, contentType: null };
+  if (typeof body === "string") return { body, contentType: "text/plain" };
+  if (typeof Blob === "function" && body instanceof Blob)
+    return { body, contentType: "application/octet-stream" };
+  if (body instanceof ArrayBuffer || ArrayBuffer.isView(body))
+    return { body, contentType: "application/octet-stream" };
+  if (typeof FormData === "function" && body instanceof FormData)
+    return { body, contentType: null };
+  if (typeof URLSearchParams === "function" && body instanceof URLSearchParams)
+    return { body, contentType: null };
+  if (typeof ReadableStream === "function" && body instanceof ReadableStream)
+    return { body, contentType: null };
+  try {
+    const text = JSON.stringify(body);
+    return text === void 0 ? null : { body: text, contentType: "application/json" };
+  } catch {
+    return null;
+  }
+}
+async function readAnswer(response, method) {
+  if (response.status === 204 || method === "HEAD") return { data: null };
+  const type = (response.headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase();
+  try {
+    if (type === "application/json") {
+      const text = await response.text();
+      return {
+        data: text.trim() === "" ? null : JSON.parse(text)
+      };
+    }
+    if (type === "application/octet-stream" || type === "application/pdf")
+      return { data: await response.blob() };
+    if (type === "text/event-stream") return { data: response };
+    if (type === "multipart/form-data")
+      return { data: await response.formData() };
+    return { data: await response.text() };
+  } catch (cause) {
+    return { unreadable: cause };
+  }
+}
+
+// src/invoke/errors.ts
+var FunctionsError = class extends Error {
+  code;
+  context;
+  constructor(code, message, context, details) {
+    super(message);
+    this.name = "FunctionsError";
+    this.code = code;
+    this.context = context;
+    if (details !== void 0)
+      Object.defineProperty(this, "details", {
+        value: details,
+        enumerable: true
+      });
+  }
+};
+var FunctionsHttpError = class extends FunctionsError {
+  constructor(response) {
+    super(
+      "FUNCTION_HTTP_ERROR",
+      `The function answered with HTTP ${String(response.status)}.`,
+      response
+    );
+    this.name = "FunctionsHttpError";
+  }
+};
+var FunctionsRelayError = class extends FunctionsError {
+  constructor(code, message, response, details) {
+    super(code, message, response, details);
+    this.name = "FunctionsRelayError";
+  }
+};
+var FunctionsFetchError = class extends FunctionsError {
+  constructor(code, message, cause, details) {
+    super(code, message, cause, details);
+    this.name = "FunctionsFetchError";
+  }
+};
+var FUNCTIONS_MESSAGES = {
+  timeout: (ms) => `The function did not answer within ${String(ms)} ms.`,
+  aborted: "The function call was stopped before the function answered.",
+  invalidBody: "functions.invoke could not send this body: JSON cannot hold it (a BigInt or a cycle). Pass a string, a Blob, bytes, FormData, URLSearchParams or a stream instead.",
+  invalidTimeout: "functions.invoke's timeout is whole milliseconds from 1 to 2147483647.",
+  invalidHeaders: "functions.invoke's headers are not valid HTTP header names and values.",
+  invalidName: "functions.invoke's name is a string: the function's name, then any path and query.",
+  unencodableName: "functions.invoke's name is not well-formed Unicode: it has a lone surrogate.",
+  dotSegments: `functions.invoke's name cannot be "." or "..", and ".." in its path cannot leave /functions/.`,
+  invalidSignal: "functions.invoke's signal is not an AbortSignal.",
+  bodyWithGetOrHead: "functions.invoke cannot send a body with GET or HEAD.",
+  /** `RELAY_ERROR`: a HEAD answer has no body, so Naro's code is not in it. */
+  headRelay: (status) => `Naro answered HTTP ${String(status)} for the function, but a HEAD answer has no body to say why. Call it with GET to read the reason.`,
+  unreadable: (status) => `The function answered HTTP ${String(status)}, but its body could not be read as its content-type says.`
+};
+
+// src/invoke/client.ts
+var MAX_TIMER_MS = 2147483647;
+function functionPath(name) {
+  const cut = name.search(/[/?#]/);
+  const head = cut === -1 ? name : name.slice(0, cut);
+  const tail = cut === -1 ? "" : name.slice(cut);
+  return `/functions/${encodeURIComponent(head)}${tail}`;
+}
+function dotSegment(segment) {
+  const dots = segment.toLowerCase().replace(/%2e/g, ".");
+  return dots === "." ? 1 : dots === ".." ? 2 : 0;
+}
+function leavesFunctions(input) {
+  const name = input.replace(/[\t\n\r]/g, "");
+  const cut = name.search(/[/?#]/);
+  const head = cut === -1 ? name : name.slice(0, cut);
+  if (head === "." || head === "..") return true;
+  if (cut === -1 || name[cut] !== "/") return false;
+  const rest = name.slice(cut + 1);
+  const end = rest.search(/[?#]/);
+  let depth = 1;
+  for (const segment of (end === -1 ? rest : rest.slice(0, end)).split(
+    /[/\\]/
+  )) {
+    const dots = dotSegment(segment);
+    if (dots === 0) depth += 1;
+    if (dots === 2) depth -= 1;
+    if (depth < 0) return true;
+  }
+  return false;
+}
+function pathOf(name) {
+  if (typeof name !== "string")
+    return { invalid: FUNCTIONS_MESSAGES.invalidName };
+  if (leavesFunctions(name)) return { invalid: FUNCTIONS_MESSAGES.dotSegments };
+  try {
+    return { path: functionPath(name) };
+  } catch {
+    return { invalid: FUNCTIONS_MESSAGES.unencodableName };
+  }
+}
+function isSignalOrNone(value) {
+  if (value === void 0 || value === null) return true;
+  if (typeof value !== "object") return false;
+  const signal = value;
+  return typeof signal.aborted === "boolean" && typeof signal.addEventListener === "function" && typeof signal.removeEventListener === "function";
+}
+function invalidOptions(message) {
+  return failed(new FunctionsFetchError("INVALID_OPTIONS", message, null));
+}
+function failed(error) {
+  return { data: null, error };
+}
+function fromNaroError(error, cause) {
+  return new FunctionsFetchError(
+    error.code,
+    error.message,
+    cause,
+    error.details
+  );
+}
+function failure(kind, cause, timeout) {
+  if (kind === "timeout")
+    return new FunctionsFetchError(
+      "TIMEOUT",
+      FUNCTIONS_MESSAGES.timeout(timeout ?? 0),
+      cause
+    );
+  if (kind === "aborted")
+    return new FunctionsFetchError(
+      "ABORTED",
+      FUNCTIONS_MESSAGES.aborted,
+      cause
+    );
+  return fromNaroError(networkError(cause), cause);
+}
+function unreadable(cause, status, signal) {
+  if (signal?.aborted)
+    return new FunctionsFetchError(
+      "ABORTED",
+      FUNCTIONS_MESSAGES.aborted,
+      cause
+    );
+  if (cause instanceof SyntaxError)
+    return new FunctionsFetchError(
+      "INVALID_RESPONSE",
+      FUNCTIONS_MESSAGES.unreadable(status),
+      cause
+    );
+  return fromNaroError(networkError(cause), cause);
+}
+async function relayError(response, head) {
+  let body;
+  try {
+    body = await response.clone().json();
+  } catch {
+    body = void 0;
+  }
+  const { status } = response;
+  const error = withRetryAfter(
+    head && body === void 0 ? {
+      code: "RELAY_ERROR",
+      message: FUNCTIONS_MESSAGES.headRelay(status),
+      details: { status }
+    } : errorFromBody(status, body) ?? invalidResponse(status),
+    response.headers
+  );
+  return new FunctionsRelayError(
+    error.code,
+    error.message,
+    response,
+    error.details
+  );
+}
+var FunctionsClient = class {
+  #http;
+  #auth;
+  constructor(http, auth) {
+    this.#http = http;
+    this.#auth = auth;
+  }
+  async invoke(name, options = {}) {
+    const method = options.method ?? "POST";
+    const { timeout, signal } = options;
+    const target = pathOf(name);
+    if ("invalid" in target) return invalidOptions(target.invalid);
+    if (timeout !== void 0 && !(Number.isInteger(timeout) && timeout > 0 && timeout <= MAX_TIMER_MS))
+      return invalidOptions(FUNCTIONS_MESSAGES.invalidTimeout);
+    if (!isSignalOrNone(signal))
+      return invalidOptions(FUNCTIONS_MESSAGES.invalidSignal);
+    const verb = typeof method === "string" ? method.toUpperCase() : "";
+    if (options.body !== void 0 && (verb === "GET" || verb === "HEAD"))
+      return invalidOptions(FUNCTIONS_MESSAGES.bodyWithGetOrHead);
+    let headers;
+    try {
+      headers = new Headers(options.headers);
+    } catch (cause) {
+      return failed(
+        new FunctionsFetchError(
+          "INVALID_OPTIONS",
+          FUNCTIONS_MESSAGES.invalidHeaders,
+          cause
+        )
+      );
+    }
+    const prepared = prepareBody(options.body);
+    if (prepared === null)
+      return failed(
+        new FunctionsFetchError(
+          "INVALID_BODY",
+          FUNCTIONS_MESSAGES.invalidBody,
+          null
+        )
+      );
+    if (prepared.contentType !== null && !headers.has("content-type"))
+      headers.set("content-type", prepared.contentType);
+    const result = await fetchUnread(this.#http, {
+      method,
+      path: target.path,
+      headers,
+      body: prepared.body,
+      timeoutMs: timeout,
+      signal,
+      // A sign-in the page URL carried goes first, as for a query (P2-6) —
+      // within the call's timeout and signal; the exchange is not cut.
+      ready: () => this.#auth.ready()
+    });
+    if ("refused" in result) return failed(fromNaroError(result.refused, null));
+    if ("failed" in result)
+      return failed(failure(result.failed, result.cause, timeout));
+    const { response } = result;
+    if (!response.ok) {
+      const error = response.headers.get("x-relay-error") === "true" ? await relayError(response, verb === "HEAD") : new FunctionsHttpError(response);
+      return { data: null, error, response };
+    }
+    const answer = await readAnswer(response, method);
+    if ("unreadable" in answer)
+      return {
+        data: null,
+        error: unreadable(answer.unreadable, response.status, signal),
+        response
+      };
+    return { data: answer.data, error: null, response };
+  }
+};
+
 // src/query/columns.ts
 function isSpace(char) {
   return char.trim() === "";
@@ -2742,19 +3416,19 @@ var RealtimeSocket = class {
   #closed(ws, code, reason, waitedMs) {
     if (this.#ws !== ws) return;
     const wasOpen = this.#state === "open";
-    const timedOut = waitedMs !== null;
+    const timedOut2 = waitedMs !== null;
     detach(ws);
     this.#ws = null;
     this.#clearTimers();
-    if (timedOut) closeQuietly(ws, 1e3);
+    if (timedOut2) closeQuietly(ws, 1e3);
     if (!wasOpen) this.#unopened += 1;
     const said = this.#said;
     this.#said = null;
-    if (!timedOut && code === 4008) this.#flooded = true;
-    const action = timedOut ? { kind: "retry", minMs: 0 } : closeAction(code, said?.code ?? reason);
+    if (!timedOut2 && code === 4008) this.#flooded = true;
+    const action = timedOut2 ? { kind: "retry", minMs: 0 } : closeAction(code, said?.code ?? reason);
     if (action.kind === "stop")
       return this.#stop(said ?? realtimeStopped(code, reason));
-    const error = timedOut ? realtimeTimedOut(waitedMs) : said ?? realtimeClosed(code);
+    const error = timedOut2 ? realtimeTimedOut(waitedMs) : said ?? realtimeClosed(code);
     this.#failReplies(error);
     this.#state = "waiting";
     const delay = delayAfter(
@@ -2767,7 +3441,7 @@ var RealtimeSocket = class {
     safely(
       () => this.#config.events.dropped(
         error,
-        timedOut ? "TIMED_OUT" : "CHANNEL_ERROR"
+        timedOut2 ? "TIMED_OUT" : "CHANNEL_ERROR"
       )
     );
   }
@@ -4164,13 +4838,13 @@ async function uploadInParts(a) {
     }).catch(() => void 0);
   };
   const etags = [];
-  const failure = {
+  const failure2 = {
     error: signal?.aborted ? uploadAborted() : null
   };
   let next = 1;
   let sentBytes = 0;
   const onAbort = () => {
-    failure.error ??= uploadAborted();
+    failure2.error ??= uploadAborted();
   };
   const tryPart = async (n, bytes) => {
     const sent2 = await send(a.http, {
@@ -4199,18 +4873,18 @@ async function uploadInParts(a) {
         progress(sentBytes);
         return null;
       }
-      if (attempt2 === ATTEMPTS || failure.error !== null || !retryable(tried.error, tried.status))
+      if (attempt2 === ATTEMPTS || failure2.error !== null || !retryable(tried.error, tried.status))
         return tried.error;
       await sleep(waitAfter(tried.error, attempt2), signal);
-      if (failure.error !== null) return tried.error;
+      if (failure2.error !== null) return tried.error;
     }
   };
   const worker = async () => {
-    while (failure.error === null && next <= partCount) {
+    while (failure2.error === null && next <= partCount) {
       const n = next;
       next += 1;
       const error = await sendPart(n);
-      if (error !== null) failure.error ??= error;
+      if (error !== null) failure2.error ??= error;
     }
   };
   signal?.addEventListener("abort", onAbort);
@@ -4218,9 +4892,9 @@ async function uploadInParts(a) {
     Array.from({ length: Math.min(CONCURRENCY, partCount) }, worker)
   );
   signal?.removeEventListener("abort", onAbort);
-  if (failure.error !== null) {
+  if (failure2.error !== null) {
     await callOff();
-    return fail(failure.error);
+    return fail(failure2.error);
   }
   const completed = await call(a.http, {
     method: "POST",
@@ -4451,8 +5125,8 @@ var StorageFileApi = class {
     const payload = payloadOf(body, options.contentType);
     if (!payload.ok) return fail(payload.error);
     const cache = `max-age=${options.cacheControl ?? "3600"}`;
-    const unreadable = headerProblem(options.contentType, cache);
-    if (unreadable !== null) return fail(unreadable);
+    const unreadable2 = headerProblem(options.contentType, cache);
+    if (unreadable2 !== null) return fail(unreadable2);
     const { signal } = options;
     if (signal?.aborted) return fail(uploadAborted());
     await this.#auth.ready();
@@ -4753,8 +5427,8 @@ var StorageFileApi = class {
     const payload = payloadOf(body, given.contentType);
     if (!payload.ok) return fail(payload.error);
     const cache = `max-age=${given.cacheControl ?? "3600"}`;
-    const unreadable = headerProblem(given.contentType, cache);
-    if (unreadable !== null) return fail(unreadable);
+    const unreadable2 = headerProblem(given.contentType, cache);
+    if (unreadable2 !== null) return fail(unreadable2);
     const { signal } = given;
     if (signal?.aborted) return fail(uploadAborted());
     const uploaded = payload.size > MAX_SINGLE_UPLOAD_BYTES ? await uploadInParts({
@@ -4835,12 +5509,14 @@ var CONFIG_MESSAGES = {
   bothKeys: "Pass createClient an anonKey or a serviceKey, not both.",
   serviceKeyOffServer: SERVICE_KEY_OFF_SERVER_MESSAGE,
   fetch: "This runtime has no fetch. Pass one to createClient({ fetch }).",
-  realtime: "createClient's realtime options take a WebSocket class, and heartbeatIntervalMs and timeoutMs in whole milliseconds from 1 to 2147483647."
+  realtime: "createClient's realtime options take a WebSocket class, and heartbeatIntervalMs and timeoutMs in whole milliseconds from 1 to 2147483647.",
+  accessTokenWithServiceKey: "Pass createClient an accessToken or a serviceKey, not both: the service key skips every policy, so the user's token would not count.",
+  accessToken: "createClient's accessToken is a function that returns the user's access token, or null for none."
 };
 var SERVICE_KEY_PREFIX = "naro_sk_";
-var MAX_TIMER_MS = 2147483647;
+var MAX_TIMER_MS2 = 2147483647;
 function isMilliseconds(value) {
-  return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= MAX_TIMER_MS;
+  return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= MAX_TIMER_MS2;
 }
 function realtimeOptionsOf(value) {
   if (value === void 0) return {};
@@ -4890,6 +5566,35 @@ function apiKeyOf(options) {
     throw new Error(CONFIG_MESSAGES.serviceKeyOffServer);
   return { key, service };
 }
+function accessTokenOf(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "function") throw new Error(CONFIG_MESSAGES.accessToken);
+  const read = value;
+  return {
+    async get() {
+      const token = await read();
+      if (token === null || token === void 0 || token === "") return null;
+      if (typeof token !== "string")
+        throw new TypeError(`accessToken returned a ${typeof token}`);
+      if (!/^[\x21-\x7E]+$/.test(token))
+        throw new TypeError(
+          "accessToken returned a string that is not a token"
+        );
+      return token;
+    }
+  };
+}
+function refusingAuth() {
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_target, property) {
+      if (typeof property === "symbol" || property === "then" || property === "toJSON" || property === "constructor" || property === "asymmetricMatch")
+        return void 0;
+      if (property === "toString") return Object.prototype.toString;
+      if (property === "valueOf") return Object.prototype.valueOf;
+      throw new Error(accessTokenAuthMessage(property));
+    }
+  });
+}
 function queryRunner(http, auth) {
   return async (query) => {
     await auth.ready();
@@ -4918,7 +5623,14 @@ var NaroClient = class {
    * them, as supabase-js does.
    */
   storage;
+  /**
+   * The project's Naro Functions (design §9): `functions.invoke(name, {
+   * body })`, as in supabase-js.
+   */
+  functions;
   #run;
+  /** Made with `accessToken`: `auth` and `channel()` refuse. */
+  #accessToken;
   #newRealtime;
   /**
    * Made by the first channel(), not by the constructor: it listens to every
@@ -4929,36 +5641,38 @@ var NaroClient = class {
   constructor(options) {
     const baseUrl = baseUrlOf(options.url);
     const { key: apiKey, service } = apiKeyOf(options);
+    const accessToken = accessTokenOf(options.accessToken);
+    if (accessToken !== void 0 && service)
+      throw new Error(CONFIG_MESSAGES.accessTokenWithServiceKey);
     if (options.fetch === void 0 && typeof globalThis.fetch !== "function")
       throw new Error(CONFIG_MESSAGES.fetch);
     const realtime = realtimeOptionsOf(options.realtime);
-    const storage = options.auth?.storage ?? defaultStorage();
+    const storage = accessToken !== void 0 ? memoryStorage() : options.auth?.storage ?? defaultStorage();
     const http = {
       baseUrl,
       apiKey,
       fetch: options.fetch,
       tokens: new TokenStore(storage, storageKey(baseUrl)),
-      accessJwt: new TokenStore(storage, accessJwtKey(baseUrl))
+      service,
+      ...accessToken !== void 0 ? { accessToken } : { accessJwt: new TokenStore(storage, accessJwtKey(baseUrl)) }
     };
-    this.auth = new AuthClient(http, {
+    const 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,
+      detectSessionInUrl: accessToken === void 0 && (options.auth?.detectSessionInUrl ?? true),
       shared: { storage, key: storageKey(baseUrl) },
       serviceKey: service
     });
-    this.#run = queryRunner(http, this.auth);
-    this.storage = new StorageClient(http, this.auth);
-    this.#newRealtime = () => new RealtimeClient({
-      http,
-      auth: this.auth,
-      service,
-      options: realtime
-    });
+    this.#accessToken = accessToken !== void 0;
+    this.auth = this.#accessToken ? refusingAuth() : auth;
+    this.#run = queryRunner(http, auth);
+    this.storage = new StorageClient(http, auth);
+    this.functions = new FunctionsClient(http, auth);
+    this.#newRealtime = () => new RealtimeClient({ http, auth, service, options: realtime });
   }
   /** Start a query on `table`: `.select()`, `.insert()`, `.update()` or `.delete()`. */
   from(table) {
@@ -4970,6 +5684,7 @@ var NaroClient = class {
    * `removeChannel`. Nothing connects until the first `subscribe()`.
    */
   channel(name, options) {
+    if (this.#accessToken) throw new Error(ACCESS_TOKEN_CHANNEL_MESSAGE);
     return this.#client().channel(name, options);
   }
   /** The channels made with `channel()` and not yet removed. */
@@ -4981,7 +5696,9 @@ var NaroClient = class {
    * one; the connection closes with the last channel.
    */
   removeChannel(channel) {
-    return this.#client().removeChannel(channel);
+    if (this.#realtime === void 0)
+      return Promise.resolve({ data: null, error: null });
+    return this.#realtime.removeChannel(channel);
   }
   /** `removeChannel()` for every channel; the connection closes. */
   removeAllChannels() {
@@ -4998,6 +5715,10 @@ function createClient(options) {
   return new NaroClient(options);
 }
 export {
+  FunctionsError,
+  FunctionsFetchError,
+  FunctionsHttpError,
+  FunctionsRelayError,
   NaroClient,
   createClient,
   objectRoute,