@nuxt-customer-portal/core 0.3.0

package/server/utils/route-meta.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+
+type RouteMetaInput = {
+  openAPI: Record<string, unknown>
+  query?: z.ZodType
+  body?: z.ZodType
+}
+
+const jsonSchema = (schema: z.ZodType): Record<string, unknown> => {
+  const result = z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' }) as Record<string, unknown>
+  delete result.$schema
+  return result
+}
+
+export const definePortalRouteMeta = ({ openAPI, query, body }: RouteMetaInput) => ({
+  openAPI: {
+    ...openAPI,
+    ...(query ? { parameters: [{ in: 'query', schema: jsonSchema(query) }] } : {}),
+    ...(body
+      ? {
+          requestBody: {
+            required: true,
+            content: { 'application/json': { schema: jsonSchema(body) } }
+          }
+        }
+      : {})
+  }
+})

package/shared/core-feature.ts

@@ -0,0 +1,152 @@
+import type { PortalFeatureDefinition } from './types/feature'
+
+export const coreFeature: PortalFeatureDefinition = {
+  id: 'portal-core',
+  navigation: [
+    {
+      id: 'dashboard',
+      labelKey: 'menu.dashboard',
+      icon: 'i-lucide-layout-dashboard',
+      to: '/dashboard',
+      audiences: ['authenticated'],
+      order: 10
+    }
+  ],
+  modules: [
+    {
+      id: 'dashboard',
+      labelKey: 'menu.dashboard',
+      icon: 'i-lucide-layout-dashboard',
+      to: '/dashboard',
+      routePrefixes: ['/dashboard'],
+      audiences: ['authenticated'],
+      order: 10,
+      menuItems: [
+        {
+          id: 'dashboard',
+          labelKey: 'menu.dashboard',
+          icon: 'i-lucide-layout-dashboard',
+          to: '/dashboard',
+          audiences: ['authenticated']
+        }
+      ]
+    }
+  ],
+  emails: [
+    {
+      id: 'email-verification',
+      labelKey: 'admin.email.messages.emailVerification',
+      defaults: {
+        en: {
+          subject: 'Verify your {{brand_name}} email address',
+          body: 'Your verification code is: <code>{{otp}}</code>',
+          footer: 'This code will expire soon. If you did not request this, please ignore this email.'
+        },
+        nl: {
+          subject: 'Verifieer uw e-mailadres voor {{brand_name}}',
+          body: 'Uw verificatiecode is: <code>{{otp}}</code>',
+          footer: 'Deze code verloopt binnenkort. Negeer dit bericht als u dit niet heeft aangevraagd.'
+        }
+      },
+      placeholders: [{ key: 'otp', labelKey: 'admin.email.placeholders.otp', example: '123456' }]
+    },
+    {
+      id: 'sign-in',
+      labelKey: 'admin.email.messages.signIn',
+      defaults: {
+        en: {
+          subject: 'Your {{brand_name}} sign-in code',
+          body: 'Your sign-in code is: <code>{{otp}}</code>',
+          footer: 'This code will expire soon. If you did not request this, please ignore this email.'
+        },
+        nl: {
+          subject: 'Uw inlogcode voor {{brand_name}}',
+          body: 'Uw inlogcode is: <code>{{otp}}</code>',
+          footer: 'Deze code verloopt binnenkort. Negeer dit bericht als u dit niet heeft aangevraagd.'
+        }
+      },
+      placeholders: [{ key: 'otp', labelKey: 'admin.email.placeholders.otp', example: '123456' }]
+    },
+    {
+      id: 'forget-password',
+      labelKey: 'admin.email.messages.passwordReset',
+      defaults: {
+        en: {
+          subject: 'Reset your {{brand_name}} password',
+          body: 'Your password reset code is: <code>{{otp}}</code>',
+          footer: 'This code will expire soon. If you did not request this, please ignore this email.'
+        },
+        nl: {
+          subject: 'Stel uw wachtwoord voor {{brand_name}} opnieuw in',
+          body: 'Uw code voor het opnieuw instellen van uw wachtwoord is: <code>{{otp}}</code>',
+          footer: 'Deze code verloopt binnenkort. Negeer dit bericht als u dit niet heeft aangevraagd.'
+        }
+      },
+      placeholders: [{ key: 'otp', labelKey: 'admin.email.placeholders.otp', example: '123456' }]
+    },
+    {
+      id: 'change-email',
+      labelKey: 'admin.email.messages.changeEmail',
+      defaults: {
+        en: {
+          subject: 'Confirm your new {{brand_name}} email address',
+          body: 'Your confirmation code is: <code>{{otp}}</code>',
+          footer: 'This code will expire soon. If you did not request this, please ignore this email.'
+        },
+        nl: {
+          subject: 'Bevestig uw nieuwe e-mailadres voor {{brand_name}}',
+          body: 'Uw bevestigingscode is: <code>{{otp}}</code>',
+          footer: 'Deze code verloopt binnenkort. Negeer dit bericht als u dit niet heeft aangevraagd.'
+        }
+      },
+      placeholders: [{ key: 'otp', labelKey: 'admin.email.placeholders.otp', example: '123456' }]
+    },
+    {
+      id: 'invitation',
+      labelKey: 'admin.email.messages.invitation',
+      defaults: {
+        en: {
+          subject: "You've been invited to join {{organization_name}}",
+          body: '{{inviter_name}} has invited you to join <strong>{{organization_name}}</strong> as {{role}}.<p style="text-align:center"><a href="{{action_url}}" class="button">Accept invitation</a></p>',
+          footer: 'This invitation will expire soon. If you did not expect it, please ignore this email.'
+        },
+        nl: {
+          subject: 'U bent uitgenodigd voor {{organization_name}}',
+          body: '{{inviter_name}} heeft u uitgenodigd om als {{role}} lid te worden van <strong>{{organization_name}}</strong>.<p style="text-align:center"><a href="{{action_url}}" class="button">Uitnodiging accepteren</a></p>',
+          footer: 'Deze uitnodiging verloopt binnenkort. Negeer dit bericht als u dit niet verwachtte.'
+        }
+      },
+      placeholders: [
+        { key: 'inviter_name', labelKey: 'admin.email.placeholders.inviterName', example: 'Alex Morgan' },
+        { key: 'organization_name', labelKey: 'admin.email.placeholders.organizationName', example: 'Example Company' },
+        { key: 'role', labelKey: 'admin.email.placeholders.role', example: 'member' },
+        { key: 'action_url', labelKey: 'admin.email.placeholders.actionUrl', example: 'https://example.com/signup' }
+      ]
+    },
+    {
+      id: 'account-deletion',
+      labelKey: 'admin.email.messages.accountDeletion',
+      defaults: {
+        en: {
+          subject: 'Confirm account deletion',
+          body: 'Hello {{user_name}}, you requested to delete your account.<p style="text-align:center"><a href="{{action_url}}" class="button">Delete account</a></p>',
+          footer: 'If you did not request this, ignore this email and your account will remain active.'
+        },
+        nl: {
+          subject: 'Bevestig het verwijderen van uw account',
+          body: 'Hallo {{user_name}}, u heeft gevraagd uw account te verwijderen.<p style="text-align:center"><a href="{{action_url}}" class="button">Account verwijderen</a></p>',
+          footer: 'Negeer dit bericht als u dit niet heeft aangevraagd; uw account blijft dan actief.'
+        }
+      },
+      placeholders: [
+        { key: 'user_name', labelKey: 'admin.email.placeholders.userName', example: 'Alex Morgan' },
+        {
+          key: 'action_url',
+          labelKey: 'admin.email.placeholders.actionUrl',
+          example: 'https://example.com/delete-account'
+        }
+      ]
+    }
+  ],
+  policy: { owner: [], admin: [], member: [] }
+}

