feat(web): server-side pagination for the contacts page

- store total now reflects the server count; loadContacts accepts skip and
  limit and remembers the current window so mutation refreshes stay in place
- contacts page uses VDataTableServer with items-length bound to the server
  total; page/size changes fetch the correct skip/limit and a debounced
  query resets to page 1 without duplicate requests
- delete bumps the load generation so an in-flight load cannot resurrect a
  deleted contact, without leaving loading stuck or hiding delete errors
- remove the dead filteredContacts computed and add defensive null
  coalescing for emails/phone_numbers in the table display
- regenerate API models with the new contacts total field

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: AchoArnold

web/app/pages/contacts/index.vue

@@ -69,6 +69,13 @@ const deleteDialog = ref(false)
 const importDialog = ref(false)
 const saving = ref(false)
 
+// Server-driven pagination state for VDataTableServer.
+const page = ref(1)
+const itemsPerPage = ref(10)
+// initialLoadComplete gates the table's initial @update:options emit so the
+// first fetch is driven by onMounted rather than firing twice on mount.
+const initialLoadComplete = ref(false)
+
 const editingId = ref<string | null>(null)
 const pendingDelete = ref<EntitiesContact | null>(null)
 
@@ -143,9 +150,10 @@ function openEdit(contact: EntitiesContact) {
   editingId.value = contact.id
   form.value = {
     name: contact.name ?? '',
-    phoneNumbers:
-      contact.phone_numbers.length > 0 ? [...contact.phone_numbers] : [''],
-    emails: contact.emails.length > 0 ? [...contact.emails] : [''],
+    phoneNumbers: contact.phone_numbers?.length
+      ? [...contact.phone_numbers]
+      : [''],
+    emails: contact.emails?.length ? [...contact.emails] : [''],
     properties: Object.entries(contact.properties ?? {}).map(
       ([key, value]) => ({ key, value }),
     ),
@@ -300,24 +308,50 @@ async function submitImport() {
   }
 }
 
+function fetchContacts() {
+  const skip = (page.value - 1) * itemsPerPage.value
+  return contactsStore
+    .loadContacts({ force: true, skip, limit: itemsPerPage.value })
+    .catch(() => {
+      // The store already surfaced the failure via a notification.
+    })
+}
+
+function onUpdateOptions(options: { page: number; itemsPerPage: number }) {
+  page.value = options.page
+  itemsPerPage.value = options.itemsPerPage
+
+  // Ignore the initial emit fired while the table mounts; onMounted owns the
+  // first fetch so the request is not duplicated.
+  if (!initialLoadComplete.value) {
+    return
+  }
+  fetchContacts()
+}
+
 watch(
   () => contactsStore.search,
   () => {
     if (searchTimer) {
       clearTimeout(searchTimer)
     }
     searchTimer = setTimeout(() => {
-      contactsStore.loadContacts(true).catch(() => {
-        // The store already surfaced the failure via a notification.
-      })
+      // A new query always resets to the first page. If we are already on
+      // page 1 the page ref does not change, so no @update:options fires and
+      // we fetch directly; otherwise resetting the page drives the fetch via
+      // onUpdateOptions. Either way exactly one request is made.
+      if (page.value !== 1) {
+        page.value = 1
+      } else {
+        fetchContacts()
+      }
     }, 350)
   },
 )
 
 onMounted(() => {
-  contactsStore.loadContacts(true).catch(() => {
-    // The store already surfaced the failure via a notification.
-  })
+  initialLoadComplete.value = true
+  fetchContacts()
 })
 
 onBeforeUnmount(() => {
@@ -386,15 +420,18 @@ onBeforeUnmount(() => {
           />
 
           <VCard variant="outlined">
-            <VDataTable
+            <VDataTableServer
+              v-model:page="page"
+              v-model:items-per-page="itemsPerPage"
               :headers="headers"
               :items="contactsStore.contacts"
+              :items-length="contactsStore.total"
               :loading="contactsStore.loading"
-              :items-per-page="10"
               :items-per-page-options="itemsPerPageOptions"
               item-value="id"
               hover
               loading-text="Loading contacts…"
+              @update:options="onUpdateOptions"
             >
               <template #[`item.name`]="{ item }">
                 <div class="d-flex align-center py-2">
@@ -416,11 +453,11 @@ onBeforeUnmount(() => {
 
               <template #[`item.phone_numbers`]="{ item }">
                 <div
-                  v-if="item.phone_numbers.length"
+                  v-if="item.phone_numbers?.length"
                   class="d-flex flex-column ga-1 py-2"
                 >
                   <VChip
-                    v-for="phone in item.phone_numbers"
+                    v-for="phone in item.phone_numbers ?? []"
                     :key="phone"
                     size="small"
                     variant="tonal"
@@ -435,11 +472,11 @@ onBeforeUnmount(() => {
 
               <template #[`item.emails`]="{ item }">
                 <div
-                  v-if="item.emails.length"
+                  v-if="item.emails?.length"
                   class="d-flex flex-column ga-1 py-2"
                 >
                   <span
-                    v-for="email in item.emails"
+                    v-for="email in item.emails ?? []"
                     :key="email"
                     class="d-flex align-center text-body-2"
                   >
@@ -518,7 +555,7 @@ onBeforeUnmount(() => {
                   </VBtn>
                 </div>
               </template>
-            </VDataTable>
+            </VDataTableServer>
           </VCard>
         </VCol>
       </VRow>

web/app/stores/contacts.ts

@@ -1,5 +1,5 @@
 import { defineStore } from 'pinia'
-import { computed, ref } from 'vue'
+import { ref } from 'vue'
 import type { EntitiesContact } from '~~/shared/types/api'
 import { getApiErrorMessage } from '~/utils/api-error'
 
@@ -10,50 +10,71 @@ export interface ContactInput {
   properties?: Record<string, string>
 }
 
+export interface LoadContactsOptions {
+  force?: boolean
+  skip?: number
+  limit?: number
+}
+
+// DEFAULT_LIMIT mirrors the contacts page's initial items-per-page. It is only
+// used when a caller (e.g. a mutation refresh) does not specify its own limit.
+const DEFAULT_LIMIT = 10
+
 export const useContactsStore = defineStore('contacts', () => {
   const contacts = ref<EntitiesContact[]>([])
+  const total = ref(0)
   const loading = ref(false)
   const search = ref('')
   const { apiFetch } = useApi()
   const notificationsStore = useNotificationsStore()
   let loadContactsGeneration = 0
 
-  const total = computed(() => contacts.value.length)
+  // The pagination window last requested by the page. Mutation-triggered
+  // refreshes reuse it so the user stays on the page they were viewing.
+  let currentSkip = 0
+  let currentLimit = DEFAULT_LIMIT
 
-  const filteredContacts = computed<EntitiesContact[]>(() => {
-    const term = search.value.trim().toLowerCase()
-    if (!term) return contacts.value
+  function normalizeOptions(
+    options: LoadContactsOptions | boolean,
+  ): LoadContactsOptions {
+    if (typeof options === 'boolean') {
+      return { force: options }
+    }
+    return options
+  }
 
-    return contacts.value.filter((contact) => {
-      const name = contact.name.toLowerCase()
-      const emails = contact.emails.join(' ').toLowerCase()
-      const phoneNumbers = contact.phone_numbers.join(' ').toLowerCase()
+  async function loadContacts(
+    options: LoadContactsOptions | boolean = {},
+  ): Promise<void> {
+    const { force = false, skip, limit } = normalizeOptions(options)
 
-      return (
-        name.includes(term) ||
-        emails.includes(term) ||
-        phoneNumbers.includes(term)
-      )
-    })
-  })
+    if (skip !== undefined) {
+      currentSkip = skip
+    }
+    if (limit !== undefined) {
+      currentLimit = limit
+    }
 
-  async function loadContacts(force = false): Promise<void> {
     if (contacts.value.length > 0 && !force) return
 
     const generation = ++loadContactsGeneration
     loading.value = true
     try {
       const term = search.value.trim()
-      const params: Record<string, string | number> = { limit: 100 }
+      const params: Record<string, string | number> = {
+        skip: currentSkip,
+        limit: currentLimit,
+      }
       if (term) {
         params.query = term
       }
-      const response = await apiFetch<{ data: EntitiesContact[] }>(
-        '/v1/contacts',
-        { params },
-      )
+      const response = await apiFetch<{
+        data: EntitiesContact[]
+        total?: number
+      }>('/v1/contacts', { params })
       if (generation === loadContactsGeneration) {
         contacts.value = response.data ?? []
+        total.value = response.total ?? contacts.value.length
       }
     } catch (error: unknown) {
       if (generation !== loadContactsGeneration) {
@@ -135,7 +156,12 @@ export const useContactsStore = defineStore('contacts', () => {
     loading.value = true
     try {
       await apiFetch(`/v1/contacts/${id}`, { method: 'DELETE' })
+      // Invalidate any in-flight load so a stale response cannot resurrect the
+      // just-deleted contact. Bumping the generation makes loadContacts skip
+      // its assignment (and its finally toggling loading) for the older request.
+      loadContactsGeneration++
       contacts.value = contacts.value.filter((contact) => contact.id !== id)
+      total.value = Math.max(0, total.value - 1)
       notificationsStore.addNotification({
         message: 'Contact deleted',
         type: 'success',
@@ -183,16 +209,18 @@ export const useContactsStore = defineStore('contacts', () => {
   function resetState() {
     loadContactsGeneration++
     contacts.value = []
+    total.value = 0
     loading.value = false
     search.value = ''
+    currentSkip = 0
+    currentLimit = DEFAULT_LIMIT
   }
 
   return {
     contacts,
+    total,
     loading,
     search,
-    total,
-    filteredContacts,
     loadContacts,
     saveContacts,
     updateContact,

web/shared/types/api.ts

@@ -679,6 +679,12 @@ export interface ResponsesContactsResponse {
   message: string;
   /** @example "success" */
   status: string;
+  /**
+   * Total is the number of contacts matching the request filter for the
+   * user, independent of the pagination skip/limit applied to Data.
+   * @example 57
+   */
+  total: number;
 }
 
 export interface ResponsesDiscordResponse {