@nuxt-customer-portal/core 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# @nuxt-customer-portal/core
+
+## 0.3.0
+
+Declare the Nuxt UI dependency used by the package's public components and types,
+so npm installations do not depend on another package's dependency layout.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nuxt Customer Portal contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# Portal core layer
+
+Portal core is the stable boundary between the host application and reusable feature layers.
+
+Feature layers register a `PortalFeatureDefinition` containing navigation, dashboard widgets, surfaces, and an organization-role policy. Client code consumes authentication and active-organization state through `usePortalSession`; server handlers import database, session, tenant, and authorization adapters from `@nuxt-customer-portal/core/server`.
+
+Feature layers must not import host paths through `~/` or `~~/`. Drizzle schema files are the exception to alias-based imports because Drizzle Kit does not resolve Nuxt aliases; local schemas reference portal core’s physical schema while the host composes all schemas into one migration stream.
+
+Portal-core and authentication database objects remain in PostgreSQL's `public`
+schema. Each feature layer owns a separate PostgreSQL schema named after the
+layer, with hyphens converted to underscores (for example,
+`service-requests` uses `service_requests`). Feature tables may reference
+portal-core tables across schemas.
+
+## Reusable pagination
+
+`usePaginatedResource<Item, Filters>` owns request cancellation, stale-response
+protection, pagination state, append/replace behavior, deduplication, and errors.
+A feature supplies only its fetch adapter and stable item key:
+
+```ts
+const products = usePaginatedResource<Product, ProductFilters>({
+  pageSize: 20,
+  getKey: (product) => product.id,
+  fetchPage: ({ filters, page, pageSize, signal }) =>
+    $fetch('/api/products', {
+      query: { ...filters, page, pageSize },
+      signal
+    })
+})
+```
+
+Use `useAutoPagination` with a list container and trailing sentinel when the next
+page should load automatically. Conventional pagination controls can use the
+same `pagination` state alongside it.

package/app/composables/useAutoPagination.ts

@@ -0,0 +1,30 @@
+export interface AutoPaginationOptions {
+  sentinel: Ref<HTMLElement | null>
+  scrollContainer?: Ref<HTMLElement | null>
+  canLoadMore: MaybeRefOrGetter<boolean>
+  loading: MaybeRefOrGetter<boolean>
+  loadMore: () => unknown
+  rootMargin?: string
+}
+
+export const useAutoPagination = (options: AutoPaginationOptions) => {
+  const { stop } = useIntersectionObserver(
+    options.sentinel,
+    ([entry]) => {
+      if (!entry?.isIntersecting) {
+        return
+      }
+      if (toValue(options.loading) || !toValue(options.canLoadMore)) {
+        return
+      }
+      void options.loadMore()
+    },
+    {
+      root: options.scrollContainer,
+      rootMargin: options.rootMargin ?? '0px 0px 240px 0px',
+      threshold: 0
+    }
+  )
+
+  return { stop }
+}

package/app/composables/useOrganization.ts

