@carlonicora/nextjs-jsonapi 1.5.0 → 1.7.0

package/src/client/config.ts

@@ -0,0 +1,78 @@
+"use client";
+
+import { ModuleWithPermissions } from "../permissions/types";
+
+// Config storage for client-side contexts
+let _clientConfig: {
+  apiUrl: string;
+  appUrl?: string;
+  trackablePages?: ModuleWithPermissions[];
+  bootstrapper?: () => void;
+  additionalHeaders?: Record<string, string>;
+} | null = null;
+
+/**
+ * Configure the JSON:API client. This is the main configuration function.
+ * This is typically called during app initialization.
+ */
+export function configureJsonApi(config: {
+  apiUrl: string;
+  appUrl?: string;
+  trackablePages?: ModuleWithPermissions[];
+  bootstrapper?: () => void;
+  additionalHeaders?: Record<string, string>;
+}): void {
+  _clientConfig = config;
+  // Call bootstrapper immediately to register all modules
+  if (config.bootstrapper) {
+    config.bootstrapper();
+  }
+}
+
+/**
+ * Configure the client config. This is typically called during app initialization.
+ * @deprecated Use configureJsonApi instead
+ */
+export function configureClientConfig(config: {
+  apiUrl: string;
+  appUrl?: string;
+  trackablePages?: ModuleWithPermissions[];
+}): void {
+  _clientConfig = config;
+}
+
+/**
+ * Get the configured API URL.
+ */
+export function getApiUrl(): string {
+  if (_clientConfig?.apiUrl) {
+    return _clientConfig.apiUrl;
+  }
+  if (typeof process !== "undefined" && process.env?.NEXT_PUBLIC_API_URL) {
+    return process.env.NEXT_PUBLIC_API_URL;
+  }
+  return "";
+}
+
+/**
+ * Get the configured app URL.
+ */
+export function getAppUrl(): string {
+  if (_clientConfig?.appUrl) {
+    return _clientConfig.appUrl;
+  }
+  if (typeof process !== "undefined" && process.env?.NEXT_PUBLIC_APP_URL) {
+    return process.env.NEXT_PUBLIC_APP_URL;
+  }
+  if (typeof window !== "undefined") {
+    return window.location.origin;
+  }
+  return "";
+}
+
+/**
+ * Get the configured trackable pages.
+ */
+export function getTrackablePages(): ModuleWithPermissions[] {
+  return _clientConfig?.trackablePages ?? [];
+}

package/src/client/index.ts

@@ -3,12 +3,17 @@
 // Context and Provider
 export * from "./context";
 
-// Hooks
+// Client-side hooks
 export * from "./hooks";
 
 // Client-side request utilities
 export * from "./request";
 export * from "./token";
+export * from "./JsonApiClient";
+export * from "./config";
+
+// All hooks (merged from /hooks entry point)
+export * from "../hooks";
 
 // Table generator registration (must be in client-only context)
 import { useCompanyTableStructure } from "../features/company/hooks";

package/src/components/containers/TabsContainer.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useCurrentUserContext } from "../../contexts";
-import { UserInterface } from "../../features";
+import { UserInterface } from "../../features/user/data";
 import { Action, ModuleWithPermissions } from "../../permissions";
 import { ScrollArea, Tabs, TabsContent, TabsList, TabsTrigger } from "../../shadcnui";
 import { cn } from "../../utils";

package/src/components/editors/BlockNoteEditor.tsx

@@ -8,7 +8,9 @@ import { CheckIcon, XIcon } from "lucide-react";
 import { useTranslations } from "next-intl";
 import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useCurrentUserContext } from "../../contexts";
-import { S3Interface, S3Service, UserInterface } from "../../features";
+import { S3Interface } from "../../features/s3/data";
+import { UserInterface } from "../../features/user/data";
+import { S3Service } from "../../features/s3/data/s3.service";
 import { Button } from "../../shadcnui";
 import { BlockNoteDiffUtil, BlockNoteWordDiffRendererUtil, cn } from "../../utils";
 import { errorToast } from "../errors";

package/src/components/index.ts

@@ -8,6 +8,7 @@ export * from "./navigations";
 export * from "./pages";
 export * from "./tables";
 
+// Feature components
 export * from "../features/auth/components";
 export * from "../features/company/components";
 export * from "../features/content/components";
