@carlonicora/nextjs-jsonapi 1.15.0 → 1.17.0

package/src/core/endpoint/__tests__/EndpointCreator.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect } from "vitest";
+import { EndpointCreator } from "../EndpointCreator";
+import { createMockModule } from "../../../testing";
+
+describe("EndpointCreator", () => {
+  describe("basic URL generation", () => {
+    it("should generate URL from string endpoint", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" });
+      expect(creator.generate()).toBe("articles");
+    });
+
+    it("should generate URL from module endpoint", () => {
+      const mockModule = createMockModule({ name: "articles" });
+      const creator = new EndpointCreator({ endpoint: mockModule });
+      expect(creator.generate()).toBe("articles");
+    });
+
+    it("should include id in URL", () => {
+      const creator = new EndpointCreator({ endpoint: "articles", id: "123" });
+      expect(creator.generate()).toBe("articles/123");
+    });
+
+    it("should include child endpoint", () => {
+      const creator = new EndpointCreator({
+        endpoint: "articles",
+        id: "123",
+        childEndpoint: "comments",
+      });
+      expect(creator.generate()).toBe("articles/123/comments");
+    });
+
+    it("should include child id", () => {
+      const creator = new EndpointCreator({
+        endpoint: "articles",
+        id: "123",
+        childEndpoint: "comments",
+        childId: "456",
+      });
+      expect(creator.generate()).toBe("articles/123/comments/456");
+    });
+  });
+
+  describe("fluent API", () => {
+    it("should support chaining endpoint()", () => {
+      const creator = new EndpointCreator({ endpoint: "initial" });
+      const result = creator.endpoint("articles");
+      expect(result).toBe(creator);
+      expect(creator.generate()).toBe("articles");
+    });
+
+    it("should support chaining id()", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" });
+      const result = creator.id("123");
+      expect(result).toBe(creator);
+      expect(creator.generate()).toBe("articles/123");
+    });
+
+    it("should support chaining childEndpoint()", () => {
+      const creator = new EndpointCreator({ endpoint: "articles", id: "123" });
+      const result = creator.childEndpoint("comments");
+      expect(result).toBe(creator);
+      expect(creator.generate()).toBe("articles/123/comments");
+    });
+
+    it("should support chaining childId()", () => {
+      const creator = new EndpointCreator({
+        endpoint: "articles",
+        id: "123",
+        childEndpoint: "comments",
+      });
+      const result = creator.childId("456");
+      expect(result).toBe(creator);
+      expect(creator.generate()).toBe("articles/123/comments/456");
+    });
+
+    it("should support full fluent chain", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" })
+        .id("123")
+        .childEndpoint("comments")
+        .childId("456");
+      expect(creator.generate()).toBe("articles/123/comments/456");
+    });
+  });
+
+  describe("query parameters", () => {
+    it("should add additional params", () => {
+      const creator = new EndpointCreator({
+        endpoint: "articles",
+        additionalParams: [{ key: "page", value: "1" }],
+      });
+      expect(creator.generate()).toBe("articles?page=1");
+    });
+
+    it("should support addAdditionalParam()", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" });
+      creator.addAdditionalParam("page", "1");
+      creator.addAdditionalParam("limit", "10");
+      expect(creator.generate()).toBe("articles?page=1&limit=10");
+    });
+
+    it("should support array values in params", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" });
+      creator.addAdditionalParam("filter", ["tag1", "tag2"]);
+      expect(creator.generate()).toBe("articles?filter=tag1,tag2");
+    });
+
+    it("should combine URL and params", () => {
+      const creator = new EndpointCreator({
+        endpoint: "articles",
+        id: "123",
+      });
+      creator.addAdditionalParam("include", "author");
+      expect(creator.generate()).toBe("articles/123?include=author");
+    });
+  });
+
+  describe("limitToType", () => {
+    it("should add include param with single type", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" });
+      creator.limitToType(["author"]);
+      expect(creator.generate()).toBe("articles?include=author");
+    });
+
+    it("should add include param with multiple types", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" });
+      creator.limitToType(["author", "comments", "tags"]);
+      expect(creator.generate()).toBe("articles?include=author,comments,tags");
+    });
+  });
+
+  describe("limitToFields", () => {
+    it("should add fields param with single selector", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" });
+      creator.limitToFields([{ type: "articles", fields: ["title", "body"] }]);
+      expect(creator.generate()).toBe("articles?fields[articles]=title,body");
+    });
+
+    it("should add fields param with multiple selectors", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" });
+      creator.limitToFields([
+        { type: "articles", fields: ["title", "body"] },
+        { type: "authors", fields: ["name", "email"] },
+      ]);
+      expect(creator.generate()).toBe(
+        "articles?fields[articles]=title,body&fields[authors]=name,email"
+      );
+    });
+
+    it("should handle empty selectors array", () => {
+      const creator = new EndpointCreator({ endpoint: "articles" });
+      creator.limitToFields([]);
+      expect(creator.generate()).toBe("articles");
+    });
+  });
+
+  describe("module endpoint support", () => {
+    it("should work with module as child endpoint", () => {
+      const parentModule = createMockModule({ name: "users" });
+      const childModule = createMockModule({ name: "posts" });
+      const creator = new EndpointCreator({
+        endpoint: parentModule,
+        id: "1",
+        childEndpoint: childModule,
+      });
+      expect(creator.generate()).toBe("users/1/posts");
+    });
+  });
+});

