@nuxt-customer-portal/invoices 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @nuxt-customer-portal/invoices
 
+## 0.8.0
+
+### Minor Changes
+
+- e558791: Support store-wide online and deferred invoice payment choices with immediate purchase fulfillment, linked unsent invoice drafts, inclusive tax review, and manual payment progress. Add unlisted products with server-generated unguessable slugs, excluded from catalog discovery while remaining available through individual product pages.
+
+### Patch Changes
+
+- Updated dependencies [175854d]
+- Updated dependencies [28bb7af]
+  - @nuxt-customer-portal/core@0.8.0
+  - @nuxt-customer-portal/ui@0.8.0
+  - @nuxt-customer-portal/clients@0.8.0
+  - @nuxt-customer-portal/organizations@0.8.0
+
 ## 0.7.0
 
 ### Patch Changes

package/app/components/InvoicesInvoiceDetail.vue

@@ -38,6 +38,33 @@ const senderLogo = computed(() => {
     ? branding?.markDark || branding?.markLight || ''
     : branding?.markLight || branding?.markDark || ''
 })
+const deferredInvoice = computed(() => 'agreedTotalMinor' in props.invoice && props.invoice.agreedTotalMinor !== null)
+const taxReview = reactive({
+  rates: props.invoice.lines.map((line) => ({ lineId: line.id, rate: line.vatRateBasisPoints / 100 }))
+})
+const taxReviewSchema = z.object({
+  rates: z.array(z.object({ lineId: z.string(), rate: z.number().min(0).max(100).multipleOf(0.01) })).min(1)
+})
+async function reviewTaxes() {
+  busy.value = true
+  try {
+    await $fetch(`/api/invoices/admin/invoices/${encodeURIComponent(props.invoice.id)}/tax-review`, {
+      method: 'POST',
+      body: {
+        rates: taxReview.rates.map((line) => ({ lineId: line.lineId, vatRateBasisPoints: Math.round(line.rate * 100) }))
+      }
+    })
+    await props.refresh()
+  } catch (error) {
+    toast.add({
+      title: t('features.invoices.messages.saveError'),
+      description: (error as { data?: { message?: string } }).data?.message,
+      color: 'error'
+    })
+  } finally {
+    busy.value = false
+  }
+}
 const api = useInvoices()
 const toast = useToast()
 const busy = ref(false)
@@ -154,6 +181,9 @@ const providerStatusColor = (status: string) => {
 const providerStatusLabel = (status: string) =>
   isKnownEmailProviderEvent(status) ? t(`features.invoices.admin.emailProviderStatus.${status}`) : status
 const historyText = (entry: InvoiceHistoryDto) => {
+  if (entry.action === 'TAX_REVIEWED') {
+    return t('features.invoices.reviewTaxes')
+  }
   if (entry.action === 'PAYMENT_REGISTERED') {
     return t('features.invoices.admin.invoiceHistory.payment', { amount: money(entry.amountMinor ?? 0) })
   }
@@ -381,6 +411,20 @@ if (!isClient.value) {
 
 <template>
   <div class="invoice-detail space-y-6">
+    <UCard v-if="!isClient && deferredInvoice && invoice.status === 'DRAFT'" class="mb-4">
+      <UForm :state="taxReview" :schema="taxReviewSchema" novalidate class="space-y-4" @submit="reviewTaxes">
+        <p>{{ t('features.invoices.taxReviewHelp') }}</p>
+        <UFormField
+          v-for="(line, index) in taxReview.rates"
+          :key="line.lineId"
+          :name="`rates.${index}.rate`"
+          :label="invoice.lines[index]?.description"
+        >
+          <UInputNumber v-model="line.rate" :min="0" :max="100" :step="0.01" />
+        </UFormField>
+        <UButton type="submit" :loading="busy">{{ t('features.invoices.reviewTaxes') }}</UButton>
+      </UForm>
+    </UCard>
     <header class="invoice-detail-header">
       <div class="min-w-0">
         <UButton

package/i18n/locales/en.json

@@ -310,7 +310,9 @@
         "saveError": "The change could not be saved",
         "fetchError": "Invoices could not be loaded",
         "senderInvoiceDetailsSaved": "Sender invoice details saved"
-      }
+      },
+      "taxReviewHelp": "Review the tax rate for every line. The agreed purchase total remains unchanged.",
+      "reviewTaxes": "Confirm tax breakdown"
     }
   }
 }

