@carlonicora/nextjs-jsonapi 3.23.0 → 3.24.0

package/src/features/oauth/components/consent/__tests__/OAuthConsentScreen.spec.tsx

@@ -0,0 +1,126 @@
+import { render, renderHook, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { UseOAuthConsentReturn } from "../../../hooks/useOAuthConsent";
+import { OAuthConsentScreen } from "../OAuthConsentScreen";
+
+const { hookState, getAuthorizationInfo, approveAuthorization, currentUserContext } = vi.hoisted(() => ({
+  hookState: { value: null as UseOAuthConsentReturn | null },
+  getAuthorizationInfo: vi.fn(),
+  approveAuthorization: vi.fn(),
+  currentUserContext: vi.fn(),
+}));
+
+// The screen tests drive a controllable hook; the hook tests (hookState.value = null) run the real one.
+vi.mock("../../../hooks/useOAuthConsent", async () => {
+  const actual = await vi.importActual<typeof import("../../../hooks/useOAuthConsent")>(
+    "../../../hooks/useOAuthConsent",
+  );
+  return {
+    ...actual,
+    useOAuthConsent: (
+      params: Parameters<typeof actual.useOAuthConsent>[0],
+      options?: Parameters<typeof actual.useOAuthConsent>[1],
+    ) => hookState.value ?? actual.useOAuthConsent(params, options),
+  };
+});
+
+vi.mock("../../../data/oauth.service", () => ({
+  OAuthService: {
+    getAuthorizationInfo: (params: unknown) => getAuthorizationInfo(params),
+    approveAuthorization: (params: unknown) => approveAuthorization(params),
+    denyAuthorization: vi.fn(),
+  },
+}));
+
+vi.mock("../../../../user/contexts/CurrentUserContext", () => ({
+  useCurrentUserContextOptional: () => currentUserContext(),
+  useCurrentUserContext: () => currentUserContext(),
+}));
+
+const PARAMS = { clientId: "client-1", redirectUri: "https://example.com/callback" };
+const CLIENT = { id: "client-1", name: "Claude" } as any;
+const C1 = { id: "c1", name: "A" };
+const C2 = { id: "c2", name: "B" };
+
+function makeHook(overrides: Partial<UseOAuthConsentReturn> = {}): UseOAuthConsentReturn {
+  return {
+    clientInfo: { client: CLIENT, scopes: [], companies: [C1] },
+    isLoading: false,
+    error: null,
+    approve: vi.fn(),
+    deny: vi.fn(),
+    isSubmitting: false,
+    companyId: "c1",
+    setCompanyId: vi.fn(),
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  hookState.value = null;
+  currentUserContext.mockReturnValue({ company: { id: "c2" } });
+});
+
+describe("OAuthConsentScreen", () => {
+  it("renders no studio picker for a single company", () => {
+    hookState.value = makeHook();
+    render(<OAuthConsentScreen params={PARAMS} appName="Test" />);
+    expect(screen.queryByLabelText("oauth.consent.company_label")).toBeNull();
+  });
+
+  it("renders the studio picker for two companies", () => {
+    hookState.value = makeHook({
+      clientInfo: { client: CLIENT, scopes: [], companies: [C1, C2] },
+      companyId: "c2",
+    });
+    render(<OAuthConsentScreen params={PARAMS} appName="Test" />);
+    expect(screen.getByLabelText("oauth.consent.company_label")).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "oauth.consent.company_label" })).toBeInTheDocument();
+  });
+
+  it("renders translated keys, not hardcoded English", () => {
+    hookState.value = makeHook();
+    render(<OAuthConsentScreen params={PARAMS} appName="Test" />);
+    expect(screen.getByText("oauth.consent.authorize")).toBeInTheDocument();
+    expect(screen.queryByText("Authorize")).toBeNull();
+  });
+});
+
+describe("useOAuthConsent", () => {
+  const renderConsentHook = async (options?: { defaultCompanyId?: string }) => {
+    const { useOAuthConsent } = await import("../../../hooks/useOAuthConsent");
+    return renderHook(() => useOAuthConsent(PARAMS, options));
+  };
+
+  it("defaultCompanyId from the host app wins over the package user context", async () => {
+    currentUserContext.mockReturnValue(undefined);
+    getAuthorizationInfo.mockResolvedValue({ client: CLIENT, scopes: [], companies: [C1, C2] });
+    const { result } = await renderConsentHook({ defaultCompanyId: "c2" });
+    await waitFor(() => expect(result.current.companyId).toBe("c2"));
+  });
+
+  it("defaults companyId to the current web-session company when it is in the list", async () => {
+    getAuthorizationInfo.mockResolvedValue({ client: CLIENT, scopes: [], companies: [C1, C2] });
+    const { result } = await renderConsentHook();
+    await waitFor(() => expect(result.current.companyId).toBe("c2"));
+  });
+
+  it("defaults to the first company when the current one is not in the list", async () => {
+    currentUserContext.mockReturnValue({ company: { id: "c9" } });
+    getAuthorizationInfo.mockResolvedValue({ client: CLIENT, scopes: [], companies: [C1, C2] });
+    const { result } = await renderConsentHook();
+    await waitFor(() => expect(result.current.companyId).toBe("c1"));
+  });
+
+  it("approve sends the selected company", async () => {
+    getAuthorizationInfo.mockResolvedValue({ client: CLIENT, scopes: [], companies: [C1, C2] });
+    approveAuthorization.mockResolvedValue({ redirectUrl: "" });
+    const { result } = await renderConsentHook();
+    await waitFor(() => expect(result.current.companyId).toBe("c2"));
+
+    await result.current.approve();
+
+    expect(approveAuthorization).toHaveBeenCalledWith(expect.objectContaining({ companyId: "c2" }));
+  });
+});

