@pylonsync/create-pylon 0.3.274 → 0.3.276

package/templates/agency/functions/upsertInvoice.ts

@@ -0,0 +1,113 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import { lineItemsTotal, type ClientRow, type InvoiceLineItem, type ProjectRow } from "../lib/agency";
+
+// upsertInvoice — owner-only. Create a bill or edit one (pass `id`). The client
+// is referenced by id and must exist; we denormalize its name onto the invoice
+// (`clientName`) so the list renders without a join, and so the bill keeps the
+// name it was issued under even if the contact is renamed later. An optional
+// project link works the same way (`projectTitle`).
+//
+// `lineItems` is the source of truth for the amount: when present we store it
+// (JSON) and compute `amountCents = Σ quantity × unitCents` server-side, so the
+// total can never disagree with the breakdown the client sent. When omitted we
+// fall back to the explicit `amountCents` (a one-line bill). Amounts are cents.
+type Args = {
+  id?: string;
+  number: string;
+  clientId: string;
+  projectId?: string;
+  lineItems?: InvoiceLineItem[];
+  amountCents: number;
+  status?: string;
+  issuedAt?: string;
+  dueAt?: string;
+  notes?: string;
+};
+
+const STATUSES = new Set(["draft", "sent", "paid", "overdue"]);
+const clip = (s: string | undefined, max: number): string | null =>
+  s != null && s.trim().length > 0 ? s.trim().slice(0, max) : null;
+
+export default mutation<Args, { ok: boolean; id: string }>({
+  auth: "user",
+  args: {
+    id: v.optional(v.string()),
+    number: v.string(),
+    clientId: v.string(),
+    projectId: v.optional(v.string()),
+    lineItems: v.optional(
+      v.array(
+        v.object({ description: v.string(), quantity: v.number(), unitCents: v.int() }),
+      ),
+    ),
+    amountCents: v.int(),
+    status: v.optional(v.string()),
+    issuedAt: v.optional(v.string()),
+    dueAt: v.optional(v.string()),
+    notes: v.optional(v.string()),
+  },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage invoices.");
+    }
+    const number = args.number.trim();
+    if (number.length < 1 || number.length > 40) {
+      throw ctx.error("INVALID_ARGS", "An invoice number is required.");
+    }
+
+    const client = (await ctx.db.get("Client", args.clientId)) as ClientRow | null;
+    if (!client) throw ctx.error("INVALID_ARGS", "Pick a client for this invoice.");
+
+    let projectId: string | null = null;
+    let projectTitle: string | null = null;
+    if (args.projectId) {
+      const project = (await ctx.db.get("Project", args.projectId)) as ProjectRow | null;
+      if (project) {
+        projectId = project.id;
+        projectTitle = project.title;
+      }
+    }
+
+    // Normalize line items; when present they define the total.
+    const items: InvoiceLineItem[] = (args.lineItems ?? [])
+      .map((it) => ({
+        description: (it.description ?? "").trim().slice(0, 300),
+        quantity: Math.max(0, Number(it.quantity) || 0),
+        unitCents: Math.max(0, Math.trunc(Number(it.unitCents) || 0)),
+      }))
+      .filter((it) => it.description.length > 0 || it.unitCents > 0);
+
+    const amountCents =
+      items.length > 0 ? lineItemsTotal(items) : Math.max(0, Math.trunc(args.amountCents || 0));
+    const status = STATUSES.has((args.status ?? "").trim()) ? args.status!.trim() : "draft";
+
+    const patch = {
+      number,
+      clientId: client.id,
+      clientName: client.name,
+      projectId,
+      projectTitle,
+      lineItems: items.length > 0 ? JSON.stringify(items) : null,
+      amountCents,
+      status,
+      issuedAt: clip(args.issuedAt, 20),
+      dueAt: clip(args.dueAt, 20),
+      notes: clip(args.notes, 2000),
+    };
+
+    if (args.id) {
+      const existing = await ctx.db.get("Invoice", args.id);
+      if (!existing) throw ctx.error("NOT_FOUND", "Invoice not found.");
+      await ctx.db.unsafe.update("Invoice", args.id, patch);
+      return { ok: true, id: args.id };
+    }
+
+    const id = await ctx.db.unsafe.insert("Invoice", {
+      ...patch,
+      createdAt: new Date().toISOString(),
+    });
+    return { ok: true, id };
+  },
+});