@@ -0,0 +1,117 @@
+import { authClient } from '@nuxt-customer-portal/core/app/utils/auth-client'
+import type { MemberRole, Organization, OrganizationType } from '@nuxt-customer-portal/core/shared/types/index'
+
+export const useOrganization = () => {
+  // Get current user's organization
+  const getCurrentOrganization = async () => {
+    const { data: member } = await authClient.organization.getActiveMember()
+    return member?.organizationId
+  }
+
+  // Check if user is organization owner
+  const isOrganizationOwner = async () => {
+    const { data: roleData } = await authClient.organization.getActiveMemberRole()
+    return roleData?.role === 'owner'
+  }
+
+  // Check if user is organization admin
+  const isOrganizationAdmin = async () => {
+    const { data: roleData } = await authClient.organization.getActiveMemberRole()
+    return roleData?.role === 'admin' || roleData?.role === 'owner'
+  }
+
+  // List all user organizations
+  const getUserOrganizations = async () => {
+    const { data } = await authClient.organization.list()
+    return data
+  }
+
+  const createOrganization = async (data: {
+    name: string
+    slug: string
+    organizationType: OrganizationType
+    keepCurrentActiveOrganization?: boolean
+  }) => {
+    return await authClient.organization.create(data)
+  }
+
+  const updateAdminOrganization = async (
+    organizationId: string,
+    data: { name: string; slug: string; officialCompanyName: string; logo: string; avatarLogo?: string }
+  ) => {
+    return await $fetch<Organization>(`/api/admin/organizations/${organizationId}`, {
+      method: 'PATCH',
+      body: data
+    })
+  }
+
+  const getActiveMember = async () => {
+    return await authClient.organization.getActiveMember()
+  }
+
+  const listMembers = async (organizationId: string) => {
+    return await authClient.organization.listMembers({
+      query: { organizationId }
+    })
+  }
+
+  const removeMember = async (memberIdOrEmail: string, organizationId: string) => {
+    return await authClient.organization.removeMember({
+      memberIdOrEmail,
+      organizationId
+    })
+  }
+
+  const inviteMember = async (email: string, organizationId: string, role: MemberRole = 'member', resend = false) => {
+    return await authClient.organization.inviteMember({
+      email,
+      organizationId,
+      role,
+      resend
+    })
+  }
+
+  const listInvitations = async (organizationId: string) => {
+    return await authClient.organization.listInvitations({
+      query: { organizationId }
+    })
+  }
+
+  const resendInvitation = async (invitationId: string, organizationId: string, email: string, role: MemberRole) => {
+    return await authClient.organization.inviteMember({
+      email,
+      organizationId,
+      role,
+      resend: true
+    })
+  }
+
+  const cancelInvitation = async (invitationId: string) => {
+    return await authClient.organization.cancelInvitation({
+      invitationId
+    })
+  }
+
+  const acceptInvitation = async (invitationId: string) => {
+    return await authClient.organization.acceptInvitation({
+      invitationId
+    })
+  }
+
+  return {
+    getCurrentOrganization,
+    isOrganizationOwner,
+    isOrganizationAdmin,
+    getUserOrganizations,
+    createOrganization,
+    updateAdminOrganization,
+    getActiveMember,
+    listMembers,
+    removeMember,
+    inviteMember,
+    listInvitations,
+    resendInvitation,
+    cancelInvitation,
+    acceptInvitation
+  }
+}

package/app/composables/usePaginatedResource.ts

