@nuxt-customer-portal/invoices 0.3.0

package/server/utils/invoice-validation.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod'
+import { hasNumericInvoiceSequence } from '@nuxt-customer-portal/invoices/shared/invoice-number'
+
+const id = z.string().trim().min(1).max(200)
+const isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
+const moneyMinor = z.number().int().min(0).max(1_000_000_000)
+const invoiceNumber = z
+  .string()
+  .trim()
+  .min(1)
+  .max(60)
+  .refine(hasNumericInvoiceSequence, 'Invoice number must end with a numeric sequence')
+export const invoiceLineSchema = z.object({
+  description: z.string().trim().min(1).max(500),
+  quantityMilli: z.number().int().positive().max(100_000_000),
+  unit: z.string().trim().min(1).max(30).default('item'),
+  unitPriceMinor: moneyMinor,
+  vatRateBasisPoints: z.number().int().min(0).max(10_000).default(2100)
+})
+export const invoiceCreateSchema = z
+  .object({
+    clientOrganizationId: id,
+    contactId: id.nullable().optional(),
+    number: invoiceNumber,
+    currency: z.string().length(3),
+    issueDate: isoDate,
+    dueDate: isoDate,
+    subject: z.string().trim().max(500).nullable().optional(),
+    notes: z.string().trim().max(5000).nullable().optional(),
+    lines: z.array(invoiceLineSchema).min(1).max(500)
+  })
+  .refine((value) => value.dueDate >= value.issueDate, {
+    path: ['dueDate'],
+    message: 'Due date must not precede invoice date'
+  })
+export type InvoiceCreateInput = z.infer<typeof invoiceCreateSchema>
+export const invoiceUpdateSchema = z
+  .object({
+    number: invoiceNumber,
+    issueDate: isoDate,
+    dueDate: isoDate,
+    subject: z.string().trim().max(500).nullable().optional(),
+    notes: z.string().trim().max(5000).nullable().optional()
+  })
+  .refine((value) => value.dueDate >= value.issueDate, {
+    path: ['dueDate'],
+    message: 'Due date must not precede invoice date'
+  })
+export const invoiceIssueSchema = z.object({ action: z.enum(['VOID', 'UNVOID']) })
+export const invoicePaymentSchema = z.object({
+  paidOn: isoDate,
+  amountMinor: moneyMinor.positive(),
+  reference: z.string().trim().max(200).nullable().optional(),
+  note: z.string().trim().max(1000).nullable().optional()
+})
+export const invoiceEmailDeliverySchema = z
+  .object({
+    to: z.string().trim().toLowerCase().email().max(320),
+    cc: z.array(z.string().trim().toLowerCase().email().max(320)).max(20).default([]),
+    locale: z.enum(['nl', 'en']),
+    subject: z.string().trim().min(1).max(500),
+    body: z.string().trim().min(1).max(10_000)
+  })
+  .transform((value) => ({ ...value, cc: [...new Set(value.cc.filter((email) => email !== value.to))] }))
+export const invoiceSettingsSchema = z.object({
+  enabled: z.boolean(),
+  currency: z.string().trim().toUpperCase().length(3),
+  defaultVatRateBasisPoints: z.number().int().min(0).max(10_000),
+  address: z.string().trim().max(5000),
+  registrationNumber: z.string().trim().max(200).nullable(),
+  vatNumber: z.string().trim().max(200).nullable(),
+  iban: z.string().trim().max(100).nullable(),
+  bic: z.string().trim().max(100).nullable(),
+  invoiceEmail: z.string().trim().email().max(320).nullable(),
+  preferredLocale: z.enum(['nl', 'en'])
+})
+export const billingContactCreateSchema = z.object({
+  userId: id.nullable().optional(),
+  name: z.string().trim().min(1).max(200),
+  email: z.string().trim().toLowerCase().email().max(320),
+  phone: z.string().trim().max(80).nullable().optional(),
+  jobTitle: z.string().trim().max(160).nullable().optional()
+})
+export const billingContactUpdateSchema = billingContactCreateSchema
+  .partial()
+  .refine((value) => Object.keys(value).length > 0, 'At least one field is required')
+const listBase = z.object({
+  search: z.string().trim().max(200).optional(),
+  page: z.coerce.number().int().positive().default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(20),
+  sortDir: z.enum(['asc', 'desc']).default('desc')
+})
+export const invoiceListQuerySchema = listBase.extend({
+  status: z.enum(['DRAFT', 'ISSUED', 'PAID', 'VOID']).optional(),
+  clientOrganizationId: id.optional(),
+  overdue: z
+    .enum(['true', 'false'])
+    .transform((value) => value === 'true')
+    .optional(),
+  sortBy: z.enum(['issueDate', 'dueDate', 'number', 'totalMinor']).default('issueDate')
+})
+export const clientInvoiceListQuerySchema = listBase.extend({
+  status: z.enum(['ISSUED', 'PAID']).optional(),
+  accessId: id.optional(),
+  overdue: z
+    .enum(['true', 'false'])
+    .transform((value) => value === 'true')
+    .optional(),
+  sortBy: z.enum(['issueDate', 'dueDate', 'number', 'totalMinor']).default('issueDate')
+})
+export type InvoiceListQuery = z.infer<typeof invoiceListQuerySchema>
+export type ClientInvoiceListQuery = z.infer<typeof clientInvoiceListQuerySchema>

