betterstart-cli 0.0.1

package/dist/assets/adapters/next/templates/init/hooks/use-upload.ts

@@ -0,0 +1,321 @@
+'use client'
+
+import { uploadMediaFromUrl } from '@admin/actions/upload'
+import type { UploadFileResult, UploadProgress } from '@admin/types'
+import { parseAcceptTypes } from '@admin/utils/upload/upload'
+import { type FileValidationConfig, validateFiles } from '@admin/utils/validation/validation'
+import { type UseMutationResult, useMutation } from '@tanstack/react-query'
+import * as React from 'react'
+
+export interface UseUploadOptions {
+  /** File validation configuration */
+  validationConfig?: FileValidationConfig
+  /** Accept string (e.g., "image/*") */
+  accept?: string
+  /** Optional maximum file size in MB */
+  maxSizeInMB?: number
+  /** Callback fired when upload progress changes */
+  onProgress?: (progress: UploadProgress[]) => void
+  /** Callback fired when upload succeeds */
+  onSuccess?: (result: UploadFileResult) => void
+  /** Callback fired when upload fails */
+  onError?: (error: Error) => void
+  /** Optional prefix for file paths in R2 */
+  prefix?: string
+  /** Whether completion callbacks should run for this upload surface */
+  isActive?: boolean
+}
+
+export interface UploadMutationVariables {
+  files: File[]
+  prefix?: string
+  activityId?: number
+}
+
+export interface UploadUrlMutationVariables {
+  url: string
+  prefix?: string
+  accept?: string
+  activityId?: number
+}
+
+export interface UseUploadReturn {
+  mutation: UseMutationResult<UploadFileResult, Error, UploadMutationVariables, unknown>
+  urlMutation: UseMutationResult<UploadFileResult, Error, UploadUrlMutationVariables, unknown>
+  progress: UploadProgress[]
+  isUploading: boolean
+  upload: (files: File[], prefix?: string) => void
+  uploadFromUrl: (
+    url: string,
+    prefix?: string,
+    acceptOverride?: string
+  ) => Promise<UploadFileResult>
+  validate: (files: File[]) => { valid: boolean; errors: string[] }
+}
+
+export function useUpload(options: UseUploadOptions = {}): UseUploadReturn {
+  const {
+    validationConfig: providedConfig,
+    accept,
+    maxSizeInMB,
+    onProgress,
+    onSuccess,
+    onError,
+    prefix: defaultPrefix,
+    isActive = true
+  } = options
+
+  const validationConfig = React.useMemo<FileValidationConfig>(() => {
+    const config: FileValidationConfig = { ...providedConfig }
+
+    if (accept) {
+      const parsedTypes = parseAcceptTypes(accept)
+      if (config.allowedTypes && config.allowedTypes.length > 0) {
+        config.allowedTypes = [...config.allowedTypes, ...parsedTypes].filter(
+          (v, i, a) => a.indexOf(v) === i
+        )
+      } else {
+        config.allowedTypes = parsedTypes
+      }
+    }
+
+    if (maxSizeInMB !== undefined) {
+      config.maxSizeInBytes = maxSizeInMB * 1024 * 1024
+    }
+
+    return config
+  }, [providedConfig, accept, maxSizeInMB])
+
+  const [progress, setProgress] = React.useState<UploadProgress[]>([])
+  const [_isPending, startTransition] = React.useTransition()
+  const mountedRef = React.useRef(true)
+  const activeRef = React.useRef(isActive)
+  const activeActivityIdRef = React.useRef(0)
+  const previousIsActiveRef = React.useRef(isActive)
+  const uploadAbortControllerRef = React.useRef<AbortController | null>(null)
+  const progressIntervalRef = React.useRef<ReturnType<typeof setInterval> | null>(null)
+  const progressResetTimeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null)
+  if (previousIsActiveRef.current !== isActive) {
+    previousIsActiveRef.current = isActive
+    activeActivityIdRef.current += 1
+  }
+  activeRef.current = isActive
+
+  const clearProgressResetTimeout = React.useCallback(() => {
+    if (progressResetTimeoutRef.current) {
+      clearTimeout(progressResetTimeoutRef.current)
+      progressResetTimeoutRef.current = null
+    }
+  }, [])
+
+  const clearProgressInterval = React.useCallback(() => {
+    if (progressIntervalRef.current) {
+      clearInterval(progressIntervalRef.current)
+      progressIntervalRef.current = null
+    }
+  }, [])
+
+  const abortActiveUpload = React.useCallback(() => {
+    if (uploadAbortControllerRef.current) {
+      uploadAbortControllerRef.current.abort()
+      uploadAbortControllerRef.current = null
+    }
+  }, [])
+
+  const cleanupActiveUpload = React.useCallback(() => {
+    clearProgressResetTimeout()
+    clearProgressInterval()
+    abortActiveUpload()
+  }, [abortActiveUpload, clearProgressInterval, clearProgressResetTimeout])
+
+  const isCurrentActiveMutation = React.useCallback((activityId?: number) => {
+    if (!mountedRef.current || !activeRef.current) return false
+    return activityId === undefined || activityId === activeActivityIdRef.current
+  }, [])
+
+  React.useEffect(() => {
+    mountedRef.current = true
+
+    return () => {
+      mountedRef.current = false
+      cleanupActiveUpload()
+    }
+  }, [cleanupActiveUpload])
+
+  const mutation = useMutation<UploadFileResult, Error, UploadMutationVariables>({
+    mutationFn: async ({ files, prefix = defaultPrefix }) => {
+      cleanupActiveUpload()
+      const abortController = new AbortController()
+      uploadAbortControllerRef.current = abortController
+
+      const initialProgress: UploadProgress[] = files.map((file) => ({
+        filename: file.name,
+        progress: 0,
+        loaded: 0,
+        total: file.size
+      }))
+      setProgress(initialProgress)
+      onProgress?.(initialProgress)
+
+      const formData = new FormData()
+      if (prefix) {
+        formData.append('prefix', prefix)
+      }
+
+      files.forEach((file, index) => {
+        formData.append(`file${index}`, file)
+      })
+
+      // Simulate progress since server doesn't support streaming
+      const progressInterval = setInterval(() => {
+        if (!mountedRef.current) return
+
+        setProgress((prev) =>
+          prev.map((p) => {
+            const newProgress = Math.min(p.progress + 10, 90)
+            return {
+              ...p,
+              progress: newProgress,
+              loaded: Math.floor((p.total * newProgress) / 100)
+            }
+          })
+        )
+      }, 200)
+      progressIntervalRef.current = progressInterval
+
+      try {
+        if (validationConfig?.maxSizeInBytes) {
+          formData.append('maxSizeInBytes', validationConfig.maxSizeInBytes.toString())
+        }
+        if (validationConfig?.maxFiles) {
+          formData.append('maxFiles', validationConfig.maxFiles.toString())
+        }
+        if (validationConfig?.allowedTypes?.length) {
+          formData.append('allowedTypes', validationConfig.allowedTypes.join(','))
+        }
+
+        const response = await fetch('/api/admin/upload', {
+          method: 'POST',
+          body: formData,
+          signal: abortController.signal
+        })
+
+        const result = (await response.json()) as UploadFileResult
+
+        if (result.success && mountedRef.current) {
+          const completeProgress: UploadProgress[] = files.map((file) => ({
+            filename: file.name,
+            progress: 100,
+            loaded: file.size,
+            total: file.size
+          }))
+          setProgress(completeProgress)
+          onProgress?.(completeProgress)
+        }
+
+        return result
+      } finally {
+        clearInterval(progressInterval)
+        if (progressIntervalRef.current === progressInterval) {
+          progressIntervalRef.current = null
+        }
+        if (uploadAbortControllerRef.current === abortController) {
+          uploadAbortControllerRef.current = null
+        }
+      }
+    },
+    onSuccess: (result, variables) => {
+      if (!mountedRef.current) return
+
+      if (!isCurrentActiveMutation(variables.activityId)) {
+        clearProgressResetTimeout()
+        startTransition(() => {
+          setProgress([])
+        })
+        return
+      }
+
+      onSuccess?.(result)
+      clearProgressResetTimeout()
+      progressResetTimeoutRef.current = setTimeout(() => {
+        progressResetTimeoutRef.current = null
+        startTransition(() => {
+          setProgress([])
+        })
+      }, 2000)
+    },
+    onError: (error, variables) => {
+      if (!mountedRef.current || error.name === 'AbortError') return
+
+      clearProgressResetTimeout()
+      setProgress([])
+      if (!isCurrentActiveMutation(variables.activityId)) return
+
+      onError?.(error)
+    }
+  })
+
+  const urlMutation = useMutation<UploadFileResult, Error, UploadUrlMutationVariables>({
+    mutationFn: async ({ url, prefix = defaultPrefix, accept: explicitAccept = accept }) =>
+      uploadMediaFromUrl(url, {
+        prefix,
+        accept: explicitAccept,
+        maxSizeInBytes: validationConfig.maxSizeInBytes
+      }),
+    onSuccess: (result, variables) => {
+      if (!isCurrentActiveMutation(variables.activityId)) return
+
+      onSuccess?.(result)
+    },
+    onError: (error, variables) => {
+      if (!isCurrentActiveMutation(variables.activityId)) return
+
+      onError?.(error)
+    }
+  })
+
+  const upload = React.useCallback(
+    (files: File[], prefix?: string) => {
+      mutation.mutate({
+        files,
+        prefix,
+        activityId: activeActivityIdRef.current
+      })
+    },
+    [mutation]
+  )
+
+  const uploadFromUrl = React.useCallback(
+    (url: string, prefix?: string, acceptOverride?: string) =>
+      urlMutation.mutateAsync({
+        url,
+        prefix,
+        accept: acceptOverride,
+        activityId: activeActivityIdRef.current
+      }),
+    [urlMutation]
+  )
+
+  const validate = React.useCallback(
+    (files: File[]) => {
+      const result = validateFiles(files, validationConfig)
+      return {
+        valid: result.valid,
+        errors: result.errors.map((e) => (e.filename ? `${e.filename}: ${e.error}` : e.error))
+      }
+    },
+    [validationConfig]
+  )
+
+  const isUploading = progress.some((p) => p.progress < 100)
+
+  return {
+    mutation,
+    urlMutation,
+    progress,
+    isUploading,
+    upload,
+    uploadFromUrl,
+    validate
+  }
+}