@@ -0,0 +1,167 @@
+export interface PaginationState {
+  total: number
+  page: number
+  pageSize: number
+  pageCount: number
+}
+
+export interface PaginatedResult<Item> {
+  items: Item[]
+  pagination: PaginationState
+}
+
+export interface PaginatedFetchContext<Filters> {
+  filters: Filters
+  page: number
+  pageSize: number
+  signal: AbortSignal
+}
+
+export interface PaginatedResourceOptions<Item, Filters> {
+  fetchPage: (context: PaginatedFetchContext<Filters>) => Promise<PaginatedResult<Item>>
+  getKey: (item: Item) => PropertyKey
+  pageSize?: number
+}
+
+export const usePaginatedResource = <Item, Filters extends object>(
+  options: PaginatedResourceOptions<Item, Filters>
+) => {
+  const defaultPageSize = options.pageSize ?? 20
+  const items = ref<Item[]>([]) as Ref<Item[]>
+  const pagination = ref<PaginationState>({
+    total: 0,
+    page: 1,
+    pageSize: defaultPageSize,
+    pageCount: 0
+  })
+  const pending = ref(false)
+  const loadingNextPage = ref(false)
+  const loadingPreviousPage = ref(false)
+  const error = ref<Error | null>(null)
+  const firstLoadedPage = ref(1)
+  const lastLoadedPage = ref(1)
+
+  let requestSequence = 0
+  let abortController: AbortController | undefined
+  let activeFilters: Filters | undefined
+
+  const loadPage = async (
+    filters: Filters,
+    loadOptions: {
+      mode?: 'replace' | 'append' | 'prepend'
+      page?: number
+      pageSize?: number
+    } = {}
+  ) => {
+    const sequence = ++requestSequence
+    const page = loadOptions.page ?? 1
+    const pageSize = loadOptions.pageSize ?? defaultPageSize
+    const mode = loadOptions.mode ?? 'replace'
+    activeFilters = filters
+    abortController?.abort()
+    abortController = new AbortController()
+    pending.value = true
+    loadingNextPage.value = mode === 'append'
+    loadingPreviousPage.value = mode === 'prepend'
+    error.value = null
+
+    try {
+      const result = await options.fetchPage({
+        filters,
+        page,
+        pageSize,
+        signal: abortController.signal
+      })
+
+      if (sequence !== requestSequence) {
+        return
+      }
+      if (mode === 'append') {
+        const existingKeys = new Set(items.value.map(options.getKey))
+        items.value = [...items.value, ...result.items.filter((item) => !existingKeys.has(options.getKey(item)))]
+        lastLoadedPage.value = Math.max(lastLoadedPage.value, result.pagination.page)
+      } else if (mode === 'prepend') {
+        const existingKeys = new Set(items.value.map(options.getKey))
+        items.value = [...result.items.filter((item) => !existingKeys.has(options.getKey(item))), ...items.value]
+        firstLoadedPage.value = Math.min(firstLoadedPage.value, result.pagination.page)
+      } else {
+        items.value = result.items
+        firstLoadedPage.value = result.pagination.page
+        lastLoadedPage.value = result.pagination.page
+      }
+      pagination.value = result.pagination
+      return result
+    } catch (cause) {
+      if (sequence !== requestSequence || (cause instanceof Error && cause.name === 'AbortError')) {
+        return
+      }
+      error.value = cause instanceof Error ? cause : new Error('Failed to load data')
+      throw cause
+    } finally {
+      if (sequence === requestSequence) {
+        pending.value = false
+        loadingNextPage.value = false
+        loadingPreviousPage.value = false
+      }
+    }
+  }
+
+  const loadNextPage = (filters: Filters = activeFilters as Filters) => {
+    if (!filters || pending.value || lastLoadedPage.value >= pagination.value.pageCount) {
+      return
+    }
+    return loadPage(filters, {
+      mode: 'append',
+      page: lastLoadedPage.value + 1,
+      pageSize: pagination.value.pageSize
+    })
+  }
+
+  const loadPreviousPage = (filters: Filters = activeFilters as Filters) => {
+    if (!filters || pending.value || firstLoadedPage.value <= 1) {
+      return
+    }
+    return loadPage(filters, {
+      mode: 'prepend',
+      page: firstLoadedPage.value - 1,
+      pageSize: pagination.value.pageSize
+    })
+  }
+
+  const reset = () => {
+    abortController?.abort()
+    requestSequence++
+    items.value = []
+    pagination.value = {
+      total: 0,
+      page: 1,
+      pageSize: defaultPageSize,
+      pageCount: 0
+    }
+    pending.value = false
+    loadingNextPage.value = false
+    loadingPreviousPage.value = false
+    error.value = null
+    firstLoadedPage.value = 1
+    lastLoadedPage.value = 1
+  }
+
+  onScopeDispose(() => abortController?.abort())
+
+  return {
+    items: readonly(items),
+    pagination: readonly(pagination),
+    pending: readonly(pending),
+    loadingNextPage: readonly(loadingNextPage),
+    loadingPreviousPage: readonly(loadingPreviousPage),
+    firstLoadedPage: readonly(firstLoadedPage),
+    lastLoadedPage: readonly(lastLoadedPage),
+    hasNextPage: computed(() => lastLoadedPage.value < pagination.value.pageCount),
+    hasPreviousPage: computed(() => firstLoadedPage.value > 1),
+    error: readonly(error),
+    loadPage,
+    loadNextPage,
+    loadPreviousPage,
+    reset
+  }
+}