package/shared/feature-registry.ts

@@ -0,0 +1,62 @@
+import type {
+  PortalFeatureDefinition,
+  PortalFeaturePolicy,
+  PortalModuleContribution,
+  PortalModuleMenuContribution,
+  PortalOrganizationRole,
+  PortalOrganizationType,
+  PortalRolePolicy
+} from './types/feature'
+
+export const mergePortalModuleMenuContributions = (
+  modules: readonly PortalModuleContribution[],
+  contributions: readonly PortalModuleMenuContribution[]
+): PortalModuleContribution[] =>
+  modules.map((module) => {
+    const additions = contributions
+      .filter((contribution) => contribution.moduleId === module.id)
+      .map((contribution) => contribution.item)
+    const items = new Map((module.menuItems ?? []).map((item) => [item.id, item]))
+    for (const item of additions) {
+      items.set(item.id, item)
+    }
+    return { ...module, menuItems: [...items.values()] }
+  })
+
+export const upsertPortalFeature = (
+  features: PortalFeatureDefinition[],
+  feature: PortalFeatureDefinition
+): PortalFeatureDefinition[] => {
+  const index = features.findIndex((item) => item.id === feature.id)
+  if (index === -1) {
+    return [...features, feature]
+  }
+  return features.map((item, itemIndex) => (itemIndex === index ? feature : item))
+}
+
+const dashboardAreaOrder = { attention: 0, main: 1, aside: 2 } as const
+
+export const sortPortalDashboardWidgets = <
+  T extends { id: string; area: keyof typeof dashboardAreaOrder; order: number }
+>(
+  widgets: readonly T[]
+): T[] =>
+  [...widgets].sort(
+    (left, right) =>
+      dashboardAreaOrder[left.area] - dashboardAreaOrder[right.area] ||
+      left.order - right.order ||
+      left.id.localeCompare(right.id)
+  )
+
+export const isPortalActionAllowed = <Action extends string>(
+  policy: PortalFeaturePolicy<Action>,
+  role: PortalOrganizationRole | null,
+  action: Action,
+  organizationType: PortalOrganizationType = 'PROVIDER'
+): boolean => {
+  const contextual = ('PROVIDER' in policy ? policy[organizationType] : policy) as PortalRolePolicy<Action>
+  return Boolean(role && contextual[role].includes(action))
+}
+
+export const canViewOrganizationDirectory = (role: PortalOrganizationRole | string | null | undefined): boolean =>
+  role === 'owner' || role === 'admin'