package/dist/assets/adapters/next/templates/init/hooks/use-users.ts

@@ -0,0 +1,12 @@
+'use client'
+
+import { getUsers } from '@admin/actions/users'
+import type { UsersPage } from '@admin/types/auth'
+import { useQuery } from '@tanstack/react-query'
+
+export function useUsers() {
+  return useQuery<UsersPage>({
+    queryKey: ['users'],
+    queryFn: () => getUsers()
+  })
+}

package/dist/assets/adapters/next/templates/init/lib/actions/auth/auth.ts

@@ -0,0 +1,58 @@
+import { sendPasswordResetEmail } from '@admin/actions/email'
+import db from '@admin/db'
+import * as schema from '@admin/db/schema'
+import { betterAuth } from 'better-auth'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { toNextJsHandler } from 'better-auth/next-js'
+
+export { toNextJsHandler }
+
+export const auth = betterAuth({
+  secret: process.env.BETTERSTART_AUTH_SECRET,
+  baseURL: process.env.BETTERSTART_AUTH_URL,
+  basePath: process.env.BETTERSTART_AUTH_BASE_PATH || '/api/admin/auth',
+  database: drizzleAdapter(db, {
+    provider: 'pg',
+    schema: {
+      user: schema.user,
+      session: schema.session,
+      account: schema.account,
+      verification: schema.verification
+    }
+  }),
+  emailAndPassword: {
+    enabled: true,
+    minPasswordLength: 8,
+    revokeSessionsOnPasswordReset: true,
+    sendResetPassword: async ({
+      user,
+      url
+    }: {
+      user: { email: string; name: string }
+      url: string
+    }) => {
+      await sendPasswordResetEmail({ user, url })
+    }
+  },
+  session: {
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+    updateAge: 60 * 60 * 24, // 1 day
+    cookieCache: {
+      enabled: true,
+      maxAge: 15 * 60 // 15 minutes — avoids DB round-trip for session validation
+    }
+  },
+  user: {
+    additionalFields: {
+      role: {
+        type: 'string',
+        required: false,
+        defaultValue: 'member',
+        input: false
+      }
+    }
+  }
+})
+
+export type Session = typeof auth.$Infer.Session
+export type User = typeof auth.$Infer.Session.user