package/i18n/locales/nl.json

@@ -310,7 +310,9 @@
         "saveError": "De wijziging kon niet worden opgeslagen",
         "fetchError": "Facturen konden niet worden geladen",
         "senderInvoiceDetailsSaved": "Factuurgegevens afzender opgeslagen"
-      }
+      },
+      "taxReviewHelp": "Controleer het btw-tarief voor elke regel. Het afgesproken aankoopbedrag blijft gelijk.",
+      "reviewTaxes": "Btw-verdeling bevestigen"
     }
   }
 }

package/migrations/0004_deferred_invoice_review.sql

@@ -0,0 +1,2 @@
+ALTER TABLE invoices.invoice ADD COLUMN agreed_total_minor integer;
+ALTER TABLE invoices.invoice ADD COLUMN tax_review_required boolean NOT NULL DEFAULT false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt-customer-portal/invoices",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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.7.0",
-    "@nuxt-customer-portal/organizations": "^0.7.0",
-    "@nuxt-customer-portal/clients": "^0.7.0",
-    "@nuxt-customer-portal/ui": "^0.7.0"
+    "@nuxt-customer-portal/core": "^0.8.0",
+    "@nuxt-customer-portal/organizations": "^0.8.0",
+    "@nuxt-customer-portal/clients": "^0.8.0",
+    "@nuxt-customer-portal/ui": "^0.8.0"
   },
   "peerDependencies": {
     "nuxt": "^4.5.1",

package/portal.manifest.mjs

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

package/server/api/invoices/admin/invoices/[id]/tax-review.post.ts

@@ -0,0 +1,14 @@
+import { requireFeatureAccess } from '@nuxt-customer-portal/core/server/portal'
+import { invoicesFeature } from '@nuxt-customer-portal/invoices/shared/feature'
+import { invoiceTaxReviewSchema } from '@nuxt-customer-portal/invoices/server/utils/invoice-validation'
+import { reviewDeferredInvoiceTax } from '@nuxt-customer-portal/invoices/server/utils/deferred-invoice'
+
+export default defineEventHandler(async (event) => {
+  const { organizationId, session } = await requireFeatureAccess(event, invoicesFeature.policy, 'manage')
+  return reviewDeferredInvoiceTax(
+    organizationId,
+    session.user.id,
+    getRouterParam(event, 'id')!,
+    invoiceTaxReviewSchema.parse(await readBody(event)).rates
+  )
+})

package/server/db/schema/invoices.ts

@@ -114,6 +114,8 @@ export const invoice = invoicesSchema.table(
     originalInvoiceId: text('original_invoice_id'),
     externalReference: text('external_reference'),
     importMetadata: jsonb('import_metadata').$type<Record<string, unknown>>(),
+    agreedTotalMinor: integer('agreed_total_minor'),
+    taxReviewRequired: boolean('tax_review_required').default(false).notNull(),
     automated: boolean('automated').default(false).notNull(),
     status: invoiceStatus('status').default('DRAFT').notNull(),
     currency: text('currency').notNull(),

package/server/utils/commerce.ts

@@ -6,6 +6,7 @@ import { firstInvoiceNumber, incrementInvoiceNumber } from '../../shared/invoice
 import { getOrganizationInvoiceProfile, requireInvoicesEnabled } from './invoice-repository'
 
 export interface CommerceDocument {
+  deferred?: boolean
   reference: string
   storeId: string
   clientId: string
@@ -77,7 +78,13 @@ export async function createCommerceDocument(tx: PoolClient, input: CommerceDocu
     taxExempt?: string
   } | null
   const notes = [
-    input.locale === 'nl' ? 'Automatisch verwerkt via Stripe.' : 'Automatically reconciled through Stripe.',
+    input.deferred
+      ? input.locale === 'nl'
+        ? 'Factuur volgt. Controleer de btw-verdeling voor verzending.'
+        : 'Invoice to follow. Review the tax breakdown before sending.'
+      : input.locale === 'nl'
+        ? 'Automatisch verwerkt via Stripe.'
+        : 'Automatically reconciled through Stripe.',
     input.paymentReference
   ]
   if (input.originalInvoiceId) {
@@ -111,7 +118,7 @@ export async function createCommerceDocument(tx: PoolClient, input: CommerceDocu
     today = new Date().toISOString().slice(0, 10)
   await tx.query(
     `INSERT INTO invoices.invoice(id,organization_id,client_organization_id,number,status,currency,issue_date,due_date,subject,notes,sender_name,sender_logo,sender_address,sender_country,sender_registration,sender_vat_number,sender_iban,sender_bic,recipient_name,recipient_address,recipient_email,recipient_locale,created_by_id,issued_at,document_type,original_invoice_id,external_reference,automated)
- VALUES($1,$2,$3,$4,'PAID',$5,$6,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,now(),$22,$23,$24,true)`,
+ VALUES($1,$2,$3,$4,$25::invoices.invoice_status,$5,$6,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,CASE WHEN $25::text='DRAFT' THEN NULL ELSE now() END,$22,$23,$24,true)`,
     [
       id,
       input.storeId,
@@ -136,7 +143,8 @@ export async function createCommerceDocument(tx: PoolClient, input: CommerceDocu
       input.actorId,
       input.originalInvoiceId ? 'credit' : 'invoice',
       input.originalInvoiceId || null,
-      input.reference
+      input.reference,
+      input.deferred ? 'DRAFT' : 'PAID'
     ]
   )
   for (const [position, line] of input.lines.entries()) {
@@ -156,19 +164,27 @@ export async function createCommerceDocument(tx: PoolClient, input: CommerceDocu
       ]
     )
   }
-  await tx.query(
-    'INSERT INTO invoices.invoice_payment(id,invoice_id,paid_on,amount_minor,reference,note,created_by_id) VALUES($1,$2,$3,$4,$5,$6,$7)',
-    [
-      randomUUID(),
+  if (!input.deferred) {
+    await tx.query(
+      'INSERT INTO invoices.invoice_payment(id,invoice_id,paid_on,amount_minor,reference,note,created_by_id) VALUES($1,$2,$3,$4,$5,$6,$7)',
+      [
+        randomUUID(),
+        id,
+        today,
+        input.total,
+        input.paymentReference,
+        'Automatically reconciled provider transaction',
+        input.actorId
+      ]
+    )
+  }
+  if (input.deferred) {
+    await tx.query('UPDATE invoices.invoice SET agreed_total_minor=$2,tax_review_required=true WHERE id=$1', [
       id,
-      today,
-      input.total,
-      input.paymentReference,
-      'Automatically reconciled provider transaction',
-      input.actorId
-    ]
-  )
-  for (const action of ['CREATED', 'ISSUED', 'PAYMENT_REGISTERED']) {
+      input.total
+    ])
+  }
+  for (const action of input.deferred ? ['CREATED'] : ['CREATED', 'ISSUED', 'PAYMENT_REGISTERED']) {
     await tx.query(
       'INSERT INTO invoices.invoice_history(id,invoice_id,action,actor_user_id,amount_minor) VALUES($1,$2,$3,$4,$5)',
       [randomUUID(), id, action, input.actorId, input.total]

package/server/utils/deferred-invoice.ts

@@ -0,0 +1,71 @@
+import { randomUUID } from 'node:crypto'
+import { createError } from 'h3'
+import { pool } from '@nuxt-customer-portal/core/server/utils/db'
+import { splitInclusiveTax } from './deferred-tax'
+
+export async function reviewDeferredInvoiceTax(
+  organizationId: string,
+  actorId: string,
+  id: string,
+  rates: Array<{ lineId: string; vatRateBasisPoints: number }>
+) {
+  const tx = await pool.connect()
+  try {
+    await tx.query('BEGIN')
+    const {
+      rows: [invoice]
+    } = await tx.query('SELECT * FROM invoices.invoice WHERE id=$1 AND organization_id=$2 FOR UPDATE', [
+      id,
+      organizationId
+    ])
+    if (!invoice || invoice.status !== 'DRAFT' || invoice.agreed_total_minor === null) {
+      throw createError({ statusCode: 409, message: 'Only deferred invoice drafts can be reviewed' })
+    }
+    const { rows: lines } = await tx.query(
+      'SELECT * FROM invoices.invoice_line WHERE invoice_id=$1 ORDER BY position',
+      [id]
+    )
+    if (
+      rates.length !== lines.length ||
+      new Set(rates.map((rate) => rate.lineId)).size !== lines.length ||
+      lines.some((line) => !rates.some((rate) => rate.lineId === line.id))
+    ) {
+      throw createError({ statusCode: 400, message: 'Review every invoice line exactly once' })
+    }
+    let total = 0
+    for (const line of lines) {
+      const gross =
+        Math.round((line.quantity_milli * line.unit_price_minor) / 1000) +
+        (line.exact_tax_minor ??
+          Math.round((((line.quantity_milli * line.unit_price_minor) / 1000) * line.vat_rate_basis_points) / 10000))
+      const rate = rates.find((rate) => rate.lineId === line.id)!.vatRateBasisPoints
+      const split = splitInclusiveTax(gross, rate)
+      const unitNet = Math.round((split.net * 1000) / line.quantity_milli)
+      if (Math.round((line.quantity_milli * unitNet) / 1000) !== split.net) {
+        throw createError({ statusCode: 409, message: 'Invoice quantity cannot represent the agreed total exactly' })
+      }
+      total += gross
+      await tx.query(
+        'UPDATE invoices.invoice_line SET unit_price_minor=$2,vat_rate_basis_points=$3,exact_tax_minor=$4,tax_details=$5 WHERE id=$1',
+        [line.id, unitNet, rate, split.tax, JSON.stringify({ reviewed: true, inclusiveTotal: gross })]
+      )
+    }
+    if (total !== invoice.agreed_total_minor) {
+      throw createError({ statusCode: 409, message: 'Invoice total must match the agreed purchase total' })
+    }
+    await tx.query('UPDATE invoices.invoice SET tax_review_required=false WHERE id=$1', [id])
+    await tx.query('INSERT INTO invoices.invoice_history(id,invoice_id,action,actor_user_id) VALUES($1,$2,$3,$4)', [
+      randomUUID(),
+      id,
+      'TAX_REVIEWED',
+      actorId
+    ])
+    await tx.query('COMMIT')
+    return { reviewed: true }
+  } catch (error) {
+    await tx.query('ROLLBACK')
+    throw error
+  } finally {
+    tx.release()
+  }
+}

package/server/utils/deferred-tax.ts

@@ -0,0 +1,7 @@
+export function splitInclusiveTax(total: number, rate: number) {
+  if (!Number.isSafeInteger(total) || total < 0 || !Number.isInteger(rate) || rate < 0 || rate > 10000) {
+    throw new Error('Invalid inclusive tax amount or rate')
+  }
+  const net = Math.round((total * 10000) / (10000 + rate))
+  return { net, tax: total - net, total }
+}

package/server/utils/invoice-email.ts

@@ -136,6 +136,16 @@ export const deliverInvoiceEmail = async (
       message: issue ? 'Only draft invoices can be issued' : 'Only issued invoices can be resent'
     })
   }
+  if (
+    issue &&
+    (selected.taxReviewRequired ||
+      (selected.agreedTotalMinor != null && selected.totalMinor !== selected.agreedTotalMinor))
+  ) {
+    throw createError({
+      statusCode: 409,
+      message: 'Review taxes and preserve the agreed purchase total before issuing this invoice'
+    })
+  }
   const preview = await getInvoiceEmailPreview(organizationId, id, input.locale, purpose)
   input = { ...input, locale: preview.locale === 'en' ? 'en' : 'nl' }
   if (!preview.emailProviderConfigured) {

package/server/utils/invoice-validation.ts

@@ -47,6 +47,12 @@ export const invoiceUpdateSchema = z
     path: ['dueDate'],
     message: 'Due date must not precede invoice date'
   })
+export const invoiceTaxReviewSchema = z.object({
+  rates: z
+    .array(z.object({ lineId: id, vatRateBasisPoints: z.number().int().min(0).max(10000) }))
+    .min(1)
+    .max(500)
+})
 export const invoiceIssueSchema = z.object({ action: z.enum(['VOID', 'UNVOID']) })
 export const invoicePaymentSchema = z.object({
   paidOn: isoDate,

package/shared/types/invoice.ts

@@ -50,6 +50,8 @@ export interface InvoiceEmailDeliveryDto {
   sentAt: string | null
 }
 export interface InvoiceDto {
+  agreedTotalMinor: number | null
+  taxReviewRequired: boolean
   id: string
   organizationId: string
   clientOrganizationId: string | null
@@ -122,6 +124,7 @@ export type ClientInvoiceDto = Omit<
   emailDeliveries?: never
 }
 export type InvoiceHistoryAction =
+  | 'TAX_REVIEWED'
   | 'CREATED'
   | 'EDITED'
   | 'ISSUED'