@carlonicora/nextjs-jsonapi 1.0.3 → 1.0.5

package/src/hooks/useSocket.ts

@@ -0,0 +1,201 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import io from "socket.io-client";
+import { Modules, rehydrate } from "../core";
+import { NotificationInterface } from "../features";
+
+type Socket = ReturnType<typeof io>;
+
+interface UseSocketOptions {
+  token: string;
+}
+
+interface SocketLike {
+  emit: (event: string, ...args: any[]) => void;
+  on: (event: string, callback: (...args: any[]) => void) => void;
+  off: (event: string, callback?: (...args: any[]) => void) => void;
+  connected: boolean;
+}
+
+interface UseSocketReturn {
+  socket: SocketLike | null;
+  isConnected: boolean;
+  messages: any[];
+  socketNotifications: NotificationInterface[];
+  sendMessage: (event: string, data: any) => void;
+  removeMessage: (index: number) => void;
+  removeSocketNotification: (index: number) => void;
+  clearMessages: () => void;
+  clearSocketNotifications: () => void;
+}
+
+export function useSocket({ token }: UseSocketOptions): UseSocketReturn {
+  const errorCount = useRef(0);
+  const shouldConnect = useRef(true);
+  const hookInstanceId = useRef(Math.random().toString(36).substring(2, 11));
+
+  const [socket, setSocket] = useState<Socket | null>(null);
+  const [isConnected, setIsConnected] = useState<boolean>(false);
+  const [messages, setMessages] = useState<any[]>([]);
+  const [socketNotifications, setSocketNotifications] = useState<NotificationInterface[]>([]);
+
+  const socketRef = useRef<Socket | null>(null);
+
+  useEffect(() => {
+    if (!token) return;
+
+    const globalSocketKey = `__socket_${process.env.NEXT_PUBLIC_API_URL?.replace(/[^a-zA-Z0-9]/g, "_")}`;
+
+    if (typeof window !== "undefined") {
+      const allSocketKeys = Object.keys(window).filter((key) => key.startsWith("__socket_"));
+
+      const existingSocket = (window as any)[globalSocketKey];
+      if (existingSocket) {
+        if (existingSocket.connected) {
+          // CRITICAL: Clear existing listeners to prevent accumulation
+          existingSocket.removeAllListeners();
+
+          socketRef.current = existingSocket;
+          setSocket(existingSocket);
+          setIsConnected(existingSocket.connected);
+        } else {
+          existingSocket.disconnect();
+          delete (window as any)[globalSocketKey];
+        }
+      }
+    }
+
+    let currentSocket: any;
+    const isReusing = socketRef.current && socketRef.current.connected;
+
+    if (isReusing) {
+      currentSocket = socketRef.current;
+    } else {
+      // React StrictMode protection: Prevent double-mounting issues
+      if (!shouldConnect.current) {
+        return;
+      }
+      shouldConnect.current = false;
+
+      try {
+        currentSocket = io(process.env.NEXT_PUBLIC_API_URL as string, {
+          auth: { token },
+          transports: ["websocket"],
+          timeout: 20000,
+        });
+
+        if (typeof window !== "undefined") {
+          if (currentSocket.id && currentSocket.id !== "undefined") {
+            (window as any)[globalSocketKey] = currentSocket;
+          }
+        }
+
+        socketRef.current = currentSocket;
+        setSocket(currentSocket);
+      } catch (error) {
+        return () => {}; // Return empty cleanup function on error
+      }
+    }
+
+    const handleConnect = () => {
+      setIsConnected(true);
+    };
+
+    const handleDisconnect = () => {
+      setIsConnected(false);
+    };
+
+    const handleMessage = (data: any) => {
+      setMessages((prevMessages) => {
+        const newMessages = [...prevMessages, data];
+        return newMessages;
+      });
+    };
+
+    const handleNotification = (data: any) => {
+      const notification = rehydrate(Modules.Notification, data) as NotificationInterface;
+      if (notification) {
+        setSocketNotifications((prev) => {
+          const newNotifications = [...prev, notification];
+          return newNotifications;
+        });
+      }
+    };
+
+    // Attach event listeners
+    if (currentSocket) {
+      currentSocket.on("connect", handleConnect);
+      currentSocket.on("disconnect", handleDisconnect);
+      currentSocket.on("message", handleMessage);
+      currentSocket.on("notification", handleNotification);
+    }
+
+    return () => {
+      shouldConnect.current = true;
+
+      // In development, preserve socket in window for HMR but remove listeners
+      if (currentSocket) {
+        if (process.env.NODE_ENV === "development") {
+          currentSocket.off("connect", handleConnect);
+          currentSocket.off("disconnect", handleDisconnect);
+          currentSocket.off("message", handleMessage);
+          currentSocket.off("notification", handleNotification);
+        } else {
+          currentSocket.off("connect", handleConnect);
+          currentSocket.off("disconnect", handleDisconnect);
+          currentSocket.off("message", handleMessage);
+          currentSocket.off("notification", handleNotification);
+
+          currentSocket.disconnect();
+
+          if (typeof window !== "undefined") {
+            delete (window as any)[globalSocketKey];
+          }
+        }
+      }
+    };
+  }, [token]);
+
+  const sendMessage = (event: string, data: any) => {
+    if (socketRef.current && isConnected) {
+      socketRef.current.emit(event, data);
+    }
+  };
+
+  const removeMessage = (index: number) => {
+    setMessages((prevMessages) => {
+      const newMessages = [...prevMessages];
+      newMessages.splice(index, 1);
+      return newMessages;
+    });
+  };
+
+  const removeSocketNotification = (index: number) => {
+    setSocketNotifications((prevNotifications) => {
+      const newNotifications = [...prevNotifications];
+      newNotifications.splice(index, 1);
+      return newNotifications;
+    });
+  };
+
+  const clearMessages = () => {
+    setMessages([]);
+  };
+
+  const clearSocketNotifications = () => {
+    setSocketNotifications([]);
+  };
+
+  return {
+    socket,
+    isConnected,
+    messages,
+    socketNotifications,
+    sendMessage,
+    removeMessage,
+    removeSocketNotification,
+    clearMessages,
+    clearSocketNotifications,
+  };
+}

