@mapomodule/core 1.0.0 → 2.0.0-beta.1

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,85 @@
+import { ref, computed } from "vue";
+import {
+  defineNuxtPlugin,
+  navigateTo,
+  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 mapoFetch = $fetch.create({
+      onRequest() {
+        pending.value++;
+      },
+      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--;
+      },
+    });
+
+    return {
+      provide: { mapoFetch, mapoFetchLoading },
+    };
+  },
+});

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

@@ -0,0 +1,62 @@
+import {
+  defineNuxtPlugin,
+  useRuntimeConfig,
+  useCookie,
+  useRequestHeaders,
+  useRequestURL,
+} from "nuxt/app";
+import { setActivePinia } from "pinia";
+import type { Pinia } from "pinia";
+import { useAuthStore } from "@mapomodule/store/runtime/stores/auth";
+import { useSidebarStore } from "@mapomodule/store/runtime/stores/sidebar";
+import type { MapoUser } from "@mapomodule/store/runtime/types";
+import { CoreCookieEnum } from "../types";
+import type { MapoCoreRuntimeConfig } from "../types";
+
+/**
+ * Performs server-side bootstrap of Mapo runtime stores.
+ *
+ * On each SSR request, this plugin:
+ * - Activates the request Pinia instance and initializes auth/sidebar stores.
+ * - Restores sidebar UI state from cookies.
+ * - 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.
+ */
+export default defineNuxtPlugin({
+  name: "mapo-core:init",
+  async setup(nuxtApp) {
+    const runtimeConfig = useRuntimeConfig().public.mapoCore as
+      | MapoCoreRuntimeConfig
+      | undefined;
+    const userInfoApi = runtimeConfig?.userInfoApi ?? "/api/profiles/me/";
+
+    const pinia = nuxtApp.$pinia as Pinia;
+    setActivePinia(pinia);
+    const authStore = useAuthStore(pinia);
+    const sidebarStore = useSidebarStore(pinia);
+
+    sidebarStore.hydrateFromCookies();
+
+    // The session cookie is HttpOnly — readable on SSR but not on the client.
+    // If present, hydrate the auth store by fetching the user with the
+    // incoming Cookie header forwarded to the proxy middleware.
+    const sessionCookie = useCookie(CoreCookieEnum.Session);
+    if (!sessionCookie.value) return;
+
+    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 });
+      authStore.setUser(user as MapoUser);
+    } catch (e) {
+      console.error(`[mapo] Cannot restore session from cookie:\n${e}`);
+      authStore.reset();
+      sessionCookie.value = null;
+    }
+  },
+});

package/src/runtime/types.nuxt.d.ts

@@ -0,0 +1,18 @@
+import type { $Fetch } from "ofetch";
+
+declare module "nuxt/app" {
+  interface NuxtApp {
+    $mapoFetch: $Fetch;
+  }
+}
+
+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/types.ts

@@ -0,0 +1,88 @@
+export enum MultipartPolicyEnum {
+  Auto = "auto",
+  Force = "force",
+  Disable = "disable",
+}
+
+export type MultipartPolicy = `${MultipartPolicyEnum}`;
+
+export enum CoreCookieEnum {
+  Session = "__mapo_session",
+}
+
+export interface ListParams {
+  page?: number;
+  limit?: number;
+  search?: string;
+  ordering?: string;
+  [key: string]: unknown;
+}
+
+export interface PaginatedResponse<T> {
+  results: T[];
+  count: number;
+  next?: string | null;
+  previous?: string | null;
+}
+
+export type ApiResponse<T> = T;
+
+export interface CrudConfig {
+  baseURL?: string;
+  headers?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+export interface CrudOptions {
+  multipart?: MultipartPolicy;
+}
+
+export interface CrudRepository<T> {
+  list(params?: ListParams, config?: CrudConfig): Promise<PaginatedResponse<T>>;
+  detail(id: string | number, config?: CrudConfig): Promise<T>;
+  create(data: Partial<T>, config?: CrudConfig, opts?: CrudOptions): Promise<T>;
+  update(
+    id: string | number,
+    data: Partial<T>,
+    config?: CrudConfig,
+    opts?: CrudOptions,
+  ): Promise<T>;
+  partialUpdate(
+    id: string | number,
+    diff: Partial<T>,
+    config?: CrudConfig,
+    opts?: CrudOptions,
+  ): Promise<T>;
+  delete(id: string | number, config?: CrudConfig): Promise<void>;
+  updateOrCreate(
+    data: Partial<T> & { id?: string | number },
+    config?: CrudConfig,
+    opts?: CrudOptions,
+  ): Promise<T>;
+  updateOrder(
+    startId: string | number,
+    endId: string | number,
+    config?: CrudConfig,
+  ): Promise<void>;
+}
+
+export interface Credentials {
+  username: string;
+  password: string;
+}
+
+export interface AuthToken {
+  token: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Shape of `runtimeConfig.public.mapoCore` as written by the module setup.
+ * All entries are guaranteed by the module `defaults`.
+ */
+export interface MapoCoreRuntimeConfig {
+  authLoginUrl: string;
+  userInfoApi: string;
+  logoutUrl: string;
+  loginUrl: string;
+}

package/src/runtime/utils/useMapoFetch.ts

@@ -0,0 +1,41 @@
+import { useNuxtApp } from "nuxt/app";
+import type { $Fetch } from "ofetch";
+import type { ComputedRef } from "vue";
+
+export interface UseMapoFetchReturn {
+  /** The auth-aware `$mapoFetch` instance (same one provided by the plugin). */
+  fetch: $Fetch;
+  /**
+   * `true` while at least one `$mapoFetch` request is in flight — globally,
+   * across the entire app. Incremented by the plugin-level `onRequest` hook
+   * and decremented by `onResponse` / `onResponseError`, so it stays accurate
+   * even for raw `useNuxtApp().$mapoFetch` calls outside this composable.
+   */
+  loading: ComputedRef<boolean>;
+}
+
+/**
+ * Returns the global `$mapoFetch` instance together with a centralized
+ * `loading` indicator that tracks **all** in-flight `$mapoFetch` requests,
+ * not just the ones made through this composable.
+ *
+ * @example
+ * ```ts
+ * const { fetch, loading } = useMapoFetch()
+ * await fetch('/api/articles/', { method: 'POST', body: payload })
+ * ```
+ *
+ * ```vue
+ * <UButton :loading="loading" @click="submit">Save</UButton>
+ * ```
+ */
+export function useMapoFetch(): UseMapoFetchReturn {
+  const nuxt = useNuxtApp() as unknown as {
+    $mapoFetch: $Fetch;
+    $mapoFetchLoading: ComputedRef<boolean>;
+  };
+  return {
+    fetch: nuxt.$mapoFetch,
+    loading: nuxt.$mapoFetchLoading,
+  };
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+export interface MapoOptions {
+  authLoginUrl?: string;
+  userInfoApi?: string;
+  logoutUrl?: string;
+  loginUrl?: string;
+}
+
+export const MAPO_DEFAULTS = {
+  authLoginUrl: "/api/auth/login",
+  userInfoApi: "/api/profiles/me/",
+  logoutUrl: "/api/auth/logout",
+  loginUrl: "/login",
+} satisfies Required<MapoOptions>;