@carlonicora/nextjs-jsonapi 3.0.1 → 3.1.1

package/src/features/ai-connection/data/__tests__/ai-connection.test.ts

@@ -0,0 +1,202 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { AiConnection } from "../ai-connection";
+import { AiConnectionInput } from "../ai-connection.interface";
+
+// ---------------------------------------------------------------------------
+// Setup — the model resolves its JSON:API types through the real
+// ModuleRegistry, so both modules it names must be registered.
+// ---------------------------------------------------------------------------
+const aiConnectionModule: ApiRequestDataTypeInterface = {
+  name: "ai-connections",
+  model: AiConnection,
+} as any;
+
+const companyModule: ApiRequestDataTypeInterface = {
+  name: "companies",
+  model: class {},
+} as any;
+
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("AiConnection", aiConnectionModule);
+  registerIfAbsent("Company", companyModule);
+});
+
+function makeHydratedData(attributeOverrides: Record<string, any> = {}) {
+  return {
+    jsonApi: {
+      id: "connection-1",
+      type: "ai-connections",
+      attributes: {
+        name: "Primary OpenRouter",
+        connectionType: "ai",
+        provider: "openrouter",
+        position: 0,
+        enabled: true,
+        model: "anthropic/claude-sonnet-4",
+        url: "https://openrouter.ai/api/v1",
+        region: "eu",
+        instance: "my-instance",
+        apiVersion: "2024-08-01",
+        allowFallbacks: true,
+        reasoningEffort: "medium",
+        maxOutputTokens: 8192,
+        dimensions: 1536,
+        inputCostPer1MTokens: 3,
+        outputCostPer1MTokens: 15,
+        cachedInputCostPer1MTokens: 0.3,
+        costPerMinute: 0.02,
+        costPerPage: 0.05,
+        directUrl: "https://example.test/audio",
+        language: "en",
+        directFormat: "json",
+        directProvider: "groq",
+        hasApiKey: true,
+        hasGoogleCredentials: false,
+        companyId: "company-1",
+        ...attributeOverrides,
+      },
+      meta: {},
+      relationships: {},
+    },
+    included: [] as any[],
+  };
+}
+
+function makeInput(overrides: Partial<AiConnectionInput> = {}): AiConnectionInput {
+  return {
+    id: "connection-1",
+    name: "Primary OpenRouter",
+    connectionType: "ai",
+    provider: "openrouter",
+    position: 0,
+    enabled: true,
+    model: "anthropic/claude-sonnet-4",
+    ...overrides,
+  };
+}
+
+describe("AiConnection.rehydrate", () => {
+  it("maps every serialized attribute, including the secret presence flags", () => {
+    const connection = new AiConnection().rehydrate(makeHydratedData());
+
+    expect(connection.id).toBe("connection-1");
+    expect(connection.type).toBe("ai-connections");
+    expect(connection.name).toBe("Primary OpenRouter");
+    expect(connection.connectionType).toBe("ai");
+    expect(connection.provider).toBe("openrouter");
+    expect(connection.position).toBe(0);
+    expect(connection.enabled).toBe(true);
+    expect(connection.model).toBe("anthropic/claude-sonnet-4");
+    expect(connection.url).toBe("https://openrouter.ai/api/v1");
+    expect(connection.region).toBe("eu");
+    expect(connection.instance).toBe("my-instance");
+    expect(connection.apiVersion).toBe("2024-08-01");
+    expect(connection.allowFallbacks).toBe(true);
+    expect(connection.reasoningEffort).toBe("medium");
+    expect(connection.maxOutputTokens).toBe(8192);
+    expect(connection.dimensions).toBe(1536);
+    expect(connection.inputCostPer1MTokens).toBe(3);
+    expect(connection.outputCostPer1MTokens).toBe(15);
+    expect(connection.cachedInputCostPer1MTokens).toBe(0.3);
+    expect(connection.costPerMinute).toBe(0.02);
+    expect(connection.costPerPage).toBe(0.05);
+    expect(connection.directUrl).toBe("https://example.test/audio");
+    expect(connection.language).toBe("en");
+    expect(connection.directFormat).toBe("json");
+    expect(connection.directProvider).toBe("groq");
+    expect(connection.hasApiKey).toBe(true);
+    expect(connection.hasGoogleCredentials).toBe(false);
+    expect(connection.companyId).toBe("company-1");
+  });
+
+  it("treats a missing companyId as a global connection and defaults the flags", () => {
+    const connection = new AiConnection().rehydrate(
+      makeHydratedData({ companyId: undefined, hasApiKey: undefined, hasGoogleCredentials: undefined }),
+    );
+
+    expect(connection.companyId).toBeUndefined();
+    expect(connection.hasApiKey).toBe(false);
+    expect(connection.hasGoogleCredentials).toBe(false);
+  });
+});
+
+describe("AiConnection.createJsonApi", () => {
+  it("serializes the non-secret attributes under the ai-connections type", () => {
+    const payload = new AiConnection().createJsonApi(makeInput());
+
+    expect(payload.data.type).toBe("ai-connections");
+    expect(payload.data.id).toBe("connection-1");
+    expect(payload.data.attributes.name).toBe("Primary OpenRouter");
+    expect(payload.data.attributes.connectionType).toBe("ai");
+    expect(payload.data.attributes.provider).toBe("openrouter");
+    expect(payload.data.attributes.position).toBe(0);
+    expect(payload.data.attributes.enabled).toBe(true);
+    expect(payload.data.attributes.model).toBe("anthropic/claude-sonnet-4");
+    // Undefined optional attributes must not be emitted at all.
+    expect("url" in payload.data.attributes).toBe(false);
+  });
+
+  it("omits the secrets when they are undefined", () => {
+    const payload = new AiConnection().createJsonApi(makeInput());
+
+    expect("apiKey" in payload.data.attributes).toBe(false);
+    expect("googleCredentialsBase64" in payload.data.attributes).toBe(false);
+  });
+
+  it('omits the secrets when they are "" — blank means keep the stored value', () => {
+    const payload = new AiConnection().createJsonApi(makeInput({ apiKey: "", googleCredentialsBase64: "" }));
+
+    expect("apiKey" in payload.data.attributes).toBe(false);
+    expect("googleCredentialsBase64" in payload.data.attributes).toBe(false);
+  });
+
+  it("includes the secrets when they carry a value", () => {
+    const payload = new AiConnection().createJsonApi(
+      makeInput({ apiKey: "sk-secret", googleCredentialsBase64: "Z29vZ2xl" }),
+    );
+
+    expect(payload.data.attributes.apiKey).toBe("sk-secret");
+    expect(payload.data.attributes.googleCredentialsBase64).toBe("Z29vZ2xl");
+  });
+
+  it("sets the company relationship only when companyId is present", () => {
+    const global = new AiConnection().createJsonApi(makeInput());
+    expect(global.data.relationships.company).toBeUndefined();
+
+    const scoped = new AiConnection().createJsonApi(makeInput({ companyId: "company-1" }));
+    expect(scoped.data.relationships.company).toEqual({
+      data: { type: "companies", id: "company-1" },
+    });
+  });
+
+  it("keeps falsy-but-meaningful values", () => {
+    const payload = new AiConnection().createJsonApi(makeInput({ enabled: false, position: 0, maxOutputTokens: 0 }));
+
+    expect(payload.data.attributes.enabled).toBe(false);
+    expect(payload.data.attributes.position).toBe(0);
+    expect(payload.data.attributes.maxOutputTokens).toBe(0);
+  });
+});
+
+describe("AiConnection.createReorderJsonApi", () => {
+  it("produces the reorder body the backend expects", () => {
+    const payload = new AiConnection().createReorderJsonApi({ ids: ["a", "b", "c"] });
+
+    expect(payload).toEqual({
+      data: {
+        type: "ai-connections",
+        ids: ["a", "b", "c"],
+      },
+    });
+  });
+});