package/shared/invitation-validation.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const invitationRoleSchema = z.object({ role: z.enum(['member', 'admin', 'owner']) }).strict()
+export type InvitationRole = z.infer<typeof invitationRoleSchema>['role']
+export const invitationChangeSchema = z.union([
+  invitationRoleSchema,
+  z.object({ status: z.literal('canceled') }).strict()
+])

package/shared/organization-avatar.ts

@@ -0,0 +1,11 @@
+export const getOrganizationAvatar = (organization: { metadata?: string | null; logo?: string | null }) => {
+  try {
+    const metadata = JSON.parse(organization.metadata || '{}')
+    if (typeof metadata?.avatarLogo === 'string' && metadata.avatarLogo) {
+      return metadata.avatarLogo
+    }
+  } catch {
+    // Older organizations may not have valid metadata.
+  }
+  return organization.logo || undefined
+}

package/shared/permissions.ts

@@ -0,0 +1,26 @@
+import { createAccessControl } from 'better-auth/plugins/access'
+import { defaultStatements, adminAc } from 'better-auth/plugins/admin/access'
+
+// Core portal statements. Feature authorization is owned by each feature policy.
+export const statement = {
+  ...defaultStatements,
+  // Organization-related permissions
+  organization: ['read', 'create', 'update', 'delete'],
+  member: ['read', 'list', 'create', 'update', 'delete', 'update-name'],
+  invitation: ['list', 'create', 'resend', 'cancel', 'delete']
+} as const
+
+// Create the access control instance
+const ac = createAccessControl(statement)
+
+// Define our roles with their permissions
+export const user = ac.newRole({
+  organization: ['read']
+})
+
+export const admin = ac.newRole({
+  ...adminAc.statements
+})
+
+// Export the access control instance and roles
+export { ac }

package/shared/portal-session.ts

@@ -0,0 +1,17 @@
+export interface PortalSession {
+  user: {
+    id: string
+    name?: string | null
+    email?: string
+    role?: string | null
+  }
+  session?: {
+    activeOrganizationId?: string | null
+  }
+  activeOrganizationId?: string | null
+}
+
+export type PortalOrganizationType = 'PROVIDER' | 'CLIENT'
+
+export const getActiveOrganizationId = (session: PortalSession): string | null =>
+  session.session?.activeOrganizationId ?? session.activeOrganizationId ?? null

package/shared/types/feature.ts