package/src/hooks/useTableGenerator.ts

@@ -0,0 +1,20 @@
+"use client";
+
+import { UseTableStructureHook, UseTableStructureHookParams, UseTableStructureHookReturn } from "./types";
+import { ModuleWithPermissions } from "../permissions";
+import { tableGeneratorRegistry } from "./TableGeneratorRegistry";
+
+export function registerTableGenerator<T, U>(
+  type: string | ModuleWithPermissions,
+  hook: UseTableStructureHook<T, U>,
+): void {
+  const name = typeof type === "string" ? type : type.name;
+  tableGeneratorRegistry.register(name, hook);
+}
+
+export function useTableGenerator<T, U>(
+  type: ModuleWithPermissions,
+  params: UseTableStructureHookParams<T, U>,
+): UseTableStructureHookReturn<T> {
+  return tableGeneratorRegistry.get(type.name, params);
+}

package/src/i18n/config.ts

@@ -0,0 +1,74 @@
+import { ComponentType } from "react";
+
+// Types for injected hooks
+export interface I18nRouter {
+  push: (href: string) => void;
+  replace: (href: string) => void;
+  back: () => void;
+  forward: () => void;
+  refresh: () => void;
+  prefetch: (href: string) => void;
+}
+
+export type UseRouterHook = () => I18nRouter;
+export type UseTranslationsHook = (namespace?: string) => (key: string, values?: Record<string, any>) => string;
+export type UseLocaleHook = () => string;
+
+export type UseDateFnsLocaleHook = () => any; // date-fns Locale type
+export type LinkComponent = ComponentType<{ href: string; children: React.ReactNode; [key: string]: any }>;
+
+export interface I18nConfig {
+  useRouter: UseRouterHook;
+  useTranslations: UseTranslationsHook;
+  useLocale?: UseLocaleHook;
+  useDateFnsLocale?: UseDateFnsLocaleHook;
+  Link: LinkComponent;
+  usePathname: () => string;
+}
+
+// Private storage
+let _config: I18nConfig | null = null;
+
+// Configuration function (called by app at startup)
+export function configureI18n(config: I18nConfig): void {
+  _config = config;
+}
+
+// Hooks for library components to use
+export function useI18nRouter(): I18nRouter {
+  if (!_config?.useRouter) {
+    throw new Error("i18n not configured. Call configureI18n() at app startup.");
+  }
+  return _config.useRouter();
+}
+
+export function useI18nTranslations(namespace?: string): (key: string, values?: Record<string, any>) => string {
+  if (!_config?.useTranslations) {
+    // Fallback: return key as-is (safe for server/client)
+    return (key: string) => key;
+  }
+  return _config.useTranslations(namespace);
+}
+
+export function getI18nLink(): LinkComponent {
+  if (!_config?.Link) {
+    throw new Error("i18n not configured. Call configureI18n() at app startup.");
+  }
+  return _config.Link;
+}
+
+export function useI18nLocale(): string {
+  if (_config?.useLocale) {
+    return _config.useLocale();
+  }
+  // Fallback to English (safe for server/client)
+  return "en";
+}
+
+export function useI18nDateFnsLocale(): any {
+  if (_config?.useDateFnsLocale) {
+    return _config.useDateFnsLocale();
+  }
+  // Fallback to undefined (Calendar will use default)
+  return undefined;
+}