package/src/features/ai-connection/data/ai-connection.fields.ts

@@ -0,0 +1,6 @@
+export enum AiConnectionFields {
+  name = "name",
+  provider = "provider",
+  model = "model",
+  enabled = "enabled",
+}

package/src/features/ai-connection/data/ai-connection.interface.ts

@@ -0,0 +1,87 @@
+import { ApiDataInterface } from "../../../core";
+
+/**
+ * One editable field of a provider, as described by the backend provider
+ * registry (`AI_PROVIDER_REGISTRY`, served as top-level JSON:API `meta` on the
+ * list endpoint). The registry carries structure only — never display text:
+ * the editor derives its i18n keys from `field`.
+ */
+export interface AiProviderFieldDescriptor {
+  field: string;
+  kind: "text" | "secret" | "number" | "boolean" | "select";
+  required?: boolean;
+  options?: string[];
+  default?: string | number | boolean;
+}
+
+/** `meta.providerRegistry`: connection type → the providers allowed for it. */
+export type AiProviderRegistry = Record<string, { provider: string; fields: AiProviderFieldDescriptor[] }[]>;
+
+/**
+ * `meta.envDefaults`: connection type → the `.env` block that always closes the
+ * chain. Secrets are never included.
+ */
+export type AiConnectionEnvDefaults = Record<string, { provider?: string; model?: string; url?: string }>;
+
+export interface AiConnectionInterface extends ApiDataInterface {
+  get name(): string;
+  get connectionType(): string;
+  get provider(): string;
+  get position(): number;
+  get enabled(): boolean;
+  get model(): string | undefined;
+  get url(): string | undefined;
+  get region(): string | undefined;
+  get instance(): string | undefined;
+  get apiVersion(): string | undefined;
+  get allowFallbacks(): boolean | undefined;
+  get reasoningEffort(): string | undefined;
+  get maxOutputTokens(): number | undefined;
+  get dimensions(): number | undefined;
+  get inputCostPer1MTokens(): number | undefined;
+  get outputCostPer1MTokens(): number | undefined;
+  get cachedInputCostPer1MTokens(): number | undefined;
+  get costPerMinute(): number | undefined;
+  get costPerPage(): number | undefined;
+  get directUrl(): string | undefined;
+  get language(): string | undefined;
+  get directFormat(): string | undefined;
+  get directProvider(): string | undefined;
+  /** Secrets are never serialised — the API returns presence flags instead. */
+  get hasApiKey(): boolean;
+  get hasGoogleCredentials(): boolean;
+  /** Absent = a global connection; set = scoped to that company. */
+  get companyId(): string | undefined;
+}
+
+export type AiConnectionInput = {
+  id: string;
+  name: string;
+  connectionType: string;
+  provider: string;
+  position: number;
+  enabled: boolean;
+  model?: string;
+  url?: string;
+  /** Secrets: omit or send "" to keep the stored value on update. */
+  apiKey?: string;
+  googleCredentialsBase64?: string;
+  region?: string;
+  instance?: string;
+  apiVersion?: string;
+  allowFallbacks?: boolean;
+  reasoningEffort?: string;
+  maxOutputTokens?: number;
+  dimensions?: number;
+  inputCostPer1MTokens?: number;
+  outputCostPer1MTokens?: number;
+  cachedInputCostPer1MTokens?: number;
+  costPerMinute?: number;
+  costPerPage?: number;
+  directUrl?: string;
+  language?: string;
+  directFormat?: string;
+  directProvider?: string;
+  /** Set on creation only — scope is immutable thereafter. */
+  companyId?: string;
+};

