nuxt-x-app-admin

Admin-specific layer for X Enterprises applications. Extends nuxt-x-app with comprehensive admin features including user management (Better Auth), Stripe billing, dashboard analytics with charts, content management, support ticketing, and AI assistants.

Installation

npm install @xenterprises/nuxt-x-app-admin

Usage

// nuxt.config.js
export default defineNuxtConfig({
  extends: [
    'nuxt-x-app-admin',  // Includes nuxt-x-app automatically
    'nuxt-x-auth',       // Better Auth for admins
  ]
})

Components

All components use the XAdmin prefix.

Dashboard

| Component | Description | |-----------|-------------| | XAdminDashboard | Complete dashboard layout with all widgets | | XAdminDashboardMetrics | Configurable metrics grid | | XAdminDashboardRevenueChart | Revenue trends with area chart | | XAdminDashboardActivityChart | User activity line chart | | XAdminDashboardUsageChart | Resource usage donut chart | | XAdminDashboardSystemChart | CPU/Memory/Disk metrics | | XAdminDashboardSystemHealth | System health status monitor | | XAdminDashboardActiveUsers | Real-time active users count | | XAdminDashboardErrorLog | Recent error log viewer |

User Management (Better Auth)

| Component | Description | |-----------|-------------| | XAdminUsersDirectory | Searchable user directory with filters | | XAdminUsersProfile | User profile management | | XAdminUsersDetail | Full user detail with tabs | | XAdminUsersSessions | Active session management | | XAdminUsersAccounts | Linked OAuth accounts |

Stripe Management

| Component | Description | |-----------|-------------| | XAdminStripeCustomers | Customer list with search and filters | | XAdminStripeCustomersDetail | Customer detail view with subscriptions | | XAdminStripeCharges | Charge/payment history table | | XAdminStripeChargesDetail | Charge detail with refund actions | | XAdminStripeInvoices | Invoice management list | | XAdminStripeInvoicesDetail | Invoice detail with refund/void actions | | XAdminStripeSubscriptions | Subscription management | | XAdminStripeSubscriptionsDetail | Subscription detail with cancel options | | XAdminStripePaymentMethods | Payment method list | | XAdminStripeWebhookLogs | Webhook event audit trail |

Content Management

| Component | Description | |-----------|-------------| | XAdminContentPosts | Blog/content post list with filters | | XAdminContentPostsEditor | Rich post editor with SEO settings | | XAdminContentMedia | Media library with grid/list views |

Support Queue

| Component | Description | |-----------|-------------| | XAdminSupportTickets | Support ticket queue with stats | | XAdminSupportTicketsDetail | Ticket conversation view with reply |

AI/Agent

| Component | Description | |-----------|-------------| | XAdminAIChat | AI chat interface | | XAdminAIAgents | Agent management list | | XAdminAIAgentEditor | Agent configuration editor |

Roles & Permissions

| Component | Description | |-----------|-------------| | XAdminRolesList | Role list with user counts | | XAdminRolesEditor | Role creation/edit with permissions | | XAdminRolesPermissionMatrix | Visual permission grid | | XAdminRolesAssignModal | Assign roles to users |

Tenant Management

| Component | Description | |-----------|-------------| | XAdminTenantsDirectory | Tenant list with search and filters | | XAdminTenantsDetail | Tenant detail view with tabs | | XAdminTenantsSettings | Tenant settings and feature flags | | XAdminTenantsBilling | Tenant billing and usage metrics |

Audit & Security

| Component | Description | |-----------|-------------| | XAdminAuditLog | System-wide activity log viewer | | XAdminImpersonationBanner | Warning banner when impersonating | | XAdminImpersonationSwitcher | Modal to select user to impersonate |

Composables

useXAdminDashboard

const dashboard = useXAdminDashboard({
  refreshInterval: 30000
})

dashboard.health.value
dashboard.metrics.value
dashboard.activeUsers.value
dashboard.revenueHistory.value
dashboard.userActivityHistory.value
dashboard.systemMetricsHistory.value

await dashboard.refreshAll()

useXAdminUsers

const admin = useXAdminUsers()

await admin.updateRole(userId, 'editor')
await admin.suspendUser(userId, 'Violation of TOS')
await admin.unsuspendUser(userId)
await admin.resetPassword(userId)
await admin.deleteUser(userId, { hardDelete: false })

useXAdminStripe

const stripe = useXAdminStripe()

stripe.customers.data
stripe.subscriptions.data
stripe.invoices.data

await stripe.syncCustomer(customerId)
await stripe.cancelSubscription(subscriptionId, { immediately: false })
await stripe.refundInvoice(invoiceId, { amount: 1000 })
await stripe.voidInvoice(invoiceId)

useXAdminContent

const content = useXAdminContent()

content.posts.data
content.pages.data
content.media.data
content.categories.data

await content.publishPost(postId)
await content.unpublishPost(postId)
await content.duplicatePost(postId)
await content.uploadMedia(files, { folder: 'images' })

