@mapomodule/core 2.0.0-beta.5 → 2.0.0-beta.6

package/dist/index.d.mts

@@ -2,6 +2,7 @@ export { ApiResponse, AuthToken, CoreCookieEnum, Credentials, CrudConfig, CrudOp
 export { MapoApiLayer, MapoFacade } from '../dist/runtime/composables/useMapo.js';
 export { RoutePermissions, useCanAccessRoute } from '../dist/runtime/auth/useCanAccessRoute.js';
 export { useMapoFetch } from '../dist/runtime/utils/useMapoFetch.js';
+export { getErrorData, getErrorDetail, getErrorStatus } from '../dist/runtime/utils/fetchError.js';
 
 interface MapoOptions {
     authLoginUrl?: string;

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export type * from "./module";
 export { MultipartPolicyEnum, CoreCookieEnum } from "./runtime/types";
 export { useCanAccessRoute } from "./runtime/auth/useCanAccessRoute";
 export { useMapoFetch } from "./runtime/utils/useMapoFetch";
+export { getErrorData, getErrorStatus, getErrorDetail, } from "./runtime/utils/fetchError";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,UAAU,CAAC;AAC9B,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,UAAU,CAAC;AAC9B,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,GACf,MAAM,4BAA4B,CAAC"}

package/dist/index.mjs

@@ -1,3 +1,4 @@
 export { CoreCookieEnum, MultipartPolicyEnum } from '../dist/runtime/types.js';
 export { useCanAccessRoute } from '../dist/runtime/auth/useCanAccessRoute.js';
 export { useMapoFetch } from '../dist/runtime/utils/useMapoFetch.js';
+export { getErrorData, getErrorDetail, getErrorStatus } from '../dist/runtime/utils/fetchError.js';

package/dist/module.d.mts

@@ -4,6 +4,7 @@ export { ApiResponse, AuthToken, CoreCookieEnum, Credentials, CrudConfig, CrudOp
 export { MapoApiLayer, MapoFacade } from '../dist/runtime/composables/useMapo.js';
 export { RoutePermissions } from '../dist/runtime/auth/useCanAccessRoute.js';
 import '../dist/runtime/utils/useMapoFetch.js';
+import '../dist/runtime/utils/fetchError.js';
 
 declare const _default: NuxtModule<MapoOptions, MapoOptions, false>;
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@mapomodule/core",
   "configKey": "mapoCore",
-  "version": "2.0.0-beta.5",
+  "version": "2.0.0-beta.6",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/runtime/__tests__/plugins/00.fetch.real.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=00.fetch.real.spec.d.ts.map

package/dist/runtime/__tests__/plugins/00.fetch.real.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"00.fetch.real.spec.d.ts","sourceRoot":"","sources":["../../../../src/runtime/__tests__/plugins/00.fetch.real.spec.ts"],"names":[],"mappings":""}

package/dist/runtime/__tests__/plugins/01.init.server.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=01.init.server.spec.d.ts.map

package/dist/runtime/__tests__/plugins/01.init.server.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"01.init.server.spec.d.ts","sourceRoot":"","sources":["../../../../src/runtime/__tests__/plugins/01.init.server.spec.ts"],"names":[],"mappings":""}

package/dist/runtime/__tests__/utils/fetchError.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fetchError.spec.d.ts.map

package/dist/runtime/__tests__/utils/fetchError.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchError.spec.d.ts","sourceRoot":"","sources":["../../../../src/runtime/__tests__/utils/fetchError.spec.ts"],"names":[],"mappings":""}

package/dist/runtime/plugins/00.fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"00.fetch.d.ts","sourceRoot":"","sources":["../../../src/runtime/plugins/00.fetch.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;GAWG;;;;;;;;AACH,wBA6DG"}
+{"version":3,"file":"00.fetch.d.ts","sourceRoot":"","sources":["../../../src/runtime/plugins/00.fetch.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;GAWG;;;;;;;;AACH,wBAmEG"}

package/dist/runtime/plugins/00.fetch.js

@@ -2,6 +2,7 @@ import { ref, computed } from "vue";
 import {
   defineNuxtPlugin,
   navigateTo,
+  useRequestHeaders,
   useRoute,
   useRuntimeConfig
 } from "nuxt/app";
@@ -33,19 +34,22 @@ export default defineNuxtPlugin({
     };
     const pending = ref(0);
     const mapoFetchLoading = computed(() => pending.value > 0);
+    const forwardedCookie = import.meta.server ? useRequestHeaders(["cookie"]).cookie : void 0;
     const mapoFetch = $fetch.create({
-      onRequest() {
+      onRequest({ options }) {
         pending.value++;
+        if (forwardedCookie) {
+          const headers = new Headers(
+            options.headers
+          );
+          if (!headers.has("cookie")) headers.set("cookie", forwardedCookie);
+          options.headers = headers;
+        }
       },
       onResponse({ response, request }) {
         pending.value--;
         handle(response.status, String(request));
       },
-      onResponseError({ response, request, error }) {
-        pending.value--;
-        handle(response?.status ?? 0, String(request));
-        return Promise.reject(error);
-      },
       onRequestError() {
         pending.value--;
       }

package/dist/runtime/plugins/01.init.server.d.ts

@@ -7,7 +7,8 @@
  * - If the HttpOnly session cookie is present, calls the configured `userInfoApi`
  *   (forwarding request cookies) to restore the authenticated user in the auth store.
  *
- * On session restore failure, it resets auth state and clears the session cookie.
+ * On session restore failure it resets auth state, and clears the session cookie only
+ * when the backend rejected the session (401/403) — never on a transport error.
  */
 declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/plugins/01.init.server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"01.init.server.d.ts","sourceRoot":"","sources":["../../../src/runtime/plugins/01.init.server.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;GAUG;;AACH,wBAmCG"}
+{"version":3,"file":"01.init.server.d.ts","sourceRoot":"","sources":["../../../src/runtime/plugins/01.init.server.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;GAWG;;AACH,wBAuCG"}

package/dist/runtime/plugins/01.init.server.js

@@ -2,8 +2,7 @@ import {
   defineNuxtPlugin,
   useRuntimeConfig,
   useCookie,
-  useRequestHeaders,
-  useRequestURL
+  useRequestHeaders
 } from "nuxt/app";
 import { setActivePinia } from "pinia";
 import { useAuthStore } from "@mapomodule/store/runtime/stores/auth";
@@ -23,15 +22,14 @@ export default defineNuxtPlugin({
     if (!sessionCookie.value) return;
     try {
       const headers = useRequestHeaders(["cookie"]);
-      const url = useRequestURL();
-      const absolute = `${url.protocol}//${url.host}${userInfoApi}`;
-      const user = await nuxtApp.$mapoFetch(absolute, { method: "GET", headers });
+      const user = await nuxtApp.$mapoFetch(userInfoApi, { method: "GET", headers });
       authStore.setUser(user);
     } catch (e) {
       console.error(`[mapo] Cannot restore session from cookie:
 ${e}`);
       authStore.reset();
-      sessionCookie.value = null;
+      const status = e?.status ?? e?.response?.status;
+      if (status === 401 || status === 403) sessionCookie.value = null;
     }
   }
 });

package/dist/runtime/utils/fetchError.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Helpers to read the backend payload out of a failed `$mapoFetch` call.
+ *
+ * `ofetch` throws a `FetchError` that exposes the parsed response body as
+ * `error.data` (and `error.response._data`) — NOT as `error.response.data`.
+ * Reading the wrong path silently yields `undefined`, which turns every
+ * backend validation message into a generic "something went wrong".
+ * Use these helpers instead of destructuring the error by hand.
+ */
+/**
+ * Parsed response body of a failed request, or `undefined` when the request
+ * failed before a response was received (network error, abort…).
+ *
+ * @example
+ * try { await crud.create(model) }
+ * catch (err) {
+ *   const data = getErrorData<{ title?: string[] }>(err)
+ *   errors.value = data ?? {}
+ * }
+ */
+export declare function getErrorData<T = Record<string, unknown>>(error: unknown): T | undefined;
+/** HTTP status of a failed request, or `0` when no response was received. */
+export declare function getErrorStatus(error: unknown): number;
+/**
+ * `detail` message returned by the backend (DRF convention), when present.
+ * Falls back to `undefined` so callers can substitute a translated default.
+ */
+export declare function getErrorDetail(error: unknown): string | undefined;
+//# sourceMappingURL=fetchError.d.ts.map

package/dist/runtime/utils/fetchError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchError.d.ts","sourceRoot":"","sources":["../../../src/runtime/utils/fetchError.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtD,KAAK,EAAE,OAAO,GACb,CAAC,GAAG,SAAS,CAGf;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGrD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGjE"}

package/dist/runtime/utils/fetchError.js

@@ -0,0 +1,12 @@
+export function getErrorData(error) {
+  const e = error;
+  return e?.data ?? e?.response?._data;
+}
+export function getErrorStatus(error) {
+  const e = error;
+  return e?.status ?? e?.statusCode ?? e?.response?.status ?? 0;
+}
+export function getErrorDetail(error) {
+  const data = getErrorData(error);
+  return typeof data?.detail === "string" ? data.detail : void 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapomodule/core",
-  "version": "2.0.0-beta.5",
+  "version": "2.0.0-beta.6",
   "description": "Mapo core: API layer, auth, composables, middleware",
   "type": "module",
   "license": "MIT",
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@mapomodule/store": "2.0.0-beta.4",
-    "@mapomodule/utils": "2.0.0-beta.2"
+    "@mapomodule/utils": "2.0.0-beta.3"
   },
   "peerDependencies": {
     "nuxt": ">=4.0.0",
@@ -57,10 +57,10 @@
     "@nuxt/kit": "4.4.2",
     "@nuxt/module-builder": "^1.0.2",
     "@nuxt/schema": "4.4.2",
-    "nuxt": "^4.4.2",
+    "nuxt": "^4.5.1",
     "ofetch": "^1.5.1",
     "pinia": "^3.0.4",
-    "vue": "^3.5.32",
-    "vue-router": "^5.0.4"
+    "vue": "^3.5.40",
+    "vue-router": "^5.2.0"
   }
 }

package/src/index.ts

@@ -2,3 +2,8 @@ export type * from "./module";
 export { MultipartPolicyEnum, CoreCookieEnum } from "./runtime/types";
 export { useCanAccessRoute } from "./runtime/auth/useCanAccessRoute";
 export { useMapoFetch } from "./runtime/utils/useMapoFetch";
+export {
+  getErrorData,
+  getErrorStatus,
+  getErrorDetail,
+} from "./runtime/utils/fetchError";

package/src/runtime/__tests__/plugins/00.fetch.real.spec.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Exercises the REAL mapo-core:fetch plugin hooks, not a hand-written copy of them.
+// The hooks are built inside setup() via the global `$fetch.create`, so stub that and
+// capture what the plugin actually passes.
+
+vi.mock("nuxt/app", () => ({
+  defineNuxtPlugin: (p: unknown) => p,
+  navigateTo: vi.fn(),
+  useRoute: () => ({ fullPath: "/articoli" }),
+  useRuntimeConfig: () => ({
+    public: { mapoCore: { logoutUrl: "/logout", loginUrl: "/login" } },
+  }),
+  useRequestHeaders: () => ({ cookie: "__mapo_session=abc; sessionid=abc" }),
+}));
+
+const authStore = { reset: vi.fn() };
+const snackStore = { show: vi.fn() };
+vi.mock("@mapomodule/store/runtime/stores/auth", () => ({
+  useAuthStore: () => authStore,
+}));
+vi.mock("@mapomodule/store/runtime/stores/snack", () => ({
+  useSnackStore: () => snackStore,
+}));
+
+import plugin from "../../plugins/00.fetch";
+
+type Hooks = {
+  onRequest: (ctx: { options: { headers?: HeadersInit } }) => void;
+  onResponse: (ctx: { response: { status: number }; request: string }) => void;
+  onResponseError?: undefined;
+  onRequestError: () => void;
+};
+
+function buildPlugin() {
+  let hooks!: Hooks;
+  const provided: Record<string, unknown> = {};
+  vi.stubGlobal("$fetch", {
+    create: (h: Hooks) => {
+      hooks = h;
+      return vi.fn();
+    },
+  });
+  const res = (
+    plugin as unknown as { setup: () => { provide: Record<string, unknown> } }
+  ).setup();
+  Object.assign(provided, res.provide);
+  return { hooks, provided };
+}
+
+describe("mapo-core:fetch — real plugin hooks", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  // ofetch runs onResponse for EVERY response and THEN onResponseError for >= 400.
+  // Decrementing in both drives the counter negative and wedges $mapoFetchLoading.
+  it("decrements the pending counter exactly once on an HTTP error", () => {
+    const { hooks, provided } = buildPlugin();
+    const loading = provided.mapoFetchLoading as { value: boolean };
+
+    hooks.onRequest({ options: {} } as never);
+    expect(loading.value).toBe(true);
+
+    // real ofetch order for an error response (verified against ofetch 1.5.1):
+    // onRequest -> onResponse(500) -> onResponseError(500)
+    hooks.onResponse({ response: { status: 500 }, request: "/api/x" });
+
+    expect(loading.value).toBe(false);
+
+    // A second request must still register — it would not if the counter went to -1.
+    hooks.onRequest({ options: {} } as never);
+    expect(loading.value).toBe(true);
+  });
+
+  it("does not swallow ofetch's FetchError by returning a rejection", () => {
+    const { hooks } = buildPlugin();
+    const returned = hooks.onResponse({
+      response: { status: 401 },
+      request: "/api/x",
+    });
+    expect(returned).toBeUndefined();
+  });
+
+  it("still resets auth on 401 and snacks on 403", () => {
+    const { hooks } = buildPlugin();
+
+    hooks.onResponse({ response: { status: 401 }, request: "/api/x" });
+    expect(authStore.reset).toHaveBeenCalled();
+
+    hooks.onResponse({ response: { status: 403 }, request: "/api/y" });
+    expect(snackStore.show).toHaveBeenCalledWith("Permission denied", "error");
+  });
+
+  // Was fired twice per 403 while both hooks called handle().
+  it("shows the 403 snackbar exactly once per response", () => {
+    const { hooks } = buildPlugin();
+    hooks.onResponse({ response: { status: 403 }, request: "/api/y" });
+    expect(snackStore.show).toHaveBeenCalledTimes(1);
+  });
+
+  // SSR does not attach browser cookies. Without forwarding, every authenticated data
+  // fetch came back 401 and `handle()` wiped the auth store mid-render — an
+  // intermittent logout on hard refresh, depending on whether the 401 landed before
+  // the payload was serialized.
+  it("forwards the incoming Cookie header on server-side requests", () => {
+    const { hooks } = buildPlugin();
+    const options: { headers?: HeadersInit } = {};
+    hooks.onRequest({ options } as never);
+
+    const headers = options.headers as Headers;
+    expect(headers.get("cookie")).toBe("__mapo_session=abc; sessionid=abc");
+  });
+
+  it("lets an explicit per-call cookie win", () => {
+    const { hooks } = buildPlugin();
+    const options: { headers?: HeadersInit } = {
+      headers: { cookie: "sessionid=explicit" },
+    };
+    hooks.onRequest({ options } as never);
+
+    expect((options.headers as Headers).get("cookie")).toBe(
+      "sessionid=explicit",
+    );
+  });
+});

package/src/runtime/__tests__/plugins/00.fetch.spec.ts

@@ -73,7 +73,9 @@ describe("Mapo Fetch Plugin — Pending Counter", () => {
     mapoFetch.onRequest();
     expect(pending.value).toBe(1);
 
-    // Simulate HTTP error (500): onResponseError is called instead of onResponse
+    // Simulate HTTP error (500). NOTE: ofetch calls onResponse for EVERY response
+    // (ofetch createFetch: onResponse, then onResponseError for status >= 400), so the
+    // real plugin must decrement in onResponse only. See the `real plugin` suite below.
     mapoFetch.onResponseError({
       response: { status: 500 },
       request: "/api/users",

package/src/runtime/__tests__/plugins/01.init.server.spec.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// --- nuxt/app is a virtual runtime module; stub the handful of helpers used. ---
+const cookieRef = { value: "a-session-value" as string | null };
+const runtimeConfig = { public: { mapoCore: {} as Record<string, unknown> } };
+
+vi.mock("nuxt/app", () => ({
+  defineNuxtPlugin: (p: unknown) => p,
+  useRuntimeConfig: () => runtimeConfig,
+  useCookie: () => cookieRef,
+  useRequestHeaders: () => ({ cookie: "__mapo_session=a-session-value" }),
+}));
+
+vi.mock("pinia", () => ({ setActivePinia: vi.fn() }));
+
+const authStore = { setUser: vi.fn(), reset: vi.fn() };
+vi.mock("@mapomodule/store/runtime/stores/auth", () => ({
+  useAuthStore: () => authStore,
+}));
+vi.mock("@mapomodule/store/runtime/stores/sidebar", () => ({
+  useSidebarStore: () => ({ hydrateFromCookies: vi.fn() }),
+}));
+
+// Imported after the mocks (vitest hoists them).
+import plugin from "../../plugins/01.init.server";
+
+function run($mapoFetch: unknown) {
+  return (
+    plugin as unknown as {
+      setup: (app: Record<string, unknown>) => Promise<void>;
+    }
+  ).setup({ $pinia: {}, $mapoFetch });
+}
+
+describe("mapo-core:init (SSR session restore)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    cookieRef.value = "a-session-value";
+    runtimeConfig.public.mapoCore = {};
+  });
+
+  // The bug this guards: building `${protocol}//${host}${userInfoApi}` dropped
+  // `app.baseURL` (404 under /backoffice/) and aimed at the browser-facing host,
+  // which the SSR container cannot resolve — so every hard refresh logged the user out.
+  it("fetches the user with a RELATIVE url so app.baseURL applies", async () => {
+    const fetchMock = vi.fn(() => Promise.resolve({ username: "root" }));
+    await run(fetchMock);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url] = fetchMock.mock.calls[0] as unknown as [string];
+    expect(url).toBe("/api/profiles/me/");
+    expect(url).not.toMatch(/^https?:\/\//);
+    expect(authStore.setUser).toHaveBeenCalledWith({ username: "root" });
+  });
+
+  it("honours a configured userInfoApi, still relative", async () => {
+    runtimeConfig.public.mapoCore = { userInfoApi: "/api/whoami/" };
+    const fetchMock = vi.fn(() => Promise.resolve({ username: "root" }));
+    await run(fetchMock);
+
+    const [url] = fetchMock.mock.calls[0] as unknown as [string];
+    expect(url).toBe("/api/whoami/");
+  });
+
+  it("clears the session cookie when the backend rejects it (401)", async () => {
+    const fetchMock = vi.fn(() =>
+      Promise.reject(Object.assign(new Error("Unauthorized"), { status: 401 })),
+    );
+    await run(fetchMock);
+
+    expect(authStore.reset).toHaveBeenCalled();
+    expect(cookieRef.value).toBeNull();
+  });
+
+  // A transport failure must not log the user out: the cookie is HttpOnly, so
+  // clearing it here is irreversible for the client.
+  it("keeps the session cookie when the backend is unreachable", async () => {
+    const fetchMock = vi.fn(() =>
+      Promise.reject(Object.assign(new Error("Bad Gateway"), { status: 502 })),
+    );
+    await run(fetchMock);
+
+    expect(authStore.reset).toHaveBeenCalled();
+    expect(cookieRef.value).toBe("a-session-value");
+  });
+
+  it("does nothing when there is no session cookie", async () => {
+    cookieRef.value = null;
+    const fetchMock = vi.fn();
+    await run(fetchMock);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

package/src/runtime/__tests__/utils/fetchError.spec.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { ofetch } from "ofetch";
+import {
+  getErrorData,
+  getErrorDetail,
+  getErrorStatus,
+} from "../../utils/fetchError";
+
+/** Minimal stand-in for the response the backend would return. */
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("fetchError helpers", () => {
+  it("reads the parsed body from FetchError.data", () => {
+    const err = {
+      status: 400,
+      data: { detail: "Invalid", title: ["required"] },
+    };
+    expect(getErrorData(err)).toEqual({
+      detail: "Invalid",
+      title: ["required"],
+    });
+    expect(getErrorDetail(err)).toBe("Invalid");
+    expect(getErrorStatus(err)).toBe(400);
+  });
+
+  it("falls back to response._data, which is where ofetch parks the body", () => {
+    const err = { response: { status: 404, _data: { detail: "Not found" } } };
+    expect(getErrorDetail(err)).toBe("Not found");
+    expect(getErrorStatus(err)).toBe(404);
+  });
+
+  it("returns undefined instead of throwing for network errors", () => {
+    expect(getErrorData(new Error("network down"))).toBeUndefined();
+    expect(getErrorDetail(undefined)).toBeUndefined();
+    expect(getErrorStatus(null)).toBe(0);
+  });
+
+  it("ignores a non-string detail so callers can use their own fallback", () => {
+    expect(
+      getErrorDetail({ data: { detail: { nested: true } } }),
+    ).toBeUndefined();
+  });
+});
+
+describe("onResponseError hook contract", () => {
+  // Regression guard: the plugin used to `return Promise.reject(context.error)`.
+  // On an HTTP error status ofetch leaves `context.error` undefined, so that
+  // rejection replaced the FetchError with `undefined` and every caller lost
+  // both the status and the backend body.
+  it("keeps the FetchError intact when the hook only observes", async () => {
+    vi.stubGlobal("fetch", async () =>
+      jsonResponse(400, { detail: "Some nodes are invalid." }),
+    );
+
+    let seenError: unknown = "not-called";
+    const api = ofetch.create({
+      onResponseError(ctx) {
+        seenError = ctx.error;
+      },
+    });
+
+    const err = await api("/api/menus/1", { method: "PUT" }).catch((e) => e);
+
+    // ofetch does not populate context.error for HTTP error statuses…
+    expect(seenError).toBeUndefined();
+    // …but the caller still receives a fully-formed FetchError.
+    expect(err).toBeDefined();
+    expect(getErrorStatus(err)).toBe(400);
+    expect(getErrorDetail(err)).toBe("Some nodes are invalid.");
+  });
+
+  it("loses the error payload when the hook rejects with context.error", async () => {
+    vi.stubGlobal("fetch", async () =>
+      jsonResponse(400, { detail: "Some nodes are invalid." }),
+    );
+
+    const api = ofetch.create({
+      onResponseError(ctx) {
+        return Promise.reject(ctx.error);
+      },
+    });
+
+    const err = await api("/api/menus/1", { method: "PUT" }).catch((e) => e);
+
+    expect(err).toBeUndefined();
+    expect(getErrorDetail(err)).toBeUndefined();
+  });
+});

package/src/runtime/plugins/00.fetch.ts

@@ -2,6 +2,7 @@ import { ref, computed } from "vue";
 import {
   defineNuxtPlugin,
   navigateTo,
+  useRequestHeaders,
   useRoute,
   useRuntimeConfig,
 } from "nuxt/app";
@@ -59,19 +60,25 @@ export default defineNuxtPlugin({
     const pending = ref(0);
     const mapoFetchLoading = computed(() => pending.value > 0);
 
+    const forwardedCookie = import.meta.server
+      ? useRequestHeaders(["cookie"]).cookie
+      : undefined;
+
     const mapoFetch = $fetch.create({
-      onRequest() {
+      onRequest({ options }) {
         pending.value++;
+        if (forwardedCookie) {
+          const headers = new Headers(
+            options.headers as HeadersInit | undefined,
+          );
+          if (!headers.has("cookie")) headers.set("cookie", forwardedCookie);
+          options.headers = headers;
+        }
       },
       onResponse({ response, request }) {
         pending.value--;
         handle(response.status, String(request));
       },
-      onResponseError({ response, request, error }) {
-        pending.value--;
-        handle(response?.status ?? 0, String(request));
-        return Promise.reject(error);
-      },
       onRequestError() {
         // Decrement counter on network errors (no response received).
         pending.value--;

package/src/runtime/plugins/01.init.server.ts

@@ -3,7 +3,6 @@ import {
   useRuntimeConfig,
   useCookie,
   useRequestHeaders,
-  useRequestURL,
 } from "nuxt/app";
 import { setActivePinia } from "pinia";
 import type { Pinia } from "pinia";
@@ -22,7 +21,8 @@ import type { MapoCoreRuntimeConfig } from "../types";
  * - If the HttpOnly session cookie is present, calls the configured `userInfoApi`
  *   (forwarding request cookies) to restore the authenticated user in the auth store.
  *
- * On session restore failure, it resets auth state and clears the session cookie.
+ * On session restore failure it resets auth state, and clears the session cookie only
+ * when the backend rejected the session (401/403) — never on a transport error.
  */
 export default defineNuxtPlugin({
   name: "mapo-core:init",
@@ -47,16 +47,20 @@ export default defineNuxtPlugin({
 
     try {
       const headers = useRequestHeaders(["cookie"]);
-      const url = useRequestURL();
-      const absolute = `${url.protocol}//${url.host}${userInfoApi}`;
       const user = await (
         nuxtApp.$mapoFetch as (url: string, opts: object) => Promise<unknown>
-      )(absolute, { method: "GET", headers });
+      )(userInfoApi, { method: "GET", headers });
       authStore.setUser(user as MapoUser);
     } catch (e) {
       console.error(`[mapo] Cannot restore session from cookie:\n${e}`);
       authStore.reset();
-      sessionCookie.value = null;
+      // Only drop the cookie when the backend actually rejected the session.
+      // A network blip or a 5xx must not log the user out: the cookie is HttpOnly,
+      // so clearing it here is irreversible for the client.
+      const status =
+        (e as { status?: number; response?: { status?: number } })?.status ??
+        (e as { response?: { status?: number } })?.response?.status;
+      if (status === 401 || status === 403) sessionCookie.value = null;
     }
   },
 });

package/src/runtime/utils/fetchError.ts

@@ -0,0 +1,50 @@
+/**
+ * Helpers to read the backend payload out of a failed `$mapoFetch` call.
+ *
+ * `ofetch` throws a `FetchError` that exposes the parsed response body as
+ * `error.data` (and `error.response._data`) — NOT as `error.response.data`.
+ * Reading the wrong path silently yields `undefined`, which turns every
+ * backend validation message into a generic "something went wrong".
+ * Use these helpers instead of destructuring the error by hand.
+ */
+
+/** Minimal structural view of an ofetch `FetchError`. */
+interface FetchErrorLike {
+  status?: number;
+  statusCode?: number;
+  data?: unknown;
+  response?: { status?: number; _data?: unknown };
+}
+
+/**
+ * Parsed response body of a failed request, or `undefined` when the request
+ * failed before a response was received (network error, abort…).
+ *
+ * @example
+ * try { await crud.create(model) }
+ * catch (err) {
+ *   const data = getErrorData<{ title?: string[] }>(err)
+ *   errors.value = data ?? {}
+ * }
+ */
+export function getErrorData<T = Record<string, unknown>>(
+  error: unknown,
+): T | undefined {
+  const e = error as FetchErrorLike | null | undefined;
+  return (e?.data ?? e?.response?._data) as T | undefined;
+}
+
+/** HTTP status of a failed request, or `0` when no response was received. */
+export function getErrorStatus(error: unknown): number {
+  const e = error as FetchErrorLike | null | undefined;
+  return e?.status ?? e?.statusCode ?? e?.response?.status ?? 0;
+}
+
+/**
+ * `detail` message returned by the backend (DRF convention), when present.
+ * Falls back to `undefined` so callers can substitute a translated default.
+ */
+export function getErrorDetail(error: unknown): string | undefined {
+  const data = getErrorData<{ detail?: unknown }>(error);
+  return typeof data?.detail === "string" ? data.detail : undefined;
+}