package/shared/email-delivery-status.ts

@@ -0,0 +1,23 @@
+export const knownEmailProviderEvents = [
+  'sent',
+  'delivered',
+  'delivery_delayed',
+  'bounced',
+  'failed',
+  'suppressed',
+  'complained',
+  'opened',
+  'clicked'
+] as const
+
+export type KnownEmailProviderEvent = (typeof knownEmailProviderEvents)[number]
+
+export const normalizeEmailProviderEvent = (value: string): string =>
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/^email\./, '')
+    .replaceAll('-', '_')
+
+export const isKnownEmailProviderEvent = (value: string): value is KnownEmailProviderEvent =>
+  knownEmailProviderEvents.includes(value as KnownEmailProviderEvent)

package/shared/feature.ts

@@ -0,0 +1,148 @@
+import type { PortalFeatureDefinition } from '@nuxt-customer-portal/core/shared/types/feature'
+
+export const invoiceActions = ['read', 'create', 'update', 'manage'] as const
+export type InvoiceAction = (typeof invoiceActions)[number]
+
+export const invoicesFeature: PortalFeatureDefinition<InvoiceAction> = {
+  id: 'invoices',
+  modules: [
+    {
+      id: 'invoices',
+      labelKey: 'features.invoices.title',
+      icon: 'i-lucide-receipt-text',
+      to: '/invoices',
+      routePrefixes: ['/invoices', '/admin/invoices'],
+      audiences: ['authenticated'],
+      order: 31,
+      menuItems: [
+        {
+          id: 'received-invoices',
+          labelKey: 'features.invoices.receivedInvoices',
+          icon: 'i-lucide-inbox',
+          to: '/invoices',
+          exact: true,
+          audiences: ['authenticated']
+        },
+        {
+          id: 'invoice-viewers',
+          labelKey: 'features.invoices.clientInvoices.viewersTitle',
+          icon: 'i-lucide-users-round',
+          to: '/invoices/viewers',
+          audiences: ['clientAdmin']
+        },
+        {
+          id: 'sales-invoices',
+          labelKey: 'features.invoices.salesInvoices',
+          icon: 'i-lucide-receipt-text',
+          to: '/admin/invoices',
+          exact: true,
+          audiences: ['providerAdmin']
+        },
+        {
+          id: 'invoice-settings',
+          labelKey: 'features.invoices.admin.workspaceSettings',
+          icon: 'i-lucide-settings-2',
+          to: '/admin/invoices/settings',
+          audiences: ['providerAdmin']
+        }
+      ]
+    }
+  ],
+  dashboardWidgets: [
+    { id: 'invoices-sales', component: 'InvoicesDashboardSalesInvoices', area: 'main', size: 'half', order: 15 },
+    { id: 'invoices-received', component: 'InvoicesDashboardReceivedInvoices', area: 'main', size: 'half', order: 40 }
+  ],
+  clientIntegration: {
+    moduleId: 'invoices',
+    labelKey: 'features.invoices.title',
+    detailComponent: 'InvoicesClientSettingsPanel'
+  },
+  emails: [
+    {
+      id: 'invoice',
+      labelKey: 'features.invoices.admin.emailMessages.invoice',
+      defaults: {
+        en: {
+          subject: 'Invoice {{invoice_number}} from {{sender_name}}',
+          body: 'Dear Sir or Madam,<br><br>Please find invoice {{invoice_number}} attached.<br><br>Kind regards,<br>{{sender_name}}'
+        },
+        nl: {
+          subject: 'Factuur {{invoice_number}} van {{sender_name}}',
+          body: 'Geachte heer/mevrouw,<br><br>In de bijlage vindt u factuur {{invoice_number}}.<br><br>Met vriendelijke groet,<br>{{sender_name}}'
+        }
+      },
+      placeholders: [
+        {
+          key: 'invoice_number',
+          labelKey: 'features.invoices.admin.emailPlaceholders.invoiceNumber',
+          example: '2026-001'
+        },
+        {
+          key: 'sender_name',
+          labelKey: 'features.invoices.admin.emailPlaceholders.senderName',
+          example: 'Example Company'
+        },
+        {
+          key: 'recipient_name',
+          labelKey: 'features.invoices.admin.emailPlaceholders.recipientName',
+          example: 'Example Client'
+        },
+        {
+          key: 'due_date',
+          labelKey: 'features.invoices.admin.emailPlaceholders.dueDate',
+          example: '30 September 2026'
+        },
+        {
+          key: 'outstanding_amount',
+          labelKey: 'features.invoices.admin.emailPlaceholders.outstandingAmount',
+          example: '€1,250.00'
+        }
+      ]
+    },
+    {
+      id: 'payment-reminder',
+      labelKey: 'features.invoices.admin.emailMessages.paymentReminder',
+      defaults: {
+        en: {
+          subject: 'Payment reminder for invoice {{invoice_number}} from {{sender_name}}',
+          body: 'Dear Sir or Madam,<br><br>Invoice {{invoice_number}}, due on {{due_date}}, remains outstanding for {{outstanding_amount}}. Please arrange payment.<br><br>Kind regards,<br>{{sender_name}}'
+        },
+        nl: {
+          subject: 'Betalingsherinnering factuur {{invoice_number}} van {{sender_name}}',
+          body: 'Geachte heer/mevrouw,<br><br>Factuur {{invoice_number}}, met vervaldatum {{due_date}}, staat nog open voor {{outstanding_amount}}. Wij verzoeken u vriendelijk te betalen.<br><br>Met vriendelijke groet,<br>{{sender_name}}'
+        }
+      },
+      placeholders: [
+        {
+          key: 'invoice_number',
+          labelKey: 'features.invoices.admin.emailPlaceholders.invoiceNumber',
+          example: '2026-001'
+        },
+        {
+          key: 'sender_name',
+          labelKey: 'features.invoices.admin.emailPlaceholders.senderName',
+          example: 'Example Company'
+        },
+        {
+          key: 'recipient_name',
+          labelKey: 'features.invoices.admin.emailPlaceholders.recipientName',
+          example: 'Example Client'
+        },
+        {
+          key: 'due_date',
+          labelKey: 'features.invoices.admin.emailPlaceholders.dueDate',
+          example: '30 September 2026'
+        },
+        {
+          key: 'outstanding_amount',
+          labelKey: 'features.invoices.admin.emailPlaceholders.outstandingAmount',
+          example: '€1,250.00'
+        }
+      ]
+    }
+  ],
+  policy: {
+    PROVIDER: { owner: invoiceActions, admin: invoiceActions, member: [] },
+    CLIENT: { owner: ['read', 'manage'], admin: ['read', 'manage'], member: ['read'] }
+  }
+}