@@ -0,0 +1,130 @@
+export type PortalAudience =
+  | 'public'
+  | 'authenticated'
+  | 'organizationAdmin'
+  | 'admin'
+  | 'providerAuthenticated'
+  | 'providerAdmin'
+  | 'clientAuthenticated'
+  | 'clientAdmin'
+export type PortalOrganizationRole = 'owner' | 'admin' | 'member'
+export type PortalOrganizationType = 'PROVIDER' | 'CLIENT'
+
+export interface PortalBadge {
+  label: string | number
+  color?: 'primary' | 'neutral' | 'success' | 'info' | 'warning' | 'error'
+  variant?: 'solid' | 'outline' | 'soft' | 'subtle'
+  square?: boolean
+  class?: string
+}
+
+export type PortalBadgeValue = string | number | PortalBadge
+
+export interface PortalNavigationItem {
+  id: string
+  labelKey: string
+  icon?: string
+  to: string
+  audiences: PortalAudience[]
+  location?: 'main' | 'admin'
+  order?: number
+  badge?: PortalBadgeValue
+}
+
+export interface PortalDashboardWidget {
+  id: string
+  component: string
+  area: 'attention' | 'main' | 'aside'
+  size: 'full' | 'half' | 'third'
+  order: number
+}
+
+export interface PortalModuleMenuItem {
+  id: string
+  labelKey: string
+  icon?: string
+  to: string
+  exact?: boolean
+  audiences: PortalAudience[]
+  order?: number
+  badge?: PortalBadgeValue
+}
+
+export interface PortalModuleContribution {
+  id: string
+  labelKey: string
+  icon?: string
+  badge?: PortalBadgeValue
+  to: string
+  routePrefixes: string[]
+  audiences: PortalAudience[]
+  order?: number
+  menuItems?: readonly PortalModuleMenuItem[]
+}
+
+export interface PortalModuleMenuContribution {
+  moduleId: string
+  item: PortalModuleMenuItem
+}
+
+export interface PortalRolePolicy<Action extends string = string> {
+  owner: readonly Action[]
+  admin: readonly Action[]
+  member: readonly Action[]
+}
+
+export type PortalFeaturePolicy<Action extends string = string> =
+  | PortalRolePolicy<Action>
+  | {
+      PROVIDER: PortalRolePolicy<Action>
+      CLIENT: PortalRolePolicy<Action>
+    }
+
+export interface PortalClientIntegration {
+  moduleId: string
+  labelKey: string
+  descriptionKey?: string
+  detailComponent?: string
+}
+
+export interface PortalSurfaceContribution {
+  id: string
+  surface: 'administration.organization.detail'
+  component: string
+  order?: number
+}
+
+export type PortalEmailLocale = 'en' | 'nl'
+
+export interface PortalEmailPlaceholder {
+  key: string
+  labelKey: string
+  descriptionKey?: string
+  example: string
+}
+
+export interface PortalEmailText {
+  subject: string
+  body: string
+  footer?: string
+}
+
+export interface PortalEmailDefinition {
+  id: string
+  labelKey: string
+  descriptionKey?: string
+  defaults: Record<PortalEmailLocale, PortalEmailText>
+  placeholders: readonly PortalEmailPlaceholder[]
+}
+
+export interface PortalFeatureDefinition<Action extends string = string> {
+  id: string
+  navigation?: readonly PortalNavigationItem[]
+  modules?: readonly PortalModuleContribution[]
+  moduleMenuItems?: readonly PortalModuleMenuContribution[]
+  dashboardWidgets?: readonly PortalDashboardWidget[]
+  surfaces?: readonly PortalSurfaceContribution[]
+  clientIntegration?: PortalClientIntegration
+  emails?: readonly PortalEmailDefinition[]
+  policy: PortalFeaturePolicy<Action>
+}

package/shared/types/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Main export file for all shared types
+ * This makes all types available throughout the application
+ */
+
+// Database entity types
+export type { User, Organization, Member, Invitation, Session, Account, Verification } from './sections/database'
+
+// Auth-related types
+export type {
+  UserRole,
+  OrganizationType,
+  MemberRole,
+  InvitationStatus,
+  SessionUser,
+  ApiError,
+  OrganizationMemberWithUser
+} from './sections/auth'
+
+// API request/response types
+export type {
+  AdminOrganizationsResponse,
+  AdminUserResponse,
+  AdminUsersResponse,
+  UpdateUserRoleRequest,
+  UpdateUserRoleResponse,
+  OrganizationInvitationsResponse,
+  BanUserRequest,
+  UnbanUserRequest,
+  ImpersonateUserRequest,
+  ImpersonateUserResponse,
+  UserSession,
+  ListUserSessionsResponse,
+  RevokeUserSessionRequest,
+  RevokeUserSessionsRequest,
+  SetUserPasswordRequest,
+  UpdateUserRequest
+} from './sections/api'
+
+export type { FilterOperator, Filter, QueryInput, QueryResult } from './sections/queryBuilder'

package/shared/types/sections/api.ts

