@nuxt-customer-portal/invoices 0.8.4 → 0.8.6

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @nuxt-customer-portal/invoices
 
+## 0.8.6
+
+### Patch Changes
+
+- @nuxt-customer-portal/clients@0.8.6
+- @nuxt-customer-portal/core@0.8.6
+- @nuxt-customer-portal/organizations@0.8.6
+- @nuxt-customer-portal/ui@0.8.6
+
+## 0.8.5
+
+### Patch Changes
+
+- ddc08fb: Open customer-facing order details from order cards and link directly to each order's invoice. Preserve order list search, filters, sorting, pagination and scroll position through both back links, and disable the Invoice action when no invoice exists.
+- ddc08fb: Avoid automatic provider lookups for resolved invoice email deliveries. Cache failed attempts, back off checks for older unresolved emails, and prevent duplicate concurrent lookups. Keep manual refresh available for later engagement and complaint events with a short cooldown.
+  - @nuxt-customer-portal/clients@0.8.5
+  - @nuxt-customer-portal/core@0.8.5
+  - @nuxt-customer-portal/organizations@0.8.5
+  - @nuxt-customer-portal/ui@0.8.5
+
 ## 0.8.4
 
 ### Patch Changes

package/README.md

@@ -2,3 +2,7 @@
 
 Standalone sales and received invoicing for Nuxt Customer Portal. Add the optional
 `@nuxt-customer-portal/invoice-timesheets` layer to create invoices from approved time.
+
+Invoice email status is refreshed on opening an invoice only when an unresolved delivery is due for a check. Delivered, opened, clicked, bounced, failed, suppressed and complained messages are excluded from automatic checks. Unresolved messages are checked at most every five minutes during the first day, hourly after one day, and daily after a week. Failed lookup attempts observe the same cooldown while preserving the last known status. Concurrent requests claim each attempt in the database before contacting the provider.
+
+Manual refresh can check resolved deliveries for later engagement or complaints, with a one-minute cooldown per message. These events are not updated automatically after delivery; receiving them continuously would require a Resend webhook integration.

package/app/components/InvoicesInvoiceDetail.vue

@@ -6,7 +6,10 @@ import type {
   InvoiceDto,
   InvoiceHistoryDto
 } from '@nuxt-customer-portal/invoices/shared/types/invoice'
