@pylonsync/create-pylon 0.3.344 → 0.3.345

package/templates/invoices/functions/recordPayment.ts

@@ -0,0 +1,72 @@
+import { mutation, v } from "@pylonsync/functions";
+import { totals, type LineItem, type Payment } from "../lib/billing";
+
+/**
+ * Record money received against an invoice.
+ *
+ * A mutation rather than a bare insert because a payment can settle the
+ * invoice, and the status flip has to happen in the same transaction — a
+ * payment that lands without the status changing leaves someone chasing an
+ * invoice that's already been paid.
+ *
+ * The balance is recomputed SERVER-side from the line items and existing
+ * payments. Trusting a client-sent balance would let a stale tab overpay or
+ * mark an invoice settled that isn't.
+ */
+export default mutation<
+  { invoiceId: string; amountCents: number; method?: string; reference?: string },
+  { ok: true; settled: boolean }
+>({
+  auth: "user",
+  args: {
+    invoiceId: v.id("Invoice"),
+    amountCents: v.number(),
+    method: v.optional(v.string()),
+    reference: v.optional(v.string()),
+  },
+  async handler(ctx, args) {
+    const amountCents = Math.round(Number(args.amountCents) || 0);
+    if (amountCents <= 0) {
+      throw ctx.error("INVALID_ARGS", "A payment must be a positive amount.");
+    }
+
+    const invoice = await ctx.db.get("Invoice", args.invoiceId);
+    if (!invoice) throw ctx.error("NOT_FOUND", "Invoice not found.");
+    if (invoice.status === "void") {
+      throw ctx.error("INVALID_ARGS", "That invoice is void.");
+    }
+
+    const items = (await ctx.db.query("LineItem", {
+      invoiceId: args.invoiceId,
+    })) as unknown as LineItem[];
+    const payments = (await ctx.db.query("Payment", {
+      invoiceId: args.invoiceId,
+    })) as unknown as Payment[];
+
+    const before = totals(invoice as never, items, payments);
+    if (amountCents > before.balanceCents) {
+      throw ctx.error(
+        "INVALID_ARGS",
+        "That is more than the outstanding balance.",
+      );
+    }
+
+    const now = new Date().toISOString();
+    await ctx.db.insert("Payment", {
+      invoiceId: args.invoiceId,
+      amountCents,
+      method: args.method ?? "other",
+      reference: args.reference || null,
+      paidAt: now,
+      recordedBy: ctx.auth.userId,
+    });
+
+    const settled = amountCents >= before.balanceCents;
+    await ctx.db.update("Invoice", args.invoiceId, {
+      updatedAt: now,
+      ...(settled ? { status: "paid" } : {}),
+    });
+
+    return { ok: true, settled } as const;
+  },
+});

package/templates/invoices/functions/seedWorkspace.ts

@@ -0,0 +1,57 @@
+import { mutation } from "@pylonsync/functions";
+import { shapeSeed } from "../lib/seed";
+
+/**
+ * Fill a brand-new billing workspace once.
+ *
+ * An empty invoice list shows nothing about totals, ageing, or partial payment.
+ * The client calls this after sign-in; it returns immediately if any invoice
+ * exists, so it's safe on every load and can never duplicate the fixtures or
+ * touch real books.
+ *
+ * Delete this function and lib/seed.ts once you're billing real clients.
+ */
+export default mutation<Record<string, never>, { seeded: boolean }>({
+  auth: "user",
+  args: {},
+  async handler(ctx) {
+    const existing = await ctx.db.query("Invoice", { $limit: 1 });
+    if (existing.length > 0) return { seeded: false };
+
+    const seed = shapeSeed();
+    const me = ctx.auth.userId;
+
+    const clientIds = new Map<string, string>();
+    for (const client of seed.clients) {
+      const id = await ctx.db.insert("Client", client.row);
+      clientIds.set(client.key, id as string);
+    }
+
+    const invoiceIds = new Map<string, string>();
+    for (const invoice of seed.invoices) {
+      const id = await ctx.db.insert("Invoice", {
+        ...invoice.row,
+        clientId: clientIds.get(invoice.client) ?? null,
+        ownerId: me,
+      });
+      invoiceIds.set(invoice.key, id as string);
+    }
+
+    for (const line of seed.lines) {
+      await ctx.db.insert("LineItem", {
+        ...line.row,
+        invoiceId: invoiceIds.get(line.invoice) ?? null,
+      });
+    }
+
+    for (const payment of seed.payments) {
+      await ctx.db.insert("Payment", {
+        ...payment.row,
+        invoiceId: invoiceIds.get(payment.invoice) ?? null,
+        recordedBy: me,
+      });
+    }
+
+    return { seeded: true };
+  },
+});

