naro-js 0.6.0 → 0.7.0

package/README.md

@@ -21,8 +21,8 @@ with the same keys — nothing to change in your app.
 import { createClient } from "naro-js";
 
 const naro = createClient({
-  url: "https://my-app.naro.sh",
-  anonKey: "naro_pk_…",
+  url: process.env.NEXT_PUBLIC_NARO_URL!,
+  anonKey: process.env.NEXT_PUBLIC_NARO_ANON_KEY!,
 });
 
 await naro.auth.signIn({ email, password });
@@ -46,6 +46,20 @@ await naro.from("posts").delete().eq("id", 10);
   throws only for a configuration mistake.
 - `url` is the project's origin alone (`https://my-app.naro.sh`): no path,
   no `?` or `#`.
+- Keep the URL and the anon key in the project's environment variables, not
+  in the code: `NEXT_PUBLIC_NARO_URL` and `NEXT_PUBLIC_NARO_ANON_KEY` (Vite
+  `VITE_…`, Astro and SvelteKit `PUBLIC_…`, server code `NARO_URL` and
+  `NARO_ANON_KEY`), saved for all environments with `naro env add` and in
+  `.env.local` for local development. Production and preview use the values
+  you saved. Server code reads `NARO_URL` and `NARO_ANON_KEY`, so save those
+  two for production and preview as well. The service key, which naro never
+  sets, goes in `NARO_SERVICE_KEY`: save one for each environment, because a
+  production service key saved for all environments is refused (401) by an
+  environment's backend. A named environment of a project with a backend has a backend of
+  its own, and naro sets those names to its address and anon key, so the same
+  code calls the right backend everywhere — an address written into the code
+  calls production's from every environment. On a custom domain, save
+  `NEXT_PUBLIC_NARO_URL=https://<your domain>` for production.
 - Queries: `.select("id, title")`, `.eq` `.neq` `.gt` `.gte` `.lt` `.lte`
   `.in` `.is` `.like` `.ilike`, `.or` `.and` `.not` `.filter` `.match`
   `.contains` `.containedBy` `.overlaps` (see [Filters](#filters)),
@@ -69,6 +83,12 @@ await naro.from("posts").delete().eq("id", 10);
 - The session token lives in `localStorage` in a browser and in memory
   elsewhere. On a server, create one client per request, or pass
   `auth: { storage }` with your own `getItem` / `setItem` / `removeItem`.
+- Queries and Storage calls carry a short-lived access token (15 minutes)
+  next to the session, which lasts days. The client renews it on its own
+  before it expires, and once more if the backend refuses it — nothing to
+  call, no timer running. When the session itself has ended (signed out
+  elsewhere, expired, the user deleted), the call answers `INVALID_SESSION`
+  and the client forgets both tokens: sign in again.
 - Types: `createClient<Database>()` with the `Database` that
   `naro gen types` writes — see [Types](#types).
 - Sign-in is naro Auth, the project's own (like Supabase Auth). Email and
@@ -80,6 +100,7 @@ await naro.from("posts").delete().eq("id", 10);
 - Email and social sign-in — see [Sign-in flows](#sign-in-flows).
 - Files — see [Storage](#storage).
 - Live changes, broadcast and presence — see [Realtime](#realtime).
+- Server code your app calls by name — see [Functions](#functions).
 
 ## Policies
 
@@ -141,7 +162,7 @@ The same from your own server, with supabase-js's `auth.admin` names:
 ```ts
 // Server only: the service key skips every policy.
 const admin = createClient({
-  url: "https://my-app.naro.sh",
+  url: process.env.NARO_URL!,
   serviceKey: process.env.NARO_SERVICE_KEY,
 });
 
@@ -318,8 +339,8 @@ import { createClient } from "naro-js";
 import type { Database, Tables } from "./database.types";
 
 const naro = createClient<Database>({
-  url: "https://my-app.naro.sh",
-  anonKey: "naro_pk_…",
+  url: process.env.NEXT_PUBLIC_NARO_URL!,
+  anonKey: process.env.NEXT_PUBLIC_NARO_ANON_KEY!,
 });
 
 // { id: number; title: string }[] | null
@@ -860,3 +881,135 @@ const naro = createClient({ url, anonKey, realtime: { WebSocket } });
 
 The whole guide, with the policies, the close codes and the limits:
 https://naro.sh/docs/realtime
+
+## Functions
+
+Server code your app calls by name, written the way Supabase Edge Functions
+are (naro-js 0.7.0). `naro functions new hello` writes one and
+`naro functions deploy hello` puts it live; the folders, imports, secrets and
+limits are in https://naro.sh/docs/functions.
+
+```ts
+// naro/functions/hello/index.ts
+import { withNaro } from "naro-js/functions";
+
+Deno.serve(
+  withNaro(async (req, { user, naro }) => {
+    const { name } = await req.json();
+    // naro acts as the caller: the tables' policies apply.
+    const { data } = await naro
+      .from("profiles")
+      .select("*")
+      .eq("id", user?.id ?? "");
+    return Response.json({ message: `Hello ${name}!`, profile: data });
+  }),
+);
+```
+
+```ts
+// your app
+import { createClient, FunctionsHttpError } from "naro-js";
+
+const naro = createClient({ url, anonKey });
+const { data, error } = await naro.functions.invoke("hello", {
+  body: { name: "Naro" },
+});
+if (error instanceof FunctionsHttpError)
+  console.log(await error.context.json());
+```
+
+- `invoke(name, { body, headers, method, timeout, signal })` calls
+  `<url>/_naro/v1/functions/<name>` (`POST` by default) with the anon key
+  and, when someone is signed in, their access token — renewed as a query's
+  is. `name` may carry a path and a query (`"hello/items?limit=5"`); only
+  the name is encoded. A name of `.` or `..`, or a path whose `..` would
+  take the URL out of `/functions/` once it is normalised, is refused
+  before anything is sent. `region` is taken and ignored.
+- An object or array goes as JSON, a string as text, a Blob or bytes as
+  `application/octet-stream`; `FormData`, `URLSearchParams` and a
+  `ReadableStream` go as they are, and your own `content-type` wins; a
+  `GET` or `HEAD` call takes no body. The
+  answer is read by its content type: JSON, a Blob for
+  `application/octet-stream` and `application/pdf`, the `Response` itself
+  for `text/event-stream`, a `FormData` for `multipart/form-data`, text
+  otherwise, `null` for 204 and `HEAD`. `timeout` (ms) is the whole call's:
+  the wait for a sign-in the page URL carried, a token renewal and the one
+  retry of a call Naro refused for an expired token count in it, up to the
+  final answer's headers. Your `signal` stops the call at any of these
+  waits; the sign-in and the renewal go on for the rest of the page. The
+  body is not timed — pass a `signal` to stop a body that is slow to
+  arrive.
+- It resolves to `{ data, error }` and never throws, with `response` beside
+  them when one came. `error` is one of supabase-js's classes, and has
+  `code`, `message` and `details` too: `FunctionsHttpError` — your function
+  answered 4xx or 5xx (`FUNCTION_HTTP_ERROR`; `error.context` is the unread
+  `Response`, and a function that threw answers
+  `500 FUNCTION_ERROR` in it); `FunctionsRelayError` — Naro answered for it
+  (`x-relay-error: true`): `FUNCTION_NOT_FOUND`, `INVALID_API_KEY`,
+  `INVALID_SESSION`, `FUNCTIONS_QUOTA_EXCEEDED` with `details.retryAfter`,
+  …, and `RELAY_ERROR` for a `HEAD` call; `FunctionsFetchError` — everything
+  else, `error.context` holding the cause:
+  - no answer came: `NETWORK_ERROR` (fetch threw, `details.cause`),
+    `TIMEOUT` (the call did not finish within `timeout` — a sign-in
+    exchange or a token renewal that outlasts it included, and Naro's
+    refusal of the first token whose body was still being read then, which
+    is dropped — a refusal of the renewed token is the call's answer, so it
+    comes back as `INVALID_SESSION` even past `timeout`), `ABORTED` (your
+    `signal`);
+  - nothing was sent: `INVALID_BODY` (a body JSON cannot hold),
+    `INVALID_OPTIONS` (a name, `timeout`, `headers` or `signal` it cannot
+    use, or a body with `GET` or `HEAD`), `ACCESS_TOKEN_UNAVAILABLE` (the
+    `accessToken` function of a client made with one failed), or the error
+    renewing the access token before the call answered — `INVALID_SESSION`
+    when the session is gone, `NETWORK_ERROR` when Naro could not be
+    reached;
+  - the function answered 2xx but its body could not be read as its
+    content type says: `INVALID_RESPONSE`, with `response` beside it.
+- Only Naro's own `INVALID_SESSION` renews the access token and tries once
+  more; your function answering `{ "code": "INVALID_SESSION" }` signs nobody
+  out. A `HEAD` answer has no body, so Naro's refusal of a `HEAD` call is
+  `RELAY_ERROR` with the status alone, and a `HEAD` call is never renewed:
+  the `INVALID_SESSION` that would say so is not there to read.
+- Inside a function, `withNaro(handler)` hands the handler `user` (`id`,
+  `email` — `null` until it is confirmed — and `emailVerified`, or `null`),
+  `role` (`anon`, `authenticated`, `service`, or `null` for a function
+  deployed with `--no-verify-jwt`), `traceId`, `naro` and `naroAdmin`. Naro
+  checked the caller before your code runs; `withNaro` does not check again.
+  `naro` sends `NARO_ANON_KEY` and the caller's token, so the tables'
+  policies apply; `naroAdmin` sends `NARO_SERVICE_KEY` and skips them, and
+  is made the first time you read it. Outside a Naro function `withNaro`
+  refuses with `withNaro can only run inside a Naro function.`
+- `role` says how the caller came in; `naro` always sends the anon key — use
+  `naroAdmin` for service access.
+- Inside a Naro function, `withNaro` finds the caller for the request it was
+  handed and for one your code rebuilt from it (`req.clone()`,
+  `new Request(req, …)`). `naro` sends the token of the request you hand
+  it, so a request you rebuild must copy `authorization` (or start from
+  `req.headers`): `new Request(req, { headers: { "x-extra": "1" } })` has no
+  `authorization`, and `naro` goes as anon while `context.user` still names
+  the caller. The caller is found per call, not per request: work one call
+  started and your module state keeps (a memoised promise, say) answers with
+  that call's caller when another call awaits it. A rebuilt request whose
+  `x-naro-trace-id` is not this call's is refused rather than run as this
+  call's caller. The trace id belongs to a chain of calls, not to one call
+  (a function calling another passes it on), so two calls sharing one are
+  not told apart.
+- With verify off (`--no-verify-jwt`), Naro checked nobody: `user` is `null`
+  even when `naro` carries the caller's token (the Data API judges that
+  token on each query), and `naro.auth.*` is refused on that client. An
+  `Authorization` that is not a bearer token — a webhook's `Basic …`, or
+  anything but printable ASCII without spaces — gives `naro` no token: it
+  goes as anon.
+- `naro` is `createClient({ url, anonKey, accessToken })`: `accessToken` is
+  a function that returns the token to send, or `null`, read for every
+  call. Such a client never stores, renews or clears a token; `naro.auth`
+  and `naro.channel()` throw on it (Realtime signs in with a session —
+  broadcast from a function with `naroAdmin`), and it cannot take a
+  `serviceKey`.
+- `naro-js/functions` declares the globals Naro provides — `Deno.serve`,
+  `Deno.env` and `EdgeRuntime.waitUntil` — so a function type-checks. Leave
+  `naro/functions` out of your app's `tsconfig.json`
+  (`"exclude": ["naro/functions"]`): a project that also loads Deno's or
+  Next.js's own declarations can see them twice.
+- A function's request has no Cloudflare `request.cf`; the caller's address
+  is in `cf-connecting-ip`.

package/dist/auth/storage.d.ts

@@ -61,6 +61,17 @@ export declare class TokenStore {
     update(transform: (current: string | null) => string | null): Promise<void>;
     /** Stores `next` only if `expected` is still stored, as one operation. */
     replaceIf(expected: string, next: string): Promise<void>;
+    /**
+     * 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: string | null, operation: () => Promise<void>): Promise<boolean>;
     /**
      * Calls `listener` after every write of the token — a sign-in, a
      * sign-out, a renewed session, a cleared INVALID_SESSION — from inside the

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { AuthClient } from "./auth/client.js";
 import { type AuthStorage } from "./auth/storage.js";
 import { type FetchLike } from "./http.js";
+import { FunctionsClient } from "./invoke/client.js";
 import { TableBuilder } from "./query/builder.js";
 import type { RealtimeChannel } from "./realtime/channel.js";
 import type { RealtimeChannelOptions, RealtimeOptions, RealtimeResult } from "./realtime/types.js";
@@ -32,9 +33,17 @@ type CommonOptions = {
      */
     realtime?: RealtimeOptions;
 };
+/**
+ * The token a client sends, from your code (design F20) — a Naro function's
+ * caller, or a token your own auth gives — read for every call; null (or
+ * undefined, or "") sends none. The client then stores, renews and clears
+ * nothing, and `auth` and `channel()` are not available.
+ */
+export type AccessToken = () => string | null | undefined | Promise<string | null | undefined>;
 export type ClientOptions = CommonOptions & ({
     anonKey: string;
     serviceKey?: undefined;
+    accessToken?: AccessToken;
 }
 /**
  * Server only: skips every policy (spec §7). Refused unless the runtime
@@ -43,6 +52,7 @@ export type ClientOptions = CommonOptions & ({
  | {
     serviceKey: string;
     anonKey?: undefined;
+    accessToken?: undefined;
 });
 /** User-facing; quoted in spec §15's "(P1-4 구현 결정)". */
 export declare const CONFIG_MESSAGES: {
@@ -53,6 +63,8 @@ export declare const CONFIG_MESSAGES: {
     readonly serviceKeyOffServer: "A Naro service key (naro_sk_…) 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_…) here and keep the service key on your server.";
     readonly fetch: "This runtime has no fetch. Pass one to createClient({ fetch }).";
     readonly realtime: "createClient's realtime options take a WebSocket class, and heartbeatIntervalMs and timeoutMs in whole milliseconds from 1 to 2147483647.";
+    readonly accessTokenWithServiceKey: "Pass createClient an accessToken or a serviceKey, not both: the service key skips every policy, so the user's token would not count.";
+    readonly accessToken: "createClient's accessToken is a function that returns the user's access token, or null for none.";
 };
 export declare class NaroClient<Database extends DatabaseShape<Database>> {
     #private;
@@ -67,6 +79,11 @@ export declare class NaroClient<Database extends DatabaseShape<Database>> {
      * them, as supabase-js does.
      */
     readonly storage: StorageClient;
+    /**
+     * The project's Naro Functions (design §9): `functions.invoke(name, {
+     * body })`, as in supabase-js.
+     */
+    readonly functions: FunctionsClient;
     constructor(options: ClientOptions);
     /** Start a query on `table`: `.select()`, `.insert()`, `.update()` or `.delete()`. */
     from<Table extends TableName<Database>>(table: Table): TableBuilder<RowOf<TablesOf<Database>[Table]>, InsertOf<TablesOf<Database>[Table]>, UpdateOf<TablesOf<Database>[Table]>>;
@@ -88,8 +105,10 @@ export declare class NaroClient<Database extends DatabaseShape<Database>> {
 }
 /**
  * The one entry point (spec §15). Throws only for a configuration mistake —
- * no url or not an origin, no key, or a service key off a server; every call
- * on the client resolves to `{ data, error }` instead.
+ * no url or not an origin, no key, a service key off a server, or an
+ * accessToken beside a service key or not a function. On a client made with
+ * accessToken, `naro.auth` and `naro.channel()` throw when used, not here.
+ * Every other call on the client resolves to `{ data, error }` instead.
  */
 export declare function createClient<Database extends DatabaseShape<Database> = UntypedDatabase>(options: ClientOptions): NaroClient<Database>;
 export {};

package/dist/errors.d.ts

@@ -92,6 +92,12 @@ export declare function invalidChannel(reason: string): NaroError;
 export declare function invalidChannelConfig(path: string, reason: string): NaroError;
 /** `createClient`'s refusal of a service key off a server, for the call that reaches the socket late. */
 export declare function serviceKeyOffServer(): NaroError;
+/** The accessToken function threw, rejected, or gave what is not a string: nothing is sent. */
+export declare function accessTokenUnavailable(cause: unknown): NaroError;
+/** `naro.auth.<name>` on such a client. */
+export declare function accessTokenAuthMessage(name: string): string;
+/** `naro.channel()` on such a client: the hub takes a session token, which it has none of. */
+export declare const 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.";
 /**
  * The hub's NOT_JOINED, raised before sending. A name that passed
  * channelNameProblem has at most 128 code points, which the hub quotes

package/dist/functions-caller.d.ts

@@ -0,0 +1,13 @@
+export declare const WITH_NARO_MESSAGES: {
+    readonly outside: "withNaro can only run inside a Naro function.";
+};
+/**
+ * The caller's token for `naro`: the Authorization value with `Bearer `
+ * (any case) taken off, as the gate reads it (Naro worker `stripBearer`) —
+ * none when it is empty or one of the project's keys, and none when it is
+ * not printable ASCII without spaces. That last rule turns away another
+ * scheme (a webhook's `Basic …` has a space after the scheme) and anything
+ * `createClient`'s `accessToken` check would refuse — which would end every
+ * `naro` call in ACCESS_TOKEN_UNAVAILABLE instead of going as anon.
+ */
+export declare function callerToken(request: Request): string | null;

package/dist/functions.d.ts

@@ -0,0 +1,65 @@
+import { type DatabaseShape, type NaroClient, type UntypedDatabase } from "./index.js";
+export type NaroFunctionRole = "anon" | "authenticated" | "service";
+/** The caller as the access token says (design F7): the email only once confirmed. */
+export type NaroFunctionUser = {
+    id: string;
+    email: string | null;
+    emailVerified: boolean;
+};
+export type NaroFunctionContext<Database extends DatabaseShape<Database> = UntypedDatabase> = {
+    /** The signed-in caller, or null. */
+    user: NaroFunctionUser | null;
+    /** null when the function was deployed with --no-verify-jwt. */
+    role: NaroFunctionRole | null;
+    traceId: string;
+    /** The anon key and the caller's token: the tables' policies apply. */
+    naro: NaroClient<Database>;
+    /** The service key: skips every policy. Made the first time it is read. */
+    readonly naroAdmin: NaroClient<Database>;
+};
+export type NaroFunctionHandler<Database extends DatabaseShape<Database> = UntypedDatabase> = (request: Request, context: NaroFunctionContext<Database>) => Response | Promise<Response>;
+/**
+ * Wraps a function's handler: `Deno.serve(withNaro(async (req, { user,
+ * naro }) => …))`, or `export default { fetch: withNaro(…) }`. Outside a
+ * Naro function — no context for the request — it refuses before the
+ * handler runs.
+ */
+export declare function withNaro<Database extends DatabaseShape<Database> = UntypedDatabase>(handler: NaroFunctionHandler<Database>): (request: Request, ...rest: unknown[]) => Promise<Response>;
+declare global {
+    namespace Deno {
+        interface ServeHandlerInfo {
+            remoteAddr: {
+                transport: "tcp";
+                hostname: string;
+                port: number;
+            };
+            completed: Promise<void>;
+        }
+        type ServeHandler = (request: Request, info: ServeHandlerInfo) => Response | Promise<Response>;
+        interface ServeOptions {
+            port?: number;
+            hostname?: string;
+            signal?: AbortSignal;
+            onListen?: (address: unknown) => void;
+            onError?: (error: unknown) => Response | Promise<Response>;
+        }
+        interface HttpServer {
+            finished: Promise<void>;
+            shutdown(): Promise<void>;
+        }
+        function serve(handler: ServeHandler): HttpServer;
+        function serve(options: ServeOptions, handler: ServeHandler): HttpServer;
+        function serve(options: ServeOptions & {
+            handler: ServeHandler;
+        }): HttpServer;
+        interface Env {
+            get(name: string): string | undefined;
+            has(name: string): boolean;
+            toObject(): Record<string, string>;
+        }
+        const env: Env;
+    }
+    var EdgeRuntime: {
+        waitUntil<T>(promise: Promise<T>): Promise<T>;
+    };
+}

package/dist/functions.js

@@ -0,0 +1,74 @@
+// src/functions-caller.ts
+var WITH_NARO_MESSAGES = {
+  outside: "withNaro can only run inside a Naro function."
+};
+var KEY_PREFIXES = ["naro_pk_", "naro_sk_"];
+function callerToken(request) {
+  const authorization = request.headers.get("authorization");
+  if (authorization === null) return null;
+  const token = authorization.replace(/^Bearer\s+/i, "");
+  if (token === "" || /^Bearer$/i.test(token)) return null;
+  if (!/^[\x21-\x7E]+$/.test(token)) return null;
+  return KEY_PREFIXES.some((prefix) => token.startsWith(prefix)) ? null : token;
+}
+
+// src/functions.ts
+import {
+  createClient
+} from "./index.js";
+var CONTEXTS = Symbol.for("naro.functions.context");
+var RUNTIME = Symbol.for("naro.functions.runtime");
+function isCall(value) {
+  return typeof value === "object" && value !== null && typeof value.traceId === "string";
+}
+function callOf(request) {
+  const globals = globalThis;
+  const contexts = globals[CONTEXTS];
+  const mapped = contexts instanceof WeakMap ? contexts.get(request) : void 0;
+  if (mapped !== void 0) return mapped;
+  const runtime = globals[RUNTIME];
+  const store = runtime?.requests?.getStore?.();
+  if (isCall(store?.call)) {
+    const traceId = request.headers.get("x-naro-trace-id");
+    if (traceId === null || traceId === store.call.traceId) return store.call;
+  }
+  throw new Error(WITH_NARO_MESSAGES.outside);
+}
+function binding(name) {
+  const env = globalThis.Deno?.env;
+  const value = typeof env?.get === "function" ? env.get(name) : void 0;
+  if (typeof value !== "string" || value === "")
+    throw new Error(WITH_NARO_MESSAGES.outside);
+  return value;
+}
+function withNaro(handler) {
+  return async (request) => {
+    const call = callOf(request);
+    const url = binding("NARO_URL");
+    const anonKey = binding("NARO_ANON_KEY");
+    const token = callerToken(request);
+    const naro = createClient({
+      url,
+      anonKey,
+      accessToken: () => token
+    });
+    let admin;
+    const context = {
+      user: call.user === null ? null : { ...call.user },
+      role: call.role,
+      traceId: call.traceId,
+      naro,
+      get naroAdmin() {
+        admin ??= createClient({
+          url,
+          serviceKey: binding("NARO_SERVICE_KEY")
+        });
+        return admin;
+      }
+    };
+    return handler(request, context);
+  };
+}
+export {
+  withNaro
+};

package/dist/http.d.ts

@@ -7,6 +7,10 @@ import { type NaroError } from "./errors.js";
  * unbound `window.fetch` works.
  */
 export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** Where a client made with `accessToken` reads its token: a string, or null for none. */
+export type AccessTokenSource = {
+    get(): Promise<string | null>;
+};
 export type HttpConfig = {
     /** The project URL without a trailing slash. */
     baseUrl: string;
@@ -20,7 +24,32 @@ export type HttpConfig = {
      * Without it (not signed in) those requests go as anon.
      */
     accessJwt?: TokenStore;
+    /**
+     * Made with the service key: the worker does not read a bearer token on
+     * its requests, so the access JWT is never renewed for them.
+     */
+    service?: boolean;
+    /**
+     * `createClient({ accessToken })` (design F20): the bearer of every data,
+     * storage and function request comes from the app's function, read for
+     * each one. Nothing is stored, renewed or cleared; `accessJwt` is then
+     * absent.
+     */
+    accessToken?: AccessTokenSource;
 };
+/**
+ * A request that carries the access JWT renews it this long before its
+ * `exp`, so it does not expire on the way or on a clock a little ahead of
+ * this one. The worker mints it for 15 minutes.
+ */
+export declare const ACCESS_JWT_MARGIN_MS = 60000;
+/**
+ * The `exp` of a JWT in epoch milliseconds, read without checking the
+ * signature — only to tell when to renew it; the worker verifies it.
+ * Null when it cannot be read: such a token goes as it is, and the worker's
+ * INVALID_SESSION, if it comes, renews it (`call`, `send`).
+ */
+export declare function expiryOf(jwt: string): number | null;
 export type CallOptions = {
     method: "GET" | "POST" | "PUT" | "DELETE";
     /** Below `/_naro/v1`, e.g. `/data/query`. */
@@ -36,7 +65,9 @@ export type CallOptions = {
     withToken: boolean;
     /**
      * Give up after this long: the request is aborted (where the runtime has
-     * AbortController) and the call answers TIMEOUT. None by default.
+     * AbortController) and the call answers TIMEOUT. It is the whole call's —
+     * a token renewal and the one retry count in it (known-issues #339).
+     * None by default.
      */
     timeoutMs?: number;
 };
@@ -62,7 +93,10 @@ export type CallResult = {
  * fetch, an unreadable body and a worker error all come back as `error`.
  *
  * An INVALID_SESSION answer from any route clears the stored token (spec
- * §11.1), but only if it is still the token this request carried.
+ * §11.1), but only if it is still the token this request carried. A Data
+ * or Storage request renews its access JWT before it goes when the JWT is
+ * about to expire (`accessJwtFor`), and once more after the worker refused
+ * it (`renewsOn`).
  */
 export declare function call(config: HttpConfig, options: CallOptions): Promise<CallResult>;
 export type SendOptions = {
@@ -99,6 +133,57 @@ export type SendResult = {
  * envelope, or INVALID_RESPONSE — and every case resolves.
  */
 export declare function send(config: HttpConfig, options: SendOptions): Promise<SendResult>;
+export type UnreadOptions = {
+    method: string;
+    /** Below `/_naro/v1`, e.g. `/functions/hello`. */
+    path: string;
+    /**
+     * The caller's headers. `apikey` is always the client's; an
+     * `authorization` of the caller's goes as it is, and the client's token
+     * is then neither sent nor renewed nor cleared for it (plan P3).
+     */
+    headers: Headers;
+    body?: BodyInit | undefined;
+    /**
+     * How long the whole call waits — renewals and the one retry included —
+     * up to the final answer's headers; the body is never timed.
+     */
+    timeoutMs?: number | undefined;
+    /** The caller's: calls the request off, and the body of an answer that came. */
+    signal?: AbortSignal | undefined;
+    /**
+     * Waited for before anything else, within the same deadline and signal —
+     * `auth.ready()`, a sign-in the page URL carried. Stopping the wait does
+     * not stop what it waits for: the exchange goes on, as a renewal does.
+     */
+    ready?: (() => Promise<unknown>) | undefined;
+};
+export type UnreadResult = {
+    response: Response;
+} | {
+    failed: "network" | "timeout" | "aborted";
+    cause: unknown;
+}
+/** Not sent: the token it needed could not be had (a renewal's error). */
+ | {
+    refused: NaroError;
+};
+/**
+ * The third primitive (design F20), for a function's answer, which is the
+ * function's own — any status, any body: the response comes back unread.
+ * Identity and cookies are as `call`'s: `apikey`, the access JWT (renewed
+ * before it goes when about to expire), `credentials: "omit"`. A stored JWT
+ * is cleared only on Naro's own `401 INVALID_SESSION` — `x-relay-error:
+ * true` — never on a function's answer that happens to say the same; then
+ * it is renewed and the request sent once more, unless its body is a
+ * stream (read once) or the session changed meanwhile (`retryBearer`).
+ * The caller's `signal` answers aborted at once, a renewal in flight
+ * included (`untilStopped`; `send` stops the same way with `untilAborted`);
+ * `timeoutMs` is the whole call's
+ * (known-issues #339): the wait for `ready`, the renewals, both sends and
+ * the reading of a refusal share it, each send ending at its headers.
+ */
+export declare function fetchUnread(config: HttpConfig, options: UnreadOptions): Promise<UnreadResult>;
 /**
  * The worker's 429s that say how long to wait. `RATE_LIMITED` is the
  * sign-in routes' per-address limiter; `WRITE_QUOTA_EXCEEDED` (PR C) is the
@@ -106,3 +191,11 @@ export declare function send(config: HttpConfig, options: SendOptions): Promise<
  * and creating or deleting users wait for 00:00 UTC, reads still work.
  */
 export declare const RETRY_AFTER_CODES: ReadonlySet<string>;
+/**
+ * The sign-in limiter says in `X-Retry-After` how many seconds to wait, and
+ * the worker keeps the header on its 429 — and sends the same header, the
+ * seconds to 00:00 UTC, with WRITE_QUOTA_EXCEEDED. It becomes `details.retryAfter`
+ * (seconds), beside any details the worker sent. The worker lists it in
+ * Access-Control-Expose-Headers, so a page on another origin reads it too.
+ */
+export declare function withRetryAfter(error: NaroError, headers: Headers): NaroError;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export { createClient, NaroClient, type ClientOptions } from "./client.js";
+export { createClient, NaroClient, type AccessToken, type ClientOptions, } from "./client.js";
+export { FunctionsError, FunctionsFetchError, FunctionsHttpError, FunctionsRelayError, } from "./invoke/errors.js";
+export type { FunctionInvokeOptions, FunctionsClient, FunctionsResponse, } from "./invoke/client.js";
 export type { AuthAdminApi } from "./auth/admin.js";
 export type { AuthClient } from "./auth/client.js";
 export type { AuthStorage } from "./auth/storage.js";