@carlonicora/nextjs-jsonapi 0.0.1 → 1.0.4

package/src/core/registry/DataClassRegistry.ts

@@ -0,0 +1,51 @@
+import { ApiDataInterface } from "../interfaces/ApiDataInterface";
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+
+export class DataClassRegistry {
+  private static _map = new Map<string, { new (): ApiDataInterface }>();
+
+  public static registerObjectClass(
+    key: ApiRequestDataTypeInterface,
+    classConstructor: { new (): ApiDataInterface },
+  ): void {
+    const classKey = key.name;
+    if (!this._map.has(classKey)) {
+      this._map.set(classKey, classConstructor);
+    }
+  }
+
+  public static get(classKey: ApiRequestDataTypeInterface): {
+    new (): ApiDataInterface;
+  } {
+    const response = this._map.get(classKey.name);
+    if (!response) {
+      throw new Error(`Class not registered for key: ${typeof classKey === "string" ? classKey : classKey.name}`);
+    }
+
+    return response;
+  }
+
+  /**
+   * Bootstrap the registry with all modules.
+   * This is a convenience method for apps to register all their modules at once.
+   *
+   * @param modules - An object with module definitions (like the app's Modules class)
+   */
+  public static bootstrap(modules: Record<string, ApiRequestDataTypeInterface>): void {
+    Object.values(modules).forEach((module) => {
+      if (module && module.model) {
+        this.registerObjectClass(module, module.model);
+      }
+    });
+  }
+
+  /**
+   * Clear all registered classes. Useful for testing.
+   */
+  public static clear(): void {
+    this._map.clear();
+  }
+}
+
+// Export alias for backward compatibility
+export { DataClassRegistry as DataClass };

package/src/core/registry/ModuleRegistrar.ts

@@ -0,0 +1,43 @@
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { DataClassRegistry } from "./DataClassRegistry";
+
+/**
+ * Helper class to bootstrap the registry from a Modules-style class.
+ * This supports the pattern where modules are defined as static getters.
+ */
+export class ModuleRegistrar {
+  private static _isBootstrapped = false;
+
+  /**
+   * Bootstrap the registry from a Modules class.
+   * Automatically detects static getters and registers their models.
+   *
+   * @param modulesClass - The Modules class with static getters
+   */
+  static bootstrap<T extends object>(modulesClass: T): void {
+    if (this._isBootstrapped) return;
+
+    const data = Object.getOwnPropertyNames(modulesClass)
+      .filter((key) => {
+        const descriptor = Object.getOwnPropertyDescriptor(modulesClass, key);
+        return descriptor && typeof descriptor.get === "function";
+      })
+      .map((key) => (modulesClass as any)[key] as ApiRequestDataTypeInterface);
+
+    data.forEach((item) => {
+      if (item && item.model) {
+        DataClassRegistry.registerObjectClass(item, item.model);
+      }
+    });
+
+    this._isBootstrapped = true;
+  }
+
+  /**
+   * Reset the bootstrapped state. Useful for testing.
+   */
+  static reset(): void {
+    this._isBootstrapped = false;
+    DataClassRegistry.clear();
+  }
+}

package/src/core/registry/ModuleRegistry.ts

@@ -0,0 +1,64 @@
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { ModuleWithPermissions } from "../../permissions/types";
+
+// Foundation module types - defined by LIBRARY
+export interface FoundationModuleDefinitions {
+  S3: ModuleWithPermissions;
+  Auth: ModuleWithPermissions;
+  User: ModuleWithPermissions;
+  Author: ModuleWithPermissions;
+  Company: ModuleWithPermissions;
+  Role: ModuleWithPermissions;
+  Notification: ModuleWithPermissions;
+  Push: ModuleWithPermissions;
+  Feature: ModuleWithPermissions;
+  Module: ModuleWithPermissions;
+  Content: ModuleWithPermissions;
+  UserTopic: ModuleWithPermissions;
+  UserExpertise: ModuleWithPermissions;
+}
+
+// App-specific modules - apps will augment this interface ONLY
+
+export interface AppModuleDefinitions {}
+
+// Combined type for full autocompletion
+export type ModuleDefinitions = FoundationModuleDefinitions & AppModuleDefinitions;
+
+class ModuleRegistryClass {
+  private _modules: Map<string, ApiRequestDataTypeInterface> = new Map();
+
+  register<K extends string>(name: K, module: ApiRequestDataTypeInterface): void {
+    this._modules.set(name, module);
+  }
+
+  get<K extends keyof ModuleDefinitions>(name: K): ModuleDefinitions[K] {
+    const module = this._modules.get(name as string);
+    if (!module) {
+      throw new Error(`Module "${String(name)}" not registered. Call bootstrap() first.`);
+    }
+    return module as ModuleDefinitions[K];
+  }
+
+  findByName(moduleName: string): ModuleWithPermissions {
+    // Search by module's name property (e.g., "topics", "articles")
+    for (const module of this._modules.values()) {
+      if ((module as ModuleWithPermissions).name === moduleName) {
+        return module as ModuleWithPermissions;
+      }
+    }
+    throw new Error(`Module not found: ${moduleName}`);
+  }
+}
+
+export const ModuleRegistry = new ModuleRegistryClass();
+
+// Proxy object for Modules.X syntax with autocompletion
+export const Modules = new Proxy({} as ModuleDefinitions, {
+  get(_, prop: string) {
+    if (prop === "findByName") {
+      return (name: string) => ModuleRegistry.findByName(name);
+    }
+    return ModuleRegistry.get(prop as keyof ModuleDefinitions);
+  },
+}) as ModuleDefinitions & { findByName: (name: string) => ModuleWithPermissions };