package/templates/agency/functions/upsertProject.ts

@@ -0,0 +1,97 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import { slugify, type ProjectRow } from "../lib/agency";
+
+// upsertProject — owner-only. Create a new case study or edit an existing one
+// (pass `id` to update). Projects are public-read, so the change shows up on the
+// dashboard's live `db.useQuery("Project")` immediately, and on the marketing
+// site on its next render. The slug is derived from the title (or an explicit
+// slug) and made unique — a unique index backs it, so we resolve collisions
+// here rather than letting the insert fail.
+type Args = {
+  id?: string;
+  title: string;
+  slug?: string;
+  client?: string;
+  summary?: string;
+  year?: string;
+  tags?: string;
+  selected?: boolean;
+  published?: boolean;
+  order?: number;
+  challenge?: string;
+  approach?: string;
+  outcome?: string;
+  liveUrl?: string;
+};
+
+const clip = (s: string | undefined, max: number): string | null =>
+  s != null && s.trim().length > 0 ? s.trim().slice(0, max) : null;
+
+export default mutation<Args, { ok: boolean; id: string; slug: string }>({
+  auth: "user",
+  args: {
+    id: v.optional(v.string()),
+    title: v.string(),
+    slug: v.optional(v.string()),
+    client: v.optional(v.string()),
+    summary: v.optional(v.string()),
+    year: v.optional(v.string()),
+    tags: v.optional(v.string()),
+    selected: v.optional(v.boolean()),
+    published: v.optional(v.boolean()),
+    order: v.optional(v.int()),
+    challenge: v.optional(v.string()),
+    approach: v.optional(v.string()),
+    outcome: v.optional(v.string()),
+    liveUrl: v.optional(v.string()),
+  },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage projects.");
+    }
+    const title = args.title.trim();
+    if (title.length < 1 || title.length > 120) {
+      throw ctx.error("INVALID_ARGS", "A project title is required (up to 120 chars).");
+    }
+
+    await ctx.db.advisoryLock("agency_projects");
+    const all = (await ctx.db.unsafe.list("Project")) as unknown as ProjectRow[];
+
+    // Resolve a unique slug (skip the row being edited).
+    const base = slugify(args.slug || title) || "project";
+    let slug = base;
+    let n = 2;
+    while (all.some((p) => p.slug === slug && p.id !== args.id)) slug = `${base}-${n++}`;
+
+    const patch = {
+      title,
+      slug,
+      client: clip(args.client, 120) ?? "",
+      summary: clip(args.summary, 300) ?? "",
+      year: clip(args.year, 12),
+      tags: clip(args.tags, 200),
+      selected: args.selected === true,
+      published: args.published !== false, // default published
+      order: Math.trunc(args.order ?? 0),
+      challenge: clip(args.challenge, 2000),
+      approach: clip(args.approach, 2000),
+      outcome: clip(args.outcome, 2000),
+      liveUrl: clip(args.liveUrl, 400),
+    };
+
+    if (args.id) {
+      const existing = all.find((p) => p.id === args.id);
+      if (!existing) throw ctx.error("NOT_FOUND", "Project not found.");
+      await ctx.db.unsafe.update("Project", args.id, patch);
+      return { ok: true, id: args.id, slug };
+    }
+
+    const id = await ctx.db.unsafe.insert("Project", {
+      ...patch,
+      createdAt: new Date().toISOString(),
+    });
+    return { ok: true, id, slug };
+  },
+});

package/templates/agency/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/agency/lib/agency.ts