package/shared/invoice-introduction.ts

@@ -0,0 +1,21 @@
+export const createHoursIntroduction = (entries: Array<{ person: string; date: string }>, locale: 'nl' | 'en') => {
+  if (!entries.length) {
+    return ''
+  }
+  const names = [...new Set(entries.map((entry) => entry.person))].sort()
+  const people = new Intl.ListFormat(locale, { style: 'long', type: 'conjunction' }).format(names)
+  const dates = entries.map((entry) => entry.date).sort()
+  const format = (date: string) =>
+    new Intl.DateTimeFormat(locale, {
+      day: 'numeric',
+      month: 'long',
+      year: 'numeric',
+      timeZone: 'UTC'
+    }).format(new Date(`${date}T12:00:00Z`))
+  const start = dates[0]!
+  const end = dates[dates.length - 1]!
+  const period = start === end ? format(start) : `${format(start)} ${locale === 'nl' ? 't/m' : 'to'} ${format(end)}`
+  return locale === 'nl'
+    ? `Hierbij factureren wij de uren van ${people} over de periode ${period}.`
+    : `We hereby invoice the hours worked by ${people} for the period ${period}.`
+}

package/shared/invoice-number.ts

@@ -0,0 +1,24 @@
+const trailingSequence = /\d+$/
+
+export const hasNumericInvoiceSequence = (number: string) => trailingSequence.test(number)
+
+export const incrementInvoiceNumber = (number: string): string => {
+  const match = number.match(trailingSequence)
+  if (!match || match.index === undefined) {
+    throw new Error('Invoice number must end with a numeric sequence')
+  }
+  const digits = match[0].split('')
+  let carry = 1
+  for (let index = digits.length - 1; index >= 0 && carry; index -= 1) {
+    const next = Number(digits[index]) + carry
+    digits[index] = String(next % 10)
+    carry = next > 9 ? 1 : 0
+  }
+  if (carry) {
+    digits.unshift('1')
+  }
+  const next = digits.join('').padStart(match[0].length, '0')
+  return `${number.slice(0, match.index)}${next}`
+}
+
+export const firstInvoiceNumber = (year = new Date().getFullYear()): string => `${year}.0001`