package/src/core/registry/index.ts

@@ -0,0 +1,3 @@
+export * from "./DataClassRegistry";
+export * from "./ModuleRegistrar";
+export * from "./ModuleRegistry";

package/src/core/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./translateResponse";
+export * from "./rehydrate";

package/src/core/utils/rehydrate.ts

@@ -0,0 +1,24 @@
+import { ApiDataInterface } from "../interfaces/ApiDataInterface";
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { JsonApiHydratedDataInterface } from "../interfaces/JsonApiHydratedDataInterface";
+import { RehydrationFactory } from "../factories/RehydrationFactory";
+
+/**
+ * Rehydrate a single dehydrated object back into its typed class instance.
+ */
+export function rehydrate<T extends ApiDataInterface>(
+  classKey: ApiRequestDataTypeInterface,
+  data: JsonApiHydratedDataInterface,
+): T {
+  return RehydrationFactory.rehydrate(classKey, data) as T;
+}
+
+/**
+ * Rehydrate a list of dehydrated objects back into typed class instances.
+ */
+export function rehydrateList<T extends ApiDataInterface>(
+  classKey: ApiRequestDataTypeInterface,
+  data: JsonApiHydratedDataInterface[],
+): T[] {
+  return RehydrationFactory.rehydrateList(classKey, data) as T[];
+}

package/src/core/utils/translateResponse.ts

@@ -0,0 +1,125 @@
+import { ApiData } from "../interfaces/ApiData";
+import { ApiDataInterface } from "../interfaces/ApiDataInterface";
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { ApiResponseInterface } from "../interfaces/ApiResponseInterface";
+import { DataClassRegistry } from "../registry/DataClassRegistry";
+
+/**
+ * Translates raw JSON:API data into typed objects.
+ * Does not require API response metadata.
+ */
+export function translateData<T extends ApiDataInterface>(params: {
+  classKey: ApiRequestDataTypeInterface;
+  data: any;
+}): T | T[] {
+  const factoryClass = DataClassRegistry.get(params.classKey);
+
+  if (!factoryClass) {
+    throw new Error(
+      `Class not registered for key: ${typeof params.classKey === "string" ? params.classKey : params.classKey.name}`,
+    );
+  }
+
+  const included: any = params.data.included ?? [];
+
+  if (Array.isArray(params.data.data)) {
+    const responseData: T[] = [];
+
+    for (const data of params.data.data) {
+      const object = new factoryClass();
+      object.rehydrate({ jsonApi: data, included: included, allData: params.data.data });
+      responseData.push(object as T);
+    }
+
+    return responseData as T[];
+  } else {
+    const responseData = new factoryClass();
+    responseData.rehydrate({
+      jsonApi: params.data.data,
+      included: included,
+    });
+
+    return responseData as T;
+  }
+}
+
+/**
+ * Translates a full API response into a typed ApiResponseInterface.
+ * Includes pagination support.
+ */
+export async function translateResponse<T extends ApiDataInterface>(params: {
+  classKey: ApiRequestDataTypeInterface;
+  apiResponse: ApiData;
+  companyId?: string;
+  language: string;
+  paginationHandler?: (endpoint: string) => Promise<ApiResponseInterface>;
+}): Promise<ApiResponseInterface> {
+  const response: ApiResponseInterface = {
+    ok: true,
+    response: 0,
+    data: [],
+    error: "",
+  };
+
+  const factoryClass = DataClassRegistry.get(params.classKey);
+
+  if (!factoryClass) {
+    throw new Error(
+      `Class not registered for key: ${typeof params.classKey === "string" ? params.classKey : params.classKey.name}`,
+    );
+  }
+
+  response.ok = params.apiResponse.ok;
+  response.response = params.apiResponse.status;
+
+  if (!params.apiResponse.ok) {
+    response.error = params.apiResponse?.data?.message ?? params.apiResponse.statusText;
+    return response;
+  }
+
+  if (params.apiResponse.status === 204) return response;
+
+  response.raw = params.apiResponse.data;
+
+  try {
+    const included: any = params.apiResponse.data.included ?? [];
+
+    if (params.apiResponse.data.links) {
+      response.self = params.apiResponse.data.links.self;
+
+      if (params.apiResponse.data.links.next && params.paginationHandler) {
+        response.next = params.apiResponse.data.links.next;
+        response.nextPage = async () => params.paginationHandler!(params.apiResponse.data.links.next);
+      }
+
+      if (params.apiResponse.data.links.prev && params.paginationHandler) {
+        response.prev = params.apiResponse.data.links.prev;
+        response.prevPage = async () => params.paginationHandler!(params.apiResponse.data.links.prev);
+      }
+    }
+
+    if (Array.isArray(params.apiResponse.data.data)) {
+      const responseData: T[] = [];
+
+      for (const data of params.apiResponse.data.data) {
+        const object = new factoryClass();
+        object.rehydrate({ jsonApi: data, included: included, allData: params.apiResponse.data.data });
+        responseData.push(object as T);
+      }
+
+      response.data = responseData;
+    } else {
+      const responseData = new factoryClass();
+      responseData.rehydrate({
+        jsonApi: params.apiResponse.data.data,
+        included: included,
+      });
+
+      response.data = responseData;
+    }
+  } catch (e) {
+    console.error(e);
+  }
+
+  return response;
+}

