@mapomodule/core 1.0.0 → 2.0.0-beta.10

package/src/module.ts

@@ -0,0 +1,114 @@
+import { readFileSync } from "node:fs";
+import {
+  defineNuxtModule,
+  addImports,
+  addPlugin,
+  addRouteMiddleware,
+  addTypeTemplate,
+  hasNuxtModule,
+  installModule,
+  createResolver,
+} from "@nuxt/kit";
+import type { NuxtModule } from "@nuxt/schema";
+import { MAPO_DEFAULTS } from "./types";
+import type { MapoOptions } from "./types";
+
+export type { MapoOptions } from "./types";
+export type {
+  ListParams,
+  PaginatedResponse,
+  ApiResponse,
+  CrudConfig,
+  CrudOptions,
+  CrudRepository,
+  MultipartPolicy,
+  Credentials,
+  AuthToken,
+} from "./runtime/types";
+export { MultipartPolicyEnum, CoreCookieEnum } from "./runtime/types";
+export type { MapoFacade, MapoApiLayer } from "./runtime/composables/useMapo";
+export type { RoutePermissions } from "./runtime/auth/useCanAccessRoute";
+
+export default defineNuxtModule<MapoOptions>({
+  meta: {
+    name: "@mapomodule/core",
+    configKey: "mapoCore",
+  },
+
+  defaults: MAPO_DEFAULTS,
+
+  async setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+
+    // In consuming apps this runtime lives inside node_modules, where Nuxt
+    // skips auto-import injection by default (workspace apps are unaffected:
+    // pnpm symlinks resolve outside node_modules). Opt back in and transpile
+    // the runtime for the SSR build.
+    nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
+    nuxt.options.imports.transform ??= {};
+    (nuxt.options.imports.transform.include ??= []).push(
+      /@mapomodule[\\/]core[\\/]/,
+    );
+
+    addTypeTemplate({
+      filename: "types/mapo-core-page-meta.d.ts",
+      getContents: () =>
+        readFileSync(
+          resolver.resolve("./runtime/page-meta.nuxt.d.ts"),
+          "utf-8",
+        ),
+    });
+
+    if (!hasNuxtModule("@mapomodule/store")) {
+      // Resolve from core's own node_modules: with pnpm's isolated layout the
+      // consuming app cannot resolve the bare "@mapomodule/store" specifier.
+      await installModule(await resolver.resolvePath("@mapomodule/store"));
+    }
+
+    // `defaults` guarantees these are set at runtime, but MapoOptions keeps
+    // them optional — spread the defaults so the assignment is fully defined.
+    nuxt.options.runtimeConfig.public.mapoCore = {
+      ...MAPO_DEFAULTS,
+      ...options,
+    };
+
+    addPlugin({ src: resolver.resolve("./runtime/plugins/00.fetch") });
+    addPlugin({
+      src: resolver.resolve("./runtime/plugins/01.init.server"),
+      mode: "server",
+    });
+
+    addImports([
+      { name: "useCrud", from: resolver.resolve("./runtime/api/crud") },
+      {
+        name: "useMapoAuth",
+        from: resolver.resolve("./runtime/auth/useMapoAuth"),
+      },
+      {
+        name: "useMapo",
+        from: resolver.resolve("./runtime/composables/useMapo"),
+      },
+      {
+        name: "useCanAccessRoute",
+        from: resolver.resolve("./runtime/auth/useCanAccessRoute"),
+      },
+      {
+        name: "useMapoFetch",
+        from: resolver.resolve("./runtime/utils/useMapoFetch"),
+      },
+    ]);
+
+    addRouteMiddleware({
+      name: "auth",
+      path: resolver.resolve("./runtime/middleware/auth"),
+    });
+    addRouteMiddleware({
+      name: "permissions",
+      path: resolver.resolve("./runtime/middleware/permissions"),
+    });
+    addRouteMiddleware({
+      name: "roles",
+      path: resolver.resolve("./runtime/middleware/roles"),
+    });
+  },
+}) satisfies NuxtModule<MapoOptions>;

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

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { ref } from "vue";
+
+// Mock setupPlugin function behavior for testing
+function setupFetchPlugin() {
+  let redirectInFlight = false;
+  const pending = ref(0);
+
+  const handle = (status: number, requestUrl: string, logoutUrl: string) => {
+    if (
+      status === 401 &&
+      !requestUrl.includes(logoutUrl) &&
+      !redirectInFlight
+    ) {
+      redirectInFlight = true;
+      // In real plugin, would redirect; here we just track the intent
+    }
+  };
+
+  const mapoFetch = {
+    onRequest: () => {
+      pending.value++;
+    },
+    onResponse: (ctx: { response: { status: number }; request: string }) => {
+      pending.value--;
+      handle(ctx.response.status, ctx.request, "/logout");
+    },
+    onResponseError: (ctx: {
+      response?: { status: number };
+      request: string;
+    }) => {
+      pending.value--;
+      handle(ctx.response?.status ?? 0, ctx.request, "/logout");
+    },
+    onRequestError: () => {
+      pending.value--;
+    },
+  };
+
+  return { pending, mapoFetch };
+}
+
+describe("Mapo Fetch Plugin — Pending Counter", () => {
+  let fixture: ReturnType<typeof setupFetchPlugin>;
+
+  beforeEach(() => {
+    fixture = setupFetchPlugin();
+  });
+
+  it("should increment pending on request and decrement on successful response", () => {
+    const { pending, mapoFetch } = fixture;
+
+    expect(pending.value).toBe(0);
+
+    // Simulate request
+    mapoFetch.onRequest();
+    expect(pending.value).toBe(1);
+
+    // Simulate successful response (200)
+    mapoFetch.onResponse({
+      response: { status: 200 },
+      request: "/api/users",
+    });
+    expect(pending.value).toBe(0);
+  });
+
+  it("should decrement pending exactly once on HTTP error (not double-decrement)", () => {
+    const { pending, mapoFetch } = fixture;
+
+    expect(pending.value).toBe(0);
+
+    // Simulate request
+    mapoFetch.onRequest();
+    expect(pending.value).toBe(1);
+
+    // 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",
+    });
+    expect(pending.value).toBe(0);
+    // Should NOT be -1 (which would indicate double-decrement)
+  });
+
+  it("should decrement pending on network error (onRequestError)", () => {
+    const { pending, mapoFetch } = fixture;
+
+    expect(pending.value).toBe(0);
+
+    // Simulate request
+    mapoFetch.onRequest();
+    expect(pending.value).toBe(1);
+
+    // Simulate network error: onRequestError is called
+    mapoFetch.onRequestError();
+    expect(pending.value).toBe(0);
+  });
+
+  it("should handle multiple concurrent requests correctly", () => {
+    const { pending, mapoFetch } = fixture;
+
+    // Three concurrent requests
+    mapoFetch.onRequest(); // Request 1
+    mapoFetch.onRequest(); // Request 2
+    mapoFetch.onRequest(); // Request 3
+    expect(pending.value).toBe(3);
+
+    // First completes successfully
+    mapoFetch.onResponse({
+      response: { status: 200 },
+      request: "/api/users",
+    });
+    expect(pending.value).toBe(2);
+
+    // Second fails with HTTP error
+    mapoFetch.onResponseError({
+      response: { status: 500 },
+      request: "/api/posts",
+    });
+    expect(pending.value).toBe(1);
+
+    // Third fails with network error
+    mapoFetch.onRequestError();
+    expect(pending.value).toBe(0);
+  });
+
+  it("should never go negative", () => {
+    const { pending, mapoFetch } = fixture;
+
+    // Ensure pending never goes negative even with edge cases
+    mapoFetch.onRequest();
+    expect(pending.value).toBe(1);
+
+    // Simulate response
+    mapoFetch.onResponse({
+      response: { status: 200 },
+      request: "/api/users",
+    });
+    expect(pending.value).toBe(0);
+
+    // Should not go negative
+    expect(pending.value).toBeGreaterThanOrEqual(0);
+  });
+});

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();
+  });
+});