@carlonicora/nextjs-jsonapi 1.0.3 → 1.0.4

package/src/core/abstracts/AbstractApiData.ts

@@ -0,0 +1,138 @@
+import { ApiDataInterface } from "../interfaces/ApiDataInterface";
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { JsonApiHydratedDataInterface } from "../interfaces/JsonApiHydratedDataInterface";
+import { RehydrationFactory } from "../factories/RehydrationFactory";
+
+export abstract class AbstractApiData implements ApiDataInterface {
+  protected _jsonApi?: any;
+  protected _included?: any[];
+
+  protected _id?: string;
+  protected _type?: string;
+  protected _createdAt?: Date;
+  protected _updatedAt?: Date;
+
+  protected _self?: string;
+
+  get type(): string {
+    if (!this._type) throw new Error("Type is not set.");
+    return this._type;
+  }
+
+  get id(): string {
+    if (!this._id) throw new Error("Id is not set.");
+    return this._id;
+  }
+
+  get self(): string | undefined {
+    return this._self;
+  }
+
+  get createdAt(): Date {
+    return this._createdAt ?? new Date();
+  }
+
+  get updatedAt(): Date {
+    return this._updatedAt ?? new Date();
+  }
+
+  get included(): any[] {
+    return this._included ?? [];
+  }
+
+  get jsonApi(): any {
+    return this._jsonApi;
+  }
+
+  ingestJsonApi(_data: JsonApiHydratedDataInterface): void {}
+
+  generateApiUrl(_params?: any): string {
+    throw new Error("Method not implemented.");
+  }
+
+  createJsonApi(_data?: any): any {
+    throw new Error("Method not implemented.");
+  }
+
+  protected _readIncluded<T extends ApiDataInterface>(
+    data: JsonApiHydratedDataInterface,
+    type: string,
+    dataType: ApiRequestDataTypeInterface,
+  ): T | T[] | undefined {
+    if (
+      data.included === undefined ||
+      data.included.length === 0 ||
+      data.jsonApi.relationships === undefined ||
+      data.jsonApi.relationships[type] === undefined ||
+      data.jsonApi.relationships[type].data === undefined
+    ) {
+      return undefined;
+    }
+
+    if (Array.isArray(data.jsonApi.relationships[type].data)) {
+      const response: T[] = data.jsonApi.relationships[type].data.map((jsonApiData: any) => {
+        const includedData = data.included.find(
+          (includedData: any) => includedData.id === jsonApiData.id && includedData.type === jsonApiData.type,
+        );
+
+        if (includedData === undefined) return undefined;
+
+        return RehydrationFactory.rehydrate(dataType, {
+          jsonApi: includedData,
+          included: data.included,
+        }) as T;
+      });
+
+      return response.filter((item: T | undefined) => item !== undefined) as T[];
+    }
+
+    const includedData = data.included.find(
+      (includedData: any) =>
+        includedData.id === data.jsonApi.relationships[type].data.id &&
+        includedData.type === data.jsonApi.relationships[type].data.type,
+    );
+
+    if (includedData === undefined && data.allData !== undefined) {
+      // Try to find in allData as a fallback
+      const fallbackData = data.allData.find(
+        (includedData: any) =>
+          includedData.id === data.jsonApi.relationships[type].data.id &&
+          includedData.type === data.jsonApi.relationships[type].data.type,
+      );
+      if (fallbackData !== undefined) {
+        return RehydrationFactory.rehydrate(dataType, {
+          jsonApi: fallbackData,
+          included: data.included,
+        }) as T;
+      }
+    }
+
+    if (includedData === undefined) return undefined;
+
+    return RehydrationFactory.rehydrate(dataType, {
+      jsonApi: includedData,
+      included: data.included,
+    }) as T;
+  }
+
+  dehydrate(): JsonApiHydratedDataInterface {
+    return {
+      jsonApi: this._jsonApi,
+      included: this._included ?? [],
+    };
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    this._jsonApi = data.jsonApi;
+    this._included = data.included;
+
+    this._type = this._jsonApi.type;
+    this._id = this._jsonApi.id;
+    this._createdAt = this._jsonApi.meta?.createdAt !== undefined ? new Date(this._jsonApi.meta.createdAt) : undefined;
+    this._updatedAt = this._jsonApi.meta?.updatedAt !== undefined ? new Date(this._jsonApi.meta.updatedAt) : undefined;
+
+    this._self = this._jsonApi.links?.self ?? undefined;
+
+    return this;
+  }
+}

