@mapomodule/core 1.0.0-alpha.9 → 2.0.0-beta.1

package/README.md

@@ -0,0 +1,46 @@
+# @mapomodule/core
+
+The service layer of Mapo. Provides the typed CRUD factory, auth composable, route middleware, the `$mapoFetch` interceptor, and the boot plugins that wire everything together.
+
+## Installation
+
+In a Nuxt 4 app — typically you don't install this directly; install the meta-package [`mapomodule`](../../mapomodule/) which registers `core` together with `@mapomodule/store`. If you really want it standalone:
+
+```bash
+pnpm add @mapomodule/core
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@mapomodule/core"],
+  mapoCore: {
+    authLoginUrl: "/api/auth/login",
+    userInfoApi: "/api/profiles/me/",
+    logoutUrl: "/api/auth/logout",
+    loginUrl: "/login",
+  },
+});
+```
+
+When installed via `mapomodule`, configure under the `mapo` key instead.
+
+## What you get (auto-imported)
+
+| API               | Purpose                                                                     |
+| ----------------- | --------------------------------------------------------------------------- |
+| `useCrud<T>(url)` | Typed CRUD repository: `list`, `get`, `create`, `update`, `patch`, `delete` |
+| `useMapoAuth()`   | `login`, `logout`, `fetchUser` — drives the auth store                      |
+| `useMapoFetch()`  | Pre-configured `$fetch` with 401/403 interceptors                           |
+| `useMapo()`       | Facade exposing the above as a single object                                |
+| `auth` middleware | Route middleware: redirects unauthenticated users to `loginUrl`             |
+
+## Dev workflow
+
+```bash
+pnpm dev:core   # from monorepo root — watch mode
+```
+
+## Configuration
+
+All endpoints fall back to the `MAPO_DEFAULTS` constant exported from this package. See [docs/modules/core](../../../docs/modules/core.md) for the full reference.

package/dist/index.d.cts

@@ -0,0 +1 @@
+export * from "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/index.js";

package/dist/index.d.mts

@@ -0,0 +1 @@
+export * from "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/index.js";

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/index.js";

package/dist/index.mjs

@@ -0,0 +1,21 @@
+import { createJiti } from "file:///home/runner/work/mapo-new/mapo-new/node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/lib/jiti.mjs";
+
+const jiti = createJiti(import.meta.url, {
+  "interopDefault": true,
+  "alias": {
+    "@mapomodule/core": "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core"
+  },
+  "transformOptions": {
+    "babel": {
+      "plugins": []
+    }
+  }
+})
+
+/** @type {import("/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/index.js")} */
+const _module = await jiti.import("/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/index.ts");
+
+export const MultipartPolicyEnum = _module.MultipartPolicyEnum;
+export const CoreCookieEnum = _module.CoreCookieEnum;
+export const useCanAccessRoute = _module.useCanAccessRoute;
+export const useMapoFetch = _module.useMapoFetch;

package/dist/module.d.cts

@@ -0,0 +1,2 @@
+export * from "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/module.js";
+export { default } from "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/module.js";

package/dist/module.d.mts

@@ -0,0 +1,2 @@
+export * from "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/module.js";
+export { default } from "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/module.js";

package/dist/module.d.ts

@@ -0,0 +1,2 @@
+export * from "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/module.js";
+export { default } from "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/module.js";

package/dist/module.json

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

package/dist/module.mjs

@@ -0,0 +1,20 @@
+import { createJiti } from "file:///home/runner/work/mapo-new/mapo-new/node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/lib/jiti.mjs";
+
+const jiti = createJiti(import.meta.url, {
+  "interopDefault": true,
+  "alias": {
+    "@mapomodule/core": "/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core"
+  },
+  "transformOptions": {
+    "babel": {
+      "plugins": []
+    }
+  }
+})
+
+/** @type {import("/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/module.js")} */
+const _module = await jiti.import("/home/runner/work/mapo-new/mapo-new/packages/@mapomodule/core/src/module.ts");
+
+export default _module?.default ?? _module;
+export const MultipartPolicyEnum = _module.MultipartPolicyEnum;
+export const CoreCookieEnum = _module.CoreCookieEnum;

package/dist/types.d.mts

@@ -0,0 +1,13 @@
+import type { ModuleHooks, ModuleRuntimeHooks, ModuleRuntimeConfig, ModulePublicRuntimeConfig } from './module.mjs'
+
+declare module '#app' {
+  interface RuntimeNuxtHooks extends ModuleRuntimeHooks {}
+}
+
+declare module '@nuxt/schema' {
+  interface NuxtHooks extends ModuleHooks {}
+  interface RuntimeConfig extends ModuleRuntimeConfig {}
+  interface PublicRuntimeConfig extends ModulePublicRuntimeConfig {}
+}
+
+export * from "./module.mjs"

package/package.json