@@ -0,0 +1,189 @@
+// Shared agency types. The Inquiry / Client / Invoice rows are what the owner
+// dashboard sees (with PII + money); the client imports only the types, never
+// server code. Project is public, so it's read on both the marketing site and
+// the dashboard.
+
+export interface InquiryRow {
+  id: string;
+  name: string;
+  email: string;
+  company?: string | null;
+  projectType?: string | null;
+  budget?: string | null;
+  message?: string | null;
+  status: string; // "new" | "booked" | "declined"
+  createdAt: string;
+}
+
+// inquiriesForOwner returns a discriminated result rather than throwing on a
+// non-owner (a query has no `ctx.error`; a bare throw becomes a stripped
+// HANDLER_ERROR). A non-owner gets `{ authorized: false }` and NO data. The
+// other owner-gated queries (clientsForOwner / invoicesForOwner) follow the
+// same shape — see OwnerResult below.
+export type OwnerInquiriesResult =
+  | { authorized: true; inquiries: InquiryRow[] }
+  | { authorized: false };
+
+// The public, PII-free capacity the landing page reads live.
+export interface CapacityData {
+  label: string; // booking window, e.g. "Q3 2026"
+  openSlots: number;
+}
+
+// A portfolio piece + case study. Public — read on the marketing site AND in
+// the dashboard. `selected` features it on the homepage; `published` toggles
+// whether the public site shows it (drafts stay owner-only).
+export interface ProjectRow {
+  id: string;
+  title: string;
+  slug: string;
+  client: string;
+  summary: string;
+  year?: string | null;
+  tags?: string | null; // comma-separated
+  selected: boolean;
+  published: boolean;
+  order: number;
+  challenge?: string | null;
+  approach?: string | null;
+  outcome?: string | null;
+  liveUrl?: string | null;
+  createdAt: string;
+}
+
+// A CRM contact (owner-only — PII).
+export interface ClientRow {
+  id: string;
+  name: string;
+  company?: string | null;
+  email?: string | null;
+  phone?: string | null;
+  status: string; // "prospect" | "active" | "past"
+  notes?: string | null;
+  createdAt: string;
+}
+
+// One line on an invoice. `unitCents` is the per-unit price in integer cents;
+// the line total is `quantity * unitCents`.
+export interface InvoiceLineItem {
+  description: string;
+  quantity: number;
+  unitCents: number;
+}
+
+// A bill tied to a client, + optional project (owner-only — money + PII).
+// `amountCents` is the integer-cents total; `lineItems` is the JSON-encoded
+// breakdown (parse with `parseLineItems`).
+export interface InvoiceRow {
+  id: string;
+  number: string;
+  clientId: string;
+  clientName: string;
+  projectId?: string | null;
+  projectTitle?: string | null;
+  lineItems?: string | null; // JSON array of InvoiceLineItem
+  amountCents: number;
+  status: string; // "draft" | "sent" | "paid" | "overdue"
+  issuedAt?: string | null;
+  dueAt?: string | null;
+  notes?: string | null;
+  createdAt: string;
+}
+
+// Owner-gated queries that carry private rows use the same discriminated shape
+// as inquiries: `{ authorized: false }` for a non-owner, otherwise the data.
+export type OwnerClientsResult =
+  | { authorized: true; clients: ClientRow[] }
+  | { authorized: false };
+
+export type OwnerInvoicesResult =
+  | { authorized: true; invoices: InvoiceRow[] }
+  | { authorized: false };
+
+/* ------------------------------ helpers ------------------------------ */
+
+// Split a comma-separated tag string into trimmed, non-empty tags.
+export function parseTags(tags?: string | null): string[] {
+  return (tags ?? "")
+    .split(",")
+    .map((t) => t.trim())
+    .filter(Boolean);
+}
+
+// Format integer cents as a currency string ("$1,500.00"). Whole-dollar amounts
+// drop the cents ("$1,500").
+export function money(cents: number): string {
+  const dollars = (cents || 0) / 100;
+  const whole = Number.isInteger(dollars);
+  return dollars.toLocaleString("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: whole ? 0 : 2,
+    maximumFractionDigits: 2,
+  });
+}
+
+// Parse the JSON line-item blob off an invoice into a clean, typed array.
+// Tolerant: bad JSON or missing fields yield an empty list / zeroed fields
+// rather than throwing, so a malformed row never crashes the dashboard or PDF.
+export function parseLineItems(raw?: string | null): InvoiceLineItem[] {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.map((it) => ({
+      description: String(it?.description ?? ""),
+      quantity: Number(it?.quantity) || 0,
+      unitCents: Math.trunc(Number(it?.unitCents) || 0),
+    }));
+  } catch {
+    return [];
+  }
+}
+
+// Total of a line-item list, in integer cents.
+export function lineItemsTotal(items: InvoiceLineItem[]): number {
+  return items.reduce((sum, it) => sum + Math.round(it.quantity * it.unitCents), 0);
+}
+
+// Slugify a project title for its /work/[slug] URL.
+export function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+// A normalized project shape the public pages render — tags already split, the
+// storage flags (selected/published/order) dropped. Built from a DB row
+// (`viewFromRow`) or, before the portfolio is seeded, from a config case study,
+// so the marketing pages render identically either way.
+export interface ProjectView {
+  slug: string;
+  title: string;
+  client: string;
+  summary: string;
+  year?: string | null;
+  tags: string[];
+  challenge?: string | null;
+  approach?: string | null;
+  outcome?: string | null;
+  liveUrl?: string | null;
+}
+
+export function viewFromRow(r: ProjectRow): ProjectView {
+  return {
+    slug: r.slug,
+    title: r.title,
+    client: r.client,
+    summary: r.summary,
+    year: r.year,
+    tags: parseTags(r.tags),
+    challenge: r.challenge,
+    approach: r.approach,
+    outcome: r.outcome,
+    liveUrl: r.liveUrl,
+  };
+}