package/src/features/auth/auth.module.ts

@@ -0,0 +1,9 @@
+import { ModuleFactory } from "../../permissions";
+import { Auth } from ".";
+
+export const AuthModule = (factory: ModuleFactory) =>
+  factory({
+    pageUrl: "/auth",
+    name: "auth",
+    model: Auth,
+  });

package/src/features/auth/config.ts

@@ -0,0 +1,57 @@
+/**
+ * Token parameters for authentication cookie management
+ */
+export interface TokenParams {
+  token?: string;
+  refreshToken?: string;
+  userId?: string;
+  companyId?: string;
+  licenseExpirationDate?: Date;
+  roles?: string[];
+  features?: string[];
+  modules?: {
+    id: string;
+    permissions: {
+      create: boolean | string;
+      read: boolean | string;
+      update: boolean | string;
+      delete: boolean | string;
+    };
+  }[];
+}
+
+/**
+ * Token handler interface for dependency injection
+ * Apps must provide implementations of these functions via configureAuth()
+ */
+export interface TokenHandler {
+  updateToken: (params: TokenParams) => Promise<void>;
+  removeToken: () => Promise<void>;
+}
+
+// Private storage for the injected token handler
+let _tokenHandler: TokenHandler | null = null;
+
+/**
+ * Configure authentication token handling
+ * Call this at app startup to provide Server Actions for cookie management
+ *
+ * @example
+ * ```typescript
+ * import { configureAuth } from "@carlonicora/nextjs-jsonapi/features";
+ * import { updateToken, removeToken } from "@/features/auth/utils/AuthCookies";
+ *
+ * configureAuth({ updateToken, removeToken });
+ * ```
+ */
+export function configureAuth(handler: TokenHandler): void {
+  _tokenHandler = handler;
+}
+
+/**
+ * Internal getter for AuthService to access the token handler
+ * @internal
+ */
+export function getTokenHandler(): TokenHandler | null {
+  return _tokenHandler;
+}

package/src/features/auth/data/auth.interface.ts

@@ -0,0 +1,31 @@
+import { ApiDataInterface } from "../../../core";
+import { UserInterface } from "../../user";
+
+export type AuthInput = {
+  id?: string;
+  email?: string | undefined | null;
+  password?: string | undefined;
+  name?: string;
+  companyName?: string;
+  partitaIva?: string;
+  codiceFiscale?: string;
+};
+
+export type AuthQuery = {
+  userId?: string;
+
+  tokenCode?: string;
+  refreshToken?: string;
+
+  login?: boolean;
+  forgot?: boolean;
+  code?: string;
+  activationCode?: string;
+  checkUsername?: string;
+};
+
+export interface AuthInterface extends ApiDataInterface {
+  get token(): string;
+  get refreshToken(): string;
+  get user(): UserInterface;
+}

