@nuxt-customer-portal/saas-configuration 0.3.0

package/app/plugins/00-portal-settings.ts

@@ -0,0 +1,26 @@
+import { primaryForeground } from '../../shared/primary-contrast'
+
+export default defineNuxtPlugin(async () => {
+  const { refreshPublicSettings } = usePortalSettings()
+  const settings = await refreshPublicSettings().catch(() => null)
+  if (!settings) {
+    return
+  }
+  const colorMode = useColorMode()
+  if (settings.appearance.colorMode === 'light-only') {
+    colorMode.preference = 'light'
+  }
+  if (settings.appearance.colorMode === 'dark-only') {
+    colorMode.preference = 'dark'
+  }
+
+  useHead(() => ({
+    htmlAttrs: { 'data-portal-theme': settings.appearance.theme },
+    style: [
+      {
+        key: 'portal-primary-colors',
+        innerHTML: `:root{--portal-primary:${settings.appearance.primaryLight};--portal-on-primary:${primaryForeground(settings.appearance.primaryLight)};--ui-primary:${settings.appearance.primaryLight};--color-primary-500:${settings.appearance.primaryLight};--color-primary-600:${settings.appearance.primaryLight}}html.dark{--portal-primary:${settings.appearance.primaryDark};--portal-on-primary:${primaryForeground(settings.appearance.primaryDark)};--ui-primary:${settings.appearance.primaryDark};--color-primary-500:${settings.appearance.primaryDark};--color-primary-600:${settings.appearance.primaryDark}}`
+      }
+    ]
+  }))
+})

package/app/plugins/saas-configuration-feature.ts

@@ -0,0 +1,3 @@
+import { saasConfigurationFeature } from '../../shared/feature'
+
+export default defineNuxtPlugin(() => usePortalFeatures().registerFeature(saasConfigurationFeature))

package/i18n/locales/en.json

@@ -0,0 +1,101 @@
+{
+  "saasSettings": {
+    "navigation": "Portal settings",
+    "title": "Portal settings",
+    "onboardingTitle": "Set up your portal",
+    "public": { "myDashboard": "My dashboard" },
+    "bootstrap": {
+      "title": "Create the portal administrator",
+      "description": "This new portal is reserved for its designated administrator. Create that account first; you will configure the portal after signing in."
+    },
+    "editor": {
+      "setupProgress": "Setup progress",
+      "portalConfiguration": "Portal configuration",
+      "configurationSections": "Configuration sections",
+      "loading": "Loading settings…",
+      "unavailable": "Settings unavailable",
+      "steps": {
+        "branding": "Branding and appearance",
+        "modules": "Modules",
+        "home": "Home page",
+        "legal": "Legal pages",
+        "review": "Review"
+      },
+      "appearanceSection": "Appearance",
+      "logoSection": "Logos for the selected color mode",
+      "fields": {
+        "portalName": "Portal name",
+        "tagline": "Tagline",
+        "supportEmail": "Support email",
+        "supportUrl": "Support URL",
+        "markLight": "Compact icon for light mode",
+        "markDark": "Compact icon for dark mode",
+        "logoLight": "Full logo for light mode",
+        "logoDark": "Full logo for dark mode",
+        "theme": "Theme",
+        "colorMode": "Color mode",
+        "primaryLight": "Primary color — light",
+        "primaryDark": "Primary color — dark",
+        "heroTitle": "Hero title",
+        "heroDescription": "Hero description",
+        "actionLabel": "Action label",
+        "actionUrl": "Action URL",
+        "introductionTitle": "Introduction title",
+        "introduction": "Introduction",
+        "supportTitle": "Support title",
+        "supportText": "Support text",
+        "termsTitle": "Terms title",
+        "termsText": "Terms text",
+        "privacyTitle": "Privacy title",
+        "privacyText": "Privacy text"
+      },
+      "assetDescriptions": {
+        "markLight": "Square icon for compact UI elements on light backgrounds, such as the login and signup screens.",
+        "markDark": "Square icon for compact UI elements on dark backgrounds, such as the login and signup screens.",
+        "logoLight": "Wide logo for headers and pages with a light background.",
+        "logoDark": "Wide logo for headers and pages with a dark background."
+      },
+      "themes": { "apex": "Apex", "brutal": "Brutal" },
+      "colorModes": { "userChoice": "User choice", "lightOnly": "Light only", "darkOnly": "Dark only" },
+      "modules": {
+        "timesheets": "Timesheets",
+        "timesheetsDescription": "Register hours by employee, client, project, and activity.",
+        "invoices": "Invoices",
+        "invoicesDescription": "Create, manage, send, and track customer invoices.",
+        "serviceRequests": "Service requests",
+        "serviceRequestsDescription": "Let customers submit requests and follow their progress.",
+        "invoiceTimesheets": "Invoice from timesheets",
+        "invoiceTimesheetsDescription": "Turn approved timesheet entries into invoice lines; requires Timesheets and Invoices.",
+        "preserved": "Data is preserved when this module is disabled."
+      },
+      "actions": {
+        "remove": "Remove",
+        "chooseImage": "Choose image",
+        "addFeature": "Add feature",
+        "back": "Back",
+        "save": "Save changes",
+        "saveContinue": "Save and continue",
+        "complete": "Complete setup"
+      },
+      "featureTitle": "Feature title",
+      "featureDescription": "Feature description",
+      "showSupport": "Show support section",
+      "review": {
+        "portal": "Portal",
+        "theme": "Theme",
+        "colorMode": "Color mode",
+        "activeModules": "Active modules",
+        "description": "Completing setup opens the configured public pages and the rest of the portal."
+      },
+      "messages": {
+        "saved": "Settings saved.",
+        "reviewSettings": "Review the settings.",
+        "saveFailed": "Settings could not be saved.",
+        "completeFailed": "Setup could not be completed.",
+        "invalidImage": "Use a valid PNG, JPEG, or WebP image smaller than 2 MB.",
+        "imageTooLarge": "The image dimensions must not exceed 2400×2400 pixels.",
+        "markTooSmall": "Compact icons must be at least 64×64 pixels."
+      }
+    }
+  }
+}

