@nuxt-customer-portal/core 0.3.3 → 0.4.0

package/server/utils/auth.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod'
+import { isPersonalClient, assertClientInvitationAcceptance } from './client-account-policy'
 import { isPortalDemo } from './demo'
 import { demoMessage, isDemoRequestAllowed } from '../../shared/demo-policy'
 import { betterAuth } from 'better-auth'
@@ -6,6 +8,7 @@ import { drizzleAdapter } from 'better-auth/adapters/drizzle'
 import { sendEmail } from './email'
 import { getInvitationEmailContent, getOTPEmailContent, getDeleteAccountEmailContent } from './email-texts'
 import { admin as adminPlugin, customSession, emailOTP, openAPI, organization } from 'better-auth/plugins'
+import { apiKey } from '@better-auth/api-key'
 import { db } from './db'
 import { and, eq, gt } from 'drizzle-orm'
 import {
@@ -15,12 +18,23 @@ import {
   verification as verificationTable,
   organization as organizationTable,
   member as organizationMemberTable,
-  invitation as organizationInvitationTable
+  invitation as organizationInvitationTable,
+  apiKey as apiKeyTable
 } from '../db/schema/auth-schema'
 import { nanoid } from 'nanoid'
-import { ac, user, admin as adminRole } from '../../shared/permissions'
+import {
+  ac,
+  user,
+  admin as adminRole,
+  organizationAc,
+  organizationOwner,
+  organizationAdmin,
+  organizationMember
+} from '../../shared/permissions'
 import { canViewOrganizationDirectory } from '../../shared/feature-registry'
 import { isSystemAdminEmail, parseSystemAdminEmails } from './admin-email-allowlist'
+import { runUserIdentityChangedHooks } from './business-hooks'
+import { socialAuthProviderEnabled } from '../../shared/social-auth'
 
 /**
  * Generate an ID in the same format as better-auth uses (nanoid)
@@ -30,13 +44,20 @@ export function generateId(): string {
   return nanoid()
 }
 
-const envFlag = (value: string | undefined, fallback = true) => (value === undefined ? fallback : value === 'true')
 const portalAuthConfig = useRuntimeConfig().portalAuth
 const registrationMode = ['open', 'invitation-only', 'disabled'].includes(process.env.PORTAL_REGISTRATION_MODE || '')
   ? process.env.PORTAL_REGISTRATION_MODE
   : portalAuthConfig.registrationMode
-const githubEnabled = envFlag(process.env.PORTAL_GITHUB_ENABLED, portalAuthConfig.githubEnabled)
-const googleEnabled = envFlag(process.env.PORTAL_GOOGLE_ENABLED, portalAuthConfig.googleEnabled)
+const githubEnabled = socialAuthProviderEnabled(
+  process.env.PORTAL_GITHUB_ENABLED,
+  process.env.GITHUB_CLIENT_ID,
+  process.env.GITHUB_CLIENT_SECRET
+)
+const googleEnabled = socialAuthProviderEnabled(
+  process.env.PORTAL_GOOGLE_ENABLED,
+  process.env.GOOGLE_CLIENT_ID,
+  process.env.GOOGLE_CLIENT_SECRET
+)
 const systemAdminEmails = isPortalDemo() ? new Set<string>() : parseSystemAdminEmails(process.env.ADMIN_EMAILS)
 
 export const auth = betterAuth({
@@ -50,7 +71,8 @@ export const auth = betterAuth({
       member: organizationMemberTable,
       verification: verificationTable,
       organization: organizationTable,
-      invitation: organizationInvitationTable
+      invitation: organizationInvitationTable,
+      apikey: apiKeyTable
     },
     usePlural: false
     // Tables are singular (e.g., "user"), so no need for usePlural
@@ -66,6 +88,95 @@ export const auth = betterAuth({
           message: demoMessage(ctx.headers?.get('accept-language') || '')
         })
       }
+      if (
+        ['/api-key/create', '/api-key/list', '/api-key/get', '/api-key/update', '/api-key/delete'].includes(ctx.path)
+      ) {
+        const body = (ctx.body ?? {}) as Record<string, unknown>
+        const query = (ctx.query ?? {}) as Record<string, unknown>
+        const current = await getSessionFromCtx(ctx)
+        const actorId = (body.userId as string | undefined) ?? current?.user.id
+        if (actorId) {
+          const [actor] = await db
+            .select({ role: userTable.role })
+            .from(userTable)
+            .where(eq(userTable.id, actorId))
+            .limit(1)
+          if (actor?.role !== 'admin') {
+            throw new APIError('FORBIDDEN', { message: 'System administrator access is required to manage API keys' })
+          }
+        }
+        let organizationId = (body.organizationId ?? query.organizationId) as string | undefined
+        const keyId = (body.keyId ?? query.id) as string | undefined
+        if (!organizationId && !keyId) {
+          organizationId = current?.session.activeOrganizationId ?? undefined
+        }
+        if (!organizationId && keyId) {
+          const [key] = await db
+            .select({ referenceId: apiKeyTable.referenceId })
+            .from(apiKeyTable)
+            .where(eq(apiKeyTable.id, keyId))
+            .limit(1)
+          organizationId = key?.referenceId
+        }
+        if (organizationId) {
+          const [selected] = await db
+            .select({ organizationType: organizationTable.organizationType })
+            .from(organizationTable)
+            .where(eq(organizationTable.id, organizationId))
+            .limit(1)
+          if (selected?.organizationType !== 'PROVIDER') {
+            throw new APIError('FORBIDDEN', {
+              message: 'API keys are only available to provider organizations'
+            })
+          }
+        }
+      }
+      if (ctx.path.startsWith('/organization/') && ctx.body) {
+        const current = await getSessionFromCtx(ctx)
+        const body = ctx.body as Record<string, unknown>
+        let target = body.organizationId as string | undefined
+        if (typeof body.invitationId === 'string') {
+          const [invite] = await db
+            .select()
+            .from(organizationInvitationTable)
+            .where(eq(organizationInvitationTable.id, body.invitationId))
+            .limit(1)
+          target = invite?.organizationId
+        }
+        const memberId = body.memberId ?? body.memberIdOrEmail
+        if (typeof memberId === 'string') {
+          const [selected] = await db
+            .select()
+            .from(organizationMemberTable)
+            .where(eq(organizationMemberTable.id, memberId))
+            .limit(1)
+          target = selected?.organizationId ?? target
+        }
+        target ||= current?.session.activeOrganizationId ?? undefined
+        if (target && (await isPersonalClient(target))) {
+          if (ctx.path === '/organization/accept-invitation') {
+            if (!current?.user.emailVerified) {
+              throw new APIError('FORBIDDEN', { message: 'Verify your email first' })
+            }
+            try {
+              await assertClientInvitationAcceptance(target, current.user.id)
+            } catch {
+              throw new APIError('CONFLICT', { message: 'Personal account already exists. Contact your coach.' })
+            }
+          } else if (
+            ![
+              '/organization/set-active',
+              '/organization/reject-invitation',
+              '/organization/check-slug',
+              '/organization/has-permission'
+            ].includes(ctx.path)
+          ) {
+            throw new APIError('FORBIDDEN', {
+              message: 'Personal account membership and organization settings cannot be changed through this route'
+            })
+          }
+        }
+      }
       if (ctx.path !== '/organization/list-members' && ctx.path !== '/organization/list-invitations') {
         return
       }
@@ -101,6 +212,11 @@ export const auth = betterAuth({
     requireEmailVerification: true
   },
   user: {
+    additionalFields: {
+      timezone: { type: 'string', required: false, input: false },
+      firstName: { type: 'string', required: false, validator: { input: z.string().trim().min(1).max(80) } },
+      lastName: { type: 'string', required: false, validator: { input: z.string().trim().min(1).max(80) } }
+    },
     deleteUser: {
       enabled: true,
       sendDeleteAccountVerification: async ({ user, url, token: _token }, _request) => {
@@ -130,19 +246,19 @@ export const auth = betterAuth({
     }
   },
   socialProviders: {
-    ...(githubEnabled && process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET
+    ...(githubEnabled
       ? {
           github: {
-            clientId: process.env.GITHUB_CLIENT_ID,
-            clientSecret: process.env.GITHUB_CLIENT_SECRET
+            clientId: process.env.GITHUB_CLIENT_ID!,
+            clientSecret: process.env.GITHUB_CLIENT_SECRET!
           }
         }
       : {}),
-    ...(googleEnabled && process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET
+    ...(googleEnabled
       ? {
           google: {
-            clientId: process.env.GOOGLE_CLIENT_ID,
-            clientSecret: process.env.GOOGLE_CLIENT_SECRET
+            clientId: process.env.GOOGLE_CLIENT_ID!,
+            clientSecret: process.env.GOOGLE_CLIENT_SECRET!
           }
         }
       : {})
@@ -209,6 +325,14 @@ export const auth = betterAuth({
             createdAt: new Date()
           })
         }
+      },
+      update: {
+        after: async (updatedUser) => {
+          await runUserIdentityChangedHooks(db, updatedUser.id, {
+            firstName: typeof updatedUser.firstName === 'string' ? updatedUser.firstName : null,
+            lastName: typeof updatedUser.lastName === 'string' ? updatedUser.lastName : null
+          })
+        }
       }
     },
     session: {
@@ -238,6 +362,12 @@ export const auth = betterAuth({
     }),
     organization({
       allowUserToCreateOrganization: false,
+      ac: organizationAc,
+      roles: {
+        owner: organizationOwner,
+        admin: organizationAdmin,
+        member: organizationMember
+      },
       schema: {
         organization: {
           additionalFields: {
@@ -290,6 +420,14 @@ export const auth = betterAuth({
         }
       }
     }),
+    apiKey({
+      references: 'organization',
+      defaultPrefix: 'portal_',
+      requireName: true,
+      startingCharactersConfig: { shouldStore: true, charactersLength: 12 },
+      keyExpiration: { minExpiresIn: 1 / 24, maxExpiresIn: 365 },
+      rateLimit: { enabled: true, timeWindow: 60_000, maxRequests: 120 }
+    }),
     emailOTP({
       overrideDefaultEmailVerification: true,
       async sendVerificationOTP({ email, otp, type }) {

package/server/utils/business-hooks.ts

@@ -26,3 +26,37 @@ export const assertTimeEntriesReopenable = async (organizationId: string, entryI
     await guard(organizationId, entryIds)
   }
 }
+
+type UserDisplayNameChangedHook = (transaction: unknown, userId: string, name: string) => Promise<void>
+const userDisplayNameChangedHooks: UserDisplayNameChangedHook[] = []
+export const registerUserDisplayNameChangedHook = (hook: UserDisplayNameChangedHook) => {
+  if (!userDisplayNameChangedHooks.includes(hook)) {
+    userDisplayNameChangedHooks.push(hook)
+  }
+}
+export const runUserDisplayNameChangedHooks = async (transaction: unknown, userId: string, name: string) => {
+  for (const hook of userDisplayNameChangedHooks) {
+    await hook(transaction, userId, name)
+  }
+}
+
+type UserIdentityChangedHook = (
+  transaction: unknown,
+  userId: string,
+  identity: { firstName: string | null; lastName: string | null }
+) => Promise<void>
+const userIdentityChangedHooks: UserIdentityChangedHook[] = []
+export const registerUserIdentityChangedHook = (hook: UserIdentityChangedHook) => {
+  if (!userIdentityChangedHooks.includes(hook)) {
+    userIdentityChangedHooks.push(hook)
+  }
+}
+export const runUserIdentityChangedHooks = async (
+  transaction: unknown,
+  userId: string,
+  identity: { firstName: string | null; lastName: string | null }
+) => {
+  for (const hook of userIdentityChangedHooks) {
+    await hook(transaction, userId, identity)
+  }
+}

package/server/utils/client-account-policy.ts

@@ -0,0 +1,15 @@
+/** Optional client package policies; core remains usable without Clients. */
+type AccountPolicy = {
+  isPersonal: (organizationId: string) => Promise<boolean>
+  assertAcceptance: (organizationId: string, userId: string) => Promise<void>
+  getIdentity: (organizationId: string) => Promise<{ name: string; firstName?: string; lastName?: string } | null>
+}
+let policy: AccountPolicy | undefined
+export const registerClientAccountPolicy = (value: AccountPolicy) => {
+  policy = value
+}
+export const isPersonalClient = async (id: string) => (policy ? policy.isPersonal(id) : false)
+export const assertClientInvitationAcceptance = async (id: string, userId: string) => {
+  await policy?.assertAcceptance(id, userId)
+}
+export const getClientAccountIdentity = async (id: string) => (policy ? policy.getIdentity(id) : null)

package/server/utils/client-configuration.ts

@@ -0,0 +1,9 @@
+export interface ClientConfigurationOverride {
+  allowedTypes: ('organization' | 'person')[]
+  personalSelfRegistration: boolean
+}
+let resolver: (() => Promise<ClientConfigurationOverride>) | undefined
+export const registerClientConfigurationResolver = (value: typeof resolver) => {
+  resolver = value
+}
+export const resolveClientConfigurationOverride = () => resolver?.()

package/server/utils/email-texts.ts

@@ -38,6 +38,33 @@ export function getInvitationEmailContent(params: InvitationEmailParams) {
   }
 }
 
