@carlonicora/nextjs-jsonapi 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",
@@ -91,6 +91,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "peerDependencies": {

package/src/atoms/index.ts

@@ -0,0 +1 @@
+export * from "./recentPagesAtom";

package/src/atoms/recentPagesAtom.ts

@@ -0,0 +1,10 @@
+import { atomWithStorage } from "jotai/utils";
+
+export interface RecentPage {
+  url: string;
+  title: string;
+  moduleType: string;
+  timestamp: number;
+}
+
+export const recentPagesAtom = atomWithStorage<RecentPage[]>("recentPages", []);

package/src/client/context/JsonApiContext.ts

@@ -0,0 +1,61 @@
+"use client";
+
+import { createContext, useContext } from "react";
+
+export type CacheProfile = "seconds" | "minutes" | "hours" | "days" | "weeks" | "max" | "default";
+
+export interface JsonApiConfig {
+  /**
+   * The base URL for API requests (e.g., https://api.example.com)
+   */
+  apiUrl: string;
+
+  /**
+   * Custom token getter function. If not provided, will use default cookie-based token retrieval.
+   */
+  tokenGetter?: () => Promise<string | undefined>;
+
+  /**
+   * Custom language getter function. If not provided, will use browser locale or next-intl.
+   */
+  languageGetter?: () => Promise<string>;
+
+  /**
+   * Default headers to include in all requests
+   */
+  defaultHeaders?: Record<string, string>;
+
+  /**
+   * Global error handler for failed requests (client-side only)
+   */
+  onError?: (status: number, message: string) => void;
+
+  /**
+   * Cache configuration
+   */
+  cacheConfig?: {
+    defaultProfile: CacheProfile;
+  };
+
+  /**
+   * Function to bootstrap the data class registry.
+   * Will be called automatically when needed.
+   */
+  bootstrapper?: () => void;
+}
+
+const JsonApiContext = createContext<JsonApiConfig | null>(null);
+
+export function useJsonApiConfig(): JsonApiConfig {
+  const config = useContext(JsonApiContext);
+  if (!config) {
+    throw new Error("useJsonApiConfig must be used within a JsonApiProvider");
+  }
+  return config;
+}
+
+export function useJsonApiConfigOptional(): JsonApiConfig | null {
+  return useContext(JsonApiContext);
+}
+
+export { JsonApiContext };

package/src/client/context/JsonApiProvider.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import React, { useEffect, useMemo } from "react";
+import { JsonApiConfig, JsonApiContext } from "./JsonApiContext";
+
+export interface JsonApiProviderProps {
+  config: JsonApiConfig;
+  children: React.ReactNode;
+}
+
+export function JsonApiProvider({ config, children }: JsonApiProviderProps) {
+  // Run bootstrapper on mount if provided
+  useEffect(() => {
+    if (config.bootstrapper) {
+      config.bootstrapper();
+    }
+  }, [config.bootstrapper]);
+
+  // Memoize config to prevent unnecessary re-renders
+  const memoizedConfig = useMemo(() => config, [config]);
+
+  return (
+    <JsonApiContext.Provider value={memoizedConfig}>
+      {children}
+    </JsonApiContext.Provider>
+  );
+}

package/src/client/context/index.ts

@@ -0,0 +1,2 @@
+export * from "./JsonApiContext";
+export * from "./JsonApiProvider";

package/src/client/hooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./useJsonApiGet";
+export * from "./useJsonApiMutation";
+export * from "./useRehydration";

package/src/client/hooks/useJsonApiGet.ts

@@ -0,0 +1,188 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { ApiDataInterface } from "../../core/interfaces/ApiDataInterface";
+import { ApiRequestDataTypeInterface } from "../../core/interfaces/ApiRequestDataTypeInterface";
+import { ApiResponseInterface } from "../../core/interfaces/ApiResponseInterface";
+
+export interface UseJsonApiGetOptions {
+  /**
+   * Whether to enable the query. If false, the query won't run.
+   */
+  enabled?: boolean;
+  /**
+   * Dependencies that trigger a refetch when changed.
+   */
+  deps?: any[];
+}
+
+export interface UseJsonApiGetResult<T> {
+  /**
+   * The fetched data, or null if not yet fetched.
+   */
+  data: T | null;
+  /**
+   * Whether the query is currently loading.
+   */
+  loading: boolean;
+  /**
+   * Error message if the query failed.
+   */
+  error: string | null;
+  /**
+   * The full API response (includes raw data, pagination, etc.)
+   */
+  response: ApiResponseInterface | null;
+  /**
+   * Function to manually refetch the data.
+   */
+  refetch: () => Promise<void>;
+  /**
+   * Whether there is a next page available.
+   */
+  hasNextPage: boolean;
+  /**
+   * Whether there is a previous page available.
+   */
+  hasPreviousPage: boolean;
+  /**
+   * Function to fetch the next page.
+   */
+  fetchNextPage: () => Promise<void>;
+  /**
+   * Function to fetch the previous page.
+   */
+  fetchPreviousPage: () => Promise<void>;
+}
+
+/**
+ * Hook for fetching data from a JSON:API endpoint.
+ *
+ * @example
+ * ```tsx
+ * const { data, loading, error, refetch } = useJsonApiGet<Article>({
+ *   classKey: Modules.Article,
+ *   endpoint: `/articles/${id}`,
+ * });
+ *
+ * if (loading) return <Loading />;
+ * if (error) return <Error message={error} />;
+ * return <ArticleView article={data} />;
+ * ```
+ */
+export function useJsonApiGet<T extends ApiDataInterface>(params: {
+  classKey: ApiRequestDataTypeInterface;
+  endpoint: string;
+  companyId?: string;
+  options?: UseJsonApiGetOptions;
+}): UseJsonApiGetResult<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [response, setResponse] = useState<ApiResponseInterface | null>(null);
+  const isMounted = useRef(true);
+
+  const fetchData = useCallback(async () => {
+    if (params.options?.enabled === false) return;
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const { JsonApiGet } = await import("../../unified/JsonApiRequest");
+      const language = navigator.language.split("-")[0] || "en";
+
+      const apiResponse = await JsonApiGet({
+        classKey: params.classKey,
+        endpoint: params.endpoint,
+        companyId: params.companyId,
+        language,
+      });
+
+      if (!isMounted.current) return;
+
+      setResponse(apiResponse);
+
+      if (apiResponse.ok) {
+        setData(apiResponse.data as T);
+      } else {
+        setError(apiResponse.error);
+      }
+    } catch (err) {
+      if (!isMounted.current) return;
+      setError(err instanceof Error ? err.message : "Unknown error");
+    } finally {
+      if (isMounted.current) {
+        setLoading(false);
+      }
+    }
+  }, [params.classKey, params.endpoint, params.companyId, params.options?.enabled]);
+
+  const fetchNextPage = useCallback(async () => {
+    if (!response?.nextPage) return;
+
+    setLoading(true);
+    try {
+      const nextResponse = await response.nextPage();
+      if (!isMounted.current) return;
+
+      setResponse(nextResponse);
+      if (nextResponse.ok) {
+        setData(nextResponse.data as T);
+      } else {
+        setError(nextResponse.error);
+      }
+    } catch (err) {
+      if (!isMounted.current) return;
+      setError(err instanceof Error ? err.message : "Unknown error");
+    } finally {
+      if (isMounted.current) {
+        setLoading(false);
+      }
+    }
+  }, [response]);
+
+  const fetchPreviousPage = useCallback(async () => {
+    if (!response?.prevPage) return;
+
+    setLoading(true);
+    try {
+      const prevResponse = await response.prevPage();
+      if (!isMounted.current) return;
+
+      setResponse(prevResponse);
+      if (prevResponse.ok) {
+        setData(prevResponse.data as T);
+      } else {
+        setError(prevResponse.error);
+      }
+    } catch (err) {
+      if (!isMounted.current) return;
+      setError(err instanceof Error ? err.message : "Unknown error");
+    } finally {
+      if (isMounted.current) {
+        setLoading(false);
+      }
+    }
+  }, [response]);
+
+  useEffect(() => {
+    isMounted.current = true;
+    fetchData();
+    return () => {
+      isMounted.current = false;
+    };
+  }, [fetchData, ...(params.options?.deps || [])]);
+
+  return {
+    data,
+    loading,
+    error,
+    response,
+    refetch: fetchData,
+    hasNextPage: !!response?.next,
+    hasPreviousPage: !!response?.prev,
+    fetchNextPage,
+    fetchPreviousPage,
+  };
+}

