feat: implement invoice installment plan builder (#404) (#529)

- Extend SplitMetaSchema with optional installments field and zod sum validation
- Add payMilestone flow with invoice/milestone text memo and Freighter signing
- Build InstallmentPlanBuilder component for add/remove/reorder UI
- Add InvoiceView payer-facing timeline with paid/upcoming/overdue badges
- Wire milestone pay buttons to on-chain payment per milestone amount
- Surface overdue installments in dashboard filters and badge counts
- Persist installments via existing in-memory splitMeta API
- Update /invoice/new Options step to include InstallmentPlanBuilder
- Add tests for schema validation, dashboard overdue filter, and builder

Co-authored-by: Emmanuel Chukwunyere <emmanuelanalaba@gmail.com>

Author: nonchalanttee22-lgtm

src/__tests__/dashboardFilters.test.ts

@@ -49,6 +49,16 @@ describe("dashboard filter presets", () => {
     expect(results.map((i) => i.id)).toEqual(["1"]);
   });
 
+  test("'overdue' returns pending invoices with splitMeta installments past due date", () => {
+    const splitMetaMap: Record<string, { installments?: { dueDate: number; status: string }[] }> = {
+      "1": { installments: [{ dueDate: now - 3600, status: "upcoming" }] },
+      "2": { installments: [{ dueDate: now + 86400, status: "upcoming" }] },
+      "3": { installments: [{ dueDate: now - 3600, status: "paid" }] },
+    };
+    const results = filterDashboardInvoices(invoices, "overdue", now, splitMetaMap);
+    expect(results.map((i) => i.id)).toEqual(["1"]);
+  });
+
   test("'all' returns every invoice", () => {
     const results = filterDashboardInvoices(invoices, "all");
     expect(results).toHaveLength(5);
@@ -61,10 +71,13 @@ describe("dashboard filter presets", () => {
       "refunded",
       "expired",
       "draft",
+      "overdue",
     ]);
     expect(DASHBOARD_PRESETS[0].emptyState.toLowerCase()).toContain("active");
     expect(DASHBOARD_PRESETS[1].emptyState.toLowerCase()).toContain("funded");
     expect(DASHBOARD_PRESETS[2].emptyState.toLowerCase()).toContain("refunded");
     expect(DASHBOARD_PRESETS[3].emptyState.toLowerCase()).toContain("expired");
+    expect(DASHBOARD_PRESETS[4].emptyState.toLowerCase()).toContain("draft");
+    expect(DASHBOARD_PRESETS[5].emptyState.toLowerCase()).toContain("overdue");
   });
 });

src/app/invoice/[id]/page.tsx

@@ -37,9 +37,11 @@ import CountdownTimer from "@/components/CountdownTimer";
 import SplitCalculator from "@/components/SplitCalculator";
 import InvoiceTagEditor from "@/components/invoice/InvoiceTagEditor";
 import type { SplitMeta } from "@/hooks/useSplitCalculator";
+import type { InstallmentMilestone } from "@/components/invoice/InvoiceView";
 import ActivityFeed from "@/components/ActivityFeed";
 import InstallmentTracker from "@/components/InstallmentTracker";
 import InstallmentPanel from "@/components/InstallmentPanel";
+import InvoiceView from "@/components/invoice/InvoiceView";
 import CoCreatorPanel from "@/components/CoCreatorPanel";
 import PaymentChannelPanel from "@/components/PaymentChannelPanel";
 import DisputeTimeline from "@/components/DisputeTimeline";
