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

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @aventara/client
 
+## 1.0.0-rc.13
+
+### Minor Changes
+
+- f3b291f: `transactionsStyle` takes a third value, `"server"`: the server still opens transactions, and callers send no plans.
+  A forced call (`forceTransaction`), a write the policy checks after it runs and `ctx.$transaction` run in a
+  transaction as under `"interactive"`, while the layer has no `POST /_transactions` route, a plan sent to it answers as
+  that absent route (`404 A2002`, one `V1006` at `["operations"]`), `framework.transaction` refuses a plan of that
+  origin the same way, the generated client has no `tx` or `transaction`, and an MCP agent layer under it has no
+  `transaction` tool. `client: { transactionsStyle: "server" }` keeps forced writes atomic without letting remote
+  callers send multi-step plans. `forceTransaction` under `"none"` is still a startup error; under `"server"` it is
+  allowed. Like `"interactive"`, `"server"` needs an adapter with transactions (`COMPILER_UNAVAILABLE_CAPABILITY`
+  otherwise). The Contract's `transactions` carries the value, so a layer that states it gets a new Contract hash.
+
+- 73aa797: A generated client takes three hooks, one function each: `new AvClient({ onCall, onSuccess, onError })`. They see
+  every call the client makes: an operation, a cached read, a transaction (once, whatever its steps) and a `$access`
+  call, as an `AvCall` (its `kind`, its `label`, the operation's `resource`, `family` and `variant` or the `$access`
+  verb, and its `requestId` when it sends one; never its arguments).
+
+  - `onCall(call)` runs when the call is made, before it is sent and before grouping. It may return, or resolve to,
+    `AvCallAdditions` for that call's request: `headers`, `credentials`, `cache`, `keepalive`, `priority` and
+    `referrerPolicy`. A header the client sets itself (`Content-Type`, `Accept`, the three `Aventara-*` headers), in
+    its canonical or lower-case spelling, and `method`, `body`, `signal`, `redirect` and `mode` are type errors, each
+    typed as the sentence that refuses it. At runtime such a header in any spelling, a name that is not a valid header
+    name and a value no request can carry (a line break, a control character, or a character outside Latin-1) are dropped with a warning (code
+    `AVENTARA_CLIENT_HOOK_HEADER_DROPPED`), once per header name for each `onCall`. The call's own `headers` option
+    wins over `onCall`'s.
+  - Calls share one `POST /_all` only when their additions are equal (in any order). An async `onCall` holds back only
+    its own call: the call is sent when it settles, with the calls queued then. Calls group when their `onCall` settles
+    together with equal additions; an `onCall` doing its own I/O per call sends each call alone, and one awaiting a
+    shared in-flight promise (cleared once it settles) keeps them in one `/_all`. A hanging `onCall` stalls only its own call, an abort settles that call at once (a `$access` call too), and a
+    call made from inside a hook never waits on the call that ran it.
+  - `onSuccess(call, result)` and `onError(call, error)` are sinks, typed as returning `void`, so any function fits
+    (an async one, `() => router.push("/login")`). What they return is ignored, an async one is not awaited, and the caller gets the same value or rejection, never delayed. `onError`
+    sees a refusal, a validation error, a transport failure and an abort, sent alone or inside an Operation Set.
+  - A hook that throws or rejects is reported once as an `AventaraWarning` (code `AVENTARA_CLIENT_HOOK_THREW`, or
+    `console.warn` where there is no `process.emitWarning`), naming the hook and the call, and skipped. A hook's failure, a value that cannot be read included, never reaches
+    the call, the calls sent with it or the process.
+
+  `fetch` stays a transport swap: it must return the `Response` unread. A token every call needs now goes in `onCall`,
+  read through one shared in-flight promise so the calls still group; the skill and the README say so.
+
+### Patch Changes
+
+- 33419de: `avclient init` now writes a client-only agent skill into the frontend, `.claude/skills/aventara-client/SKILL.md`: how the generated client calls the API, for this `@aventara/client`. The new `avclient skill` command refreshes it after an upgrade; a file you edited is kept with a warning unless you pass `--force`. The generated client still needs no `@aventara/client` at run time.
+
+- a6cebba: `avclient` refuses an entrypoint carrying credentials with a sentence that now says to add them through `onCall`,
+  not a custom `fetch`.
+- e6495a0: The agent skills cover more of this release. The server skill says that a `state` rejecting with a `401` or `403`
+  status answers `A4000` or `A4001`, that `forceTransaction` also runs under `transactionsStyle: "server"` (the way to
+  keep forced writes atomic without client plans), that an enum field takes no validator, and how SQLite's one
+  connection makes a plain operation wait for an open transaction (`AVENTARA_PRISMA_SQLITE_TRANSACTION_JOINED`, the
+  `driver` check). It no longer says that a `ctx` create must write a field the root's or the `application` overlay's
+  `compute.create` fills. The client guide, in both skills, adds `AvCall` and `AvCallAdditions` for typing a hook, that
+  a hanging `onCall` stalls only its own call, the `AVENTARA_CLIENT_OPTIONS_NO_DEFAULT` warning, the refusal of an
+  entrypoint carrying credentials, and how a client of your own computes a transaction step's `fingerprint` with
+  `AvProtocol.fingerprint`.
+
+- a9260d2: The agent skills cover what an agent needs without opening `node_modules`:
+
+  - The frontend skill (`avclient skill`) now explains what a call returns (`Date`, `bigint`, `AvDecimal`, `Uint8Array`), which error class each code throws (`AvTransportError` included), `error.cause.issues` for form errors, transactions with `$ref`, and a new `reference/client-setup.md`: `framework.client.ts` (`defineClientConfig`, `env`, `AVENTARA_API_URL`, `generateAt`), regenerating after the server changed, `avclient generate --yes` in CI, and the stale-client error (`A2005`, `AvContractMismatchError`). It also links the docs for agents.
+  - The server skill (`aventara skill`) adds `reference/avz.md` (every `AvZ` check and Json shape builder, `AvZ.infer`) and covers the `policy` and `access` keys, MCP token claims in `ctx.$state.mcp.claims`, the Next.js `state` example, `avDehydrate`/`avHydrate` and server transactions in Next.js, testing with `createFakeAdapter` (what `execute` receives and returns), switching the database or driver, `ctx.$sql`, `ctx.$transaction` and `ctx.$transport`, the compute stage types, and the `AVENTARA_PREBUILT_STALE` fallback.
+  - With `@aventara/access` installed, the skill now says to write Access's own skill with `avaccess skill` (`npx avaccess skill`, or `pnpm exec avaccess skill`).
+  - Corrected: a write-only field is written `"read"` everywhere; a field pipe or compute stage that returns `undefined` keeps the value; a read compute may be a plain function and gets `field`, `value`, `record` and `ctx`.
+  - `CONFIG_FORBIDDEN_IN_OVERLAY` in the error catalog now names `managedElsewhere` as well as a field `definition`.
+- Updated dependencies [6c3e25c]
+- Updated dependencies [2aaa27d]
+- Updated dependencies [f3b291f]
+- Updated dependencies [2aaa27d]
+- Updated dependencies [e4e8abd]
+- Updated dependencies [e662048]
+- Updated dependencies [f3b291f]
+- Updated dependencies [f3b291f]
+- Updated dependencies [6c3e25c]
+- Updated dependencies [6c3e25c]
+- Updated dependencies [a708188]
+- Updated dependencies [a9260d2]
+  - @aventara/core@1.0.0-rc.13
+
+## 1.0.0-rc.12
+
+### Patch Changes
+
+- afd5eda: `avclient generate` no longer renames a Resource named `all` to `allModel`. The server refuses a Client Contract Resource named `all` when the Framework is built, so no contract it serves carries one.
+- Updated dependencies [fdeee8a]
+  - @aventara/core@1.0.0-rc.12
+
 ## 1.0.0-rc.11
 
 ### Patch Changes