package/src/features/auth/data/auth.service.ts

@@ -0,0 +1,159 @@
+import { AuthInput, AuthInterface } from ".";
+import { JsonApiDelete, JsonApiGet, JsonApiPost } from "../../../";
+import {
+  AbstractService,
+  ApiResponseInterface,
+  EndpointCreator,
+  HttpMethod,
+  JsonApiHydratedDataInterface,
+  Modules,
+  rehydrate,
+} from "../../../core";
+import { UserInterface } from "../../user";
+import { getTokenHandler } from "../config";
+
+export class AuthService extends AbstractService {
+  static async login(params: { email: string; password: string; language?: string }): Promise<UserInterface> {
+    const language = params.language || "en-US";
+
+    const apiResponse: ApiResponseInterface = await JsonApiPost({
+      classKey: Modules.Auth,
+      endpoint: new EndpointCreator({ endpoint: Modules.Auth, id: "login" }).generate(),
+      body: { email: params.email, password: params.password } as AuthInput,
+      language: language,
+    });
+
+    if (!apiResponse.ok) throw new Error(apiResponse.error);
+
+    const auth = apiResponse.data as AuthInterface;
+
+    // Use injected token handler if configured
+    const handler = getTokenHandler();
+    if (handler) {
+      await handler.updateToken({
+        token: auth.token,
+        refreshToken: auth.refreshToken,
+        userId: auth.user.id,
+        companyId: auth.user.company?.id,
+        licenseExpirationDate: auth.user.company?.licenseExpirationDate,
+        roles: auth.user.roles.map((role) => role.id),
+        features: auth.user.company?.features?.map((feature) => feature.id) ?? [],
+        modules: auth.user.modules.map((module) => ({
+          id: module.id,
+          permissions: module.permissions,
+        })),
+      });
+    }
+
+    return auth.user;
+  }
+
+  static async logout(params?: { language?: string }): Promise<void> {
+    const language = params?.language || "en-US";
+
+    await JsonApiDelete({
+      classKey: Modules.Auth,
+      endpoint: new EndpointCreator({ endpoint: Modules.Auth }).generate(),
+      language: language,
+    });
+
+    // Use injected token handler if configured
+    const handler = getTokenHandler();
+    if (handler) {
+      await handler.removeToken();
+    }
+  }
+
+  static async initialiseForgotPassword(params: { email: string; language?: string }): Promise<void> {
+    const language = params.language || "en-US";
+
+    const response: ApiResponseInterface = await JsonApiPost({
+      classKey: Modules.Auth,
+      endpoint: new EndpointCreator({ endpoint: Modules.Auth, id: "forgot" }).generate(),
+      body: { email: params.email } as AuthInput,
+      language: language,
+    });
+
+    if (!response.ok) {
+      throw new Error(response.error);
+    }
+  }
+
+  static async register(params: AuthInput): Promise<void> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.Auth, id: "register" });
+
+    await this.callApi({
+      type: Modules.Auth,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+      input: params,
+    });
+  }
+
+  static async activate(params: { activationCode: string }): Promise<void> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.Auth,
+      id: "activate",
+      childEndpoint: params.activationCode,
+    });
+
+    await this.callApi({ type: Modules.Auth, method: HttpMethod.POST, endpoint: endpoint.generate() });
+  }
+
+  static async validateCode(params: { code: string; language?: string }): Promise<void> {
+    const language = params.language || "en-US";
+
+    const apiResponse: ApiResponseInterface = await JsonApiGet({
+      classKey: Modules.Auth,
+      endpoint: new EndpointCreator({ endpoint: Modules.Auth, id: "validate", childEndpoint: params.code }).generate(),
+      language: language,
+    });
+
+    if (!apiResponse.ok) throw new Error(apiResponse.error);
+  }
+
+  static async resetPassword(params: { code: string; password: string }): Promise<void> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.Auth, id: "reset", childEndpoint: params.code });
+
+    const input: AuthInput = { password: params.password };
+
+    await this.callApi({ type: Modules.Auth, method: HttpMethod.POST, endpoint: endpoint.generate(), input: input });
+  }
+
+  static async acceptInvitation(params: { code: string; password: string }): Promise<void> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.Auth, id: "invitation", childEndpoint: params.code });
+
+    const input: AuthInput = { password: params.password };
+
+    await this.callApi({ type: Modules.Auth, method: HttpMethod.POST, endpoint: endpoint.generate(), input: input });
+  }
+
+  static async findToken(params: { tokenCode: string }): Promise<AuthInterface> {
+    return await this.callApi<AuthInterface>({
+      type: Modules.Auth,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.Auth }).addAdditionalParam("code", params.tokenCode).generate(),
+    });
+  }
+
+  static async saveToken(params: { dehydratedAuth: JsonApiHydratedDataInterface }): Promise<void> {
+    const auth: AuthInterface = rehydrate(Modules.Auth, params.dehydratedAuth) as AuthInterface;
+
+    const handler = getTokenHandler();
+    if (handler) {
+      await handler.updateToken({
+        token: auth.token,
+        refreshToken: auth.refreshToken,
+        userId: auth.user.id,
+        companyId: auth.user.company?.id,
+        licenseExpirationDate: auth.user.company?.licenseExpirationDate,
+        roles: auth.user.roles.map((role) => role.id),
+        features: auth.user.company?.features?.map((feature) => feature.id) ?? [],
+        modules: auth.user.modules.map((module) => ({
+          id: module.id,
+          permissions: module.permissions,
+        })),
+      });
+    }
+  }
+}