package/src/features/oauth/components/consent/index.ts

@@ -2,3 +2,4 @@ export * from "./OAuthConsentHeader";
 export * from "./OAuthScopeList";
 export * from "./OAuthConsentActions";
 export * from "./OAuthConsentScreen";
+export * from "./OAuthCompanySelector";

package/src/features/oauth/data/__tests__/oauth.service.spec.ts

@@ -0,0 +1,103 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { AbstractService } from "../../../../core/abstracts/AbstractService";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { OAuthConsentRequest } from "../../interfaces/oauth.interface";
+import { OAuthClient } from "../oauth";
+import { OAuthService } from "../oauth.service";
+
+// ModuleRegistry is backed by a globalThis symbol shared across test files in a
+// worker, hence the register-if-absent guard (same idiom as HandbookThreadService.spec.ts).
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("OAuth", { name: "oauth-clients", model: OAuthClient } as any);
+});
+
+type CallApiParams = { method: string; endpoint: string; input?: unknown; overridesJsonApiCreation?: boolean };
+const callApiWithMeta = () => vi.spyOn(AbstractService as any, "callApiWithMeta");
+const firstCall = (spy: ReturnType<typeof callApiWithMeta>): CallApiParams => spy.mock.calls[0][0] as CallApiParams;
+
+const fullRequest: OAuthConsentRequest = {
+  clientId: "client-1",
+  redirectUri: "https://example.test/cb",
+  scope: "read mcp",
+  state: "xyz",
+  codeChallenge: "challenge",
+  codeChallengeMethod: "S256",
+  companyId: "11111111-1111-4111-8111-111111111111",
+};
+
+describe("OAuthClient authorization bodies (RFC 6749 wire format)", () => {
+  it("builds the approve body with snake_case keys in wire order", () => {
+    const body = new OAuthClient().createApproveAuthorizationJsonApi(fullRequest);
+
+    expect(JSON.stringify(body)).toBe(
+      JSON.stringify({
+        client_id: "client-1",
+        redirect_uri: "https://example.test/cb",
+        scope: "read mcp",
+        state: "xyz",
+        code_challenge: "challenge",
+        code_challenge_method: "S256",
+        company_id: "11111111-1111-4111-8111-111111111111",
+      }),
+    );
+  });
+
+  it("omits optional approve fields that were not supplied", () => {
+    const body = new OAuthClient().createApproveAuthorizationJsonApi({
+      clientId: "client-1",
+      redirectUri: "https://example.test/cb",
+    });
+
+    expect(JSON.stringify(body)).toBe('{"client_id":"client-1","redirect_uri":"https://example.test/cb"}');
+  });
+
+  it("builds the deny body with only client_id, redirect_uri and state", () => {
+    const body = new OAuthClient().createDenyAuthorizationJsonApi(fullRequest);
+
+    expect(JSON.stringify(body)).toBe(
+      '{"client_id":"client-1","redirect_uri":"https://example.test/cb","state":"xyz"}',
+    );
+  });
+});
+
+describe("OAuthService consent calls", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("approveAuthorization sends the model's approve body and returns the redirect url", async () => {
+    const spy = callApiWithMeta().mockResolvedValue({ meta: { redirectUrl: "https://example.test/cb?code=1" } });
+
+    const result = await OAuthService.approveAuthorization(fullRequest);
+
+    const call = firstCall(spy);
+    expect(call.method).toBe("POST");
+    expect(call.endpoint).toContain("oauth/authorize/approve");
+    expect(call.overridesJsonApiCreation).toBe(true);
+    expect(call.input).toEqual(new OAuthClient().createApproveAuthorizationJsonApi(fullRequest));
+    expect(result).toEqual({ redirectUrl: "https://example.test/cb?code=1" });
+  });
+
+  it("denyAuthorization sends the model's deny body and returns the redirect url", async () => {
+    const spy = callApiWithMeta().mockResolvedValue({
+      meta: { redirectUrl: "https://example.test/cb?error=access_denied" },
+    });
+
+    const result = await OAuthService.denyAuthorization(fullRequest);
+
+    const call = firstCall(spy);
+    expect(call.method).toBe("POST");
+    expect(call.endpoint).toContain("oauth/authorize/deny");
+    expect(call.overridesJsonApiCreation).toBe(true);
+    expect(call.input).toEqual(new OAuthClient().createDenyAuthorizationJsonApi(fullRequest));
+    expect(result).toEqual({ redirectUrl: "https://example.test/cb?error=access_denied" });
+  });
+});

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