@@ -15,3 +16,6 @@ export * from "../features/feature/components";
 export * from "../features/notification/components";
 export * from "../features/role/components";
 export * from "../features/user/components";
+
+// shadcn/ui components (merged from /shadcnui entry point)
+export * from "../shadcnui";

package/src/components/navigations/Breadcrumb.tsx

@@ -21,7 +21,7 @@ type BreadcrumbProps = { items: BreadcrumbItemData[] };
 
 const ITEMS_TO_DISPLAY = 3;
 
-export function Breadcrumb({ items }: BreadcrumbProps) {
+export function BreadcrumbNavigation({ items }: BreadcrumbProps) {
   const generateUrl = usePageUrlGenerator();
   const t = useTranslations();
 

package/src/components/navigations/Header.tsx

@@ -2,7 +2,7 @@
 
 import { useSharedContext } from "../../contexts/SharedContext";
 import { SidebarTrigger } from "../../shadcnui";
-import { Breadcrumb } from "./Breadcrumb";
+import { BreadcrumbNavigation } from "./Breadcrumb";
 
 type HeaderProps = {
   children?: React.ReactNode;
@@ -16,7 +16,7 @@ export function Header({ children }: HeaderProps) {
       <div className="bg-sidebar flex h-12 w-full flex-row items-center justify-between pl-2 pr-4">
         <SidebarTrigger aria-label="Toggle sidebar" />
         <div className="flex w-full flex-row items-center justify-start">
-          <Breadcrumb items={breadcrumbs} />
+          <BreadcrumbNavigation items={breadcrumbs} />
         </div>
         <div className="flex w-64 flex-row items-center justify-end gap-x-4 whitespace-nowrap">
           {children ? children : null}

package/src/contexts/CommonContext.tsx

@@ -3,7 +3,7 @@
 import { useTranslations } from "next-intl";
 
 import { createContext, ReactNode, useContext } from "react";
-import { UserInterface } from "../features";
+import { UserInterface } from "../features/user/data";
 import { useCurrentUserContext } from "../features/user/contexts";
 import { BreadcrumbItemData } from "../interfaces";
 import { SharedProvider } from "./SharedContext";

package/src/contexts/SocketContext.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import React, { createContext, useContext } from "react";
-import { NotificationInterface } from "../features";
+import { NotificationInterface } from "../features/notification/data";
 import { useSocket } from "../hooks";
 
 interface SocketContextProps {

package/src/contexts/index.ts

@@ -5,3 +5,6 @@ export * from "../features/user/contexts";
 export * from "./CommonContext";
 export * from "./SharedContext";
 export * from "./SocketContext";
+
+// Jotai atoms (merged from /atoms entry point)
+export * from "../atoms";

package/src/core/abstracts/ClientAbstractService.ts

@@ -0,0 +1,255 @@
+"use client";
+
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { ApiResponseInterface } from "../interfaces/ApiResponseInterface";
+import {
+  ClientJsonApiGet,
+  ClientJsonApiPost,
+  ClientJsonApiPut,
+  ClientJsonApiPatch,
+  ClientJsonApiDelete,
+} from "../../client/JsonApiClient";
+// Duplicated to avoid importing from AbstractService which pulls in server code
+// These are exported so client services can import them from here instead of core
+export enum ClientHttpMethod {
+  GET = "GET",
+  POST = "POST",
+  PUT = "PUT",
+  PATCH = "PATCH",
+  DELETE = "DELETE",
+}
+
+export interface ClientNextRef {
+  next?: string;
+}
+
+export interface ClientPreviousRef {
+  previous?: string;
+}
+
+export interface ClientSelfRef {
+  self?: string;
+}
+
+let globalErrorHandler: ((status: number, message: string) => void) | null = null;
+
+/**
+ * Set a global error handler for API errors (client-side only).
+ * This handler will be called instead of throwing errors.
+ */
+export function setClientGlobalErrorHandler(handler: (status: number, message: string) => void) {
+  globalErrorHandler = handler;
+}
+
+/**
+ * Get the current global error handler.
+ */
+export function getClientGlobalErrorHandler(): ((status: number, message: string) => void) | null {
+  return globalErrorHandler;
+}
+
+/**
+ * Client-side abstract base class for services that interact with the JSON:API.
+ * Use this for client components.
+ */
+export abstract class ClientAbstractService {
+  /**
+   * Extract locale from client-side URL pathname
+   * URL structure: /{locale}/route-path (e.g., /it/accounts)
+   * Fallback chain: URL locale → navigator.language → "en"
+   */
+  private static getClientLocale(): string {
+    if (typeof window === "undefined") {
+      return "en"; // Should not happen in client service
+    }
+
+    // Extract locale from URL pathname (first segment after leading slash)
+    const pathSegments = window.location.pathname.split("/").filter(Boolean);
+    const urlLocale = pathSegments[0];
+
+    // Validate against supported locales (currently only "en")
+    const supportedLocales = ["en"];
+    if (urlLocale && supportedLocales.includes(urlLocale)) {
+      return urlLocale;
+    }
+
+    // Fallback to navigator language
+    const navigatorLocale = navigator.language.split("-")[0];
+    if (navigatorLocale && supportedLocales.includes(navigatorLocale)) {
+      return navigatorLocale;
+    }
+
+    // Final fallback
+    return "en";
+  }
+
+  /**
+   * Fetch the next page of results.
+   */
+  static async next<T>(params: {
+    type: ApiRequestDataTypeInterface;
+    endpoint: string;
+    next?: ClientNextRef;
+    previous?: ClientPreviousRef;
+    self?: ClientSelfRef;
+  }): Promise<T> {
+    return await this.callApi<T>({
+      method: ClientHttpMethod.GET,
+      type: params.type,
+      endpoint: params.endpoint,
+      next: params.next,
+      previous: params.previous,
+      self: params.self,
+    });
+  }
+
+  /**
+   * Fetch the previous page of results.
+   */
+  static async previous<T>(params: {
+    type: ApiRequestDataTypeInterface;
+    endpoint: string;
+    next?: ClientNextRef;
+    previous?: ClientPreviousRef;
+    self?: ClientSelfRef;
+  }): Promise<T> {
+    return await this.callApi<T>({
+      method: ClientHttpMethod.GET,
+      type: params.type,
+      endpoint: params.endpoint,
+      next: params.next,
+      previous: params.previous,
+      self: params.self,
+    });
+  }
+
+  /**
+   * Make a client-side API call.
+   */
+  protected static async callApi<T>(params: {
+    type: ApiRequestDataTypeInterface;
+    method: ClientHttpMethod;
+    endpoint: string;
+    companyId?: string;
+    input?: any;
+    overridesJsonApiCreation?: boolean;
+    next?: ClientNextRef;
+    previous?: ClientPreviousRef;
+    self?: ClientSelfRef;
+    responseType?: ApiRequestDataTypeInterface;
+    files?: { [key: string]: File | Blob } | File | Blob;
+  }): Promise<T> {
+    let apiResponse: ApiResponseInterface;
+
+    // Client-side: extract locale from URL pathname
+    const language = this.getClientLocale();
+
+    switch (params.method) {
+      case ClientHttpMethod.GET:
+        apiResponse = await ClientJsonApiGet({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          language: language,
+        });
+        break;
+      case ClientHttpMethod.POST:
+        apiResponse = await ClientJsonApiPost({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          body: params.input,
+          overridesJsonApiCreation: params.overridesJsonApiCreation,
+          language: language,
+          responseType: params.responseType,
+          files: params.files,
+        });
+        break;
+      case ClientHttpMethod.PUT:
+        apiResponse = await ClientJsonApiPut({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          body: params.input,
+          language: language,
+          responseType: params.responseType,
+          files: params.files,
+        });
+        break;
+      case ClientHttpMethod.PATCH:
+        apiResponse = await ClientJsonApiPatch({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          body: params.input,
+          overridesJsonApiCreation: params.overridesJsonApiCreation,
+          language: language,
+          responseType: params.responseType,
+          files: params.files,
+        });
+        break;
+      case ClientHttpMethod.DELETE:
+        apiResponse = await ClientJsonApiDelete({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          language: language,
+          responseType: params.responseType,
+        });
+        break;
+      default:
+        throw new Error("Method not found");
+    }
+
+    if (!apiResponse.ok) {
+      if (globalErrorHandler) {
+        globalErrorHandler(apiResponse.response, apiResponse.error);
+        return undefined as any;
+      } else {
+        const error = new Error(`${apiResponse.response}:${apiResponse.error}`) as any;
+        error.status = apiResponse.response;
+        error.digest = `HTTP_${apiResponse.response}`;
+        throw error;
+      }
+    }
+
+    if (apiResponse.next && params.next) params.next.next = apiResponse.next;
+    if (apiResponse.prev && params.previous) params.previous.previous = apiResponse.prev;
+    if (apiResponse.self && params.self) params.self.self = apiResponse.self;
+
+    return apiResponse.data as T;
+  }
+
+  /**
+   * Get raw JSON:API response data without deserialization.
+   */
+  protected static async getRawData(params: {
+    type: ApiRequestDataTypeInterface;
+    method: ClientHttpMethod;
+    endpoint: string;
+    companyId?: string;
+  }): Promise<any> {
+    const language = this.getClientLocale();
+
+    const apiResponse: ApiResponseInterface = await ClientJsonApiGet({
+      classKey: params.type,
+      endpoint: params.endpoint,
+      companyId: params.companyId,
+      language: language,
+    });
+
+    if (!apiResponse.ok) {
+      if (globalErrorHandler) {
+        globalErrorHandler(apiResponse.response, apiResponse.error);
+        return undefined as any;
+      } else {
+        const error = new Error(`${apiResponse.response}:${apiResponse.error}`) as any;
+        error.status = apiResponse.response;
+        error.digest = `HTTP_${apiResponse.response}`;
+        throw error;
+      }
+    }
+
+    return apiResponse.raw;
+  }
+}

package/src/core/abstracts/ServerAbstractService.ts

@@ -0,0 +1,180 @@
+// Server-only abstract service (NOT a server action - cannot be called from client components)
+
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { ApiResponseInterface } from "../interfaces/ApiResponseInterface";
+import {
+  ServerJsonApiGet,
+  ServerJsonApiPost,
+  ServerJsonApiPut,
+  ServerJsonApiPatch,
+  ServerJsonApiDelete,
+} from "../../server/JsonApiServer";
+import { HttpMethod, NextRef, PreviousRef, SelfRef } from "./AbstractService";
+
+/**
+ * Server-side abstract base class for services that interact with the JSON:API.
+ * Use this for server components and server actions.
+ */
+export abstract class ServerAbstractService {
+  /**
+   * Fetch the next page of results.
+   */
+  static async next<T>(params: {
+    type: ApiRequestDataTypeInterface;
+    endpoint: string;
+    next?: NextRef;
+    previous?: PreviousRef;
+    self?: SelfRef;
+  }): Promise<T> {
+    return await this.callApi<T>({
+      method: HttpMethod.GET,
+      type: params.type,
+      endpoint: params.endpoint,
+      next: params.next,
+      previous: params.previous,
+      self: params.self,
+    });
+  }
+
+  /**
+   * Fetch the previous page of results.
+   */
+  static async previous<T>(params: {
+    type: ApiRequestDataTypeInterface;
+    endpoint: string;
+    next?: NextRef;
+    previous?: PreviousRef;
+    self?: SelfRef;
+  }): Promise<T> {
+    return await this.callApi<T>({
+      method: HttpMethod.GET,
+      type: params.type,
+      endpoint: params.endpoint,
+      next: params.next,
+      previous: params.previous,
+      self: params.self,
+    });
+  }
+
+  /**
+   * Make a server-side API call.
+   */
+  protected static async callApi<T>(params: {
+    type: ApiRequestDataTypeInterface;
+    method: HttpMethod;
+    endpoint: string;
+    companyId?: string;
+    input?: any;
+    overridesJsonApiCreation?: boolean;
+    next?: NextRef;
+    previous?: PreviousRef;
+    self?: SelfRef;
+    responseType?: ApiRequestDataTypeInterface;
+    files?: { [key: string]: File | Blob } | File | Blob;
+  }): Promise<T> {
+    let apiResponse: ApiResponseInterface;
+
+    // Get language from next-intl server
+    const { getLocale } = await import("next-intl/server");
+    const language = (await getLocale()) ?? "en";
+
+    switch (params.method) {
+      case HttpMethod.GET:
+        apiResponse = await ServerJsonApiGet({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          language: language,
+        });
+        break;
+      case HttpMethod.POST:
+        apiResponse = await ServerJsonApiPost({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          body: params.input,
+          overridesJsonApiCreation: params.overridesJsonApiCreation,
+          language: language,
+          responseType: params.responseType,
+          files: params.files,
+        });
+        break;
+      case HttpMethod.PUT:
+        apiResponse = await ServerJsonApiPut({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          body: params.input,
+          language: language,
+          responseType: params.responseType,
+          files: params.files,
+        });
+        break;
+      case HttpMethod.PATCH:
+        apiResponse = await ServerJsonApiPatch({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          body: params.input,
+          overridesJsonApiCreation: params.overridesJsonApiCreation,
+          language: language,
+          responseType: params.responseType,
+          files: params.files,
+        });
+        break;
+      case HttpMethod.DELETE:
+        apiResponse = await ServerJsonApiDelete({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          language: language,
+          responseType: params.responseType,
+        });
+        break;
+      default:
+        throw new Error("Method not found");
+    }
+
+    if (!apiResponse.ok) {
+      const error = new Error(`${apiResponse.response}:${apiResponse.error}`) as any;
+      error.status = apiResponse.response;
+      error.digest = `HTTP_${apiResponse.response}`;
+      throw error;
+    }
+
+    if (apiResponse.next && params.next) params.next.next = apiResponse.next;
+    if (apiResponse.prev && params.previous) params.previous.previous = apiResponse.prev;
+    if (apiResponse.self && params.self) params.self.self = apiResponse.self;
+
+    return apiResponse.data as T;
+  }
+
+  /**
+   * Get raw JSON:API response data without deserialization.
+   */
+  protected static async getRawData(params: {
+    type: ApiRequestDataTypeInterface;
+    method: HttpMethod;
+    endpoint: string;
+    companyId?: string;
+  }): Promise<any> {
+    const { getLocale } = await import("next-intl/server");
+    const language = (await getLocale()) ?? "en";
+
+    const apiResponse: ApiResponseInterface = await ServerJsonApiGet({
+      classKey: params.type,
+      endpoint: params.endpoint,
+      companyId: params.companyId,
+      language: language,
+    });
+
+    if (!apiResponse.ok) {
+      const error = new Error(`${apiResponse.response}:${apiResponse.error}`) as any;
+      error.status = apiResponse.response;
+      error.digest = `HTTP_${apiResponse.response}`;
+      throw error;
+    }
+
+    return apiResponse.raw;
+  }
+}

package/src/core/abstracts/index.ts

@@ -1,2 +1,4 @@
 export * from "./AbstractApiData";
+// AbstractService is a base class needed by all services
 export * from "./AbstractService";
+export * from "./ClientAbstractService";

package/src/core/index.ts

@@ -1,7 +1,7 @@
-// Interfaces
+// Core interfaces
 export * from "./interfaces";
 
-// Abstracts (will be added)
+// Abstracts
 export * from "./abstracts";
 
 // Factories
@@ -16,5 +16,37 @@ export * from "./endpoint";
 // Field selectors
 export * from "./fields";
 
-// Utilities
+// Core utilities
 export * from "./utils";
+
+// Top-level interfaces (breadcrumb, d3)
+export * from "../interfaces";
+
+// Top-level utilities (cn, date-formatter, schemas, etc.)
+export * from "../utils";
+
+// Permissions
+export * from "../permissions";
+
+// Feature data classes, interfaces, and modules
+export * from "../features/auth/data";
+export * from "../features/auth/enums";
+export * from "../features/auth/auth.module";
+export * from "../features/company/data";
+export * from "../features/company/company.module";
+export * from "../features/content/data";
+export * from "../features/content/content.module";
+export * from "../features/feature/data";
+export * from "../features/feature/feature.module";
+export * from "../features/module";
+export * from "../features/notification/data";
+export * from "../features/notification/notification.module";
+export * from "../features/push/data";
+export * from "../features/push/push.module";
+export * from "../features/role/data";
+export * from "../features/role/role.module";
+export * from "../features/s3";
+export * from "../features/search";
+export * from "../features/user/data";
+export * from "../features/user/user.module";
+export * from "../features/user/author.module";