+export interface PersonalAccountInvitationEmailParams {
+  invitationLink: string
+  recipientName?: string | null
+}
+
+export function getPersonalAccountInvitationEmailContent(params: PersonalAccountInvitationEmailParams) {
+  return {
+    messageId: 'personal-account-invitation',
+    values: {
+      ...(params.recipientName?.trim() ? { recipient_name: params.recipientName.trim() } : {}),
+      action_url: params.invitationLink
+    },
+    subject: 'Set up your personal portal account',
+    params: {
+      greeting: 'Hello,',
+      body_text: `A personal portal profile has been created for you. Set up your account to access your purchases, appointments, invoices, and shared files.
+             <p style="text-align: center;">
+                <a href="${params.invitationLink}" class="button">Set up your account</a>
+            </p>
+        `,
+      action_url: params.invitationLink,
+      action_text: 'Set up your account',
+      footer_text: 'This account setup link expires soon. If you did not expect this message, please ignore it.'
+    }
+  }
+}
+
 /**
  * Centralized OTP email content
  * Used for email verification, sign-in, and password reset OTP codes

package/server/utils/email.ts

@@ -1,4 +1,6 @@
 import { coreFeature } from '@nuxt-customer-portal/core/shared/core-feature'
+import { emailRecipientName } from '@nuxt-customer-portal/core/shared/email-recipient'
+import { pool } from './db'
 import { sendPortalEmail } from './portal-email'
 
 // Define the structure for the parameters used in the template
@@ -18,20 +20,41 @@ interface SendEmailArgs {
   messageId?: string
   values?: Record<string, string>
   locale?: string
+  idempotencyKey?: string
 }
 
 // Updated sendEmail function using the template
-export const sendEmail = async ({ to, subject, params, messageId, values = {}, locale }: SendEmailArgs) => {
+export const sendEmail = async ({
+  to,
+  subject,
+  params,
+  messageId,
+  values = {},
+  locale,
+  idempotencyKey
+}: SendEmailArgs) => {
   const definition = coreFeature.emails?.find((item) => item.id === messageId)
   if (!definition) {
     throw new Error(`Unknown core email definition: ${messageId}`)
   }
+  const recipient = await pool.query<{ first_name: string | null; name: string | null }>(
+    'SELECT first_name,name FROM public."user" WHERE lower(email)=lower($1) LIMIT 1',
+    [to]
+  )
   return sendPortalEmail({
     moduleId: coreFeature.id,
     definition,
     locale,
-    values,
+    values: {
+      recipient_name: emailRecipientName({
+        firstName: recipient.rows[0]?.first_name,
+        displayName: recipient.rows[0]?.name,
+        email: to
+      }),
+      ...values
+    },
     to,
+    idempotencyKey,
     text: messageId ? undefined : { subject, body: params.body_text, footer: params.footer_text }
   })
 }

package/server/utils/invitation-management.ts

@@ -1,3 +1,4 @@
+import { isPersonalClient } from './client-account-policy'
 import { and, eq, gt } from 'drizzle-orm'
 import { createError } from 'h3'
 import { invitationChangeSchema } from '../../shared/invitation-validation'
@@ -10,6 +11,9 @@ export const changePendingInvitation = async (organizationId: string, invitation
     throw createError({ statusCode: 400, message: 'Invalid invitation change' })
   }
   const change = parsed.data
+  if ('role' in change && (await isPersonalClient(organizationId))) {
+    throw createError({ statusCode: 403, message: 'Personal invitation roles cannot be changed' })
+  }
   const [updated] = await db
     .update(invitation)
     .set(change)

package/server/utils/openapi-contracts.ts

@@ -6,6 +6,7 @@ type OpenApiOperation = Record<string, unknown>
 
 export interface PortalOpenApiContracts {
   owner: string
+  securitySchemes?: Record<string, Record<string, unknown>>
   query?: Record<string, z.ZodType>
   body?: Record<string, z.ZodType>
   requestBody?: Record<string, Record<string, unknown>>
@@ -120,6 +121,13 @@ const addContract = (operation: OpenApiOperation): void => {
 }
 
 export const enrichOpenApiContracts = <T extends OpenApiDocument>(document: T): T => {
+  const components = (document.components ?? {}) as Record<string, unknown>
+  components.securitySchemes = Object.assign(
+    {},
+    components.securitySchemes,
+    ...(contractRegistry[contractRegistryKey] ?? []).map((item) => item.securitySchemes ?? {})
+  )
+  Object.assign(document, { components })
   for (const pathItem of Object.values(document.paths ?? {})) {
     for (const operation of Object.values(pathItem)) {
       addContract(operation)

package/server/utils/permissions.ts

@@ -1,3 +1,4 @@
+import { isPersonalClient } from './client-account-policy'
 import { db } from './db'
 import { member as memberTable, organization as organizationTable } from '../db/schema/auth-schema'
 import { eq, and } from 'drizzle-orm'
@@ -113,6 +114,9 @@ export const hasPermission = async (
   subject: string,
   action: string
 ): Promise<boolean> => {
+  if (organizationId && ['member', 'invitation'].includes(subject) && (await isPersonalClient(organizationId))) {
+    return false
+  }
   const { permissions } = await getUserPermissions(userId, systemRole, organizationId)
   const subjectPermissions = permissions[subject] || []
   return Array.isArray(subjectPermissions) && subjectPermissions.includes(action)

package/server/utils/portal-email.ts

@@ -3,6 +3,7 @@ import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:
 import { eq } from 'drizzle-orm'
 import { createError } from 'h3'
 import { Resend } from 'resend'
+import { marked } from 'marked'
 import type {
   PortalEmailDefinition,
   PortalEmailLocale,
@@ -47,6 +48,9 @@ const TEMPLATE_PLACEHOLDERS = new Set([
 const placeholderPattern = /{{\s*([a-z0-9_]+)\s*}}/gi
 const senderPattern = /^\s*([^<>]+?)\s*<\s*([^<>]+)\s*>\s*$/
 
+export const renderPortalEmailMarkdown = (value: string) =>
+  marked.parse(value, { async: false, breaks: true, gfm: true }) as string
+
 const parseSender = (value = '') => {
   const match = value.match(senderPattern)
   return match ? { fromName: match[1]!.trim(), fromEmail: match[2]!.trim() } : { fromName: '', fromEmail: value.trim() }
@@ -341,8 +345,10 @@ export const renderPortalEmail = async (input: {
   const messageValues = { ...input.values, brand_name: brandName }
   const allowed = new Set([...input.definition.placeholders.map((item) => item.key), 'brand_name'])
   const subject = replacePlaceholders(text.subject, messageValues, allowed)
-  const body = replacePlaceholders(text.body, messageValues, allowed)
-  const footer = replacePlaceholders(text.footer ?? '', messageValues, allowed)
+  const bodySource = replacePlaceholders(text.body, messageValues, allowed)
+  const footerSource = replacePlaceholders(text.footer ?? '', messageValues, allowed)
+  const body = renderPortalEmailMarkdown(bodySource)
+  const footer = renderPortalEmailMarkdown(footerSource)
   const htmlTemplate = input.htmlTemplate ?? settings.htmlTemplate
   validatePortalEmailTemplate(htmlTemplate)
   const inlineAttachments: PortalEmailAttachment[] = []
@@ -392,6 +398,7 @@ export const sendPortalEmail = async (input: {
   fromName?: string
   attachments?: PortalEmailAttachment[]
   idempotencyKey?: string
+  subjectPrefix?: string
 }) => {
   if (isPortalDemo()) {
     rejectDemoAction()
@@ -400,6 +407,7 @@ export const sendPortalEmail = async (input: {
     renderPortalEmail({ ...input, inlineBrandAssets: true }),
     providerConfiguration()
   ])
+  const subject = `${input.subjectPrefix ?? ''}${rendered.subject}`
   const fromEmail = input.fromEmail || provider.fromEmail
   const fromName = input.fromName || provider.fromName
   const from = fromName ? `${fromName.replace(/[<>\r\n]/g, '')} <${fromEmail}>` : fromEmail
@@ -408,7 +416,7 @@ export const sendPortalEmail = async (input: {
       from,
       to: [input.to],
       cc: input.cc?.length ? input.cc : undefined,
-      subject: rendered.subject,
+      subject,
       html: rendered.html,
       text: rendered.text,
       attachments: [...rendered.inlineAttachments, ...(input.attachments ?? [])]
@@ -418,7 +426,7 @@ export const sendPortalEmail = async (input: {
   if (error) {
     throw new Error(error.message)
   }
-  return { ...data, rendered }
+  return { ...data, rendered: { ...rendered, subject } }
 }
 
 export const retrievePortalEmail = async (providerMessageId: string) => {

package/server/utils/public-api-route.ts

@@ -0,0 +1,14 @@
+export function isPublicStoreRoute(method: string, pathname: string) {
+  return (
+    (method === 'GET' &&
+      (/^\/api\/store\/v1\/products(?:\/[^/]+)?$/.test(pathname) ||
+        /^\/api\/store\/(product|media)\/[^/]+$/.test(pathname) ||
+        /^\/api\/store\/planning\/[^/]+\/availability$/.test(pathname) ||
+        pathname === '/api/store/planning/hold' ||
+        /^\/api\/store\/sandbox-checkout\/[^/]+$/.test(pathname))) ||
+    (method === 'POST' &&
+      (['/api/store/checkout', '/api/store/webhooks/stripe', '/api/store/planning/holds'].includes(pathname) ||
+        /^\/api\/store\/sandbox-checkout\/[^/]+$/.test(pathname))) ||
+    (method === 'DELETE' && pathname === '/api/store/planning/hold')
+  )
+}

package/server/utils/public-invitation-route.ts

@@ -0,0 +1,3 @@
+export const isPublicInvitationRoute = (method: string, pathname: string) =>
+  (method === 'GET' && pathname === '/api/organizations/get-invitation') ||
+  (method === 'POST' && pathname === '/api/organizations/invitation-signup')

package/server/utils/timezone-validation.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod'
+import { isValidTimezone } from '../../shared/timezone'
+
+export const timezoneSchema = z.string().trim().max(100).refine(isValidTimezone, 'A valid IANA timezone is required')

package/server/utils/timezones.ts

@@ -0,0 +1,28 @@
+import { eq } from 'drizzle-orm'
+import { db } from './db'
+import { organization, organizationSettings, user } from '../db/schema/auth-schema'
+import { DEFAULT_TIMEZONE, resolveTimezones } from '../../shared/timezone'
+
+export const getProviderTimezone = async () => {
+  const [provider] = await db
+    .select({ timezone: organizationSettings.timezone })
+    .from(organization)
+    .leftJoin(organizationSettings, eq(organization.id, organizationSettings.organizationId))
+    .where(eq(organization.organizationType, 'PROVIDER'))
+    .limit(1)
+  return provider?.timezone || DEFAULT_TIMEZONE
+}
+type ClientTimezoneResolver = (id: string) => Promise<string | null>
+let clientResolver: ClientTimezoneResolver = async () => null
+export const registerClientTimezoneResolver = (resolver: ClientTimezoneResolver) => {
+  clientResolver = resolver
+}
+/** Caller must authorize the user and active organization before exposing this projection. */
+export const getResolvedTimezones = async (userId: string, clientOrganizationId?: string | null) => {
+  const [providerTimezone, clientTimezone, users] = await Promise.all([
+    getProviderTimezone(),
+    clientOrganizationId ? clientResolver(clientOrganizationId) : null,
+    db.select({ timezone: user.timezone }).from(user).where(eq(user.id, userId)).limit(1)
+  ])
+  return resolveTimezones({ providerTimezone, clientTimezone, userTimezone: users[0]?.timezone ?? null })
+}