package/src/core/abstracts/AbstractService.ts

@@ -0,0 +1,263 @@
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { ApiResponseInterface } from "../interfaces/ApiResponseInterface";
+
+export enum HttpMethod {
+  GET = "GET",
+  POST = "POST",
+  PUT = "PUT",
+  PATCH = "PATCH",
+  DELETE = "DELETE",
+}
+
+export interface NextRef {
+  next?: string;
+}
+
+export interface PreviousRef {
+  previous?: string;
+}
+
+export interface SelfRef {
+  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 setGlobalErrorHandler(handler: (status: number, message: string) => void) {
+  globalErrorHandler = handler;
+}
+
+/**
+ * Get the current global error handler.
+ */
+export function getGlobalErrorHandler(): ((status: number, message: string) => void) | null {
+  return globalErrorHandler;
+}
+
+/**
+ * Abstract base class for services that interact with the JSON:API.
+ * Extend this class to create feature-specific services.
+ */
+export abstract class AbstractService {
+  /**
+   * 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"; // Server-side fallback
+    }
+
+    // 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";
+  }
+
+  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 an API call with automatic environment detection and error handling.
+   */
+  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> {
+    // Dynamic import to avoid bundling issues
+    const { JsonApiGet, JsonApiPost, JsonApiPut, JsonApiPatch, JsonApiDelete } =
+      await import("../../unified/JsonApiRequest");
+
+    let apiResponse: ApiResponseInterface;
+
+    // Get language based on environment
+    let language = "en";
+    if (typeof window === "undefined") {
+      const { getLocale } = await import("next-intl/server");
+      language = (await getLocale()) ?? "en";
+    } else {
+      // Client-side: extract locale from URL pathname
+      language = this.getClientLocale();
+    }
+
+    switch (params.method) {
+      case HttpMethod.GET:
+        apiResponse = await JsonApiGet({
+          classKey: params.type,
+          endpoint: params.endpoint,
+          companyId: params.companyId,
+          language: language,
+        });
+        break;
+      case HttpMethod.POST:
+        apiResponse = await JsonApiPost({
+          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 JsonApiPut({
+          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 JsonApiPatch({
+          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 JsonApiDelete({
+          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 && typeof window !== "undefined") {
+        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: HttpMethod;
+    endpoint: string;
+    companyId?: string;
+  }): Promise<any> {
+    const { JsonApiGet } = await import("../../unified/JsonApiRequest");
+
+    let language = "en";
+
+    if (typeof window === "undefined") {
+      const { getLocale } = await import("next-intl/server");
+      language = (await getLocale()) ?? "en";
+    } else {
+      // Client-side: extract locale from URL pathname
+      language = this.getClientLocale();
+    }
+
+    const apiResponse: ApiResponseInterface = await JsonApiGet({
+      classKey: params.type,
+      endpoint: params.endpoint,
+      companyId: params.companyId,
+      language: language,
+    });
+
+    if (!apiResponse.ok) {
+      if (globalErrorHandler && typeof window !== "undefined") {
+        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/index.ts

@@ -0,0 +1,2 @@
+export * from "./AbstractApiData";
+export * from "./AbstractService";

package/src/core/endpoint/EndpointCreator.ts

@@ -0,0 +1,97 @@
+import { FieldSelector } from "../fields/FieldSelector";
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+
+export type EndpointQuery = {
+  endpoint: ApiRequestDataTypeInterface;
+  id?: string;
+  childEndpoint?: ApiRequestDataTypeInterface | string;
+  childId?: string;
+  additionalParams?: { key: string; value: string | string[] }[];
+};
+
+export class EndpointCreator {
+  private _endpoint: EndpointQuery;
+
+  constructor(params: {
+    endpoint: ApiRequestDataTypeInterface;
+    id?: string;
+    childEndpoint?: ApiRequestDataTypeInterface | string;
+    childId?: string;
+    additionalParams?: { key: string; value: string }[];
+  }) {
+    this._endpoint = {
+      endpoint: params.endpoint,
+      id: params.id,
+      childEndpoint: params.childEndpoint,
+      childId: params.childId,
+      additionalParams: params.additionalParams ?? [],
+    };
+  }
+
+  endpoint(value: ApiRequestDataTypeInterface): EndpointCreator {
+    this._endpoint.endpoint = value;
+    return this;
+  }
+
+  id(value: string): EndpointCreator {
+    this._endpoint.id = value;
+    return this;
+  }
+
+  childEndpoint(value: ApiRequestDataTypeInterface | string): EndpointCreator {
+    this._endpoint.childEndpoint = value;
+    return this;
+  }
+
+  childId(value: string): EndpointCreator {
+    this._endpoint.childId = value;
+    return this;
+  }
+
+  set additionalParams(value: { key: string; value: string }[]) {
+    this._endpoint.additionalParams = value;
+  }
+
+  addAdditionalParam(key: string, value: string | string[]): EndpointCreator {
+    if (!this._endpoint.additionalParams) this._endpoint.additionalParams = [];
+    this._endpoint.additionalParams.push({ key, value });
+    return this;
+  }
+
+  limitToType(selectors: string[]): this {
+    this.addAdditionalParam(`include`, selectors.join(","));
+    return this;
+  }
+
+  limitToFields(selectors: FieldSelector<any>[]): this {
+    if (selectors.length === 0) return this;
+
+    selectors.forEach((selector) => {
+      const fieldString = selector.fields.join(",");
+      this.addAdditionalParam(`fields[${selector.type}]`, fieldString);
+    });
+
+    return this;
+  }
+
+  generate(): string {
+    let additionalParams = "";
+    if (this._endpoint.additionalParams) {
+      additionalParams = this._endpoint.additionalParams.map((param) => `${param.key}=${param.value}`).join("&");
+    }
+
+    let response = `${this._endpoint.endpoint.name}`;
+    if (this._endpoint.id) response += `/${this._endpoint.id}`;
+    if (this._endpoint.childEndpoint) {
+      response += `/${
+        typeof this._endpoint.childEndpoint === "string"
+          ? this._endpoint.childEndpoint
+          : this._endpoint.childEndpoint.name
+      }`;
+    }
+    if (this._endpoint.childId) response += `/${this._endpoint.childId}`;
+    if (additionalParams) response += `?${additionalParams}`;
+
+    return response;
+  }
+}

package/src/core/endpoint/index.ts

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

package/src/core/factories/JsonApiDataFactory.ts

@@ -0,0 +1,12 @@
+import { ApiDataInterface } from "../interfaces/ApiDataInterface";
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { DataClassRegistry } from "../registry/DataClassRegistry";
+
+export class JsonApiDataFactory {
+  public static create(classKey: ApiRequestDataTypeInterface, data: any): any {
+    const factoryClass = DataClassRegistry.get(classKey);
+
+    const instance = new factoryClass() as ApiDataInterface;
+    return instance.createJsonApi(data);
+  }
+}

package/src/core/factories/RehydrationFactory.ts

@@ -0,0 +1,30 @@
+import { ApiDataInterface } from "../interfaces/ApiDataInterface";
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { JsonApiHydratedDataInterface } from "../interfaces/JsonApiHydratedDataInterface";
+import { DataClassRegistry } from "../registry/DataClassRegistry";
+
+export class RehydrationFactory {
+  public static rehydrate<T extends ApiDataInterface>(
+    classKey: ApiRequestDataTypeInterface,
+    data: JsonApiHydratedDataInterface,
+  ): T {
+    const factoryClass = DataClassRegistry.get(classKey);
+
+    const instance = new factoryClass();
+    return instance.rehydrate(data) as T;
+  }
+
+  public static rehydrateList<T extends ApiDataInterface>(
+    classKey: ApiRequestDataTypeInterface,
+    data: JsonApiHydratedDataInterface[],
+  ): T[] {
+    const factoryClass = DataClassRegistry.get(classKey);
+
+    const response = data.map((item: JsonApiHydratedDataInterface) => {
+      const instance = new factoryClass();
+      return instance.rehydrate(item) as T;
+    });
+
+    return response;
+  }
+}

package/src/core/factories/index.ts

@@ -0,0 +1,2 @@
+export * from "./JsonApiDataFactory";
+export * from "./RehydrationFactory";

package/src/core/fields/FieldSelector.ts

@@ -0,0 +1,15 @@
+export type GetterKeys<T> = {
+  [K in keyof T]: T[K] extends () => any ? never : K;
+}[keyof T];
+
+export type FieldSelector<T> = {
+  type: string;
+  fields: ReadonlyArray<GetterKeys<T>>;
+};
+
+export function createJsonApiInclusion<T>(dataType: string, fields: ReadonlyArray<GetterKeys<T>>): FieldSelector<T> {
+  return {
+    type: dataType,
+    fields,
+  };
+}

package/src/core/fields/index.ts

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

package/src/core/index.ts

@@ -0,0 +1,20 @@
+// Interfaces
+export * from "./interfaces";
+
+// Abstracts (will be added)
+export * from "./abstracts";
+
+// Factories
+export * from "./factories";
+
+// Registry
+export * from "./registry";
+
+// Endpoint builder
+export * from "./endpoint";
+
+// Field selectors
+export * from "./fields";
+
+// Utilities
+export * from "./utils";

package/src/core/interfaces/ApiData.ts

@@ -0,0 +1,8 @@
+export type ApiData = {
+  data: any;
+  ok: boolean;
+  status: number;
+  statusText: string;
+  token?: string;
+  refreshToken?: string;
+};

package/src/core/interfaces/ApiDataInterface.ts

@@ -0,0 +1,15 @@
+import { JsonApiHydratedDataInterface } from "./JsonApiHydratedDataInterface";
+
+export interface ApiDataInterface {
+  get included(): any[];
+  get type(): string;
+  get id(): string;
+  get createdAt(): Date;
+  get updatedAt(): Date;
+  get self(): string | undefined;
+  get jsonApi(): any;
+  generateApiUrl(params?: any): string;
+  dehydrate(): JsonApiHydratedDataInterface;
+  rehydrate(data: JsonApiHydratedDataInterface): this;
+  createJsonApi(data: any): any;
+}

package/src/core/interfaces/ApiRequestDataTypeInterface.ts

@@ -0,0 +1,14 @@
+import { FieldSelector } from "../fields/FieldSelector";
+
+export type ApiRequestDataTypeInterface = {
+  name: string;
+  cache?: string;
+  inclusions?: Record<
+    string,
+    {
+      types?: string[];
+      fields?: FieldSelector<any>[];
+    }
+  >;
+  model: new () => any;
+};

package/src/core/interfaces/ApiResponseInterface.ts

@@ -0,0 +1,17 @@
+import { ApiDataInterface } from "./ApiDataInterface";
+
+export interface ApiResponseInterface {
+  ok: boolean;
+  response: number;
+  raw?: any;
+
+  self?: string;
+  next?: string;
+  prev?: string;
+  nextPage?: () => Promise<ApiResponseInterface>;
+  prevPage?: () => Promise<ApiResponseInterface>;
+
+  data: ApiDataInterface | ApiDataInterface[];
+
+  error: string;
+}

package/src/core/interfaces/JsonApiHydratedDataInterface.ts

@@ -0,0 +1,5 @@
+export interface JsonApiHydratedDataInterface {
+  jsonApi: any;
+  included: any[];
+  allData?: any[];
+}

package/src/core/interfaces/index.ts

@@ -0,0 +1,5 @@
+export * from "./ApiData";
+export * from "./ApiDataInterface";
+export * from "./ApiRequestDataTypeInterface";
+export * from "./ApiResponseInterface";
+export * from "./JsonApiHydratedDataInterface";