package/app/composables/usePortalFeatures.ts

@@ -0,0 +1,74 @@
+import type { PortalFeatureDefinition } from '@nuxt-customer-portal/core/shared/types/feature'
+import {
+  mergePortalModuleMenuContributions,
+  sortPortalDashboardWidgets,
+  upsertPortalFeature
+} from '@nuxt-customer-portal/core/shared/feature-registry'
+
+export const usePortalFeatures = () => {
+  const features = useState<PortalFeatureDefinition[]>('portal-features', () => [])
+  const enabledModules = useState<string[] | null>('portal-enabled-modules', () => null)
+
+  const featureEnabled = (feature: PortalFeatureDefinition) => {
+    if (!enabledModules.value) {
+      return true
+    }
+    if (!['timesheets', 'invoices', 'service-requests', 'invoice-timesheets'].includes(feature.id)) {
+      return true
+    }
+    return enabledModules.value.includes(feature.id)
+  }
+
+  const registerFeature = (feature: PortalFeatureDefinition) => {
+    features.value = upsertPortalFeature(features.value, feature)
+  }
+
+  const navigation = computed(() =>
+    features.value
+      .filter(featureEnabled)
+      .flatMap((feature) => feature.navigation ?? [])
+      .sort((a, b) => (a.order ?? 100) - (b.order ?? 100))
+  )
+
+  const dashboardWidgets = computed(() =>
+    sortPortalDashboardWidgets(
+      features.value.filter(featureEnabled).flatMap((feature) => feature.dashboardWidgets ?? [])
+    )
+  )
+
+  const modules = computed(() => {
+    const enabledFeatures = features.value.filter(featureEnabled)
+    return mergePortalModuleMenuContributions(
+      enabledFeatures.flatMap((feature) => feature.modules ?? []),
+      enabledFeatures.flatMap((feature) => feature.moduleMenuItems ?? [])
+    ).sort((a, b) => (a.order ?? 100) - (b.order ?? 100))
+  })
+
+  const surfaces = computed(() =>
+    features.value
+      .filter(featureEnabled)
+      .flatMap((feature) => feature.surfaces ?? [])
+      .sort((a, b) => (a.order ?? 100) - (b.order ?? 100) || a.id.localeCompare(b.id))
+  )
+
+  const contributionsFor = (surface: string) =>
+    computed(() => surfaces.value.filter((contribution) => contribution.surface === surface))
+
+  const clientIntegrations = computed(() =>
+    features.value
+      .filter(featureEnabled)
+      .flatMap((feature) => (feature.clientIntegration ? [feature.clientIntegration] : []))
+      .sort((left, right) => left.moduleId.localeCompare(right.moduleId))
+  )
+
+  return {
+    features: readonly(features),
+    navigation,
+    modules,
+    dashboardWidgets,
+    surfaces,
+    clientIntegrations,
+    contributionsFor,
+    registerFeature
+  }
+}

package/app/composables/usePortalSession.ts

@@ -0,0 +1,20 @@
+export const usePortalSession = () => {
+  const userStore = useUserStore()
+  const {
+    activeOrganizationId,
+    activeOrganizationRole,
+    activeOrganizationType,
+    currentUser,
+    isAdmin,
+    isAuthenticated
+  } = storeToRefs(userStore)
+
+  return {
+    activeOrganizationId: readonly(activeOrganizationId),
+    activeOrganizationRole: readonly(activeOrganizationRole),
+    activeOrganizationType: readonly(activeOrganizationType),
+    currentUser: readonly(currentUser),
+    isSystemAdmin: readonly(isAdmin),
+    isAuthenticated: readonly(isAuthenticated)
+  }
+}