package/templates/agency/lib/invoice-pdf.tsx

@@ -0,0 +1,174 @@
+import React from "react";
+import { Document, Page, View, Text, StyleSheet, pdf } from "@react-pdf/renderer";
+import { money, type InvoiceLineItem } from "./agency";
+
+// Invoice → PDF, with @react-pdf/renderer (the React-to-PDF renderer — note
+// `react-pdf` proper is a *viewer* for existing PDFs; this is the generator).
+//
+// This module is imported DYNAMICALLY from the dashboard's "Download PDF" click
+// handler (`await import("@/lib/invoice-pdf")`), never during render — so the
+// ~1MB renderer + this document never touch SSR or the initial client bundle;
+// it loads only when the owner actually exports a bill. The PDF mirrors the
+// on-screen invoice view so what you see is what you download.
+
+export interface InvoicePdfData {
+  number: string;
+  status: string;
+  issuedAt?: string | null;
+  dueAt?: string | null;
+  notes?: string | null;
+  projectTitle?: string | null;
+  items: InvoiceLineItem[];
+  amountCents: number;
+  billTo: { name: string; company?: string | null; email?: string | null };
+  studio: {
+    name: string;
+    addressLines: string[];
+    paymentTerms: string;
+    footerNote: string;
+    brandColor: string;
+  };
+}
+
+// Build (and return) the invoice PDF as a Blob the caller can download.
+export async function buildInvoiceBlob(data: InvoicePdfData): Promise<Blob> {
+  return await pdf(<InvoiceDocument data={data} />).toBlob();
+}
+
+const STATUS_COLOR: Record<string, string> = {
+  draft: "#71717a",
+  sent: "#2563eb",
+  paid: "#16a34a",
+  overdue: "#dc2626",
+};
+
+function InvoiceDocument({ data }: { data: InvoicePdfData }) {
+  const { studio, billTo } = data;
+  const s = makeStyles(studio.brandColor);
+  // A bill with no explicit line items still prints one line for its total.
+  const items =
+    data.items.length > 0
+      ? data.items
+      : [{ description: "Services", quantity: 1, unitCents: data.amountCents }];
+
+  return (
+    <Document title={`Invoice ${data.number}`} author={studio.name}>
+      <Page size="A4" style={s.page}>
+        {/* Header */}
+        <View style={s.header}>
+          <View>
+            <Text style={s.studioName}>{studio.name}</Text>
+            {studio.addressLines.map((l, i) => (
+              <Text key={i} style={s.muted}>
+                {l}
+              </Text>
+            ))}
+          </View>
+          <View style={s.headerRight}>
+            <Text style={s.invoiceLabel}>INVOICE</Text>
+            <Text style={s.invoiceNumber}>{data.number}</Text>
+            <Text style={[s.status, { color: STATUS_COLOR[data.status] ?? "#71717a" }]}>
+              {data.status.toUpperCase()}
+            </Text>
+          </View>
+        </View>
+
+        <View style={s.rule} />
+
+        {/* Bill-to + meta */}
+        <View style={s.cols}>
+          <View style={s.col}>
+            <Text style={s.sectionLabel}>BILL TO</Text>
+            <Text style={s.strong}>{billTo.name}</Text>
+            {billTo.company ? <Text style={s.muted}>{billTo.company}</Text> : null}
+            {billTo.email ? <Text style={s.muted}>{billTo.email}</Text> : null}
+          </View>
+          <View style={s.colRight}>
+            {data.projectTitle ? <Meta s={s} label="Project" value={data.projectTitle} /> : null}
+            {data.issuedAt ? <Meta s={s} label="Issued" value={data.issuedAt} /> : null}
+            {data.dueAt ? <Meta s={s} label="Due" value={data.dueAt} /> : null}
+            <Meta s={s} label="Terms" value={studio.paymentTerms} />
+          </View>
+        </View>
+
+        {/* Line items */}
+        <View style={s.table}>
+          <View style={s.tableHead}>
+            <Text style={[s.cell, s.cDesc, s.headCell]}>Description</Text>
+            <Text style={[s.cell, s.cQty, s.headCell]}>Qty</Text>
+            <Text style={[s.cell, s.cUnit, s.headCell]}>Unit</Text>
+            <Text style={[s.cell, s.cAmt, s.headCell]}>Amount</Text>
+          </View>
+          {items.map((it, i) => (
+            <View key={i} style={s.tableRow}>
+              <Text style={[s.cell, s.cDesc]}>{it.description}</Text>
+              <Text style={[s.cell, s.cQty]}>{it.quantity}</Text>
+              <Text style={[s.cell, s.cUnit]}>{money(it.unitCents)}</Text>
+              <Text style={[s.cell, s.cAmt]}>{money(Math.round(it.quantity * it.unitCents))}</Text>
+            </View>
+          ))}
+          <View style={s.totalRow}>
+            <Text style={s.totalLabel}>Total due</Text>
+            <Text style={s.totalValue}>{money(data.amountCents)}</Text>
+          </View>
+        </View>
+
+        {data.notes ? (
+          <View style={s.notes}>
+            <Text style={s.sectionLabel}>NOTES</Text>
+            <Text style={s.muted}>{data.notes}</Text>
+          </View>
+        ) : null}
+
+        <Text style={s.footer} fixed>
+          {studio.footerNote}
+        </Text>
+      </Page>
+    </Document>
+  );
+}
+
+function Meta({ s, label, value }: { s: ReturnType<typeof makeStyles>; label: string; value: string }) {
+  return (
+    <View style={s.metaRow}>
+      <Text style={s.metaLabel}>{label}</Text>
+      <Text style={s.metaValue}>{value}</Text>
+    </View>
+  );
+}
+
+function makeStyles(brand: string) {
+  return StyleSheet.create({
+    page: { padding: 48, fontSize: 10, color: "#27272a", fontFamily: "Helvetica", lineHeight: 1.4 },
+    header: { flexDirection: "row", justifyContent: "space-between", alignItems: "flex-start" },
+    studioName: { fontSize: 18, fontFamily: "Helvetica-Bold", color: "#18181b", marginBottom: 4 },
+    headerRight: { alignItems: "flex-end" },
+    invoiceLabel: { fontSize: 11, letterSpacing: 2, color: brand, fontFamily: "Helvetica-Bold" },
+    invoiceNumber: { fontSize: 13, marginTop: 2, fontFamily: "Helvetica-Bold", color: "#18181b" },
+    status: { fontSize: 9, marginTop: 4, fontFamily: "Helvetica-Bold", letterSpacing: 1 },
+    muted: { color: "#71717a" },
+    rule: { borderBottomWidth: 1, borderBottomColor: "#e4e4e7", marginVertical: 18 },
+    cols: { flexDirection: "row", justifyContent: "space-between", marginBottom: 24 },
+    col: { width: "55%" },
+    colRight: { width: "40%" },
+    sectionLabel: { fontSize: 8, letterSpacing: 1.5, color: "#a1a1aa", fontFamily: "Helvetica-Bold", marginBottom: 5 },
+    strong: { fontFamily: "Helvetica-Bold", color: "#18181b", fontSize: 11 },
+    metaRow: { flexDirection: "row", justifyContent: "space-between", marginBottom: 3 },
+    metaLabel: { color: "#a1a1aa" },
+    metaValue: { color: "#27272a", fontFamily: "Helvetica-Bold" },
+    table: { marginTop: 4 },
+    tableHead: { flexDirection: "row", borderBottomWidth: 1, borderBottomColor: "#27272a", paddingBottom: 6 },
+    headCell: { fontFamily: "Helvetica-Bold", color: "#18181b", fontSize: 9, letterSpacing: 0.5 },
+    tableRow: { flexDirection: "row", borderBottomWidth: 1, borderBottomColor: "#f4f4f5", paddingVertical: 8 },
+    cell: { fontSize: 10 },
+    cDesc: { width: "52%", paddingRight: 8 },
+    cQty: { width: "12%", textAlign: "right" },
+    cUnit: { width: "18%", textAlign: "right" },
+    cAmt: { width: "18%", textAlign: "right" },
+    totalRow: { flexDirection: "row", justifyContent: "flex-end", marginTop: 12, paddingTop: 4 },
+    totalLabel: { fontSize: 11, fontFamily: "Helvetica-Bold", color: "#18181b", marginRight: 16 },
+    totalValue: { fontSize: 14, fontFamily: "Helvetica-Bold", color: brand, minWidth: 90, textAlign: "right" },
+    notes: { marginTop: 28 },
+    footer: { position: "absolute", bottom: 36, left: 48, right: 48, fontSize: 9, color: "#a1a1aa", textAlign: "center" },
+  });
+}

