@facteurjs/react

The @facteurjs/react package provides React hooks and components to facilitate Facteur integration in React applications. It is built on top of Tanstack Query for query and cache management, and uses @facteurjs/client internally.

Installation

pnpm install @facteurjs/react @tanstack/react-query

Configure the Facteur provider and Tanstack Query in your application:

import { FacteurProvider } from '@facteurjs/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <FacteurProvider
        apiUrl="https://your-api.com"
        notifiableId={currentUser.id}
      >
        <YourApp />
      </FacteurProvider>
    </QueryClientProvider>
  )
}

FacteurProvider Props:

apiUrl (string, required): Your Facteur API URL
notifiableId (string|number): Connected user ID

Type Safety

For better type safety with your custom notification data:

// types/facteur.ts
declare module '@facteurjs/react' {
  interface DatabaseContent {
    orderId?: number
    productName?: string
    // ... your custom data types
  }
}

React Hooks

useNotifications()

Hook to retrieve the list of notifications with automatic caching.

Parameters:

page (number, optional): Page number
limit (number, optional): Number of items per page
status (string, optional): Filter by status ('read' | 'seen' | 'unread' | 'unseen')
tenantId (string, optional): Tenant ID

const { data: notifications, isLoading, error } = useNotifications({
  page: 1,
  limit: 10,
  status: 'unread'
})

useMarkAsRead()

Hook to mark a notification as read with automatic cache invalidation.

const markAsRead = useMarkAsRead()

const handleMarkAsRead = () => {
  markAsRead.mutate({ notificationId: notification.id })
}

useMarkAsSeen()

Hook to mark a notification as seen with automatic cache invalidation.

const markAsSeen = useMarkAsSeen()

const handleMarkAsSeen = () => {
  markAsSeen.mutate({ notificationId: notification.id })
}

useMarkAllAsRead()

Hook to mark all notifications as read.

const markAllAsRead = useMarkAllAsRead()

const handleMarkAllAsRead = () => {
  markAllAsRead.mutate({ tenantId: 'optional-tenant-id' })
}

useMarkAllAsSeen()

Hook to mark all notifications as seen.

const markAllAsSeen = useMarkAllAsSeen()

const handleMarkAllAsSeen = () => {
  markAllAsSeen.mutate({ tenantId: 'optional-tenant-id' })
}

usePreferences()

Hook to retrieve notification preferences with caching.