package/templates/invoices/functions/setInvoiceStatus.ts

@@ -0,0 +1,35 @@
+import { mutation, v } from "@pylonsync/functions";
+import { isValidStatus } from "../lib/billing";
+
+/**
+ * Move an invoice between draft, sent, paid, and void.
+ *
+ * "overdue" is deliberately NOT settable — it's derived from the due date and
+ * the balance (lib/billing.ts), so there is no column to fall out of date and
+ * no nightly job to run.
+ *
+ * Sending stamps the issue date if it's missing, because "sent" with no issue
+ * date is a document that can't be aged.
+ */
+export default mutation<{ invoiceId: string; status: string }, { ok: true }>({
+  auth: "user",
+  args: { invoiceId: v.id("Invoice"), status: v.string() },
+  async handler(ctx, args) {
+    if (!isValidStatus(args.status)) {
+      throw ctx.error("INVALID_ARGS", `Unknown status "${args.status}".`);
+    }
+
+    const invoice = await ctx.db.get("Invoice", args.invoiceId);
+    if (!invoice) throw ctx.error("NOT_FOUND", "Invoice not found.");
+
+    const now = new Date().toISOString();
+    const patch: Record<string, unknown> = {
+      status: args.status,
+      updatedAt: now,
+    };
+    if (args.status === "sent" && !invoice.issueDate) patch.issueDate = now;
+
+    await ctx.db.update("Invoice", args.invoiceId, patch);
+    return { ok: true } as const;
+  },
+});

package/templates/invoices/gitignore

@@ -0,0 +1,10 @@
+node_modules/
+.pylon/
+pylon.manifest.json
+pylon.client.ts
+web/dist/
+*.db
+*.db-*
+.env
+.env.local
+.DS_Store

package/templates/invoices/lib/billing.ts