package/shared/appointment-time.ts

@@ -0,0 +1,43 @@
+export interface AppointmentTimeOptions {
+  locale?: string | string[]
+  timeZone: string
+  midnight: string
+  dateStyle?: Intl.DateTimeFormatOptions['dateStyle']
+  includeDate?: boolean
+}
+
+export function formatAppointmentTime(value: string | Date, options: AppointmentTimeOptions): string {
+  const date = new Date(value)
+  const parts = new Intl.DateTimeFormat('en', {
+    hour: '2-digit',
+    minute: '2-digit',
+    hourCycle: 'h23',
+    timeZone: options.timeZone
+  }).formatToParts(date)
+  if (
+    parts.find((part) => part.type === 'hour')?.value === '00' &&
+    parts.find((part) => part.type === 'minute')?.value === '00'
+  ) {
+    return options.midnight
+  }
+  return new Intl.DateTimeFormat(options.locale, { timeStyle: 'short', timeZone: options.timeZone }).format(date)
+}
+
+export function formatAppointmentRange(
+  start: string | Date,
+  end: string | Date,
+  options: AppointmentTimeOptions
+): string {
+  if (options.includeDate === false) {
+    return `${formatAppointmentTime(start, options)} – ${formatAppointmentTime(end, options)}`
+  }
+  const formatter = new Intl.DateTimeFormat(options.locale, {
+    dateStyle: options.dateStyle ?? 'long',
+    timeStyle: 'short',
+    timeZone: options.timeZone
+  })
+  const endTime = formatAppointmentTime(end, options)
+  return endTime === options.midnight
+    ? `${formatter.format(new Date(start))} – ${options.midnight}`
+    : formatter.formatRange(new Date(start), new Date(end))
+}