@rxbenefits/hooks

Custom React hooks for RxBenefits applications - comprehensive set of 58 hooks for API interactions, permissions, entity management, and utilities

Overview

The @rxbenefits/hooks package provides a comprehensive collection of custom React hooks used across RxBenefits applications. These hooks encapsulate common patterns for data fetching, state management, permissions, and business logic.

🚀 Features

• 58 custom hooks covering all major use cases
• React Query integration for optimal data fetching
• Auth0 integration for authentication and permissions
• Type-safe with full TypeScript support
• Tree-shakeable - only import what you need
• Comprehensive documentation and examples
• Well-tested with Jest and React Testing Library

📦 Installation

npm install @rxbenefits/hooks

Peer Dependencies

This package requires the following peer dependencies:

npm install @auth0/auth0-react @datadog/browser-rum react react-query antd

Dependencies

• @rxbenefits/contexts - Feature flags and module configuration
• @rxbenefits/types - TypeScript type definitions
• @rxbenefits/constants - Application constants
• @rxbenefits/utils - Utility functions
• @rxbenefits/ui - UI component types

⚠️ Important Note: This package currently depends on @optimize/api as a peer dependency. The API library will be migrated in a future release. For now, ensure @optimize/api is available in your consuming application.

📚 Hook Categories

🔧 Utility Hooks

General-purpose React hooks for common patterns:

• usePagination - Table pagination management
• useEffectOnce - Run effect only once on mount
• useURLQuery - Parse URL query parameters
• useTitle - Set document title
• useRelativeTime - Display relative timestamps
• useDisableRefetchOnFocus - Disable React Query refetch on focus

🎯 Feature Flag & Context Hooks

Hooks for accessing feature flags and module configuration:

• useFeatureFlags - Access feature flags
• useGenAIFeatureFlags - GenAI-specific feature flags
• useShowRolesPage - Roles page visibility
• useShowUserPermissions - User permissions visibility
• useModuleConfig - Module configuration

🔐 Permission & Role Hooks

Authorization and access control:

• usePermissions - Extract and manage user permissions
• useCheckAllPermissions - Check if user has all permissions
• useCheckAnyPermissions - Check if user has any permission
• useDeveloper - Check developer status
• useUsersRoles - Manage user roles
• useRoles - Access role data
• useFinancialClaimDetail - Invoice claim detail permissions
• useFinancialClaimSummary - Invoice claim summary permissions
• useFinancialInvoice - Invoice permissions
• useFinancialInvoiceClaimExtract - Invoice claim extract permissions

👤 Entity Hooks

Hooks for managing domain entities:

• useUser - Current user data and profile
• useCurrentUser - Enhanced current user with access control
• useUsers - User list management
• useEmployee - Employee data management
• useEmployeeQuery - Advanced employee queries
• useDependent - Dependent data management
• useOrganization - Organization data
• useAppAccess - Application access control
• useApplications - Available applications
• useGroupSummary - Group summary data
• useInvoice - Invoice management
• useLocations - Location data
• useFiles - File upload and management

🌐 API Integration Hooks

Hooks wrapping specific API services:

• Communication Manager API
  • useCommunicationManager
• DataMapper API
  • useEligibilityImport
  • useImportSchema
  • useTemplates
• Evaluate API
  • useProspectOpps
• Keystone API
  • useEvents
  • useLists
  • useListTypes
• Member Issues API
  • useMemberIssues
• MembersHub API
  • useMembersHub
• Plan Provision API
  • usePlanProvision
• Protect API
  • useConditions
  • useInterventions

⚙️ Environment & Configuration

• useEnvironment - Environment configuration

🎯 Usage Examples

Basic Hook Usage

import { usePagination } from '@rxbenefits/hooks';

function MyTable() {
  const {
    currentPage,
    limit,
    pagination,
    setCount,
    setParams,
  } = usePagination('my-table');

  // Use pagination props with Ant Design table
  return (
    <Table
      dataSource={data}
      columns={columns}
      pagination={pagination}
    />
  );
}

Permission Hooks

import { useCheckAllPermissions } from '@rxbenefits/hooks';