package/src/core/factories/__tests__/JsonApiDataFactory.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { JsonApiDataFactory } from "../JsonApiDataFactory";
+import { DataClassRegistry } from "../../registry/DataClassRegistry";
+import { ApiDataInterface } from "../../interfaces/ApiDataInterface";
+
+// Mock class that tracks createJsonApi calls
+class MockDataClass implements Partial<ApiDataInterface> {
+  type = "articles";
+  id = "1";
+
+  createJsonApi = vi.fn((data: any) => ({
+    type: "articles",
+    attributes: data,
+  }));
+
+  get included() {
+    return [];
+  }
+  get createdAt() {
+    return new Date();
+  }
+  get updatedAt() {
+    return new Date();
+  }
+  get self() {
+    return "/articles/1";
+  }
+  get jsonApi() {
+    return { type: this.type, id: this.id };
+  }
+  generateApiUrl() {
+    return `/articles/${this.id}`;
+  }
+  dehydrate() {
+    return { jsonApi: this.jsonApi, included: [], allData: [] };
+  }
+  rehydrate(data: any) {
+    return this;
+  }
+}
+
+describe("JsonApiDataFactory", () => {
+  const mockModule = { name: "articles", model: MockDataClass };
+
+  beforeEach(() => {
+    DataClassRegistry.clear();
+    vi.clearAllMocks();
+  });
+
+  describe("create", () => {
+    it("should create JSON:API formatted data", () => {
+      DataClassRegistry.registerObjectClass(mockModule as any, MockDataClass as any);
+
+      const inputData = { title: "Test Article", body: "Content" };
+      const result = JsonApiDataFactory.create(mockModule as any, inputData);
+
+      expect(result).toEqual({
+        type: "articles",
+        attributes: inputData,
+      });
+    });
+
+    it("should use the registered class to create data", () => {
+      DataClassRegistry.registerObjectClass(mockModule as any, MockDataClass as any);
+
+      const inputData = { title: "Test" };
+      JsonApiDataFactory.create(mockModule as any, inputData);
+
+      // The create method should have been called
+      // Note: We can't directly verify createJsonApi was called since
+      // it's called on a new instance, but we can verify the output format
+    });
+
+    it("should throw for unregistered module", () => {
+      const unregisteredModule = { name: "unknown", model: MockDataClass };
+
+      expect(() =>
+        JsonApiDataFactory.create(unregisteredModule as any, { data: "test" })
+      ).toThrow("Class not registered for key: unknown");
+    });
+
+    it("should handle empty data", () => {
+      DataClassRegistry.registerObjectClass(mockModule as any, MockDataClass as any);
+
+      const result = JsonApiDataFactory.create(mockModule as any, {});
+
+      expect(result).toEqual({
+        type: "articles",
+        attributes: {},
+      });
+    });
+
+    it("should handle complex nested data", () => {
+      DataClassRegistry.registerObjectClass(mockModule as any, MockDataClass as any);
+
+      const complexData = {
+        title: "Test",
+        metadata: {
+          tags: ["tag1", "tag2"],
+          author: { name: "John", email: "john@example.com" },
+        },
+      };
+
+      const result = JsonApiDataFactory.create(mockModule as any, complexData);
+
+      expect(result.attributes).toEqual(complexData);
+    });
+  });
+});