package/dist/assets/adapters/next/templates/init/lib/actions/auth/client.ts

@@ -0,0 +1,12 @@
+'use client'
+
+import { createAuthClient } from 'better-auth/react'
+
+export const authClient = createAuthClient({
+  baseURL:
+    process.env.NEXT_PUBLIC_BETTERSTART_AUTH_URL ||
+    (typeof window !== 'undefined' ? window.location.origin : ''),
+  basePath: '/api/admin/auth'
+})
+
+export const { signIn, signUp, signOut, useSession } = authClient

package/dist/assets/adapters/next/templates/init/lib/actions/auth/middleware.ts

@@ -0,0 +1,46 @@
+import { UserRole } from '@admin/types/auth'
+import { getAdminPostLoginPath, isUserRole } from '@admin/utils/auth/roles'
+import { headers } from 'next/headers'
+import { redirect } from 'next/navigation'
+import { cache } from 'react'
+import { auth, type User } from './auth'
+
+export { UserRole } from '@admin/types/auth'
+
+interface GetSessionOptions {
+  disableCookieCache?: boolean
+}
+
+/**
+ * Get the current session from Better Auth.
+ * Wrapped with React.cache to deduplicate within a single request.
+ */
+export const getSession = cache(async (options: GetSessionOptions = {}) => {
+  const session = await auth.api.getSession({
+    query: options.disableCookieCache ? { disableCookieCache: true } : undefined,
+    headers: await headers()
+  })
+  return session
+})
+
+/**
+ * Require the user to have one of the specified roles.
+ * Redirects to /admin/login if unauthenticated and to /admin/profile if authenticated
+ * without the required Admin role.
+ */
+export async function requireRole(allowedRoles: readonly UserRole[]): Promise<User> {
+  const session = await getSession({ disableCookieCache: true })
+
+  if (!session?.user) {
+    redirect('/admin/login')
+  }
+
+  const user = session.user
+  const role = isUserRole(user.role) ? user.role : UserRole.MEMBER
+
+  if (!allowedRoles.includes(role)) {
+    redirect(getAdminPostLoginPath(role))
+  }
+
+  return user
+}