package/src/client/hooks/useJsonApiMutation.ts

@@ -0,0 +1,193 @@
+"use client";
+
+import { useState, useCallback } from "react";
+import { ApiDataInterface } from "../../core/interfaces/ApiDataInterface";
+import { ApiRequestDataTypeInterface } from "../../core/interfaces/ApiRequestDataTypeInterface";
+import { ApiResponseInterface } from "../../core/interfaces/ApiResponseInterface";
+
+export type MutationMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface UseJsonApiMutationResult<T> {
+  /**
+   * The result data from the mutation, or null if not yet executed.
+   */
+  data: T | null;
+  /**
+   * Whether the mutation is currently in progress.
+   */
+  loading: boolean;
+  /**
+   * Error message if the mutation failed.
+   */
+  error: string | null;
+  /**
+   * The full API response.
+   */
+  response: ApiResponseInterface | null;
+  /**
+   * Execute the mutation.
+   */
+  mutate: (params: MutationParams) => Promise<T | null>;
+  /**
+   * Reset the mutation state.
+   */
+  reset: () => void;
+}
+
+export interface MutationParams {
+  /**
+   * The endpoint to call.
+   */
+  endpoint: string;
+  /**
+   * The request body.
+   */
+  body?: any;
+  /**
+   * Files to upload.
+   */
+  files?: { [key: string]: File | Blob } | File | Blob;
+  /**
+   * Company ID for multi-tenant requests.
+   */
+  companyId?: string;
+  /**
+   * Override the default JSON:API body creation.
+   */
+  overridesJsonApiCreation?: boolean;
+  /**
+   * Response type if different from the request type.
+   */
+  responseType?: ApiRequestDataTypeInterface;
+}
+
+/**
+ * Hook for making mutations (POST, PUT, PATCH, DELETE) to a JSON:API endpoint.
+ *
+ * @example
+ * ```tsx
+ * const { mutate, loading, error } = useJsonApiMutation<Article>({
+ *   method: "POST",
+ *   classKey: Modules.Article,
+ * });
+ *
+ * const handleSubmit = async (data: ArticleInput) => {
+ *   const result = await mutate({
+ *     endpoint: "/articles",
+ *     body: data,
+ *   });
+ *   if (result) {
+ *     // Success!
+ *   }
+ * };
+ * ```
+ */
+export function useJsonApiMutation<T extends ApiDataInterface>(config: {
+  method: MutationMethod;
+  classKey: ApiRequestDataTypeInterface;
+  onSuccess?: (data: T) => void;
+  onError?: (error: string) => void;
+}): UseJsonApiMutationResult<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [response, setResponse] = useState<ApiResponseInterface | null>(null);
+
+  const reset = useCallback(() => {
+    setData(null);
+    setLoading(false);
+    setError(null);
+    setResponse(null);
+  }, []);
+
+  const mutate = useCallback(
+    async (params: MutationParams): Promise<T | null> => {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const { JsonApiPost, JsonApiPut, JsonApiPatch, JsonApiDelete } = await import("../../unified/JsonApiRequest");
+        const language = navigator.language.split("-")[0] || "en";
+
+        let apiResponse: ApiResponseInterface;
+
+        switch (config.method) {
+          case "POST":
+            apiResponse = await JsonApiPost({
+              classKey: config.classKey,
+              endpoint: params.endpoint,
+              companyId: params.companyId,
+              body: params.body,
+              overridesJsonApiCreation: params.overridesJsonApiCreation,
+              files: params.files,
+              language,
+              responseType: params.responseType,
+            });
+            break;
+          case "PUT":
+            apiResponse = await JsonApiPut({
+              classKey: config.classKey,
+              endpoint: params.endpoint,
+              companyId: params.companyId,
+              body: params.body,
+              files: params.files,
+              language,
+              responseType: params.responseType,
+            });
+            break;
+          case "PATCH":
+            apiResponse = await JsonApiPatch({
+              classKey: config.classKey,
+              endpoint: params.endpoint,
+              companyId: params.companyId,
+              body: params.body,
+              overridesJsonApiCreation: params.overridesJsonApiCreation,
+              files: params.files,
+              language,
+              responseType: params.responseType,
+            });
+            break;
+          case "DELETE":
+            apiResponse = await JsonApiDelete({
+              classKey: config.classKey,
+              endpoint: params.endpoint,
+              companyId: params.companyId,
+              language,
+              responseType: params.responseType,
+            });
+            break;
+        }
+
+        setResponse(apiResponse);
+
+        if (apiResponse.ok) {
+          const resultData = apiResponse.data as T;
+          setData(resultData);
+          config.onSuccess?.(resultData);
+          return resultData;
+        } else {
+          setError(apiResponse.error);
+          config.onError?.(apiResponse.error);
+          return null;
+        }
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Unknown error";
+        setError(errorMessage);
+        config.onError?.(errorMessage);
+        return null;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [config],
+  );
+
+  return {
+    data,
+    loading,
+    error,
+    response,
+    mutate,
+    reset,
+  };
+}