package/src/core/factories/__tests__/RehydrationFactory.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { RehydrationFactory } from "../RehydrationFactory";
+import { DataClassRegistry } from "../../registry/DataClassRegistry";
+import { ApiDataInterface } from "../../interfaces/ApiDataInterface";
+import { JsonApiHydratedDataInterface } from "../../interfaces/JsonApiHydratedDataInterface";
+
+// Mock class that tracks rehydrate calls
+class MockDataClass implements Partial<ApiDataInterface> {
+  type = "articles";
+  id = "1";
+  rehydratedData: JsonApiHydratedDataInterface | null = null;
+
+  rehydrate(data: JsonApiHydratedDataInterface) {
+    this.rehydratedData = data;
+    return this;
+  }
+
+  get included() {
+    return [];
+  }
+  get createdAt() {
+    return new Date();
+  }
+  get updatedAt() {
+    return new Date();
+  }
+  get self() {
+    return "/articles/1";
+  }
+  get jsonApi() {
+    return { type: this.type, id: this.id };
+  }
+  generateApiUrl() {
+    return `/articles/${this.id}`;
+  }
+  dehydrate() {
+    return { jsonApi: this.jsonApi, included: [], allData: [] };
+  }
+  createJsonApi(data: any) {
+    return { type: this.type, attributes: data };
+  }
+}
+
+describe("RehydrationFactory", () => {
+  const mockModule = { name: "articles", model: MockDataClass };
+
+  beforeEach(() => {
+    DataClassRegistry.clear();
+  });
+
+  describe("rehydrate", () => {
+    it("should rehydrate a single data object", () => {
+      DataClassRegistry.registerObjectClass(mockModule as any, MockDataClass as any);
+
+      const hydratedData: JsonApiHydratedDataInterface = {
+        jsonApi: { type: "articles", id: "1", attributes: { title: "Test" } },
+        included: [],
+        allData: [],
+      };
+
+      const result = RehydrationFactory.rehydrate(mockModule as any, hydratedData);
+
+      expect(result).toBeInstanceOf(MockDataClass);
+      expect((result as MockDataClass).rehydratedData).toBe(hydratedData);
+    });
+
+    it("should throw for unregistered module", () => {
+      const unregisteredModule = { name: "unknown", model: MockDataClass };
+
+      const hydratedData: JsonApiHydratedDataInterface = {
+        jsonApi: {},
+        included: [],
+      };
+
+      expect(() =>
+        RehydrationFactory.rehydrate(unregisteredModule as any, hydratedData)
+      ).toThrow("Class not registered for key: unknown");
+    });
+
+    it("should create a new instance for rehydration", () => {
+      DataClassRegistry.registerObjectClass(mockModule as any, MockDataClass as any);
+
+      const hydratedData1: JsonApiHydratedDataInterface = {
+        jsonApi: { type: "articles", id: "1" },
+        included: [],
+      };
+      const hydratedData2: JsonApiHydratedDataInterface = {
+        jsonApi: { type: "articles", id: "2" },
+        included: [],
+      };
+
+      const result1 = RehydrationFactory.rehydrate(mockModule as any, hydratedData1);
+      const result2 = RehydrationFactory.rehydrate(mockModule as any, hydratedData2);
+
+      // Each rehydration should create a new instance
+      expect(result1).not.toBe(result2);
+    });
+  });
+
+  describe("rehydrateList", () => {
+    it("should rehydrate an array of data objects", () => {
+      DataClassRegistry.registerObjectClass(mockModule as any, MockDataClass as any);
+
+      const hydratedDataList: JsonApiHydratedDataInterface[] = [
+        { jsonApi: { type: "articles", id: "1" }, included: [] },
+        { jsonApi: { type: "articles", id: "2" }, included: [] },
+        { jsonApi: { type: "articles", id: "3" }, included: [] },
+      ];
+
+      const results = RehydrationFactory.rehydrateList(mockModule as any, hydratedDataList);
+
+      expect(results).toHaveLength(3);
+      results.forEach((result, index) => {
+        expect(result).toBeInstanceOf(MockDataClass);
+        expect((result as MockDataClass).rehydratedData).toBe(hydratedDataList[index]);
+      });
+    });
+
+    it("should return empty array for empty input", () => {
+      DataClassRegistry.registerObjectClass(mockModule as any, MockDataClass as any);
+
+      const results = RehydrationFactory.rehydrateList(mockModule as any, []);
+
+      expect(results).toEqual([]);
+    });
+
+    it("should throw for unregistered module", () => {
+      const unregisteredModule = { name: "unknown", model: MockDataClass };
+
+      expect(() =>
+        RehydrationFactory.rehydrateList(unregisteredModule as any, [
+          { jsonApi: {}, included: [] },
+        ])
+      ).toThrow("Class not registered for key: unknown");
+    });
+
+    it("should create unique instances for each item", () => {
+      DataClassRegistry.registerObjectClass(mockModule as any, MockDataClass as any);
+
+      const hydratedDataList: JsonApiHydratedDataInterface[] = [
+        { jsonApi: { type: "articles", id: "1" }, included: [] },
+        { jsonApi: { type: "articles", id: "2" }, included: [] },
+      ];
+
+      const results = RehydrationFactory.rehydrateList(mockModule as any, hydratedDataList);
+
+      // Each item should be a unique instance
+      expect(results[0]).not.toBe(results[1]);
+    });
+  });
+});