@@ -385,7 +387,7 @@ export default function InvoiceDetailPage({ params }: Props) {
 
   if (loading) {
     return (
-      <main className="max-w-2xl mx-auto px-4 sm:px-6 py-16">
+    <main className="max-w-2xl mx-auto px-4 sm:px-6 py-16 overflow-x-hidden">
         <div className="animate-pulse space-y-4">
           <div className="h-8 w-48 bg-gray-700 rounded" />
           <div className="h-4 w-full bg-gray-700 rounded" />
@@ -739,18 +741,28 @@ export default function InvoiceDetailPage({ params }: Props) {
       />
 
       {/* Installment schedule — only shown to payers with a registered plan */}
-      {publicKey && (
-        <>
-          <InstallmentTracker
-            invoice={invoice}
-            publicKey={publicKey}
-            onPayNow={(amount) => {
-              setPayAmount(formatAmount(amount));
-              setShowPayModal(true);
-            }}
-          />
-          <InstallmentPanel invoiceId={id} publicKey={publicKey} />
-        </>
+      {publicKey && loadedSplitMeta?.installments && loadedSplitMeta.installments.length > 0 && (
+        <InvoiceView
+          invoice={invoice}
+          installments={loadedSplitMeta.installments as InstallmentMilestone[]}
+          publicKey={publicKey}
+          onPaid={async (milestoneId, txHash) => {
+            const updated = (loadedSplitMeta.installments || []).map((m) =>
+              m.id === milestoneId ? { ...m, status: 'paid', txHash } : m
+            );
+            const newSplitMeta = { ...loadedSplitMeta, installments: updated } as SplitMeta;
+            setLoadedSplitMeta(newSplitMeta);
+            try {
+              await fetch(`/api/invoices/${id}`, {
+                method: "PATCH",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ splitMeta: newSplitMeta }),
+              });
+            } catch {
+              // ignore persistence errors
+            }
+          }}
+        />
       )}
 
       {/* Deadline extension voting — shown to payers on Pending invoices */}

src/app/invoice/new/page.tsx

@@ -33,6 +33,7 @@ import {
   calculateSplit,
   type SplitMeta,
 } from "@/hooks/useSplitCalculator";
+import InstallmentPlanBuilder from "@/components/invoice/InstallmentPlanBuilder";
 
 const RecipientForm = dynamic(() => import("@/components/RecipientForm"), { ssr: false });
 const TemplateManager = dynamic(() => import("@/components/TemplateManager"), { ssr: false });
@@ -132,6 +133,7 @@ function NewInvoiceForm() {
   const [intervalDays, setIntervalDays] = useState<7 | 30>(7);
   const [submitting, setSubmitting] = useState(false);
   const [splitMeta, setSplitMeta] = useState<SplitMeta | null>(null);
+  const [installments, setInstallments] = useState<{ id: string; amount: number; dueDate: number; status: string; txHash?: string }[]>([]);
   const [tags, setTags] = useState<string[]>([]);
   const { allTags, saveTags } = useInvoiceTags();
 
@@ -178,6 +180,7 @@ function NewInvoiceForm() {
     recurring,
     intervalDays,
     splitMeta,
+    installments,
   };
 
   const { isOffline: draftOffline, discardDraft } = useOfflineDraftAutosave(
@@ -448,6 +451,12 @@ function NewInvoiceForm() {
     goToStep(Math.max(step - 1, 0));
   };
 
+  const payloadForApi = () => {
+    if (!splitMeta) return null;
+    if (installments.length === 0) return splitMeta;
+    return { ...splitMeta, installments };
+  };
+
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
     if (!validateStep(step)) return;
@@ -485,11 +494,12 @@ function NewInvoiceForm() {
           recipients.map((r) => ({ address: r.address, amount: r.amount }))
         );
         addToast(`Invoice #${invoiceId} created`, "success");
-        if (splitMeta && splitMeta.recipients.length > 0) {
+        const apiPayload = payloadForApi();
+        if (apiPayload && (apiPayload as any).recipients?.length > 0) {
           fetch(`/api/invoices/${invoiceId}`, {
             method: "PATCH",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ splitMeta }),
+            body: JSON.stringify({ splitMeta: apiPayload }),
           }).catch(() => null);
         }
         if (tags.length > 0) {
@@ -514,11 +524,12 @@ function NewInvoiceForm() {
             amount: equalSplit ? (perRecipientAmount ?? "0") : r.amount,
           }))
         );
-        if (splitMeta && splitMeta.recipients.length > 0) {
+        const apiPayload = payloadForApi();
+        if (apiPayload && (apiPayload as any).recipients?.length > 0) {
           fetch(`/api/invoices/${invoiceId}`, {
             method: "PATCH",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ splitMeta }),
+            body: JSON.stringify({ splitMeta: apiPayload }),
           }).catch(() => null);
         }
         if (tags.length > 0) {
@@ -752,7 +763,9 @@ function NewInvoiceForm() {
     </div>
   );
 
-  const renderOptions = () => (
+  const renderOptions = () => {
+    const total = recipients.reduce((s, r) => s + parseFloat(r.amount || "0"), 0);
+    return (
     <div className="flex flex-col gap-6">
       <h2 className="text-xl font-semibold text-gray-900 dark:text-white">Options</h2>
 
@@ -785,7 +798,7 @@ function NewInvoiceForm() {
 
       {autofilled && !cloneSourceId && (
         <p className="text-xs text-indigo-400 bg-indigo-950/50 border border-indigo-800 rounded-lg px-3 py-2">
-          Autofilled from history — you can override any value.
+          Autofilled from history — you can override any value below.
         </p>
       )}
 
@@ -796,8 +809,16 @@ function NewInvoiceForm() {
           </p>
         </div>
       )}
+
+      <InstallmentPlanBuilder
+        totalAmount={total}
+        installments={installments}
+        assetCode={token === (process.env.NEXT_PUBLIC_USDC_ADDRESS ?? "") ? "USDC" : "XLM"}
+        onChange={setInstallments}
+      />
     </div>
-  );
+    );
+  };
 
   const renderReview = () => {
     const total = recipients.reduce((s, r) => s + parseFloat(r.amount || "0"), 0);

src/components/DashboardClient.tsx

@@ -74,6 +74,7 @@ export default function DashboardClient() {
   // Activity feed panel
   const [feedOpen, setFeedOpen] = useState(false);
   const { unreadCount } = useActivityFeed();
+  const [splitMetaMap, setSplitMetaMap] = useState<Record<string, { installments?: { dueDate: number; status: string }[] }>>({});
 
   // ── URL mutation helpers ────────────────────────────────────────────────────
 
@@ -140,6 +141,58 @@ export default function DashboardClient() {
     };
   }, [router]);
 
+  // Fetch invoices progressively
+  useEffect(() => {
+    if (!publicKey) return;
+    const fetchInvoices = async () => {
+      setLoading(true);
+      const results: Invoice[] = [];
+      for (let id = 1; id <= 50; id++) {
+        try {
+          const inv = await splitClient.getInvoice(String(id));
+          const mine =
+            inv.creator === publicKey ||
+            inv.recipients.some((r) => r.address === publicKey);
+          if (mine) {
+            results.push(inv);
+            setInvoices([...results]);
+          }
+        } catch {
+          break;
+        }
+      }
+      setLoading(false);
+    };
+    fetchInvoices().catch((e) => { setError(String(e)); setLoading(false); });
+  }, [publicKey]);
+
+  // Fetch splitMeta for overdue detection
+  useEffect(() => {
+    if (!publicKey || invoices.length === 0) return;
+    let cancelled = false;
+    (async () => {
+      const map: Record<string, { installments?: { dueDate: number; status: string }[] }> = {};
+      await Promise.all(
+        invoices.map(async (inv) => {
+          try {
+            const res = await fetch(`/api/invoices/${inv.id}`);
+            if (res.ok) {
+              const json = await res.json();
+              if (json.splitMeta?.installments) {
+                map[inv.id] = json.splitMeta;
+              }
+            }
+          } catch {
+            // ignore
+          }
+        })
+      );
+      if (!cancelled) setSplitMetaMap(map);
+    })();
+    return () => { cancelled = true; };
+  }, [publicKey, invoices]);
+
+  // Numeric search debounce
   // ── Numeric search debounce ─────────────────────────────────────────────────
   useEffect(() => {
     const trimmed = searchValue.trim();
@@ -165,7 +218,7 @@ export default function DashboardClient() {
 
   // ── Derived data ────────────────────────────────────────────────────────────
 
-  const presetCounts = useMemo(() => getDashboardPresetCounts(invoices), [invoices]);
+  const presetCounts = useMemo(() => getDashboardPresetCounts(invoices, Math.floor(Date.now() / 1000), splitMetaMap), [invoices, splitMetaMap]);
 
   const visibleInvoices = useMemo(() => {
     // 1. status filter (multi-select chips); if none selected show all
@@ -174,7 +227,7 @@ export default function DashboardClient() {
         ? invoices
         : invoices.filter((inv) =>
             statuses.some((s) =>
-              filterDashboardInvoices([inv], s).length > 0,
+              filterDashboardInvoices([inv], s, Math.floor(Date.now() / 1000), splitMetaMap).length > 0,
             ),
           );
     // 2. date range
@@ -186,6 +239,7 @@ export default function DashboardClient() {
     // 4. sort
     result = sortInvoices(result, sort);
     return result;
+  }, [invoices, statuses, dateFrom, dateTo, sort, splitMetaMap]);
   }, [invoices, statuses, dateFrom, dateTo, sort, tag, tagsByInvoice]);
 
   const { totalActive, totalValueLocked, totalReleased } = useMemo(() => {