@nuxt-customer-portal/clients 0.3.3 → 0.4.1

package/server/plugins/client-accounts.ts

@@ -0,0 +1,114 @@
+import {
+  registerUserDisplayNameChangedHook,
+  registerUserIdentityChangedHook
+} from '@nuxt-customer-portal/core/server/utils/business-hooks'
+import { and, eq, inArray } from 'drizzle-orm'
+import { createError } from 'h3'
+import { db } from '@nuxt-customer-portal/core/server/utils/db'
+import { member, organization } from '@nuxt-customer-portal/core/schema'
+import { registerClientAccountPolicy } from '@nuxt-customer-portal/core/server/utils/client-account-policy'
+import { registerClientTimezoneResolver } from '@nuxt-customer-portal/core/server/utils/timezones'
+import { clientProfile } from '../db/schema/clients'
+import { getClientConfiguration, setClientConfigurationValidation } from '../utils/client-configuration'
+
+export default defineNitroPlugin(() => {
+  registerUserDisplayNameChangedHook(async (transaction, userId, name) => {
+    const tx = transaction as Parameters<Parameters<typeof db.transaction>[0]>[0]
+    const personalClients = await tx
+      .select({ id: clientProfile.organizationId })
+      .from(clientProfile)
+      .innerJoin(member, eq(member.organizationId, clientProfile.organizationId))
+      .where(and(eq(member.userId, userId), eq(clientProfile.clientType, 'person')))
+    for (const client of personalClients) {
+      await tx.update(organization).set({ name }).where(eq(organization.id, client.id))
+      await tx
+        .update(clientProfile)
+        .set({ officialName: name, updatedAt: new Date() })
+        .where(eq(clientProfile.organizationId, client.id))
+    }
+  })
+  registerUserIdentityChangedHook(async (transaction, userId, identity) => {
+    if (!identity.firstName || !identity.lastName) {
+      return
+    }
+    const tx = transaction as Parameters<Parameters<typeof db.transaction>[0]>[0]
+    const personalClientIds = tx
+      .select({ id: member.organizationId })
+      .from(member)
+      .innerJoin(clientProfile, eq(clientProfile.organizationId, member.organizationId))
+      .where(and(eq(member.userId, userId), eq(clientProfile.clientType, 'person')))
+    await tx
+      .update(clientProfile)
+      .set({ firstName: identity.firstName, lastName: identity.lastName, updatedAt: new Date() })
+      .where(inArray(clientProfile.organizationId, personalClientIds))
+  })
+  // Nitro does not await plugin return values. Register policies synchronously,
+  // and gate requests on database validation instead of leaving a startup gap.
+  const configurationReady = Promise.resolve()
+    .then(async () => {
+      const config = await getClientConfiguration()
+      return db
+        .selectDistinct({ clientType: clientProfile.clientType })
+        .from(clientProfile)
+        .then((profiles) =>
+          profiles.some((row) => !config.allowedTypes.includes(row.clientType))
+            ? 'Cannot disable a client type while clients of that type exist'
+            : null
+        )
+    })
+    .catch(() => 'Client configuration could not be validated. Check database migrations and connectivity.')
+  setClientConfigurationValidation(configurationReady)
+  const profile = async (id: string) =>
+    (await db.select().from(clientProfile).where(eq(clientProfile.organizationId, id)).limit(1))[0]
+  registerClientTimezoneResolver(async (id) => (await profile(id))?.timezone ?? null)
+  registerClientAccountPolicy({
+    isPersonal: async (id) => (await profile(id))?.clientType === 'person',
+    getIdentity: async (id) => {
+      const client = await profile(id)
+      if (!client) {
+        return null
+      }
+      return {
+        name: client.officialName,
+        ...(client.firstName ? { firstName: client.firstName } : {}),
+        ...(client.lastName ? { lastName: client.lastName } : {})
+      }
+    },
+    assertAcceptance: async (id, userId) => {
+      const client = await profile(id)
+      if (client?.archivedAt) {
+        throw createError({ statusCode: 403, message: 'Archived clients cannot accept invitations' })
+      }
+      if (client?.clientType !== 'person') {
+        return
+      }
+      const existing = await db
+        .select({ organizationId: member.organizationId })
+        .from(member)
+        .where(eq(member.organizationId, id))
+        .limit(1)
+      const personal = await db
+        .select({ id: member.id })
+        .from(member)
+        .where(
+          and(
+            eq(member.userId, userId),
+            inArray(
+              member.organizationId,
+              db
+                .select({ id: clientProfile.organizationId })
+                .from(clientProfile)
+                .where(eq(clientProfile.clientType, 'person'))
+            )
+          )
+        )
+        .limit(1)
+      if (existing.length || personal.length) {
+        throw createError({
+          statusCode: 409,
+          message: 'A personal account already exists. Contact your coach to reconcile the accounts.'
+        })
+      }
+    }
+  })
+})