package/README.md

@@ -121,8 +121,9 @@ const maybe = await avClient.User.find.first({ where }); // User | null — a mi
 ```
 
 - `avClient` is the default export: the client of the deployment the tree was generated from.
-  `new AvClient({ entrypoint, fetch })` makes another. `entrypoint` is for a deployment serving exactly the same
-  ClientContract (tests, SSR), and `fetch` is for a custom fetch.
+  `new AvClient({ entrypoint, fetch, onCall, onSuccess, onError })` makes another. `entrypoint` is for a deployment
+  serving exactly the same ClientContract (tests, SSR), `fetch` swaps the transport, and the three hooks see every call
+  (see "Hooks" below).
 - The client has one property per Resource, one per family under it, and one per advertised variant. Only what the
   ClientContract advertises exists, in the type and at runtime. A Resource named like one of the client's own members
   (`all`, `tx`, `transaction`, `then`, `constructor`, `Object.prototype`'s names) is reached as `<name>Model`, with one
@@ -165,6 +166,7 @@ const [campaigns, unread, me] = await Promise.all([
   requests.
 - Sent alone, never grouped: a call with `headers` or a `requestId` (they belong to one request), a call made with
   `{ grouping: false }`, every call of a client made with `new AvClient({ grouping: false })`, and a transaction.
+  Calls whose `onCall` additions differ never share a request: each set of equal additions is its own `/_all`.
 - A server without `/_all` (it answers `A2002`) gets the calls again one by one, and that client stops grouping.
 
 ### Aborting a call
@@ -268,18 +270,66 @@ to the handle's position in the list it runs with. Two mistakes are refused befo
 them in process: one handle twice (`AvValidationError`, `A2004`/`V1001`), and a `$ref` to a handle not in the list
 (`AvValidationError`, `A2007`/`V1010`). A handle is plain data: any client of the same generated tree may run it.
 
-## Custom fetch and authentication
+## Hooks: `onCall`, `onSuccess`, `onError`
 
-`fetch` is typed as your platform's own `fetch` when your `lib` declares one (DOM, `@types/node`), so the platform
-`fetch` is accepted without a cast; with neither, a structural fetch type stands in. The client adds no headers of its
-own beyond the protocol's, so authentication goes in a custom fetch:
+Three options of `new AvClient(…)` see every call the client makes: an operation, a cached read, a transaction (once,
+whatever its steps) and a `$access` call. Each takes the call as an `AvCall`: its `kind` (`"operation"`,
+`"transaction"`, `"access"`), its `label` (`"Post" find.many`), the `resource`, `family` and `variant` of an
+operation, the `verb` of a `$access` call, and its `requestId` when it sends one. Never its arguments.
 
 ```ts
