@aventara/next 1.0.0-rc.12 → 1.0.0-rc.14

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @aventara/next
 
+## 1.0.0-rc.14
+
+### Patch Changes
+
+- 0895a93: `avDehydrate` and `avHydrate` are typed: data handed from a Server Component to a Client Component as props keeps its type, with no cast.
+
+  - `avDehydrate(data)` (`@aventara/next`) returns an `AvDehydrated<T>` for data of type `T`, and `avHydrate(value)` (`@/aventara/client`) of an `AvDehydrated<T>` returns the `T`, its `Date`, `bigint`, `Uint8Array` and `AvDecimal` values included. Type an SWR `fallback` prop `AvDehydrated<T>` and pass `avHydrate(fallback)` to `SWRConfig` as it is.
+  - `AvDehydrated<T>` is new, exported by `@aventara/next` and by the `src/aventara/client.ts` that `aventara-build --client` writes; the two are one type. It is opaque: a plain object, the data itself, or the dehydrated form of another type is a compile error where an `AvDehydrated<T>` is expected.
+  - A Resource or enum named `AvDehydrated` or `avHydrate` is now emitted under a renamed identifier (`AvDehydratedModel`, `avHydrateModel`), with a warning, as other names the generated client owns are. Before, `src/aventara/client.ts`'s own declaration hid a Resource type of that name, which could not be imported from it.
+  - Read data you dehydrate through `@/aventara/universal`: `@/aventara/server` types a decimal as core's `AvDecimal`, while `avHydrate` revives it as the browser client's.
+  - Pass `avHydrate(fallback)` to `SWRConfig`, never the dehydrated value itself: SWR's `fallback` is typed `any`, so the compiler cannot catch it.
+  - `avHydrate` still takes `unknown` and returns `unknown`; `avDehydrate` of an `unknown` value returns an `AvDehydrated<unknown>`. `serializeData: avDehydrate` and `deserializeData: avHydrate` in TanStack Query are written as before.
+  - The agent skills show the SWR props pattern typed, with no cast. The frontend skill's refresh line no longer names `npx`, and says a file you edited is kept with a warning naming it, and replaced with `--force`.
+
+- Updated dependencies [1c5eaa3]
+  - @aventara/core@1.0.0-rc.14
+  - @aventara/mcp@1.0.0-rc.14
+
+## 1.0.0-rc.13
+
+### Patch Changes
+
+- e4e8abd: The same rule now holds for in-process calls. When `state` rejects with an object whose `status` or `statusCode` is
+  the number 401 or 403, an `avClient` call in a Next.js Server Component or Server Action rejects with an `AvAuthError`
+  of code `A4000` or `A4001`, and so does `framework.serverClient.$access.can` given `headers`. Its message is core's own
+  (`"Unauthenticated."` or `"Forbidden."`) and nothing of the rejection reaches the caller. Before, the call rejected
+  with the library's own error. A thrown `AvError` and any other rejection still reject the call unchanged.
+
+  An object whose `status` and `statusCode` are both numbers that disagree, such as `status: 500` beside
+  `statusCode: 401`, is no longer read as a refusal: a route answers it `500 A3000`. A number beside a non-number, such
+  as Better Auth's `status: "UNAUTHORIZED"` beside `statusCode: 401`, is still read by the number.
+
+- e662048: A request whose `state` (the host's `state` option, or the `access` provider's `state`) rejects with an object whose
+  `status` or `statusCode` is the number 401 or 403 is now answered `401 A4000` or `403 A4001`, not `500 A3000`. This is
+  how authentication libraries refuse a bad credential: Better Auth's `APIError` for a wrong API key carries
+  `statusCode: 401`. The answer is core's own envelope (`"Unauthenticated."` or `"Forbidden."`); nothing of the
+  rejection, neither its message nor its code, reaches the caller, and it is not reported to `diagnostics`, as a thrown
+  `AvError("A4000", …)` is not. It applies on every protocol route that seeds state: operations, cached reads,
+  `/_transactions`, `/_all`, `/_access/can`, and MCP tool calls. A thrown `AvError` is still its own outcome, and any
+  other rejection, a 401 beside a 403 included, is still `500 A3000`.
+- 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
+  - @aventara/mcp@1.0.0-rc.13
+
 ## 1.0.0-rc.12
 
 ### Patch Changes

package/README.md

