@aventara/client 1.0.0-rc.1 → 1.0.0-rc.11

package/dist/config/config.loader.js

@@ -9,7 +9,15 @@ export const CLIENT_CONFIG_FILE_EXTENSIONS = [
     ".mts",
     ".cts",
 ];
-export const CLIENT_CONFIG_BASENAME = "framework.client";
+export const CLIENT_CONFIG_FILE_EXTENSIONS_AS_LISTED = [
+    ".ts",
+    ".mts",
+    ".cts",
+    ".js",
+    ".mjs",
+    ".cjs",
+];
+const CLIENT_CONFIG_BASENAME = "framework.client";
 export const CLIENT_CONFIG_FILE = `${CLIENT_CONFIG_BASENAME}.ts`;
 export function clientConfigFilesIn(directory) {
     return CLIENT_CONFIG_FILE_EXTENSIONS.map((extension) => `${CLIENT_CONFIG_BASENAME}${extension}`).filter((name) => statSync(path.resolve(directory, name), {
@@ -27,7 +35,8 @@ export function findClientConfigFile(directory) {
 export async function loadClientConfigFile(directory) {
     const name = findClientConfigFile(directory);
     if (name === undefined) {
-        throw new AvClientConfigError(`no ${CLIENT_CONFIG_BASENAME}.{${CLIENT_CONFIG_FILE_EXTENSIONS.map((extension) => extension.slice(1)).join(",")}} in ${path.resolve(directory)}; create ${CLIENT_CONFIG_FILE} with ` +
+        const [first, ...others] = CLIENT_CONFIG_FILE_EXTENSIONS_AS_LISTED;
+        throw new AvClientConfigError(`no ${CLIENT_CONFIG_BASENAME}${first}, ${others.slice(0, -1).join(", ")} or ${others.at(-1)} in ${path.resolve(directory)}; create ${CLIENT_CONFIG_FILE} with ` +
             "`export default defineClientConfig({ entrypoint, generateAt })` (or run `avclient init`) and run the generator from its directory.");
     }
     const file = path.resolve(directory, name);
@@ -66,10 +75,19 @@ function clientConfigOf(file, config) {
     if (tsconfigFile !== undefined && typeof tsconfigFile !== "string") {
         throw new AvClientConfigError(`${file}'s tsconfigFile must be a string, a path relative to ${path.dirname(file)}.`);
     }
+    const accessOrigins = members.accessOrigins;
+    if (accessOrigins !== undefined && !Array.isArray(accessOrigins)) {
+        throw new AvClientConfigError(`${file}'s accessOrigins must be a list of origins ("https://auth.example.com"), each a string or env("NAME").`);
+    }
     return {
         entrypoint: configValueOf(file, "entrypoint", members.entrypoint),
         generateAt: configValueOf(file, "generateAt", members.generateAt),
         ...(tsconfigFile === undefined ? {} : { tsconfigFile }),
+        ...(accessOrigins === undefined
+            ? {}
+            : {
+                accessOrigins: accessOrigins.map((origin) => configValueOf(file, "accessOrigins", origin)),
+            }),
     };
 }
 function configValueOf(file, member, value) {

package/dist/config/config.resolver.d.ts

@@ -1,4 +1,4 @@
-import type { AvClientConfigInput, AvEnvReference, ClientEntrypoint, ResolvedClientConfig } from "./client-config.interface.js";
+import type { AvClientConfigInput, AvEnvReference, ClientEntrypoint, EmittedEntrypoint, ResolvedClientConfig, SameOriginEntrypoint } from "./client-config.interface.js";
 import type { EnvCascadeResolution } from "./env.cascade.js";
 /** Gives a `framework.client.ts` its type: returns `config` unchanged. */
 export declare function defineClientConfig(config: AvClientConfigInput): AvClientConfigInput;
@@ -11,7 +11,7 @@ export declare function env(name: string): AvEnvReference;
 export declare class AvClientConfigError extends Error {
     readonly name = "AvClientConfigError";
 }
-export interface ClientConfigResolutionInput {
+interface ClientConfigResolutionInput {
     readonly config: AvClientConfigInput;
     readonly cascade: EnvCascadeResolution;
     /** The directory holding the config file; `generateAt` resolves against it. */
@@ -26,4 +26,11 @@ export declare function resolveClientConfig(input: ClientConfigResolutionInput):
  * @throws AvClientConfigError in one sentence that does not echo the value.
  */
 export declare function resolveEntrypoint(value: string): ClientEntrypoint;
-export declare function entrypointHref(entrypoint: ClientEntrypoint): string;
+/**
+ * The same-origin entrypoint of a framework mounted at `api`.
+ *
+ * @throws AvClientConfigError when `api` is not a mount path.
+ */
+export declare function sameOriginEntrypoint(api: string): SameOriginEntrypoint;
+export declare function entrypointHref(entrypoint: EmittedEntrypoint): string;
+export {};

package/dist/config/config.resolver.js

@@ -24,9 +24,27 @@ export function resolveClientConfig(input) {
             : {
                 tsconfigFile: path.resolve(input.configDirectory, tsconfigFile),
             }),
+        accessOrigins: (input.config.accessOrigins ?? []).map((origin) => resolveAccessOrigin(resolveValue("accessOrigins", origin, input.cascade))),
         mode: input.cascade.mode,
     };
 }
+function resolveAccessOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        url = undefined;
+    }
+    if (url === undefined ||
+        (url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.origin !== value.replace(/\/$/u, "").toLowerCase()) {
+        throw new AvClientConfigError('accessOrigins holds a value that is no http(s) origin; each must be scheme, host and port alone ("https://auth.example.com").');
+    }
+    return url.origin;
+}
 function resolveValue(field, value, cascade) {
     if (typeof value === "string") {
         if (value === "")
@@ -77,7 +95,17 @@ export function resolveEntrypoint(value) {
 function writtenMountPath(value) {
     return value.replace(/^[A-Za-z][A-Za-z0-9+.-]*:[/\\]*[^/\\?#]*/u, "");
 }
+export function sameOriginEntrypoint(api) {
+    const normalized = AvProtocol.normalizeEntrypoint(api);
+    if (!normalized.ok) {
+        throw new AvClientConfigError(`api ${normalized.message}.`);
+    }
+    return { path: normalized.path };
+}
 export function entrypointHref(entrypoint) {
+    if (entrypoint.deployment === undefined) {
+        return entrypoint.path;
+    }
     const url = new URL(entrypoint.deployment.href);
     url.pathname = entrypoint.path === "" ? "/" : entrypoint.path;
     return url.href.replace(/\/$/, "");

package/dist/config/env.cascade.d.ts

@@ -2,10 +2,8 @@
 export type EnvRecord = Readonly<Record<string, string>>;
 /** The process environment as Node types it: values may be `undefined`. */
 export type ProcessEnvInput = Readonly<Record<string, string | undefined>>;
-/** The mode used when neither an explicit mode nor `NODE_ENV` supplies one. */
-export declare const DEFAULT_ENV_MODE = "development";
 export type EnvFileReader = (filePath: string) => string | undefined;
-export interface EnvCascadeInput {
+interface EnvCascadeInput {
     /** The directory the five candidates are looked up in. */
     readonly directory: string;
     /** A snapshot of the process environment. Never mutated. */
@@ -31,10 +29,7 @@ export declare class AvEnvFileError extends Error {
 }
 /** The four file candidates for a mode, highest precedence first. */
 export declare function envCascadeCandidates(mode: string): readonly string[];
-export declare function resolveEnvMode(processEnv: ProcessEnvInput, explicit?: string): string;
 export declare function resolveEnvCascade(input: EnvCascadeInput): EnvCascadeResolution;
-/** Reads a candidate from disk; `ENOENT` alone means "not there". */
-export declare function readEnvFileFromDisk(filePath: string): string | undefined;
 /**
  * Parses one file's content. A file whose content holds a line the parser would
  * silently discard is malformed: the user wrote something they expect to take
@@ -50,3 +45,4 @@ export declare function parseEnvFile(filePath: string, content: string): Record<
  * spanning lines — or, when there is none, to the end of its own line.
  */
 export declare function firstDiscardedLine(content: string): number | undefined;
+export {};

package/dist/config/env.cascade.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parseEnv } from "node:util";
-export const DEFAULT_ENV_MODE = "development";
+const DEFAULT_ENV_MODE = "development";
 export class AvEnvFileError extends Error {
     filePath;
     reason;
@@ -15,7 +15,7 @@ export class AvEnvFileError extends Error {
 export function envCascadeCandidates(mode) {
     return [`.env.${mode}.local`, `.env.${mode}`, ".env.local", ".env"];
 }
-export function resolveEnvMode(processEnv, explicit) {
+function resolveEnvMode(processEnv, explicit) {
     if (explicit !== undefined && explicit !== "")
         return explicit;
     const nodeEnv = processEnv.NODE_ENV;
@@ -44,7 +44,7 @@ export function resolveEnvCascade(input) {
     }
     return { mode, env: Object.freeze(env), candidates, loaded };
 }
-export function readEnvFileFromDisk(filePath) {
+function readEnvFileFromDisk(filePath) {
     try {
         return readFileSync(filePath, "utf8");
     }

package/dist/config/module-style.resolver.d.ts

@@ -1,12 +1,10 @@
-import type { TsConfigJsonResolved } from "get-tsconfig";
-import type { ClientModuleStyle, ImportFileExtension, ModuleFormat } from "../emit/module-style.interface.js";
-import { type LocatedTsconfig } from "./tsconfig.locator.js";
+import type { ClientModuleStyle } from "../emit/module-style.interface.js";
 /** What the run follows, and where it read it from. */
 export interface ResolvedModuleStyle extends ClientModuleStyle {
     /** The tsconfig the style was inferred from. */
     readonly tsconfig: string;
 }
-export interface ModuleStyleInput {
+interface ModuleStyleInput {
     /** The absolute `generateAt`. */
     readonly generateAt: string;
     /** The generated entry file, absolute: the file the project must include. */
@@ -23,5 +21,4 @@ export interface ModuleStyleInput {
 export declare function resolveModuleStyle(input: ModuleStyleInput): ResolvedModuleStyle;
 /** The refusal of a project with no tsconfig: a JavaScript project. */
 export declare function noTsconfigRefusal(generateAt: string): string;
-export declare function importFileExtensionOf(config: TsConfigJsonResolved): ImportFileExtension;
-export declare function moduleFormatOf(tsconfig: LocatedTsconfig, generateAt: string): ModuleFormat;
+export {};

package/dist/config/module-style.resolver.js

@@ -20,7 +20,7 @@ export function noTsconfigRefusal(generateAt) {
         "(`npx tsc --init` writes one), or, if it has one this search does not find, name it with `tsconfigFile` " +
         "in your framework.client config. Nothing was written.");
 }
-export function importFileExtensionOf(config) {
+function importFileExtensionOf(config) {
     const options = config.compilerOptions;
     if (options?.allowImportingTsExtensions ||
         options?.rewriteRelativeImportExtensions) {
@@ -32,7 +32,7 @@ export function importFileExtensionOf(config) {
         ? ""
         : "js";
 }
-export function moduleFormatOf(tsconfig, generateAt) {
+function moduleFormatOf(tsconfig, generateAt) {
     const module = tsconfig.config.compilerOptions?.module?.toLowerCase();
     if (module === undefined || module === "") {
         return "esm";

package/dist/config/tsconfig.locator.d.ts

@@ -4,7 +4,7 @@ export interface LocatedTsconfig {
     readonly path: string;
     readonly config: TsConfigJsonResolved;
 }
-export interface TsconfigLocation {
+interface TsconfigLocation {
     /** The absolute `generateAt`: the search starts there. */
     readonly generateAt: string;
     /** The generated entry file the project must include, absolute. */
@@ -19,3 +19,4 @@ export interface TsconfigLocation {
  * @throws AvClientConfigError when the named `tsconfigFile` is missing or unreadable.
  */
 export declare function locateTsconfig(location: TsconfigLocation): LocatedTsconfig | undefined;
+export {};

package/dist/config/tsconfig.locator.js

@@ -11,18 +11,30 @@ export function locateTsconfig(location) {
         return undefined;
     }
     if (found.config.references === undefined ||
-        createFilesMatcher(found)(location.entryFile) !== undefined) {
+        includesEntry(found, location.entryFile)) {
         return found;
     }
     for (const reference of found.config.references) {
         const referenced = referencedTsconfig(found.path, reference.path);
         if (referenced !== undefined &&
-            createFilesMatcher(referenced)(location.entryFile) !== undefined) {
+            includesEntry(referenced, location.entryFile)) {
             return referenced;
         }
     }
     return found;
 }
+function includesEntry(tsconfig, file) {
+    const directory = path.dirname(tsconfig.path);
+    const local = (entries) => entries.map((entry) => path.isAbsolute(entry) ? path.relative(directory, entry) || "." : entry);
+    const { files, include, exclude } = tsconfig.config;
+    const config = {
+        ...tsconfig.config,
+        ...(files === undefined ? {} : { files: local(files) }),
+        ...(include === undefined ? {} : { include: local(include) }),
+        ...(exclude === undefined ? {} : { exclude: local(exclude) }),
+    };
+    return (createFilesMatcher({ path: tsconfig.path, config })(file) !== undefined);
+}
 function namedTsconfig(file) {
     try {
         readFileSync(file, "utf8");

package/dist/contract/contract.acceptance.d.ts

@@ -1,5 +1,4 @@
 import type { AvContractClient } from "@aventara/core";
-export declare const SUPPORTED_PROTOCOL_VERSIONS: ReadonlySet<number>;
 export type ContractRejectionReason = "protocol-unsupported" | "hash-mismatch" | "structure-invalid";
 export type ContractAccepted = {
     readonly accepted: true;

package/dist/contract/contract.acceptance.js

@@ -1,5 +1,5 @@
 import { AVENTARA_PROTOCOL_VERSION, AvCanonicalJsonError, computeClientContractHash, validateClientContractStructure, } from "@aventara/core/internal";
-export const SUPPORTED_PROTOCOL_VERSIONS = new Set([
+const SUPPORTED_PROTOCOL_VERSIONS = new Set([
     AVENTARA_PROTOCOL_VERSION,
 ]);
 const REFUSED_EXIT_CODE = 1;

package/dist/contract/contract.fetcher.d.ts

@@ -7,7 +7,7 @@ export type ContractFetch = (url: URL, init: {
     readonly headers?: Readonly<Record<string, string>>;
 }) => Promise<ContractResponse>;
 export declare const CONTRACT_NOT_MODIFIED: unique symbol;
-export type ContractTransportFailureReason = 
+type ContractTransportFailureReason = 
 /** No response at all: DNS, refused connection, TLS, abort. */
 "request-failed"
 /** A response that is not 2xx — nothing was served for the protocol to judge. */
@@ -28,3 +28,4 @@ export declare function displayUrl(url: URL): string;
  * @throws AvContractTransportError when no JSON value arrives.
  */
 export declare function fetchClientContractBody(entrypoint: ClientEntrypoint, fetch?: ContractFetch, ifNoneMatch?: string): Promise<unknown>;
+export {};

package/dist/contract/contract.loader.d.ts

@@ -1,7 +1,7 @@
 import type { AvContractClient } from "@aventara/core";
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 import { type ContractFetch } from "./contract.fetcher.js";
-export interface ClientContractLoadInput {
+interface ClientContractLoadInput {
     readonly entrypoint: ClientEntrypoint;
     readonly fetch?: ContractFetch;
 }
@@ -10,7 +10,7 @@ export interface ClientContractLoadInput {
  * @throws AvContractProtocolError when what arrived is refused.
  */
 export declare function loadClientContract(input: ClientContractLoadInput): Promise<AvContractClient>;
-export interface ClientContractSince {
+interface ClientContractSince {
     readonly contract: AvContractClient;
     /** The deployment answered `304`: `contract` is the one the caller held. */
     readonly notModified: boolean;
@@ -22,3 +22,4 @@ export interface ClientContractSince {
  * `stored` the GET is unconditional.
  */
 export declare function loadClientContractSince(input: ClientContractLoadInput, stored: AvContractClient | undefined): Promise<ClientContractSince>;
+export {};

package/dist/emit/access.emitter.d.ts

@@ -0,0 +1,12 @@
+import type { AvContractClient } from "@aventara/core";
+import { ACCESS_VERB_NAMES, ACCESS_VERBS } from "@aventara/core/internal";
+import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.interface.js";
+/** One verb `$access` offers beside `can`. */
+export type AccessVerbName = (typeof ACCESS_VERB_NAMES)[number];
+/** Whether a verb takes arguments, and what it resolves (core's verb table). */
+export declare function accessVerbShape(name: AccessVerbName): (typeof ACCESS_VERBS)[AccessVerbName];
+/** The verbs the section states, in `$access`'s order; none without `verbs`. */
+export declare function accessVerbsOf(contract: AvContractClient): readonly AccessVerbName[];
+/** `runtime/access.ts`, or nothing when the section states no verb. */
+export declare function emitAccessModules(contract: AvContractClient, style: ClientModuleStyle): readonly EmittedModule[];

package/dist/emit/access.emitter.js

@@ -0,0 +1,263 @@
+import { ACCESS_VERB_NAMES, ACCESS_VERBS } from "@aventara/core/internal";
+import { importSpecifier, } from "./module-style.interface.js";
+export function accessVerbShape(name) {
+    return ACCESS_VERBS[name];
+}
+export function accessVerbsOf(contract) {
+    const verbs = contract.access?.verbs;
+    return verbs === undefined
+        ? []
+        : ACCESS_VERB_NAMES.filter((name) => verbs[name] !== undefined);
+}
+export function emitAccessModules(contract, style) {
+    const verbs = contract.access?.verbs;
+    const names = accessVerbsOf(contract);
+    if (verbs === undefined || names.length === 0) {
+        return [];
+    }
+    const from = (module) => JSON.stringify(importSpecifier(module, style));
+    const table = names
+        .map((name) => {
+        const verb = verbs[name];
+        return `\t${name}: { method: ${JSON.stringify(verb?.method)}, path: ${JSON.stringify(verb?.path)}, result: ${JSON.stringify(verb?.result)} },\n`;
+    })
+        .join("");
+    return [
+        {
+            path: "runtime/access.ts",
+            source: `import { AvTransportError } from ${from("./errors")};
+import type { AvCallOptions, PlatformSignal, TransportConnection } from ${from("./transport")};
+
+/**
+ * Aventara Access's verbs, as this deployment's ClientContract states them:
+ * each one a request to Access's own route, its result projected onto the
+ * schema the ClientContract promises.
+ */
+
+/**
+ * Aventara Access answered a verb with a status that is not 2xx. It carries the
+ * status and Access's own code and message; it is no AvError, because Access's
+ * answers are not framework envelopes.
+ */
+export class AvAccessError extends Error {
+	override readonly name: string = "AvAccessError";
+	/** The HTTP status Access answered. */
+	readonly status: number;
+	/** Access's own error code, or null when its answer named none. */
+	readonly code: string | null;
+
+	constructor(message: string, status: number, code: string | null) {
+		super(message);
+		this.status = status;
+		this.code = code;
+	}
+}
+
+/** Where the app mounted Aventara Access. */
+const ACCESS_URL = ${JSON.stringify(contract.access?.url ?? "")};
+
+/** Each verb this client offers: its route under ACCESS_URL and its result's schema. */
+const VERBS = {
+${table}} as const;
+
+/** One verb this client offers. */
+export type AccessVerb = keyof typeof VERBS;
+
+/** A schema node, as the projection reads it. */
+type Schema = { readonly [key: string]: unknown };
+
+/** What a verb hands fetch. */
+interface AccessInit {
+	readonly method: "GET" | "POST";
+	readonly headers: Readonly<Record<string, string>>;
+	readonly body?: string;
+	readonly cache?: "no-store";
+	readonly signal?: PlatformSignal;
+}
+
+/** What a verb reads of fetch's answer. */
+interface AccessAnswer {
+	readonly status: number;
+	text(): Promise<string>;
+}
+
+/** The URL of a verb's route: a root-relative ACCESS_URL put under an absolute entrypoint's origin. */
+function routeOf(entrypoint: string, path: string): string {
+	const base = ACCESS_URL.replace(/\\/+$/, "");
+	const origin = /^[a-z][a-z0-9+.-]*:\\/\\/[^/?#]*/i.exec(entrypoint)?.[0];
+	return base.startsWith("/") && origin !== undefined ? origin + base + path : base + path;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * \`schema\` as a member's schema.
+ *
+ * @throws TypeError when it is none (a free-form object or list, a tuple read
+ *   past its length): outside the forms a ClientContract states.
+ */
+function memberSchema(schema: unknown): Schema {
+	if (!isRecord(schema)) {
+		throw new TypeError("the schema is not one of the forms a ClientContract states");
+	}
+	return schema as Schema;
+}
+
+/** Whether \`value\` can be read by \`schema\` at all: its JSON type. */
+function fits(value: unknown, schema: Schema): boolean {
+	if (Object.hasOwn(schema, "const")) {
+		return value === schema["const"];
+	}
+	if (Array.isArray(schema["enum"])) {
+		return schema["enum"].includes(value);
+	}
+	for (const keyword of ["anyOf", "oneOf"]) {
+		const options = schema[keyword];
+		if (Array.isArray(options)) {
+			return options.some((option) => fits(value, option as Schema));
+		}
+	}
+	switch (schema["type"]) {
+		case "null":
+			return value === null;
+		case "boolean":
+			return typeof value === "boolean";
+		case "string":
+			return typeof value === "string";
+		case "number":
+			return typeof value === "number";
+		case "integer":
+			return Number.isInteger(value);
+		case "array":
+			return Array.isArray(value);
+		case "object":
+			return isRecord(value);
+		default:
+			return false;
+	}
+}
+
+/**
+ * \`value\` projected onto \`schema\`: every object down to the members the schema
+ * declares, a list member by member. The schema is the promise.
+ *
+ * @throws TypeError when the value is not one the schema describes.
+ */
+function projected(value: unknown, schema: Schema): unknown {
+	if (!fits(value, schema)) {
+		throw new TypeError("the value is not the one the ClientContract describes");
+	}
+	for (const keyword of ["anyOf", "oneOf"]) {
+		const options = schema[keyword];
+		if (Array.isArray(options)) {
+			const option = options.find((candidate) => fits(value, candidate as Schema)) as Schema;
+			return projected(value, option);
+		}
+	}
+	if (Array.isArray(value)) {
+		const prefix = schema["prefixItems"];
+		const items = Array.isArray(prefix) ? undefined : memberSchema(schema["items"]);
+		return Object.freeze(
+			value.map((member: unknown, index: number) =>
+				projected(member, items ?? memberSchema((prefix as readonly unknown[])[index])),
+			),
+		);
+	}
+	if (isRecord(value)) {
+		const properties = schema["properties"];
+		if (isRecord(properties)) {
+			const copy: Record<string, unknown> = {};
+			for (const [key, member] of Object.entries(properties)) {
+				if (Object.hasOwn(value, key) && value[key] !== undefined) {
+					copy[key] = projected(value[key], member as Schema);
+				}
+			}
+			return Object.freeze(copy);
+		}
+		const values = memberSchema(schema["additionalProperties"]);
+		return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, member]) => [key, projected(member, values)])));
+	}
+	return value;
+}
+
+/** Access's error answer, read for its code and message. */
+function refusalOf(verb: AccessVerb, status: number, text: string): AvAccessError {
+	let body: unknown;
+	try {
+		body = JSON.parse(text);
+	} catch {
+		body = undefined;
+	}
+	const code = isRecord(body) && typeof body["code"] === "string" ? body["code"] : null;
+	const message =
+		isRecord(body) && typeof body["message"] === "string" ? body["message"] : "Aventara Access refused $access." + verb + " (HTTP " + status + ").";
+	return new AvAccessError(message, status, code);
+}
+
+/**
+ * Runs one Access verb: one request to its route, its 2xx answer projected onto
+ * its result schema (\`null\` stays \`null\`: no one is signed in).
+ *
+ * @throws AvAccessError on a non-2xx answer; AvTransportError when no answer
+ *   arrived, or the answer is not the value the ClientContract describes. A
+ *   caller's abort rejects with what fetch rejected with.
+ */
+export async function callAccess(
+	connection: TransportConnection,
+	verb: AccessVerb,
+	args: unknown,
+	options: AvCallOptions = {},
+): Promise<unknown> {
+	const { method, path, result } = VERBS[verb];
+	const operation = "$access." + verb;
+	const headers: Record<string, string> = { ...options.headers };
+	let init: AccessInit;
+	if (method === "GET") {
+		init = { method, headers, cache: "no-store" };
+	} else {
+		headers["Content-Type"] = "application/json";
+		init = { method, headers, body: JSON.stringify(args ?? {}) };
+	}
+	if (options.signal !== undefined) {
+		init = { ...init, signal: options.signal };
+	}
+	const fetch = connection.fetch as unknown as (url: string, init: AccessInit) => Promise<AccessAnswer>;
+	let answer: AccessAnswer;
+	let text: string;
+	try {
+		answer = await fetch(routeOf(connection.entrypoint, path), init);
+		text = await answer.text();
+	} catch (error) {
+		if (options.signal?.aborted === true) {
+			throw error;
+		}
+		throw new AvTransportError("The request for " + operation + " failed before any answer arrived.", null);
+	}
+	if (answer.status < 200 || answer.status > 299) {
+		throw refusalOf(verb, answer.status, text);
+	}
+	let value: unknown;
+	try {
+		value = text.trim() === "" ? null : JSON.parse(text);
+	} catch {
+		throw new AvTransportError("The answer to " + operation + " (HTTP " + answer.status + ") is not JSON.", answer.status);
+	}
+	if (value === null) {
+		return null;
+	}
+	try {
+		return projected(value, result as Schema);
+	} catch (error) {
+		throw new AvTransportError(
+			"The answer to " + operation + " (HTTP " + answer.status + ") holds a value this client cannot read: " +
+				(error instanceof Error ? error.message : String(error)),
+			answer.status,
+		);
+	}
+}
+`,
+        },
+    ];
+}

package/dist/emit/banner.emitter.d.ts

@@ -1,7 +1,12 @@
 export declare const GENERATED_OWNERSHIP_LINE = "/* !!! Generated by @aventara/client. Do not edit. !!! */";
+/** The command a generated file says to regenerate it with: a command in backticks, then any words about it. */
+export type RegenerateCommand = `\`${string}\`${string}`;
+/** `avclient generate`'s own: what its banner and errors say. */
+export declare const AVCLIENT_REGENERATE: RegenerateCommand;
+/** `avclient generate`'s banner. */
 export declare const GENERATED_BANNER: readonly string[];
 /** `source` with the banner before it and one blank line between. */
-export declare function withGeneratedBanner(source: string): string;
+export declare function withGeneratedBanner(source: string, regenerate?: RegenerateCommand): string;
 /**
  * How far into a file the ownership line is looked for. The banner opens every
  * emitted file, so the line sits well inside this; a reader never has to read a

package/dist/emit/banner.emitter.js

@@ -1,12 +1,16 @@
 export const GENERATED_OWNERSHIP_LINE = "/* !!! Generated by @aventara/client. Do not edit. !!! */";
-export const GENERATED_BANNER = [
-    "// biome-ignore-all format: generated output",
-    "// biome-ignore-all lint: generated output",
-    GENERATED_OWNERSHIP_LINE,
-    "/* Regenerate with `avclient generate`. */",
-];
-export function withGeneratedBanner(source) {
-    return `${GENERATED_BANNER.join("\n")}\n\n${source}`;
+export const AVCLIENT_REGENERATE = "`avclient generate`";
+function generatedBanner(regenerate = AVCLIENT_REGENERATE) {
+    return [
+        "// biome-ignore-all format: generated output",
+        "// biome-ignore-all lint: generated output",
+        GENERATED_OWNERSHIP_LINE,
+        `/* Regenerate with ${regenerate}. */`,
+    ];
+}
+export const GENERATED_BANNER = generatedBanner();
+export function withGeneratedBanner(source, regenerate = AVCLIENT_REGENERATE) {
+    return `${generatedBanner(regenerate).join("\n")}\n\n${source}`;
 }
 export const GENERATED_OWNERSHIP_HEAD_BYTES = 1024;
 export function carriesGeneratedOwnership(head) {

package/dist/emit/cached-read.emitter.d.ts

@@ -0,0 +1,3 @@
+import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.interface.js";
+export declare function emitCachedReadModules(style: ClientModuleStyle): readonly EmittedModule[];