+// One read of the token for every call made while it is in flight, so those calls still group (see below).
+let inFlight: Promise<string> | undefined;
+const token = (): Promise<string> =>
+	(inFlight ??= session.token().finally(() => {
+		inFlight = undefined;
+	}));
+
 const client = new AvClient({
-	fetch: (input, init) => fetch(input, { ...init, headers: { ...init?.headers, Authorization: `Bearer ${token}` } }),
+	onCall: async () => ({ headers: { Authorization: `Bearer ${await token()}` } }),
+	onSuccess: (call, result) => metrics.record(call.label, result),
+	onError: (call, error) => {
+		if (error instanceof AvAuthError) router.replace("/login");
+		else console.warn(call.label, error);
+	},
 });
 ```
 
+- `onCall(call)` runs when the call is made, before it is sent and before the calls made with it are grouped. It may
+  return, or resolve to, `AvCallAdditions` for that call's request: `headers`, and `credentials`, `cache`, `keepalive`,
+  `priority` and `referrerPolicy`. Calls share an Operation Set only when their additions are equal (in any order).
+- An async `onCall` holds back its own call and no other. The calls made together are sent once a microtask passes
+  with no new call; a call whose `onCall` has not settled by then is sent when it settles, together with the calls
+  queued at that moment. So calls group when their `onCall` settles together with equal additions. An `onCall` that
+  does its own I/O for each call (reads the token again for every call) settles each call at its own time and sends
+  each in its own request. To keep grouping, have `onCall` await one shared in-flight promise, cleared once it
+  settles, as `token()` above: every call made while it is in flight settles with it and shares one `/_all`. If
+  `token()` rejects, the call is sent without `Authorization` (the hook warning fires) and will likely reach `onError`
+  as a refusal.
+  A hanging `onCall` stalls only its own call, aborting that call settles it at once, and a call made from inside a
+  hook never waits on the call that ran the hook.
+- What the request sends, in order: `onCall`'s additions, then the call's own `headers` option, which wins over them,
+  then avClient's own headers, which always win. A header avClient sets itself (`Content-Type`, `Accept`,
+  `Aventara-Protocol-Version`, `Aventara-Contract-Hash`, `Aventara-Request-Id`), in its canonical or lower-case
+  spelling, is a type error in `onCall`'s `headers`, and so are `method`, `body`, `signal`, `redirect` and `mode`.
+  At runtime such a header in any spelling, a name that is not a valid header name and a value no request can carry
+  (a line break, a control character, or a character outside Latin-1, such as an emoji or an em dash) are dropped, with a warning (code
+  `AVENTARA_CLIENT_HOOK_HEADER_DROPPED`) naming the header and the call, once per header name for each `onCall`.
+- `onSuccess(call, result)` and `onError(call, error)` are sinks, for side effects only (log, report, navigate). They
+  are typed as returning `void`, so any function fits (`() => router.push("/login")`, an async one), and what they
+  return is ignored. An async one is not awaited: it never delays the caller's result or rejection, and its rejection
+  is reported like a throw. `onError` sees every rejection (a refusal, a validation error, a transport failure,
+  an abort), sent alone or in an Operation Set, and the caller still gets the same rejection.
+- A hook that throws, or rejects, is reported once as a warning (`process.emitWarning`, an `AventaraWarning` with code
+  `AVENTARA_CLIENT_HOOK_THREW`, or `console.warn` where there is no `process`), naming the hook and the call, and is
+  skipped: the call goes on, with no additions when it was `onCall` (as when its value cannot be read). A hook's
+  failure never reaches the call, the calls sent with it or the process.
+
+`fetch` swaps the transport and nothing else (a test's fake, a runtime's own fetch). It is typed as your platform's own
+`fetch` when your `lib` declares one (DOM, `@types/node`), so the platform `fetch` is accepted without a cast; with
+neither, a structural fetch type stands in. It must return the `Response` unread: the client reads the body itself, an
+Operation Set's line by line as it streams. Headers and credentials for every call go in `onCall`.
+
 The platform `fetch` is read when a call is made, not when the client is imported. Importing the client never fails
 where there is no `fetch`; a call does, saying why. An entrypoint carrying credentials is refused when the config is
 resolved.
@@ -316,9 +366,9 @@ export default defineClientConfig({
 });
 ```
 
