SDK Hooks
Complete reference for all React hooks provided by @naap/plugin-sdk.
Authentication Hooks#
useAuth#
Returns the authentication service with user state and authorization methods.
import { useAuth } from '@naap/plugin-sdk';
const auth = useAuth();| Method | Return Type | Description |
|---|---|---|
getUser() | AuthUser | null | Current authenticated user |
getToken() | Promise<string> | JWT authentication token |
isAuthenticated() | boolean | Whether user is logged in |
hasRole(role) | boolean | Check if user has a role |
hasPermission(resource, action) | boolean | Check a specific permission |
useUser#
Convenience hook to get the current user directly.
import { useUser } from '@naap/plugin-sdk';
const user = useUser(); // AuthUser | nulluseUserHasRole#
Check if the current user has a specific role.
import { useUserHasRole } from '@naap/plugin-sdk';
const isAdmin = useUserHasRole('system:admin'); // booleanuseUserHasPermission#
Check if the current user has a specific permission.
import { useUserHasPermission } from '@naap/plugin-sdk';
const canWrite = useUserHasPermission('plugins', 'write'); // booleanShell Service Hooks#
useShell#
Returns the full shell context with all services.
| 1 | import { useShell } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const shell = useShell(); |
| 4 | // shell.auth, shell.navigate, shell.eventBus, shell.theme, |
| 5 | // shell.notifications, shell.integrations, shell.logger, |
| 6 | // shell.permissions, shell.tenant, shell.team |
useNotify#
Returns the notification service for displaying toasts.
| 1 | import { useNotify } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const notify = useNotify(); |
| 4 | |
| 5 | notify.success('Saved!'); |
| 6 | notify.error('Failed to save'); |
| 7 | notify.warning('Are you sure?'); |
| 8 | notify.info('Update available'); |
useEvents#
Returns the event bus for inter-plugin communication.
| 1 | import { useEvents } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const events = useEvents(); |
| 4 | |
| 5 | // Emit |
| 6 | events.emit('my-plugin:updated', { id: '123' }); |
| 7 | |
| 8 | // Listen |
| 9 | const unsub = events.on('theme:change', (data) => { ... }); |
| 10 | |
| 11 | // Request/Response |
| 12 | const result = await events.request('other:get-data', { query: 'test' }); |
| 13 | |
| 14 | // Handle requests |
| 15 | events.handleRequest('my:get-data', async (req) => { |
| 16 | return { items: await fetchItems(req.query) }; |
| 17 | }); |
useThemeService#
Returns the theme service for reading and controlling the theme.
| 1 | import { useThemeService } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const theme = useThemeService(); |
| 4 | |
| 5 | theme.mode; // 'light' | 'dark' |
| 6 | theme.toggle(); // Toggle between light/dark |
| 7 | theme.setMode('dark'); |
useLogger#
Returns a structured logger scoped to your plugin.
| 1 | import { useLogger } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const logger = useLogger(); |
| 4 | |
| 5 | logger.info('Plugin loaded', { version: '1.0.0' }); |
| 6 | logger.warn('Deprecated', { feature: 'oldApi' }); |
| 7 | logger.error('Request failed', { status: 500 }); |
| 8 | logger.debug('Cache hit', { key: 'user-123' }); |
useNavigate#
Returns the navigation function for programmatic routing.
| 1 | import { useNavigate } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const navigate = useNavigate(); |
| 4 | |
| 5 | navigate('/dashboard'); |
| 6 | navigate('/plugins/my-plugin/settings'); |
usePermissions#
Returns the permission service for authorization checks.
| 1 | import { usePermissions } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const perms = usePermissions(); |
| 4 | |
| 5 | perms.can('plugins', 'write'); // boolean |
| 6 | perms.hasRole('system:admin'); // boolean |
API Client Hooks#
useApiClient#
Returns a configured HTTP client with authentication headers.
| 1 | import { useApiClient } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const client = useApiClient(); |
| 4 | |
| 5 | const data = await client.get('/api/v1/my-plugin/items'); |
| 6 | await client.post('/api/v1/my-plugin/items', { name: 'New' }); |
usePluginApi#
Returns a simplified API client scoped to your plugin's API prefix.
| 1 | import { usePluginApi } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const api = usePluginApi(); |
| 4 | |
| 5 | // Automatically prefixes with your plugin's apiPrefix |
| 6 | const items = await api.get('/items'); |
| 7 | await api.post('/items', { name: 'New' }); |
| 8 | await api.patch('/items/123', { status: 'done' }); |
| 9 | await api.delete('/items/123'); |
useAuthHeaders#
Returns authentication headers for use with custom fetch calls.
| 1 | import { useAuthHeaders } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const headers = useAuthHeaders(); |
| 4 | // { Authorization: 'Bearer ...', 'X-User-ID': '...' } |
| 5 | |
| 6 | const res = await fetch('/api/v1/external', { headers }); |
Configuration Hooks#
usePluginConfig#
Returns plugin configuration (merged from user, team, and global scopes).
| 1 | import { usePluginConfig } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const config = usePluginConfig(); |
| 4 | // or scoped: usePluginConfig('user') | usePluginConfig('team') |
useConfigValue#
Returns a single configuration value with an optional default.
| 1 | import { useConfigValue } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const pageSize = useConfigValue('pageSize', 20); |
| 4 | const theme = useConfigValue('customTheme', 'default'); |
Team & Tenant Hooks#
useTeam#
Returns the current team context.
| 1 | import { useTeam } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const team = useTeam(); |
| 4 | // team.id, team.name, team.role |
useTenant#
Returns the current tenant context.
| 1 | import { useTenant } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const tenant = useTenant(); |
| 4 | // tenant.id, tenant.name, tenant.config |
Integration Hooks#
useIntegrations#
Returns the integration service for AI, storage, and email.
| 1 | import { useIntegrations } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const integrations = useIntegrations(); |
| 4 | |
| 5 | // AI |
| 6 | const response = await integrations.ai.complete({ |
| 7 | prompt: 'Summarize...', |
| 8 | model: 'gpt-4', |
| 9 | }); |
| 10 | |
| 11 | // Storage |
| 12 | const url = await integrations.storage.upload(file); |
| 13 | |
| 14 | |
| 15 | await integrations.email.send({ to, subject, body }); |
useAI#
Shortcut to the AI integration service.
| 1 | import { useAI } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const ai = useAI(); |
| 4 | const result = await ai.complete({ prompt: 'Hello' }); |
useStorage#
Shortcut to the storage integration service.
| 1 | import { useStorage } from '@naap/plugin-sdk'; |
| 2 | |
| 3 | const storage = useStorage(); |
| 4 | const url = await storage.upload(file, { path: 'uploads/' }); |