package/i18n/locales/nl.json

@@ -0,0 +1,105 @@
+{
+  "saasSettings": {
+    "navigation": "Portaalinstellingen",
+    "title": "Portaalinstellingen",
+    "onboardingTitle": "Stel je portaal in",
+    "public": { "myDashboard": "Mijn dashboard" },
+    "bootstrap": {
+      "title": "Maak de portaalbeheerder aan",
+      "description": "Dit nieuwe portaal is gereserveerd voor de aangewezen beheerder. Maak eerst dit account aan; na het inloggen configureer je het portaal."
+    },
+    "editor": {
+      "setupProgress": "Voortgang van de installatie",
+      "portalConfiguration": "Portaalconfiguratie",
+      "configurationSections": "Configuratieonderdelen",
+      "loading": "Instellingen laden…",
+      "unavailable": "Instellingen niet beschikbaar",
+      "steps": {
+        "branding": "Huisstijl en weergave",
+        "modules": "Modules",
+        "home": "Homepage",
+        "legal": "Juridische pagina's",
+        "review": "Controleren"
+      },
+      "appearanceSection": "Weergave",
+      "logoSection": "Logo's voor de gekozen kleurmodus",
+      "fields": {
+        "portalName": "Portaalnaam",
+        "tagline": "Ondertitel",
+        "supportEmail": "E-mailadres voor ondersteuning",
+        "supportUrl": "URL voor ondersteuning",
+        "markLight": "Pictogram voor lichte modus",
+        "markDark": "Pictogram voor donkere modus",
+        "logoLight": "Volledig logo voor lichte modus",
+        "logoDark": "Volledig logo voor donkere modus",
+        "theme": "Thema",
+        "colorMode": "Kleurmodus",
+        "primaryLight": "Primaire kleur — licht",
+        "primaryDark": "Primaire kleur — donker",
+        "heroTitle": "Titel van de hero",
+        "heroDescription": "Beschrijving van de hero",
+        "actionLabel": "Tekst van de knop",
+        "actionUrl": "URL van de knop",
+        "introductionTitle": "Titel van de introductie",
+        "introduction": "Introductie",
+        "supportTitle": "Titel van ondersteuning",
+        "supportText": "Tekst voor ondersteuning",
+        "termsTitle": "Titel van de voorwaarden",
+        "termsText": "Algemene voorwaarden",
+        "privacyTitle": "Titel van het privacybeleid",
+        "privacyText": "Privacybeleid"
+      },
+      "assetDescriptions": {
+        "markLight": "Vierkant pictogram voor compacte onderdelen op een lichte achtergrond, zoals de login- en registratieschermen.",
+        "markDark": "Vierkant pictogram voor compacte onderdelen op een donkere achtergrond, zoals de login- en registratieschermen.",
+        "logoLight": "Breed logo voor kopteksten en pagina's met een lichte achtergrond.",
+        "logoDark": "Breed logo voor kopteksten en pagina's met een donkere achtergrond."
+      },
+      "themes": { "apex": "Apex", "brutal": "Brutal" },
+      "colorModes": {
+        "userChoice": "Keuze van de gebruiker",
+        "lightOnly": "Alleen licht",
+        "darkOnly": "Alleen donker"
+      },
+      "modules": {
+        "timesheets": "Urenregistratie",
+        "timesheetsDescription": "Registreer uren per medewerker, klant, project en activiteit.",
+        "invoices": "Facturen",
+        "invoicesDescription": "Maak, beheer, verstuur en volg facturen voor klanten.",
+        "serviceRequests": "Serviceverzoeken",
+        "serviceRequestsDescription": "Laat klanten verzoeken indienen en de voortgang volgen.",
+        "invoiceTimesheets": "Factuur uit urenregistratie",
+        "invoiceTimesheetsDescription": "Zet goedgekeurde uren om in factuurregels; vereist Urenregistratie en Facturen.",
+        "preserved": "Gegevens blijven bewaard wanneer je deze module uitschakelt."
+      },
+      "actions": {
+        "remove": "Verwijderen",
+        "chooseImage": "Afbeelding kiezen",
+        "addFeature": "Kenmerk toevoegen",
+        "back": "Terug",
+        "save": "Wijzigingen opslaan",
+        "saveContinue": "Opslaan en doorgaan",
+        "complete": "Installatie voltooien"
+      },
+      "featureTitle": "Titel van het kenmerk",
+      "featureDescription": "Beschrijving van het kenmerk",
+      "showSupport": "Ondersteuningssectie tonen",
+      "review": {
+        "portal": "Portaal",
+        "theme": "Thema",
+        "colorMode": "Kleurmodus",
+        "activeModules": "Actieve modules",
+        "description": "Na het voltooien van de installatie worden de openbare pagina's en de rest van het portaal geopend."
+      },
+      "messages": {
+        "saved": "Instellingen opgeslagen.",
+        "reviewSettings": "Controleer de instellingen.",
+        "saveFailed": "De instellingen konden niet worden opgeslagen.",
+        "completeFailed": "De installatie kon niet worden voltooid.",
+        "invalidImage": "Gebruik een geldige PNG-, JPEG- of WebP-afbeelding kleiner dan 2 MB.",
+        "imageTooLarge": "De afmetingen mogen niet groter zijn dan 2400×2400 pixels.",
+        "markTooSmall": "Compacte pictogrammen moeten minimaal 64×64 pixels zijn."
+      }
+    }
+  }
+}

