@nuxt-customer-portal/invoices 0.3.0

package/server/api/invoices/client/[accessId]/viewers.put.ts

@@ -0,0 +1,17 @@
+import { requireActiveOrganizationRole } from '@nuxt-customer-portal/core/server/portal'
+import { setClientInvoiceViewer } from '@nuxt-customer-portal/invoices/server/utils/invoice-repository'
+
+export default defineEventHandler(async (event) => {
+  const { session, organizationId, role } = await requireActiveOrganizationRole(event)
+  if (!['owner', 'admin'].includes(role)) {
+    throw createError({ statusCode: 403, message: 'Client administrator access required' })
+  }
+  const body = await readBody<{ userId: string; assigned: boolean }>(event)
+  return setClientInvoiceViewer(
+    getRouterParam(event, 'accessId')!,
+    organizationId,
+    session.user.id,
+    body.userId,
+    body.assigned
+  )
+})

package/server/api/invoices/client/invoices/[id]/attachments/[attachmentId].get.ts

@@ -0,0 +1,20 @@
+import { requireActiveOrganizationRole } from '@nuxt-customer-portal/core/server/portal'
+import { getClientInvoiceAttachment } from '@nuxt-customer-portal/invoices/server/utils/invoice-repository'
+
+export default defineEventHandler(async (event) => {
+  const { session, organizationId, role } = await requireActiveOrganizationRole(event)
+  const attachment = await getClientInvoiceAttachment(
+    organizationId,
+    session.user.id,
+    role === 'owner' || role === 'admin' || session.user.role === 'admin',
+    getRouterParam(event, 'id')!,
+    getRouterParam(event, 'attachmentId')!
+  )
+  setResponseHeaders(event, {
+    'Content-Type': attachment.contentType,
+    'Content-Length': attachment.size,
+    'Content-Disposition': `attachment; filename*=UTF-8''${encodeURIComponent(attachment.fileName)}`,
+    'Cache-Control': 'private, no-store'
+  })
+  return Buffer.from(attachment.contentBase64, 'base64')
+})

package/server/api/invoices/client/invoices/[id]/index.get.ts

@@ -0,0 +1,12 @@
+import { requireActiveOrganizationRole } from '@nuxt-customer-portal/core/server/portal'
+import { getClientInvoice } from '@nuxt-customer-portal/invoices/server/utils/invoice-repository'
+
+export default defineEventHandler(async (event) => {
+  const { session, organizationId, role } = await requireActiveOrganizationRole(event)
+  return getClientInvoice(
+    organizationId,
+    session.user.id,
+    role === 'owner' || role === 'admin' || session.user.role === 'admin',
+    getRouterParam(event, 'id')!
+  )
+})

package/server/api/invoices/client/invoices/[id]/pdf.get.ts

@@ -0,0 +1,23 @@
+import { requireActiveOrganizationRole } from '@nuxt-customer-portal/core/server/portal'
+import { generateInvoicePdf } from '@nuxt-customer-portal/invoices/server/utils/invoice-pdf'
+import { getClientInvoice } from '@nuxt-customer-portal/invoices/server/utils/invoice-repository'
+
+export default defineEventHandler(async (event) => {
+  const { session, organizationId, role } = await requireActiveOrganizationRole(event)
+  const selected = await getClientInvoice(
+    organizationId,
+    session.user.id,
+    role === 'owner' || role === 'admin' || session.user.role === 'admin',
+    getRouterParam(event, 'id')!
+  )
+  const query = getQuery(event)
+  const pdf = await generateInvoicePdf(selected, typeof query.locale === 'string' ? query.locale : undefined)
+  const disposition = query.download === '1' ? 'attachment' : 'inline'
+  const fileName = `invoice-${selected.number.replace(/[^a-z0-9._-]+/gi, '-')}.pdf`
+  setResponseHeaders(event, {
+    'Content-Type': 'application/pdf',
+    'Content-Disposition': `${disposition}; filename="${fileName}"`,
+    'Cache-Control': 'private, no-store'
+  })
+  return Buffer.from(pdf)
+})

