@aws/nx-plugin-mcp 1.0.0-rc.96 → 1.0.0-rc.98

package/docs/guides/connection/react-fastapi.mdx

@@ -125,8 +125,8 @@ For more fine-grained control, you can use the `watch-generate:<ApiName>-client`
 />
 :::
 
-:::warning[File Watcher Dependency]
-`watch-generate:<ApiName>-client` relies on the [`nx watch`](https://nx.dev/docs/guides/tasks--caching/workspace-watching) command, which requires the [Nx Daemon](https://nx.dev/docs/concepts/nx-daemon) to be running. Therefore if you have disabled the daemon, the client won't automatically regenerate when making changes to your FastAPI.
+:::note[The dev target requires the Nx Daemon]
+The `dev` target hot-reloads local dev servers. Many of these rely on [`nx watch`](https://nx.dev/docs/guides/tasks--caching/workspace-watching) to achieve this, which requires the [Nx Daemon](https://nx.dev/docs/concepts/nx-daemon) to be enabled.
 :::
 
 ### Using the API Hook
@@ -146,13 +146,15 @@ function MyComponent() {
   const api = useMyApi();
   const item = useQuery(api.getItem.queryOptions({ itemId: 'some-id' }));
 
-  if (item.isLoading) return <div>Loading...</div>;
-  if (item.isError) return <div>Error: {item.error.message}</div>;
+  if (item.isPending) return <div>Loading...</div>;
+  if (item.isError) return <div>Error: {JSON.stringify(item.error.error)}</div>;
 
   return <div>Item: {item.data.name}</div>;
 }
 ```
 
+The error is a discriminated union of `{ status, error }` objects rather than an `Error`, so there is no top-level `message` to render. Narrow on `status` to read a specific response body — see [Error Handling](#error-handling) below.
+
 <Drawer title="Using the API client directly" trigger="Click here for an example using the vanilla client directly.">
 ```tsx {5,13}
 import { useState, useEffect } from 'react';
@@ -222,7 +224,7 @@ function CreateItemForm() {
 
       {createItem.isError && (
         <div className="error">
-          Error: {createItem.error.message}
+          Error: {JSON.stringify(createItem.error.error)}
         </div>
       )}
     </form>
@@ -248,7 +250,7 @@ const createItem = useMutation({
   onSettled: () => {
     // This will run when the mutation completes (success or error)
     // Good place to invalidate queries that might be affected
-    queryClient.invalidateQueries({ queryKey: api.listItems.queryKey() });
+    queryClient.invalidateQueries({ queryKey: api.listItems.queryKey({}) });
   }
 });
 ```
@@ -370,12 +372,12 @@ function ItemList() {
       }),
   });
 
-  if (items.isLoading) {
+  if (items.isPending) {
     return <LoadingSpinner />;
   }
 
   if (items.isError) {
-    return <ErrorMessage message={items.error.message} />;
+    return <ErrorMessage message={JSON.stringify(items.error.error)} />;
   }
 
   return (
@@ -495,7 +497,9 @@ function ItemList() {
 
 ### Error Handling
 
-The integration includes built-in error handling with typed error responses. An `<operation-name>Error` type is generated which encapsulates the possible error responses defined in the OpenAPI specification. Each error has a `status` and `error` property, and by checking the value of `status` you can narrow to a specific type of error.
+The integration includes built-in error handling with typed error responses. An `<OperationName>Error` type is generated which is a union of one `<OperationName><StatusCode>Error` member per error status the operation's `responses` declares. Each member has a `status` and an `error` property, so switching on `status` narrows `error` to that status's model.
+
+The example below assumes `create_item` declares the [`responses` defined further down this page](#specifying-response-models) — a `400` `ValidationErrorDetails`, a `403` `str` and a `500` `ErrorDetails`. Only the statuses you declare appear in the union (plus FastAPI's own `422`), so a `case` for a status you haven't declared is a compile error.
 
 ```tsx {12}
 import { useMutation } from '@tanstack/react-query';
@@ -511,34 +515,32 @@ function MyComponent() {
   if (createItem.error) {
     switch (createItem.error.status) {
       case 400:
-        // error.error is typed as CreateItem400Response
+        // error.error is typed as ValidationErrorDetails
         return (
           <div>
             <h2>Invalid input:</h2>
             <p>{createItem.error.error.message}</p>
             <ul>
-              {createItem.error.error.validationErrors.map((err) => (
-                <li key={err.field}>{err.message}</li>
+              {createItem.error.error.fieldErrors.map((err) => (
+                <li key={err}>{err}</li>
               ))}
             </ul>
           </div>
         );
       case 403:
-        // error.error is typed as CreateItem403Response
+        // error.error is a string as specified in the responses
         return (
           <div>
             <h2>Not authorized:</h2>
-            <p>{createItem.error.error.reason}</p>
+            <p>{createItem.error.error}</p>
           </div>
         );
       case 500:
-      case 502:
-        // error.error is typed as CreateItem5XXResponse
+        // error.error is typed as ErrorDetails
         return (
           <div>
             <h2>Server error:</h2>
             <p>{createItem.error.error.message}</p>
-            <p>Trace ID: {createItem.error.error.traceId}</p>
           </div>
         );
     }
@@ -548,6 +550,10 @@ function MyComponent() {
 }
 ```
 
+:::note[Python field names]
+The generated client camelCases model fields, so a Pydantic model declaring `field_errors` is read as `error.fieldErrors`.
+:::
+
 <Drawer title="Error handling using the API client directly" trigger="Click here for an example using the vanilla client directly.">
 ```tsx {9,15}
 function MyComponent() {
@@ -566,34 +572,32 @@ function MyComponent() {
   if (error) {
     switch (error.status) {
       case 400:
-        // error.error is typed as CreateItem400Response
+        // error.error is typed as ValidationErrorDetails
         return (
           <div>
             <h2>Invalid input:</h2>
             <p>{error.error.message}</p>
             <ul>
-              {error.error.validationErrors.map((err) => (
-                <li key={err.field}>{err.message}</li>
+              {error.error.fieldErrors.map((err) => (
+                <li key={err}>{err}</li>
               ))}
             </ul>
           </div>
         );
       case 403:
-        // error.error is typed as CreateItem403Response
+        // error.error is a string as specified in the responses
         return (
           <div>
             <h2>Not authorized:</h2>
-            <p>{error.error.reason}</p>
+            <p>{error.error}</p>
           </div>
         );
       case 500:
-      case 502:
-        // error.error is typed as CreateItem5XXResponse
+        // error.error is typed as ErrorDetails
         return (
           <div>
             <h2>Server error:</h2>
             <p>{error.error.message}</p>
-            <p>Trace ID: {error.error.traceId}</p>
           </div>
         );
     }
@@ -784,6 +788,8 @@ def list_items(page: int = 1, limit: int = 10):
 
 The generated hooks and client methods are automatically organized based on the OpenAPI tags in your FastAPI endpoints. This helps keep your API calls organized and makes it easier to find related operations.
 
+Within a group each operation keeps its own camelCased name, taken from your endpoint function's name — so `def list_items()` tagged `"items"` is reached at `api.items.listItems`.
+
 For example:
 
 ```python title="items.py"
@@ -791,7 +797,7 @@ For example:
     "/items",
     tags=["items"],
 )
-def list():
+def list(cursor: str | None = None):
     # ...
 
 @app.post(
@@ -811,6 +817,10 @@ def list():
     # ...
 ```
 
+:::tip[Repeated function names]
+Two endpoints named `list` in different tags don't clash — the generator qualifies a duplicated name with its tag, so both are reachable at `api.items.list` and `api.users.list`.
+:::
+
 The generated hooks will be grouped by these tags:
 
 ```tsx
@@ -821,7 +831,7 @@ function ItemsAndUsers() {
   const api = useMyApi();
 
   // Items operations are grouped under api.items
-  const items = useQuery(api.items.list.queryOptions());
+  const items = useQuery(api.items.list.queryOptions({}));
   const createItem = useMutation(api.items.create.mutationOptions());
 
   // Users operations are grouped under api.users
@@ -873,7 +883,7 @@ function ItemsAndUsers() {
         setIsLoading(true);
 
         // Items operations are grouped under api.items
-        const itemsData = await api.items.list();
+        const itemsData = await api.items.list({});
         setItems(itemsData);
 
         // Users operations are grouped under api.users
@@ -943,7 +953,7 @@ from pydantic import BaseModel
 class ErrorDetails(BaseModel):
     message: str
 
-class ValidationError(BaseModel):
+class ValidationErrorDetails(BaseModel):
     message: str
     field_errors: list[str]
 ```
@@ -958,7 +968,7 @@ class NotFoundException(Exception):
         self.message = message
 
 class ValidationException(Exception):
-    def __init__(self, details: ValidationError):
+    def __init__(self, details: ValidationErrorDetails):
         self.details = details
 ```
 
@@ -997,8 +1007,8 @@ Finally, specify the response models for different error status codes in your en
 @app.get(
     "/items/{item_id}",
     responses={
-        404: {"model": str}
-        500: {"model": ErrorDetails}
+        404: {"model": str},
+        500: {"model": ErrorDetails},
     }
 )
 def get_item(item_id: str) -> Item:
@@ -1010,14 +1020,15 @@ def get_item(item_id: str) -> Item:
 @app.post(
     "/items",
     responses={
-        400: {"model": ValidationError},
-        403: {"model": str}
+        400: {"model": ValidationErrorDetails},
+        403: {"model": str},
+        500: {"model": ErrorDetails},
     }
 )
 def create_item(item: Item) -> Item:
     if not is_valid(item):
         raise ValidationException(
-            ValidationError(
+            ValidationErrorDetails(
                 message="Invalid item data",
                 field_errors=["name is required"]
             )
@@ -1035,33 +1046,18 @@ import { useMutation, useQuery } from '@tanstack/react-query';
 function ItemComponent() {
   const api = useMyApi();
 
-  // Query with typed error handling
-  const getItem = useQuery({
-    ...api.getItem.queryOptions({ itemId: '123' }),
-    onError: (error) => {
-      // Error is typed based on the responses in your FastAPI
-      switch (error.status) {
-        case 404:
-          // error.error is a string as specified in the responses
-          console.error('Not found:', error.error);
-          break;
-        case 500:
-          // error.error is typed as ErrorDetails
-          console.error('Server error:', error.error.message);
-          break;
-      }
-    }
-  });
+  const getItem = useQuery(api.getItem.queryOptions({ itemId: '123' }));
 
   // Mutation with typed error handling
   const createItem = useMutation({
     ...api.createItem.mutationOptions(),
     onError: (error) => {
+      // Error is typed based on the responses in your FastAPI
       switch (error.status) {
         case 400:
-          // error.error is typed as ValidationError
+          // error.error is typed as ValidationErrorDetails
           console.error('Validation error:', error.error.message);
-          console.error('Field errors:', error.error.field_errors);
+          console.error('Field errors:', error.error.fieldErrors);
           break;
         case 403:
           // error.error is a string as specified in the responses
@@ -1073,10 +1069,13 @@ function ItemComponent() {
 
   // Component rendering with error handling
   if (getItem.isError) {
-    if (getItem.error.status === 404) {
-      return <NotFoundMessage message={getItem.error.error} />;
-    } else {
-      return <ErrorMessage message={getItem.error.error.message} />;
+    switch (getItem.error.status) {
+      case 404:
+        // error.error is a string as specified in the responses
+        return <NotFoundMessage message={getItem.error.error} />;
+      case 500:
+        // error.error is typed as ErrorDetails
+        return <ErrorMessage message={getItem.error.error.message} />;
     }
   }
 
@@ -1137,9 +1136,9 @@ function ItemComponent() {
 
       switch (err.status) {
         case 400:
-          // err.error is typed as ValidationError
+          // err.error is typed as ValidationErrorDetails
           console.error('Validation error:', err.error.message);
-          console.error('Field errors:', err.error.field_errors);
+          console.error('Field errors:', err.error.fieldErrors);
           break;
         case 403:
           // err.error is a string as specified in the responses
@@ -1186,7 +1185,7 @@ import { useQuery } from '@tanstack/react-query';
 
 function ItemList() {
   const api = useMyApi();
-  const items = useQuery(api.listItems.queryOptions());
+  const items = useQuery(api.listItems.queryOptions({}));
 
   if (items.isLoading) {
     return <LoadingSpinner />;
@@ -1196,17 +1195,11 @@ function ItemList() {
     const err = items.error;
     switch (err.status) {
       case 403:
-        // err.error is typed as ListItems403Response
-        return <ErrorMessage message={err.error.reason} />;
+        // err.error is a string as specified in the responses
+        return <ErrorMessage message={err.error} />;
       case 500:
-      case 502:
-        // err.error is typed as ListItems5XXResponse
-        return (
-          <ErrorMessage
-            message={err.error.message}
-            details={`Trace ID: ${err.error.traceId}`}
-          />
-        );
+        // err.error is typed as ErrorDetails
+        return <ErrorMessage message={err.error.message} />;
       default:
         return <ErrorMessage message="An unknown error occurred" />;
     }
@@ -1214,7 +1207,7 @@ function ItemList() {
 
   return (
     <ul>
-      {items.data.map((item) => (
+      {items.data?.items.map((item) => (
         <li key={item.id}>{item.name}</li>
       ))}
     </ul>
@@ -1233,7 +1226,7 @@ function ItemList() {
   useEffect(() => {
     const fetchItems = async () => {
       try {
-        const data = await api.listItems();
+        const data = await api.listItems({});
         setItems(data);
       } catch (err) {
         setError(err);
@@ -1252,17 +1245,11 @@ function ItemList() {
     const err = error as ListItemsError;
     switch (err.status) {
       case 403:
-        // err.error is typed as ListItems403Response
-        return <ErrorMessage message={err.error.reason} />;
+        // err.error is a string as specified in the responses
+        return <ErrorMessage message={err.error} />;
       case 500:
-      case 502:
-        // err.error is typed as ListItems5XXResponse
-        return (
-          <ErrorMessage
-            message={err.error.message}
-            details={`Trace ID: ${err.error.traceId}`}
-          />
-        );
+        // err.error is typed as ErrorDetails
+        return <ErrorMessage message={err.error.message} />;
       default:
         return <ErrorMessage message="An unknown error occurred" />;
     }
@@ -1285,41 +1272,53 @@ Implement optimistic updates for a better user experience:
 
 ```tsx
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import type { ListItemsOutput } from '../generated/my-api/types.gen';
 
 function ItemList() {
   const api = useMyApi();
   const queryClient = useQueryClient();
 
   // Query to fetch items
-  const itemsQuery = useQuery(api.listItems.queryOptions());
+  const itemsQuery = useQuery(api.listItems.queryOptions({}));
 
   // Mutation for deleting items with optimistic updates
   const deleteMutation = useMutation({
     ...api.deleteItem.mutationOptions(),
-    onMutate: async (itemId) => {
+    onMutate: async ({ itemId }) => {
       // Cancel any outgoing refetches
-      await queryClient.cancelQueries({ queryKey: api.listItems.queryKey() });
+      await queryClient.cancelQueries({
+        queryKey: api.listItems.queryKey({}),
+      });
 
       // Snapshot the previous value
-      const previousItems = queryClient.getQueryData(api.listItems.queryKey());
+      const previousItems = queryClient.getQueryData<ListItemsOutput>(
+        api.listItems.queryKey({}),
+      );
 
       // Optimistically update to the new value
-      queryClient.setQueryData(
-        api.listItems.queryKey(),
-        (old) => old.filter((item) => item.id !== itemId)
+      queryClient.setQueryData<ListItemsOutput>(
+        api.listItems.queryKey({}),
+        (old) =>
+          old && {
+            ...old,
+            items: old.items.filter((item) => item.id !== itemId),
+          },
       );
 
       // Return a context object with the snapshot
       return { previousItems };
     },
-    onError: (err, itemId, context) => {
+    onError: (err, _input, context) => {
       // If the mutation fails, use the context returned from onMutate to roll back
-      queryClient.setQueryData(api.listItems.queryKey(), context.previousItems);
+      queryClient.setQueryData(
+        api.listItems.queryKey({}),
+        context?.previousItems,
+      );
       console.error('Failed to delete item:', err);
     },
     onSettled: () => {
       // Always refetch after error or success to ensure data is in sync with server
-      queryClient.invalidateQueries({ queryKey: api.listItems.queryKey() });
+      queryClient.invalidateQueries({ queryKey: api.listItems.queryKey({}) });
     },
   });
 
@@ -1333,11 +1332,11 @@ function ItemList() {
 
   return (
     <ul>
-      {itemsQuery.data.map((item) => (
+      {itemsQuery.data?.items.map((item) => (
         <li key={item.id}>
           {item.name}
           <button
-            onClick={() => deleteMutation.mutate(item.id)}
+            onClick={() => deleteMutation.mutate({ itemId: item.id })}
             disabled={deleteMutation.isPending}
           >
             {deleteMutation.isPending ? 'Deleting...' : 'Delete'}
@@ -1413,19 +1412,22 @@ function ItemForm() {
     const error = createItem.error;
     switch (error.status) {
       case 400:
-        // error.error is typed as CreateItem400Response
+        // error.error is typed as ValidationErrorDetails
         return (
           <FormError
             message="Invalid input"
-            errors={error.error.validationErrors}
+            errors={error.error.fieldErrors}
           />
         );
       case 403:
-        // error.error is typed as CreateItem403Response
-        return <AuthError reason={error.error.reason} />;
-      default:
-        // error.error is typed as CreateItem5XXResponse for 500, 502, etc.
+        // error.error is a string as specified in the responses
+        return <AuthError reason={error.error} />;
+      case 500:
+        // error.error is typed as ErrorDetails
         return <ServerError message={error.error.message} />;
+      default:
+        // FastAPI adds a 422 to every endpoint, so `default` isn't narrowed
+        return <ServerError message="An unknown error occurred" />;
     }
   }
 
@@ -1461,22 +1463,16 @@ function ItemForm() {
       const err = e as CreateItemError;
       switch (err.status) {
         case 400:
-          // err.error is typed as CreateItem400Response
-          console.error('Validation errors:', err.error.validationErrors);
+          // err.error is typed as ValidationErrorDetails
+          console.error('Validation errors:', err.error.fieldErrors);
           break;
         case 403:
-          // err.error is typed as CreateItem403Response
-          console.error('Not authorized:', err.error.reason);
+          // err.error is a string as specified in the responses
+          console.error('Not authorized:', err.error);
           break;
         case 500:
-        case 502:
-          // err.error is typed as CreateItem5XXResponse
-          console.error(
-            'Server error:',
-            err.error.message,
-            'Trace:',
-            err.error.traceId,
-          );
+          // err.error is typed as ErrorDetails
+          console.error('Server error:', err.error.message);
           break;
       }
       setError(err);
@@ -1490,13 +1486,15 @@ function ItemForm() {
         return (
           <FormError
             message="Invalid input"
-            errors={error.error.validationErrors}
+            errors={error.error.fieldErrors}
           />
         );
       case 403:
-        return <AuthError reason={error.error.reason} />;
-      default:
+        return <AuthError reason={error.error} />;
+      case 500:
         return <ServerError message={error.error.message} />;
+      default:
+        return <ServerError message="An unknown error occurred" />;
     }
   }
 

package/docs/guides/connection/react-py-agent.mdx

@@ -183,6 +183,10 @@ The connection generator automatically configures `dev` integration:
 The website and connected agent will hot-reload, enabling you to quickly iterate on both together without deploying to AWS.
 :::
 
+:::note[The dev target requires the Nx Daemon]
+The `dev` target hot-reloads local dev servers. Many of these rely on [`nx watch`](https://nx.dev/docs/guides/tasks--caching/workspace-watching) to achieve this, which requires the [Nx Daemon](https://nx.dev/docs/concepts/nx-daemon) to be enabled.
+:::
+
 ## More Information
 
 For more information, please refer to: