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

package/dist/emit/cached-read.emitter.js

@@ -0,0 +1,158 @@
+import { canonicalJson } from "@aventara/core/internal";
+import { moduleSpecifierWriter, } from "./module-style.interface.js";
+export function emitCachedReadModules(style) {
+    return [
+        { path: "runtime/canonical-json.ts", source: CANONICAL_JSON_MODULE },
+        {
+            path: "runtime/cached-read.ts",
+            source: cachedReadModuleSource(moduleSpecifierWriter(style)),
+        },
+    ];
+}
+const MAX_READ_URL_LENGTH = 4096;
+const CANONICAL_JSON_MODULE = `// @ts-nocheck
+/**
+ * The canonical JSON (RFC 8785) of a cached read's arguments: @aventara/core's
+ * own writer, its compiled source copied as it is, so one read is one URL.
+ */
+export ${canonicalJson.toString()}
+`;
+function cachedReadModuleSource(from) {
+    return `import { CLIENT_CONTRACT_HASH } from ${from("../metadata")};
+import { canonicalJson as canonicalJsonOf } from ${from("./canonical-json")};
+import { CACHED_READS } from ${from("./descriptor")};
+import {
+	type PlatformSignal,
+	type PreparedOperation,
+	routeOf,
+	sendOperation,
+	sendRead,
+	type TransportConnection,
+} from ${from("./transport")};
+
+/**
+ * Cached reads: a read the ClientContract marks cache is sent as
+ * GET <entrypoint>/_resources/<resource>/find/<variant>?q=<arguments>&v=<hash>,
+ * alone, so a browser or a CDN may keep its answer. q is the arguments'
+ * canonical JSON, percent-encoded, or deflate-raw and base64url when that is
+ * shorter. A URL longer than MAX_READ_URL_LENGTH is POSTed instead.
+ */
+
+/** The longest URL, in characters, a cached read is sent as a GET; a longer one is POSTed. */
+export const MAX_READ_URL_LENGTH = ${MAX_READ_URL_LENGTH};
+
+/** The canonical JSON of a JSON value; throws a TypeError for anything else. */
+const canonicalJson: (value: unknown) => string = canonicalJsonOf;
+
+/** Whether the ClientContract marks this read cache: it is sent as a GET, never grouped. */
+export function isCachedRead(operation: PreparedOperation): boolean {
+	return (
+		operation.family === "find" &&
+		Object.hasOwn(CACHED_READS, operation.resource) &&
+		(CACHED_READS[operation.resource] ?? []).includes(operation.variant)
+	);
+}
+
+/**
+ * Sends one cached read: a GET with its q and v, or a POST to the same route
+ * when its URL would pass MAX_READ_URL_LENGTH or canonical JSON cannot write its
+ * arguments. Settles as every call does.
+ */
+export async function sendCachedRead(
+	connection: TransportConnection,
+	operation: PreparedOperation,
+	signal?: PlatformSignal,
+): Promise<unknown> {
+	let json: string;
+	try {
+		json = canonicalJson(JSON.parse(operation.body));
+	} catch {
+		return sendOperation(connection, operation, signal);
+	}
+	const query = "q=" + (await queryArgument(json)) + "&v=" + encodeURIComponent(CLIENT_CONTRACT_HASH);
+	return (connection.entrypoint + routeOf(operation) + "?" + query).length > MAX_READ_URL_LENGTH
+		? sendOperation(connection, operation, signal)
+		: sendRead(connection, operation, query, signal);
+}
+
+/** q: the JSON percent-encoded, or deflate-raw and base64url when that is shorter. */
+async function queryArgument(json: string): Promise<string> {
+	const plain = encodeURIComponent(json);
+	const compressed = await deflated(json);
+	return compressed !== undefined && compressed.length < plain.length ? compressed : plain;
+}
+
+/** What the client reads of a CompressionStream, where the consumer's lib declares none. */
+interface Compression {
+	readonly writable: {
+		getWriter(): { write(chunk: Uint8Array): Promise<void>; close(): Promise<void> };
+	};
+	readonly readable: {
+		getReader(): { read(): Promise<{ readonly done: boolean; readonly value?: Uint8Array | undefined }> };
+	};
+}
+
+/** The JSON's UTF-8 bytes deflate-raw'd, in base64url; undefined where the runtime cannot. */
+async function deflated(json: string): Promise<string | undefined> {
+	const platform = globalThis as unknown as {
+		readonly CompressionStream?: new (format: string) => Compression;
+		readonly TextEncoder?: new () => { encode(text: string): Uint8Array };
+	};
+	const Stream = platform.CompressionStream;
+	const Encoder = platform.TextEncoder;
+	if (typeof Stream !== "function" || typeof Encoder !== "function") {
+		return undefined;
+	}
+	try {
+		const stream = new Stream("deflate-raw");
+		const writer = stream.writable.getWriter();
+		const written = writer.write(new Encoder().encode(json)).then(() => writer.close());
+		written.catch((): void => undefined);
+		const reader = stream.readable.getReader();
+		const chunks: Uint8Array[] = [];
+		let total = 0;
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) {
+				break;
+			}
+			if (chunk.value !== undefined) {
+				chunks.push(chunk.value);
+				total += chunk.value.length;
+			}
+		}
+		await written;
+		const bytes = new Uint8Array(total);
+		let offset = 0;
+		for (const chunk of chunks) {
+			bytes.set(chunk, offset);
+			offset += chunk.length;
+		}
+		return base64Url(bytes);
+	} catch {
+		return undefined;
+	}
+}
+
+const BASE64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/** Base64url without padding. */
+function base64Url(bytes: Uint8Array): string {
+	let text = "";
+	for (let index = 0; index < bytes.length; index += 3) {
+		const first = bytes[index] ?? 0;
+		const second = bytes[index + 1];
+		const third = bytes[index + 2];
+		const group = (first << 16) | ((second ?? 0) << 8) | (third ?? 0);
+		text += BASE64URL.charAt((group >> 18) & 63) + BASE64URL.charAt((group >> 12) & 63);
+		if (second !== undefined) {
+			text += BASE64URL.charAt((group >> 6) & 63);
+		}
+		if (third !== undefined) {
+			text += BASE64URL.charAt(group & 63);
+		}
+	}
+	return text;
+}
+`;
+}