package/server/api/invoices/client/invoices/index.get.ts

@@ -0,0 +1,14 @@
+import { requireActiveOrganizationRole } from '@nuxt-customer-portal/core/server/portal'
+import { clientInvoiceListQuerySchema } from '@nuxt-customer-portal/invoices/server/utils/invoice-validation'
+import { listClientInvoicesPage } from '@nuxt-customer-portal/invoices/server/utils/invoice-listing'
+
+export default defineEventHandler(async (event) => {
+  const { session, organizationId, role } = await requireActiveOrganizationRole(event)
+  const isAdmin = role === 'owner' || role === 'admin' || session.user.role === 'admin'
+  return listClientInvoicesPage(
+    organizationId,
+    session.user.id,
+    isAdmin,
+    clientInvoiceListQuerySchema.parse(getQuery(event))
+  )
+})

package/server/api/invoices/client/suppliers.get.ts

@@ -0,0 +1,8 @@
+import { requireActiveOrganizationRole } from '@nuxt-customer-portal/core/server/portal'
+import { listClientInvoiceSuppliers } from '@nuxt-customer-portal/invoices/server/utils/invoice-repository'
+
+export default defineEventHandler(async (event) => {
+  const { session, organizationId, role } = await requireActiveOrganizationRole(event)
+  const isAdmin = role === 'owner' || role === 'admin' || session.user.role === 'admin'
+  return listClientInvoiceSuppliers(organizationId, session.user.id, isAdmin)
+})

package/server/db/schema/invoices.ts