package/dist/assets/adapters/next/templates/init/lib/actions/email/form-delivery.ts

@@ -0,0 +1,72 @@
+import { sendEmail } from '@admin/actions/email'
+import type { SendEmailResult } from '@admin/actions/email/types'
+import {
+  type FormEmailDeliveryInput,
+  isValidEmail,
+  normalizeEmailList,
+  renderNotificationEmail,
+  renderThankYouEmail
+} from '@admin/utils/email/form-delivery'
+
+export type { FormEmailDeliveryInput } from '@admin/utils/email/form-delivery'
+
+interface QueuedFormEmail {
+  label: string
+  to: string | string[]
+  subject: string
+  html: string
+}
+
+async function sendQueuedEmail(email: QueuedFormEmail): Promise<{
+  label: string
+  result: SendEmailResult
+}> {
+  const result = await sendEmail({
+    to: email.to,
+    subject: email.subject,
+    html: email.html
+  })
+
+  return {
+    label: email.label,
+    result
+  }
+}
+
+export async function sendFormEmails(input: FormEmailDeliveryInput): Promise<void> {
+  const notificationEmails = normalizeEmailList(input.notificationEmails)
+  const submitterEmail = input.submitterEmail?.trim()
+  const queuedEmails: QueuedFormEmail[] = []
+
+  if (notificationEmails.length > 0) {
+    queuedEmails.push({
+      label: 'form notification',
+      to: notificationEmails,
+      subject: `New ${input.formLabel} submission`,
+      html: renderNotificationEmail(input)
+    })
+  }
+
+  if (submitterEmail && isValidEmail(submitterEmail)) {
+    queuedEmails.push({
+      label: 'form submitter confirmation',
+      to: submitterEmail,
+      subject: `We received your ${input.formLabel} submission`,
+      html: renderThankYouEmail(input)
+    })
+  }
+
+  if (queuedEmails.length === 0) {
+    return
+  }
+
+  const results = await Promise.all(queuedEmails.map(sendQueuedEmail))
+  const failures = results.filter(({ result }) => !result.delivered)
+
+  if (failures.length > 0) {
+    console.error(
+      `Failed to send ${failures.length} ${input.formName} form email(s):`,
+      failures.map(({ label, result }) => `${label}: ${result.reason ?? 'unknown error'}`)
+    )
+  }
+}

