* )
* }
* ```
*/
export function useNotifications({
userId,
enabled = true,
listNotifications,
markNotificationAsRead,
markAllNotificationsAsRead,
buildCSRFHeaders,
onInvalidate,
}: UseNotificationsOptions): UseNotificationsReturn {
const [notifications, setNotifications] = useState([])
const [isLoading, setIsLoading] = useState(true)
const [error, setError] = useState(null)
const [isConnected, setIsConnected] = useState(false)
const socketRef = useRef(null)
const channelRef = useRef(null)
// Track if component is mounted to prevent state updates after unmount (React StrictMode safety)
const mountedRef = useRef(true)
// Use the Zustand counter store
const setCounter = useCounterStore((state: CounterState) => state.setCounter)
const setCounters = useCounterStore((state: CounterState) => state.setCounters)
const incrementCounter = useCounterStore((state: CounterState) => state.incrementCounter)
const unreadCount = useCounterStore((state: CounterState) => state.counters.unread_notifications)
// Fetch notifications from backend
const fetchNotifications = useCallback(async () => {
if (!enabled || !userId) return
setIsLoading(true)
setError(null)
try {
const result = await listNotifications({
headers: buildCSRFHeaders(),
fields: [
'id',
'title',
'message',
'type',
'source',
'actionUrl',
'actionLabel',
'read',
'readAt',
'occurredAt',
'insertedAt',
],
input: { userId },
})
if (result.success) {
const data = result.data
setNotifications(data)
// Update the unread counter
const unread = data.filter((n: Notification) => !n.read).length
setCounter('unread_notifications', unread)
} else {
setError('Failed to fetch notifications')
}
} catch (err) {
setError(err instanceof Error ? err.message : 'Failed to fetch notifications')
} finally {
setIsLoading(false)
}
}, [enabled, userId, listNotifications, buildCSRFHeaders, setCounter])
// Mark single notification as read
const markAsRead = useCallback(
async (notificationId: string) => {
try {
const result = await markNotificationAsRead({
headers: buildCSRFHeaders(),
identity: notificationId,
fields: ['id', 'read'],
})
if (result.success) {
setNotifications((prev) =>
prev.map((n) => (n.id === notificationId ? { ...n, read: true } : n))
)
// Decrement counter (uses functional update, no stale closure)
incrementCounter('unread_notifications', -1)
}
} catch (err) {
console.error('[AshDispatch] Failed to mark notification as read:', err)
}
},
[markNotificationAsRead, buildCSRFHeaders, incrementCounter]
)
// Mark all notifications as read
const markAllAsRead = useCallback(async () => {
if (!userId) return
try {
const result = await markAllNotificationsAsRead({
headers: buildCSRFHeaders(),
input: { userId },
})
if (result.success) {
setNotifications((prev) => prev.map((n) => ({ ...n, read: true })))
setCounter('unread_notifications', 0)
}
} catch (err) {
console.error('[AshDispatch] Failed to mark all notifications as read:', err)
}
}, [userId, markAllNotificationsAsRead, buildCSRFHeaders, setCounter])
// Connect to Phoenix channel for real-time updates
const connectChannel = useCallback(async () => {
if (!userId || !enabled) return
// If there's already a channel, leave it first
if (channelRef.current) {
channelRef.current.leave()
channelRef.current = null
}
try {
// Fetch socket token from your API
const response = await fetch('/api/inbox/socket-token', {
headers: buildCSRFHeaders(),
credentials: 'include',
})
// Check if component was unmounted during async wait (React StrictMode safety)
if (!mountedRef.current) return
if (!response.ok) {
return // Socket connection is optional
}
const data = await response.json()
// Check again after parsing JSON
if (!mountedRef.current) return
if (!data.success) {
return
}
const token = data.data.token
// Create socket connection
const socket = new Socket('/socket', {
params: { token },
})
socket.onError(() => {
if (mountedRef.current) setIsConnected(false)
})
socket.onClose(() => {
if (mountedRef.current) setIsConnected(false)
})
socket.connect()
socketRef.current = socket
// Join the channel for notifications (configurable via :channel_topic)
const channel = socket.channel(`#{channel_topic()}:${userId}`, {})
// Listen for initial state (bulk counter load on connect)
channel.on('initial_state', (rawPayload: unknown) => {
const payload = rawPayload as { counters?: Record }
if (!mountedRef.current) return
if (payload.counters) {
// Filter to only valid counters and update the store
const validCounters: Record = {}
for (const [key, value] of Object.entries(payload.counters)) {
if (isValidCounter(key)) {
validCounters[key] = value
}
}
setCounters(validCounters)
}
})
// Listen for new notifications
channel.on('new_notification', (rawNotification: unknown) => {
const notification = rawNotification as Notification
if (!mountedRef.current) return
setNotifications((prev) => [notification, ...prev])
if (!notification.read) {
// Use incrementCounter to avoid stale closure issues
incrementCounter('unread_notifications', 1)
}
// Trigger query invalidation if specified
if (notification.invalidates?.length && onInvalidate) {
onInvalidate(notification.invalidates)
}
})
// Listen for counter updates (from UserChannel.broadcast_counter or custom broadcast)
// Note: phoenix-js types callback som `(payload: unknown)`; widens till
// `unknown` och narrowar via `as`-cast så TS-strict consumers (saleflow
// m.fl.) inte failar på contravarians.
channel.on('counter_updated', (rawPayload: unknown) => {
const payload = rawPayload as { counter: string; value: number; metadata?: { invalidate_queries?: string[] } }
if (!mountedRef.current) return
if (isValidCounter(payload.counter)) {
setCounter(payload.counter as CounterName, payload.value)
}
// Trigger query invalidation if specified in metadata
if (payload.metadata?.invalidate_queries?.length && onInvalidate) {
onInvalidate(payload.metadata.invalidate_queries)
}
})
channel
.join()
.receive('ok', () => {
if (mountedRef.current) setIsConnected(true)
})
.receive('error', () => {
if (mountedRef.current) setIsConnected(false)
})
channelRef.current = channel
} catch {
// Socket connection is optional
}
}, [userId, enabled, buildCSRFHeaders, setCounter, setCounters, incrementCounter, onInvalidate])
// Initial fetch
useEffect(() => {
fetchNotifications()
}, [fetchNotifications])
// Connect to channel
useEffect(() => {
mountedRef.current = true
connectChannel()
return () => {
mountedRef.current = false
if (channelRef.current) {
channelRef.current.leave()
channelRef.current = null
}
if (socketRef.current) {
socketRef.current.disconnect()
socketRef.current = null
}
}
}, [connectChannel])
return {
notifications,
unreadCount,
isLoading,
error,
isConnected,
markAsRead,
markAllAsRead,
refresh: fetchNotifications,
}
}
"""
end
# ============================================================================
# Additional SDK Generators (Provider, UI Components, README)
# ============================================================================
defp generate_notification_provider_content do
"""
// ⚠️ AUTO-GENERATED by mix ash_dispatch.gen — DO NOT EDIT
// Source: projects/ash_dispatch/lib/mix/tasks/ash_dispatch.gen.ex
// To modify, change the generator and re-run: mix ash_dispatch.gen
// Provider component that initializes notification state
// Detects SocketProvider context and uses shared socket when available
"use client"
import { createContext, useContext, useEffect, useCallback, useState, useRef, type ReactNode } from 'react'
import { useNotifications, type Notification, type UseNotificationsReturn, type UseNotificationsOptions } from './hooks/use-notifications'
import { useSocketContext } from './socket-provider'
import { useCounterStore, type CounterState } from './store'
// ============================================================================
// Context
// ============================================================================
const NotificationContext = createContext(null)
/**
* Hook to access notification context.
* Must be used within a NotificationProvider.
*/
export function useNotificationContext(): UseNotificationsReturn {
const context = useContext(NotificationContext)
if (!context) {
throw new Error('useNotificationContext must be used within a NotificationProvider')
}
return context
}
// ============================================================================
// Shared Socket Implementation
// ============================================================================
/** Uses the shared SocketProvider for real-time events instead of its own socket. */
function useNotificationsWithSharedSocket({
userId,
enabled = true,
listNotifications,
markNotificationAsRead,
markAllNotificationsAsRead,
buildCSRFHeaders,
onInvalidate,
}: UseNotificationsOptions): UseNotificationsReturn {
const socket = useSocketContext()!
const [notifications, setNotifications] = useState([])
const [isLoading, setIsLoading] = useState(true)
const [error, setError] = useState(null)
const setCounter = useCounterStore((state: CounterState) => state.setCounter)
const incrementCounter = useCounterStore((state: CounterState) => state.incrementCounter)
const unreadCount = useCounterStore((state: CounterState) => state.counters.unread_notifications)
const onInvalidateRef = useRef(onInvalidate)
onInvalidateRef.current = onInvalidate
// Fetch notifications from backend (same as standalone)
const fetchNotifications = useCallback(async () => {
if (!enabled || !userId) return
setIsLoading(true)
setError(null)
try {
const result = await listNotifications({
headers: buildCSRFHeaders(),
fields: [
'id', 'title', 'message', 'type', 'source',
'actionUrl', 'actionLabel', 'read', 'readAt',
'occurredAt', 'insertedAt',
],
input: { userId },
})
if (result.success) {
const data = result.data
setNotifications(data)
const unread = data.filter((n: Notification) => !n.read).length
setCounter('unread_notifications', unread)
} else {
setError('Failed to fetch notifications')
}
} catch (err) {
setError(err instanceof Error ? err.message : 'Failed to fetch notifications')
} finally {
setIsLoading(false)
}
}, [enabled, userId, listNotifications, buildCSRFHeaders, setCounter])
// Subscribe to real-time events via shared socket
useEffect(() => {
if (!userId || !enabled) return
const unsubs: (() => void)[] = []
unsubs.push(socket.on('new_notification', (rawNotification: unknown) => {
const notification = rawNotification as Notification
setNotifications((prev) => [notification, ...prev])
if (!notification.read) {
incrementCounter('unread_notifications', 1)
}
if (notification.invalidates?.length && onInvalidateRef.current) {
onInvalidateRef.current(notification.invalidates)
}
}))
// Counter values are already updated by SocketProvider's built-in handler.
// Only subscribe here for query invalidation metadata. Same `unknown` →
// narrow pattern som channel.on ovan.
unsubs.push(socket.on('counter_updated', (rawPayload: unknown) => {
const payload = rawPayload as { counter: string; value: number; metadata?: { invalidate_queries?: string[] } }
if (payload.metadata?.invalidate_queries?.length && onInvalidateRef.current) {
onInvalidateRef.current(payload.metadata.invalidate_queries)
}
}))
return () => { unsubs.forEach((fn) => fn()) }
}, [userId, enabled, socket, setCounter, incrementCounter])
// Initial fetch
useEffect(() => { fetchNotifications() }, [fetchNotifications])
const markAsRead = useCallback(
async (notificationId: string) => {
try {
const result = await markNotificationAsRead({
headers: buildCSRFHeaders(),
identity: notificationId,
fields: ['id', 'read'],
})
if (result.success) {
setNotifications((prev) =>
prev.map((n) => (n.id === notificationId ? { ...n, read: true } : n))
)
incrementCounter('unread_notifications', -1)
}
} catch (err) {
console.error('[AshDispatch] Failed to mark notification as read:', err)
}
},
[markNotificationAsRead, buildCSRFHeaders, incrementCounter]
)
const markAllAsRead = useCallback(async () => {
if (!userId) return
try {
const result = await markAllNotificationsAsRead({
headers: buildCSRFHeaders(),
input: { userId },
})
if (result.success) {
setNotifications((prev) => prev.map((n) => ({ ...n, read: true })))
setCounter('unread_notifications', 0)
}
} catch (err) {
console.error('[AshDispatch] Failed to mark all notifications as read:', err)
}
}, [userId, markAllNotificationsAsRead, buildCSRFHeaders, setCounter])
return {
notifications,
unreadCount,
isLoading,
error,
isConnected: socket.isConnected,
markAsRead,
markAllAsRead,
refresh: fetchNotifications,
}
}
// ============================================================================
// Provider
// ============================================================================
export interface NotificationProviderProps extends UseNotificationsOptions {
children: ReactNode
}
/**
* Provider component that initializes notification state.
*
* When wrapped in a ``, uses the shared socket for real-time events.
* Otherwise, falls back to its own socket connection (backwards compatible).
*
* @example
* ```tsx
* // Recommended: with SocketProvider (shared socket)
*
*
* {children}
*
*
*
* // Also works: standalone (own socket, backwards compatible)
*
* {children}
*
* ```
*/
/** Inner provider using the shared socket for real-time events. */
function SharedSocketNotificationProvider({ children, ...options }: NotificationProviderProps) {
const notificationState = useNotificationsWithSharedSocket(options)
return (
{children}
)
}
/** Inner provider using its own standalone socket connection. */
function StandaloneNotificationProvider({ children, ...options }: NotificationProviderProps) {
const notificationState = useNotifications(options)
return (
{children}
)
}
export function NotificationProvider({ children, ...options }: NotificationProviderProps) {
const socketContext = useSocketContext()
// Dispatch to the correct inner provider — avoids conditional hook calls
if (socketContext) {
return {children}
}
return {children}
}
"""
end
defp generate_notification_bell_content do
"""
// ⚠️ AUTO-GENERATED by mix ash_dispatch.gen — DO NOT EDIT
// Source: projects/ash_dispatch/lib/mix/tasks/ash_dispatch.gen.ex
// To modify, change the generator and re-run: mix ash_dispatch.gen
// Drop-in notification bell component
"use client"
import { useNotificationContext } from './notification-provider'
// ============================================================================
// Types
// ============================================================================
export interface NotificationBellProps {
/** Custom class name for the container */
className?: string
/** Custom icon component (defaults to bell SVG) */
icon?: React.ReactNode
/** Whether to show the notification count badge */
showBadge?: boolean
/** Maximum count to display (shows "99+" if exceeded) */
maxCount?: number
/** Callback when bell is clicked */
onClick?: () => void
}
// ============================================================================
// Default Icon
// ============================================================================
function BellIcon({ className }: { className?: string }) {
return (
)
}
// ============================================================================
// Component
// ============================================================================
/**
* Drop-in notification bell component with unread badge.
*
* Uses the NotificationContext, so must be placed within a NotificationProvider.
*
* @example
* ```tsx
* // Simple usage in header:
* setShowPanel(true)} />
*
* // With custom styling:
*
*
* // With custom icon (e.g., from @tabler/icons-react):
* import { IconBell } from '@tabler/icons-react'
* } />
* ```
*/
export function NotificationBell({
className = '',
icon,
showBadge = true,
maxCount = 99,
onClick,
}: NotificationBellProps) {
const { unreadCount } = useNotificationContext()
const displayCount = unreadCount > maxCount ? `${maxCount}+` : unreadCount
return (
)
}
"""
end
defp generate_readme_content do
"""
# AshDispatch TypeScript SDK
Auto-generated TypeScript SDK for AshDispatch notifications and counters.
## Installation
This SDK requires the following peer dependencies:
```bash
npm install zustand phoenix
# or
pnpm add zustand phoenix
# or
yarn add zustand phoenix
```
## Quick Start
### 1. Wrap your app with SocketProvider and NotificationProvider
```tsx
// app/layout.tsx or your authenticated layout
import { SocketProvider, NotificationProvider } from '@/lib/generated/ash-dispatch'
import {
listNotifications,
markNotificationAsRead,
markAllNotificationsAsRead,
buildCSRFHeaders,
} from '@/lib/generated/ash_rpc'
export default function Layout({ children }) {
const { user } = useAuth() // Your auth hook
return (
{children}
)
}
```
The `SocketProvider` creates a single shared Phoenix socket and channel. All consumers
(notifications, custom events) multiplex over the same connection.
> **Note:** `NotificationProvider` also works without `SocketProvider` — it falls back to
> its own socket connection for backwards compatibility.
### Subscribe to custom events
```tsx
import { useUserChannelEvent } from '@/lib/generated/ash-dispatch'
function MyComponent() {
useUserChannelEvent("pipeline_progress", (payload) => {
console.log("Progress:", payload)
})
}
```
### 2. Add the NotificationBell to your header
```tsx
import { NotificationBell } from '@/lib/generated/ash-dispatch/notification-bell'
function Header() {
const [showPanel, setShowPanel] = useState(false)
return (
setShowPanel(true)} />
)
}
```
### 3. Access notifications anywhere
```tsx
import { useNotificationContext } from '@/lib/generated/ash-dispatch/notification-provider'
function NotificationList() {
const { notifications, markAsRead, markAllAsRead, isLoading } = useNotificationContext()
if (isLoading) return
Loading...
return (
{notifications.map((n) => (
markAsRead(n.id)}>
{n.title}
{n.message}
))}
)
}
```
## Using Counters Directly
For simple counter access without the full notification system:
```tsx
import { useCounter } from '@/lib/generated/ash-dispatch'
function Badge() {
const unreadCount = useCounter('unread_notifications')
return {unreadCount}
}
```
Or use the Zustand store directly:
```tsx
import { useCounterStore } from '@/lib/generated/ash-dispatch/store'
function CounterDisplay() {
const counters = useCounterStore((state) => state.counters)
return
{JSON.stringify(counters, null, 2)}
}
```
## Real-time Updates
The SDK connects to Phoenix channels via the `SocketProvider` (or standalone via `useNotifications`). Ensure your backend has:
1. A socket endpoint at `/socket`
2. A user channel at `user:{userId}`
3. A `getToken` function that returns a socket token (e.g., via RPC action)
## API Reference
### Hooks
| Hook | Description |
|------|-------------|
| `useNotifications(options)` | Full notification management with RPC and channels |
| `useUserChannelEvent(event, handler)` | Subscribe to shared socket events with auto-cleanup |
| `useCounter(name)` | Single counter value |
| `useChannel(options)` | Low-level Phoenix channel connection |
### Components
| Component | Description |
|-----------|-------------|
| `SocketProvider` | Shared Phoenix socket — one connection for all consumers |
| `NotificationProvider` | Context provider for notification state |
| `NotificationBell` | Drop-in bell icon with badge |
### Types
| Type | Description |
|------|-------------|
| `Notification` | Notification object from backend |
| `SocketContextValue` | Shape of the shared socket context |
| `CounterName` | Union of all counter names |
| `AllCounters` | Object type with all counter values |
## Generated Files
| File | Description |
|------|-------------|
| `types.ts` | Counter types, defaults, and metadata |
| `events.ts` | Event IDs and metadata |
| `store.ts` | Zustand store for counters |
| `channel.ts` | Phoenix channel utilities |
| `socket-provider.tsx` | Shared socket provider |
| `hooks/use-channel.ts` | Channel connection hook |
| `hooks/use-user-channel.ts` | Event subscription hook |
| `hooks/use-counter.ts` | Single counter hook |
| `hooks/use-notifications.ts` | Complete notification hook |
| `notification-provider.tsx` | React context provider |
| `notification-bell.tsx` | Drop-in UI component |
| `index.ts` | Re-exports |
---
Generated by `mix ash_dispatch.gen`
"""
end
# ============================================================================
# Gettext Catalog Generation
# ============================================================================
# Auto-generates a Gettext catalog module from dispatch content: block strings.
# This enables `mix gettext.extract` to discover the strings without manual catalogs.
defp generate_gettext_catalog(events, otp_app) do
gettext_backend = AshDispatch.Config.gettext_backend()
if is_nil(gettext_backend) do
0
else
# Collect all content strings from events
content_strings =
events
|> Enum.flat_map(fn event ->
content = event.content || %{}
[
content[:title],
content[:notification_title],
content[:message],
content[:notification_message],
content[:action_label]
]
|> Enum.reject(&is_nil/1)
end)
|> Enum.uniq()
|> Enum.sort()
if content_strings == [] do
0
else
catalog_module = Module.concat([Macro.camelize(to_string(otp_app)), "Events", "I18nCatalog"])
dgettext_calls =
Enum.map_join(content_strings, "\n", fn str ->
escaped = String.replace(str, "\"", "\\\"")
" dgettext(\"notifications\", \"#{escaped}\")"
end)
content = """
# Auto-generated by mix ash_dispatch.gen — DO NOT EDIT
# Registers dispatch content: strings with Gettext for extraction.
defmodule #{inspect(catalog_module)} do
@moduledoc false
use Gettext, backend: #{inspect(gettext_backend)}
@doc false
def __catalog__ do
#{dgettext_calls}
end
end
"""
path = Path.join([
"lib",
to_string(otp_app),
"events",
"i18n_catalog.ex"
])
# Only write if content changed
existing = File.read(path)
if existing == {:ok, content} do
0
else
File.mkdir_p!(Path.dirname(path))
File.write!(path, content)
Mix.shell().info("* creating #{path}")
1
end
end
end
end
end