Invoice Payment Workflow

type InvoiceStatus = 
  | "draft"      // Being prepared
  | "scheduled"  // Scheduled for future send
  | "unpaid"     // Sent, awaiting payment
  | "paid"       // Payment received
  | "overdue"    // Past due date
  | "canceled";  // Cancelled

interface PaymentTerms {
  name: string;
  netDays: number;
  discountPercent?: number;
  discountDays?: number; // If paid within X days
}

// Example: 2/10 Net 30
const terms: PaymentTerms = {
  name: "2/10 Net 30",
  netDays: 30,
  discountPercent: 2,
  discountDays: 10
};

interface ReminderConfig {
  dueSoonDays: number;
  firstOverdueDays: number;
  secondOverdueDays: number;
  finalNoticeDays: number;
  escalationDays: number;
  
  // Channels
  emailEnabled: boolean;
  smsEnabled: boolean;
  
  // Content
  templates: {
    dueSoon: string;
    dueToday: string;
    overdue: string;
    final: string;
  };
}

interface TransactionMatch {
  transactionId: string;
  invoiceId: string;
  matchType: "exact" | "partial" | "manual";
  confidence: number; // 0-100
  matchCriteria: {
    amountMatch: boolean;
    referenceMatch: boolean;
    customerMatch: boolean;
    dateMatch: boolean;
  };
}

async function autoMatchTransaction(transaction: BankTransaction): Promise<TransactionMatch | null> {
  // 1. Check exact amount match
  const exactMatches = await findInvoicesByAmount(transaction.amount);
  
  // 2. Check reference number
  const refMatches = await findInvoicesByReference(transaction.reference);
  
  // 3. Check customer name in description
  const customerMatches = await findInvoicesByCustomerName(transaction.description);
  
  // 4. Score and select best match
  const bestMatch = scoreMatches([...exactMatches, ...refMatches, ...customerMatches]);
  
  return bestMatch.confidence > 80 ? bestMatch : null;
}

interface PartialPayment {
  invoiceId: string;
  totalAmount: number;
  paidAmount: number;
  remainingAmount: number;
  payments: Array<{
    transactionId: string;
    amount: number;
    date: string;
  }>;
}

// Invoice status for partial payments
function getInvoiceStatus(invoice: Invoice, payments: Payment[]): InvoiceStatus {
  const totalPaid = payments.reduce((sum, p) => sum + p.amount, 0);
  
  if (totalPaid >= invoice.total) return "paid";
  if (totalPaid > 0) return "unpaid"; // Partially paid still shows as unpaid
  if (new Date() > new Date(invoice.dueDate)) return "overdue";
  return "unpaid";
}

async function createInvoiceFromJob(jobId: string, options: {
  dueDate?: string;
  paymentTerms?: string;
  discount?: number;
  notes?: string;
}): Promise<Invoice> {
  const job = await getJob(jobId);
  
  // Gather line items
  const lineItems = await getJobLineItems(jobId);
  const timeEntries = await getJobTimeEntries(jobId);
  const materials = await getJobMaterials(jobId);
  
  const invoice = await db.insert(invoices).values({
    teamId: job.teamId,
    customerId: job.customerId,
    invoiceNumber: generateInvoiceNumber(),
    sourceJobId: jobId,
    
    // Copy job details
    customerName: job.customerName,
    customerEmail: job.customerEmail,
    
    // Calculate totals
    subtotal: calculateSubtotal(lineItems, timeEntries, materials),
    tax: calculateTax(subtotal),
    discount: options.discount || 0,
    total: subtotal + tax - discount,
    
    // Payment terms
    dueDate: options.dueDate || calculateDueDate(options.paymentTerms),
    paymentTerms: options.paymentTerms || "net_30",
    
    status: "draft",
    notes: options.notes
  }).returning();
  
  // Update job status
  await db.update(workbooksJobs)
    .set({ status: "invoiced", invoiceId: invoice.id })
    .where(eq(workbooksJobs.id, jobId));
  
  return invoice;
}

const validTransitions: Record<InvoiceStatus, InvoiceStatus[]> = {
  draft: ["scheduled", "unpaid", "canceled"],
  scheduled: ["unpaid", "canceled"],
  unpaid: ["paid", "overdue", "canceled"],
  overdue: ["paid", "canceled"],
  paid: [],      // Terminal
  canceled: []   // Terminal
};

// Create invoice
invoices.create({
  customerId: string,
  lineItems: LineItem[],
  dueDate: string,
  paymentTerms: string
})

// Create from job
invoices.createFromJob({
  jobId: string,
  dueDate?: string,
  paymentTerms?: string
})

// Send invoice
invoices.send({
  id: string,
  method: "email" | "sms",
  scheduledDate?: string
})

// Record payment
invoices.recordPayment({
  id: string,
  amount: number,
  method: "bank" | "card" | "cash" | "check",
  transactionId?: string
})

// Get payment history
invoices.getPaymentHistory({ id: string })

const invoiceEmailTemplate = {
  subject: "Invoice {{invoiceNumber}} from {{companyName}}",
  body: `
    Dear {{customerName}},
    
    Please find attached invoice {{invoiceNumber}} for {{total}}.
    
    Due Date: {{dueDate}}
    Payment Terms: {{paymentTerms}}
    
    Pay online: {{paymentLink}}
    
    Thank you for your business.
  `
};

const reminderTemplate = {
  subject: "Payment Reminder: Invoice {{invoiceNumber}}",
  body: `
    Dear {{customerName}},
    
    This is a friendly reminder that invoice {{invoiceNumber}} 
    for {{total}} is {{status}}.
    
    {{#if overdue}}
    This invoice is now {{dayOverdue}} days overdue.
    {{/if}}
    
    Pay online: {{paymentLink}}
  `
};

cd apps/workbooks-api
bun test src/__tests__/crud/invoices.test.ts
bun test src/__tests__/integration/invoice-payment.test.ts