package/dist/assets/adapters/next/templates/init/lib/actions/email/index.ts

@@ -0,0 +1,4 @@
+export { isEmailDeliveryConfigured } from './is-email-delivery-configured'
+export { getEmailProvider } from './provider'
+export { sendEmail } from './send-email'
+export { sendPasswordResetEmail } from './send-password-reset-email'

package/dist/assets/adapters/next/templates/init/lib/actions/email/is-email-delivery-configured.ts

@@ -0,0 +1,5 @@
+import { getEmailProvider } from './provider'
+
+export function isEmailDeliveryConfigured(): boolean {
+  return getEmailProvider().isConfigured()
+}

package/dist/assets/adapters/next/templates/init/lib/actions/email/none.ts

@@ -0,0 +1,24 @@
+import type {
+  AdminEmailProvider,
+  PasswordResetEmailInput,
+  SendEmailInput,
+  SendEmailResult
+} from '@admin/actions/email/types'
+
+const NOT_CONFIGURED_REASON = 'Email delivery is not configured.'
+
+async function notDelivered(
+  _input: SendEmailInput | PasswordResetEmailInput
+): Promise<SendEmailResult> {
+  return {
+    delivered: false,
+    reason: NOT_CONFIGURED_REASON
+  }
+}
+
+export const noneEmailProvider: AdminEmailProvider = {
+  id: 'none',
+  isConfigured: () => false,
+  sendEmail: notDelivered,
+  sendPasswordResetEmail: notDelivered
+}

package/dist/assets/adapters/next/templates/init/lib/actions/email/provider.ts

@@ -0,0 +1,6 @@
+import { noneEmailProvider } from '@admin/actions/email/none'
+import type { AdminEmailProvider } from '@admin/actions/email/types'
+
+export function getEmailProvider(): AdminEmailProvider {
+  return noneEmailProvider
+}

package/dist/assets/adapters/next/templates/init/lib/actions/email/send-email.ts

