@mapomodule/core 1.0.0 → 2.0.0-beta.10

package/src/runtime/api/crud.ts

@@ -0,0 +1,138 @@
+import { normalizeEndpoint } from "@mapomodule/utils";
+import { applyMultipartPolicy } from "./multipart";
+import { useMapoFetch } from "../utils/useMapoFetch";
+import { MultipartPolicyEnum } from "../types";
+import type {
+  PaginatedResponse,
+  ResourceMetadata,
+  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),
+      });
+    },
+
+    options(config) {
+      return fetch<ResourceMetadata>(base, {
+        method: "OPTIONS",
+        ...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;
+}

package/src/runtime/auth/useCanAccessRoute.ts

@@ -0,0 +1,48 @@
+import { useAuthStore } from "@mapomodule/store/runtime/stores/auth";
+import type { RouteMeta } from "vue-router";
+
+/** Two-format permission spec: Django model shorthand or explicit codename list. */
+export type RoutePermissions = { model: string } | string[];
+
+/**
+ * Returns whether the current user can access a route based on its meta.
+ * Mirrors the logic of the `auth`, `permissions`, and `roles` middlewares
+ * so the sidebar and any UI that gates visibility stays in sync with navigation guards.
+ */
+export function useCanAccessRoute(meta: RouteMeta): boolean {
+  const auth = useAuthStore();
+
+  const raw = meta.middleware;
+  const middleware = Array.isArray(raw) ? raw : raw ? [raw] : [];
+
+  // auth middleware: must be logged in
+  if (middleware.includes("auth") && !auth.isAuthenticated) return false;
+
+  // roles middleware
+  if (middleware.includes("roles")) {
+    const required = meta.roles as string[] | undefined;
+    if (required?.length && !auth.info?.is_superuser) {
+      const userGroups = auth.info?.groups ?? [];
+      if (!required.some((r: string) => userGroups.includes(r))) return false;
+    }
+  }
+
+  // permissions middleware
+  if (middleware.includes("permissions")) {
+    const perms = meta.permissions as RoutePermissions | undefined;
+    if (perms && !auth.info?.is_superuser) {
+      if (Array.isArray(perms)) {
+        if (!perms.every((p) => auth.rawPermissions.includes(p))) return false;
+      } else {
+        const hasView = auth.rawPermissions.some(
+          (p) =>
+            p === `view_${perms.model}` ||
+            (p.endsWith(`_${perms.model}`) && p.startsWith("view")),
+        );
+        if (!hasView) return false;
+      }
+    }
+  }
+
+  return true;
+}

package/src/runtime/auth/useMapoAuth.ts

@@ -0,0 +1,91 @@
+import { useNuxtApp, navigateTo, useCookie, useRuntimeConfig } from "nuxt/app";
+import { useAuthStore } from "@mapomodule/store/runtime/stores/auth";
+import { CoreCookieEnum } from "../types";
+import type { Credentials, MapoCoreRuntimeConfig } from "../types";
+
+/**
+ * Optional endpoint overrides for auth operations.
+ */
+type AuthOverrides = {
+  /** Login endpoint used to create the server session. */
+  authLoginUrl?: string;
+  /** Endpoint used to fetch the current authenticated user profile. */
+  userInfoApi?: string;
+  /** Logout endpoint used to invalidate the server session. */
+  logoutUrl?: string;
+};
+
+/**
+ * Provides authentication helpers built on top of the shared Mapo fetch client.
+ *
+ * Endpoints are resolved from runtime config and can be selectively overridden
+ * through `options`.
+ *
+ * @param options Optional endpoint overrides for login, logout, and user fetch.
+ * @returns Auth helpers: `login`, `logout`, and `fetchUser`.
+ */
+export function useMapoAuth(options?: AuthOverrides) {
+  const rc = useRuntimeConfig().public.mapoCore as MapoCoreRuntimeConfig;
+  const authLoginUrl = options?.authLoginUrl ?? rc.authLoginUrl;
+  const userInfoApi = options?.userInfoApi ?? rc.userInfoApi;
+  const logoutUrl = options?.logoutUrl ?? rc.logoutUrl;
+  const loginUrl = rc.loginUrl;
+
+  const { $mapoFetch } = useNuxtApp() as ReturnType<typeof useNuxtApp> & {
+    $mapoFetch: typeof $fetch;
+  };
+  const authStore = useAuthStore();
+
+  /**
+   * Fetches the current user from `userInfoApi` and hydrates the auth store.
+   */
+  async function fetchUser(): Promise<void> {
+    const user = await $mapoFetch<
+      import("@mapomodule/store/runtime/types").MapoUser
+    >(userInfoApi, { method: "GET" });
+    authStore.setUser(user);
+  }
+
+  /**
+   * Performs login and then confirms the session by fetching the current user.
+   *
+   * The backend is expected to set an HttpOnly session cookie on successful
+   * login. `fetchUser` is used immediately after to hydrate store state.
+   *
+   * @param credentials User credentials payload for the login endpoint.
+   */
+  async function login(credentials: Credentials): Promise<void> {
+    // The backend sets the session cookie (HttpOnly) on a successful login.
+    // We confirm the session by fetching the user — if it succeeds, the
+    // store is hydrated and isAuthenticated becomes true.
+    await $mapoFetch(authLoginUrl, { method: "POST", body: credentials });
+    await fetchUser();
+  }
+
+  /**
+   * Logs out the current user and always performs local cleanup.
+   *
+   * Cleanup includes clearing the session cookie mirror, resetting auth store
+   * state, removing persisted Mapo draft keys from localStorage, and navigating
+   * to the configured login page.
+   */
+  async function logout(): Promise<void> {
+    try {
+      await $mapoFetch(logoutUrl, { method: "GET" });
+    } finally {
+      useCookie(CoreCookieEnum.Session).value = null;
+      authStore.reset();
+      if (typeof localStorage !== "undefined") {
+        const toRemove: string[] = [];
+        for (let i = 0; i < localStorage.length; i++) {
+          const k = localStorage.key(i);
+          if (k?.startsWith("mapo:draft:")) toRemove.push(k);
+        }
+        toRemove.forEach((k) => localStorage.removeItem(k));
+      }
+      await navigateTo(loginUrl);
+    }
+  }
+
+  return { login, logout, fetchUser };
+}

package/src/runtime/composables/useMapo.ts

@@ -0,0 +1,61 @@
+import { useSnackStore } from "@mapomodule/store/runtime/stores/snack";
+import { useConfirmStore } from "@mapomodule/store/runtime/stores/confirm";
+import { useMapoAuth } from "../auth/useMapoAuth";
+import { useCrud } from "../api/crud";
+import type { MapoOptions } from "../../types";
+import type { CrudRepository } from "../types";
+
+/**
+ * API layer exposed by {@link useMapo}.
+ */
+export interface MapoApiLayer {
+  /**
+   * Creates a CRUD repository bound to the provided endpoint.
+   *
+   * @param endpoint API endpoint for the resource collection.
+   * @returns A typed repository with list/detail/create/update/delete helpers.
+   */
+  crud<T>(endpoint: string): CrudRepository<T>;
+}
+
+/**
+ * High-level facade that groups the most common Mapo runtime capabilities.
+ *
+ * This keeps feature access ergonomic in components by exposing API, auth,
+ * feedback stores, and resolved options from a single composable call.
+ */
+export interface MapoFacade {
+  /** Resource-oriented API helpers. */
+  $api: MapoApiLayer;
+  /** Authentication helpers (`login`, `logout`, `fetchUser`). */
+  $auth: ReturnType<typeof useMapoAuth>;
+  /** Global snackbar store for user feedback messages. */
+  $snack: ReturnType<typeof useSnackStore>;
+  /** Global confirm dialog store for destructive/critical actions. */
+  $confirm: ReturnType<typeof useConfirmStore>;
+  /** Effective options passed to the facade factory. */
+  $options: MapoOptions;
+}
+
+/**
+ * Creates the Mapo facade used across admin pages and composables.
+ *
+ * The facade is a convenience aggregator over lower-level composables/stores:
+ * - `$api.crud<T>(endpoint)` delegates to `useCrud<T>(endpoint)`.
+ * - `$auth` delegates to `useMapoAuth(options)` (same overrides).
+ * - `$snack` and `$confirm` expose the shared UI feedback stores.
+ *
+ * @param options Optional runtime overrides forwarded to the auth layer.
+ * @returns A `MapoFacade` with grouped API/auth/feedback capabilities.
+ */
+export function useMapo(options: MapoOptions = {}): MapoFacade {
+  return {
+    $api: {
+      crud: <T>(endpoint: string): CrudRepository<T> => useCrud<T>(endpoint),
+    },
+    $auth: useMapoAuth(options),
+    $snack: useSnackStore(),
+    $confirm: useConfirmStore(),
+    $options: options,
+  };
+}

package/src/runtime/middleware/auth.ts

@@ -0,0 +1,24 @@
+import {
+  defineNuxtRouteMiddleware,
+  navigateTo,
+  useRuntimeConfig,
+} from "nuxt/app";
+import { useAuthStore } from "@mapomodule/store/runtime/stores/auth";
+
+/**
+ * Route middleware that protects authenticated pages.
+ *
+ * If the user is not authenticated, it redirects to the configured login page
+ * and appends the current route (`to.fullPath`) as a `redirect` query param,
+ * so the app can return the user to the original destination after login.
+ */
+export default defineNuxtRouteMiddleware((to) => {
+  const loginUrl = (useRuntimeConfig().public.mapoCore as { loginUrl: string })
+    .loginUrl;
+  const auth = useAuthStore();
+  if (!auth.isAuthenticated) {
+    return navigateTo(
+      `${loginUrl}?redirect=${encodeURIComponent(to.fullPath)}`,
+    );
+  }
+});

package/src/runtime/middleware/permissions.ts

@@ -0,0 +1,52 @@
+import { defineNuxtRouteMiddleware, createError } from "nuxt/app";
+import { useAuthStore } from "@mapomodule/store/runtime/stores/auth";
+
+type RoutePermissions = { model: string } | string[];
+
+/**
+ * Route middleware that enforces page-level permissions from `to.meta.permissions`.
+ *
+ * Supported formats:
+ * - `string[]`: all listed raw permission codenames are required.
+ * - `{ model: string }`: permissions are derived from codenames ending with
+ *   `_<model>` (for example, `view_article`, `change_article`).
+ *
+ * Behavior:
+ * - If no permissions are declared, access is allowed.
+ * - Superusers always pass; for model-based permissions, full CRUD actions are
+ *   exposed in `auth.pagePermissions[routeName]`.
+ * - For regular users, access is denied with HTTP 403 when required permissions
+ *   are missing (or `view` is missing for model-based permissions).
+ * - For allowed model-based routes, resolved actions are stored in
+ *   `auth.pagePermissions[routeName]`.
+ */
+export default defineNuxtRouteMiddleware((to) => {
+  const auth = useAuthStore();
+  const perms = to.meta.permissions as RoutePermissions | undefined;
+  if (!perms) return;
+  if (auth.info?.is_superuser) {
+    if (!Array.isArray(perms)) {
+      auth.pagePermissions[String(to.name)] = [
+        "view",
+        "add",
+        "change",
+        "delete",
+      ];
+    }
+    return;
+  }
+
+  if (Array.isArray(perms)) {
+    if (!perms.every((p) => auth.rawPermissions.includes(p)))
+      throw createError({ statusCode: 403, message: "Forbidden" });
+  } else {
+    const actions = auth.rawPermissions
+      .filter((p) => p.endsWith(`_${perms.model}`))
+      .map((p) => p.replace(`_${perms.model}`, ""));
+
+    if (!actions.includes("view"))
+      throw createError({ statusCode: 403, message: "Forbidden" });
+
+    auth.pagePermissions[String(to.name)] = actions;
+  }
+});

package/src/runtime/middleware/roles.ts

@@ -0,0 +1,23 @@
+import { defineNuxtRouteMiddleware, createError } from "nuxt/app";
+import { useAuthStore } from "@mapomodule/store/runtime/stores/auth";
+
+/**
+ * Route middleware that enforces role-based access from `to.meta.roles`.
+ *
+ * Access rules:
+ * - If no roles are configured on the route, access is allowed.
+ * - Superusers always bypass role checks.
+ * - For other users, at least one required role must match a user group.
+ * - If no match is found, navigation is blocked with HTTP 403.
+ */
+export default defineNuxtRouteMiddleware((to) => {
+  const auth = useAuthStore();
+  const required = to.meta.roles as string[] | undefined;
+  if (!required?.length) return;
+  if (auth.info?.is_superuser) return;
+  const userGroups = auth.info?.groups ?? [];
+  const hasRole = required.some((r) => userGroups.includes(r));
+  if (!hasRole) {
+    throw createError({ statusCode: 403, message: "Forbidden" });
+  }
+});

package/src/runtime/page-meta.nuxt.d.ts

@@ -0,0 +1,23 @@
+declare module "#app" {
+  interface PageMeta {
+    /**
+     * Permissions required to access this route. Checked by the 'permissions' middleware and sidebar visibility.
+     * - `{ model: string }` — derives `view_<model>` from a Django model name and populates `authStore.pagePermissions`
+     * - `string[]` — raw Django permission codenames (e.g. `['view_article', 'change_article']`)
+     */
+    permissions?: { model: string } | string[];
+    /** Required role/group names. Checked by the 'roles' middleware. */
+    roles?: string[];
+  }
+}
+
+declare module "vue-router" {
+  interface RouteMeta {
+    permissions?: { model: string } | string[];
+    roles?: string[];
+    /** Route middleware names applied to this route. Read by useCanAccessRoute for sidebar visibility. */
+    middleware?: string | string[];
+  }
+}
+
+export {};

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

@@ -0,0 +1,92 @@
+import { ref, computed } from "vue";
+import {
+  defineNuxtPlugin,
+  navigateTo,
+  useRequestHeaders,
+  useRoute,
+  useRuntimeConfig,
+} from "nuxt/app";
+import { useAuthStore } from "@mapomodule/store/runtime/stores/auth";
+import { useSnackStore } from "@mapomodule/store/runtime/stores/snack";
+import type { MapoCoreRuntimeConfig } from "../types";
+
+/**
+ * Registers the global Mapo fetch client and loading state.
+ *
+ * The plugin provides:
+ * - `$mapoFetch`: a shared `$fetch` instance with centralized request/response hooks.
+ * - `$mapoFetchLoading`: a computed boolean based on a global pending-request counter.
+ *
+ * Error handling behavior:
+ * - `401` (except logout calls): reset auth state and, on client, redirect to login
+ *   with the current route encoded in a `redirect` query parameter.
+ * - `403`: show a global "Permission denied" error snackbar.
+ */
+export default defineNuxtPlugin({
+  name: "mapo-core:fetch",
+  enforce: "pre",
+  setup() {
+    const rc = useRuntimeConfig().public.mapoCore as MapoCoreRuntimeConfig;
+    const logoutUrl = rc.logoutUrl;
+    const loginUrl = rc.loginUrl;
+
+    // Track whether a 401 redirect is already in flight to prevent duplicate redirects.
+    let redirectInFlight = false;
+
+    const handle = (status: number, requestUrl: string) => {
+      if (
+        status === 401 &&
+        !requestUrl.includes(logoutUrl) &&
+        !redirectInFlight
+      ) {
+        redirectInFlight = true;
+        const auth = useAuthStore();
+        auth.reset();
+        if (import.meta.client) {
+          const route = useRoute();
+          navigateTo(
+            `${loginUrl}?redirect=${encodeURIComponent(route.fullPath)}`,
+          );
+        }
+      }
+      if (status === 403) {
+        useSnackStore().show("Permission denied", "error");
+      }
+    };
+
+    // Global loading counter — incremented on every request, decremented once on every
+    // response (success or error) or request error. Exposed as $mapoFetchLoading so any
+    // component can show a spinner without wrapping every fetch call manually.
+    const pending = ref(0);
+    const mapoFetchLoading = computed(() => pending.value > 0);
+
+    const forwardedCookie = import.meta.server
+      ? useRequestHeaders(["cookie"]).cookie
+      : undefined;
+
+    const mapoFetch = $fetch.create({
+      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));
+      },
+      onRequestError() {
+        // Decrement counter on network errors (no response received).
+        pending.value--;
+      },
+    });
+
+    return {
+      provide: { mapoFetch, mapoFetchLoading },
+    };
+  },
+});