@qwickapps/server 1.6.0 → 1.7.0

package/dist-ui-lib/src/api/types.d.ts

@@ -0,0 +1,313 @@
+/**
+ * API Client Type Definitions
+ *
+ * Type-safe API client interfaces for the auto-generated client.
+ * These types are manually maintained and should be updated when
+ * new plugins/routes are added.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import type { HealthResponse, InfoResponse, DiagnosticsResponse, ConfigResponse, LogsResponse, LogSource, UsersResponse, User, InviteUserRequest, InvitationResponse, BansResponse, ApiKeysResponse, ApiKey, CreateApiKeyRequest, UpdateApiKeyRequest, AvailableScopesResponse, KeyUsageResponse, EntitlementsStatus, UiContributionsResponse, PluginsResponse, AuthConfigStatus, RuntimeAuthConfig, UpdateAuthConfigRequest, TestProviderRequest, TestProviderResponse, NotificationsStatsResponse, NotificationsClientsResponse, RateLimitConfigUpdateRequest, RateLimitConfigUpdateResponse, PreferencesResponse } from './controlPanelApi.js';
+/**
+ * Type-safe API route manifest
+ *
+ * Manually maintained to provide IDE autocomplete and type checking.
+ * Update when new plugins/routes are added.
+ */
+export interface APIClientManifest {
+    routes: {
+        'config.query': {
+            method: 'GET';
+            path: '/api/config';
+            auth: true;
+        };
+        'core.health': {
+            method: 'GET';
+            path: '/api/health';
+            auth: false;
+        };
+        'core.info': {
+            method: 'GET';
+            path: '/api/info';
+            auth: false;
+        };
+        'core.diagnostics': {
+            method: 'GET';
+            path: '/api/diagnostics';
+            auth: false;
+        };
+        'core.uiContributions': {
+            method: 'GET';
+            path: '/api/ui-contributions';
+            auth: false;
+        };
+        'core.plugins': {
+            method: 'GET';
+            path: '/api/plugins';
+            auth: false;
+        };
+        'logs.query': {
+            method: 'GET';
+            path: '/api/logs';
+            auth: true;
+        };
+        'logs.sources': {
+            method: 'GET';
+            path: '/api/logs/sources';
+            auth: true;
+        };
+        'users.query': {
+            method: 'GET';
+            path: '/api/users';
+            auth: true;
+        };
+        'users.get': {
+            method: 'GET';
+            path: '/api/users/:id';
+            auth: true;
+        };
+        'users.invite': {
+            method: 'POST';
+            path: '/api/users/invite';
+            auth: true;
+        };
+        'bans.query': {
+            method: 'GET';
+            path: '/api/bans';
+            auth: true;
+        };
+        'apiKeys.query': {
+            method: 'GET';
+            path: '/api/api-keys';
+            auth: true;
+        };
+        'apiKeys.create': {
+            method: 'POST';
+            path: '/api/api-keys';
+            auth: true;
+        };
+        'apiKeys.get': {
+            method: 'GET';
+            path: '/api/api-keys/:id';
+            auth: true;
+        };
+        'apiKeys.update': {
+            method: 'PUT';
+            path: '/api/api-keys/:id';
+            auth: true;
+        };
+        'apiKeys.delete': {
+            method: 'DELETE';
+            path: '/api/api-keys/:id';
+            auth: true;
+        };
+        'apiKeys.scopes': {
+            method: 'GET';
+            path: '/api/api-keys/scopes';
+            auth: true;
+        };
+        'apiKeys.usage': {
+            method: 'GET';
+            path: '/api/api-keys/:id/usage';
+            auth: true;
+        };
+        'entitlements.query': {
+            method: 'GET';
+            path: '/api/entitlements';
+            auth: true;
+        };
+        'auth.status': {
+            method: 'GET';
+            path: '/api/auth/status';
+            auth: true;
+        };
+        'auth.config': {
+            method: 'GET';
+            path: '/api/auth/config';
+            auth: true;
+        };
+        'auth.update': {
+            method: 'PUT';
+            path: '/api/auth/config';
+            auth: true;
+        };
+        'auth.test': {
+            method: 'POST';
+            path: '/api/auth/test-provider';
+            auth: true;
+        };
+        'notifications.stats': {
+            method: 'GET';
+            path: '/api/notifications/stats';
+            auth: true;
+        };
+        'notifications.clients': {
+            method: 'GET';
+            path: '/api/notifications/clients';
+            auth: true;
+        };
+        'rateLimit.config': {
+            method: 'GET';
+            path: '/api/rate-limit/config';
+            auth: true;
+        };
+        'rateLimit.update': {
+            method: 'PUT';
+            path: '/api/rate-limit/config';
+            auth: true;
+        };
+        'preferences.query': {
+            method: 'GET';
+            path: '/api/preferences';
+            auth: true;
+        };
+    };
+}
+/**
+ * Query parameters for log queries
+ */
+export interface LogQueryParams {
+    level?: string;
+    source?: string;
+    limit?: number;
+    offset?: number;
+    startTime?: string;
+    endTime?: string;
+}
+/**
+ * Query parameters for user queries
+ */
+export interface UserQueryParams {
+    status?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Query parameters for bans
+ */
+export interface BanQueryParams {
+    userId?: string;
+    active?: boolean;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Query parameters for API keys
+ */
+export interface ApiKeyQueryParams {
+    userId?: string;
+    active?: boolean;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Query parameters for entitlements
+ */
+export interface EntitlementQueryParams {
+    userId?: string;
+}
+/**
+ * Query parameters for preferences
+ */
+export interface PreferenceQueryParams {
+    userId?: string;
+}
+/**
+ * Generated API Client interface
+ *
+ * Provides type-safe access to all API routes.
+ * Auto-generated at runtime, types defined manually.
+ */
+export interface APIClient {
+    /** Configuration plugin routes */
+    config: {
+        /** Get server configuration */
+        query: () => Promise<ConfigResponse>;
+    };
+    /** Core system routes */
+    core: {
+        /** Health check endpoint */
+        health: () => Promise<HealthResponse>;
+        /** Server information */
+        info: () => Promise<InfoResponse>;
+        /** System diagnostics */
+        diagnostics: () => Promise<DiagnosticsResponse>;
+        /** UI contributions from plugins */
+        uiContributions: () => Promise<UiContributionsResponse>;
+        /** List plugins */
+        plugins: () => Promise<PluginsResponse>;
+    };
+    /** Logs plugin routes */
+    logs: {
+        /** Query logs */
+        query: (params?: LogQueryParams) => Promise<LogsResponse>;
+        /** Get log sources */
+        sources: () => Promise<LogSource[]>;
+    };
+    /** Users plugin routes */
+    users: {
+        /** Query users */
+        query: (params?: UserQueryParams) => Promise<UsersResponse>;
+        /** Get user by ID */
+        get: (id: string) => Promise<User>;
+        /** Invite new user */
+        invite: (data: InviteUserRequest) => Promise<InvitationResponse>;
+    };
+    /** Bans plugin routes */
+    bans: {
+        /** Query bans */
+        query: (params?: BanQueryParams) => Promise<BansResponse>;
+    };
+    /** API Keys plugin routes */
+    apiKeys: {
+        /** Query API keys */
+        query: (params?: ApiKeyQueryParams) => Promise<ApiKeysResponse>;
+        /** Create API key */
+        create: (data: CreateApiKeyRequest) => Promise<ApiKey>;
+        /** Get API key by ID */
+        get: (id: string) => Promise<ApiKey>;
+        /** Update API key */
+        update: (id: string, data: UpdateApiKeyRequest) => Promise<ApiKey>;
+        /** Delete API key */
+        delete: (id: string) => Promise<void>;
+        /** Get available scopes */
+        scopes: () => Promise<AvailableScopesResponse>;
+        /** Get key usage stats */
+        usage: (id: string) => Promise<KeyUsageResponse>;
+    };
+    /** Entitlements plugin routes */
+    entitlements: {
+        /** Query entitlements */
+        query: (params?: EntitlementQueryParams) => Promise<EntitlementsStatus>;
+    };
+    /** Auth plugin routes */
+    auth: {
+        /** Get auth status */
+        status: () => Promise<AuthConfigStatus>;
+        /** Get auth config */
+        config: () => Promise<RuntimeAuthConfig>;
+        /** Update auth config */
+        update: (data: UpdateAuthConfigRequest) => Promise<RuntimeAuthConfig>;
+        /** Test provider connection */
+        test: (data: TestProviderRequest) => Promise<TestProviderResponse>;
+    };
+    /** Notifications plugin routes */
+    notifications: {
+        /** Get notification stats */
+        stats: () => Promise<NotificationsStatsResponse>;
+        /** Get connected clients */
+        clients: () => Promise<NotificationsClientsResponse>;
+    };
+    /** Rate limit plugin routes */
+    rateLimit: {
+        /** Get rate limit config */
+        config: () => Promise<RateLimitConfigUpdateResponse>;
+        /** Update rate limit config */
+        update: (data: RateLimitConfigUpdateRequest) => Promise<RateLimitConfigUpdateResponse>;
+    };
+    /** Preferences plugin routes */
+    preferences: {
+        /** Query preferences */
+        query: (params?: PreferenceQueryParams) => Promise<PreferencesResponse>;
+    };
+}

package/dist-ui-lib/src/components/ControlPanelApp.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ControlPanelApp Component
+ *
+ * A wrapper around QwickApp that provides control panel functionality.
+ * Injects base control panel routes (Dashboard, Health, Logs, System)
+ * and allows consumers to add custom routes.
+ *
+ * Usage:
+ * ```tsx
+ * import { ControlPanelApp } from '@qwickapps/server/ui';
+ *
+ * function App() {
+ *   return (
+ *     <ControlPanelApp
+ *       productName="My Service"
+ *       logo={<MyLogo />}
+ *       customDashboard={<MyDashboard />}
+ *     >
+ *       <Route path="/users" element={<UsersPage />} />
+ *       <Route path="/settings" element={<SettingsPage />} />
+ *     </ControlPanelApp>
+ *   );
+ * }
+ * ```
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import { ReactNode } from 'react';
+import { type MenuItem } from '@qwickapps/react-framework';
+import { type DashboardWidget, type WidgetComponent } from '../dashboard';
+export interface ControlPanelAppProps {
+    /** Product name displayed in the header */
+    productName?: string;
+    /** Custom logo component */
+    logo?: ReactNode;
+    /** Custom footer content (replaces default) */
+    footerContent?: ReactNode;
+    /** Initial dashboard widgets to register (legacy context-based system) */
+    dashboardWidgets?: DashboardWidget[];
+    /**
+     * Widget components to register for the plugin-based widget system.
+     * These map component names (from server WidgetContribution) to React components.
+     * Built-in widgets (ServiceHealthWidget, etc.) are registered automatically.
+     */
+    widgetComponents?: WidgetComponent[];
+    /** Additional navigation items to add to the base control panel nav */
+    navigationItems?: MenuItem[];
+    /** Whether to show the base control panel navigation (Dashboard, Health, etc.) */
+    showBaseNavigation?: boolean;
+    /** Base navigation item IDs to hide (e.g., ['health'] to hide the Health page) */
+    hideBaseNavItems?: string[];
+    /** Whether to show theme switcher in settings */
+    showThemeSwitcher?: boolean;
+    /** Whether to show palette switcher in settings */
+    showPaletteSwitcher?: boolean;
+    /** Base path for the control panel (e.g., '/cpanel') */
+    basePath?: string;
+    /** Custom routes to add (as Route elements) */
+    children?: ReactNode;
+}
+export declare function ControlPanelApp({ productName, logo, footerContent, dashboardWidgets, widgetComponents, navigationItems, showBaseNavigation, hideBaseNavItems, showThemeSwitcher, showPaletteSwitcher, basePath: _basePath, // Keep for backwards compatibility but unused (API always at /api)
+children, }: ControlPanelAppProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/components/auth/AcceptInvitationPage.d.ts

@@ -0,0 +1,21 @@
+/**
+ * AcceptInvitationPage - User invitation acceptance form
+ *
+ * Allows invited users to set password and activate their account
+ */
+export interface AcceptInvitationPageProps {
+    /**
+     * Auto-generated API client from qwickapps-server
+     */
+    apiClient: any;
+    /**
+     * Callback invoked on successful invitation acceptance
+     */
+    onSuccess?: (user: any) => void;
+    /**
+     * Path to redirect to after successful acceptance
+     * @default '/login'
+     */
+    redirectTo?: string;
+}
+export declare function AcceptInvitationPage({ apiClient, onSuccess, redirectTo, }: AcceptInvitationPageProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/components/auth/LoginPage.d.ts

@@ -0,0 +1,27 @@
+/**
+ * LoginPage - User login form component
+ *
+ * Provides email/password login with integration to auth provider
+ */
+export interface LoginPageProps {
+    /**
+     * Callback invoked on successful login
+     */
+    onSuccess?: (user: any) => void;
+    /**
+     * Path to redirect to after successful login
+     * @default '/dashboard'
+     */
+    redirectTo?: string;
+    /**
+     * Whether to show signup link
+     * @default true
+     */
+    showSignupLink?: boolean;
+    /**
+     * Whether to show password reset link
+     * @default true
+     */
+    showPasswordResetLink?: boolean;
+}
+export declare function LoginPage({ onSuccess, redirectTo, showSignupLink, showPasswordResetLink, }: LoginPageProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/components/auth/PasswordResetConfirmPage.d.ts

@@ -0,0 +1,17 @@
+/**
+ * PasswordResetConfirmPage - Password reset confirmation form
+ *
+ * Allows users to set a new password using reset token
+ */
+export interface PasswordResetConfirmPageProps {
+    /**
+     * Callback invoked on successful password reset
+     */
+    onSuccess?: () => void;
+    /**
+     * Path to redirect to after successful reset
+     * @default '/login'
+     */
+    redirectTo?: string;
+}
+export declare function PasswordResetConfirmPage({}: PasswordResetConfirmPageProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/components/auth/PasswordResetPage.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PasswordResetPage - Password reset request form
+ *
+ * Allows users to request a password reset email
+ */
+export interface PasswordResetPageProps {
+    /**
+     * Callback invoked on successful password reset request
+     */
+    onSuccess?: () => void;
+}
+export declare function PasswordResetPage({ onSuccess }: PasswordResetPageProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/components/auth/SignupPage.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SignupPage - User registration form component
+ *
+ * Provides name, email, password registration with validation
+ */
+export interface SignupPageProps {
+    /**
+     * Callback invoked on successful registration
+     */
+    onSuccess?: (user: any) => void;
+    /**
+     * Path to redirect to after successful registration
+     * @default '/verify-email'
+     */
+    redirectTo?: string;
+    /**
+     * Whether email verification is required
+     * @default true
+     */
+    requireEmailVerification?: boolean;
+    /**
+     * Whether to show login link
+     * @default true
+     */
+    showLoginLink?: boolean;
+}
+export declare function SignupPage({ onSuccess, redirectTo, showLoginLink, }: SignupPageProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/components/auth/VerifyEmailPage.d.ts

@@ -0,0 +1,12 @@
+/**
+ * VerifyEmailPage - Email verification page
+ *
+ * Displays instructions for email verification
+ */
+export interface VerifyEmailPageProps {
+    /**
+     * User's email address
+     */
+    email?: string;
+}
+export declare function VerifyEmailPage({ email }: VerifyEmailPageProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/components/auth/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Authentication page components
+ *
+ * Reusable auth pages for frontend applications
+ */
+export { LoginPage } from './LoginPage';
+export type { LoginPageProps } from './LoginPage';
+export { SignupPage } from './SignupPage';
+export type { SignupPageProps } from './SignupPage';
+export { AcceptInvitationPage } from './AcceptInvitationPage';
+export type { AcceptInvitationPageProps } from './AcceptInvitationPage';
+export { PasswordResetPage } from './PasswordResetPage';
+export type { PasswordResetPageProps } from './PasswordResetPage';
+export { PasswordResetConfirmPage } from './PasswordResetConfirmPage';
+export type { PasswordResetConfirmPageProps } from './PasswordResetConfirmPage';
+export { VerifyEmailPage } from './VerifyEmailPage';
+export type { VerifyEmailPageProps } from './VerifyEmailPage';
+export { AuthLayout, AuthError } from './shared';
+export type { AuthLayoutProps, AuthErrorProps } from './shared';

package/dist-ui-lib/src/components/auth/shared/AuthError.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AuthError - Error message display component for auth pages
+ *
+ * Displays error messages with consistent styling
+ */
+export interface AuthErrorProps {
+    message: string;
+}
+export declare function AuthError({ message }: AuthErrorProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/components/auth/shared/AuthLayout.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AuthLayout - Common layout wrapper for authentication pages
+ *
+ * Provides centered, card-style layout for auth forms
+ */
+import React from 'react';
+export interface AuthLayoutProps {
+    title: string;
+    children: React.ReactNode;
+}
+export declare function AuthLayout({ title, children }: AuthLayoutProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/components/auth/shared/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared auth components
+ */
+export { AuthLayout } from './AuthLayout';
+export type { AuthLayoutProps } from './AuthLayout';
+export { AuthError } from './AuthError';
+export type { AuthErrorProps } from './AuthError';

package/dist-ui-lib/src/components/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Control Panel UI Components
+ *
+ * Re-exports all public UI components for use by consumers.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+export { ControlPanelApp, type ControlPanelAppProps } from './ControlPanelApp';
+export type { MenuItem, Column, StatCardProps, DataTableProps } from '@qwickapps/react-framework';
+export { StatCard, DataTable } from '@qwickapps/react-framework';
+export { DashboardPage } from '../pages/DashboardPage';
+export { LogsPage } from '../pages/LogsPage';
+export { SystemPage } from '../pages/SystemPage';
+export { NotFoundPage } from '../pages/NotFoundPage';
+export { UsersPage, type UsersPageProps } from '../pages/UsersPage';
+export { EntitlementsPage, type EntitlementsPageProps } from '../pages/EntitlementsPage';
+export { AcceptInvitationPage, type AcceptInvitationPageProps } from '../pages/AcceptInvitationPage';
+export { DashboardWidgetProvider, useDashboardWidgets, useRegisterWidget, DashboardWidgetRenderer, type DashboardWidget, type DashboardWidgetProviderProps, WidgetComponentRegistryProvider, useWidgetComponentRegistry, PluginWidgetRenderer, getBuiltInWidgetComponents, ServiceHealthWidget, type WidgetComponent, type WidgetComponentRegistryProviderProps, } from '../dashboard';
+export { PluginManagementPage, PluginStatusWidget, PluginConfigPanel, type PluginManagementPageProps, type PluginStatusWidgetProps, type PluginConfigPanelProps, type ConfigField, type ConfigFieldType, } from './plugins';
+export { api } from '../api/controlPanelApi';
+export type { HealthCheck, HealthResponse, InfoResponse, DiagnosticsResponse, ConfigResponse, LogEntry, LogsResponse, LogSource, UserStatus, User, UsersResponse, InviteUserRequest, InvitationResponse, AcceptInvitationRequest, AcceptInvitationResponse, Ban, BansResponse, EntitlementDefinition, EntitlementResult, EntitlementSourceInfo, EntitlementsStatus, PluginFeatures, } from '../api/controlPanelApi';

package/dist-ui-lib/src/components/plugins/PluginConfigPanel.d.ts

@@ -0,0 +1,65 @@
+/**
+ * PluginConfigPanel - Live configuration editor for plugins
+ *
+ * Provides form-based config editing with validation and real-time updates.
+ *
+ * @example
+ * ```tsx
+ * <PluginConfigPanel
+ *   title="Rate Limit Configuration"
+ *   description="Adjust rate limiting settings"
+ *   config={config}
+ *   schema={[
+ *     { key: 'maxRequests', label: 'Max Requests', type: 'number', min: 1 },
+ *     { key: 'windowMs', label: 'Window (ms)', type: 'number', min: 1000 },
+ *     { key: 'strategy', label: 'Strategy', type: 'select', options: [...] }
+ *   ]}
+ *   onSave={handleSave}
+ *   onReset={handleReset}
+ * />
+ * ```
+ */
+import React from 'react';
+export type ConfigFieldType = 'text' | 'number' | 'boolean' | 'select' | 'textarea';
+export interface ConfigField {
+    /** Config key */
+    key: string;
+    /** Display label */
+    label: string;
+    /** Field type */
+    type: ConfigFieldType;
+    /** Field description */
+    description?: string;
+    /** For number type */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** For select type */
+    options?: Array<{
+        value: string | number;
+        label: string;
+    }>;
+    /** Validation */
+    required?: boolean;
+    pattern?: RegExp;
+    validate?: (value: unknown) => string | null;
+}
+export interface PluginConfigPanelProps {
+    /** Panel title */
+    title: string;
+    /** Optional description */
+    description?: string;
+    /** Current configuration */
+    config: Record<string, unknown>;
+    /** Schema defining config fields */
+    schema: ConfigField[];
+    /** Save handler */
+    onSave: (newConfig: Record<string, unknown>) => Promise<void>;
+    /** Reset handler */
+    onReset: () => void;
+    /** Loading state */
+    loading?: boolean;
+    /** Read-only mode */
+    readOnly?: boolean;
+}
+export declare const PluginConfigPanel: React.FC<PluginConfigPanelProps>;