package/src/core/index.ts

@@ -29,13 +29,21 @@ export * from "../utils";
 export * from "../permissions";
 
 // Feature data classes, interfaces, and modules
+export * from "../features/auth/auth.module";
 export * from "../features/auth/data";
 export * from "../features/auth/enums";
-export * from "../features/auth/auth.module";
-export * from "../features/company/data";
+export * from "../features/billing/data";
+export * from "../features/billing/modules";
+export * from "../features/billing/stripe-customer";
+export * from "../features/billing/stripe-invoice";
+export * from "../features/billing/stripe-price";
+export * from "../features/billing/stripe-product";
+export * from "../features/billing/stripe-subscription";
+export * from "../features/billing/stripe-usage";
 export * from "../features/company/company.module";
-export * from "../features/content/data";
+export * from "../features/company/data";
 export * from "../features/content/content.module";
+export * from "../features/content/data";
 export * from "../features/feature/data";
 export * from "../features/feature/feature.module";
 export * from "../features/module";
@@ -47,6 +55,6 @@ export * from "../features/role/data";
 export * from "../features/role/role.module";
 export * from "../features/s3";
 export * from "../features/search";
+export * from "../features/user/author.module";
 export * from "../features/user/data";
 export * from "../features/user/user.module";
-export * from "../features/user/author.module";

package/src/core/interfaces/ApiResponseInterface.ts