@@ -7,6 +7,7 @@ import {
   OAuthConsentInfo,
   OAuthConsentRequest,
 } from "../interfaces/oauth.interface";
+import { OAuthClient } from "./oauth";
 
 /**
  * Service for OAuth client management and authorization consent flow.
@@ -151,14 +152,7 @@ export class OAuthService extends AbstractService {
       type: Modules.OAuth,
       method: HttpMethod.POST,
       endpoint: new EndpointCreator({ endpoint: "oauth/authorize/approve" }).generate(),
-      input: {
-        client_id: params.clientId,
-        redirect_uri: params.redirectUri,
-        scope: params.scope,
-        state: params.state,
-        code_challenge: params.codeChallenge,
-        code_challenge_method: params.codeChallengeMethod,
-      },
+      input: new OAuthClient().createApproveAuthorizationJsonApi(params),
       overridesJsonApiCreation: true,
     });
 
@@ -176,11 +170,7 @@ export class OAuthService extends AbstractService {
       type: Modules.OAuth,
       method: HttpMethod.POST,
       endpoint: new EndpointCreator({ endpoint: "oauth/authorize/deny" }).generate(),
-      input: {
-        client_id: params.clientId,
-        redirect_uri: params.redirectUri,
-        state: params.state,
-      },
+      input: new OAuthClient().createDenyAuthorizationJsonApi(params),
       overridesJsonApiCreation: true,
     });
 

package/src/features/oauth/data/oauth.ts

@@ -1,5 +1,5 @@
 import { AbstractApiData, JsonApiHydratedDataInterface } from "../../../core";
-import { OAuthClientInput, OAuthClientInterface } from "../interfaces/oauth.interface";
+import { OAuthClientInput, OAuthClientInterface, OAuthConsentRequest } from "../interfaces/oauth.interface";
 
 /**
  * OAuth client data model
@@ -84,4 +84,33 @@ export class OAuthClient extends AbstractApiData implements OAuthClientInterface
 
     return response;
   }
+
+  /**
+   * Body for POST /oauth/authorize/approve.
+   * The authorize endpoints speak the RFC 6749 wire format (snake_case keys,
+   * no JSON:API envelope), so this dedicated method owns that shape and the
+   * service sends it with `overridesJsonApiCreation`.
+   */
+  createApproveAuthorizationJsonApi(params: OAuthConsentRequest) {
+    return {
+      client_id: params.clientId,
+      redirect_uri: params.redirectUri,
+      scope: params.scope,
+      state: params.state,
+      code_challenge: params.codeChallenge,
+      code_challenge_method: params.codeChallengeMethod,
+      company_id: params.companyId,
+    };
+  }
+
+  /**
+   * Body for POST /oauth/authorize/deny (RFC 6749 wire format, see above).
+   */
+  createDenyAuthorizationJsonApi(params: OAuthConsentRequest) {
+    return {
+      client_id: params.clientId,
+      redirect_uri: params.redirectUri,
+      state: params.state,
+    };
+  }
 }

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

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useState } from "react";
 import { OAuthConsentInfo, OAuthConsentRequest } from "../interfaces/oauth.interface";
 import { OAuthService } from "../data/oauth.service";