package/migrations/0000_portal_settings.sql

@@ -0,0 +1,9 @@
+CREATE SCHEMA IF NOT EXISTS "saas_configuration";
+
+CREATE TABLE "saas_configuration"."portal_settings" (
+  "id" boolean PRIMARY KEY DEFAULT true NOT NULL CHECK ("id" = true),
+  "settings" jsonb NOT NULL,
+  "onboarding_step" text DEFAULT 'branding' NOT NULL,
+  "completed_at" timestamptz,
+  "updated_at" timestamptz DEFAULT now() NOT NULL
+);

package/nuxt.config.ts

@@ -0,0 +1,15 @@
+import { fileURLToPath } from 'node:url'
+
+export default defineNuxtConfig({
+  $meta: { name: 'nuxt-customer-portal-saas-configuration' },
+  modules: ['@nuxtjs/i18n'],
+  css: [fileURLToPath(new URL('./app/assets/css/main.css', import.meta.url))],
+  i18n: {
+    defaultLocale: 'en',
+    strategy: 'no_prefix',
+    locales: [
+      { code: 'en', file: 'en.json' },
+      { code: 'nl', file: 'nl.json' }
+    ]
+  }
+})

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@nuxt-customer-portal/saas-configuration",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "exports": {
+    ".": "./nuxt.config.ts",
+    "./portal-manifest": "./portal.manifest.mjs",
+    "./shared/*": "./shared/*.ts",
+    "./server/*": "./server/*.ts"
+  },
+  "dependencies": {
+    "@nuxtjs/i18n": "^10.6.0",
+    "drizzle-orm": "^0.45.2",
+    "sharp": "^0.34.5",
+    "zod": "^4.4.3",
+    "@nuxt/ui": "^4.10.0",
+    "@nuxt-customer-portal/core": "^0.3.0",
+    "@nuxt-customer-portal/ui": "^0.3.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.5.1",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "nuxt": "^4.5.1",
+    "vue": "^3.5.0"
+  },
+  "license": "MIT",
+  "homepage": "https://nuxt-customer-portal.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ludulicious/nuxt-customer-portal.git"
+  },
+  "files": [
+    "LICENSE",
+    "CHANGELOG.md",
+    "README.md",
+    "app",
+    "server",
+    "shared",
+    "i18n",
+    "migrations",
+    "nuxt.config.ts",
+    "portal.manifest.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/portal.manifest.mjs

@@ -0,0 +1,7 @@
+export default {
+  id: 'saas-configuration',
+  version: '0.3.0',
+  source: '@nuxt-customer-portal/saas-configuration',
+  dependsOn: ['core'],
+  migrations: './migrations'
+}

package/server/api/admin/portal-settings/complete.post.ts

@@ -0,0 +1,5 @@
+export default defineEventHandler(async (event) => {
+  await requirePortalSettingsAdmin(event)
+  const body = await readBody(event)
+  return completePortalOnboarding(body?.settings)
+})

package/server/api/admin/portal-settings/index.get.ts

@@ -0,0 +1,4 @@
+export default defineEventHandler(async (event) => {
+  await requirePortalSettingsAdmin(event)
+  return readPortalSettings()
+})

package/server/api/admin/portal-settings/index.put.ts

@@ -0,0 +1,5 @@
+export default defineEventHandler(async (event) => {
+  await requirePortalSettingsAdmin(event)
+  const body = await readBody(event)
+  return writePortalSettings(body?.settings, body?.step)
+})

package/server/api/portal/bootstrap.get.ts

@@ -0,0 +1 @@
+export default defineEventHandler(async () => readPortalOnboardingState())

package/server/api/portal/public.get.ts

@@ -0,0 +1,10 @@
+export default defineEventHandler(async () => {
+  const { settings, completed } = await readPortalSettings()
+  return {
+    completed,
+    branding: settings.branding,
+    appearance: settings.appearance,
+    enabledModules: settings.enabledModules,
+    content: settings.content
+  }
+})

package/server/middleware/01-portal-bootstrap-gate.ts

@@ -0,0 +1,50 @@
+const alwaysAllowed = ['/api/health', '/api/portal/bootstrap', '/api/portal/public']
+const moduleApiPrefixes: Record<string, string[]> = {
+  timesheets: ['/api/timesheets'],
+  invoices: ['/api/invoices'],
+  'service-requests': ['/api/service-requests'],
+  'invoice-timesheets': ['/api/invoice-timesheets']
+}
+
+export default defineEventHandler(async (event) => {
+  const path = getRequestURL(event).pathname
+  if (!path.startsWith('/api/')) {
+    return
+  }
+  if (alwaysAllowed.some((prefix) => path.startsWith(prefix))) {
+    return
+  }
+
+  const state = await readPortalOnboardingState()
+  if (path.startsWith('/api/auth/')) {
+    if (!state.completed && path.includes('/sign-in/social')) {
+      throw createError({
+        statusCode: 403,
+        message: 'Social authentication is unavailable until portal setup is complete'
+      })
+    }
+    if (!state.completed && path.includes('/sign-up/')) {
+      const body = await readBody(event)
+      if (!isReservedPortalAdmin(body?.email)) {
+        throw createError({
+          statusCode: 403,
+          message: 'Only the reserved portal administrator can create the first account'
+        })
+      }
+    }
+    return
+  }
+
+  if (!state.completed && !path.startsWith('/api/admin/portal-settings')) {
+    throw createError({ statusCode: 503, message: 'Portal setup is not complete' })
+  }
+
+  if (state.completed) {
+    const { settings } = await readPortalSettings()
+    for (const [moduleId, prefixes] of Object.entries(moduleApiPrefixes)) {
+      if (!settings.enabledModules.includes(moduleId as never) && prefixes.some((prefix) => path.startsWith(prefix))) {
+        throw createError({ statusCode: 404, message: 'Module is not enabled' })
+      }
+    }
+  }
+})

package/server/utils/portal-settings.ts

@@ -0,0 +1,138 @@
+import type { H3Event } from 'h3'
+import sharp from 'sharp'
+import { getSession } from '@nuxt-customer-portal/core/server'
+import { pool } from '@nuxt-customer-portal/core/server/utils/db'
+import {
+  defaultPortalSettings,
+  portalOnboardingSteps,
+  portalSettingsSchema,
+  type PortalOnboardingState,
+  type PortalOnboardingStep,
+  type PortalSettings
+} from '../../shared/settings'
+
+interface SettingsRow {
+  settings: PortalSettings
+  onboarding_step: string
+  completed_at: Date | null
+}
+
+const reservedAdminEmails = () =>
+  new Set(
+    (process.env.ADMIN_EMAILS || '')
+      .split(',')
+      .map((value) => value.trim().toLowerCase())
+      .filter(Boolean)
+  )
+
+export async function readPortalSettings(): Promise<{
+  settings: PortalSettings
+  step: PortalOnboardingStep
+  completed: boolean
+}> {
+  const result = await pool.query<SettingsRow>(
+    'SELECT settings, onboarding_step, completed_at FROM saas_configuration.portal_settings WHERE id=true'
+  )
+  const row = result.rows[0]
+  if (row) {
+    const step =
+      row.onboarding_step === 'appearance'
+        ? 'branding'
+        : portalOnboardingSteps.includes(row.onboarding_step as PortalOnboardingStep)
+          ? (row.onboarding_step as PortalOnboardingStep)
+          : 'branding'
+    return { settings: portalSettingsSchema.parse(row.settings), step, completed: Boolean(row.completed_at) }
+  }
+  const defaults = defaultPortalSettings(process.env.PORTAL_PROVIDER_NAME || 'Customer Portal')
+  await pool.query(
+    `INSERT INTO saas_configuration.portal_settings (id, settings) VALUES (true, $1::jsonb) ON CONFLICT (id) DO NOTHING`,
+    [JSON.stringify(defaults)]
+  )
+  return { settings: defaults, step: 'branding', completed: false }
+}
+
+export async function readPortalOnboardingState(): Promise<PortalOnboardingState> {
+  const [admin, stored] = await Promise.all([
+    pool.query<{ exists: boolean }>(`SELECT EXISTS(SELECT 1 FROM "user" WHERE role='admin') AS exists`),
+    readPortalSettings()
+  ])
+  return { adminExists: Boolean(admin.rows[0]?.exists), completed: stored.completed, step: stored.step }
+}
+
+export async function requirePortalSettingsAdmin(event: H3Event) {
+  const session = await getSession(event)
+  if (!session?.user || session.user.role !== 'admin') {
+    throw createError({ statusCode: 403, message: 'System administrator access required' })
+  }
+  return session
+}
+
+export async function validatePortalBrandImages(settings: PortalSettings) {
+  for (const [name, value] of Object.entries(settings.branding)) {
+    if (!name.toLowerCase().includes('logo') && !name.toLowerCase().includes('mark')) {
+      continue
+    }
+    if (!value) {
+      continue
+    }
+    const encoded = String(value).split(',', 2)[1] || ''
+    const buffer = Buffer.from(encoded, 'base64')
+    if (buffer.length > 2_000_000) {
+      throw createError({ statusCode: 400, message: `${name} must be smaller than 2 MB` })
+    }
+    try {
+      const metadata = await sharp(buffer).metadata()
+      if (!['png', 'jpeg', 'webp'].includes(metadata.format || '') || !metadata.width || !metadata.height) {
+        throw new Error('Unsupported image')
+      }
+      if (metadata.width > 2400 || metadata.height > 2400) {
+        throw createError({ statusCode: 400, message: `${name} dimensions must not exceed 2400×2400` })
+      }
+      if (name.startsWith('mark') && (metadata.width < 64 || metadata.height < 64)) {
+        throw createError({ statusCode: 400, message: `${name} must be at least 64×64` })
+      }
+    } catch (error) {
+      if (error && typeof error === 'object' && 'statusCode' in error) {
+        throw error
+      }
+      throw createError({ statusCode: 400, message: `${name} is not a valid image` })
+    }
+  }
+}
+
+export async function writePortalSettings(input: unknown, requestedStep?: unknown) {
+  const settings = portalSettingsSchema.parse(input)
+  await validatePortalBrandImages(settings)
+  const step = portalOnboardingSteps.includes(requestedStep as PortalOnboardingStep)
+    ? (requestedStep as PortalOnboardingStep)
+    : undefined
+  await pool.query(
+    `UPDATE saas_configuration.portal_settings SET settings=$1::jsonb, onboarding_step=COALESCE($2,onboarding_step), updated_at=now() WHERE id=true`,
+    [JSON.stringify(settings), step || null]
+  )
+  return { settings, step: step || (await readPortalSettings()).step }
+}
+
+export async function completePortalOnboarding(input: unknown) {
+  const settings = portalSettingsSchema.parse(input)
+  await validatePortalBrandImages(settings)
+  const client = await pool.connect()
+  try {
+    await client.query('BEGIN')
+    await client.query(
+      `UPDATE saas_configuration.portal_settings SET settings=$1::jsonb, onboarding_step='review', completed_at=now(), updated_at=now() WHERE id=true`,
+      [JSON.stringify(settings)]
+    )
+    await client.query('COMMIT')
+  } catch (error) {
+    await client.query('ROLLBACK')
+    throw error
+  } finally {
+    client.release()
+  }
+  return { settings, step: 'review' as const, completed: true }
+}
+
+export function isReservedPortalAdmin(email: unknown) {
+  return typeof email === 'string' && reservedAdminEmails().has(email.trim().toLowerCase())
+}

package/shared/feature.ts

@@ -0,0 +1,30 @@
+import type { PortalFeatureDefinition } from '@nuxt-customer-portal/core/shared/types/feature'
+
+export const saasConfigurationFeature: PortalFeatureDefinition = {
+  id: 'saas-configuration',
+  navigation: [
+    {
+      id: 'portal-settings',
+      labelKey: 'saasSettings.navigation',
+      icon: 'i-lucide-palette',
+      to: '/admin/portal-settings',
+      audiences: ['admin'],
+      location: 'admin',
+      order: 120
+    }
+  ],
+  moduleMenuItems: [
+    {
+      moduleId: 'admin',
+      item: {
+        id: 'portal-settings',
+        labelKey: 'saasSettings.navigation',
+        icon: 'i-lucide-palette',
+        to: '/admin/portal-settings',
+        audiences: ['admin'],
+        order: 120
+      }
+    }
+  ],
+  policy: { owner: [], admin: [], member: [] }
+}

package/shared/primary-contrast.ts

@@ -0,0 +1,12 @@
+/** Choose the foreground with the highest contrast against a validated sRGB hex color. */
+export const primaryForeground = (hex: string): '#ffffff' | '#000000' => {
+  if (!/^#[0-9a-f]{6}$/i.test(hex)) {
+    return '#ffffff'
+  }
+  const channels = [1, 3, 5].map((offset) => {
+    const value = parseInt(hex.slice(offset, offset + 2), 16) / 255
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4
+  })
+  const luminance = channels[0]! * 0.2126 + channels[1]! * 0.7152 + channels[2]! * 0.0722
+  return 1.05 / (luminance + 0.05) >= (luminance + 0.05) / 0.05 ? '#ffffff' : '#000000'
+}