@@ -4,6 +4,7 @@ export interface ApiResponseInterface {
   ok: boolean;
   response: number;
   raw?: any;
+  meta?: Record<string, any>;
 
   self?: string;
   next?: string;

package/src/core/registry/ModuleRegistry.ts

@@ -1,6 +1,6 @@
-import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
 import { ModuleWithPermissions } from "../../permissions/types";
-import { tryBootstrap, hasBootstrapper } from "./bootstrapStore";
+import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
+import { hasBootstrapper, tryBootstrap } from "./bootstrapStore";
 
 // Foundation module types - defined by LIBRARY
 export interface FoundationModuleDefinitions {
@@ -17,6 +17,15 @@ export interface FoundationModuleDefinitions {
   Content: ModuleWithPermissions;
   UserTopic: ModuleWithPermissions;
   UserExpertise: ModuleWithPermissions;
+  // Billing modules - READ: all users, UPDATE: CompanyAdministrator, ADMIN: Administrator
+  Billing: ModuleWithPermissions;
+  StripeCustomer: ModuleWithPermissions;
+  StripePaymentMethod: ModuleWithPermissions;
+  StripeSubscription: ModuleWithPermissions;
+  StripeInvoice: ModuleWithPermissions;
+  StripeProduct: ModuleWithPermissions;
+  StripePrice: ModuleWithPermissions;
+  StripeUsage: ModuleWithPermissions;
 }
 
 // App-specific modules - apps will augment this interface ONLY

package/src/core/registry/__tests__/DataClassRegistry.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { DataClassRegistry, DataClass } from "../DataClassRegistry";
+import { createMockModule } from "../../../testing";
+import { ApiDataInterface } from "../../interfaces/ApiDataInterface";
+
+// Mock class for testing
+class MockArticle implements Partial<ApiDataInterface> {
+  type = "articles";
+  id = "1";
+  get included() {
+    return [];
+  }
+  get createdAt() {
+    return new Date();
+  }
+  get updatedAt() {
+    return new Date();
+  }
+  get self() {
+    return "/articles/1";
+  }
+  get jsonApi() {
+    return { type: this.type, id: this.id };
+  }
+  generateApiUrl() {
+    return `/articles/${this.id}`;
+  }
+  dehydrate() {
+    return { jsonApi: this.jsonApi, included: [], allData: [] };
+  }
+  rehydrate(data: any) {
+    return this;
+  }
+  createJsonApi(data: any) {
+    return { type: this.type, attributes: data };
+  }
+}
+
+describe("DataClassRegistry", () => {
+  beforeEach(() => {
+    DataClassRegistry.clear();
+  });
+
+  describe("registerObjectClass", () => {
+    it("should register a class", () => {
+      const module = createMockModule({ name: "articles" });
+      DataClassRegistry.registerObjectClass(module, MockArticle as any);
+      expect(() => DataClassRegistry.get(module)).not.toThrow();
+    });
+
+    it("should not register duplicate classes", () => {
+      const module = createMockModule({ name: "articles" });
+      DataClassRegistry.registerObjectClass(module, MockArticle as any);
+      DataClassRegistry.registerObjectClass(module, MockArticle as any);
+      // Should not throw, just ignore duplicate
+      expect(() => DataClassRegistry.get(module)).not.toThrow();
+    });
+  });
+
+  describe("get", () => {
+    it("should retrieve registered class", () => {
+      const module = createMockModule({ name: "articles" });
+      DataClassRegistry.registerObjectClass(module, MockArticle as any);
+      const retrieved = DataClassRegistry.get(module);
+      expect(retrieved).toBe(MockArticle);
+    });
+
+    it("should throw for unregistered class", () => {
+      const module = createMockModule({ name: "unknown" });
+      expect(() => DataClassRegistry.get(module)).toThrow(
+        "Class not registered for key: unknown"
+      );
+    });
+  });
+
+  describe("bootstrap", () => {
+    it("should register all modules from object", () => {
+      const modules = {
+        Article: {
+          name: "articles",
+          model: MockArticle,
+        },
+        User: {
+          name: "users",
+          model: MockArticle,
+        },
+      };
+
+      DataClassRegistry.bootstrap(modules as any);
+
+      expect(() =>
+        DataClassRegistry.get({ name: "articles", model: MockArticle } as any)
+      ).not.toThrow();
+      expect(() =>
+        DataClassRegistry.get({ name: "users", model: MockArticle } as any)
+      ).not.toThrow();
+    });
+
+    it("should skip modules without model", () => {
+      const modules = {
+        Article: {
+          name: "articles",
+          model: MockArticle,
+        },
+        Invalid: {
+          name: "invalid",
+          // no model
+        },
+      };
+
+      DataClassRegistry.bootstrap(modules as any);
+
+      expect(() =>
+        DataClassRegistry.get({ name: "articles", model: MockArticle } as any)
+      ).not.toThrow();
+      expect(() =>
+        DataClassRegistry.get({ name: "invalid", model: null } as any)
+      ).toThrow();
+    });
+  });
+
+  describe("clear", () => {
+    it("should clear all registered classes", () => {
+      const module = createMockModule({ name: "articles" });
+      DataClassRegistry.registerObjectClass(module, MockArticle as any);
+      DataClassRegistry.clear();
+      expect(() => DataClassRegistry.get(module)).toThrow();
+    });
+  });
+
+  describe("DataClass alias", () => {
+    it("should be an alias for DataClassRegistry", () => {
+      expect(DataClass).toBe(DataClassRegistry);
+    });
+  });
+});