+import { useCurrentUserContextOptional } from "../../user/contexts/CurrentUserContext";
 
 export interface UseOAuthConsentReturn {
   /** Client and scope info for consent display */
@@ -17,6 +18,10 @@ export interface UseOAuthConsentReturn {
   deny: () => Promise<void>;
   /** Whether approve/deny is in progress */
   isSubmitting: boolean;
+  /** The studio (company) the authorization is granted for */
+  companyId: string | undefined;
+  /** Select the studio (company) the authorization is granted for */
+  setCompanyId: (id: string) => void;
 }
 
 /**
@@ -37,11 +42,35 @@ export interface UseOAuthConsentReturn {
  * // On button click: approve() or deny()
  * ```
  */
-export function useOAuthConsent(params: OAuthConsentRequest): UseOAuthConsentReturn {
+export function useOAuthConsent(
+  params: OAuthConsentRequest,
+  options?: {
+    /**
+     * The studio open in the host app's session. Apps that keep the signed-in
+     * user in their own context (not the package UserProvider) pass it here;
+     * it wins over the package context.
+     */
+    defaultCompanyId?: string;
+  },
+): UseOAuthConsentReturn {
   const [clientInfo, setClientInfo] = useState<OAuthConsentInfo | null>(null);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<Error | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
+  const [companyId, setCompanyId] = useState<string | undefined>(undefined);
+  const contextCompanyId = useCurrentUserContextOptional()?.company?.id;
+  const currentCompanyId = options?.defaultCompanyId ?? contextCompanyId;
+
+  // 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.
+  useEffect(() => {
+    const companies = clientInfo?.companies ?? [];
+    if (companies.length === 0) return;
+    if (companyId && companies.some((company) => company.id === companyId)) return;
+
+    const current = currentCompanyId ? companies.find((company) => company.id === currentCompanyId) : undefined;
+    setCompanyId(current?.id ?? companies[0]?.id);
+  }, [clientInfo, currentCompanyId, companyId]);
 
   // Fetch client info on mount
   useEffect(() => {
@@ -83,7 +112,7 @@ export function useOAuthConsent(params: OAuthConsentRequest): UseOAuthConsentRet
     setError(null);
 
     try {
-      const result = await OAuthService.approveAuthorization(params);
+      const result = await OAuthService.approveAuthorization({ ...params, companyId });
 
       // Redirect to client with authorization code
       if (result.redirectUrl) {
@@ -95,7 +124,7 @@ export function useOAuthConsent(params: OAuthConsentRequest): UseOAuthConsentRet
       setIsSubmitting(false);
     }
     // Note: Don't set isSubmitting to false on success - we're redirecting
-  }, [params]);
+  }, [params, companyId]);
 
   const deny = useCallback(async (): Promise<void> => {
     setIsSubmitting(true);
@@ -123,5 +152,7 @@ export function useOAuthConsent(params: OAuthConsentRequest): UseOAuthConsentRet
     approve,
     deny,
     isSubmitting,
+    companyId,
+    setCompanyId,
   };
 }

package/src/features/oauth/interfaces/oauth.interface.ts

@@ -89,13 +89,15 @@ export interface OAuthConsentRequest {
   codeChallenge?: string;
   /** PKCE method: 'S256' (recommended) or 'plain' */
   codeChallengeMethod?: string;
+  /** The studio (company) the issued tokens are bound to; sent as `company_id` on approve */
+  companyId?: string;
 }
 
 /**
  * Scope information for display in consent screen
  */
 export interface OAuthScopeInfo {
-  /** The scope identifier (e.g., 'photographs:read') */
+  /** The scope identifier (e.g., 'read', 'mcp') */
   scope: string;
   /** Human-readable scope name */
   name: string;
@@ -111,6 +113,8 @@ export interface OAuthScopeInfo {
 export interface OAuthConsentInfo {
   client: OAuthClientInterface;
   scopes: OAuthScopeInfo[];
+  /** The caller's companies, ordered by name; the user picks one when there is more than one */
+  companies?: Array<{ id: string; name: string }>;
 }
 
 /**
@@ -130,36 +134,18 @@ export const OAUTH_SCOPE_DISPLAY: Record<string, OAuthScopeInfo> = {
     description: "Write access to your data",
     icon: "pencil",
   },
-  "photographs:read": {
-    scope: "photographs:read",
-    name: "View Photographs",
-    description: "Access and download your photo library",
-    icon: "image",
-  },
-  "photographs:write": {
-    scope: "photographs:write",
-    name: "Upload Photographs",
-    description: "Add new photos to your rolls",
-    icon: "upload",
-  },
-  "rolls:read": {
-    scope: "rolls:read",
-    name: "View Rolls",
-    description: "See your film rolls and collections",
-    icon: "film",
-  },
-  "rolls:write": {
-    scope: "rolls:write",
-    name: "Manage Rolls",
-    description: "Create and modify film rolls",
-    icon: "folder-plus",
-  },
   profile: {
     scope: "profile",
     name: "View Profile",
     description: "Access your name and email",
     icon: "user",
   },
+  mcp: {
+    scope: "mcp",
+    name: "MCP Server Access",
+    description: "Let an AI assistant read and act on your data through the MCP server",
+    icon: "shield",
+  },
   admin: {
     scope: "admin",
     name: "Administrative Access",

package/src/hooks/__tests__/useDataListRetriever.test.ts

@@ -243,7 +243,7 @@ describe("useDataListRetriever", () => {
       const retriever = vi.fn().mockResolvedValue(mockData);
 
       const { result } = renderHook(() =>
-        useDataListRetriever({
+        useDataListRetriever<(typeof mockData)[number]>({
           retriever,
           module: mockModule,
         }),

package/dist/AssistantInterface-RvZzlcA_.d.ts

@@ -1,36 +0,0 @@
-import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.js';
-
-type AssistantInput = {
-    firstMessage: string;
-    title?: string;
-    howToMode?: boolean;
-    limitToHowToId?: string;
-    handbookMode?: boolean;
-    limitToHandbookPageId?: string;
-    /**
-     * BlockNote document behind `firstMessage`. Sent alongside the flattened
-     * text so the server can re-derive the content and read `@`-mentions from
-     * the inline nodes; the flattened text is never trusted on its own.
-     */
-    contentBlocks?: unknown[];
-    /**
-     * Resource the thread is bound to (e.g. a campaign). Confines every agent
-     * data-access point in the run to that resource's scope.
-     */
-    boundContent?: {
-        type: string;
-        id: string;
-    };
-};
-interface AssistantInterface extends ApiDataInterface {
-    get title(): string;
-    get messageCount(): number;
-    /** Agent engine the thread runs on — `"operator"` or undefined (responder). */
-    get engine(): string | undefined;
-    /** JSON:API type of the resource this thread is bound to, when bound. */
-    get boundContentType(): string | undefined;
-    /** Id of the resource this thread is bound to, when bound. */
-    get boundContentId(): string | undefined;
-}
-
-export type { AssistantInput as A, AssistantInterface as a };

package/dist/AssistantInterface-jL56dyNc.d.mts

@@ -1,36 +0,0 @@
-import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.mjs';
-
-type AssistantInput = {
-    firstMessage: string;
-    title?: string;
-    howToMode?: boolean;
-    limitToHowToId?: string;
-    handbookMode?: boolean;
-    limitToHandbookPageId?: string;
-    /**
-     * BlockNote document behind `firstMessage`. Sent alongside the flattened
-     * text so the server can re-derive the content and read `@`-mentions from
-     * the inline nodes; the flattened text is never trusted on its own.
-     */
-    contentBlocks?: unknown[];
-    /**
-     * Resource the thread is bound to (e.g. a campaign). Confines every agent
-     * data-access point in the run to that resource's scope.
-     */
-    boundContent?: {
-        type: string;
-        id: string;
-    };
-};
-interface AssistantInterface extends ApiDataInterface {
-    get title(): string;
-    get messageCount(): number;
-    /** Agent engine the thread runs on — `"operator"` or undefined (responder). */
-    get engine(): string | undefined;
-    /** JSON:API type of the resource this thread is bound to, when bound. */
-    get boundContentType(): string | undefined;
-    /** Id of the resource this thread is bound to, when bound. */
-    get boundContentId(): string | undefined;
-}
-
-export type { AssistantInput as A, AssistantInterface as a };