@carlonicora/nextjs-jsonapi 3.0.0 → 3.1.0

package/src/features/ai-connection/components/forms/AiConnectionEditor.tsx

@@ -0,0 +1,329 @@
+"use client";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useTranslations } from "next-intl";
+import { ReactNode, useCallback, useEffect, useMemo } from "react";
+import { useForm } from "react-hook-form";
+import { v4 } from "uuid";
+import { z } from "zod";
+import { EditorSheet, FormCheckbox, FormInput, FormPassword, FormSelect, MicroLabel } from "../../../../components";
+import { Modules } from "../../../../core";
+import { Alert, AlertDescription, AlertTitle } from "../../../../shadcnui";
+import { AiConnectionInput, AiConnectionInterface, AiConnectionService, AiProviderFieldDescriptor } from "../../data";
+import { useAiConnections } from "../../contexts/AiConnectionsContext";
+
+/** Fields grouped under the collapsed-by-convention cost block (spec § 4). */
+const COST_FIELDS = [
+  "inputCostPer1MTokens",
+  "outputCostPer1MTokens",
+  "cachedInputCostPer1MTokens",
+  "costPerMinute",
+  "costPerPage",
+];
+
+type AiConnectionFormValues = {
+  id: string;
+  name: string;
+  provider: string;
+  enabled: boolean;
+  /** Every provider-specific field, keyed by the registry's field id. */
+  values: Record<string, any>;
+};
+
+export type AiConnectionEditorProps = {
+  /** Omitted in create mode. */
+  connection?: AiConnectionInterface;
+  /** Fixed by the card that owns the editor — never editable. */
+  connectionType: string;
+  /** Slot in the chain. Fixed: reordering is the up/down arrows' job. */
+  position: number;
+  /** Scope, set on creation only — immutable thereafter (spec § Decisions). */
+  companyId?: string;
+  trigger?: ReactNode;
+  forceShow?: boolean;
+  onClose?: () => void;
+};
+
+/**
+ * Schema-driven editor for one link in a fallback chain.
+ *
+ * The static half of the form (name / provider / enabled) is a fixed zod shape;
+ * everything else is rendered blind from `meta.providerRegistry`, so a new
+ * provider field on the backend needs no change here — only an i18n string.
+ * Required-ness is enforced by a `superRefine` over the same registry, which
+ * keeps failures inline on the field instead of an error toast. The backend
+ * re-validates authoritatively.
+ */
+export function AiConnectionEditor({
+  connection,
+  connectionType,
+  position,
+  companyId,
+  trigger,
+  forceShow,
+  onClose,
+}: AiConnectionEditorProps) {
+  const t = useTranslations();
+  const { providerRegistry, refresh } = useAiConnections();
+  const isEdit = !!connection;
+
+  const registryRows = useMemo(() => providerRegistry[connectionType] ?? [], [providerRegistry, connectionType]);
+  const providers = useMemo(() => registryRows.map((row) => row.provider), [registryRows]);
+
+  const fieldsFor = useCallback(
+    (provider: string): AiProviderFieldDescriptor[] =>
+      registryRows.find((row) => row.provider === provider)?.fields ?? [],
+    [registryRows],
+  );
+
+  /** Seeds the `values` map for a provider: stored value → registry default → empty. */
+  const defaultsFor = useCallback(
+    (provider: string): Record<string, any> => {
+      const stored = connection as unknown as Record<string, unknown> | undefined;
+      const seeded: Record<string, any> = {};
+
+      fieldsFor(provider).forEach((descriptor) => {
+        if (descriptor.kind === "boolean") {
+          const current = stored?.[descriptor.field];
+          seeded[descriptor.field] =
+            current !== undefined && current !== null ? current === true : descriptor.default === true;
+          return;
+        }
+
+        // Secrets are write-only: the API answers with a has-flag, never a value.
+        if (descriptor.kind === "secret") {
+          seeded[descriptor.field] = "";
+          return;
+        }
+
+        const current = stored?.[descriptor.field];
+        if (current !== undefined && current !== null) seeded[descriptor.field] = String(current);
+        else seeded[descriptor.field] = descriptor.default !== undefined ? String(descriptor.default) : "";
+      });
+
+      return seeded;
+    },
+    [connection, fieldsFor],
+  );
+
+  const hasStoredSecret = useCallback(
+    (field: string) => {
+      if (!connection) return false;
+      if (field === "apiKey") return connection.hasApiKey;
+      if (field === "googleCredentialsBase64") return connection.hasGoogleCredentials;
+      return false;
+    },
+    [connection],
+  );
+
+  const formSchema = useMemo(
+    () =>
+      z
+        .object({
+          id: z.uuidv4(),
+          name: z.string().min(1, { message: t("ai_connections.admin.errors.name") }),
+          provider: z.string().min(1, { message: t("ai_connections.admin.errors.required_field") }),
+          enabled: z.boolean(),
+          values: z.record(z.string(), z.any()),
+        })
+        .superRefine((data, ctx) => {
+          fieldsFor(data.provider)
+            .filter((descriptor) => descriptor.required)
+            .forEach((descriptor) => {
+              const value = data.values?.[descriptor.field];
+              // A stored secret counts as filled: blank means "keep it".
+              const filled =
+                descriptor.kind === "secret"
+                  ? !!value || hasStoredSecret(descriptor.field)
+                  : descriptor.kind === "boolean"
+                    ? value !== undefined
+                    : value !== undefined && value !== null && String(value).trim() !== "";
+              if (filled) return;
+              ctx.addIssue({
+                code: "custom",
+                message: t("ai_connections.admin.errors.required_field"),
+                path: ["values", descriptor.field],
+              });
+            });
+        }),
+    [t, fieldsFor, hasStoredSecret],
+  );
+
+  const getDefaultValues = useCallback(
+    (): AiConnectionFormValues => ({
+      id: connection?.id ?? v4(),
+      name: connection?.name ?? "",
+      provider: connection?.provider ?? providers[0] ?? "",
+      enabled: connection?.enabled ?? true,
+      values: defaultsFor(connection?.provider ?? providers[0] ?? ""),
+    }),
+    [connection, providers, defaultsFor],
+  );
+
+  const form = useForm<AiConnectionFormValues>({
+    resolver: zodResolver(formSchema),
+    defaultValues: getDefaultValues(),
+  });
+
+  // The registry arrives with the list request, which can resolve after this
+  // component mounts — so the provider and its field map are seeded again once
+  // it is available. Pre-filling via setValue is the supported create-mode
+  // pattern (EditorSheet re-seeds only on edit; see EditorSheet.tsx:163-190).
+  useEffect(() => {
+    if (registryRows.length === 0) return;
+
+    const currentProvider = form.getValues("provider");
+    const provider = currentProvider || connection?.provider || providers[0] || "";
+    if (!provider) return;
+    if (provider !== currentProvider) form.setValue("provider", provider);
+
+    const currentValues = form.getValues("values");
+    if (!currentValues || Object.keys(currentValues).length === 0) form.setValue("values", defaultsFor(provider));
+    // Deliberately keyed on the registry alone: re-running on `form` identity
+    // would clobber what the user has typed.
+  }, [registryRows]);
+
+  const selectedProvider = form.watch("provider");
+  const selectedFields = fieldsFor(selectedProvider);
+  const configFields = selectedFields.filter((descriptor) => !COST_FIELDS.includes(descriptor.field));
+  const costFields = selectedFields.filter((descriptor) => COST_FIELDS.includes(descriptor.field));
+
+  /** Registry value → wire value. Numbers arrive from the input as strings. */
+  const coerce = (descriptor: AiProviderFieldDescriptor, raw: any) => {
+    if (descriptor.kind === "boolean") return raw === true;
+    if (raw === undefined || raw === null || String(raw).trim() === "") return undefined;
+    if (descriptor.kind === "number") {
+      const parsed = Number(String(raw).replace(",", "."));
+      return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return String(raw);
+  };
+
+  const renderField = (descriptor: AiProviderFieldDescriptor) => {
+    const id = `values.${descriptor.field}`;
+    const label = t(`ai_connections.admin.fields.${descriptor.field}`);
+
+    switch (descriptor.kind) {
+      case "secret":
+        return (
+          <FormPassword
+            key={descriptor.field}
+            form={form}
+            id={id}
+            name={label}
+            isRequired={descriptor.required}
+            placeholder={
+              isEdit && hasStoredSecret(descriptor.field)
+                ? t("ai_connections.admin.placeholders.secret_unchanged")
+                : undefined
+            }
+          />
+        );
+      case "boolean":
+        return <FormCheckbox key={descriptor.field} form={form} id={id} name={label} />;
+      case "select":
+        return (
+          <FormSelect
+            key={descriptor.field}
+            form={form}
+            id={id}
+            name={label}
+            isRequired={descriptor.required}
+            allowEmpty={!descriptor.required}
+            values={(descriptor.options ?? []).map((option) => ({ id: option, text: option }))}
+          />
+        );
+      case "number":
+        // "decimal", not "number": FormInput's number mode strips everything but
+        // digits, which would make a cost of 0.15 unrepresentable.
+        return (
+          <FormInput
+            key={descriptor.field}
+            form={form}
+            id={id}
+            name={label}
+            type="decimal"
+            isRequired={descriptor.required}
+          />
+        );
+      default:
+        return <FormInput key={descriptor.field} form={form} id={id} name={label} isRequired={descriptor.required} />;
+    }
+  };
+
+  return (
+    <EditorSheet
+      form={form}
+      entityType={t("ai_connections.admin.entity")}
+      entityName={connection?.name}
+      isEdit={isEdit}
+      module={Modules.AiConnection}
+      size="md"
+      onSuccess={refresh}
+      onSubmit={async (values) => {
+        const attributes: Record<string, unknown> = {};
+        fieldsFor(values.provider).forEach((descriptor) => {
+          const coerced = coerce(descriptor, values.values?.[descriptor.field]);
+          if (coerced !== undefined) attributes[descriptor.field] = coerced;
+        });
+
+        const payload = {
+          id: values.id,
+          name: values.name,
+          connectionType,
+          provider: values.provider,
+          position,
+          enabled: values.enabled,
+          ...attributes,
+          // Scope is fixed at creation; sending it on update would be a no-op at
+          // best and a scope change at worst, which the design forbids.
+          ...(isEdit || !companyId ? {} : { companyId }),
+        } as AiConnectionInput;
+
+        if (isEdit) await AiConnectionService.update(payload);
+        else await AiConnectionService.create(payload);
+      }}
+      onReset={getDefaultValues}
+      trigger={trigger}
+      forceShow={forceShow}
+      onClose={onClose}
+    >
+      <div className="flex w-full flex-col gap-y-4">
+        {connectionType === "embedder" && (
+          <Alert variant="destructive">
+            <AlertTitle>{t("ai_connections.admin.embedder_warning.title")}</AlertTitle>
+            <AlertDescription>{t("ai_connections.admin.embedder_warning.description")}</AlertDescription>
+          </Alert>
+        )}
+
+        <FormInput
+          form={form}
+          id="name"
+          name={t("ai_connections.admin.fields.name")}
+          placeholder={t("ai_connections.admin.placeholders.name")}
+          isRequired
+        />
+
+        <FormSelect
+          form={form}
+          id="provider"
+          name={t("ai_connections.admin.fields.provider")}
+          isRequired
+          values={providers.map((provider) => ({ id: provider, text: provider }))}
+          onChange={(provider) => form.setValue("values", defaultsFor(provider))}
+        />
+
+        <FormCheckbox form={form} id="enabled" name={t("ai_connections.admin.fields.enabled")} />
+
+        {configFields.map(renderField)}
+
+        {costFields.length > 0 && (
+          <div className="flex w-full flex-col gap-y-4">
+            <MicroLabel>{t("ai_connections.admin.fields.costs_section")}</MicroLabel>
+            {costFields.map(renderField)}
+          </div>
+        )}
+      </div>
+    </EditorSheet>
+  );
+}

package/src/features/ai-connection/components/lists/AiConnectionTypeCard.tsx

@@ -0,0 +1,223 @@
+"use client";
+
+import { ChevronDownIcon, ChevronUpIcon, PlusIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { SectionHeader } from "../../../../components";
+import { errorToast } from "../../../../components/errors";
+import { Badge, Button, Card, CardAction, CardContent, CardHeader, EmptyState, Switch } from "../../../../shadcnui";
+import { cn } from "../../../../utils";
+import { AiConnectionInput, AiConnectionInterface, AiConnectionService } from "../../data";
+import { useAiConnections } from "../../contexts/AiConnectionsContext";
+import { AiConnectionDeleter } from "../forms/AiConnectionDeleter";
+import { AiConnectionEditor } from "../forms/AiConnectionEditor";
+
+/**
+ * Rebuilds the full write payload for an existing connection.
+ *
+ * Every mutation goes through the model (AiConnectionService.update →
+ * AiConnection.createJsonApi), so an inline toggle has to resend the row's
+ * current attributes rather than patch a single one. Secrets are deliberately
+ * absent: an omitted secret means "keep the stored value" (spec § Decisions),
+ * and the API never serialises them back in the first place.
+ */
+function toInput(connection: AiConnectionInterface, overrides: Partial<AiConnectionInput>): AiConnectionInput {
+  return {
+    id: connection.id,
+    name: connection.name,
+    connectionType: connection.connectionType,
+    provider: connection.provider,
+    position: connection.position,
+    enabled: connection.enabled,
+    model: connection.model,
+    url: connection.url,
+    region: connection.region,
+    instance: connection.instance,
+    apiVersion: connection.apiVersion,
+    allowFallbacks: connection.allowFallbacks,
+    reasoningEffort: connection.reasoningEffort,
+    maxOutputTokens: connection.maxOutputTokens,
+    dimensions: connection.dimensions,
+    inputCostPer1MTokens: connection.inputCostPer1MTokens,
+    outputCostPer1MTokens: connection.outputCostPer1MTokens,
+    cachedInputCostPer1MTokens: connection.cachedInputCostPer1MTokens,
+    costPerMinute: connection.costPerMinute,
+    costPerPage: connection.costPerPage,
+    directUrl: connection.directUrl,
+    language: connection.language,
+    directFormat: connection.directFormat,
+    directProvider: connection.directProvider,
+    ...overrides,
+  };
+}
+
+export type AiConnectionTypeCardProps = {
+  /** One of the eight AI connection types — also the card's heading key. */
+  connectionType: string;
+};
+
+/**
+ * One fallback chain, for one connection type, in the currently selected scope.
+ *
+ * The chain always ends with a read-only ".env fallback" row: the env block is
+ * the last candidate the resolver tries, so showing it keeps the page an honest
+ * picture of what a call will actually do (spec § 4).
+ */
+export function AiConnectionTypeCard({ connectionType }: AiConnectionTypeCardProps) {
+  const t = useTranslations();
+  const { connections, envDefaults, scopeCompanyId, refresh } = useAiConnections();
+
+  const rows = useMemo(
+    () =>
+      connections
+        .filter(
+          (connection) =>
+            connection.connectionType === connectionType &&
+            (scopeCompanyId ? connection.companyId === scopeCompanyId : !connection.companyId),
+        )
+        .sort((a, b) => a.position - b.position),
+    [connections, connectionType, scopeCompanyId],
+  );
+
+  // Shown greyed-out under the "inheriting global chain" hint when a company
+  // scope has no chain of its own for this type.
+  const globalRows = useMemo(
+    () =>
+      connections
+        .filter((connection) => connection.connectionType === connectionType && !connection.companyId)
+        .sort((a, b) => a.position - b.position),
+    [connections, connectionType],
+  );
+
+  const inheritsGlobal = !!scopeCompanyId && rows.length === 0;
+  const envDefault = envDefaults[connectionType];
+  const typeLabel = t(`ai_connections.admin.types.${connectionType}`);
+
+  const setEnabled = async (connection: AiConnectionInterface, enabled: boolean) => {
+    try {
+      await AiConnectionService.update(toInput(connection, { enabled }));
+      await refresh();
+    } catch (error) {
+      errorToast({ title: typeLabel, error });
+    }
+  };
+
+  /** Moves a row by one slot and renumbers the whole chain server-side. */
+  const move = async (index: number, delta: number) => {
+    const target = index + delta;
+    if (target < 0 || target >= rows.length) return;
+    const reordered = [...rows];
+    const [moved] = reordered.splice(index, 1);
+    reordered.splice(target, 0, moved);
+    try {
+      await AiConnectionService.reorder({ ids: reordered.map((connection) => connection.id) });
+      await refresh();
+    } catch (error) {
+      errorToast({ title: typeLabel, error });
+    }
+  };
+
+  const renderRow = (connection: AiConnectionInterface, index: number, readOnly: boolean, total: number) => (
+    <div
+      key={connection.id}
+      className={cn("flex items-center gap-3 px-3 py-2", readOnly && "opacity-50")}
+      data-testid={`ai-connection-row-${connection.id}`}
+    >
+      <span className="text-muted-foreground w-5 text-right text-xs tabular-nums">{index + 1}</span>
+      <div className="flex min-w-0 flex-1 flex-col">
+        <span className="truncate text-sm">{connection.name}</span>
+        <span className="text-muted-foreground truncate text-xs">
+          {[connection.provider, connection.model].filter(Boolean).join(" · ")}
+        </span>
+      </div>
+      <Switch
+        checked={connection.enabled}
+        disabled={readOnly}
+        aria-label={t("ai_connections.admin.fields.enabled")}
+        onCheckedChange={(checked) => {
+          if (!readOnly) void setEnabled(connection, checked === true);
+        }}
+      />
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        className="text-muted-foreground"
+        aria-label={t("ai_connections.admin.reorder.up")}
+        disabled={readOnly || index === 0}
+        onClick={() => void move(index, -1)}
+      >
+        <ChevronUpIcon />
+      </Button>
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        className="text-muted-foreground"
+        aria-label={t("ai_connections.admin.reorder.down")}
+        disabled={readOnly || index === total - 1}
+        onClick={() => void move(index, 1)}
+      >
+        <ChevronDownIcon />
+      </Button>
+      {!readOnly && (
+        <>
+          <AiConnectionEditor
+            connection={connection}
+            connectionType={connectionType}
+            position={connection.position}
+            companyId={connection.companyId}
+          />
+          <AiConnectionDeleter connection={connection} />
+        </>
+      )}
+    </div>
+  );
+
+  return (
+    <Card>
+      <CardHeader>
+        <SectionHeader>{typeLabel}</SectionHeader>
+        <CardAction>
+          <AiConnectionEditor
+            connectionType={connectionType}
+            position={rows.length}
+            companyId={scopeCompanyId ?? undefined}
+            trigger={
+              <Button variant="outline" size="sm">
+                <PlusIcon />
+                {t("ai_connections.admin.create")}
+              </Button>
+            }
+          />
+        </CardAction>
+      </CardHeader>
+      <CardContent>
+        {inheritsGlobal && (
+          <p className="text-muted-foreground mb-2 text-xs">{t("ai_connections.admin.scope.inherits_global")}</p>
+        )}
+
+        <div className="divide-border flex flex-col divide-y rounded-md border">
+          {inheritsGlobal
+            ? globalRows.map((connection, index) => renderRow(connection, index, true, globalRows.length))
+            : rows.map((connection, index) => renderRow(connection, index, false, rows.length))}
+
+          {!inheritsGlobal && rows.length === 0 && (
+            <EmptyState
+              className="p-3"
+              title={t("ai_connections.admin.empty.title")}
+              description={t("ai_connections.admin.empty.description")}
+            />
+          )}
+
+          {/* The env block is always the last candidate the resolver tries, so
+              it always closes the chain — read-only, with no controls. */}
+          <div className="bg-muted/40 flex flex-wrap items-center gap-2 px-3 py-2">
+            <Badge variant="softGray">{t("ai_connections.admin.env_fallback")}</Badge>
+            <span className="text-muted-foreground truncate text-xs">
+              {[envDefault?.provider, envDefault?.model, envDefault?.url].filter(Boolean).join(" · ")}
+            </span>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

package/src/features/ai-connection/contexts/AiConnectionsContext.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { SharedProvider } from "../../../contexts";
+import { usePageUrlGenerator } from "../../../hooks";
+import { BreadcrumbItemData } from "../../../interfaces";
+import { AiConnectionEnvDefaults, AiConnectionInterface, AiConnectionService, AiProviderRegistry } from "../data";
+
+/**
+ * Route the breadcrumb links back to. Constant rather than a prop for the same
+ * reason TOKEN_USAGE_ADMIN_PAGE_URL is
+ * (features/tokenusage/contexts/TokenUsageAdminContext.tsx): the breadcrumb is
+ * built here, not by the consuming app, and the path convention IS the contract.
+ */
+export const AI_CONNECTIONS_ADMIN_PAGE_URL = "/administration/ai-connections";
+
+export interface AiConnectionsContextType {
+  /** Every connection, both scopes — the cards filter per scope themselves. */
+  connections: AiConnectionInterface[];
+  /** `meta.providerRegistry` from the list endpoint: connectionType → provider rows. */
+  providerRegistry: AiProviderRegistry;
+  /** `meta.envDefaults` from the list endpoint: the read-only final chain link. */
+  envDefaults: AiConnectionEnvDefaults;
+  /** `null` = the global chain; a company id = that company's chain. */
+  scopeCompanyId: string | null;
+  setScopeCompanyId: (companyId: string | null) => void;
+  /** Re-reads the whole list. Called after every mutation. */
+  refresh: () => Promise<void>;
+  isLoading: boolean;
+}
+
+const defaultContextValue: AiConnectionsContextType = {
+  connections: [],
+  providerRegistry: {},
+  envDefaults: {},
+  scopeCompanyId: null,
+  setScopeCompanyId: () => {},
+  refresh: async () => {},
+  isLoading: false,
+};
+
+const AiConnectionsContext = createContext<AiConnectionsContextType | undefined>(undefined);
+
+export type AiConnectionsProviderProps = {
+  children: ReactNode;
+};
+
+/**
+ * Owns the single list request behind the AI-connections admin page and the
+ * scope the page is looking at.
+ *
+ * It also publishes the page chrome, exactly as TokenUsageAdminContext does:
+ * RoundPageContainerTitle and the header breadcrumb read `useSharedContext()`,
+ * and that value is supplied far up the tree — a page that publishes nothing
+ * silently inherits the previous page's title.
+ */
+export const AiConnectionsProvider = ({ children }: AiConnectionsProviderProps) => {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const [connections, setConnections] = useState<AiConnectionInterface[]>([]);
+  const [providerRegistry, setProviderRegistry] = useState<AiProviderRegistry>({});
+  const [envDefaults, setEnvDefaults] = useState<AiConnectionEnvDefaults>({});
+  const [scopeCompanyId, setScopeCompanyId] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+
+  const refresh = useCallback(async () => {
+    setIsLoading(true);
+    try {
+      const response = await AiConnectionService.listConnections();
+      setConnections(response.connections);
+      setProviderRegistry(response.providerRegistry);
+      setEnvDefaults(response.envDefaults);
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const value = useMemo<AiConnectionsContextType>(
+    () => ({
+      connections,
+      providerRegistry,
+      envDefaults,
+      scopeCompanyId,
+      setScopeCompanyId,
+      refresh,
+      isLoading,
+    }),
+    [connections, providerRegistry, envDefaults, scopeCompanyId, refresh, isLoading],
+  );
+
+  const breadcrumbs: BreadcrumbItemData[] = [
+    {
+      name: t("ai_connections.admin.title"),
+      href: generateUrl({ page: AI_CONNECTIONS_ADMIN_PAGE_URL }),
+    },
+  ];
+
+  return (
+    <SharedProvider value={{ breadcrumbs, title: { type: t("ai_connections.admin.title") } }}>
+      <AiConnectionsContext.Provider value={value}>{children}</AiConnectionsContext.Provider>
+    </SharedProvider>
+  );
+};
+
+export const useAiConnections = (): AiConnectionsContextType => useContext(AiConnectionsContext) ?? defaultContextValue;