package/src/features/ai-connection/data/ai-connection.service.ts

@@ -0,0 +1,90 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { AiConnection } from "./ai-connection";
+import {
+  AiConnectionEnvDefaults,
+  AiConnectionInput,
+  AiConnectionInterface,
+  AiProviderRegistry,
+} from "./ai-connection.interface";
+
+export class AiConnectionService extends AbstractService {
+  /**
+   * Full list plus the editor meta in one round-trip: the list endpoint carries
+   * the provider registry and the `.env` defaults as top-level JSON:API `meta`.
+   */
+  static async listConnections(): Promise<{
+    connections: AiConnectionInterface[];
+    providerRegistry: AiProviderRegistry;
+    envDefaults: AiConnectionEnvDefaults;
+  }> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.AiConnection });
+    endpoint.addAdditionalParam("fetchAll", "true");
+
+    const { data, meta } = await this.callApiWithMeta<AiConnectionInterface[]>({
+      type: Modules.AiConnection,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+
+    return {
+      connections: data ?? [],
+      providerRegistry: (meta?.providerRegistry ?? {}) as AiProviderRegistry,
+      envDefaults: (meta?.envDefaults ?? {}) as AiConnectionEnvDefaults,
+    };
+  }
+
+  /**
+   * Create a connection. The optional `companyId` fixes its scope forever.
+   */
+  static async create(params: AiConnectionInput): Promise<AiConnectionInterface> {
+    return this.callApi<AiConnectionInterface>({
+      type: Modules.AiConnection,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.AiConnection }).generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * Update a connection. Blank/omitted secrets keep the stored values.
+   */
+  static async update(params: AiConnectionInput): Promise<AiConnectionInterface> {
+    return this.callApi<AiConnectionInterface>({
+      type: Modules.AiConnection,
+      method: HttpMethod.PUT,
+      endpoint: new EndpointCreator({ endpoint: Modules.AiConnection, id: params.id }).generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * Delete a connection.
+   */
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.AiConnection,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.AiConnection, id: params.id }).generate(),
+    });
+  }
+
+  /**
+   * Reorder one chain: the ordered id list is renumbered 0..n-1 server-side.
+   * Dedicated model method + `overridesJsonApiCreation` — the sanctioned
+   * pairing, never a hand-built payload here.
+   */
+  static async reorder(params: { ids: string[] }): Promise<void> {
+    const model = new AiConnection();
+
+    await this.callApi({
+      type: Modules.AiConnection,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.AiConnection,
+        childEndpoint: "reorder",
+      }).generate(),
+      input: model.createReorderJsonApi({ ids: params.ids }),
+      overridesJsonApiCreation: true, // OK — the model method provides the structure
+    });
+  }
+}