package/templates/agency/lib/owner.ts

@@ -0,0 +1,26 @@
+// Who owns this studio site? A studio is single-tenant — one business, one
+// owner — so ownership is just "the email the owner signs in with", configured
+// once via the PYLON_OWNER_EMAIL env var. The owner-only functions
+// (inquiriesForOwner etc.) read that env (via `ctx.env`) and compare it here.
+//
+// Fail closed: if PYLON_OWNER_EMAIL is unset, NOBODY is the owner and the
+// dashboard stays locked. That's deliberate — an unset owner on a public site
+// must not mean "everyone can read the inquiries". Set it in .env (see
+// .env.example) before signing in.
+
+export function normalizeOwner(raw: string | null | undefined): string | null {
+  const v = raw?.trim().toLowerCase();
+  return v && v.length > 0 ? v : null;
+}
+
+// Pure comparator — the caller supplies the configured owner value (from
+// `ctx.env.PYLON_OWNER_EMAIL`), so the rule lives in one place and stays
+// testable without reaching for the environment here.
+export function emailMatchesOwner(
+  email: string | null | undefined,
+  ownerRaw: string | null | undefined,
+): boolean {
+  const owner = normalizeOwner(ownerRaw);
+  if (!owner) return false;
+  return (email ?? "").trim().toLowerCase() === owner;
+}