package/dist/emit/client-surface.emitter.js

@@ -1,5 +1,7 @@
+import { ACCESS_VERB_NAMES } from "@aventara/core/internal";
+import { accessVerbShape, accessVerbsOf, } from "./access.emitter.js";
 import { contractHasFieldChecks } from "./field-check.emitter.js";
-import { shapedContractType } from "./json-shape.emitter.js";
+import { jsonSchemaType, shapedContractType } from "./json-shape.emitter.js";
 import { importSpecifier, } from "./module-style.interface.js";
 import { ownPropertyKey } from "./name.deriver.js";
 export function emitClientSurfaceModule(contract, names, style) {
@@ -18,6 +20,58 @@ export function emitClientSurfaceModule(contract, names, style) {
     const renamedEntries = renamed.length === 0
         ? ""
         : ` ${renamed.map((property) => `${ownPropertyKey(property.contractName)}: ${JSON.stringify(property.property)}`).join(", ")} `;
+    const access = contract.access;
+    const verbs = accessVerbsOf(contract);
+    const argsType = (name) => {
+        const schema = access?.verbs?.[name]?.args;
+        return schema === undefined
+            ? "undefined"
+            : jsonSchemaType(schema);
+    };
+    const argsMembers = ACCESS_VERB_NAMES.filter((name) => accessVerbShape(name).args)
+        .map((name) => `readonly ${name}: ${argsType(name)}`)
+        .join("; ");
+    const accessTypes = access === undefined
+        ? ""
+        : "\n" +
+            "/** One question `$access.can` takes: an action on a Resource, or on the one row its unique `where` names. */\n" +
+            "type AccessQuestion = {\n" +
+            "\treadonly [R in Resource]: {\n" +
+            "\t\treadonly resource: R;\n" +
+            '\t\treadonly action: "read" | "create" | "update" | "delete";\n' +
+            `\t\treadonly where?: AvUniqueWhereInput<${C}, R, ClientScalarForms>;\n` +
+            "\t};\n" +
+            "}[Resource];\n" +
+            "\n" +
+            "/** `avClient.$access`: `can`, and the Aventara Access verbs this deployment offers. */\n" +
+            "type AccessSurface = Pick<\n" +
+            "\tAvAccessVerbs<\n" +
+            "\t\tAccessQuestion,\n" +
+            `\t\t${verbs.includes("me") ? "AvAccessMe" : "never"},\n` +
+            `\t\t{ ${argsMembers} },\n` +
+            '\t\tOmit<AvCallOptions, "grouping">\n' +
+            "\t>,\n" +
+            `\t${["can", ...verbs].map((name) => JSON.stringify(name)).join(" | ")}\n` +
+            ">;\n";
+    const accessMember = (name) => {
+        const shape = accessVerbShape(name);
+        const quoted = JSON.stringify(name);
+        const parameters = shape.args
+            ? "args: unknown, callOptions: AvCallOptions = {}"
+            : "callOptions: AvCallOptions = {}";
+        const args = shape.args ? "args" : "undefined";
+        return shape.resolves === "nothing"
+            ? `\t\t\t\t${name}: async (${parameters}): Promise<void> => {\n\t\t\t\t\tawait callAccess(connect(), ${quoted}, ${args}, callOptions);\n\t\t\t\t},\n`
+            : `\t\t\t\t${name}: async (${parameters}) => callAccess(connect(), ${quoted}, ${args}, callOptions),\n`;
+    };
+    const accessRuntime = access === undefined
+        ? ""
+        : '\t\tObject.defineProperty(this, "$access", {\n' +
+            "\t\t\tvalue: Object.freeze({\n" +
+            "\t\t\t\tcan: async (questions: readonly unknown[], callOptions: AvCallOptions = {}) => askCan(connect(), questions, callOptions),\n" +
+            verbs.map(accessMember).join("") +
+            "\t\t\t}),\n" +
+            "\t\t});\n";
     const surface = (name, call) => `type ${name} = {\n` +
         `\treadonly [${resourceKey}]: {\n` +
         "\t\treadonly [F in keyof Grammar[R]]: {\n" +
@@ -32,23 +86,37 @@ export function emitClientSurfaceModule(contract, names, style) {
                 ? ""
                 : `import type { JsonFieldType } from ${from("./derivation/contracts/json-shape")};\n`) +
             `import type { AvApplicationScalarForms } from ${from("./derivation/contracts/scalar-value-type")};\n` +
-            `import type { AvOperationArgumentsFor, AvResourceKey } from ${from("./derivation/operations/operation-arguments")};\n` +
+            (access === undefined
+                ? `import type { AvOperationArgumentsFor, AvResourceKey } from ${from("./derivation/operations/operation-arguments")};\n`
+                : `import type { AvOperationArgumentsFor, AvResourceKey, AvUniqueWhereInput } from ${from("./derivation/operations/operation-arguments")};\n`) +
             `import type { ${interactive ? "AvDeferredOperationCall, " : ""}AvOperationCall, AvOperationGrammar } from ${from("./derivation/operations/operation-call")};\n` +
             `import type { AvOperationFamily, AvOperationIdentity } from ${from("./derivation/operations/operation-identity")};\n` +
             `import type { AdmittedOperationResult } from ${from("./derivation/operations/operation-result")};\n` +
             (interactive
                 ? `import type { AvOperation, AvTransactionResults } from ${from("./derivation/transactions/deferred-operation")};\n`
                 : "") +
+            (access === undefined
+                ? ""
+                : `import type { AvAccessVerbs } from ${from("./derivation/policy/access-verbs")};\n`) +
             `import { DEFAULT_ENTRYPOINT } from ${from("./metadata")};\n` +
+            (verbs.length === 0
+                ? ""
+                : `import { callAccess } from ${from("./runtime/access")};\n`) +
             `import type { AvDecimal } from ${from("./runtime/decimal")};\n` +
             `import { ADVERTISED_OPERATIONS } from ${from("./runtime/descriptor")};\n` +
             (checked
                 ? `import { ${interactive ? "checkOperation, checkPlan" : "checkOperation"} } from ${from("./runtime/field-validators")};\n`
                 : "") +
+            `import { all, CallQueue${interactive ? ", withSignal" : ""} } from ${from("./runtime/operation-set")};\n` +
             (interactive
                 ? `import { deferOperation, runTransaction } from ${from("./runtime/transaction")};\n`
                 : "") +
-            `import { type AvCallOptions, execute, type AvFetch, type TransportConnection } from ${from("./runtime/transport")};\n` +
+            (access === undefined
+                ? `import type { AvCallOptions, AvFetch, PlatformSignal, TransportConnection } from ${from("./runtime/transport")};\n`
+                : `import { askCan, type AvCallOptions, type AvFetch, type PlatformSignal, type TransportConnection } from ${from("./runtime/transport")};\n`) +
+            (verbs.includes("me")
+                ? `import type { AvAccessMe } from ${from("./types")};\n`
+                : "") +
             "\n" +
             `export type { AvCallOptions } from ${from("./runtime/transport")};\n` +
             "\n" +
@@ -66,6 +134,11 @@ export function emitClientSurfaceModule(contract, names, style) {
             "\treadonly entrypoint?: string;\n" +
             "\t/** A custom fetch, for authentication or tests; the platform's otherwise. */\n" +
             "\treadonly fetch?: AvFetch;\n" +
+            "\t/**\n" +
+            "\t * false sends every call to its own route. Otherwise the calls made\n" +
+            "\t * together (in one tick) go out as one Operation Set, POST /_all.\n" +
+            "\t */\n" +
+            "\treadonly grouping?: boolean;\n" +
             "}\n" +
             "\n" +
             (shaped === undefined
@@ -99,9 +172,30 @@ export function emitClientSurfaceModule(contract, names, style) {
                     "/** Sends the handles as one plan and resolves their results as a typed tuple. */\n" +
                     "type TransactionCall = <const Steps extends readonly AvOperation<unknown>[]>(\n" +
                     "\tsteps: Steps,\n" +
-                    "\toptions?: AvCallOptions,\n" +
+                    '\toptions?: Omit<AvCallOptions, "grouping">,\n' +
                     ") => Promise<AvTransactionResults<Steps>>;\n"
                 : "") +
+            accessTypes +
+            "\n" +
+            "/** How one call of `all(…, { settle: true })` settled. */\n" +
+            "type AllSettledEntry<T> =\n" +
+            '\t| { readonly status: "fulfilled"; readonly value: T }\n' +
+            '\t| { readonly status: "rejected"; readonly reason: unknown };\n' +
+            "\n" +
+            "/** Awaits an object of calls together and resolves one value per key, or with `settle: true` one settled entry per key. */\n" +
+            "type AllCall = <E extends { readonly [key: string]: PromiseLike<unknown> }, S extends boolean = false>(\n" +
+            "\tentries: E,\n" +
+            "\toptions?: {\n" +
+            "\t\t/** Aborts every call of this `all`, and no other. */\n" +
+            "\t\treadonly signal?: PlatformSignal;\n" +
+            "\t\t/** true settles every key on its own and never rejects for one; strict otherwise. */\n" +
+            "\t\treadonly settle?: S;\n" +
+            "\t},\n" +
+            ") => Promise<\n" +
+            "\tS extends true\n" +
+            "\t\t? { -readonly [K in keyof E]: AllSettledEntry<Awaited<E[K]>> }\n" +
+            "\t\t: { -readonly [K in keyof E]: Awaited<E[K]> }\n" +
+            ">;\n" +
             "\n" +
             "/** The generated client: one property per Resource this deployment's ClientContract advertises. */\n" +
             "export interface AvClient extends AvClientSurface {}\n" +
@@ -120,6 +214,19 @@ export function emitClientSurfaceModule(contract, names, style) {
                     " */\n"
                 : "/** The generated client. */\n") +
             "export class AvClient {\n" +
+            "\t/**\n" +
+            "\t * Awaits an object of calls together, so they go out as one Operation Set,\n" +
+            "\t * and resolves one value per key. Strict: the first failure rejects it and\n" +
+            "\t * aborts its other calls (fail-fast, not atomic: what already ran stays\n" +
+            "\t * done). With `settle: true` every key settles as `{ status, value }` or\n" +
+            "\t * `{ status, reason }`. Its `signal` aborts each of its calls and no other.\n" +
+            "\t */\n" +
+            "\tdeclare readonly all: AllCall;\n" +
+            (access === undefined
+                ? ""
+                : "\t/** The policy's answers for the UI (`can`), and the Aventara Access verbs this deployment offers. */\n" +
+                    "\tdeclare readonly $access: AccessSurface;\n" +
+                    (interactive ? "" : "\n")) +
             (interactive
                 ? "\t/** Deferred operations, for `transaction`. */\n" +
                     "\tdeclare readonly tx: AvTxSurface;\n" +
@@ -131,15 +238,14 @@ export function emitClientSurfaceModule(contract, names, style) {
             '\t\tconst entrypoint = (options.entrypoint ?? DEFAULT_ENTRYPOINT).replace(/\\/+$/, "");\n' +
             "\t\tconst given = options.fetch;\n" +
             "\t\tconst connect = (): TransportConnection => ({ entrypoint, fetch: platformFetch(given) });\n" +
+            "\t\tconst queue = new CallQueue(connect, options.grouping !== false);\n" +
             "\t\tfor (const [resource, families] of operationTree(\n" +
             "\t\t\t(resource, family, variant): OperationMethod =>\n" +
             (checked
-                ? "\t\t\t\tasync (args = {}, callOptions = {}) => {\n" +
-                    "\t\t\t\t\tcheckOperation(resource, family, args);\n" +
-                    "\t\t\t\t\treturn execute(connect(), resource, family, variant, args, callOptions);\n" +
-                    "\t\t\t\t},\n"
-                : "\t\t\t\tasync (args = {}, callOptions = {}) =>\n" +
-                    "\t\t\t\t\texecute(connect(), resource, family, variant, args, callOptions),\n") +
+                ? "\t\t\t\t(args = {}, callOptions = {}) =>\n" +
+                    "\t\t\t\t\tqueue.operation(resource, family, variant, args, callOptions, checkOperation),\n"
+                : "\t\t\t\t(args = {}, callOptions = {}) =>\n" +
+                    "\t\t\t\t\tqueue.operation(resource, family, variant, args, callOptions),\n") +
             "\t\t)) {\n" +
             "\t\t\tObject.defineProperty(this, propertyOf(resource), { value: families, enumerable: true });\n" +
             "\t\t}\n" +
@@ -154,12 +260,23 @@ export function emitClientSurfaceModule(contract, names, style) {
                     "\t\t}\n" +
                     '\t\tObject.defineProperty(this, "tx", { value: Object.freeze(deferred) });\n' +
                     '\t\tObject.defineProperty(this, "transaction", {\n' +
-                    "\t\t\tvalue: async (steps: unknown, callOptions: AvCallOptions = {}) =>\n" +
+                    "\t\t\tvalue: (steps: unknown, callOptions: AvCallOptions = {}) => {\n" +
+                    "\t\t\t\tconst plan = Array.isArray(steps) ? [...(steps as readonly unknown[])] : steps;\n" +
+                    "\t\t\t\treturn queue.alone(\n" +
+                    "\t\t\t\t\t(signal) =>\n" +
                     (checked
-                        ? "\t\t\t\trunTransaction(connect(), steps, callOptions, checkPlan),\n"
-                        : "\t\t\t\trunTransaction(connect(), steps, callOptions),\n") +
+                        ? "\t\t\t\t\t\trunTransaction(connect(), plan, withSignal(callOptions, signal), checkPlan),\n"
+                        : "\t\t\t\t\t\trunTransaction(connect(), plan, withSignal(callOptions, signal)),\n") +
+                    "\t\t\t\t\tcallOptions.signal,\n" +
+                    "\t\t\t\t);\n" +
+                    "\t\t\t},\n" +
                     "\t\t});\n"
                 : "") +
+            '\t\tObject.defineProperty(this, "all", {\n' +
+            "\t\t\tvalue: (entries: unknown, allOptions?: { readonly signal?: PlatformSignal; readonly settle?: boolean }) =>\n" +
+            "\t\t\t\tall(entries, allOptions),\n" +
+            "\t\t});\n" +
+            accessRuntime +
             "\t}\n" +
             "}\n" +
             "\n" +

package/dist/emit/client-tree.emitter.d.ts

@@ -1,8 +1,15 @@
 import type { AvContractClient } from "@aventara/core";
-import type { ClientEntrypoint } from "../config/client-config.interface.js";
+import type { EmittedEntrypoint } from "../config/client-config.interface.js";
+import { type RegenerateCommand } from "./banner.emitter.js";
 import { type ClientEmission } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
 /**
  * @throws AvGeneratedNameError when a name cannot be emitted, even renamed.
+ * @throws AvClientConfigError when the ClientContract's Access URL is on an
+ *   origin other than the entrypoint's that `accessOrigins` does not list.
  */
-export declare function emitClientTree(contract: AvContractClient, entrypoint: ClientEntrypoint, style: ClientModuleStyle): ClientEmission;
+export declare function emitClientTree(contract: AvContractClient, entrypoint: EmittedEntrypoint, style: ClientModuleStyle, regenerate?: RegenerateCommand, accessOrigins?: readonly string[]): ClientEmission;
+/** How an entry re-exports `AvClient`: the class itself, or its type alone. */
+export type ClientClassExport = "value" | "type";
+/** The entry's re-exports, its default aside, as source: one statement per module. */
+export declare function clientEntryReExports(style: ClientModuleStyle, clientClass?: ClientClassExport, accessVerbs?: boolean): string;

package/dist/emit/client-tree.emitter.js

@@ -1,20 +1,27 @@
-import { withGeneratedBanner } from "./banner.emitter.js";
+import { AvClientConfigError } from "../config/config.resolver.js";
+import { accessVerbsOf, emitAccessModules } from "./access.emitter.js";
+import { AVCLIENT_REGENERATE, withGeneratedBanner, } from "./banner.emitter.js";
+import { emitCachedReadModules } from "./cached-read.emitter.js";
 import { emitClientSurfaceModule } from "./client-surface.emitter.js";
 import { emitContractCarrierModule } from "./contract-carrier.emitter.js";
-import { emitDerivationModules } from "./derivation.emitter.js";
-import { emitDescriptorModule } from "./descriptor.emitter.js";
+import { ACCESS_DERIVATION_ROOTS, DERIVATION_ROOTS, emitDerivationModules, } from "./derivation.emitter.js";
+import { contractHasCachedReads, emitDescriptorModule, } from "./descriptor.emitter.js";
 import { CLIENT_ENTRY_FILE, GENERATED_DIRECTORY, } from "./emitted-tree.interface.js";
 import { emitEnumsModule } from "./enum.emitter.js";
 import { emitFieldCheckModules } from "./field-check.emitter.js";
 import { moduleSpecifierWriter, } from "./module-style.interface.js";
 import { deriveEmittedNames } from "./name.deriver.js";
 import { emitNamedTypesModule } from "./named-type.emitter.js";
+import { emitOperationSetModule } from "./operation-set.emitter.js";
 import { emitDecimalModule, emitErrorsModule, emitMetadataModule, emitTransportModule, errorsModuleExports, } from "./runtime.emitter.js";
 import { emitScalarCodecModule } from "./scalar.codec.js";
 import { emitTransactionModules } from "./transaction.emitter.js";
-export function emitClientTree(contract, entrypoint, style) {
+export function emitClientTree(contract, entrypoint, style, regenerate = AVCLIENT_REGENERATE, accessOrigins = []) {
+    refuseForeignAccessOrigin(contract, entrypoint, accessOrigins);
     const names = deriveEmittedNames(contract);
-    const derivation = emitDerivationModules();
+    const derivation = emitDerivationModules(undefined, contract.access === undefined
+        ? DERIVATION_ROOTS
+        : [...DERIVATION_ROOTS, ...ACCESS_DERIVATION_ROOTS]);
     const generated = [
         ...derivation,
         emitClientSurfaceModule(contract, names, style),
@@ -24,8 +31,11 @@ export function emitClientTree(contract, entrypoint, style) {
         emitMetadataModule(contract.protocol, entrypoint),
         emitScalarCodecModule(style),
         emitDecimalModule(),
-        emitErrorsModule(),
-        emitTransportModule(style),
+        emitErrorsModule(regenerate),
+        emitTransportModule(style, contract.access !== undefined),
+        emitOperationSetModule(style, contractHasCachedReads(contract)),
+        ...(contractHasCachedReads(contract) ? emitCachedReadModules(style) : []),
+        ...emitAccessModules(contract, style),
         emitNamedTypesModule(contract, names, style),
         ...(contract.transactions === "interactive"
             ? emitTransactionModules(style)
@@ -33,7 +43,10 @@ export function emitClientTree(contract, entrypoint, style) {
         ...emitFieldCheckModules(contract, style, new Set(derivation.map((module) => module.path))),
     ];
     const files = [
-        { path: CLIENT_ENTRY_FILE, source: clientEntrySource(style) },
+        {
+            path: CLIENT_ENTRY_FILE,
+            source: clientEntrySource(style, accessVerbsOf(contract).length > 0),
+        },
         ...generated.map((module) => ({
             path: `${GENERATED_DIRECTORY}/${module.path}`,
             source: module.source,
@@ -44,21 +57,44 @@ export function emitClientTree(contract, entrypoint, style) {
         .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
         .map((file) => ({
         path: file.path,
-        bytes: encoder.encode(withGeneratedBanner(file.source)),
+        bytes: encoder.encode(withGeneratedBanner(file.source, regenerate)),
     }));
     return { tree, style, warnings: names.warnings };
 }
-function clientEntrySource(style) {
-    const specifier = moduleSpecifierWriter(style);
-    const from = (module) => specifier(`./${GENERATED_DIRECTORY}/${module.replace(/\.d\.ts$|\.ts$/, "")}`);
-    return (`export { default } from ${from("client.ts")};\n` +
-        `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype AvCallOptions,\n} from ${from("client.ts")};\n` +
+function clientEntrySource(style, accessVerbs) {
+    return (`export { default } from ${generatedModuleSpecifier(style, "client.ts")};\n` +
+        clientEntryReExports(style, "value", accessVerbs));
+}
+function generatedModuleSpecifier(style, module) {
+    return moduleSpecifierWriter(style)(`./${GENERATED_DIRECTORY}/${module.replace(/\.d\.ts$|\.ts$/, "")}`);
+}
+export function clientEntryReExports(style, clientClass = "value", accessVerbs = false) {
+    const from = (module) => generatedModuleSpecifier(style, module);
+    return ((clientClass === "value"
+        ? `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype AvCallOptions,\n} from ${from("client.ts")};\n`
+        : `export type { AvClient, AvClientOptions, AvCallOptions } from ${from("client.ts")};\n`) +
         `export type { AvFetch } from ${from("runtime/transport.ts")};\n` +
         `export type { AvOperation } from ${from("derivation/transactions/deferred-operation.d.ts")};\n` +
         `export type * from ${from("types.d.ts")};\n` +
         `export * from ${from("enums.ts")};\n` +
         `export { AvDecimal } from ${from("runtime/decimal.ts")};\n` +
+        `export { avLazy } from ${from("runtime/operation-set.ts")};\n` +
         `export {\n${errorsModuleExports()
             .map((name) => `\t${name},\n`)
-            .join("")}} from ${from("runtime/errors.ts")};\n`);
+            .join("")}} from ${from("runtime/errors.ts")};\n` +
+        (accessVerbs
+            ? `export { AvAccessError } from ${from("runtime/access.ts")};\n`
+            : ""));
+}
+function refuseForeignAccessOrigin(contract, entrypoint, accessOrigins) {
+    const url = contract.access?.url;
+    if (url === undefined || url.startsWith("/")) {
+        return;
+    }
+    const origin = new URL(url).origin;
+    if (origin === entrypoint.deployment?.origin ||
+        accessOrigins.includes(origin)) {
+        return;
+    }
+    throw new AvClientConfigError(`the ClientContract's Aventara Access URL is on ${origin}, not on the entrypoint's origin; $access sends sign-in credentials there, so it is emitted only when avclient's framework.client.ts lists that origin in accessOrigins (a same-origin client from aventara-build --client takes none: mount Access on the app's own origin).`);
 }

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

@@ -5,8 +5,6 @@ export declare const DERIVATION_ROOTS: readonly string[];
  * (POSIX-separated); `undefined` when there is none.
  */
 export type DeclarationReader = (relative: string) => string | undefined;
-/** The published declarations of the `@aventara/core` this package resolves. */
-export declare function publishedCoreDeclarations(): DeclarationReader;
 /**
  * Core's declaration closure from {@link DERIVATION_ROOTS}, as modules under
  * `derivation/`, in UTF-16 code-unit order of their path.
@@ -14,4 +12,6 @@ export declare function publishedCoreDeclarations(): DeclarationReader;
  * @throws Error when the closure cannot be transported — a defect of the
  *   installed `@aventara/core`, never of the consumer's input.
  */
-export declare function emitDerivationModules(read?: DeclarationReader): readonly EmittedModule[];
+/** The roots a client with the `access` section copies besides {@link DERIVATION_ROOTS}. */
+export declare const ACCESS_DERIVATION_ROOTS: readonly string[];
+export declare function emitDerivationModules(read?: DeclarationReader, roots?: readonly string[]): readonly EmittedModule[];

package/dist/emit/derivation.emitter.js

@@ -13,7 +13,7 @@ export const DERIVATION_ROOTS = [
     "transactions/deferred-operation",
     "transactions/transaction-reference",
 ];
-export function publishedCoreDeclarations() {
+function publishedCoreDeclarations() {
     const dist = path.dirname(fileURLToPath(import.meta.resolve("@aventara/core")));
     return (relative) => {
         try {
@@ -27,9 +27,12 @@ export function publishedCoreDeclarations() {
         }
     };
 }
-export function emitDerivationModules(read = publishedCoreDeclarations()) {
+export const ACCESS_DERIVATION_ROOTS = [
+    "policy/access-verbs",
+];
+export function emitDerivationModules(read = publishedCoreDeclarations(), roots = DERIVATION_ROOTS) {
     const copied = new Map();
-    const queue = DERIVATION_ROOTS.map((root) => `${root}.d.ts`);
+    const queue = roots.map((root) => `${root}.d.ts`);
     while (queue.length > 0) {
         const file = queue.shift();
         if (copied.has(file)) {

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

@@ -2,3 +2,5 @@ import type { AvContractClient } from "@aventara/core";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 /** `generated/runtime/descriptor.ts`, before the banner. */
 export declare function emitDescriptorModule(contract: AvContractClient): EmittedModule;
+/** Whether the ClientContract marks any read `cache`: a client that sends GETs. */
+export declare function contractHasCachedReads(contract: AvContractClient): boolean;

package/dist/emit/descriptor.emitter.js

@@ -51,9 +51,36 @@ export function emitDescriptorModule(contract) {
             "\tresource: string,\n" +
             "\tfamily: string,\n" +
             "\tvariant: string,\n" +
-            `])[] = [${advertised.length === 0 ? "" : `\n${advertised.join("")}`}];\n`,
+            `])[] = [${advertised.length === 0 ? "" : `\n${advertised.join("")}`}];\n` +
+            "\n" +
+            "/** The ClientContract's limits a group of calls is split by: entries per Operation Set, and request bytes. */\n" +
+            "export const OPERATION_SET_LIMITS: { readonly maxAll: number; readonly maxRequestBytes: number } = {\n" +
+            `\tmaxAll: ${JSON.stringify(contract.limits.maxAll)},\n` +
+            `\tmaxRequestBytes: ${JSON.stringify(contract.limits.maxRequestBytes)},\n` +
+            "};\n" +
+            cachedReadsSource(contract),
     };
 }
+function cachedReadsSource(contract) {
+    const entries = codeUnitOrder(Object.keys(contract.resources)).flatMap((name) => {
+        const variants = codeUnitOrder(Object.keys(contract.resources[name]?.cache ?? {}));
+        return variants.length === 0
+            ? []
+            : [
+                `\t${ownPropertyKey(name)}: [${variants.map((variant) => JSON.stringify(variant)).join(", ")}],\n`,
+            ];
+    });
+    return entries.length === 0
+        ? ""
+        : "\n" +
+            "/** Per Resource, the find variants served as a cached read: sent as a GET. */\n" +
+            "export const CACHED_READS: { readonly [resource: string]: readonly string[] } = {\n" +
+            entries.join("") +
+            "};\n";
+}
+export function contractHasCachedReads(contract) {
+    return Object.values(contract.resources).some((resource) => Object.keys(resource.cache ?? {}).length > 0);
+}
 function decodingOf(field) {
     if (field === undefined) {
         return undefined;

package/dist/emit/emitted-tree.interface.d.ts

@@ -8,7 +8,7 @@ export declare const LEGACY_CLIENT_ENTRY_FILES: readonly string[];
 /** The directory holding every other emitted module, under `generateAt`. */
 export declare const GENERATED_DIRECTORY = "generated";
 export type DerivationModulePath = `derivation/${string}.d.ts`;
-export type GeneratedModulePath = DerivationModulePath | "client.ts" | "contract.ts" | "enums.ts" | "metadata.ts" | "runtime/codec.ts" | "runtime/decimal.ts" | "runtime/descriptor.ts" | "runtime/errors.ts" | "runtime/field-check.evaluator.ts" | "runtime/field-validators.ts" | "runtime/fingerprint.ts" | "runtime/transaction.ts" | "runtime/transport.ts" | "types.d.ts";
+export type GeneratedModulePath = DerivationModulePath | "client.ts" | "contract.ts" | "enums.ts" | "metadata.ts" | "runtime/access.ts" | "runtime/cached-read.ts" | "runtime/canonical-json.ts" | "runtime/codec.ts" | "runtime/decimal.ts" | "runtime/descriptor.ts" | "runtime/errors.ts" | "runtime/field-check.evaluator.ts" | "runtime/field-validators.ts" | "runtime/fingerprint.ts" | "runtime/operation-set.ts" | "runtime/transaction.ts" | "runtime/transport.ts" | "types.d.ts";
 export declare const CONTRACT_CARRIER_MODULE = "contract.ts";
 /** A path in the emitted tree: relative to `generateAt`, POSIX-separated. */
 export type EmittedFilePath = typeof CLIENT_ENTRY_FILE | `${typeof GENERATED_DIRECTORY}/${GeneratedModulePath}`;

package/dist/emit/field-check.emitter.d.ts

@@ -4,7 +4,7 @@ import { type ClientModuleStyle } from "./module-style.interface.js";
 /** Where `@aventara/core` publishes the evaluator's source, relative to its package root. */
 export declare const EVALUATOR_SOURCE = "src/runtime/field-check.evaluator.ts";
 /** Reads the evaluator's published source; `undefined` when core publishes none. */
-export type EvaluatorSourceReader = () => string | undefined;
+type EvaluatorSourceReader = () => string | undefined;
 /** The evaluator's source as the `@aventara/core` this package resolves publishes it. */
 export declare function publishedCoreEvaluator(): EvaluatorSourceReader;
 /** Whether the ClientContract carries any check: a field's validators or a Json Shape node's. */
@@ -19,3 +19,4 @@ export declare function contractHasFieldChecks(contract: AvContractClient): bool
  *   `@aventara/core`, never of the consumer's input.
  */
 export declare function emitFieldCheckModules(contract: AvContractClient, style: ClientModuleStyle, derivation: ReadonlySet<string>, read?: EvaluatorSourceReader): readonly EmittedModule[];
+export {};