package/src/features/ai-connection/data/ai-connection.ts

@@ -0,0 +1,244 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { AiConnectionInput, AiConnectionInterface } from "./ai-connection.interface";
+
+export class AiConnection extends AbstractApiData implements AiConnectionInterface {
+  private _name?: string;
+  private _connectionType?: string;
+  private _provider?: string;
+  private _position?: number;
+  private _enabled?: boolean;
+  private _model?: string;
+  private _url?: string;
+  private _region?: string;
+  private _instance?: string;
+  private _apiVersion?: string;
+  private _allowFallbacks?: boolean;
+  private _reasoningEffort?: string;
+  private _maxOutputTokens?: number;
+  private _dimensions?: number;
+  private _inputCostPer1MTokens?: number;
+  private _outputCostPer1MTokens?: number;
+  private _cachedInputCostPer1MTokens?: number;
+  private _costPerMinute?: number;
+  private _costPerPage?: number;
+  private _directUrl?: string;
+  private _language?: string;
+  private _directFormat?: string;
+  private _directProvider?: string;
+  private _hasApiKey?: boolean;
+  private _hasGoogleCredentials?: boolean;
+  private _companyId?: string;
+
+  get name(): string {
+    return this._name ?? "";
+  }
+
+  get connectionType(): string {
+    return this._connectionType ?? "";
+  }
+
+  get provider(): string {
+    return this._provider ?? "";
+  }
+
+  get position(): number {
+    return this._position ?? 0;
+  }
+
+  get enabled(): boolean {
+    return this._enabled ?? true;
+  }
+
+  get model(): string | undefined {
+    return this._model;
+  }
+
+  get url(): string | undefined {
+    return this._url;
+  }
+
+  get region(): string | undefined {
+    return this._region;
+  }
+
+  get instance(): string | undefined {
+    return this._instance;
+  }
+
+  get apiVersion(): string | undefined {
+    return this._apiVersion;
+  }
+
+  get allowFallbacks(): boolean | undefined {
+    return this._allowFallbacks;
+  }
+
+  get reasoningEffort(): string | undefined {
+    return this._reasoningEffort;
+  }
+
+  get maxOutputTokens(): number | undefined {
+    return this._maxOutputTokens;
+  }
+
+  get dimensions(): number | undefined {
+    return this._dimensions;
+  }
+
+  get inputCostPer1MTokens(): number | undefined {
+    return this._inputCostPer1MTokens;
+  }
+
+  get outputCostPer1MTokens(): number | undefined {
+    return this._outputCostPer1MTokens;
+  }
+
+  get cachedInputCostPer1MTokens(): number | undefined {
+    return this._cachedInputCostPer1MTokens;
+  }
+
+  get costPerMinute(): number | undefined {
+    return this._costPerMinute;
+  }
+
+  get costPerPage(): number | undefined {
+    return this._costPerPage;
+  }
+
+  get directUrl(): string | undefined {
+    return this._directUrl;
+  }
+
+  get language(): string | undefined {
+    return this._language;
+  }
+
+  get directFormat(): string | undefined {
+    return this._directFormat;
+  }
+
+  get directProvider(): string | undefined {
+    return this._directProvider;
+  }
+
+  get hasApiKey(): boolean {
+    return this._hasApiKey ?? false;
+  }
+
+  get hasGoogleCredentials(): boolean {
+    return this._hasGoogleCredentials ?? false;
+  }
+
+  get companyId(): string | undefined {
+    return this._companyId;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes ?? {};
+
+    this._name = attributes.name;
+    this._connectionType = attributes.connectionType;
+    this._provider = attributes.provider;
+    this._position = attributes.position;
+    this._enabled = attributes.enabled;
+    this._model = attributes.model;
+    this._url = attributes.url;
+    this._region = attributes.region;
+    this._instance = attributes.instance;
+    this._apiVersion = attributes.apiVersion;
+    this._allowFallbacks = attributes.allowFallbacks;
+    this._reasoningEffort = attributes.reasoningEffort;
+    this._maxOutputTokens = attributes.maxOutputTokens;
+    this._dimensions = attributes.dimensions;
+    this._inputCostPer1MTokens = attributes.inputCostPer1MTokens;
+    this._outputCostPer1MTokens = attributes.outputCostPer1MTokens;
+    this._cachedInputCostPer1MTokens = attributes.cachedInputCostPer1MTokens;
+    this._costPerMinute = attributes.costPerMinute;
+    this._costPerPage = attributes.costPerPage;
+    this._directUrl = attributes.directUrl;
+    this._language = attributes.language;
+    this._directFormat = attributes.directFormat;
+    this._directProvider = attributes.directProvider;
+    this._hasApiKey = attributes.hasApiKey;
+    this._hasGoogleCredentials = attributes.hasGoogleCredentials;
+    this._companyId = attributes.companyId;
+
+    return this;
+  }
+
+  createJsonApi(data: AiConnectionInput): any {
+    const response: any = {
+      data: {
+        type: Modules.AiConnection.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    const setIfDefined = (key: keyof AiConnectionInput) => {
+      if (data[key] !== undefined) response.data.attributes[key] = data[key];
+    };
+
+    (
+      [
+        "name",
+        "connectionType",
+        "provider",
+        "position",
+        "enabled",
+        "model",
+        "url",
+        "region",
+        "instance",
+        "apiVersion",
+        "allowFallbacks",
+        "reasoningEffort",
+        "maxOutputTokens",
+        "dimensions",
+        "inputCostPer1MTokens",
+        "outputCostPer1MTokens",
+        "cachedInputCostPer1MTokens",
+        "costPerMinute",
+        "costPerPage",
+        "directUrl",
+        "language",
+        "directFormat",
+        "directProvider",
+      ] as const
+    ).forEach(setIfDefined);
+
+    // Secrets: an empty string means "keep the stored value" — omit it from the
+    // payload entirely so the backend never overwrites what it already holds.
+    if (data.apiKey) response.data.attributes.apiKey = data.apiKey;
+    if (data.googleCredentialsBase64) {
+      response.data.attributes.googleCredentialsBase64 = data.googleCredentialsBase64;
+    }
+
+    // Scope is chosen at creation and immutable thereafter.
+    if (data.companyId) {
+      response.data.relationships.company = {
+        data: { type: Modules.Company.name, id: data.companyId },
+      };
+    }
+
+    return response;
+  }
+
+  /**
+   * Body for POST /ai-connections/reorder. A dedicated model method so the
+   * service never constructs a JSON:API payload itself — the sanctioned pairing
+   * for `overridesJsonApiCreation`.
+   */
+  createReorderJsonApi(params: { ids: string[] }): any {
+    return {
+      data: {
+        type: Modules.AiConnection.name,
+        ids: params.ids,
+      },
+    };
+  }
+}

package/src/features/ai-connection/data/index.ts

@@ -0,0 +1,4 @@
+export * from "./ai-connection";
+export * from "./ai-connection.fields";
+export * from "./ai-connection.interface";
+export * from "./ai-connection.service";