-import { isKnownEmailProviderEvent } from '@nuxt-customer-portal/invoices/shared/email-delivery-status'
+import {
+  isKnownEmailProviderEvent,
+  shouldRefreshInvoiceEmailStatus
+} from '@nuxt-customer-portal/invoices/shared/email-delivery-status'
 
 const props = withDefaults(
   defineProps<{
@@ -377,7 +380,10 @@ const attachmentUrl = (attachmentId: string) =>
     ? `/api/invoices/client/invoices/${props.invoice.id}/attachments/${attachmentId}`
     : `/api/invoices/admin/invoices/${props.invoice.id}/attachments/${attachmentId}`
 const refreshEmailStatuses = async (forceRefresh = false) => {
-  if (!emailDeliveries.value.some((delivery) => delivery.providerMessageId)) {
+  if (
+    refreshingEmailStatuses.value ||
+    !emailDeliveries.value.some((delivery) => shouldRefreshInvoiceEmailStatus(delivery, forceRefresh))
+  ) {
     return
   }
   refreshingEmailStatuses.value = true

package/app/pages/admin/invoices/[id].vue

@@ -2,6 +2,12 @@
 defineOptions({ name: 'AdminInvoiceDetailPage' })
 
 const route = useRoute()
+const ordersReturnTo = computed(() =>
+  typeof route.query.ordersReturnTo === 'string' &&
+  /^\/admin\/products\/orders(?:\?|$)/.test(route.query.ordersReturnTo)
+    ? route.query.ordersReturnTo
+    : undefined
+)
 const { t } = useI18n()
 const api = useInvoices()
 const invoiceId = computed(() => String(route.params.id))
@@ -31,6 +37,12 @@ useSeoMeta({
       icon="i-lucide-circle-alert"
       :title="t('features.invoices.admin.invoiceNotFound')"
     />
-    <InvoicesInvoiceDetail v-else-if="invoice" :invoice="invoice" :refresh="refresh" />
+    <InvoicesInvoiceDetail
+      v-else-if="invoice"
+      :invoice="invoice"
+      :refresh="refresh"
+      :back-to="ordersReturnTo"
+      :back-label="ordersReturnTo ? t('features.invoices.admin.backToOrderList') : undefined"
+    />
   </section>
 </template>

package/i18n/locales/en.json

@@ -153,6 +153,7 @@
         "paid": "Paid",
         "backToInvoices": "Back to invoices",
         "backToOrders": "Back to purchases",
+        "backToOrderList": "Back to orders",
         "invoiceTitle": "Invoice {number}",
         "invoiceDocumentTitle": "INVOICE",
         "print": "Print",

package/i18n/locales/nl.json

@@ -153,6 +153,7 @@
         "paid": "Betaald",
         "backToInvoices": "Terug naar facturen",
         "backToOrders": "Terug naar aankopen",
+        "backToOrderList": "Terug naar bestellingen",
         "invoiceTitle": "Factuur {number}",
         "invoiceDocumentTitle": "FACTUUR",
         "print": "Afdrukken",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt-customer-portal/invoices",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "license": "MIT",
   "homepage": "https://nuxt-customer-portal.com",
   "repository": {
@@ -44,10 +44,10 @@
     "pg": "^8.22.0",
     "resend": "^6.18.1",
     "zod": "^4.4.3",
-    "@nuxt-customer-portal/core": "^0.8.4",
-    "@nuxt-customer-portal/organizations": "^0.8.4",
-    "@nuxt-customer-portal/ui": "^0.8.4",
-    "@nuxt-customer-portal/clients": "^0.8.4"
+    "@nuxt-customer-portal/core": "^0.8.6",
+    "@nuxt-customer-portal/ui": "^0.8.6",
+    "@nuxt-customer-portal/clients": "^0.8.6",
+    "@nuxt-customer-portal/organizations": "^0.8.6"
   },
   "peerDependencies": {
     "nuxt": "^4.5.1",

package/portal.manifest.mjs

@@ -1,6 +1,6 @@
 export default {
   id: 'invoices',
-  version: '0.8.4',
+  version: '0.8.6',
   source: '@nuxt-customer-portal/invoices',
   clientModuleId: 'invoices',
   dependsOn: ['core', 'ui', 'organizations', 'clients'],

package/server/utils/invoice-email-status.ts

@@ -1,13 +1,14 @@
-import { and, eq, isNotNull } from 'drizzle-orm'
+import { and, eq, isNotNull, isNull } from 'drizzle-orm'
 import { db } from '@nuxt-customer-portal/core/server/portal'
 import { retrievePortalEmail } from '@nuxt-customer-portal/core/server/utils/portal-email'
-import { normalizeEmailProviderEvent } from '@nuxt-customer-portal/invoices/shared/email-delivery-status'
+import {
+  normalizeEmailProviderEvent,
+  shouldRefreshInvoiceEmailStatus
+} from '@nuxt-customer-portal/invoices/shared/email-delivery-status'
 import type { InvoiceEmailStatusRefreshDto } from '@nuxt-customer-portal/invoices/shared/types/invoice'
 import { invoice, invoiceEmailDelivery } from '@nuxt-customer-portal/invoices/server/db/schema/invoices'
 import { getInvoice } from './invoice-repository'
 
-const STATUS_CACHE_MS = 60_000
-
 export const refreshInvoiceEmailStatuses = async (
   organizationId: string,
   invoiceId: string,
@@ -26,38 +27,47 @@ export const refreshInvoiceEmailStatuses = async (
       )
     )
   const failures: InvoiceEmailStatusRefreshDto['failures'] = []
-  const staleBefore = Date.now() - STATUS_CACHE_MS
-
-  await Promise.all(
-    deliveries.map(async ({ delivery }) => {
-      if (
-        !forceRefresh &&
-        delivery.providerStatusCheckedAt &&
-        delivery.providerStatusCheckedAt.getTime() > staleBefore
-      ) {
-        return
-      }
-      try {
-        const providerEmail = await retrievePortalEmail(delivery.providerMessageId!)
-        const checkedAt = new Date()
-        await db
-          .update(invoiceEmailDelivery)
-          .set({
-            providerLastEvent: providerEmail.last_event ? normalizeEmailProviderEvent(providerEmail.last_event) : null,
-            providerStatusCheckedAt: checkedAt
-          })
-          .where(eq(invoiceEmailDelivery.id, delivery.id))
-      } catch (error) {
-        failures.push({
-          deliveryId: delivery.id,
-          code:
-            error instanceof Error && error.message.includes('not configured')
-              ? 'PROVIDER_NOT_CONFIGURED'
-              : 'PROVIDER_LOOKUP_FAILED'
+  for (const { delivery } of deliveries) {
+    if (!shouldRefreshInvoiceEmailStatus(delivery, forceRefresh)) {
+      continue
+    }
+    // Claim the attempt before calling the provider. Concurrent requests skip it,
+    // and failures also observe the cooldown without changing the known status.
+    const [claimed] = await db
+      .update(invoiceEmailDelivery)
+      .set({ providerStatusCheckedAt: new Date() })
+      .where(
+        and(
+          eq(invoiceEmailDelivery.id, delivery.id),
+          delivery.providerStatusCheckedAt
+            ? eq(invoiceEmailDelivery.providerStatusCheckedAt, delivery.providerStatusCheckedAt)
+            : isNull(invoiceEmailDelivery.providerStatusCheckedAt)
+        )
+      )
+      .returning({ id: invoiceEmailDelivery.id })
+    if (!claimed) {
+      continue
+    }
+    try {
+      const providerEmail = await retrievePortalEmail(delivery.providerMessageId!)
+      await db
+        .update(invoiceEmailDelivery)
+        .set({
+          providerLastEvent: providerEmail.last_event
+            ? normalizeEmailProviderEvent(providerEmail.last_event)
+            : delivery.providerLastEvent
         })
-      }
-    })
-  )
+        .where(eq(invoiceEmailDelivery.id, delivery.id))
+    } catch (error) {
+      failures.push({
+        deliveryId: delivery.id,
+        code:
+          error instanceof Error && error.message.includes('not configured')
+            ? 'PROVIDER_NOT_CONFIGURED'
+            : 'PROVIDER_LOOKUP_FAILED'
+      })
+    }
+  }
 
   const refreshed = await getInvoice(organizationId, invoiceId)
   return { deliveries: refreshed.emailDeliveries ?? [], failures }

package/shared/email-delivery-status.ts

@@ -21,3 +21,46 @@ export const normalizeEmailProviderEvent = (value: string): string =>
 
 export const isKnownEmailProviderEvent = (value: string): value is KnownEmailProviderEvent =>
   knownEmailProviderEvents.includes(value as KnownEmailProviderEvent)
+
+type EmailStatusRefreshState = {
+  providerMessageId: string | null
+  providerLastEvent: string | null
+  providerStatusCheckedAt: Date | string | null
+  sentAt: Date | string | null
+  createdAt: Date | string
+}
+
+const MINUTE_MS = 60_000
+const DAY_MS = 24 * 60 * MINUTE_MS
+const completedDeliveryEvents = new Set([
+  'delivered',
+  'opened',
+  'clicked',
+  'bounced',
+  'failed',
+  'suppressed',
+  'complained'
+])
+
+export const shouldRefreshInvoiceEmailStatus = (
+  delivery: EmailStatusRefreshState,
+  forceRefresh = false,
+  now = Date.now()
+): boolean => {
+  if (!delivery.providerMessageId) {
+    return false
+  }
+  // Delivery is resolved; later engagement/complaint events can still be requested manually.
+  if (!forceRefresh && completedDeliveryEvents.has(normalizeEmailProviderEvent(delivery.providerLastEvent || ''))) {
+    return false
+  }
+  const age = now - new Date(delivery.sentAt || delivery.createdAt).getTime()
+  const interval = forceRefresh
+    ? MINUTE_MS
+    : age >= 7 * DAY_MS
+      ? DAY_MS
+      : age >= DAY_MS
+        ? 60 * MINUTE_MS
+        : 5 * MINUTE_MS
+  return !delivery.providerStatusCheckedAt || now - new Date(delivery.providerStatusCheckedAt).getTime() >= interval
+}