package/src/client/hooks/useRehydration.ts

@@ -0,0 +1,47 @@
+"use client";
+
+import { useMemo } from "react";
+import { ApiDataInterface } from "../../core/interfaces/ApiDataInterface";
+import { ApiRequestDataTypeInterface } from "../../core/interfaces/ApiRequestDataTypeInterface";
+import { JsonApiHydratedDataInterface } from "../../core/interfaces/JsonApiHydratedDataInterface";
+import { RehydrationFactory } from "../../core/factories/RehydrationFactory";
+
+/**
+ * Hook to rehydrate server-passed data into typed objects.
+ * Use this when passing data from server components to client components.
+ *
+ * @example
+ * ```tsx
+ * // In server component
+ * const article = await ArticleService.findOne(id);
+ * return <ArticleDetails data={article.dehydrate()} />;
+ *
+ * // In client component
+ * function ArticleDetails({ data }: { data: JsonApiHydratedDataInterface }) {
+ *   const article = useRehydration<Article>(Modules.Article, data);
+ *   return <div>{article.title}</div>;
+ * }
+ * ```
+ */
+export function useRehydration<T extends ApiDataInterface>(
+  classKey: ApiRequestDataTypeInterface,
+  data: JsonApiHydratedDataInterface | null | undefined,
+): T | null {
+  return useMemo(() => {
+    if (!data) return null;
+    return RehydrationFactory.rehydrate<T>(classKey, data);
+  }, [classKey, data]);
+}
+
+/**
+ * Hook to rehydrate a list of server-passed data into typed objects.
+ */
+export function useRehydrationList<T extends ApiDataInterface>(
+  classKey: ApiRequestDataTypeInterface,
+  data: JsonApiHydratedDataInterface[] | null | undefined,
+): T[] {
+  return useMemo(() => {
+    if (!data || data.length === 0) return [];
+    return RehydrationFactory.rehydrateList<T>(classKey, data);
+  }, [classKey, data]);
+}