package/server/utils/client-access.ts

@@ -1,4 +1,5 @@
 import type { H3Event } from 'h3'
+import { isPersonalClient } from '@nuxt-customer-portal/core/server/utils/client-account-policy'
 import { requireActiveOrganizationRole } from '@nuxt-customer-portal/core/server/portal'
 
 export const requireOwnerClientManager = async (event: H3Event) => {
@@ -21,3 +22,11 @@ export const requireClientProfileManager = async (event: H3Event, clientOrganiza
   }
   return context
 }
+
+export const requireClientMemberManager = async (event: H3Event, id: string) => {
+  const context = await requireClientProfileManager(event, id)
+  if (context.organizationType !== 'PROVIDER' && (await isPersonalClient(id))) {
+    throw createError({ statusCode: 403, message: 'Personal accounts cannot manage members or invitations' })
+  }
+  return context
+}

package/server/utils/client-configuration.ts

@@ -0,0 +1,37 @@
+import { resolveClientConfigurationOverride } from '@nuxt-customer-portal/core/server/utils/client-configuration'
+import { createError } from 'h3'
+
+export const getClientConfiguration = async () => {
+  const config = useRuntimeConfig()
+  const clients = { ...config.public.clients, ...(await resolveClientConfigurationOverride()) } as {
+    allowedTypes?: string[]
+    personalSelfRegistration?: boolean
+    defaultModules?: string[]
+  }
+  const allowedTypes = clients.allowedTypes ?? ['organization']
+  if (!allowedTypes.length || allowedTypes.some((type) => !['organization', 'person'].includes(type))) {
+    throw new Error('clients.allowedTypes must contain organization and/or person')
+  }
+  const registrationMode = process.env.PORTAL_REGISTRATION_MODE || config.portalAuth.registrationMode
+  if (clients.personalSelfRegistration && (!allowedTypes.includes('person') || registrationMode !== 'open')) {
+    throw new Error('Personal registration requires person clients and open authentication registration')
+  }
+  return { ...clients, allowedTypes }
+}
+export const requireAllowedClientType = async (type: string) => {
+  if (!(await getClientConfiguration()).allowedTypes.includes(type)) {
+    throw createError({ statusCode: 403, message: 'This client type is not enabled' })
+  }
+}
+
+// Server middleware awaits this promise; Nitro request hooks swallow thrown errors.
+let configurationReady: Promise<string | null> = Promise.resolve('Client configuration has not initialized')
+export const setClientConfigurationValidation = (ready: Promise<string | null>) => {
+  configurationReady = ready
+}
+export const requireClientConfigurationReady = async () => {
+  const error = await configurationReady
+  if (error) {
+    throw createError({ statusCode: 503, message: error })
+  }
+}

package/server/utils/client-repository.ts

@@ -1,4 +1,4 @@
-import { and, asc, count, desc, eq, ilike, inArray, isNotNull, isNull, or } from 'drizzle-orm'
+import { and, asc, count, desc, eq, ilike, inArray, isNotNull, isNull, or, sql } from 'drizzle-orm'
 import { nanoid } from 'nanoid'
 import { getOrganizationAvatar } from '@nuxt-customer-portal/core/shared/organization-avatar'
 import { db } from '@nuxt-customer-portal/core/server/portal'
@@ -8,6 +8,9 @@ import { runClientCreatedHooks } from '@nuxt-customer-portal/core/server/utils/b
 import type { GenericClientDto, ClientListResponse } from '@nuxt-customer-portal/clients/shared/types/client'
 import type { ClientCreateInput, GenericClientListQuery, ClientUpdateInput } from './client-validation'
 