useXAdminSupport

const support = useXAdminSupport()

support.tickets.data
support.agents.value
support.stats.value

await support.assignTicket(ticketId, agentId)
await support.closeTicket(ticketId, 'Resolved')
await support.reopenTicket(ticketId)
await support.replyToTicket(ticketId, 'Hello!', { close: true })

useXAdminAI

const ai = useXAdminAI()

ai.agents.data
ai.conversations.data
ai.messages.value
ai.isStreaming.value

await ai.selectAgent(agentId)
await ai.sendMessage('Hello!')
await ai.streamMessage('Generate a report', (chunk) => console.log(chunk))
await ai.createAgent({ name: 'Support Bot', systemPrompt: '...' })

useXAdminRoles

const roles = useXAdminRoles()

roles.roles.data.value
roles.permissions.value

await roles.updatePermissions(roleId, ['perm1', 'perm2'])
await roles.assignRole(userId, roleId)
await roles.revokeRole(userId, roleId)
roles.hasPermission(roleId, 'users:delete')

useXAdminTenants

const tenants = useXAdminTenants()

await tenants.suspend(tenantId, 'Violation reason')
await tenants.activate(tenantId)
await tenants.updatePlan(tenantId, 'enterprise')
await tenants.updateSettings(tenantId, { maxUsers: 100 })

useXAdminAuditLog

const auditLog = useXAdminAuditLog()

await auditLog.getLogsByUser(userId)
await auditLog.getLogsByResource('users', userId)
await auditLog.getLogsByDateRange(startDate, endDate)
await auditLog.exportLogs('csv')

useXAdminImpersonation

const impersonation = useXAdminImpersonation()

impersonation.isImpersonating.value
impersonation.impersonatedUser.value

await impersonation.startImpersonation(userId)
await impersonation.stopImpersonation()

Layer Architecture

nuxt-x-app-admin (this layer)
    │
    └── extends nuxt-x-app
           │
           └── Shared components: XATable, XAChart*, XACard, etc.

When you extend nuxt-x-app-admin, you automatically get all components from nuxt-x-app as well, including charts powered by Nuxt Charts.

Directory Structure

nuxt-x-app-admin/
├── app/
│   ├── components/
│   │   └── XAdmin/
│   │       ├── Dashboard/
│   │       │   ├── index.vue
│   │       │   ├── Metrics.vue
│   │       │   ├── RevenueChart.vue
│   │       │   ├── ActivityChart.vue
│   │       │   ├── UsageChart.vue
│   │       │   ├── SystemChart.vue
│   │       │   ├── SystemHealth.vue
│   │       │   ├── ActiveUsers.vue
│   │       │   └── ErrorLog.vue
│   │       ├── Users/
│   │       │   ├── Directory.vue
│   │       │   ├── Profile.vue
│   │       │   ├── Detail.vue
│   │       │   ├── Sessions.vue
│   │       │   └── Accounts.vue
│   │       ├── Stripe/
│   │       │   ├── Customers/
│   │       │   ├── Charges/
│   │       │   ├── Invoices/
│   │       │   ├── Subscriptions/
│   │       │   ├── PaymentMethods/
│   │       │   └── WebhookLogs/
│   │       ├── Content/
│   │       │   ├── Posts/
│   │       │   └── Media/
│   │       ├── Support/
│   │       │   └── Tickets/
│   │       ├── AI/
│   │       │   ├── Chat.vue
│   │       │   ├── Agents.vue
│   │       │   └── AgentEditor.vue
│   │       ├── Roles/
│   │       ├── Tenants/
│   │       ├── AuditLog/
│   │       └── Impersonation/
│   ├── composables/
│   │   ├── useXAdminDashboard.js
│   │   ├── useXAdminUsers.js
│   │   ├── useXAdminStripe.js
│   │   ├── useXAdminContent.js
│   │   ├── useXAdminSupport.js
│   │   ├── useXAdminAI.js
│   │   ├── useXAdminRoles.js
│   │   ├── useXAdminTenants.js
│   │   ├── useXAdminAuditLog.js
│   │   └── useXAdminImpersonation.js
│   └── types/
│       └── index.ts
├── nuxt.config.ts
└── package.json

API Endpoints Expected

Dashboard

• GET /api/admin/dashboard/health
• GET /api/admin/dashboard/metrics
• GET /api/admin/dashboard/active-users
• GET /api/admin/dashboard/errors
• GET /api/admin/dashboard/charts/revenue
• GET /api/admin/dashboard/charts/activity
• GET /api/admin/dashboard/charts/usage
• GET /api/admin/dashboard/charts/system

Users

• GET/POST /api/admin/users
• GET/PUT/DELETE /api/admin/users/:id
• POST /api/admin/users/:id/ban
• POST /api/admin/users/:id/unban
• POST /api/admin/users/:id/reset-password
• GET/DELETE /api/admin/users/sessions
• POST /api/admin/users/sessions/revoke-all
• GET/DELETE /api/admin/users/accounts

