Shell Services
The services provided by the NaaP shell to plugins: authentication, events, theme, notifications, and more.
Overview#
The shell provides a rich set of services to plugins through the ShellContext. These services abstract away platform concerns so plugins can focus on their domain logic.
Authentication Service#
Manages user identity, roles, and permissions.
TypeScript
| 1 | const auth = useAuth(); |
| 2 | |
| 3 | // Check authentication state |
| 4 | auth.isAuthenticated(); // boolean |
| 5 | auth.getUser(); // AuthUser | null |
| 6 | auth.getToken(); // Promise<string> |
| 7 | |
| 8 | // Authorization |
| 9 | auth.hasRole('admin'); // boolean |
| 10 | auth.hasPermission('plugins', 'write'); // boolean |
AuthUser Object#
TypeScript
| 1 | interface AuthUser { |
| 2 | id: string; |
| 3 | email?: string | null; |
| 4 | displayName?: string | null; |
| 5 | avatarUrl?: string | null; |
| 6 | roles: string[]; |
| 7 | permissions: Array<{ |
| 8 | resource: string; |
| 9 | action: string; |
| 10 | }>; |
| 11 | } |
Event Bus#
Enables communication between plugins and the shell.
TypeScript
| 1 | const eventBus = useEvents(); |
| 2 | |
| 3 | // Emit an event |
| 4 | eventBus.emit('my-plugin:data-updated', { itemId: '123' }); |
| 5 | |
| 6 | // Listen for events |
| 7 | const unsubscribe = eventBus.on('theme:change', (data) => { |
| 8 | console.log('Theme changed to:', data.mode); |
| 9 | }); |
| 10 | |
| 11 | // Request-response pattern |
| 12 | const result = await eventBus.request<RequestType, ResponseType>( |
| 13 | 'other-plugin:get-data', |
| 14 | { query: 'test' } |
| 15 | ); |
| 16 | |
| 17 | // Handle requests from other plugins |
| 18 | eventBus.handleRequest('my-plugin:get-data', async (data) => { |
| 19 | return { items: await fetchItems(data.query) }; |
| 20 | }); |
Built-in Events#
| Event | Payload | Description |
|---|---|---|
shell:ready | { version: string } | Shell initialization complete |
auth:login | { userId: string } | User logged in |
auth:logout | {} | User logged out |
theme:change | { mode: 'light' | 'dark' } | Theme toggled |
team:change | { teamId: string | null } | Team context switched |
plugin:preferences:changed | { pluginName: string } | Plugin preferences updated |
Notification Service#
Displays toast notifications to the user.
TypeScript
| 1 | const notify = useNotify(); |
| 2 | |
| 3 | notify.success('Item saved successfully!'); |
| 4 | notify.error('Failed to save item'); |
| 5 | notify.warning('This action cannot be undone'); |
| 6 | notify.info('New version available'); |
Theme Service#
Manages light/dark mode and provides theme state.
TypeScript
| 1 | const { theme } = useShell(); |
| 2 | |
| 3 | // Read current theme |
| 4 | theme.mode; // 'light' | 'dark' |
| 5 | |
| 6 | // Toggle theme |
| 7 | theme.toggle(); |
| 8 | |
| 9 | // Set specific mode |
| 10 | theme.setMode('dark'); |
Logger Service#
Structured logging with levels and plugin context.
TypeScript
| 1 | const logger = useLogger(); |
| 2 | |
| 3 | logger.info('Plugin loaded', { version: '1.0.0' }); |
| 4 | logger.warn('Deprecated API used', { endpoint: '/v1/old' }); |
| 5 | logger.error('Request failed', { status: 500, error: 'Timeout' }); |
| 6 | logger.debug('Cache hit', { key: 'user-123' }); |
Integration Service#
Access to platform integrations: AI, storage, and email.
TypeScript
| 1 | const integrations = useIntegrations(); |
| 2 | |
| 3 | // AI completions |
| 4 | const response = await integrations.ai.complete({ |
| 5 | prompt: 'Summarize this data...', |
| 6 | model: 'gpt-4', |
| 7 | }); |
| 8 | |
| 9 | // File storage |
| 10 | const url = await integrations.storage.upload(file, { |
| 11 | path: 'uploads/document.pdf', |
| 12 | }); |
| 13 | |
| 14 | // Send email |
| 15 | await integrations.email.send({ |
| 16 | to: 'user@example.com', |
| 17 | subject: 'Notification', |
| 18 | body: 'Your report is ready.', |
| 19 | }); |
Permission Service#
Check granular permissions for the current user.
TypeScript
| 1 | const permissions = usePermissions(); |
| 2 | |
| 3 | // Check a specific permission |
| 4 | permissions.can('plugins', 'write'); // boolean |
| 5 | permissions.can('admin', 'access'); // boolean |
| 6 | |
| 7 | // Check a role |
| 8 | permissions.hasRole('system:admin'); // boolean |
Navigation#
Programmatic navigation within the shell.
TypeScript
| 1 | const { navigate } = useShell(); |
| 2 | |
| 3 | navigate('/dashboard'); |
| 4 | navigate('/plugins/my-plugin/settings'); |