@carlonicora/nextjs-jsonapi 4.1.1 → 4.2.0

package/src/features/oauth/hooks/__tests__/useOAuthScopeText.spec.ts

@@ -0,0 +1,30 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { OAUTH_SCOPE_DISPLAY } from "../../interfaces/oauth.interface";
+import { useOAuthScopeText } from "../useOAuthScopeText";
+
+// The suite's next-intl mock (vitest.setup.ts) returns the key itself.
+describe("useOAuthScopeText", () => {
+  it("reads the built-in scopes from oauth.ui.scopes.<id>.*", () => {
+    const { result } = renderHook(() => useOAuthScopeText());
+
+    expect(result.current("mcp")).toEqual({
+      name: "oauth.ui.scopes.mcp.name",
+      description: "oauth.ui.scopes.mcp.description",
+    });
+    expect(result.current(OAUTH_SCOPE_DISPLAY.read)).toEqual({
+      name: "oauth.ui.scopes.read.name",
+      description: "oauth.ui.scopes.read.description",
+    });
+  });
+
+  it("keeps the text an app-defined scope carries, falling back to its id", () => {
+    const { result } = renderHook(() => useOAuthScopeText());
+
+    expect(result.current({ scope: "photos:read", name: "View Photographs", description: "See photos" })).toEqual({
+      name: "View Photographs",
+      description: "See photos",
+    });
+    expect(result.current("photos:write")).toEqual({ name: "photos:write", description: "" });
+  });
+});

package/src/features/oauth/hooks/index.ts

@@ -1,3 +1,4 @@
 export * from "./useOAuthClients";
 export * from "./useOAuthClient";
 export * from "./useOAuthConsent";
+export * from "./useOAuthScopeText";

package/src/features/oauth/hooks/useOAuthClient.ts

@@ -1,7 +1,8 @@
 "use client";
 