@@ -0,0 +1,251 @@
+import { boolean, date, index, integer, pgSchema, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core'
+import { sql } from 'drizzle-orm'
+import { organization, user } from '@nuxt-customer-portal/core/schema'
+
+export const invoicesSchema = pgSchema('invoices')
+export const invoiceStatus = invoicesSchema.enum('invoice_status', ['DRAFT', 'ISSUED', 'PAID', 'VOID'])
+export const invoiceEmailDeliveryStatus = invoicesSchema.enum('invoice_email_delivery_status', [
+  'PENDING',
+  'SENT',
+  'FAILED'
+])
+export const invoiceEmailPurpose = invoicesSchema.enum('invoice_email_purpose', ['INVOICE', 'REMINDER'])
+const audit = {
+  createdAt: timestamp('created_at', { mode: 'date' }).defaultNow().notNull(),
+  updatedAt: timestamp('updated_at', { mode: 'date' })
+    .defaultNow()
+    .$onUpdate(() => new Date())
+    .notNull()
+}
+
+export const invoiceSettings = invoicesSchema.table('settings', {
+  organizationId: text('organization_id')
+    .primaryKey()
+    .references(() => organization.id, { onDelete: 'cascade' }),
+  enabled: boolean('enabled').default(false).notNull(),
+  currency: text('currency').default('EUR').notNull(),
+  defaultVatRateBasisPoints: integer('default_vat_rate_basis_points').default(2100).notNull(),
+  address: text('address').default('').notNull(),
+  registrationNumber: text('registration_number'),
+  vatNumber: text('vat_number'),
+  iban: text('iban'),
+  bic: text('bic'),
+  invoiceEmail: text('invoice_email'),
+  // Retained for one compatibility release. The portal-wide email template is now used instead.
+  invoiceEmailTemplate: text('invoice_email_template'),
+  preferredLocale: text('preferred_locale').default('nl').notNull(),
+  ...audit
+})
+
+export const billingContact = invoicesSchema.table(
+  'billing_contact',
+  {
+    id: text('id').primaryKey(),
+    organizationId: text('organization_id')
+      .notNull()
+      .references(() => organization.id, { onDelete: 'cascade' }),
+    userId: text('user_id').references(() => user.id, { onDelete: 'set null' }),
+    name: text('name').notNull(),
+    email: text('email').notNull(),
+    phone: text('phone'),
+    jobTitle: text('job_title'),
+    ...audit
+  },
+  (table) => [
+    uniqueIndex('billing_contact_org_email_uidx').on(table.organizationId, table.email),
+    index('billing_contact_org_idx').on(table.organizationId)
+  ]
+)
+
+export const invoiceClientAccess = invoicesSchema.table(
+  'client_access',
+  {
+    id: text('id').primaryKey(),
+    providerOrganizationId: text('provider_organization_id')
+      .notNull()
+      .references(() => organization.id, { onDelete: 'cascade' }),
+    clientOrganizationId: text('client_organization_id')
+      .notNull()
+      .references(() => organization.id, { onDelete: 'restrict' }),
+    enabled: boolean('enabled').default(true).notNull(),
+    ...audit
+  },
+  (table) => [
+    uniqueIndex('invoice_client_access_provider_client_uidx').on(
+      table.providerOrganizationId,
+      table.clientOrganizationId
+    ),
+    index('invoice_client_access_client_idx').on(table.clientOrganizationId)
+  ]
+)
+
+export const invoiceClientViewer = invoicesSchema.table(
+  'client_viewer',
+  {
+    id: text('id').primaryKey(),
+    accessId: text('access_id')
+      .notNull()
+      .references(() => invoiceClientAccess.id, { onDelete: 'cascade' }),
+    userId: text('user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'cascade' }),
+    createdById: text('created_by_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'restrict' }),
+    createdAt: timestamp('created_at', { mode: 'date' }).defaultNow().notNull()
+  },
+  (table) => [
+    uniqueIndex('invoice_client_viewer_access_user_uidx').on(table.accessId, table.userId),
+    index('invoice_client_viewer_user_idx').on(table.userId)
+  ]
+)
+
+export const invoice = invoicesSchema.table(
+  'invoice',
+  {
+    id: text('id').primaryKey(),
+    organizationId: text('organization_id')
+      .notNull()
+      .references(() => organization.id, { onDelete: 'cascade' }),
+    clientOrganizationId: text('client_organization_id').references(() => organization.id, { onDelete: 'restrict' }),
+    number: text('number').notNull(),
+    status: invoiceStatus('status').default('DRAFT').notNull(),
+    currency: text('currency').notNull(),
+    issueDate: date('issue_date', { mode: 'string' }).notNull(),
+    dueDate: date('due_date', { mode: 'string' }).notNull(),
+    subject: text('subject'),
+    notes: text('notes'),
+    senderName: text('sender_name').notNull(),
+    senderLogo: text('sender_logo'),
+    senderAddress: text('sender_address').notNull(),
+    senderRegistration: text('sender_registration'),
+    senderVatNumber: text('sender_vat_number'),
+    senderIban: text('sender_iban'),
+    senderBic: text('sender_bic'),
+    recipientName: text('recipient_name').notNull(),
+    recipientAddress: text('recipient_address').notNull(),
+    recipientContactName: text('recipient_contact_name'),
+    recipientEmail: text('recipient_email'),
+    recipientLocale: text('recipient_locale').default('nl').notNull(),
+    createdById: text('created_by_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'restrict' }),
+    issuedAt: timestamp('issued_at', { mode: 'date' }),
+    ...audit
+  },
+  (table) => [
+    uniqueIndex('invoice_org_number_uidx').on(table.organizationId, table.number),
+    index('invoice_org_status_idx').on(table.organizationId, table.status),
+    index('invoice_client_idx').on(table.clientOrganizationId)
+  ]
+)
+
+export const invoiceLine = invoicesSchema.table(
+  'invoice_line',
+  {
+    id: text('id').primaryKey(),
+    invoiceId: text('invoice_id')
+      .notNull()
+      .references(() => invoice.id, { onDelete: 'cascade' }),
+    position: integer('position').notNull(),
+    description: text('description').notNull(),
+    quantityMilli: integer('quantity_milli').notNull(),
+    unit: text('unit').default('item').notNull(),
+    unitPriceMinor: integer('unit_price_minor').notNull(),
+    vatRateBasisPoints: integer('vat_rate_basis_points').default(2100).notNull()
+  },
+  (table) => [index('invoice_line_invoice_idx').on(table.invoiceId)]
+)
+
+export const invoicePayment = invoicesSchema.table(
+  'invoice_payment',
+  {
+    id: text('id').primaryKey(),
+    invoiceId: text('invoice_id')
+      .notNull()
+      .references(() => invoice.id, { onDelete: 'cascade' }),
+    paidOn: date('paid_on', { mode: 'string' }).notNull(),
+    amountMinor: integer('amount_minor').notNull(),
+    reference: text('reference'),
+    note: text('note'),
+    createdById: text('created_by_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'restrict' }),
+    createdAt: timestamp('created_at', { mode: 'date' }).defaultNow().notNull()
+  },
+  (table) => [index('invoice_payment_invoice_idx').on(table.invoiceId)]
+)
+
+export const invoiceHistory = invoicesSchema.table(
+  'invoice_history',
+  {
+    id: text('id').primaryKey(),
+    invoiceId: text('invoice_id')
+      .notNull()
+      .references(() => invoice.id, { onDelete: 'cascade' }),
+    action: text('action').notNull(),
+    actorUserId: text('actor_user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'restrict' }),
+    amountMinor: integer('amount_minor'),
+    attachmentName: text('attachment_name'),
+    createdAt: timestamp('created_at', { mode: 'date' }).defaultNow().notNull()
+  },
+  (table) => [index('invoice_history_invoice_idx').on(table.invoiceId)]
+)
+
+export const invoiceAttachment = invoicesSchema.table(
+  'invoice_attachment',
+  {
+    id: text('id').primaryKey(),
+    invoiceId: text('invoice_id')
+      .notNull()
+      .references(() => invoice.id, { onDelete: 'cascade' }),
+    fileName: text('file_name').notNull(),
+    contentType: text('content_type').notNull(),
+    size: integer('size').notNull(),
+    contentBase64: text('content_base64').notNull(),
+    uploadedById: text('uploaded_by_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'restrict' }),
+    createdAt: timestamp('created_at', { mode: 'date' }).defaultNow().notNull()
+  },
+  (table) => [index('invoice_attachment_invoice_idx').on(table.invoiceId)]
+)
+
+export const invoiceEmailDelivery = invoicesSchema.table(
+  'invoice_email_delivery',
+  {
+    id: text('id').primaryKey(),
+    invoiceId: text('invoice_id')
+      .notNull()
+      .references(() => invoice.id, { onDelete: 'cascade' }),
+    status: invoiceEmailDeliveryStatus('status').default('PENDING').notNull(),
+    purpose: invoiceEmailPurpose('purpose').default('INVOICE').notNull(),
+    recipientEmail: text('recipient_email').notNull(),
+    ccEmails: text('cc_emails').default('[]').notNull(),
+    locale: text('locale').notNull(),
+    subject: text('subject').notNull(),
+    body: text('body').notNull(),
+    actorUserId: text('actor_user_id')
+      .notNull()
+      .references(() => user.id, { onDelete: 'restrict' }),
+    providerMessageId: text('provider_message_id'),
+    providerLastEvent: text('provider_last_event'),
+    providerStatusCheckedAt: timestamp('provider_status_checked_at', { mode: 'date' }),
+    errorMessage: text('error_message'),
+    payloadHash: text('payload_hash').notNull(),
+    createdAt: timestamp('created_at', { mode: 'date' }).defaultNow().notNull(),
+    updatedAt: timestamp('updated_at', { mode: 'date' })
+      .defaultNow()
+      .$onUpdate(() => new Date())
+      .notNull(),
+    sentAt: timestamp('sent_at', { mode: 'date' })
+  },
+  (table) => [
+    index('invoice_email_delivery_invoice_idx').on(table.invoiceId, table.createdAt),
+    uniqueIndex('invoice_email_delivery_pending_invoice_uidx')
+      .on(table.invoiceId)
+      .where(sql`${table.status} = 'PENDING'`)
+  ]
+)

package/server/plugins/openapi-contracts.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod'
+import { registerPortalOpenApiContracts } from '@nuxt-customer-portal/core/server/utils/openapi-contracts'
+import {
+  billingContactCreateSchema,
+  billingContactUpdateSchema,
+  invoiceCreateSchema,
+  invoiceEmailDeliverySchema,
+  invoiceIssueSchema,
+  invoiceListQuerySchema,
+  invoicePaymentSchema,
+  invoiceSettingsSchema,
+  invoiceUpdateSchema
+} from '../utils/invoice-validation'
+
+const refresh = z.object({ refresh: z.enum(['1']).optional() })
+const locale = z.object({ locale: z.enum(['nl', 'en']).optional() })
+
+export default defineNitroPlugin(() =>
+  registerPortalOpenApiContracts({
+    owner: 'invoices',
+    query: {
+      invoicesAdminInvoicesGet: invoiceListQuerySchema,
+      invoicesAdminEmailDomainGet: refresh,
+      invoicesAdminInvoicesByIdEmailStatusPost: refresh,
+      invoicesAdminInvoicesByIdEmailPreviewGet: locale,
+      invoicesAdminInvoicesByIdReminderPreviewGet: locale,
+      invoicesAdminInvoicesByIdPdfGet: locale
+    },
+    body: {
+      invoicesAdminSettingsPut: invoiceSettingsSchema,
+      invoicesAdminInvoicesPost: invoiceCreateSchema,
+      invoicesAdminInvoicesByIdPatch: z.union([invoiceUpdateSchema, invoiceIssueSchema]),
+      invoicesAdminInvoicesByIdPaymentsPost: invoicePaymentSchema,
+      invoicesAdminInvoicesByIdIssuePost: invoiceEmailDeliverySchema,
+      invoicesAdminInvoicesByIdEmailPost: invoiceEmailDeliverySchema,
+      invoicesAdminInvoicesByIdReminderPost: invoiceEmailDeliverySchema,
+      invoicesAdminClientsByClientIdContactsPost: billingContactCreateSchema,
+      invoicesAdminClientsByClientIdContactsByIdPatch: billingContactUpdateSchema
+    },
+    requestBody: {
+      invoicesAdminInvoicesByIdAttachmentsPost: {
+        required: true,
+        content: {
+          'multipart/form-data': {
+            schema: {
+              type: 'object',
+              required: ['file'],
+              properties: { file: { type: 'string', format: 'binary', description: 'Invoice attachment file.' } }
+            }
+          }
+        }
+      }
+    }
+  })
+)

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

@@ -0,0 +1,64 @@
+import { and, eq, isNotNull } 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 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,
+  forceRefresh = false
+): Promise<InvoiceEmailStatusRefreshDto> => {
+  await getInvoice(organizationId, invoiceId)
+  const deliveries = await db
+    .select({ delivery: invoiceEmailDelivery })
+    .from(invoiceEmailDelivery)
+    .innerJoin(invoice, eq(invoice.id, invoiceEmailDelivery.invoiceId))
+    .where(
+      and(
+        eq(invoice.organizationId, organizationId),
+        eq(invoiceEmailDelivery.invoiceId, invoiceId),
+        isNotNull(invoiceEmailDelivery.providerMessageId)
+      )
+    )
+  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'
+        })
+      }
+    })
+  )
+
+  const refreshed = await getInvoice(organizationId, invoiceId)
+  return { deliveries: refreshed.emailDeliveries ?? [], failures }
+}