Stripe

• GET/POST /api/admin/stripe/customers
• GET /api/admin/stripe/customers/:id
• POST /api/admin/stripe/customers/:id/sync
• GET /api/admin/stripe/charges
• GET /api/admin/stripe/charges/:id
• POST /api/admin/stripe/charges/:id/refund
• GET /api/admin/stripe/subscriptions
• POST /api/admin/stripe/subscriptions/:id/cancel
• GET /api/admin/stripe/invoices
• POST /api/admin/stripe/invoices/:id/refund
• POST /api/admin/stripe/invoices/:id/void
• GET /api/admin/stripe/webhook-logs

Content

• GET/POST /api/admin/content/posts
• GET/PUT/DELETE /api/admin/content/posts/:id
• POST /api/admin/content/posts/:id/publish
• POST /api/admin/content/posts/:id/unpublish
• POST /api/admin/content/posts/:id/duplicate
• GET/POST /api/admin/content/media
• POST /api/admin/content/media/upload
• DELETE /api/admin/content/media/:id
• GET/POST /api/admin/content/categories

Support

• GET/POST /api/admin/support/tickets
• GET/PATCH /api/admin/support/tickets/:id
• POST /api/admin/support/tickets/:id/assign
• POST /api/admin/support/tickets/:id/close
• POST /api/admin/support/tickets/:id/reopen
• POST /api/admin/support/tickets/:id/reply
• GET /api/admin/support/agents
• GET /api/admin/support/stats

AI

• GET/POST /api/admin/ai/agents
• GET/PUT/DELETE /api/admin/ai/agents/:id
• GET/POST /api/admin/ai/conversations
• GET/DELETE /api/admin/ai/conversations/:id
• POST /api/admin/ai/chat
• POST /api/admin/ai/chat/stream

Roles & Permissions

• GET/POST /api/admin/roles
• GET/PUT/DELETE /api/admin/roles/:id
• GET /api/admin/roles/permissions
• PUT /api/admin/roles/:id/permissions
• POST /api/admin/roles/:id/assign
• POST /api/admin/roles/:id/revoke

Tenants

• GET/POST /api/admin/tenants
• GET/PUT/DELETE /api/admin/tenants/:id
• POST /api/admin/tenants/:id/suspend
• POST /api/admin/tenants/:id/activate
• PUT /api/admin/tenants/:id/plan
• PUT /api/admin/tenants/:id/settings

Audit Log

• GET /api/admin/audit-log
• POST /api/admin/audit-log/export

Impersonation

• POST /api/admin/impersonation/start
• POST /api/admin/impersonation/stop
• GET /api/admin/impersonation/status

Environment Variables

This layer itself does not read any environment variables directly. However, the backend API endpoints it communicates with will typically require configuration. Document these in your app's .env:

| Name | Required | Description | |------|----------|-------------| | STRIPE_SECRET_KEY | Yes (backend) | Stripe API key for billing management | | STRIPE_WEBHOOK_SECRET | Yes (backend) | Stripe webhook signing secret | | BETTER_AUTH_SECRET | Yes (backend) | Better Auth session secret | | NUXT_PUBLIC_API_BASE | No | Override API base URL (default: /api) |

Error Reference

All composables follow a consistent error pattern:

| Error Source | Behavior | |-------------|----------| | $fetch failure | Toast shown (if showToast: true), error re-thrown | | Invalid input | Caught by backend, returned as typed error | | Network timeout | Toast with "Failed to..." message, error re-thrown |

Each composable accepts showToast: false to suppress toast notifications and handle errors manually.

How It Works

nuxt-x-app-admin is a Nuxt layer that extends nuxt-x-app. It provides admin-specific UI components and composables organized by domain (Users, Stripe, Tenants, Roles, etc.).

Components live under app/components/XAdmin/ and are auto-registered with the XAdmin prefix via Nuxt's component auto-import. Each component is designed to be self-contained: pass an endpoint prop to point it at your API, and it handles data fetching, loading states, pagination, and actions internally using useXCrud from the base layer.

Composables live under app/composables/ and wrap $fetch calls with toast notifications, error handling, and state management. They use useXCrud for list/detail CRUD and raw $fetch for custom actions (suspend, impersonate, refund, etc.).

Data flow: Component -> Composable -> $fetch('/api/...') -> Your backend API. The layer does not include server routes — you provide the API backend.

Types are exported from app/types/index.ts and define the shapes for Stripe objects, AdminUser, AuditLogEntry, Tenant, Role, Permission, etc.

nuxt.config.ts

The layer's nuxt.config.ts configures:

• extends: ['../nuxt-x-app'] to inherit base components and utilities
• components pointing to ./app/components with path prefix
• imports.dirs pointing to ./app/composables for auto-import
• typescript.strict: true

app.config.ts

Not currently used. Consumer apps can provide their own app.config.ts to configure component defaults if needed.

License

UNLICENSED