package/shared/types/invoice.ts

@@ -0,0 +1,251 @@
+export type InvoiceStatus = 'DRAFT' | 'ISSUED' | 'PAID' | 'VOID'
+export interface InvoiceLineDto {
+  id: string
+  description: string
+  quantityMilli: number
+  unit: string
+  unitPriceMinor: number
+  vatRateBasisPoints: number
+  amountMinor: number
+}
+export interface InvoicePaymentDto {
+  id: string
+  paidOn: string
+  amountMinor: number
+  reference: string | null
+  note: string | null
+}
+export interface InvoiceHistoryDto {
+  id: string
+  action: string
+  actorName: string
+  amountMinor: number | null
+  attachmentName: string | null
+  createdAt: string
+}
+export interface InvoiceAttachmentDto {
+  id: string
+  fileName: string
+  contentType: string
+  size: number
+  uploadedByName: string
+  createdAt: string
+}
+export interface InvoiceEmailDeliveryDto {
+  id: string
+  purpose: 'INVOICE' | 'REMINDER'
+  status: 'PENDING' | 'SENT' | 'FAILED'
+  recipientEmail: string
+  ccEmails: string[]
+  locale: string
+  subject: string
+  actorName: string
+  providerMessageId: string | null
+  providerLastEvent: string | null
+  providerStatusCheckedAt: string | null
+  errorMessage: string | null
+  createdAt: string
+  sentAt: string | null
+}
+export interface InvoiceDto {
+  id: string
+  organizationId: string
+  clientOrganizationId: string | null
+  number: string
+  status: InvoiceStatus
+  currency: string
+  issueDate: string
+  dueDate: string
+  subject: string | null
+  notes: string | null
+  senderName: string
+  senderLogo: string | null
+  senderAddress: string
+  senderRegistration: string | null
+  senderVatNumber: string | null
+  senderIban: string | null
+  senderBic: string | null
+  recipientName: string
+  recipientAddress: string
+  recipientContactName: string | null
+  recipientEmail: string | null
+  recipientLocale: string
+  issuedAt: string | null
+  createdAt: string
+  updatedAt: string
+  lines: InvoiceLineDto[]
+  payments: InvoicePaymentDto[]
+  history: InvoiceHistoryDto[]
+  attachments: InvoiceAttachmentDto[]
+  emailDeliveries: InvoiceEmailDeliveryDto[]
+  subtotalMinor: number
+  vatMinor: number
+  totalMinor: number
+  paidMinor: number
+  outstandingMinor: number
+  isOverdue: boolean
+  daysOverdue: number
+  reminderCount: number
+  lastReminderSentAt: string | null
+}
+export type ClientInvoiceSummaryDto = Pick<
+  InvoiceDto,
+  | 'id'
+  | 'number'
+  | 'status'
+  | 'currency'
+  | 'issueDate'
+  | 'dueDate'
+  | 'subject'
+  | 'totalMinor'
+  | 'outstandingMinor'
+  | 'isOverdue'
+  | 'daysOverdue'
+> & { supplierName: string; accessId: string }
+export type ClientInvoiceDto = Omit<
+  InvoiceDto,
+  'payments' | 'reminderCount' | 'lastReminderSentAt' | 'history' | 'emailDeliveries'
+> & {
+  supplierName: string
+  accessId: string
+  payments?: never
+  reminderCount?: never
+  lastReminderSentAt?: never
+  history?: never
+  emailDeliveries?: never
+}
+export type InvoiceHistoryAction =
+  | 'CREATED'
+  | 'EDITED'
+  | 'ISSUED'
+  | 'VOIDED'
+  | 'UNVOIDED'
+  | 'PAYMENT_REGISTERED'
+  | 'ATTACHMENT_ADDED'
+  | 'ATTACHMENT_REMOVED'
+  | 'EMAIL_SENT'
+  | 'REMINDER_SENT'
+export type InvoiceEmailPurpose = 'INVOICE' | 'REMINDER'
+export interface OrganizationInvoiceProfileDto extends InvoiceSettingsDto {
+  name: string
+  logo: string | null
+}
+export interface InvoiceSettingsDto {
+  organizationId: string
+  enabled: boolean
+  currency: string
+  defaultVatRateBasisPoints: number
+  address: string
+  registrationNumber: string | null
+  vatNumber: string | null
+  iban: string | null
+  bic: string | null
+  invoiceEmail: string | null
+  preferredLocale: 'nl' | 'en'
+}
+export interface InvoiceCapabilitiesDto {
+  canConfigureInvoices: boolean
+  canManageInvoices: boolean
+  canViewReceivedInvoices: boolean
+  canManageViewers: boolean
+  invoicesEnabled: boolean
+}
+export interface ClientInvoiceSupplierDto {
+  id: string
+  providerOrganizationId: string
+  providerName: string
+  canViewInvoices: boolean
+}
+export interface ClientInvoiceViewerDto {
+  id: string
+  name: string
+  email: string
+  role: string
+  assigned: boolean
+  fixedAccess: boolean
+}
+export interface InvoiceEmailPreviewDto {
+  to: string
+  cc: string[]
+  locale: string
+  subject: string
+  body: string
+  senderEmail: string
+  senderDomain: string
+  emailProviderConfigured: boolean
+  senderDomainVerified: boolean
+  attachments: Array<{ fileName: string; size: number }>
+  totalAttachmentSize: number
+  maximumAttachmentSize: number
+}
+export interface InvoiceEmailStatusRefreshDto {
+  deliveries: InvoiceEmailDeliveryDto[]
+  failures: Array<{ deliveryId: string; code: 'PROVIDER_NOT_CONFIGURED' | 'PROVIDER_LOOKUP_FAILED' }>
+}
+export interface InvoiceContactDto {
+  id: string
+  name: string
+  email: string
+  phone: string | null
+  jobTitle: string | null
+}
+export interface InvoiceClientDto {
+  id: string
+  organizationId: string
+  name: string
+  officialName: string
+  address: string
+  registrationNumber: string | null
+  vatNumber: string | null
+  invoiceEmail: string | null
+  preferredLocale: 'nl' | 'en'
+  contacts: InvoiceContactDto[]
+}
+export interface InvoiceSourceEntryDto {
+  entryId: string
+  date: string
+  client: string
+  clientOrganizationId: string
+  project: string
+  projectId: string
+  person: string
+  activity: string
+  minutes: number
+  hourlyRateMinor: number
+  amountMinor: number
+  currency: string
+  note: string | null
+}
+export type InvoiceableEntryDto = InvoiceSourceEntryDto
+export interface InvoicesListPagination {
+  total: number
+  page: number
+  pageSize: number
+  pageCount: number
+}
+export interface InvoicesListResponse<T> {
+  items: T[]
+  pagination: InvoicesListPagination
+}
+export interface InvoiceSourceProvider {
+  id: string
+  labelKey: string
+  descriptionKey: string
+  load: (query: { from: string; to: string }) => Promise<{ enabled: boolean; entries: InvoiceSourceEntryDto[] }>
+  create: (input: Record<string, unknown>) => Promise<{ id: string }>
+}
+export interface InvoiceClientAccessOverviewDto {
+  configured: boolean
+  enabled: boolean
+  moduleEnabled: boolean
+  members: {
+    id: string
+    name: string
+    email: string
+    image: string | null
+    role: string
+    fixedAccess: boolean
+    assigned: boolean
+    canView: boolean
+  }[]
+}

package/tokens.css

@@ -0,0 +1,25 @@
+:root {
+  --invoices-color-running: var(--color-success-600);
+  --invoices-color-running-soft: var(--color-success-50);
+  --invoices-color-weekend: var(--color-neutral-50);
+  --invoices-rule: var(--ui-border);
+  --invoices-radius: var(--ui-radius);
+  --invoices-space-cell: 0.75rem;
+  --invoices-duration-fast: 120ms;
+  --invoices-ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.dark {
+  --invoices-color-running: var(--color-success-400);
+  --invoices-color-running-soft: var(--color-neutral-800);
+  --invoices-color-weekend: var(--color-neutral-900);
+}
+
+html[data-portal-theme='brutal'] {
+  --invoices-color-weekend: var(--color-paper-2);
+}
+
+html.dark[data-portal-theme='brutal'] {
+  --invoices-color-running-soft: var(--color-paper-2);
+  --invoices-color-weekend: var(--color-paper-2);
+}