-A verb on another origin carries cookies only when your `fetch` sends them: pass one that does
-(`new AvClient({ fetch: (url, init) => fetch(url, { ...init, credentials: "include" }) })`), and have Access allow
-that origin with credentials (CORS).
+A verb on another origin carries cookies only when its request asks for them: return `credentials: "include"` from
+`onCall` (`new AvClient({ onCall: () => ({ credentials: "include" }) })`), and have Access allow that origin with
+credentials (CORS).
 
 ## Up to date
 

package/dist/cli/command.parser.d.ts

@@ -1,4 +1,5 @@
-export declare const USAGE = "avclient \u2014 generate a typed Aventara client from a deployed ClientContract.\n\nUsage:\n  avclient generate [--yes]   Read framework.client.ts (or .mts, .cts, .js, .mjs,\n                              .cjs) in the current directory, fetch\n                              <entrypoint>/_contract, and write AvClient.ts and\n                              generated/ into its generateAt directory, its imports\n                              spelled as the project's tsconfig.json says.\n  avclient init [options]     Set up this frontend: write framework.client.ts, the\n                              .env entry, the avclient:generate script and the\n                              @aventara/client devDependency; install; generate.\n      --entrypoint <url>      The server's entrypoint [http://localhost:3000/api].\n      --env-var <NAME>        Read it from this variable [AVENTARA_API_URL].\n      --no-env-var            Write it into framework.client.ts as a literal.\n      --generate-at <dir>     Where the client goes [./src/api].\n      --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n      --skip-install          Print the install instead of running it.\n      --skip-generate         Do not generate now.\n      -y, --yes               Accept every default, and replace differing content.\n  avclient --help             Print this and exit 0.\n  avclient <command> --help   Print that command's usage and exit 0.\n  avclient --version, -v      Print this generator's version and exit 0.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed. Generated\nfiles are replaced on every run; do not edit them.\n\nBefore framework.client.ts is evaluated, the .env cascade is read from the\ncurrent directory, highest precedence first: the process environment,\n.env.<mode>.local, .env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or\n\"development\".\n";
+export declare const USAGE = "avclient \u2014 generate a typed Aventara client from a deployed ClientContract.\n\nUsage:\n  avclient generate [--yes]   Read framework.client.ts (or .mts, .cts, .js, .mjs,\n                              .cjs) in the current directory, fetch\n                              <entrypoint>/_contract, and write AvClient.ts and\n                              generated/ into its generateAt directory, its imports\n                              spelled as the project's tsconfig.json says.\n  avclient init [options]     Set up this frontend: write framework.client.ts, the\n                              .env entry, the avclient:generate script and the\n                              @aventara/client devDependency; install; generate.\n      --entrypoint <url>      The server's entrypoint [http://localhost:3000/api].\n      --env-var <NAME>        Read it from this variable [AVENTARA_API_URL].\n      --no-env-var            Write it into framework.client.ts as a literal.\n      --generate-at <dir>     Where the client goes [./src/api].\n      --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n      --skip-install          Print the install instead of running it.\n      --skip-generate         Do not generate now.\n      -y, --yes               Accept every default, and replace differing content.\n  avclient skill [--force]    Write or refresh this frontend's agent skill\n                              (.claude/skills/aventara-client/); --force replaces\n                              a file you edited. avclient init writes it too.\n  avclient --help             Print this and exit 0.\n  avclient <command> --help   Print that command's usage and exit 0.\n  avclient --version, -v      Print this generator's version and exit 0.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed. Generated\nfiles are replaced on every run; do not edit them.\n\nBefore framework.client.ts is evaluated, the .env cascade is read from the\ncurrent directory, highest precedence first: the process environment,\n.env.<mode>.local, .env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or\n\"development\".\n";
+export declare const SKILL_USAGE = "Usage: avclient skill [--force]\n\nWrite or refresh this frontend's agent skill, .claude/skills/aventara-client/,\nfor this @aventara/client: how the generated client calls the API. A file you\nedited is kept, with a warning.\n\nOptions:\n  --force   Replace a file you edited.\n";
 export declare const GENERATE_USAGE = "Usage: avclient generate [--yes]\n\nRead framework.client.ts (or .mts, .cts, .js, .mjs, .cjs) in the current directory,\nfetch <entrypoint>/_contract, and write AvClient.ts and generated/ into its\ngenerateAt directory, its imports spelled as the project's tsconfig.json says.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed.\n\nBefore the config is evaluated, the .env cascade is read from the current\ndirectory, highest precedence first: the process environment, .env.<mode>.local,\n.env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or \"development\".\n";
 export declare const INIT_USAGE = "Usage: avclient init [options]\n\nSet up this frontend: write framework.client.ts, the .env entry, the avclient:generate\nscript and the @aventara/client devDependency; install; generate.\n\nOptions:\n  --entrypoint <url>             The server's entrypoint [http://localhost:3000/api].\n  --env-var <NAME>               Read it from this variable [AVENTARA_API_URL].\n  --no-env-var                   Write it into framework.client.ts as a literal.\n  --generate-at <dir>            Where the client goes [./src/api].\n  --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n  --skip-install                 Print the install instead of running it.\n  --skip-generate                Do not generate now.\n  --verbose                      Show the install's output as it runs.\n  -y, --yes                      Accept every default, and replace differing content.\n\nOn a terminal every unanswered question is asked; anywhere else, pass its flag\nor --yes, or the run stops before writing anything.\n";
 export type ClientInitCommand = {
@@ -14,9 +15,12 @@ export type ClientInitCommand = {
 /** What the command line asked for. */
 type CliCommand = {
     readonly command: "help";
-    readonly topic?: "generate" | "init";
+    readonly topic?: "generate" | "init" | "skill";
 } | {
     readonly command: "version";
+} | {
+    readonly command: "skill";
+    readonly force: boolean;
 } | {
     readonly command: "generate";
     readonly yes: boolean;

package/dist/cli/command.parser.js

@@ -18,6 +18,9 @@ Usage:
       --skip-install          Print the install instead of running it.
       --skip-generate         Do not generate now.
       -y, --yes               Accept every default, and replace differing content.
+  avclient skill [--force]    Write or refresh this frontend's agent skill
+                              (.claude/skills/aventara-client/); --force replaces
+                              a file you edited. avclient init writes it too.
   avclient --help             Print this and exit 0.
   avclient <command> --help   Print that command's usage and exit 0.
   avclient --version, -v      Print this generator's version and exit 0.
@@ -37,6 +40,15 @@ current directory, highest precedence first: the process environment,
 .env.<mode>.local, .env.<mode>, .env.local, .env — where mode is NODE_ENV, or
 "development".
 `;
+export const SKILL_USAGE = `Usage: avclient skill [--force]
+
+Write or refresh this frontend's agent skill, .claude/skills/aventara-client/,
+for this @aventara/client: how the generated client calls the API. A file you
+edited is kept, with a warning.
+
+Options:
+  --force   Replace a file you edited.
+`;
 export const GENERATE_USAGE = `Usage: avclient generate [--yes]
 
 Read ${CLIENT_CONFIG_FILE} (or .mts, .cts, .js, .mjs, .cjs) in the current directory,
@@ -90,13 +102,20 @@ export function parseCliCommand(argv) {
     if (command === "--version" || command === "-v") {
         return { command: "version" };
     }
-    if ((command === "init" || command === "generate") &&
+    if ((command === "init" || command === "generate" || command === "skill") &&
         (rest.includes("--help") || rest.includes("-h"))) {
         return { command: "help", topic: command };
     }
     if (command === "init") {
         return parseInit(rest, help);
     }
+    if (command === "skill") {
+        const [extra] = rest.filter((argument) => argument !== "--force");
+        if (extra !== undefined || rest.length > 1) {
+            throw new AvCliCommandError(`unexpected argument ${JSON.stringify(extra ?? "--force")}: skill takes only --force; ${help}`);
+        }
+        return { command: "skill", force: rest.length === 1 };
+    }
     if (command !== "generate") {
         throw new AvCliCommandError(`unknown command ${JSON.stringify(command)}; ${help}`);
     }

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { GENERATE_USAGE, INIT_USAGE, parseCliCommand, USAGE, } from "./cli/command.parser.js";
+import { GENERATE_USAGE, INIT_USAGE, parseCliCommand, SKILL_USAGE, USAGE, } from "./cli/command.parser.js";
 import { runGenerate } from "./cli/generate.command.js";
 import { renderGenerationFailure } from "./cli/generation-failure.renderer.js";
 import { progressModeOf } from "./cli/step.reporter.js";
@@ -6,6 +6,7 @@ import { createTerminalPrompter } from "./cli/terminal.prompter.js";
 import { AVENTARA_CLIENT_GENERATOR_VERSION } from "./index.js";
 import { runClientInit } from "./init/client-init.orchestrator.js";
 import { runCommand } from "./init/command.runner.js";
+import { writeClientSkill } from "./skill/client-skill.writer.js";
 export async function runCli(argv, io) {
     try {
         const command = parseCliCommand(argv);
@@ -14,7 +15,9 @@ export async function runCli(argv, io) {
                 ? USAGE
                 : command.topic === "init"
                     ? INIT_USAGE
-                    : GENERATE_USAGE);
+                    : command.topic === "skill"
+                        ? SKILL_USAGE
+                        : GENERATE_USAGE);
             return 0;
         }
         if (command.command === "version") {
@@ -24,6 +27,18 @@ export async function runCli(argv, io) {
         if (command.command === "init") {
             return await runClientInit(command, io);
         }
+        if (command.command === "skill") {
+            const skill = writeClientSkill({
+                directory: io.cwd,
+                clientVersion: AVENTARA_CLIENT_GENERATOR_VERSION,
+                force: command.force,
+            });
+            for (const warning of skill.warnings) {
+                io.stderr(`avclient: warning: ${warning}.\n`);
+            }
+            io.stdout(`avclient: ${skill.written.length === 0 ? "the client skill is up to date" : `wrote ${skill.written.join(", ")}`}.\n`);
+            return 0;
+        }
         return await runGenerate(io, command.yes);
     }
     catch (error) {

package/dist/config/config.resolver.js

@@ -76,7 +76,7 @@ export function resolveEntrypoint(value) {
     if (url.username !== "" || url.password !== "") {
         throw new AvClientConfigError("entrypoint must not carry credentials: the platform's fetch refuses a URL that " +
             "includes them, and the entrypoint is embedded in the generated client, which ships — " +
-            "authenticate through a custom fetch instead.");
+            "add credentials through onCall instead.");
     }
     if (value.includes("?") || value.includes("#")) {
         throw new AvClientConfigError("entrypoint must not carry a query or fragment; it is the origin plus mount path only.");

package/dist/emit/access.emitter.js

@@ -26,7 +26,7 @@ export function emitAccessModules(contract, style) {
         {
             path: "runtime/access.ts",
             source: `import { AvTransportError } from ${from("./errors")};
-import type { AvCallOptions, PlatformSignal, TransportConnection } from ${from("./transport")};
+import { type AvCallOptions, type PlatformSignal, type TransportConnection, withAdditions } from ${from("./transport")};
 
 /**
  * Aventara Access's verbs, as this deployment's ClientContract states them:
@@ -227,7 +227,7 @@ export async function callAccess(
 	let answer: AccessAnswer;
 	let text: string;
 	try {
-		answer = await fetch(routeOf(connection.entrypoint, path), init);
+		answer = await fetch(routeOf(connection.entrypoint, path), withAdditions(connection.additions, init));
 		text = await answer.text();
 	} catch (error) {
 		if (options.signal?.aborted === true) {

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

@@ -60,18 +60,53 @@ export function emitClientSurfaceModule(contract, names, style) {
             ? "args: unknown, callOptions: AvCallOptions = {}"
             : "callOptions: AvCallOptions = {}";
         const args = shape.args ? "args" : "undefined";
+        const call = `observeCall(options, accessCall(${quoted}, callOptions), callOptions.signal, (additions) =>\n\t\t\t\t\t\tcallAccess({ ...connect(), additions }, ${quoted}, ${args}, callOptions),\n\t\t\t\t\t)`;
         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`;
+            ? `\t\t\t\t${name}: async (${parameters}): Promise<void> => {\n\t\t\t\t\tawait ${call};\n\t\t\t\t},\n`
+            : `\t\t\t\t${name}: async (${parameters}) =>\n\t\t\t\t\t${call},\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" +
+            "\t\t\t\tcan: async (questions: readonly unknown[], callOptions: AvCallOptions = {}) =>\n" +
+            '\t\t\t\t\tobserveCall(options, accessCall("can", callOptions), callOptions.signal, (additions) =>\n' +
+            "\t\t\t\t\t\taskCan({ ...connect(), additions }, questions, callOptions),\n" +
+            "\t\t\t\t\t),\n" +
             verbs.map(accessMember).join("") +
             "\t\t\t}),\n" +
             "\t\t});\n";
+    const callType = "/** One call, as avClient's hooks see it: what it is, never its arguments. */\n" +
+        "export type AvCall =\n" +
+        "\t| {\n" +
+        '\t\t\treadonly kind: "operation";\n' +
+        "\t\t\treadonly resource: Resource;\n" +
+        "\t\t\treadonly family: AvOperationFamily;\n" +
+        "\t\t\treadonly variant: string;\n" +
+        '\t\t\t/** How errors and warnings name it: `"Post" find.many`. */\n' +
+        "\t\t\treadonly label: string;\n" +
+        "\t\t\t/** Its requestId, when it sends one. */\n" +
+        "\t\t\treadonly requestId?: string;\n" +
+        "\t  }" +
+        (interactive
+            ? "\n\t| {\n" +
+                "\t\t\t/** A transaction: one call, whatever its steps. */\n" +
+                '\t\t\treadonly kind: "transaction";\n' +
+                '\t\t\treadonly label: "the transaction";\n' +
+                "\t\t\treadonly requestId?: string;\n" +
+                "\t  }"
+            : "") +
+        (access === undefined
+            ? ""
+            : "\n\t| {\n" +
+                '\t\t\treadonly kind: "access";\n' +
+                `\t\t\treadonly verb: ${["can", ...verbs].map((name) => JSON.stringify(name)).join(" | ")};\n` +
+                "\t\t\t/** `$access.can`, `$access.me`, … */\n" +
+                "\t\t\treadonly label: string;\n" +
+                "\t\t\t/** Its requestId, when it sends one (`can` alone does). */\n" +
+                "\t\t\treadonly requestId?: string;\n" +
+                "\t  }") +
+        ";\n";
     const surface = (name, call) => `type ${name} = {\n` +
         `\treadonly [${resourceKey}]: {\n` +
         "\t\treadonly [F in keyof Grammar[R]]: {\n" +
@@ -107,18 +142,18 @@ export function emitClientSurfaceModule(contract, names, style) {
             (checked
                 ? `import { ${interactive ? "checkOperation, checkPlan" : "checkOperation"} } from ${from("./runtime/field-validators")};\n`
                 : "") +
-            `import { all, CallQueue${interactive ? ", withSignal" : ""} } from ${from("./runtime/operation-set")};\n` +
+            `import { ${access === undefined ? "" : "accessCall, "}all, CallQueue${access === undefined ? "" : ", observeCall"}${interactive ? ", transactionCall, withSignal" : ""} } from ${from("./runtime/operation-set")};\n` +
             (interactive
                 ? `import { deferOperation, runTransaction } from ${from("./runtime/transaction")};\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`) +
+                ? `import type { AvCallAdditions, AvCallOptions, AvFetch, PlatformSignal, TransportConnection } from ${from("./runtime/transport")};\n`
+                : `import { askCan, type AvCallAdditions, 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` +
+            `export type { AvCallAdditions, AvCallOptions } from ${from("./runtime/transport")};\n` +
             "\n" +
             "/**\n" +
             " * The forms this client reads and writes: core's application forms\n" +
@@ -128,19 +163,51 @@ export function emitClientSurfaceModule(contract, names, style) {
             "\treadonly decimal: AvDecimal;\n" +
             "};\n" +
             "\n" +
-            "/** How an `AvClient` reaches its deployment. */\n" +
+            "/** How an `AvClient` reaches its deployment, and what sees its calls. */\n" +
             "export interface AvClientOptions {\n" +
             "\t/** Another deployment serving exactly the same ClientContract; the generated default otherwise. */\n" +
             "\treadonly entrypoint?: string;\n" +
-            "\t/** A custom fetch, for authentication or tests; the platform's otherwise. */\n" +
+            "\t/**\n" +
+            "\t * The fetch every request is sent with, in place of the platform's (a\n" +
+            "\t * test's fake, a runtime's own). It must return the Response unread: the\n" +
+            "\t * client reads the body itself, an Operation Set's as it streams. Headers\n" +
+            "\t * or credentials for every call go in onCall.\n" +
+            "\t */\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" +
+            "\t/**\n" +
+            "\t * Runs once for every call, when it is made: before it is sent and before\n" +
+            "\t * the calls made with it are grouped. It may return, or resolve to,\n" +
+            "\t * additions for that call's request (a token, `credentials`); an async\n" +
+            "\t * onCall is awaited before the calls are grouped. Calls share an Operation\n" +
+            "\t * Set only when their additions are equal. The call's own `headers` option\n" +
+            "\t * wins over a header added here, and avClient's own headers always win.\n" +
+            "\t * A throw is reported as a warning, and the call goes on with no additions.\n" +
+            "\t */\n" +
+            "\treadonly onCall?: (call: AvCall) => AvCallAdditions | void | PromiseLike<AvCallAdditions | void>;\n" +
+            "\t/**\n" +
+            "\t * A sink for a call that resolved, and its result: side effects only (log,\n" +
+            "\t * report). What it returns is ignored, an async one is not awaited (it\n" +
+            "\t * never delays the caller's result), and a throw or a rejection is reported\n" +
+            "\t * as a warning and ignored.\n" +
+            "\t */\n" +
+            "\treadonly onSuccess?: (call: AvCall, result: unknown) => void;\n" +
+            "\t/**\n" +
+            "\t * A sink for a call that rejected (a refusal, a validation error, a\n" +
+            "\t * transport failure, an abort), sent alone or in an Operation Set: side\n" +
+            "\t * effects only (log, report, navigate). The caller still gets the same\n" +
+            "\t * rejection, never delayed: what it returns is ignored, an async one is not\n" +
+            "\t * awaited, and a throw or a rejection is reported as a warning and ignored.\n" +
+            "\t */\n" +
+            "\treadonly onError?: (call: AvCall, error: unknown) => void;\n" +
             "}\n" +
             "\n" +
+            callType +
+            "\n" +
             (shaped === undefined
                 ? ""
                 : "/** The ClientContract, with each shaped Json field's own type. */\n" +
@@ -238,7 +305,7 @@ 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\tconst queue = new CallQueue(connect, options.grouping !== false, options);\n" +
             "\t\tfor (const [resource, families] of operationTree(\n" +
             "\t\t\t(resource, family, variant): OperationMethod =>\n" +
             (checked
@@ -263,11 +330,12 @@ export function emitClientSurfaceModule(contract, names, style) {
                     "\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" +
+                    "\t\t\t\t\t(connection, signal) =>\n" +
                     (checked
-                        ? "\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\t\trunTransaction(connection, plan, withSignal(callOptions, signal), checkPlan),\n"
+                        : "\t\t\t\t\t\trunTransaction(connection, plan, withSignal(callOptions, signal)),\n") +
                     "\t\t\t\t\tcallOptions.signal,\n" +
+                    "\t\t\t\t\ttransactionCall(callOptions),\n" +
                     "\t\t\t\t);\n" +
                     "\t\t\t},\n" +
                     "\t\t});\n"

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

@@ -33,7 +33,7 @@ export function emitClientTree(contract, entrypoint, style, regenerate = AVCLIEN
         emitDecimalModule(),
         emitErrorsModule(regenerate),
         emitTransportModule(style, contract.access !== undefined),
-        emitOperationSetModule(style, contractHasCachedReads(contract)),
+        emitOperationSetModule(style, contractHasCachedReads(contract), contract.access !== undefined),
         ...(contractHasCachedReads(contract) ? emitCachedReadModules(style) : []),
         ...emitAccessModules(contract, style),
         emitNamedTypesModule(contract, names, style),
@@ -71,8 +71,8 @@ function generatedModuleSpecifier(style, module) {
 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 {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype AvCallOptions,\n\ttype AvCall,\n\ttype AvCallAdditions,\n} from ${from("client.ts")};\n`
+        : `export type { AvClient, AvClientOptions, AvCallOptions, AvCall, AvCallAdditions } 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` +

package/dist/emit/name.deriver.js

@@ -6,6 +6,8 @@ export const RESERVED_EMITTED_NAMES = [
         "AvAccessMe",
         "AvClient",
         "AvClientOptions",
+        "AvCall",
+        "AvCallAdditions",
         "AvCallOptions",
         "AvCause",
         "AvDecimal",
@@ -55,7 +57,6 @@ export const CLIENT_MEMBER_NAMES = [
     "__lookupGetter__",
     "__lookupSetter__",
     "__proto__",
-    "all",
     "constructor",
     "hasOwnProperty",
     "isPrototypeOf",

package/dist/emit/operation-set.emitter.d.ts

@@ -1,3 +1,3 @@
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
-export declare function emitOperationSetModule(style: ClientModuleStyle, cached?: boolean): EmittedModule;
+export declare function emitOperationSetModule(style: ClientModuleStyle, cached?: boolean, access?: boolean): EmittedModule;