@@ -0,0 +1,134 @@
+/**
+ * API request/response types for all API endpoints
+ */
+import type { Organization, User, Invitation } from './database'
+import type { UserRole } from './auth'
+
+/**
+ * GET /api/admin/organizations
+ * Response: Array of organizations
+ */
+export type AdminOrganizationsResponse = Organization[]
+
+/**
+ * GET /api/admin/users
+ * Response: Array of users with selected fields
+ */
+export type AdminUserResponse = User
+
+export type AdminUsersResponse = AdminUserResponse[]
+
+/**
+ * PATCH /api/admin/users/[id]/role
+ * Request body for updating user role
+ */
+export interface UpdateUserRoleRequest {
+  role: UserRole
+}
+
+/**
+ * PATCH /api/admin/users/[id]/role
+ * Response after updating user role
+ */
+export interface UpdateUserRoleResponse {
+  success: boolean
+  message: string
+}
+
+/**
+ * GET /api/organizations/[id]/invitations
+ * Response: Array of invitations for an organization
+ */
+export type OrganizationInvitationsResponse = Invitation[]
+
+/**
+ * Admin user management types
+ */
+
+/**
+ * Ban user request
+ */
+export interface BanUserRequest {
+  userId: string
+  banReason?: string
+  banExpiresIn?: number // seconds
+}
+
+/**
+ * Unban user request
+ */
+export interface UnbanUserRequest {
+  userId: string
+}
+
+/**
+ * Impersonate user request
+ */
+export interface ImpersonateUserRequest {
+  userId: string
+}
+
+/**
+ * Impersonate user response
+ */
+export interface ImpersonateUserResponse {
+  success: boolean
+  message?: string
+}
+
+/**
+ * User session from better-auth
+ */
+export interface UserSession {
+  id: string
+  expiresAt: Date
+  token: string
+  createdAt: Date
+  updatedAt: Date
+  ipAddress?: string
+  userAgent?: string
+  userId: string
+  activeOrganizationId?: string
+  impersonatedBy?: string
+}
+
+/**
+ * List user sessions response
+ */
+export interface ListUserSessionsResponse {
+  sessions: UserSession[]
+}
+
+/**
+ * Revoke user session request
+ */
+export interface RevokeUserSessionRequest {
+  sessionToken: string
+}
+
+/**
+ * Revoke all user sessions request
+ */
+export interface RevokeUserSessionsRequest {
+  userId: string
+}
+
+/**
+ * Set user password request
+ */
+export interface SetUserPasswordRequest {
+  userId: string
+  newPassword: string
+}
+
+/**
+ * Update user request
+ */
+export interface UpdateUserRequest {
+  userId: string
+  data: {
+    name?: string
+    image?: string | null
+    [key: string]: unknown
+  }
+}

package/shared/types/sections/auth.ts

@@ -0,0 +1,71 @@
+/**
+ * Auth-related types including roles, session user, and permissions
+ */
+import type { User } from './database'
+
+/**
+ * User role type - possible values for user.role
+ */
+export type UserRole = 'user' | 'admin'
+
+export type OrganizationType = 'PROVIDER' | 'CLIENT'
+
+/**
+ * Member role type - possible values for organization member roles
+ */
+export type MemberRole = 'admin' | 'member' | 'owner'
+
+/**
+ * Invitation status type
+ */
+export type InvitationStatus = 'pending' | 'accepted' | 'rejected'
+
+/**
+ * Session user extends User with providerId added by customSession hook
+ * This is the user object that appears in session.user
+ */
+export interface SessionUser extends User {
+  providerId?: string | null
+  activeOrganizationId?: string | null
+}
+
+/**
+ * Standard API error response type
+ */
+export interface ApiError {
+  statusCode: number
+  message: string
+  data?: unknown
+}
+
+/**
+ * Organization member with nested user object
+ * This is the structure returned by better-auth organization.listMembers()
+ */
+export interface OrganizationMemberWithUser {
+  id: string
+  organizationId: string
+  userId: string
+  role: MemberRole | MemberRole[]
+  createdAt: Date
+  user: {
+    id: string
+    name: string | null
+    email: string
+    image: string | null
+    emailVerified: boolean
+    role: UserRole
+    createdAt: Date
+    updatedAt: Date
+    banned: boolean
+  }
+}
+
+/**
+ * Response from listMembers API which may include pagination
+ */
+export interface ListMembersResponse {
+  members?: OrganizationMemberWithUser[]
+  data?: OrganizationMemberWithUser[]
+  total?: number
+}