package/src/client/index.ts

@@ -0,0 +1,11 @@
+"use client";
+
+// Context and Provider
+export * from "./context";
+
+// Hooks
+export * from "./hooks";
+
+// Client-side request utilities
+export * from "./request";
+export * from "./token";

package/src/client/request.ts

@@ -0,0 +1,97 @@
+"use client";
+
+import { ApiData } from "../core/interfaces/ApiData";
+
+export interface DirectFetchParams {
+  method: string;
+  url: string;
+  token?: string;
+  body?: any;
+  files?: { [key: string]: File | Blob } | File | Blob;
+  companyId?: string;
+  language: string;
+  additionalHeaders?: Record<string, string>;
+}
+
+/**
+ * Client-side direct fetch to bypass server action overhead.
+ * Use this for client-side API calls.
+ */
+export async function directFetch(params: DirectFetchParams): Promise<ApiData> {
+  const response: ApiData = {
+    data: undefined,
+    ok: false,
+    status: 0,
+    statusText: "",
+  };
+
+  const additionalHeaders: Record<string, string> = { ...params.additionalHeaders };
+
+  if (params.companyId) {
+    additionalHeaders["x-companyid"] = params.companyId;
+  }
+  additionalHeaders["x-language"] = params.language;
+
+  let requestBody: BodyInit | undefined = undefined;
+
+  if (params.files) {
+    const formData = new FormData();
+    if (params.body && typeof params.body === "object") {
+      for (const key in params.body) {
+        if (Object.prototype.hasOwnProperty.call(params.body, key)) {
+          formData.append(
+            key,
+            typeof params.body[key] === "object" ? JSON.stringify(params.body[key]) : params.body[key],
+          );
+        }
+      }
+    }
+
+    if (params.files instanceof Blob) {
+      formData.append("file", params.files);
+    } else if (typeof params.files === "object" && params.files !== null) {
+      for (const key in params.files) {
+        if (Object.prototype.hasOwnProperty.call(params.files, key)) {
+          formData.append(key, params.files[key]);
+        }
+      }
+    }
+
+    requestBody = formData;
+  } else if (params.body !== undefined) {
+    requestBody = JSON.stringify(params.body);
+    additionalHeaders["Content-Type"] = "application/json";
+  }
+
+  const options: RequestInit = {
+    method: params.method,
+    headers: { Accept: "application/json", ...additionalHeaders },
+  };
+
+  if (requestBody !== undefined) {
+    options.body = requestBody;
+  }
+
+  if (params.token) {
+    options.headers = { ...options.headers, Authorization: `Bearer ${params.token}` };
+  }
+
+  try {
+    const apiResponse = await fetch(params.url, options);
+
+    response.ok = apiResponse.ok;
+    response.status = apiResponse.status;
+    response.statusText = apiResponse.statusText;
+    try {
+      response.data = await apiResponse.json();
+    } catch {
+      response.data = undefined;
+    }
+  } catch {
+    response.ok = false;
+    response.status = 500;
+    response.data = undefined;
+  }
+
+  return response;
+}

package/src/client/token.ts

@@ -0,0 +1,10 @@
+"use client";
+
+import { getCookie } from "cookies-next";
+
+/**
+ * Get the authentication token from cookies (client-side only)
+ */
+export async function getClientToken(): Promise<string | undefined> {
+  return await getCookie("token");
+}

package/src/components/containers/PageContainer.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+import { cn } from "../../utils";
+import { Header } from "../navigations";
+
+type PageContainerProps = { children: React.ReactNode; testId?: string; className?: string };
+
+export function PageContainer({ children, testId, className }: PageContainerProps) {
+  return (
+    <div className={`flex h-full w-full flex-col`} data-testid={testId}>
+      <Header />
+      <main className={cn(`flex w-full flex-1 flex-col gap-y-4 pt-4 pl-4 pr-4`, className)}>{children}</main>
+    </div>
+  );
+}