package/src/i18n/index.ts

@@ -0,0 +1,18 @@
+export {
+  configureI18n,
+  useI18nRouter,
+  useI18nTranslations,
+  useI18nLocale,
+  useI18nDateFnsLocale,
+  getI18nLink,
+} from "./config";
+
+export type {
+  I18nConfig,
+  I18nRouter,
+  UseRouterHook,
+  UseTranslationsHook,
+  UseLocaleHook,
+  UseDateFnsLocaleHook,
+  LinkComponent,
+} from "./config";

package/src/index.ts

@@ -0,0 +1,20 @@
+// Unified API (auto-detects environment)
+export * from "./unified";
+
+// Core exports for convenience
+export * from "./core";
+
+// Permissions
+export * from "./permissions";
+
+// I18n configuration (NOT hooks - those are in /hooks with "use client")
+export { configureI18n } from "./i18n";
+export type { I18nConfig } from "./i18n";
+
+// Roles configuration
+export { configureRoles, getRoleId, isRolesConfigured } from "./roles";
+export type { RoleIdConfig } from "./roles";
+
+// Auth configuration
+export { configureAuth, getTokenHandler } from "./features/auth/config";
+export type { TokenHandler, TokenParams } from "./features/auth/config";

package/src/interfaces/breadcrumb.item.data.interface.ts

@@ -0,0 +1,4 @@
+export type BreadcrumbItemData = {
+  name: string;
+  href?: string;
+};

package/src/interfaces/d3.link.interface.ts

@@ -0,0 +1,8 @@
+import type { SimulationLinkDatum } from "d3";
+import { D3Node } from "./d3.node.interface";
+
+export interface D3Link extends SimulationLinkDatum<D3Node> {
+  source: string | D3Node;
+  target: string | D3Node;
+  relationshipType?: string;
+}

package/src/interfaces/d3.node.interface.ts