@@ -1,22 +1,65 @@
 {
   "name": "@mapomodule/core",
-  "version": "1.0.0-alpha.9",
-  "description": "This is part of Mapo nuxt module. Injects the core mapo plugin helpers.",
-  "author": "bnznamco <gabriele.baldi.01@gmail.com>",
-  "keywords": [
-    "mapo",
-    "nuxt",
-    "Admin",
-    "Panel"
-  ],
+  "version": "2.0.0-beta.1",
+  "description": "Mapo core: API layer, auth, composables, middleware",
+  "type": "module",
   "license": "MIT",
-  "repository": "https://github.com/lotrekagency/mapo",
-  "main": "./module.js",
-  "dependencies": {
-    "@mapomodule/utils": "^1.0.0-alpha.9"
+  "author": "Lotrek Agency (https://lotrek.it)",
+  "homepage": "https://lotrekagency.github.io/mapo-new/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lotrekagency/mapo-new.git",
+    "directory": "packages/@mapomodule/core"
+  },
+  "bugs": {
+    "url": "https://github.com/lotrekagency/mapo-new/issues"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "next"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./types": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./runtime/*": {
+      "types": "./src/runtime/*.ts",
+      "import": "./dist/runtime/*.js",
+      "default": "./src/runtime/*"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "dev": "nuxt-module-build build --stub --watch",
+    "build": "nuxt-module-build build && tsc -p tsconfig.build-types.json",
+    "prepare": "nuxt-module-build build --stub",
+    "dev:prepare": "nuxt-module-build build --stub",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@mapomodule/store": "2.0.0-beta.1",
+    "@mapomodule/utils": "2.0.0-beta.1"
+  },
+  "peerDependencies": {
+    "nuxt": ">=4.0.0"
   },
-  "gitHead": "a75142247a9371981aea57b76828bd354b375aea"
+  "devDependencies": {
+    "@nuxt/kit": "4.4.2",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "4.4.2",
+    "nuxt": "^4.4.2",
+    "ofetch": "^1.5.1",
+    "pinia": "^3.0.4",
+    "vue": "^3.5.32",
+    "vue-router": "^5.0.4"
+  }
 }

package/src/index.ts

@@ -0,0 +1,4 @@
+export type * from "./module";
+export { MultipartPolicyEnum, CoreCookieEnum } from "./runtime/types";
+export { useCanAccessRoute } from "./runtime/auth/useCanAccessRoute";
+export { useMapoFetch } from "./runtime/utils/useMapoFetch";

package/src/module.ts

@@ -0,0 +1,102 @@
+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);
+
+    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")) {
+      await installModule("@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.spec.ts

@@ -0,0 +1,144 @@
+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): onResponseError is called instead of onResponse
+    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/api/crud.ts

@@ -0,0 +1,130 @@
+import { normalizeEndpoint } from "@mapomodule/utils";
+import { applyMultipartPolicy } from "./multipart";
+import { useMapoFetch } from "../utils/useMapoFetch";
+import { MultipartPolicyEnum } from "../types";
+import type {
+  PaginatedResponse,
+  CrudConfig,
+  CrudOptions,
+  CrudRepository,
+} from "../types";
+
+/**
+ * Creates a typed CRUD repository bound to a resource endpoint.
+ *
+ * The returned repository exposes common operations (`list`, `detail`, `create`,
+ * `update`, `partialUpdate`, `delete`) plus utility actions (`updateOrCreate`,
+ * `updateOrder`). Requests are executed through the shared Mapo fetch client.
+ *
+ * Configuration precedence:
+ * - `higherConf` defines repository-level default request options.
+ * - Per-call config arguments override repository-level defaults.
+ *
+ * Multipart handling:
+ * - Write methods pass payloads through `applyMultipartPolicy`, using
+ *   `MultipartPolicyEnum.Auto` unless overridden in `CrudOptions`.
+ *
+ * @typeParam T Entity type handled by the repository.
+ * @param endpoint Resource endpoint (normalized to a trailing-slash base path).
+ * @param higherConf Optional repository-level fetch configuration defaults.
+ * @returns A typed `CrudRepository<T>` for the specified endpoint.
+ */
+export function useCrud<T>(
+  endpoint: string,
+  higherConf?: CrudConfig,
+): CrudRepository<T> {
+  const base = normalizeEndpoint(endpoint);
+
+  /**
+   * Merges higher-level CRUD config with per-call config.
+   *
+   * Per-call options take precedence over defaults provided at repository
+   * creation time.
+   */
+  function merged(local?: CrudConfig): Record<string, unknown> {
+    return { ...higherConf, ...local };
+  }
+
+  /**
+   * Executes a typed request through the shared Mapo fetch client.
+   *
+   * @param path Target URL path.
+   * @param options Request options passed to `$mapoFetch`.
+   * @returns A promise resolving to the typed response payload.
+   */
+  function fetch<R>(
+    path: string,
+    options: Record<string, unknown>,
+  ): Promise<R> {
+    return useMapoFetch().fetch(path, options as never) as Promise<R>;
+  }
+
+  return {
+    list(params, config) {
+      return fetch<PaginatedResponse<T>>(base, {
+        method: "GET",
+        params,
+        ...merged(config),
+      });
+    },
+
+    detail(id, config) {
+      return fetch<T>(`${base}${id}/`, { method: "GET", ...merged(config) });
+    },
+
+    create(data, config, opts: CrudOptions = {}) {
+      const body = applyMultipartPolicy(
+        data as Record<string, unknown>,
+        opts.multipart ?? MultipartPolicyEnum.Auto,
+      );
+      return fetch<T>(base, { method: "POST", body, ...merged(config) });
+    },
+
+    update(id, data, config, opts: CrudOptions = {}) {
+      const body = applyMultipartPolicy(
+        data as Record<string, unknown>,
+        opts.multipart ?? MultipartPolicyEnum.Auto,
+      );
+      return fetch<T>(`${base}${id}/`, {
+        method: "PUT",
+        body,
+        ...merged(config),
+      });
+    },
+
+    partialUpdate(id, diff, config, opts: CrudOptions = {}) {
+      const body = applyMultipartPolicy(
+        diff as Record<string, unknown>,
+        opts.multipart ?? MultipartPolicyEnum.Auto,
+      );
+      return fetch<T>(`${base}${id}/`, {
+        method: "PATCH",
+        body,
+        ...merged(config),
+      });
+    },
+
+    delete(id, config) {
+      return fetch<void>(`${base}${id}/`, {
+        method: "DELETE",
+        ...merged(config),
+      });
+    },
+
+    updateOrCreate(data, config, opts) {
+      if (data.id) {
+        const { id, ...rest } = data;
+        return this.update(id, rest as Partial<T>, config, opts);
+      }
+      return this.create(data as Partial<T>, config, opts);
+    },
+
+    updateOrder(startId, endId, config) {
+      return fetch<void>(`${base}update_order/`, {
+        method: "POST",
+        body: { startId, endId },
+        ...merged(config),
+      });
+    },
+  };
+}