@@ -0,0 +1,259 @@
+// Invoice arithmetic and status.
+//
+// MONEY IS INTEGER CENTS everywhere in this app. Floating-point dollars are how
+// an invoice ends up off by a penny after tax, and a penny on an invoice is a
+// support ticket. Values are converted at the edges — `parseAmount` on input,
+// `money` on output — and never in between.
+//
+// Pure: no React, no `db`. The totals a customer is billed from are the last
+// thing that should need a running server to verify.
+
+export interface Status {
+  id: string;
+  label: string;
+}
+
+export const STATUSES: Status[] = [
+  { id: "draft", label: "Draft" },
+  { id: "sent", label: "Sent" },
+  { id: "paid", label: "Paid" },
+  { id: "void", label: "Void" },
+];
+
+export interface LineItem {
+  id: string;
+  invoiceId: string;
+  description: string;
+  /** Thousandths, so 1.5 hours is 1500 — no float quantities either. */
+  quantityMilli: number;
+  unitPriceCents: number;
+}
+
+export interface Payment {
+  id: string;
+  invoiceId: string;
+  amountCents: number;
+  paidAt?: string | null;
+  method?: string | null;
+}
+
+export interface Invoice {
+  id: string;
+  number: string;
+  clientId?: string | null;
+  status: string;
+  /** Basis points: 875 = 8.75%. Integer, for the same reason as cents. */
+  taxRateBps?: number | null;
+  issueDate?: string | null;
+  dueDate?: string | null;
+  notes?: string | null;
+  createdAt?: string | null;
+}
+
+export function statusById(id: string): Status | undefined {
+  return STATUSES.find((s) => s.id === id);
+}
+
+export function isValidStatus(id: string): boolean {
+  return STATUSES.some((s) => s.id === id);
+}
+
+export interface Totals {
+  subtotalCents: number;
+  taxCents: number;
+  totalCents: number;
+  paidCents: number;
+  balanceCents: number;
+}
+
+/**
+ * What an invoice is worth, what's been paid, and what's left.
+ *
+ * Tax is computed on the rounded subtotal rather than per line: that's what a
+ * customer can reproduce from the printed invoice, and per-line rounding drifts
+ * from the visible total.
+ */
+export function totals(
+  invoice: Invoice,
+  items: LineItem[],
+  payments: Payment[],
+): Totals {
+  const lines = items.filter((item) => item.invoiceId === invoice.id);
+  const subtotalCents = lines.reduce((sum, item) => sum + lineTotalCents(item), 0);
+
+  const bps = Math.max(0, Number(invoice.taxRateBps) || 0);
+  const taxCents = Math.round((subtotalCents * bps) / 10_000);
+  const totalCents = subtotalCents + taxCents;
+
+  const paidCents = payments
+    .filter((payment) => payment.invoiceId === invoice.id)
+    .reduce((sum, payment) => sum + (Number(payment.amountCents) || 0), 0);
+
+  return {
+    subtotalCents,
+    taxCents,
+    totalCents,
+    paidCents,
+    // Never negative: an overpayment is a credit to handle deliberately, not a
+    // negative balance that quietly offsets the next invoice.
+    balanceCents: Math.max(0, totalCents - paidCents),
+  };
+}
+
+/** One line, rounded once. quantityMilli is thousandths of a unit. */
+export function lineTotalCents(item: {
+  quantityMilli: number;
+  unitPriceCents: number;
+}): number {
+  const qty = Number(item.quantityMilli) || 0;
+  const unit = Number(item.unitPriceCents) || 0;
+  return Math.round((qty * unit) / 1000);
+}
+
+/**
+ * Overdue is DERIVED, not a stored status — an invoice becomes overdue by the
+ * clock passing, and no job runs at midnight to flip a column. A sent invoice
+ * with a due date in the past and a balance outstanding is overdue; anything
+ * paid, void, or still a draft is not.
+ */
+export function isOverdue(
+  invoice: Invoice,
+  balanceCents: number,
+  now: number = Date.now(),
+): boolean {
+  if (invoice.status !== "sent") return false;
+  if (balanceCents <= 0) return false;
+  const due = Date.parse(invoice.dueDate ?? "");
+  if (!Number.isFinite(due)) return false;
+  return now > endOfDay(due);
+}
+
+/** What to show in the status column, including the derived Overdue. */
+export function displayStatus(
+  invoice: Invoice,
+  balanceCents: number,
+  now: number = Date.now(),
+): string {
+  if (isOverdue(invoice, balanceCents, now)) return "overdue";
+  // A sent invoice that's been fully paid reads as paid even before someone
+  // remembers to change the field.
+  if (invoice.status === "sent" && balanceCents <= 0) return "paid";
+  return invoice.status;
+}
+
+export function daysOverdue(
+  invoice: Invoice,
+  now: number = Date.now(),
+): number | null {
+  const due = Date.parse(invoice.dueDate ?? "");
+  if (!Number.isFinite(due)) return null;
+  return Math.floor((startOfDay(now) - startOfDay(due)) / 86_400_000);
+}
+
+export interface Summary {
+  outstandingCents: number;
+  overdueCents: number;
+  paidCents: number;
+  draftCount: number;
+  overdueCount: number;
+}
+
+/** The numbers on the list header: what's owed, what's late, what's landed. */
+export function summarize(
+  invoices: Invoice[],
+  items: LineItem[],
+  payments: Payment[],
+  now: number = Date.now(),
+): Summary {
+  const summary: Summary = {
+    outstandingCents: 0,
+    overdueCents: 0,
+    paidCents: 0,
+    draftCount: 0,
+    overdueCount: 0,
+  };
+
+  for (const invoice of invoices) {
+    const t = totals(invoice, items, payments);
+    summary.paidCents += t.paidCents;
+    if (invoice.status === "draft") summary.draftCount += 1;
+    if (invoice.status === "sent") {
+      summary.outstandingCents += t.balanceCents;
+      if (isOverdue(invoice, t.balanceCents, now)) {
+        summary.overdueCents += t.balanceCents;
+        summary.overdueCount += 1;
+      }
+    }
+  }
+  return summary;
+}
+
+/** "$1,240.00" — invoices show exact amounts, never a compacted $1.2K. */
+export function money(cents: number | null | undefined): string {
+  const value = Number(cents) || 0;
+  const sign = value < 0 ? "-" : "";
+  const abs = Math.abs(value);
+  const dollars = Math.floor(abs / 100).toLocaleString("en-US");
+  const rest = String(abs % 100).padStart(2, "0");
+  return `${sign}$${dollars}.${rest}`;
+}
+
+/** "1.5" from 1500 thousandths, without a trailing ".000". */
+export function quantity(milli: number | null | undefined): string {
+  const value = (Number(milli) || 0) / 1000;
+  return String(Number(value.toFixed(3)));
+}
+
+/**
+ * Parse a typed amount into cents. Accepts "1,240.50", "$1240.5", "1240".
+ * Returns null for anything it can't read, so a bad keystroke can't silently
+ * become $0.00 on a bill.
+ */
+export function parseAmount(input: string): number | null {
+  const cleaned = input.replace(/[$,\s]/g, "");
+  if (!cleaned || !/^-?\d*\.?\d*$/.test(cleaned) || cleaned === "." || cleaned === "-") {
+    return null;
+  }
+  const value = Number(cleaned);
+  if (!Number.isFinite(value)) return null;
+  return Math.round(value * 100);
+}
+
+/** Parse a typed quantity into thousandths. */
+export function parseQuantity(input: string): number | null {
+  const cleaned = input.replace(/[,\s]/g, "");
+  if (!cleaned || !/^\d*\.?\d*$/.test(cleaned) || cleaned === ".") return null;
+  const value = Number(cleaned);
+  if (!Number.isFinite(value)) return null;
+  return Math.round(value * 1000);
+}
+
+/**
+ * The next invoice number, continuing whatever series is already there.
+ *
+ * Derived from the existing numbers rather than a stored counter: a counter in
+ * a synced replica is a race, and gaps in an invoice series get asked about by
+ * accountants.
+ */
+export function nextNumber(existing: string[], year: number): string {
+  const prefix = `INV-${year}-`;
+  let highest = 0;
+  for (const number of existing) {
+    if (!number.startsWith(prefix)) continue;
+    const suffix = Number(number.slice(prefix.length));
+    if (Number.isFinite(suffix) && suffix > highest) highest = suffix;
+  }
+  return `${prefix}${String(highest + 1).padStart(4, "0")}`;
+}
+
+function startOfDay(ms: number): number {
+  const date = new Date(ms);
+  date.setHours(0, 0, 0, 0);
+  return date.getTime();
+}
+
+function endOfDay(ms: number): number {
+  const date = new Date(ms);
+  date.setHours(23, 59, 59, 999);
+  return date.getTime();
+}