+import { getProviderTimezone } from '@nuxt-customer-portal/core/server/utils/timezones'
+import { requireAllowedClientType } from './client-configuration'
+
 const normalizeNullable = (value: string | null | undefined) => value?.trim() || null
 
 const clientSelection = {
@@ -17,6 +20,10 @@ const clientSelection = {
   logo: organization.logo,
   metadata: organization.metadata,
   createdAt: organization.createdAt,
+  clientType: clientProfile.clientType,
+  firstName: clientProfile.firstName,
+  lastName: clientProfile.lastName,
+  timezone: clientProfile.timezone,
   officialName: clientProfile.officialName,
   address: clientProfile.address,
   registrationNumber: clientProfile.registrationNumber,
@@ -33,6 +40,10 @@ interface ClientRow {
   logo: string | null
   metadata: string | null
   createdAt: Date
+  clientType: 'organization' | 'person'
+  firstName: string | null
+  lastName: string | null
+  timezone: string | null
   officialName: string
   address: string
   registrationNumber: string | null
@@ -46,6 +57,7 @@ const hydrateClients = async (rows: ClientRow[]): Promise<GenericClientDto[]> =>
   if (!rows.length) {
     return []
   }
+  const providerTimezone = await getProviderTimezone()
   const ids = rows.map((row) => row.organizationId as string)
   const [modules, members, invitations] = await Promise.all([
     db.select().from(clientModule).where(inArray(clientModule.organizationId, ids)),
@@ -58,6 +70,8 @@ const hydrateClients = async (rows: ClientRow[]): Promise<GenericClientDto[]> =>
         phone: member.phone,
         jobTitle: member.jobTitle,
         name: user.name,
+        firstName: user.firstName,
+        lastName: user.lastName,
         email: user.email,
         image: user.image
       })
@@ -78,26 +92,32 @@ const hydrateClients = async (rows: ClientRow[]): Promise<GenericClientDto[]> =>
       .where(and(inArray(invitation.organizationId, ids), eq(invitation.status, 'pending')))
       .orderBy(asc(invitation.email))
   ])
-  return rows.map((row) => ({
-    id: row.organizationId,
-    organizationId: row.organizationId,
-    name: row.name,
-    slug: row.slug,
-    logo: row.logo,
-    avatarLogo: getOrganizationAvatar(row) ?? null,
-    officialName: row.officialName,
-    address: row.address,
-    registrationNumber: row.registrationNumber,
-    vatNumber: row.vatNumber,
-    invoiceEmail: row.invoiceEmail,
-    preferredLocale: row.preferredLocale === 'en' ? 'en' : 'nl',
-    archivedAt: row.archivedAt?.toISOString() ?? null,
-    modules: modules
-      .filter((item) => item.organizationId === row.organizationId)
-      .map((item) => ({ moduleId: item.moduleId, enabled: item.enabled })),
-    members: members
-      .filter((item) => item.organizationId === row.organizationId)
-      .map((item) => ({
+  return rows.map((row) => {
+    const clientMembers = members.filter((item) => item.organizationId === row.organizationId)
+    const personalMember = row.clientType === 'person' ? clientMembers[0] : undefined
+    return {
+      id: row.organizationId,
+      organizationId: row.organizationId,
+      name: row.name,
+      firstName: row.clientType === 'person' ? (row.firstName ?? personalMember?.firstName ?? null) : null,
+      lastName: row.clientType === 'person' ? (row.lastName ?? personalMember?.lastName ?? null) : null,
+      slug: row.slug,
+      logo: row.logo,
+      avatarLogo: getOrganizationAvatar(row) ?? null,
+      clientType: row.clientType,
+      timezone: row.timezone,
+      schedulingTimezone: row.timezone || providerTimezone,
+      officialName: row.officialName,
+      address: row.address,
+      registrationNumber: row.registrationNumber,
+      vatNumber: row.vatNumber,
+      invoiceEmail: row.invoiceEmail,
+      preferredLocale: row.preferredLocale === 'en' ? 'en' : 'nl',
+      archivedAt: row.archivedAt?.toISOString() ?? null,
+      modules: modules
+        .filter((item) => item.organizationId === row.organizationId)
+        .map((item) => ({ moduleId: item.moduleId, enabled: item.enabled })),
+      members: clientMembers.map((item) => ({
         id: item.id,
         userId: item.userId,
         name: item.name,
@@ -107,20 +127,22 @@ const hydrateClients = async (rows: ClientRow[]): Promise<GenericClientDto[]> =>
         phone: item.phone,
         jobTitle: item.jobTitle
       })),
-    invitations: invitations
-      .filter((item) => item.organizationId === row.organizationId)
-      .map((item) => ({
-        id: item.id,
-        email: item.email,
-        role: item.role || 'member',
-        status: item.status,
-        expiresAt: item.expiresAt.toISOString()
-      }))
-  }))
+      invitations: invitations
+        .filter((item) => item.organizationId === row.organizationId)
+        .map((item) => ({
+          id: item.id,
+          email: item.email,
+          role: item.role || 'member',
+          status: item.status,
+          expiresAt: item.expiresAt.toISOString()
+        }))
+    }
+  })
 }
 
 export const listGenericClientsPage = async (query: GenericClientListQuery): Promise<ClientListResponse> => {
   const conditions = [
+    query.clientType ? eq(clientProfile.clientType, query.clientType) : undefined,
     eq(organization.organizationType, 'CLIENT'),
     query.status === 'archived'
       ? isNotNull(clientProfile.archivedAt)
@@ -202,39 +224,59 @@ export const listSelectableClients = async (moduleId?: string) => {
   return page.items
 }
 
-export const createClient = async (actorUserId: string, input: ClientCreateInput) =>
-  db.transaction(async (tx) => {
-    const [existingSlug] = await tx
-      .select({ id: organization.id })
-      .from(organization)
-      .where(eq(organization.slug, input.slug))
-      .limit(1)
-    if (existingSlug) {
-      throw createError({ statusCode: 409, message: 'Organization slug already exists', data: { field: 'slug' } })
-    }
-    const organizationId = nanoid()
-    await tx.insert(organization).values({
-      id: organizationId,
-      name: input.name,
-      slug: input.slug,
-      organizationType: 'CLIENT',
-      createdAt: new Date()
-    })
-    await tx.insert(clientProfile).values({
-      organizationId,
-      officialName: input.officialName,
-      address: input.address,
-      registrationNumber: normalizeNullable(input.registrationNumber),
-      vatNumber: normalizeNullable(input.vatNumber),
-      invoiceEmail: normalizeNullable(input.invoiceEmail),
-      preferredLocale: input.preferredLocale
-    })
-    await runClientCreatedHooks(tx, organizationId)
-    for (const moduleId of [...new Set(input.moduleIds ?? [])]) {
-      await tx.insert(clientModule).values({ id: nanoid(), organizationId, moduleId, enabledById: actorUserId })
-    }
-    return organizationId
+type ClientTransaction = Pick<typeof db, 'select' | 'insert' | 'execute'>
+export const createClientInTransaction = async (
+  tx: ClientTransaction,
+  actorUserId: string,
+  input: ClientCreateInput
+) => {
+  const type = input.clientType ?? 'organization'
+  await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext('portal-client-configuration'))`)
+  await requireAllowedClientType(type)
+  const clientSlug =
+    type === 'person'
+      ? `person-${nanoid()
+          .toLowerCase()
+          .replace(/[^a-z0-9]/g, '')}`
+      : input.slug!
+
+  const [existingSlug] = await tx
+    .select({ id: organization.id })
+    .from(organization)
+    .where(eq(organization.slug, clientSlug))
+    .limit(1)
+  if (existingSlug) {
+    throw createError({ statusCode: 409, message: 'Organization slug already exists', data: { field: 'slug' } })
+  }
+  const organizationId = nanoid()
+  await tx.insert(organization).values({
+    id: organizationId,
+    name: input.name,
+    slug: clientSlug,
+    organizationType: 'CLIENT',
+    createdAt: new Date()
+  })
+  await tx.insert(clientProfile).values({
+    organizationId,
+    clientType: type,
+    firstName: type === 'person' ? input.firstName : null,
+    lastName: type === 'person' ? input.lastName : null,
+    timezone: input.timezone ?? null,
+    officialName: type === 'person' ? input.name : input.officialName!,
+    address: input.address,
+    registrationNumber: normalizeNullable(input.registrationNumber),
+    vatNumber: normalizeNullable(input.vatNumber),
+    invoiceEmail: normalizeNullable(input.invoiceEmail),
+    preferredLocale: input.preferredLocale
   })
+  await runClientCreatedHooks(tx, organizationId)
+  for (const moduleId of [...new Set(input.moduleIds ?? [])]) {
+    await tx.insert(clientModule).values({ id: nanoid(), organizationId, moduleId, enabledById: actorUserId })
+  }
+  return organizationId
+}
+export const createClient = async (actorUserId: string, input: ClientCreateInput) =>
+  db.transaction((tx) => createClientInTransaction(tx, actorUserId, input))
 
 export const updateClient = async (organizationId: string, input: ClientUpdateInput) =>
   db.transaction(async (tx) => {
@@ -246,6 +288,13 @@ export const updateClient = async (organizationId: string, input: ClientUpdateIn
     if (!selected) {
       throw createError({ statusCode: 404, message: 'Client not found' })
     }
+    const [profile] = await tx.select().from(clientProfile).where(eq(clientProfile.organizationId, organizationId))
+    if (profile?.clientType === 'person' && (input.registrationNumber || input.vatNumber)) {
+      throw createError({ statusCode: 400, message: 'Personal clients cannot have company fields' })
+    }
+    if (profile?.clientType !== 'person' && (input.firstName !== undefined || input.lastName !== undefined)) {
+      throw createError({ statusCode: 400, message: 'Name parts are only available for personal clients' })
+    }
     const orgValues: Record<string, unknown> = {}
     if (input.name !== undefined) {
       orgValues.name = input.name
@@ -257,6 +306,12 @@ export const updateClient = async (organizationId: string, input: ClientUpdateIn
     if (input.officialName !== undefined) {
       values.officialName = input.officialName
     }
+    if (input.timezone !== undefined) {
+      values.timezone = input.timezone
+    }
+    if (profile?.clientType === 'person' && input.name !== undefined) {
+      values.officialName = input.name
+    }
     if (input.address !== undefined) {
       values.address = input.address
     }
@@ -272,7 +327,21 @@ export const updateClient = async (organizationId: string, input: ClientUpdateIn
     if (input.preferredLocale !== undefined) {
       values.preferredLocale = input.preferredLocale
     }
+    if (input.firstName !== undefined && input.lastName !== undefined) {
+      values.firstName = input.firstName
+      values.lastName = input.lastName
+    }
     await tx.update(clientProfile).set(values).where(eq(clientProfile.organizationId, organizationId))
+    if (input.firstName !== undefined && input.lastName !== undefined) {
+      const personalUserIds = tx
+        .select({ id: member.userId })
+        .from(member)
+        .where(eq(member.organizationId, organizationId))
+      await tx
+        .update(user)
+        .set({ firstName: input.firstName, lastName: input.lastName })
+        .where(inArray(user.id, personalUserIds))
+    }
   })
 
 export const setClientArchived = async (organizationId: string, actorUserId: string, archived: boolean) => {

package/server/utils/client-validation.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { timezoneSchema } from '@nuxt-customer-portal/core/server/utils/timezone-validation'
 
 const id = z.string().min(1).max(128)
 const slug = z
@@ -9,6 +10,7 @@ const slug = z
   .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
 
 export const genericClientListQuerySchema = z.object({
+  clientType: z.enum(['organization', 'person']).optional(),
   search: z.string().trim().max(200).optional(),
   status: z.enum(['all', 'active', 'archived']).optional(),
   moduleId: z.string().trim().max(100).optional(),
@@ -18,10 +20,14 @@ export const genericClientListQuerySchema = z.object({
   sortDir: z.enum(['asc', 'desc']).default('asc')
 })
 
-export const genericClientCreateSchema = z.object({
+const clientFields = z.object({
+  clientType: z.enum(['organization', 'person']).default('organization'),
+  firstName: z.string().trim().min(1).max(80).optional(),
+  lastName: z.string().trim().min(1).max(80).optional(),
+  timezone: timezoneSchema.nullable().optional(),
   name: z.string().trim().min(2).max(160),
-  slug,
-  officialName: z.string().trim().min(2).max(200),
+  slug: slug.optional(),
+  officialName: z.string().trim().min(2).max(200).optional(),
   address: z.string().trim().max(1000).default(''),
   registrationNumber: z.string().trim().max(200).nullable().optional(),
   vatNumber: z.string().trim().max(100).nullable().optional(),
@@ -30,9 +36,31 @@ export const genericClientCreateSchema = z.object({
   moduleIds: z.array(z.string().trim().min(1).max(100)).max(50).optional()
 })
 
-export const clientUpdateSchema = genericClientCreateSchema
-  .omit({ slug: true, moduleIds: true })
+export const genericClientCreateSchema = clientFields.superRefine((input, ctx) => {
+  if (input.clientType === 'organization') {
+    if (!input.slug) {
+      ctx.addIssue({ code: 'custom', path: ['slug'], message: 'Company slug is required' })
+    }
+    if (!input.officialName) {
+      ctx.addIssue({ code: 'custom', path: ['officialName'], message: 'Company name is required' })
+    }
+  } else if (input.registrationNumber || input.vatNumber) {
+    ctx.addIssue({ code: 'custom', message: 'Personal clients cannot have company registration or VAT fields' })
+  } else if (!input.firstName || !input.lastName) {
+    ctx.addIssue({ code: 'custom', path: ['firstName'], message: 'Personal clients require first and last name' })
+  }
+})
+export const clientUpdateSchema = clientFields
+  .omit({ slug: true, moduleIds: true, clientType: true })
   .partial()
+  .extend({
+    address: z.string().trim().max(1000).optional(),
+    preferredLocale: z.enum(['nl', 'en']).optional()
+  })
+  .strict()
+  .refine((value) => (value.firstName === undefined) === (value.lastName === undefined), {
+    message: 'First and last name must be updated together'
+  })
   .refine((value) => Object.keys(value).length > 0, 'At least one field is required')
 export const clientArchiveSchema = z.object({ archived: z.boolean() })
 export const clientModuleUpdateSchema = z.object({ enabled: z.boolean() })

package/server/utils/purchase-client.ts

@@ -0,0 +1,90 @@
+import { randomUUID } from 'node:crypto'
+import type { PoolClient } from 'pg'
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { createError } from 'h3'
+import { createClientInTransaction } from './client-repository'
+import { requireAllowedClientType } from './client-configuration'
+
+export interface PurchaseClientInput {
+  type: 'person' | 'organization'
+  firstName: string
+  lastName: string
+  name: string
+  email: string
+  company: string
+  address: string
+  registrationNumber: string
+  vatNumber: string
+  clientId?: string
+}
+/** Never resolve company membership from unverified checkout fields. */
+export async function provisionPurchaseClient(
+  tx: PoolClient,
+  input: PurchaseClientInput,
+  verifiedUserId: string | null,
+  actorId: string,
+  locale: 'en' | 'nl'
+) {
+  await requireAllowedClientType(input.type)
+  await tx.query('SELECT pg_advisory_xact_lock(hashtext($1))', [`purchase-client:${input.email}`])
+  let clientId: string | undefined
+  if (input.clientId && verifiedUserId) {
+    const result = await tx.query<{ id: string }>(
+      `SELECT p.organization_id AS id FROM clients.client_profile p JOIN public.member m ON m.organization_id=p.organization_id WHERE m.user_id=$1 AND p.organization_id=$2 AND p.client_type=$3 AND p.archived_at IS NULL`,
+      [verifiedUserId, input.clientId, input.type]
+    )
+    if (!result.rows[0]) {
+      throw createError({ statusCode: 403, message: 'Client membership required' })
+    }
+    clientId = result.rows[0].id
+  }
+  if (!clientId && input.type === 'person') {
+    // Reuse an existing personal billing client without granting membership or overwriting its profile.
+    const result = await tx.query<{ id: string }>(
+      `SELECT p.organization_id AS id FROM clients.client_profile p JOIN public.member m ON m.organization_id=p.organization_id JOIN public."user" u ON u.id=m.user_id WHERE lower(u.email)=$1 AND p.client_type='person' AND p.archived_at IS NULL LIMIT 1`,
+      [input.email]
+    )
+    clientId = result.rows[0]?.id
+    if (!clientId) {
+      const pending = await tx.query<{ id: string }>(
+        `SELECT p.organization_id AS id FROM clients.client_profile p JOIN public.invitation i ON i.organization_id=p.organization_id WHERE lower(i.email)=$1 AND p.client_type='person' AND p.archived_at IS NULL AND i.status='pending' ORDER BY i.expires_at DESC LIMIT 1`,
+        [input.email]
+      )
+      clientId = pending.rows[0]?.id
+    }
+  }
+  if (!clientId) {
+    // Use the public client creation contract and its registered hooks in this transaction.
+    const database = drizzle(tx)
+    clientId = await createClientInTransaction(database, actorId, {
+      clientType: input.type,
+      name: input.type === 'person' ? input.name : input.company,
+      ...(input.type === 'person' ? { firstName: input.firstName, lastName: input.lastName } : {}),
+      slug: `buyer-${randomUUID()}`,
+      officialName: input.type === 'person' ? input.name : input.company,
+      address: input.address,
+      registrationNumber: input.type === 'organization' ? input.registrationNumber || null : null,
+      vatNumber: input.type === 'organization' ? input.vatNumber || null : null,
+      invoiceEmail: input.email,
+      preferredLocale: locale,
+      moduleIds: ['invoices']
+    })
+  }
+  const existing = await tx.query(
+    `SELECT 1 FROM public.member m JOIN public."user" u ON u.id=m.user_id WHERE m.organization_id=$1 AND lower(u.email)=$2`,
+    [clientId, input.email]
+  )
+  let invitationId: string | null = null
+  if (!existing.rowCount) {
+    const pending = await tx.query<{ id: string }>(
+      "SELECT id FROM public.invitation WHERE organization_id=$1 AND lower(email)=$2 AND status='pending' LIMIT 1",
+      [clientId, input.email]
+    )
+    invitationId = pending.rows[0]?.id || randomUUID()
+    await tx.query(
+      `INSERT INTO public.invitation(id,organization_id,email,role,status,expires_at,inviter_id) VALUES($1,$2,$3,'owner','pending',now()+interval '7 days',$4) ON CONFLICT(id) DO UPDATE SET expires_at=now()+interval '7 days'`,
+      [invitationId, clientId, input.email, actorId]
+    )
+  }
+  return { clientId, invitationId }
+}

package/shared/feature.ts

@@ -48,3 +48,19 @@ export const clientsFeature: PortalFeatureDefinition<ClientAction> = {
     CLIENT: { owner: ['read', 'update', 'manageMembers'], admin: ['read', 'update', 'manageMembers'], member: ['read'] }
   }
 }
+
+export const clientsIcon = (allowedTypes: readonly string[] = []) =>
+  allowedTypes.includes('person') ? 'i-lucide-users-round' : 'i-lucide-building-2'
+
+export const createClientsFeature = (allowedTypes: readonly string[]): typeof clientsFeature => {
+  const icon = clientsIcon(allowedTypes)
+  return {
+    ...clientsFeature,
+    navigation: clientsFeature.navigation?.map((item) => ({ ...item, icon })),
+    modules: clientsFeature.modules?.map((item) => ({
+      ...item,
+      icon,
+      menuItems: item.menuItems?.map((entry) => ({ ...entry, icon }))
+    }))
+  }
+}

package/shared/personal-onboarding.ts

@@ -0,0 +1,6 @@
+export const needsPersonalOnboarding = (input: {
+  enabled: boolean
+  emailVerified: boolean
+  membershipCount: number
+  hasPendingInvitation: boolean
+}) => input.enabled && input.emailVerified && input.membershipCount === 0 && !input.hasPendingInvitation

package/shared/private-client-invitation.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod'
+
+export const privateClientInvitationSchema = z
+  .object({
+    requestId: z.uuid(),
+    clientId: z.string().min(1).optional(),
+    name: z.string().trim().min(2).max(160).optional(),
+    email: z.string().trim().toLowerCase().email(),
+    preferredLocale: z.enum(['en', 'nl']).default('en')
+  })
+  .refine((value) => Boolean(value.clientId || value.name), { message: 'Choose a client or enter a name' })

package/shared/types/client.ts

@@ -24,8 +24,13 @@ export interface GenericClientDto {
   id: string
   organizationId: string
   name: string
+  firstName: string | null
+  lastName: string | null
   slug: string
   logo: string | null
+  clientType: 'organization' | 'person'
+  timezone: string | null
+  schedulingTimezone: string
   officialName: string
   address: string
   registrationNumber: string | null