@@ -0,0 +1,6 @@
+import type { SendEmailInput, SendEmailResult } from '@admin/actions/email/types'
+import { getEmailProvider } from './provider'
+
+export async function sendEmail(input: SendEmailInput): Promise<SendEmailResult> {
+  return getEmailProvider().sendEmail(input)
+}

package/dist/assets/adapters/next/templates/init/lib/actions/email/send-password-reset-email.ts

@@ -0,0 +1,10 @@
+import type { PasswordResetEmailInput } from '@admin/actions/email/types'
+import { getEmailProvider } from './provider'
+
+export async function sendPasswordResetEmail(input: PasswordResetEmailInput): Promise<void> {
+  const result = await getEmailProvider().sendPasswordResetEmail(input)
+
+  if (!result.delivered) {
+    throw new Error(result.reason ?? 'Email delivery is not configured.')
+  }
+}

package/dist/assets/adapters/next/templates/init/lib/actions/email/types.ts

@@ -0,0 +1,25 @@
+export interface SendEmailInput {
+  to: string | string[]
+  subject: string
+  html: string
+}
+
+export interface SendEmailResult {
+  delivered: boolean
+  reason?: string
+}
+
+export interface PasswordResetEmailInput {
+  user: {
+    email: string
+    name: string
+  }
+  url: string
+}
+
+export interface AdminEmailProvider {
+  id: string
+  isConfigured: () => boolean
+  sendEmail: (input: SendEmailInput) => Promise<SendEmailResult>
+  sendPasswordResetEmail: (input: PasswordResetEmailInput) => Promise<SendEmailResult>
+}

package/dist/assets/adapters/next/templates/init/lib/actions/entity-versions/get-entity-versions.ts

@@ -0,0 +1,48 @@
+'use server'
+
+import db from '@admin/db'
+import { entityVersions, user } from '@admin/db/schema'
+import { and, desc, eq } from 'drizzle-orm'
+import { alias } from 'drizzle-orm/pg-core'
+import { cacheLife, cacheTag } from 'next/cache'
+import type { EntityVersionWithAuthor } from './types'
+import { entityVersionsCacheTags } from './types'
+
+const createdByUser = alias(user, 'entity_version_created_by_user')
+
+export async function getEntityVersions(
+  entityType: string,
+  entityId: string
+): Promise<EntityVersionWithAuthor[]> {
+  'use cache'
+  cacheLife('max')
+  cacheTag(entityVersionsCacheTags.for(entityType, entityId))
+
+  try {
+    const rows = await db
+      .select({
+        id: entityVersions.id,
+        entityType: entityVersions.entityType,
+        entityId: entityVersions.entityId,
+        version: entityVersions.version,
+        data: entityVersions.data,
+        createdAt: entityVersions.createdAt,
+        createdBy: entityVersions.createdBy,
+        createdByUser: {
+          id: createdByUser.id,
+          name: createdByUser.name,
+          email: createdByUser.email,
+          image: createdByUser.image
+        }
+      })
+      .from(entityVersions)
+      .leftJoin(createdByUser, eq(entityVersions.createdBy, createdByUser.id))
+      .where(and(eq(entityVersions.entityType, entityType), eq(entityVersions.entityId, entityId)))
+      .orderBy(desc(entityVersions.version), desc(entityVersions.createdAt))
+
+    return rows as EntityVersionWithAuthor[]
+  } catch (error) {
+    console.error('Error fetching entity versions:', error)
+    return []
+  }
+}

package/dist/assets/adapters/next/templates/init/lib/actions/entity-versions/index.ts

@@ -0,0 +1,10 @@
+export { getEntityVersions } from './get-entity-versions'
+export { createEntityVersion } from './internal-create-entity-version'
+export { deleteEntityVersions } from './internal-delete-entity-versions'
+export type {
+  EntityVersion,
+  EntityVersionAuthor,
+  EntityVersionData,
+  EntityVersionWithAuthor
+} from './types'
+export { entityVersionsCacheTags } from './types'