+import { useTranslations } from "next-intl";
 import { useAtomValue, useSetAtom } from "jotai";
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import {
   oauthClientByIdAtom,
   removeOAuthClientAtom,
@@ -49,6 +50,11 @@ export function useOAuthClient(clientId: string): UseOAuthClientReturn {
   const updateClientInStore = useSetAtom(updateOAuthClientAtom);
   const removeClientFromStore = useSetAtom(removeOAuthClientAtom);
   const setNewClientSecret = useSetAtom(setNewClientSecretAtom);
+  const t = useTranslations();
+  // A ref, not a dependency: the translator must not re-create the callbacks below
+  // (they drive effects that refetch), it only words the fallback errors.
+  const tRef = useRef(t);
+  tRef.current = t;
 
   // Local state for fetched client (if not in store)
   const [fetchedClient, setFetchedClient] = useState<OAuthClientInterface | null>(null);
@@ -68,7 +74,7 @@ export function useOAuthClient(clientId: string): UseOAuthClientReturn {
       setFetchedClient(fetched);
     } catch (err) {
       console.error("[useOAuthClient] Failed to fetch client:", err);
-      setError(err instanceof Error ? err : new Error("Failed to fetch OAuth client"));
+      setError(err instanceof Error ? err : new Error(tRef.current("oauth.ui.errors.fetch_client")));
     } finally {
       setIsLoading(false);
     }
@@ -94,7 +100,7 @@ export function useOAuthClient(clientId: string): UseOAuthClientReturn {
         setFetchedClient(updated);
       } catch (err) {
         console.error("[useOAuthClient] Failed to update client:", err);
-        const error = err instanceof Error ? err : new Error("Failed to update OAuth client");
+        const error = err instanceof Error ? err : new Error(tRef.current("oauth.ui.errors.update_client"));
         setError(error);
         throw error;
       } finally {
@@ -115,7 +121,7 @@ export function useOAuthClient(clientId: string): UseOAuthClientReturn {
       removeClientFromStore(clientId);
     } catch (err) {
       console.error("[useOAuthClient] Failed to delete client:", err);
-      const error = err instanceof Error ? err : new Error("Failed to delete OAuth client");
+      const error = err instanceof Error ? err : new Error(tRef.current("oauth.ui.errors.delete_client"));
       setError(error);
       throw error;
     } finally {
@@ -141,7 +147,7 @@ export function useOAuthClient(clientId: string): UseOAuthClientReturn {
       return result.clientSecret;
     } catch (err) {
       console.error("[useOAuthClient] Failed to regenerate secret:", err);
-      const error = err instanceof Error ? err : new Error("Failed to regenerate client secret");
+      const error = err instanceof Error ? err : new Error(tRef.current("oauth.ui.errors.regenerate_secret"));
       setError(error);
       throw error;
     } finally {

package/src/features/oauth/hooks/useOAuthClients.ts

@@ -1,7 +1,8 @@
 "use client";
 
+import { useTranslations } from "next-intl";
 import { useAtom, useSetAtom } from "jotai";
-import { useCallback, useEffect } from "react";
+import { useCallback, useEffect, useRef } from "react";
 import {
   addOAuthClientAtom,
   oauthClientsAtom,
@@ -48,6 +49,11 @@ export function useOAuthClients(): UseOAuthClientsReturn {
   const [error, setError] = useAtom(oauthClientsErrorAtom);
   const addClient = useSetAtom(addOAuthClientAtom);
   const setNewClientSecret = useSetAtom(setNewClientSecretAtom);
+  const t = useTranslations();
+  // A ref, not a dependency: the translator must not re-create the callbacks below
+  // (they drive effects that refetch), it only words the fallback errors.
+  const tRef = useRef(t);
+  tRef.current = t;
 
   const fetchClients = useCallback(async () => {
     setIsLoading(true);
@@ -58,7 +64,7 @@ export function useOAuthClients(): UseOAuthClientsReturn {
       setClients(fetchedClients);
     } catch (err) {
       console.error("[useOAuthClients] Failed to fetch clients:", err);
-      setError(err instanceof Error ? err : new Error("Failed to fetch OAuth clients"));
+      setError(err instanceof Error ? err : new Error(tRef.current("oauth.ui.errors.fetch_clients")));
     } finally {
       setIsLoading(false);
     }
@@ -91,7 +97,7 @@ export function useOAuthClients(): UseOAuthClientsReturn {
         return result;
       } catch (err) {
         console.error("[useOAuthClients] Failed to create client:", err);
-        const error = err instanceof Error ? err : new Error("Failed to create OAuth client");
+        const error = err instanceof Error ? err : new Error(tRef.current("oauth.ui.errors.create_client"));
         setError(error);
         throw error;
       } finally {

package/src/features/oauth/hooks/useOAuthConsent.ts

@@ -1,6 +1,7 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
+import { useTranslations } from "next-intl";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { OAuthConsentInfo, OAuthConsentRequest } from "../interfaces/oauth.interface";
 import { OAuthService } from "../data/oauth.service";
 import { useCurrentUserContextOptional } from "../../user/contexts/CurrentUserContext";
@@ -60,6 +61,11 @@ export function useOAuthConsent(
   const [companyId, setCompanyId] = useState<string | undefined>(undefined);
   const contextCompanyId = useCurrentUserContextOptional()?.company?.id;
   const currentCompanyId = options?.defaultCompanyId ?? contextCompanyId;
+  const t = useTranslations();
+  // A ref, not a dependency: the translator must not re-create the callbacks below
+  // (they drive effects that refetch), it only words the fallback errors.
+  const tRef = useRef(t);
+  tRef.current = t;
 
   // Seed the studio choice once the user's companies arrive: the studio open in
   // the web session when it is in the list, otherwise the first one.
@@ -78,7 +84,7 @@ export function useOAuthConsent(
       // scope is deliberately NOT required: RFC 6749 §3.3 makes it optional
       // and the server defaults to the client's registered scopes.
       if (!params.clientId || !params.redirectUri) {
-        setError(new Error("Missing required authorization parameters"));
+        setError(new Error(tRef.current("oauth.ui.errors.missing_parameters")));
         setIsLoading(false);
         return;
       }
@@ -91,7 +97,7 @@ export function useOAuthConsent(
         setClientInfo(info);
       } catch (err) {
         console.error("[useOAuthConsent] Failed to fetch authorization info:", err);
-        setError(err instanceof Error ? err : new Error("Failed to load authorization info"));
+        setError(err instanceof Error ? err : new Error(tRef.current("oauth.ui.errors.load_authorization")));
       } finally {
         setIsLoading(false);
       }
@@ -120,7 +126,7 @@ export function useOAuthConsent(
       }
     } catch (err) {
       console.error("[useOAuthConsent] Failed to approve authorization:", err);
-      setError(err instanceof Error ? err : new Error("Failed to approve authorization"));
+      setError(err instanceof Error ? err : new Error(tRef.current("oauth.ui.errors.approve_authorization")));
       setIsSubmitting(false);
     }
     // Note: Don't set isSubmitting to false on success - we're redirecting
@@ -139,7 +145,7 @@ export function useOAuthConsent(
       }
     } catch (err) {
       console.error("[useOAuthConsent] Failed to deny authorization:", err);
-      setError(err instanceof Error ? err : new Error("Failed to deny authorization"));
+      setError(err instanceof Error ? err : new Error(tRef.current("oauth.ui.errors.deny_authorization")));
       setIsSubmitting(false);
     }
     // Note: Don't set isSubmitting to false on success - we're redirecting

package/src/features/oauth/hooks/useOAuthScopeText.ts

@@ -0,0 +1,33 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useCallback } from "react";
+import { OAUTH_SCOPE_DISPLAY, OAuthScopeInfo } from "../interfaces/oauth.interface";
+
+export type OAuthScopeText = { name: string; description: string };
+
+/**
+ * Returns a function that words a scope in the active language.
+ *
+ * The scopes defined in `OAUTH_SCOPE_DISPLAY` read their name and description
+ * from `oauth.ui.scopes.<id>.*`; the English text in that constant stays as
+ * data only. Any other scope (an app's own, or one the server describes) keeps
+ * the name and description it carries, falling back to its id.
+ */
+export function useOAuthScopeText(): (scope: string | OAuthScopeInfo) => OAuthScopeText {
+  const t = useTranslations();
+  return useCallback(
+    (scope: string | OAuthScopeInfo): OAuthScopeText => {
+      const id = typeof scope === "string" ? scope : scope.scope;
+      if (Object.prototype.hasOwnProperty.call(OAUTH_SCOPE_DISPLAY, id)) {
+        return {
+          name: t(`oauth.ui.scopes.${id}.name`),
+          description: t(`oauth.ui.scopes.${id}.description`),
+        };
+      }
+      const info = typeof scope === "string" ? undefined : scope;
+      return { name: info?.name || id, description: info?.description ?? "" };
+    },
+    [t],
+  );
+}

package/src/features/rbac/components/RbacByRoleContainer.tsx

@@ -61,11 +61,12 @@ const CellButton = memo(function CellButton({
   );
 });
 
-const ACTION_LABELS: Record<ActionType, string> = {
-  read: "Read",
-  create: "Create",
-  update: "Update",
-  delete: "Delete",
+/** Message keys for the action column headers. */
+const ACTION_LABEL_KEYS: Record<ActionType, string> = {
+  read: "rbac.actions.read",
+  create: "rbac.actions.create",
+  update: "rbac.actions.update",
+  delete: "rbac.actions.delete",
 };
 
 export default function RbacByRoleContainer() {
@@ -192,7 +193,7 @@ export default function RbacByRoleContainer() {
                           key={action}
                           className="min-w-28 px-2 py-2 text-center text-xs font-medium text-muted-foreground"
                         >
-                          {ACTION_LABELS[action]}
+                          {t(ACTION_LABEL_KEYS[action])}
                         </th>
                       ))}
                     </tr>

package/src/features/rbac/components/RbacContainer.tsx

@@ -81,11 +81,12 @@ const CellButton = memo(function CellButton({
 // changed.
 // ---------------------------------------------------------------------------
 
-const ACTION_LABELS: Record<ActionType, string> = {
-  read: "Read",
-  create: "Create",
-  update: "Update",
-  delete: "Delete",
+/** Message keys for the action column headers. */
+const ACTION_LABEL_KEYS: Record<ActionType, string> = {
+  read: "rbac.actions.read",
+  create: "rbac.actions.create",
+  update: "rbac.actions.update",
+  delete: "rbac.actions.delete",
 };
 
 interface ModuleEditorProps {
@@ -121,7 +122,7 @@ const ModuleEditor = memo(function ModuleEditor({
               <th className="w-40 px-4 py-2 text-start text-xs font-medium text-muted-foreground">{t("rbac.role")}</th>
               {ACTION_TYPES.map((action) => (
                 <th key={action} className="min-w-28 px-2 py-2 text-center text-xs font-medium text-muted-foreground">
-                  {ACTION_LABELS[action]}
+                  {t(ACTION_LABEL_KEYS[action])}
                 </th>
               ))}
             </tr>

package/src/features/rbac/contexts/RbacContext.tsx

@@ -138,14 +138,14 @@ export const RbacProvider = ({
     setSaving(true);
     try {
       await RbacService.saveMatrix({ matrix, roleNames, moduleNames, outputPath });
-      showToast(`Saved to ${outputPath}`);
+      showToast(t("rbac.saved_to", { path: outputPath }));
     } catch (err) {
       console.error("Failed to save RBAC matrix:", err);
       showError(err instanceof Error ? err.message : String(err));
     } finally {
       setSaving(false);
     }
-  }, [matrix, roleNames, moduleNames, outputPath]);
+  }, [matrix, roleNames, moduleNames, outputPath, t]);
 
   const breadcrumb = (): BreadcrumbItemData[] => {
     const response: BreadcrumbItemData[] = [];
@@ -168,7 +168,7 @@ export const RbacProvider = ({
     functions.push(
       <Button key="rbacSave" size="sm" onClick={handleSave} disabled={!canSave} className="gap-1">
         {saving ? <Loader2Icon className="h-3.5 w-3.5 animate-spin" /> : <DownloadIcon className="h-3.5 w-3.5" />}
-        Save to permissions.ts
+        {t("rbac.save_to_file")}
       </Button>,
     );
     if (functions.length > 0) response.functions = functions;

package/src/features/user/components/containers/UserContainer.tsx

@@ -2,16 +2,18 @@
 
 import { RoundPageContainer, Tab } from "@/components";
 import { Modules } from "@/core";
+import { useTranslations } from "next-intl";
 import { useUserContext } from "../../contexts";
 import { UserContent } from "../details";
 
 export function UserContainer() {
+  const t = useTranslations();
   const { user } = useUserContext();
   if (!user) return null;
 
   const tabs: Tab[] = [
     {
-      label: "Details",
+      label: t("ui.labels.details"),
       content: <UserContent user={user} />,
     },
   ];

package/src/features/user/data/__tests__/user.test.ts

@@ -0,0 +1,66 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { User } from "../user";
+
+// The model resolves its JSON:API types through the real ModuleRegistry, so every
+// module it names in rehydrate()/createJsonApi() must be registered.
+const modules: Record<string, ApiRequestDataTypeInterface> = {
+  User: { name: "users", model: User } as any,
+  Role: { name: "roles", model: class {} } as any,
+  Company: { name: "companies", model: class {} } as any,
+  Module: { name: "modules", model: class {} } as any,
+};
+
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  for (const [key, module] of Object.entries(modules)) registerIfAbsent(key, module);
+});
+
+function makeHydratedData(attributeOverrides: Record<string, any> = {}) {
+  return {
+    jsonApi: {
+      id: "user-1",
+      type: "users",
+      attributes: {
+        name: "Carlo",
+        email: "carlo@example.test",
+        ...attributeOverrides,
+      },
+      meta: {},
+      relationships: {},
+    },
+    included: [] as any[],
+  };
+}
+
+describe("User.rehydrate", () => {
+  it("exposes the saved language", () => {
+    const user = new User().rehydrate(makeHydratedData({ language: "it" }));
+    expect(user.language).toBe("it");
+  });
+
+  it("leaves language undefined when the user has not chosen one", () => {
+    const user = new User().rehydrate(makeHydratedData());
+    expect(user.language).toBeUndefined();
+  });
+});
+
+describe("User.createJsonApi", () => {
+  it("writes language when provided", () => {
+    const payload = new User().createJsonApi({ id: "user-1", language: "it" });
+    expect(payload.data.attributes.language).toBe("it");
+  });
+
+  it("omits language when undefined", () => {
+    const payload = new User().createJsonApi({ id: "user-1", name: "Carlo" });
+    expect(payload.data.attributes).not.toHaveProperty("language");
+  });
+});

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

@@ -17,6 +17,7 @@ export type UserInput = {
   avatar?: string;
   phone?: string;
   rate?: number;
+  language?: string;
 };
 
 export interface UserInterface extends ApiDataInterface {
@@ -28,6 +29,7 @@ export interface UserInterface extends ApiDataInterface {
   get avatarUrl(): string | undefined;
   get phone(): string | undefined;
   get rate(): number | undefined;
+  get language(): string | undefined;
 
   get isActivated(): boolean;
   get isDeleted(): boolean;

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

@@ -243,6 +243,15 @@ export class UserService extends AbstractService {
     });
   }
 
+  static async patchLanguage(params: { id: string; language: string }): Promise<UserInterface> {
+    return this.callApi({
+      type: Modules.User,
+      method: HttpMethod.PATCH,
+      endpoint: new EndpointCreator({ endpoint: Modules.User, id: params.id, childEndpoint: "language" }).generate(),
+      input: params,
+    });
+  }
+
   static async patchRate(params: UserInput): Promise<UserInterface> {
     return this.callApi({
       type: Modules.User,

package/src/features/user/data/user.ts

@@ -14,6 +14,7 @@ export class User extends AbstractApiData implements UserInterface, SearchResult
   private _avatarUrl?: string;
   private _phone?: string;
   private _rate?: number;
+  private _language?: string;
 
   private _isActivated?: boolean;
   private _isDeleted?: boolean;
@@ -62,6 +63,10 @@ export class User extends AbstractApiData implements UserInterface, SearchResult
     return this._rate;
   }
 
+  get language(): string | undefined {
+    return this._language;
+  }
+
   get relevance(): number | undefined {
     return this._relevance;
   }
@@ -103,6 +108,7 @@ export class User extends AbstractApiData implements UserInterface, SearchResult
     this._bio = data.jsonApi.attributes.bio;
     this._phone = data.jsonApi.attributes.phone;
     this._rate = data.jsonApi.attributes.rate;
+    this._language = data.jsonApi.attributes.language;
 
     this._avatar = data.jsonApi.attributes.avatar;
     this._avatarUrl = data.jsonApi.attributes.avatarUrl;
@@ -143,6 +149,7 @@ export class User extends AbstractApiData implements UserInterface, SearchResult
     if (data.adminCreated) response.data.attributes.adminCreated = true;
     if (data.avatar !== undefined) response.data.attributes.avatar = data.avatar;
     if (data.rate !== undefined) response.data.attributes.rate = data.rate;
+    if (data.language !== undefined) response.data.attributes.language = data.language;
 
     if (data.roleIds) {
       response.data.relationships.roles = {

package/src/features/waitlist/components/forms/WaitlistForm.tsx

@@ -115,7 +115,7 @@ export function WaitlistForm({ onSuccess }: WaitlistFormProps) {
       setIsSuccess(true);
       onSuccess?.();
     } catch (e) {
-      errorToast({ error: e });
+      errorToast({ title: t("common.errors.error"), error: e });
     } finally {
       setIsSubmitting(false);
     }

package/src/features/waitlist/components/lists/WaitlistList.tsx

@@ -38,7 +38,7 @@ export function WaitlistList({ fullWidth }: WaitlistListProps = {}) {
       showToast(t("waitlist.admin.invite_sent", { email: entry.email }));
       void data.refresh();
     } catch (error) {
-      errorToast({ error });
+      errorToast({ title: t("common.errors.error"), error });
     }
   };
 

package/src/i18n/__tests__/config.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { configureI18n, getI18nServerLocale, type I18nConfig } from "../config";
+import { configureI18n, getI18nServerLocale, getI18nSupportedLocales, type I18nConfig } from "../config";
 
 function config(getLocale: I18nConfig["getLocale"]): I18nConfig {
   return {
@@ -25,3 +25,23 @@ describe("getI18nServerLocale", () => {
     await expect(getI18nServerLocale()).rejects.toThrow(/configureI18n/);
   });
 });
+
+describe("getI18nSupportedLocales", () => {
+  afterEach(() => {
+    configureI18n(null as unknown as I18nConfig);
+  });
+
+  it('returns ["en"] when i18n is not configured', () => {
+    expect(getI18nSupportedLocales()).toEqual(["en"]);
+  });
+
+  it('returns ["en"] when supportedLocales is not set', () => {
+    configureI18n(config(async () => "en"));
+    expect(getI18nSupportedLocales()).toEqual(["en"]);
+  });
+
+  it("returns the configured supported locales", () => {
+    configureI18n({ ...config(async () => "en"), supportedLocales: ["en", "it"] });
+    expect(getI18nSupportedLocales()).toEqual(["en", "it"]);
+  });
+});

package/src/i18n/config.ts

@@ -33,6 +33,11 @@ export interface I18nConfig {
    * `next/root-params` — a module only allowed inside the app directory.
    */
   getLocale: GetLocaleFunction;
+  /**
+   * Locales the app supports. The first entry is the fallback.
+   * Defaults to `["en"]` when omitted.
+   */
+  supportedLocales?: string[];
 }
 
 // Private storage
@@ -89,3 +94,11 @@ export function useI18nDateFnsLocale(): any {
   // Fallback to undefined (Calendar will use default)
   return undefined;
 }
+
+/** The app's supported locales. Defaults to `["en"]` when not configured. */
+export function getI18nSupportedLocales(): string[] {
+  if (_config?.supportedLocales && _config.supportedLocales.length > 0) {
+    return _config.supportedLocales;
+  }
+  return ["en"];
+}

package/src/i18n/index.ts

@@ -6,6 +6,7 @@ export {
   useI18nDateFnsLocale,
   getI18nLink,
   getI18nServerLocale,
+  getI18nSupportedLocales,
 } from "./config";
 
 export type {