package/src/runtime/api/multipart.ts

@@ -0,0 +1,78 @@
+import type { MultipartPolicy } from "../types";
+import { MultipartPolicyEnum } from "../types";
+
+/**
+ * Flattened file entry extracted from a nested payload.
+ */
+interface FileEntry {
+  /** Dot-notation path where the file/blob was found in the original payload. */
+  path: string;
+  /** File-like value to append to FormData. */
+  file: File | Blob;
+}
+
+/**
+ * Recursively collects all `File`/`Blob` values from a nested payload.
+ *
+ * @param obj Value to inspect.
+ * @param path Current dot-notation traversal path.
+ * @returns A flat list of file entries with their original paths.
+ */
+function collectFiles(obj: unknown, path = ""): FileEntry[] {
+  if (obj instanceof File || obj instanceof Blob) {
+    return [{ path, file: obj }];
+  }
+  if (Array.isArray(obj)) {
+    return obj.flatMap((item, i) =>
+      collectFiles(item, path ? `${path}.${i}` : String(i)),
+    );
+  }
+  if (obj !== null && typeof obj === "object") {
+    return Object.entries(obj as Record<string, unknown>).flatMap(
+      ([key, val]) => collectFiles(val, path ? `${path}.${key}` : key),
+    );
+  }
+  return [];
+}
+
+/**
+ * Converts a payload into multipart `FormData`.
+ *
+ * The full payload is serialized under the `data` field, while every extracted
+ * `File`/`Blob` is appended as a dedicated FormData field at its dot-path key.
+ *
+ * @param obj Source payload object.
+ * @returns Multipart form data representation of `obj`.
+ */
+function toFormData(obj: Record<string, unknown>): FormData {
+  const files = collectFiles(obj);
+  const fd = new FormData();
+  // JSON.stringify naturally drops File/Blob — used as the plain-data field
+  fd.append("data", JSON.stringify(obj));
+  for (const { path, file } of files) {
+    fd.append(path, file);
+  }
+  return fd;
+}
+
+/**
+ * Applies the configured multipart policy to a request payload.
+ *
+ * Policy behavior:
+ * - `Disable`: always return the original object payload.
+ * - `Force`: always return a `FormData` payload.
+ * - `Auto`: return `FormData` only when at least one `File`/`Blob` is present.
+ *
+ * @param payload Request payload object.
+ * @param policy Multipart transformation policy.
+ * @returns Either the original payload or a `FormData` instance.
+ */
+export function applyMultipartPolicy(
+  payload: Record<string, unknown>,
+  policy: MultipartPolicy,
+): FormData | Record<string, unknown> {
+  if (policy === MultipartPolicyEnum.Disable) return payload;
+  if (policy === MultipartPolicyEnum.Force) return toFormData(payload);
+  // auto: transform only if File/Blob are present
+  return collectFiles(payload).length > 0 ? toFormData(payload) : payload;
+}