package/templates/invoices/lib/format.ts

@@ -0,0 +1,53 @@
+// Small display helpers shared across views. Pure, so the timeline and the
+// queue can't drift on how they render the same instant.
+
+/** Initials for an avatar: "Dana Whitfield" → "DW", "jordan@x.com" → "JO". */
+export function initials(nameOrEmail: string | null | undefined): string {
+  const raw = (nameOrEmail ?? "").trim();
+  if (!raw) return "?";
+  const name = raw.includes("@") ? raw.split("@")[0] : raw;
+  const parts = name.split(/[\s._-]+/).filter(Boolean);
+  if (parts.length === 0) return "?";
+  if (parts.length === 1) return parts[0].slice(0, 2).toUpperCase();
+  return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+}
+
+/** A stable accent per record, so the same person keeps their colour. */
+export function accentIndex(seed: string, buckets = 6): number {
+  let hash = 0;
+  for (let i = 0; i < seed.length; i += 1) {
+    hash = (hash * 31 + seed.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash) % buckets;
+}
+
+/** "just now" / "4h ago" / "Mar 3". */
+export function relativeTime(
+  iso: string | null | undefined,
+  now: number = Date.now(),
+): string {
+  if (!iso) return "";
+  const then = Date.parse(iso);
+  if (!Number.isFinite(then)) return "";
+  const seconds = Math.round((now - then) / 1000);
+  if (seconds < 45) return "just now";
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.round(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  return new Date(then).toLocaleDateString("en-US", { month: "short", day: "numeric" });
+}
+
+/** "3h 20m" / "45m" / "2d" — a duration an agent reads at a glance. */
+export function duration(minutes: number): string {
+  const abs = Math.abs(Math.round(minutes));
+  if (abs < 60) return `${abs}m`;
+  if (abs < 1440) {
+    const hours = Math.floor(abs / 60);
+    const rest = abs % 60;
+    return rest === 0 ? `${hours}h` : `${hours}h ${rest}m`;
+  }
+  return `${Math.floor(abs / 1440)}d`;
+}

package/templates/invoices/lib/search.ts

@@ -0,0 +1,78 @@
+// Client-side search powering the ⌘K palette.
+//
+// A small team's CRM fits in the synced replica, so search runs locally against
+// data already in memory: results appear as you type, with no request per
+// keystroke. Swap in `db.useSearch` (Pylon's FTS) when a workspace outgrows
+// that — the component boundary doesn't change, only this file.
+
+export interface SearchItem {
+  id: string;
+  type: "deal" | "company" | "contact";
+  title: string;
+  /** Second line: the company for a contact, the domain for a company. */
+  subtitle?: string;
+  href: string;
+  /** Extra text matched but not displayed — an email, say. */
+  keywords?: string;
+}
+
+export interface Scored extends SearchItem {
+  score: number;
+}
+
+/**
+ * Rank items against a query. Prefix matches beat word-boundary matches, which
+ * beat substring matches; ties break on the shorter title, so "Acme" ranks
+ * above "Acme Corporation Holdings" for the query "acme".
+ */
+export function searchItems(
+  items: SearchItem[],
+  query: string,
+  limit = 8,
+): SearchItem[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return items.slice(0, limit);
+
+  const scored: Scored[] = [];
+  for (const item of items) {
+    const score = scoreItem(item, q);
+    if (score > 0) scored.push({ ...item, score });
+  }
+  scored.sort(
+    (a, b) => b.score - a.score || a.title.length - b.title.length ||
+      a.title.localeCompare(b.title),
+  );
+  return scored.slice(0, limit);
+}
+
+function scoreItem(item: SearchItem, q: string): number {
+  const title = item.title.toLowerCase();
+  if (title.startsWith(q)) return 100;
+  if (wordStart(title, q)) return 80;
+  if (title.includes(q)) return 60;
+
+  const haystack = `${item.subtitle ?? ""} ${item.keywords ?? ""}`.toLowerCase();
+  if (wordStart(haystack, q)) return 40;
+  if (haystack.includes(q)) return 20;
+  return 0;
+}
+
+function wordStart(haystack: string, needle: string): boolean {
+  let from = 0;
+  for (;;) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) return false;
+    if (at === 0 || /[\s._@/-]/.test(haystack[at - 1])) return true;
+    from = at + 1;
+  }
+}
+
+/** Move through a list with arrow keys, wrapping at both ends. */
+export function moveSelection(
+  current: number,
+  delta: number,
+  length: number,
+): number {
+  if (length === 0) return 0;
+  return (current + delta + length) % length;
+}