@carlonicora/nextjs-jsonapi 1.0.3 → 1.0.4

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";

package/src/server/cache.ts

@@ -0,0 +1,28 @@
+"use server";
+
+import { revalidateTag } from "next/cache";
+
+export type CacheProfile = "seconds" | "minutes" | "hours" | "days" | "weeks" | "max" | "default";
+
+/**
+ * Revalidate a cache tag to invalidate cached data.
+ * Next.js 16+ requires a profile parameter.
+ *
+ * @param tag - The cache tag to invalidate
+ * @param profile - The cache profile (defaults to "max" for immediate invalidation)
+ */
+export async function invalidateCacheTag(tag: string, profile: CacheProfile = "max"): Promise<void> {
+  revalidateTag(tag, profile);
+}
+
+/**
+ * Revalidate multiple cache tags.
+ *
+ * @param tags - Array of cache tags to invalidate
+ * @param profile - The cache profile (defaults to "max" for immediate invalidation)
+ */
+export async function invalidateCacheTags(tags: string[], profile: CacheProfile = "max"): Promise<void> {
+  for (const tag of tags) {
+    revalidateTag(tag, profile);
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,3 @@
+export * from "./request";
+export * from "./token";
+export * from "./cache";

package/src/server/request.ts

@@ -0,0 +1,113 @@
+"use server";
+
+import { ApiData } from "../core/interfaces/ApiData";
+import { cacheLife } from "next/dist/server/use-cache/cache-life";
+import { cacheTag } from "next/dist/server/use-cache/cache-tag";
+
+export interface ServerRequestParams {
+  method: string;
+  url: string;
+  token?: string;
+  cache?: string;
+  body?: any;
+  files?: { [key: string]: File | Blob } | File | Blob;
+  companyId?: string;
+  language: string;
+  additionalHeaders?: Record<string, string>;
+}
+
+/**
+ * Server-side request with Next.js caching support.
+ * Uses "use cache" directive for automatic caching.
+ */
+export async function serverRequest(params: ServerRequestParams): Promise<ApiData> {
+  "use cache";
+
+  const response: ApiData = {
+    data: undefined,
+    ok: false,
+    status: 0,
+    statusText: "",
+  };
+
+  // Apply caching configuration
+  if (params.cache) {
+    if (["days", "default", "hours", "max", "minutes", "seconds", "weeks"].includes(params.cache)) {
+      cacheLife(params.cache as any);
+    } else {
+      cacheTag(params.cache);
+    }
+  } else {
+    cacheLife("seconds");
+  }
+
+  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/server/token.ts

@@ -0,0 +1,10 @@
+"use server";
+
+/**
+ * Get the authentication token from cookies (server-side)
+ */
+export async function getServerToken(): Promise<string | undefined> {
+  const { cookies } = await import("next/headers");
+  const cookieStore = await cookies();
+  return cookieStore.get("token")?.value;
+}