From 85e22349d83d49934875209da9ca3722e7b186f4 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Wed, 21 Jan 2026 14:52:09 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`feat/se?= =?UTF-8?q?rvices-subpage`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @zeedivx. * https://github.com/Anvoria/authly/pull/49#issuecomment-3769764544 The following files were modified: * `apps/api/internal/domain/service/handler.go` * `apps/web/src/app/auth/login/page.tsx` * `apps/web/src/app/authorize/page.tsx` * `apps/web/src/app/dashboard/admin/services/[id]/page.tsx` * `apps/web/src/app/dashboard/admin/users/page.tsx` * `apps/web/src/app/layout.tsx` * `apps/web/src/app/page.tsx` * `apps/web/src/components/dashboard/admin/services/OverviewTab.tsx` * `apps/web/src/components/dashboard/admin/services/overview/AuthenticationSection.tsx` * `apps/web/src/components/dashboard/admin/services/overview/BasicDetailsSection.tsx` * `apps/web/src/components/dashboard/admin/services/overview/CredentialsCard.tsx` * `apps/web/src/components/dashboard/admin/services/overview/MetadataCard.tsx` * `apps/web/src/components/dashboard/admin/services/overview/SaveActions.tsx` * `apps/web/src/components/dashboard/admin/services/overview/ServiceForm.tsx` * `apps/web/src/components/dashboard/admin/services/overview/StatusCard.tsx` * `apps/web/src/components/dashboard/admin/users/EditUserModal.tsx` * `apps/web/src/components/ui/CopyButton.tsx` * `apps/web/src/components/ui/FormField.tsx` * `apps/web/src/components/ui/TagInput.tsx` * `apps/web/src/lib/hooks/admin/usePermissions.ts` * `apps/web/src/lib/hooks/admin/useRoles.ts` * `apps/web/src/proxy.ts` --- apps/api/internal/domain/service/handler.go | 7 +++--- apps/web/src/app/auth/login/page.tsx | 9 +++++++- apps/web/src/app/authorize/page.tsx | 11 ++++++++- .../dashboard/admin/services/[id]/page.tsx | 8 ++++++- .../src/app/dashboard/admin/users/page.tsx | 4 ++-- apps/web/src/app/layout.tsx | 6 ++--- apps/web/src/app/page.tsx | 7 +++++- .../dashboard/admin/services/OverviewTab.tsx | 10 +++++++- .../overview/AuthenticationSection.tsx | 17 +++++++++++++- .../services/overview/BasicDetailsSection.tsx | 14 ++++++++++- .../services/overview/CredentialsCard.tsx | 11 ++++++++- .../admin/services/overview/MetadataCard.tsx | 12 +++++++++- .../admin/services/overview/SaveActions.tsx | 11 ++++++++- .../admin/services/overview/ServiceForm.tsx | 16 ++++++++++++- .../admin/services/overview/StatusCard.tsx | 10 +++++++- .../dashboard/admin/users/EditUserModal.tsx | 15 ++++++------ apps/web/src/components/ui/CopyButton.tsx | 11 ++++++++- apps/web/src/components/ui/FormField.tsx | 12 +++++++++- apps/web/src/components/ui/TagInput.tsx | 16 ++++++++++++- .../web/src/lib/hooks/admin/usePermissions.ts | 23 +++++++++++++++---- apps/web/src/lib/hooks/admin/useRoles.ts | 19 +++++++++++---- apps/web/src/proxy.ts | 10 +++++++- 22 files changed, 217 insertions(+), 42 deletions(-) diff --git a/apps/api/internal/domain/service/handler.go b/apps/api/internal/domain/service/handler.go index d295548..bdf5196 100644 --- a/apps/api/internal/domain/service/handler.go +++ b/apps/api/internal/domain/service/handler.go @@ -10,14 +10,15 @@ type Handler struct { serviceService ServiceInterface } -// NewHandler creates a Handler configured with the provided ServiceInterface. +// NewHandler creates a new Handler using the provided ServiceInterface. func NewHandler(s ServiceInterface) *Handler { return &Handler{serviceService: s} } // validateServiceID validates the service ID parameter from the request. // It checks if the ID is present and has a valid UUID format. -// Returns the validated ID or an error response. +// validateServiceID validates the "id" route parameter and returns it. +// If the parameter is missing or not a valid UUID, it sends a 400 validation error response and returns a non-nil error. func validateServiceID(c *fiber.Ctx) (string, error) { id := c.Params("id") if id == "" { @@ -201,4 +202,4 @@ func (h *Handler) DeleteService(c *fiber.Ctx) error { } return utils.SuccessResponse(c, nil, "Service deleted successfully") -} +} \ No newline at end of file diff --git a/apps/web/src/app/auth/login/page.tsx b/apps/web/src/app/auth/login/page.tsx index d596a0b..9da5d51 100644 --- a/apps/web/src/app/auth/login/page.tsx +++ b/apps/web/src/app/auth/login/page.tsx @@ -17,6 +17,13 @@ import LocalStorageTokenService from "@/authly/lib/services/TokenService"; type LoginFormData = z.infer; +/** + * Renders the login form UI and handles user authentication plus optional OpenID Connect (OIDC) redirect flow. + * + * The component validates credentials, calls the login mutation, displays API and field errors, and upon successful login initiates an OIDC authorization redirect (including PKCE code verifier generation when needed). It also provides a link to the registration page that preserves OIDC parameters when present. + * + * @returns The JSX element for the sign-in page content + */ function LoginPageContent() { const searchParams = useSearchParams(); const router = useRouter(); @@ -172,4 +179,4 @@ export default function LoginPage() { ); -} +} \ No newline at end of file diff --git a/apps/web/src/app/authorize/page.tsx b/apps/web/src/app/authorize/page.tsx index c20a049..cc8582e 100644 --- a/apps/web/src/app/authorize/page.tsx +++ b/apps/web/src/app/authorize/page.tsx @@ -28,6 +28,15 @@ type AuthPageState = | { type: "consent"; client: { name: string; logo_url?: string; client_id: string }; scopes: string[] } | { type: "redirecting" }; +/** + * Render the OIDC authorization page UI and manage the authorization flow lifecycle. + * + * This component validates the incoming OIDC request, checks the IdP session, redirects to login when required, + * presents an error view for invalid requests or clients, shows a consent screen for user approval, and performs + * the confirm/deny actions that ultimately redirect back to the client application. + * + * @returns The component's UI: a loading layout during validation/redirecting or auto-approval, an error view when validation fails, a consent screen when user approval is required, or `null` if no view applies. + */ function AuthorizePageContent() { const searchParams = useSearchParams(); const router = useRouter(); @@ -260,4 +269,4 @@ export default function AuthorizePage() { ); -} +} \ No newline at end of file diff --git a/apps/web/src/app/dashboard/admin/services/[id]/page.tsx b/apps/web/src/app/dashboard/admin/services/[id]/page.tsx index 8d73305..a39672e 100644 --- a/apps/web/src/app/dashboard/admin/services/[id]/page.tsx +++ b/apps/web/src/app/dashboard/admin/services/[id]/page.tsx @@ -14,6 +14,12 @@ interface ServicePageProps { params: Promise<{ id: string }>; } +/** + * Renders the admin service detail page for the service identified by the route `id`. + * + * @param params - Promise resolving to an object with the route `id` string used to load the service + * @returns The React element for the service details view, including loading and error states and tabbed content + */ export default function ServicePage({ params }: ServicePageProps) { const { id } = use(params); const { data: response, isLoading, isError } = useAdminService(id); @@ -113,4 +119,4 @@ export default function ServicePage({ params }: ServicePageProps) { ); -} +} \ No newline at end of file diff --git a/apps/web/src/app/dashboard/admin/users/page.tsx b/apps/web/src/app/dashboard/admin/users/page.tsx index c5ca8b6..ef0f55c 100644 --- a/apps/web/src/app/dashboard/admin/users/page.tsx +++ b/apps/web/src/app/dashboard/admin/users/page.tsx @@ -16,7 +16,7 @@ const PAGE_SIZE = 50; /** * Render the admin Users management page with a searchable, paginated list of users. * - * The component maintains local search and page state, debounces the search input, resets to page 1 when the debounced search changes, and fetches users with page-size pagination. The UI adapts to loading, error, empty, and populated states and provides controls for searching, clearing the search, retrying failed loads, and changing pages. + * The component maintains local `search` and `page` state, applies a debounced search input for data fetching, and displays appropriate UI for loading, error, empty, and populated states. It provides controls for searching, clearing the search, retrying failed loads, and changing pages. * * @returns The Users management page UI as a JSX element */ @@ -99,4 +99,4 @@ export default function UsersPage() { ); -} +} \ No newline at end of file diff --git a/apps/web/src/app/layout.tsx b/apps/web/src/app/layout.tsx index 99136ec..23b1808 100644 --- a/apps/web/src/app/layout.tsx +++ b/apps/web/src/app/layout.tsx @@ -39,10 +39,10 @@ export const viewport: Viewport = { }; /** - * Provide the application's root HTML structure, apply global font variables, and wrap page content with the QueryProvider. + * Render the application's root HTML structure, apply global font variables, and wrap page content with QueryProvider and AuthProvider. * * @param children - The application content to render inside the layout. - * @returns The `` element (lang="en") containing a `` whose children are wrapped by the QueryProvider. + * @returns The `` element (lang="en") whose `` applies the global font variables and contains `children` wrapped by `QueryProvider` and `AuthProvider`; includes a top-right `Toaster`. */ export default function RootLayout({ children }: { children: React.ReactNode }) { return ( @@ -57,4 +57,4 @@ export default function RootLayout({ children }: { children: React.ReactNode }) ); -} +} \ No newline at end of file diff --git a/apps/web/src/app/page.tsx b/apps/web/src/app/page.tsx index 910dad5..f90127b 100644 --- a/apps/web/src/app/page.tsx +++ b/apps/web/src/app/page.tsx @@ -4,6 +4,11 @@ import Footer from "@/authly/components/landing/Footer"; import Hero from "@/authly/components/landing/Hero"; import Navbar from "@/authly/components/landing/Navbar"; +/** + * Top-level home page component that composes the landing page layout. + * + * @returns The page's root JSX element containing Navbar, Hero, Features, CodeExamples, and Footer arranged vertically within a main container. + */ export default function Home() { return (
@@ -18,4 +23,4 @@ export default function Home() {
); -} +} \ No newline at end of file diff --git a/apps/web/src/components/dashboard/admin/services/OverviewTab.tsx b/apps/web/src/components/dashboard/admin/services/OverviewTab.tsx index 6c7d6b4..078ecc1 100644 --- a/apps/web/src/components/dashboard/admin/services/OverviewTab.tsx +++ b/apps/web/src/components/dashboard/admin/services/OverviewTab.tsx @@ -10,6 +10,14 @@ interface OverviewTabProps { serviceId: string; } +/** + * Renders the overview tab for an admin service: loads service data, handles loading and error states, and presents an editable ServiceForm. + * + * Shows an error toast when the service fails to load. + * + * @param serviceId - The ID of the service to load and edit. + * @returns The OverviewTab React element. + */ export function OverviewTab({ serviceId }: OverviewTabProps) { const { data: response, isLoading, isError } = useAdminService(serviceId); const { mutate: updateService, isPending: isUpdating } = useUpdateService(); @@ -38,4 +46,4 @@ export function OverviewTab({ serviceId }: OverviewTabProps) { isUpdating={isUpdating} /> ); -} +} \ No newline at end of file diff --git a/apps/web/src/components/dashboard/admin/services/overview/AuthenticationSection.tsx b/apps/web/src/components/dashboard/admin/services/overview/AuthenticationSection.tsx index 8f6ca7e..536e796 100644 --- a/apps/web/src/components/dashboard/admin/services/overview/AuthenticationSection.tsx +++ b/apps/web/src/components/dashboard/admin/services/overview/AuthenticationSection.tsx @@ -19,6 +19,21 @@ interface AuthenticationSectionProps { disabled?: boolean; } +/** + * Render the Authentication section of the client settings UI, showing and managing redirect URIs and allowed scopes. + * + * Renders an animated list of `redirectURIs` with optional remove buttons, an input and Add control for new redirect URIs (Enter key triggers add), and a TagInput for `allowedScopes`. + * + * @param redirectURIs - List of redirect URIs to display + * @param allowedScopes - Current allowed OAuth scopes + * @param newRedirectURI - Current value of the new redirect URI input + * @param onAllowedScopesChange - Called with the updated scopes when the TagInput changes + * @param onNewRedirectURIChange - Called with the input value when the new redirect URI changes + * @param onAddRedirect - Called to add the value from `newRedirectURI` to the list + * @param onRemoveRedirect - Called with the index of a redirect URI to remove + * @param disabled - When true, disables inputs and hides remove controls (default: false) + * @returns The React element for the Authentication section + */ export function AuthenticationSection({ redirectURIs, allowedScopes, @@ -108,4 +123,4 @@ export function AuthenticationSection({ ); -} +} \ No newline at end of file diff --git a/apps/web/src/components/dashboard/admin/services/overview/BasicDetailsSection.tsx b/apps/web/src/components/dashboard/admin/services/overview/BasicDetailsSection.tsx index 9adee83..bae46be 100644 --- a/apps/web/src/components/dashboard/admin/services/overview/BasicDetailsSection.tsx +++ b/apps/web/src/components/dashboard/admin/services/overview/BasicDetailsSection.tsx @@ -15,6 +15,18 @@ interface BasicDetailsSectionProps { disabled?: boolean; } +/** + * Render the Basic Details form section for editing a service's name, description, and primary domain. + * + * @param name - The current service name displayed in the Service Name input. + * @param description - The current service description displayed in the Description input. + * @param domain - The current primary domain displayed in the Primary Domain input. + * @param onNameChange - Callback invoked with the updated name when the Service Name input changes. + * @param onDescriptionChange - Callback invoked with the updated description when the Description input changes. + * @param onDomainChange - Callback invoked with the updated domain when the Primary Domain input changes. + * @param disabled - When `true`, disables all inputs (defaults to `false`). + * @returns A React element containing the titled section with three labeled inputs and associated hints/icons. + */ export function BasicDetailsSection({ name, description, @@ -61,4 +73,4 @@ export function BasicDetailsSection({ ); -} +} \ No newline at end of file diff --git a/apps/web/src/components/dashboard/admin/services/overview/CredentialsCard.tsx b/apps/web/src/components/dashboard/admin/services/overview/CredentialsCard.tsx index a52eae4..d97e97e 100644 --- a/apps/web/src/components/dashboard/admin/services/overview/CredentialsCard.tsx +++ b/apps/web/src/components/dashboard/admin/services/overview/CredentialsCard.tsx @@ -7,6 +7,15 @@ interface CredentialsCardProps { clientSecret: string | null; } +/** + * Render a credentials card showing the client ID and client secret with optional copy controls. + * + * The client ID is shown in plain text with a copy button. The client secret, when provided, is displayed masked and includes a copy button; when `null`, the card indicates the client is public. + * + * @param clientId - The client identifier to display and copy + * @param clientSecret - The client secret to display (masked) and copy, or `null` to indicate a public client + * @returns The JSX element representing the credentials card + */ export function CredentialsCard({ clientId, clientSecret }: CredentialsCardProps) { return (
@@ -45,4 +54,4 @@ export function CredentialsCard({ clientId, clientSecret }: CredentialsCardProps
); -} +} \ No newline at end of file diff --git a/apps/web/src/components/dashboard/admin/services/overview/MetadataCard.tsx b/apps/web/src/components/dashboard/admin/services/overview/MetadataCard.tsx index 0361ad7..f490f49 100644 --- a/apps/web/src/components/dashboard/admin/services/overview/MetadataCard.tsx +++ b/apps/web/src/components/dashboard/admin/services/overview/MetadataCard.tsx @@ -8,6 +8,16 @@ interface MetadataCardProps { serviceId: string; } +/** + * Render a compact metadata panel showing creation time, last update, and the service identifier with a copy control. + * + * Created and updated timestamps are parsed with the `Date` constructor and displayed using the runtime locale. + * + * @param createdAt - Timestamp string for when the resource was created; displayed as a localized date/time string + * @param updatedAt - Timestamp string for the last update; displayed as a localized date/time string + * @param serviceId - Service identifier shown in a truncated field with a button to copy the value + * @returns A React element that renders the metadata card UI + */ export function MetadataCard({ createdAt, updatedAt, serviceId }: MetadataCardProps) { return (
@@ -37,4 +47,4 @@ export function MetadataCard({ createdAt, updatedAt, serviceId }: MetadataCardPr
); -} +} \ No newline at end of file diff --git a/apps/web/src/components/dashboard/admin/services/overview/SaveActions.tsx b/apps/web/src/components/dashboard/admin/services/overview/SaveActions.tsx index 3d2584c..1f9f78f 100644 --- a/apps/web/src/components/dashboard/admin/services/overview/SaveActions.tsx +++ b/apps/web/src/components/dashboard/admin/services/overview/SaveActions.tsx @@ -13,6 +13,15 @@ interface SaveActionsProps { disabled?: boolean; } +/** + * Render an action bar that displays an unsaved changes indicator and a save button. + * + * @param hasChanges - Whether there are unsaved changes to save + * @param isSaving - Whether a save operation is currently in progress + * @param onSave - Handler invoked when the save button is clicked (receives the form event) + * @param disabled - If true, disables the save button regardless of change or saving state + * @returns A JSX element containing the save actions bar + */ export function SaveActions({ hasChanges, isSaving, onSave, disabled = false }: SaveActionsProps) { return (
@@ -40,4 +49,4 @@ export function SaveActions({ hasChanges, isSaving, onSave, disabled = false }:
); -} +} \ No newline at end of file diff --git a/apps/web/src/components/dashboard/admin/services/overview/ServiceForm.tsx b/apps/web/src/components/dashboard/admin/services/overview/ServiceForm.tsx index 22e4984..9230010 100644 --- a/apps/web/src/components/dashboard/admin/services/overview/ServiceForm.tsx +++ b/apps/web/src/components/dashboard/admin/services/overview/ServiceForm.tsx @@ -23,6 +23,20 @@ interface ServiceFormProps { isUpdating: boolean; } +/** + * Renders a form for viewing and editing a service's details in the admin UI. + * + * The form initializes fields from `service`, allows adding/removing redirect URIs (with URL format and duplicate validation), + * and submits changes via the provided `updateService` mutation. It disables editing and prevents updates for the default Authly service + * and surfaces success and API error messages via toasts. + * + * @param service - The service object providing initial field values and metadata. + * @param serviceId - The identifier used when submitting updates for the service. + * @param updateService - Mutation function used to persist changes to the service. + * @param isUpdating - Whether an update request is in progress; disables save actions while true. + * + * @returns The React element for the service edit form. + */ export function ServiceForm({ service, serviceId, updateService, isUpdating }: ServiceFormProps) { const isDefaultService = isDefaultAuthlyService(service.id) || isDefaultAuthlyService(service.client_id); @@ -179,4 +193,4 @@ export function ServiceForm({ service, serviceId, updateService, isUpdating }: S ); -} +} \ No newline at end of file diff --git a/apps/web/src/components/dashboard/admin/services/overview/StatusCard.tsx b/apps/web/src/components/dashboard/admin/services/overview/StatusCard.tsx index e7af411..7803065 100644 --- a/apps/web/src/components/dashboard/admin/services/overview/StatusCard.tsx +++ b/apps/web/src/components/dashboard/admin/services/overview/StatusCard.tsx @@ -9,6 +9,14 @@ interface StatusCardProps { disabled?: boolean; } +/** + * Renders a status card with a label and a toggle switch for activating or deactivating a service. + * + * @param isActive - Whether the service is currently active + * @param onToggle - Callback invoked when the switch is toggled + * @param disabled - If true, disables user interaction with the switch + * @returns The rendered React element for the status card + */ export function StatusCard({ isActive, onToggle, disabled = false }: StatusCardProps) { return (
@@ -27,4 +35,4 @@ export function StatusCard({ isActive, onToggle, disabled = false }: StatusCardP
); -} +} \ No newline at end of file diff --git a/apps/web/src/components/dashboard/admin/users/EditUserModal.tsx b/apps/web/src/components/dashboard/admin/users/EditUserModal.tsx index 50df16d..27a96cb 100644 --- a/apps/web/src/components/dashboard/admin/users/EditUserModal.tsx +++ b/apps/web/src/components/dashboard/admin/users/EditUserModal.tsx @@ -17,15 +17,14 @@ interface EditUserModalProps { } /** - * Renders a modal containing a form to edit a user's username, email, and active status. + * Render a modal form for editing a user's username, email, and active status. * - * Validates input with the updateUserRequestSchema, displays field-level validation messages - * and server update errors, and submits changes via the useUpdateUser hook. Calls `onClose` - * when the update succeeds or when the Cancel button is clicked. + * Validates input, displays field-level and global update errors, submits changes, + * and closes the modal on successful update or when the Cancel button is clicked. * - * @param user - The user object to edit (pre-fills the form). - * @param onClose - Callback invoked to close the modal. - * @returns The modal content element for editing the user. + * @param user - The user to edit; used to pre-fill form fields + * @param onClose - Callback invoked to close the modal + * @returns The modal content element for editing the user */ export function EditUserModalContent({ user, onClose }: EditUserModalProps) { const { mutate: updateUser, isPending, error: updateError } = useUpdateUser(); @@ -129,4 +128,4 @@ export function EditUserModalContent({ user, onClose }: EditUserModalProps) { ); -} +} \ No newline at end of file diff --git a/apps/web/src/components/ui/CopyButton.tsx b/apps/web/src/components/ui/CopyButton.tsx index ad1f142..4009920 100644 --- a/apps/web/src/components/ui/CopyButton.tsx +++ b/apps/web/src/components/ui/CopyButton.tsx @@ -12,6 +12,15 @@ interface CopyButtonProps { className?: string; } +/** + * Renders a button that copies a provided string to the clipboard and shows a success toast. + * + * @param value - The string to copy to the clipboard when the button is activated. + * @param ariaLabel - Accessible label used for the button and the success message. + * @param onCopy - Optional callback invoked after a successful copy. + * @param className - Optional CSS class(es) applied to the button element. + * @returns A button element that copies `value` when activated and updates its icon and aria-label to reflect the copied state. + */ export function CopyButton({ value, ariaLabel, onCopy, className }: CopyButtonProps) { const [copied, copy] = useCopyToClipboard(); @@ -35,4 +44,4 @@ export function CopyButton({ value, ariaLabel, onCopy, className }: CopyButtonPr /> ); -} +} \ No newline at end of file diff --git a/apps/web/src/components/ui/FormField.tsx b/apps/web/src/components/ui/FormField.tsx index 94d20e9..7960874 100644 --- a/apps/web/src/components/ui/FormField.tsx +++ b/apps/web/src/components/ui/FormField.tsx @@ -9,6 +9,16 @@ interface FormFieldProps { className?: string; } +/** + * Renders a labeled form field container with optional hint or error text. + * + * @param label - Optional label text displayed above the field. + * @param error - Optional error message; when present it is shown instead of the hint and styled as an error. + * @param hint - Optional helper text shown when `error` is not present. + * @param children - The field content (e.g., input, select, textarea). + * @param className - Additional CSS class names applied to the container. + * @returns A JSX element containing the composed form field. + */ export function FormField({ label, error, hint, children, className }: FormFieldProps) { return (
@@ -26,4 +36,4 @@ export function FormField({ label, error, hint, children, className }: FormField )}
); -} +} \ No newline at end of file diff --git a/apps/web/src/components/ui/TagInput.tsx b/apps/web/src/components/ui/TagInput.tsx index 0cbe21d..6c877a4 100644 --- a/apps/web/src/components/ui/TagInput.tsx +++ b/apps/web/src/components/ui/TagInput.tsx @@ -15,6 +15,20 @@ interface TagInputProps { "aria-label"?: string; } +/** + * Render a tag editor with inline removable tags and an input for adding new tags. + * + * Adds a trimmed tag when Enter, space, or comma is pressed (duplicates are ignored); when the input is empty, Backspace removes the last tag. + * + * @param value - Current list of tags + * @param onChange - Callback invoked with the updated tag list + * @param placeholder - Placeholder text shown only when there are no tags + * @param className - Additional CSS classes applied to the container + * @param disabled - When true, prevents adding/removing tags and styles the component as disabled + * @param error - When true, applies error styling + * @param aria-label - Accessibility label for the input element + * @returns The rendered React element for the tag input component + */ export function TagInput({ value, onChange, @@ -100,4 +114,4 @@ export function TagInput({ /> ); -} +} \ No newline at end of file diff --git a/apps/web/src/lib/hooks/admin/usePermissions.ts b/apps/web/src/lib/hooks/admin/usePermissions.ts index 4c9b708..06a8443 100644 --- a/apps/web/src/lib/hooks/admin/usePermissions.ts +++ b/apps/web/src/lib/hooks/admin/usePermissions.ts @@ -2,7 +2,11 @@ import { useQueryClient } from "@tanstack/react-query"; import { $api } from "@/authly/lib/api/client"; /** - * Hook to fetch permissions for a service. + * Fetches permission definitions for a given service, optionally filtered by resource and paginated. + * + * @param serviceId - The service identifier used as the `service_id` query parameter; the query is disabled when empty + * @param params - Optional query filters: `resource` to narrow by resource, `limit` and `offset` for pagination + * @returns The query result containing permissions that match the provided `service_id` and filters */ export function useServicePermissions( serviceId: string, @@ -26,7 +30,12 @@ export function useServicePermissions( } /** - * Hook to create a new permission definition. + * Creates a permission definition for a service and exposes a mutation hook. + * + * On successful creation, invalidates cached GET /admin/permissions queries scoped to the + * created permission's `service_id` and also invalidates the general permissions query to refresh lists. + * + * @returns The mutation result object for performing the create operation and observing its state. */ export function useCreatePermission() { const queryClient = useQueryClient(); @@ -47,7 +56,9 @@ export function useCreatePermission() { } /** - * Hook to update a permission definition. + * Updates an existing permission definition. + * + * @returns The mutation object for performing a PUT to `/admin/permissions/{id}`; on success it invalidates the cached permission list queries. */ export function useUpdatePermission() { const queryClient = useQueryClient(); @@ -60,7 +71,9 @@ export function useUpdatePermission() { } /** - * Hook to delete a permission definition. + * Provides a mutation hook for deleting an administrative permission definition. + * + * @returns A mutation result that deletes a permission by id; on success it invalidates the cached permission list (`["get", "/admin/permissions"]`) so list data is refreshed. */ export function useDeletePermission() { const queryClient = useQueryClient(); @@ -70,4 +83,4 @@ export function useDeletePermission() { queryClient.invalidateQueries({ queryKey: ["get", "/admin/permissions"] }); }, }); -} +} \ No newline at end of file diff --git a/apps/web/src/lib/hooks/admin/useRoles.ts b/apps/web/src/lib/hooks/admin/useRoles.ts index b8dc8bb..adc9702 100644 --- a/apps/web/src/lib/hooks/admin/useRoles.ts +++ b/apps/web/src/lib/hooks/admin/useRoles.ts @@ -2,7 +2,10 @@ import { useQueryClient } from "@tanstack/react-query"; import { $api } from "@/authly/lib/api/client"; /** - * Hook to fetch roles for a service. + * Fetches roles for the given service. + * + * @param serviceId - ID of the service used to filter roles + * @returns The query result containing the roles for the specified service */ export function useServiceRoles(serviceId: string) { return $api.useQuery( @@ -22,7 +25,9 @@ export function useServiceRoles(serviceId: string) { } /** - * Hook to create a new role. + * Creates a new role and exposes a mutation hook for performing that action. + * + * @returns A mutation hook that posts a new role; on success it invalidates the cached roles for the affected service and the overall roles list. */ export function useCreateRole() { const queryClient = useQueryClient(); @@ -38,7 +43,9 @@ export function useCreateRole() { } /** - * Hook to update a role. + * Creates a mutation hook for updating an existing admin role. + * + * @returns A mutation hook that updates a role at `/admin/roles/{id}` and invalidates the cached roles list (`["get", "/admin/roles"]`) on success. */ export function useUpdateRole() { const queryClient = useQueryClient(); @@ -51,7 +58,9 @@ export function useUpdateRole() { } /** - * Hook to delete a role. + * Deletes a role by id and refreshes the cached roles list when the deletion succeeds. + * + * @returns The mutation hook for deleting a role. Calling `mutate`/`mutateAsync` requires variables that include the role `id`. */ export function useDeleteRole() { const queryClient = useQueryClient(); @@ -61,4 +70,4 @@ export function useDeleteRole() { queryClient.invalidateQueries({ queryKey: ["get", "/admin/roles"] }); }, }); -} +} \ No newline at end of file diff --git a/apps/web/src/proxy.ts b/apps/web/src/proxy.ts index 4a2c5c2..05e9b91 100644 --- a/apps/web/src/proxy.ts +++ b/apps/web/src/proxy.ts @@ -6,6 +6,14 @@ const AUTH_PATHS = ["/auth/login", "/auth/register"]; import { OIDC_CONFIG } from "./lib/config"; +/** + * Enforces route-level authentication and performs OIDC redirect handling for incoming requests. + * + * For requests to protected paths, redirects unauthenticated users to the OIDC authorize endpoint with client, redirect, response type, and scope parameters. For authenticated requests to authentication pages, attempts to reconstruct and redirect to an authorize URL from an `oidc_params` query value; if reconstruction fails or `oidc_params` is absent, redirects to `/dashboard`. For all other requests, allows the request to continue unmodified. + * + * @param request - The incoming Next.js request to evaluate and possibly redirect. + * @returns A NextResponse that redirects to an OIDC authorize URL, redirects to `/dashboard`, or continues the request pipeline via `NextResponse.next()`. + */ export function proxy(request: NextRequest) { const { pathname } = request.nextUrl; const hasSession = request.cookies.has("session"); @@ -44,4 +52,4 @@ export function proxy(request: NextRequest) { export const config = { matcher: ["/((?!api|_next/static|_next/image|favicon.ico|images).*)"], -}; +}; \ No newline at end of file