@@ -0,0 +1,12 @@
+import { LucideIcon } from "lucide-react";
+
+export interface D3Node extends d3.SimulationNodeDatum {
+  id: string;
+  name: string;
+  instanceType: string;
+  relationshipType?: string;
+  isBrowsableNode?: boolean;
+  icon?: LucideIcon;
+  visible?: boolean;
+  washedOut?: boolean;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,3 @@
+export * from "./breadcrumb.item.data.interface";
+export * from "./d3.link.interface";
+export * from "./d3.node.interface";

package/src/permissions/check.ts

@@ -0,0 +1,127 @@
+import { Action, ModuleWithPermissions, PermissionModule, PermissionUser } from "./types";
+
+/**
+ * Check if a user has permission to perform an action on a module.
+ *
+ * @param module - The module to check permissions for
+ * @param action - The action to check (read, create, update, delete)
+ * @param user - The user with their modules and permissions
+ * @param data - Optional data object for path-based permission checks
+ */
+export function checkPermissions<T extends PermissionUser>(params: {
+  module: ModuleWithPermissions;
+  action: Action;
+  user: T;
+  data?: any;
+}): boolean {
+  const selectedModule = params.user.modules.find((module: PermissionModule) => module.id === params.module.moduleId);
+
+  if (!selectedModule) return false;
+  const permissionConfig = selectedModule.permissions[params.action];
+
+  if (!permissionConfig) return false;
+  if (typeof permissionConfig === "boolean") return permissionConfig as boolean;
+
+  if (!params.data) return true;
+
+  try {
+    const singlePermissionConfig = permissionConfig.split("|").map((p) => p.trim());
+
+    for (const path of singlePermissionConfig) {
+      if (getValueFromPath(params.data, path, params.user.id)) return true;
+    }
+    return false;
+  } catch {
+    if (typeof permissionConfig === "string") {
+      return getValueFromPath(params.data, permissionConfig, params.user.id);
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check permissions from server context where user object is not fully available.
+ *
+ * @param module - The module to check permissions for
+ * @param action - The action to check
+ * @param userId - The user's ID
+ * @param selectedModule - The selected module with its permissions
+ * @param data - Optional data object for path-based permission checks
+ */
+export function checkPermissionsFromServer(params: {
+  module: ModuleWithPermissions;
+  action: Action;
+  userId: string;
+  selectedModule?: PermissionModule;
+  data?: any;
+}): boolean {
+  if (!params.selectedModule) return false;
+  const permissionConfig = params.selectedModule.permissions[params.action];
+
+  if (!permissionConfig) return false;
+  if (typeof permissionConfig === "boolean") return permissionConfig as boolean;
+
+  if (!params.data) return true;
+
+  try {
+    const singlePermissionConfig = permissionConfig.split("|").map((p) => p.trim());
+
+    for (const path of singlePermissionConfig) {
+      if (getValueFromPath(params.data, path, params.userId)) return true;
+    }
+    return false;
+  } catch {
+    if (typeof permissionConfig === "string") {
+      return getValueFromPath(params.data, permissionConfig, params.userId);
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Traverse an object path and check if the value matches the user ID.
+ * Handles nested objects, arrays, and various data structures.
+ */
+export function getValueFromPath(obj: any, path: string, userId: string): any {
+  const parts = path.split(".");
+  let current = obj;
+
+  for (const part of parts) {
+    if (!current) return false;
+
+    if (Array.isArray(current)) {
+      let found = false;
+      for (const item of current) {
+        const result = getValueFromPath(item, parts.slice(parts.indexOf(part)).join("."), userId);
+        if (result === userId || result === true) {
+          found = true;
+          break;
+        }
+      }
+      return found;
+    } else if (current[part] !== undefined) {
+      current = current[part];
+    } else {
+      return false;
+    }
+  }
+
+  if (Array.isArray(current)) {
+    // If final value is an array, check if any element has id matching userId
+    return current.some((item: any) => {
+      if (typeof item === "object" && item.id !== undefined) {
+        return item.id.toString() === userId;
+      }
+      return item.toString() === userId;
+    });
+  }
+
+  // Direct comparison for primitive values or objects with id
+  if (typeof current === "object" && current.id !== undefined) {
+    return current.id.toString() === userId;
+  }
+
+  return current.toString() === userId;
+}

package/src/permissions/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./check";

package/src/permissions/types.ts

@@ -0,0 +1,109 @@
+import { ApiRequestDataTypeInterface } from "../core/interfaces/ApiRequestDataTypeInterface";
+import { FieldSelector } from "../core/fields/FieldSelector";
+
+/**
+ * Permission actions
+ */
+export enum Action {
+  Read = "read",
+  Create = "create",
+  Update = "update",
+  Delete = "delete",
+}
+
+/**
+ * Generic permission check type.
+ * Can be a boolean or a function that checks permissions dynamically.
+ * @template T - The data type being checked
+ * @template U - The user type (defaults to PermissionUser)
+ */
+export type PermissionCheck<T, U = PermissionUser> = boolean | ((user?: U | string, data?: T) => boolean);
+
+/**
+ * Page URL configuration for modules
+ */
+export type PageUrl = {
+  pageUrl?: string;
+};
+
+/**
+ * Module permission definition wrapper
+ */
+export type ModulePermissionDefinition<T> = {
+  interface: T;
+};
+
+/**
+ * Base module definition
+ */
+export type ModuleDefinition = {
+  pageUrl?: string;
+  name: string;
+  model: any;
+  feature?: string;
+  moduleId?: string;
+};
+
+/**
+ * Permission configuration for a module.
+ * Can be a boolean (allow/deny all) or a string path for dynamic checks.
+ */
+export interface PermissionConfig {
+  create: boolean | string;
+  read: boolean | string;
+  update: boolean | string;
+  delete: boolean | string;
+}
+
+/**
+ * Generic interface for a module that has permissions.
+ * Apps should ensure their Module class implements this.
+ */
+export interface PermissionModule {
+  id: string;
+  permissions: PermissionConfig;
+}
+
+/**
+ * Generic interface for a user that has modules with permissions.
+ * Apps should ensure their User class implements this.
+ */
+export interface PermissionUser {
+  id: string;
+  modules: PermissionModule[];
+}
+
+/**
+ * Module definition with permissions - extends ApiRequestDataTypeInterface
+ */
+export type ModuleWithPermissions = ApiRequestDataTypeInterface & {
+  pageUrl?: string;
+  feature?: string;
+  moduleId?: string;
+  inclusions?: Record<
+    string,
+    {
+      types?: string[];
+      fields?: FieldSelector<any>[];
+    }
+  >;
+};
+
+/**
+ * Factory type for creating module definitions
+ */
+export type ModuleFactory = (params: {
+  pageUrl?: string;
+  name: string;
+  cache?: string | "days" | "default" | "hours" | "max" | "minutes" | "seconds" | "weeks";
+  model: any;
+  feature?: string;
+  moduleId?: string;
+  inclusions?: Record<
+    string,
+    {
+      types?: string[];
+      fields?: FieldSelector<any>[];
+    }
+  >;
+}) => ModuleWithPermissions;

package/src/roles/config.ts

@@ -0,0 +1,46 @@
+/**
+ * Role ID configuration interface
+ * Apps provide their role IDs via configureRoles()
+ */
+export interface RoleIdConfig {
+  Administrator: string;
+  CompanyAdministrator: string;
+  [key: string]: string; // Allow additional roles
+}
+
+// Private storage for the injected role IDs
+let _roleId: RoleIdConfig | null = null;
+
+/**
+ * Configure role IDs for the library
+ * Call this at app startup to provide role ID constants
+ *
+ * @example
+ * ```typescript
+ * import { configureRoles } from "@carlonicora/nextjs-jsonapi";
+ * import { RoleId } from "@phlow/shared";
+ *
+ * configureRoles(RoleId);
+ * ```
+ */
+export function configureRoles(roleId: RoleIdConfig): void {
+  _roleId = roleId;
+}
+
+/**
+ * Get configured role IDs
+ * @throws Error if roles not configured
+ */
+export function getRoleId(): RoleIdConfig {
+  if (!_roleId) {
+    throw new Error("Roles not configured. Call configureRoles() at app startup.");
+  }
+  return _roleId;
+}
+
+/**
+ * Check if roles have been configured
+ */
+export function isRolesConfigured(): boolean {
+  return _roleId !== null;
+}

package/src/roles/index.ts

@@ -0,0 +1 @@
+export { configureRoles, getRoleId, isRolesConfigured, type RoleIdConfig } from "./config";