package/src/features/auth/data/auth.ts

@@ -0,0 +1,54 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { UserInterface } from "../../user/data/user.interface";
+import { AuthInput, AuthInterface } from "./auth.interface";
+
+export class Auth extends AbstractApiData implements AuthInterface {
+  private _token?: string;
+  private _refreshToken?: string;
+  private _user?: UserInterface;
+
+  get token(): string {
+    if (!this._token) throw new Error("Token is not defined");
+    return this._token;
+  }
+
+  get refreshToken(): string {
+    if (!this._refreshToken) throw new Error("Refresh token is not defined");
+    return this._refreshToken;
+  }
+
+  get user(): UserInterface {
+    if (!this._user) throw new Error("User is not defined");
+    return this._user;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._token = data.jsonApi.attributes.token ?? undefined;
+    this._refreshToken = data.jsonApi.attributes.refreshToken ?? undefined;
+
+    this._user = this._readIncluded(data, "user", Modules.User) as UserInterface;
+
+    return this;
+  }
+
+  createJsonApi(data: AuthInput) {
+    const response: any = {
+      data: {
+        type: Modules.Auth.name,
+        attributes: {},
+      },
+    };
+
+    if (data.id) response.data.id = data.id;
+    if (data.email !== undefined) response.data.attributes.email = data.email;
+    if (data.name !== undefined) response.data.attributes.name = data.name;
+    if (data.companyName !== undefined) response.data.attributes.companyName = data.companyName;
+    if (data.password !== undefined) response.data.attributes.password = data.password;
+    if (data.partitaIva !== undefined) response.data.attributes.partitaIva = data.partitaIva;
+    if (data.codiceFiscale !== undefined) response.data.attributes.codiceFiscale = data.codiceFiscale;
+
+    return response;
+  }
+}

package/src/features/auth/data/index.ts

@@ -0,0 +1,3 @@
+export * from "./auth";
+export * from "./auth.interface";
+export * from "./auth.service";

package/src/features/auth/index.ts

@@ -0,0 +1,3 @@
+export * from "./auth.module";
+export * from "./data";
+export { configureAuth, type TokenHandler, type TokenParams } from "./config";

package/src/features/company/company.module.ts

@@ -0,0 +1,10 @@
+import { ModuleFactory } from "../../permissions";
+import { Company } from ".";
+
+export const CompanyModule = (factory: ModuleFactory) =>
+  factory({
+    pageUrl: "/companies",
+    name: "companies",
+    model: Company,
+    moduleId: "f9e77c8f-bfd1-4fd4-80b0-e1d891ab7113",
+  });

package/src/features/company/data/company.fields.ts

@@ -0,0 +1,6 @@
+export enum CompanyFields {
+  companyId = "companyId",
+  name = "name",
+  createdAt = "createdAt",
+  updatedAt = "updatedAt",
+}

package/src/features/company/data/company.interface.ts

@@ -0,0 +1,28 @@
+import { ApiDataInterface } from "../../../core";
+import { FeatureInterface } from "../../feature/data/feature.interface";
+import { ModuleInterface } from "../../module/data/module.interface";
+
+export type CompanyInput = {
+  id: string;
+  name?: string;
+  logo?: string;
+  configurations?: any;
+
+  license?: string;
+  privateKey?: string;
+
+  featureIds?: string[];
+  moduleIds?: string[];
+};
+
+export interface CompanyInterface extends ApiDataInterface {
+  get name(): string;
+  get configurations(): any;
+  get logo(): string | undefined;
+  get logoUrl(): string | undefined;
+
+  get licenseExpirationDate(): Date | undefined;
+
+  get features(): FeatureInterface[];
+  get modules(): ModuleInterface[];
+}