function AdminPanel() {
  const hasAdminAccess = useCheckAllPermissions([
    'view:admin',
    'edit:config',
  ]);

  if (!hasAdminAccess) {
    return <AccessDenied />;
  }

  return <AdminDashboard />;
}

User Management

import { useUser } from '@rxbenefits/hooks';

function UserProfile() {
  const {
    user,
    useUserProfile,
    useUserMutation,
  } = useUser();

  const { data: profile, isLoading } = useUserProfile();
  const { mutate: updateProfile } = useUserMutation();

  const handleUpdate = (updates) => {
    updateProfile({ ...profile, ...updates });
  };

  return (
    <ProfileForm
      data={profile}
      onSubmit={handleUpdate}
      loading={isLoading}
    />
  );
}

Feature Flags

import { useFeatureFlags } from '@rxbenefits/hooks';

function NewFeature() {
  const { featureFlags, loading } = useFeatureFlags();

  const isEnabled = featureFlags.some(
    (flag) =>
      flag.portalFeature === 'new_feature' && flag.canView
  );

  if (!isEnabled) {
    return null;
  }

  return <NewFeatureComponent />;
}

API Integration

import { useMemberIssues } from '@rxbenefits/hooks';

function IssuesPanel({ memberId }) {
  const {
    useGetMemberIssue,
    useDeleteDocument,
  } = useMemberIssues();

  const { data: issue, isLoading } = useGetMemberIssue(
    memberId
  );
  const { mutate: deleteDoc } = useDeleteDocument();

  return (
    <IssuesList
      issues={issue}
      onDeleteDocument={deleteDoc}
      loading={isLoading}
    />
  );
}

🛠️ Development

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0

Setup

# Install dependencies
npm install

# Run type checking
npm run typecheck

# Run linter
npm run lint

# Run tests
npm test

# Build package
npm run build

Testing

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

⚠️ Migration Notes

This package is part of the RxBenefits monorepo migration. Key considerations:

1. API Dependency: Currently depends on @optimize/api as a peer dependency. This will be updated when the API library is migrated.

2. Type Safety: Full TypeScript compilation requires @optimize/api to be available. Runtime functionality is not affected.

3. Circular Dependencies: All circular dependencies have been resolved. Hooks import from other hooks using relative paths.

4. Breaking Changes: The FeatureFlagsProvider (from @rxbenefits/contexts) now requires a userId prop instead of using the useUser hook internally.

📝 Migration from Monorepo

If you're migrating from the monorepo:

// Before (monorepo)
import { usePagination, useUser } from '@optimize/hooks';

// After (npm package)
import { usePagination, useUser } from '@rxbenefits/hooks';

All hook exports remain the same - only the import path changes.

🔄 React Query Integration

Most hooks use React Query for data fetching. Ensure your app is wrapped with QueryClientProvider:

import { QueryClient, QueryClientProvider } from 'react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
    </QueryClientProvider>
  );
}

🔒 Auth0 Integration

Permission and user hooks require Auth0 setup:

import { Auth0Provider } from '@auth0/auth0-react';

function App() {
  return (
    <Auth0Provider
      domain="your-domain.auth0.com"
      clientId="your-client-id"
      redirectUri={window.location.origin}
    >
      <YourApp />
    </Auth0Provider>
  );
}

📄 License

MIT © RxBenefits

🤝 Contributing

This package is part of the RxBenefits infrastructure. For contribution guidelines, please refer to the main RxBenefits documentation.

📞 Support

For issues and questions:

• GitHub Issues: https://github.com/rxbenefits/rxbenefits-hooks/issues
• Internal Slack: #engineering

📚 Related Packages

• @rxbenefits/types - TypeScript types
• @rxbenefits/constants - Constants
• @rxbenefits/utils - Utilities
• @rxbenefits/ui - UI components
• @rxbenefits/contexts - Context providers
• @rxbenefits/forms - Form schemas

🗺️ Roadmap

• [ ] Migrate API library to remove @optimize/api peer dependency
• [ ] Add Storybook documentation for hook examples
• [ ] Migrate to TanStack Query v5 (from React Query v3)
• [ ] Add performance monitoring hooks
• [ ] Improve test coverage to 80%+