@@ -282,11 +282,29 @@ export const Providers = ({ children }: { children: React.ReactNode }) => (
 ```
 
 With SWR, pass `avDehydrate({ [key]: data })` from the Server Component and `avHydrate(fallback)` to `SWRConfig`'s
-`fallback` in the Client Component.
+`fallback` in the Client Component. Type that prop `AvDehydrated<T>` (from `@/aventara/client`; this package exports the
+same type): `avDehydrate` of a `T` is an `AvDehydrated<T>` and `avHydrate` of one is the `T` again, so no cast is
+written, and a plain object or data of another type is a compile error on the prop. Pass `avHydrate(fallback)` to
+`SWRConfig`, never `fallback` itself: SWR's `fallback` is typed `any`, so the compiler cannot catch it. `avHydrate` also
+takes `unknown` and answers `unknown` (TanStack Query's `deserializeData`); `avDehydrate` of an `unknown` value is an
+`AvDehydrated<unknown>`, and it is TanStack Query's `serializeData` as it is. Read the data you dehydrate through
+`@/aventara/universal`: `@/aventara/server`'s `avClient` types a decimal as core's `AvDecimal`, while `avHydrate` revives
+it as the browser client's.
 
 Importing `@/aventara/client` instead of `@/aventara/universal` in shared code opts out of running on the server: its
 calls are refused there.
 
+### The client's hooks
+
+`onCall`, `onSuccess` and `onError` for `@/aventara/client` and `@/aventara/universal` go in
+`src/aventara/client-options.ts` (or `.js`), whose default export `aventara-build --client` gives every client it writes
+(`@aventara/build`'s README). The file ships to the browser too: no server-only import, no secret, and
+`typeof window` when a hook must act differently on the server. On the server, `onCall`'s headers reach the in-process
+request but not its state, which comes from the request being served. `@/aventara/server` is the Framework's own
+client, not an `AvClient`, and takes no hooks. Calls group in the browser only when their `onCall` settles together
+with equal additions: an `onCall` reading a token over I/O for each call sends each call alone, so read it through
+one shared in-flight promise, cleared once it settles (`@aventara/client`'s README has the recipe).
+
 ## Routes
 
 `handlers` answers the protocol's routes under `api`: each operation route (`POST /api/_resources/...`),

package/dist/aventara.factory.d.ts

@@ -12,10 +12,15 @@ type HostOptions<M extends AvAdapterModel> = {
     readonly adapter: AvAdapter<M> | (() => AvAdapter<M> | PromiseLike<AvAdapter<M>>);
     /**
      * Seeds a request's `ctx.$state`, once per request, from its headers and,
-     * on a route call, the route handler's request. A throw is answered like
-     * any developer failure: a thrown `AvError` as its own outcome, anything
-     * else as an internal failure. Omitted, the state is `{}`, or what the
-     * `access` provider's `state` seeds; not together with `access`.
+     * on a route call, the route handler's request. A thrown `AvError` is its
+     * own outcome. A rejection carrying `status` or `statusCode` 401 or 403
+     * (two numbers that disagree are neither) is `A4000` or `A4001`, with
+     * core's own message and nothing of the rejection's, unreported: a route
+     * answers `401` or `403`, and an `avClient` call in a Server Component or
+     * Server Action rejects with that code's `AvAuthError`. Anything else is
+     * `500 A3000` on a route, and rejects an `avClient` call unchanged.
+     * Omitted, the state is `{}`, or what the `access` provider's `state`
+     * seeds; not together with `access`.
      */
     state?(context: AvNextStateContext): AvState | Promise<AvState>;
 };

package/dist/hydration-tag.format.d.ts

@@ -8,4 +8,9 @@ export declare const HYDRATION_FORMAT: {
     readonly objectTag: "object";
     /** The scalars a value is tagged as: those whose runtime values JSON does not carry. */
     readonly scalarTags: readonly ["bigint", "bytes", "datetime", "decimal"];
+    /**
+     * The key of `AvDehydrated<T>`'s brand: a property of its type only, never
+     * of the value, holding the `T` the value was dehydrated from.
+     */
+    readonly typeKey: "~avDehydrated";
 };

package/dist/hydration-tag.format.js

@@ -3,4 +3,5 @@ export const HYDRATION_FORMAT = {
     valueKey: "v",
     objectTag: "object",
     scalarTags: ["bigint", "bytes", "datetime", "decimal"],
+    typeKey: "~avDehydrated",
 };

package/dist/index.d.ts

@@ -2,4 +2,4 @@ import "server-only";
 export { Aventara } from "./aventara.factory.js";
 export type { AvNextHandlers, AvNextStateContext, } from "./route-handlers.factory.js";
 export type { AvNextAppTransaction, AvNextClientTransaction, } from "./server-operations.factory.js";
-export { avDehydrate } from "./value.dehydrator.js";
+export { type AvDehydrated, avDehydrate } from "./value.dehydrator.js";

package/dist/request-state.cache.js

@@ -1,4 +1,4 @@
-import { holdRequestPrincipal } from "@aventara/core/internal";
+import { holdRequestPrincipal, inProcessStateRejection, } from "@aventara/core/internal";
 import { headers } from "next/headers.js";
 import { cache } from "react";
 export function createRequestState(state) {
@@ -6,7 +6,14 @@ export function createRequestState(state) {
         return async () => undefined;
     }
     return cache(async () => {
-        const seeded = await state({ headers: await headers() });
+        const given = await headers();
+        let seeded;
+        try {
+            seeded = await state({ headers: given });
+        }
+        catch (error) {
+            throw inProcessStateRejection(error);
+        }
         holdRequestPrincipal(seeded);
         return seeded;
     });

package/dist/value.dehydrator.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Data of type `T` as `avDehydrate` sends it from the server: opaque, read
+ * back as the `T` only by `avHydrate` from `@/aventara/client`. Type a Client
+ * Component's prop with it to hand it server data with no cast.
+ *
+ * Pass `avHydrate(fallback)` on, never the dehydrated value itself: a
+ * receiver typed `any`, such as SWR's `fallback`, takes either, so the type
+ * cannot catch it.
+ *
+ * @example
+ * export function Drafts({ fallback }: { readonly fallback: AvDehydrated<{ drafts: Post[] }> }) {
+ *   return <SWRConfig value={{ fallback: avHydrate(fallback) }}>…</SWRConfig>;
+ * }
+ */
+export type AvDehydrated<T> = {
+    /** The type the value was dehydrated from: the type's brand, no member of the value. */
+    readonly "~avDehydrated": T;
+};
 /**
  * Makes data an Aventara client answered safe to pass from the server to the
  * browser: each `Date`, `bigint`, `Uint8Array` and decimal becomes a tagged
@@ -6,9 +24,15 @@
  * plain objects are copied with their members dehydrated; any other value is
  * returned as it is.
  *
- * Give it to TanStack Query as `dehydrate(queryClient, { serializeData: avDehydrate })`,
- * or call it on an SWR `fallback` in a Server Component.
+ * Data of type `T` dehydrates to an `AvDehydrated<T>`, which `avHydrate`
+ * reads back as the `T`: pass it to a Client Component as a prop typed
+ * `AvDehydrated<T>`, such as an SWR `fallback`, and pass `avHydrate(fallback)`
+ * on in the browser, never the dehydrated value itself (SWR's `fallback` is
+ * typed `any`, so the type cannot catch it). Give it to TanStack Query as
+ * `dehydrate(queryClient, { serializeData: avDehydrate })`.
  *
  * @throws TypeError for a `Date` with no wire form (invalid, or a year past four digits).
  */
+export declare function avDehydrate<T>(data: T): AvDehydrated<T>;
+/** As a function typed `(data: unknown) => unknown`, such as TanStack Query's `serializeData`; a call resolves to the generic signature. */
 export declare function avDehydrate(data: unknown): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/next",
-  "version": "1.0.0-rc.12",
+  "version": "1.0.0-rc.14",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Next.js App Router host integration for Aventara.",
   "type": "module",
@@ -22,11 +22,11 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/core": "1.0.0-rc.12",
+    "@aventara/core": "1.0.0-rc.14",
     "server-only": "0.0.1"
   },
   "peerDependencies": {
-    "@aventara/mcp": "1.0.0-rc.12",
+    "@aventara/mcp": "1.0.0-rc.14",
     "next": ">=16.4 <17",
     "react": "^19.0.0"
   },
@@ -53,10 +53,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/build": "1.0.0-rc.12",
-    "@aventara/client": "1.0.0-rc.12",
-    "@aventara/mcp": "1.0.0-rc.12",
-    "@aventara/testing": "1.0.0-rc.12",
+    "@aventara/build": "1.0.0-rc.14",
+    "@aventara/client": "1.0.0-rc.14",
+    "@aventara/mcp": "1.0.0-rc.14",
+    "@aventara/testing": "1.0.0-rc.14",
     "@modelcontextprotocol/sdk": "1.32.2",
     "@tanstack/react-query": "5.104.2",
     "@types/react": "19.3.0",