@pylonsync/create-pylon 0.3.274 → 0.3.276

package/templates/agency/functions/bookInquiry.ts

@@ -0,0 +1,42 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// bookInquiry — owner-only. Marks a lead "booked" AND consumes one project slot:
+// it decrements Capacity.openSlots, which syncs to every open landing page, so
+// the hero's "N slots open" counter ticks down live for everyone. Taking a
+// per-row advisory lock on the capacity row makes the read-then-decrement
+// race-safe. Idempotent: booking an already-booked lead doesn't double-count.
+export default mutation<{ inquiryId: string }, { ok: boolean; openSlots: number }>({
+  auth: "user",
+  args: { inquiryId: v.id("Inquiry") },
+  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 inquiries.");
+    }
+
+    const inquiry = (await ctx.db.get("Inquiry", args.inquiryId)) as
+      | { status: string }
+      | null;
+    if (!inquiry) throw ctx.error("NOT_FOUND", "Inquiry not found.");
+
+    await ctx.db.advisoryLock("agency_capacity");
+    const cap = ((await ctx.db.unsafe.list("Capacity")) as unknown as {
+      id: string;
+      openSlots: number;
+    }[])[0];
+    let openSlots = cap?.openSlots ?? 0;
+
+    // Only decrement when this lead is newly booked — re-booking is a no-op.
+    if (inquiry.status !== "booked" && cap) {
+      openSlots = Math.max(0, cap.openSlots - 1);
+      await ctx.db.unsafe.update("Capacity", cap.id, {
+        openSlots,
+        updatedAt: new Date().toISOString(),
+      });
+    }
+    await ctx.db.unsafe.update("Inquiry", args.inquiryId, { status: "booked" });
+
+    return { ok: true, openSlots };
+  },
+});

package/templates/agency/functions/clientsForOwner.ts

@@ -0,0 +1,27 @@
+import { query } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import type { ClientRow, OwnerClientsResult } from "../lib/agency";
+
+// clientsForOwner — the owner's CRM. Client rows hold contact PII (name, email,
+// phone), so the entity denies all client access; this owner-gated query is the
+// only way to read them. A query has no `ctx.error`, so a non-owner gets
+// `{ authorized: false }` (a bare throw would surface as a stripped
+// HANDLER_ERROR) and NO data. The dashboard calls it with `callFn` and refetches
+// after any write.
+export default query({
+  auth: "user",
+  async handler(ctx): Promise<OwnerClientsResult> {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    const email = (me?.email as string | undefined) ?? null;
+    if (!emailMatchesOwner(email, ctx.env.PYLON_OWNER_EMAIL)) {
+      return { authorized: false };
+    }
+
+    const rows = (await ctx.db.unsafe.list("Client")) as unknown as ClientRow[];
+    const clients = rows
+      .map((r) => ({ ...r }))
+      .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+
+    return { authorized: true, clients };
+  },
+});

package/templates/agency/functions/declineInquiry.ts

@@ -0,0 +1,41 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// declineInquiry — owner-only. Marks a lead "declined". If it had been "booked",
+// it returns the project slot to the pool (Capacity.openSlots += 1), which syncs
+// live so the hero counter ticks back up everywhere. Race-safe via the capacity
+// advisory lock; idempotent on an already-declined lead.
+export default mutation<{ inquiryId: string }, { ok: boolean; openSlots: number }>({
+  auth: "user",
+  args: { inquiryId: v.id("Inquiry") },
+  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 inquiries.");
+    }
+
+    const inquiry = (await ctx.db.get("Inquiry", args.inquiryId)) as
+      | { status: string }
+      | null;
+    if (!inquiry) throw ctx.error("NOT_FOUND", "Inquiry not found.");
+
+    await ctx.db.advisoryLock("agency_capacity");
+    const cap = ((await ctx.db.unsafe.list("Capacity")) as unknown as {
+      id: string;
+      openSlots: number;
+    }[])[0];
+    let openSlots = cap?.openSlots ?? 0;
+
+    // Releasing a previously-booked lead frees its slot again.
+    if (inquiry.status === "booked" && cap) {
+      openSlots = cap.openSlots + 1;
+      await ctx.db.unsafe.update("Capacity", cap.id, {
+        openSlots,
+        updatedAt: new Date().toISOString(),
+      });
+    }
+    await ctx.db.unsafe.update("Inquiry", args.inquiryId, { status: "declined" });
+
+    return { ok: true, openSlots };
+  },
+});

package/templates/agency/functions/deleteClient.ts

@@ -0,0 +1,27 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import type { InvoiceRow } from "../lib/agency";
+
+// deleteClient — owner-only. Refuses to delete a client that still has invoices
+// (a financial record must not lose its counterparty); the owner deletes or
+// reassigns those invoices first. Returns `{ ok: false, invoices: n }` so the
+// dashboard can explain why.
+export default mutation<{ id: string }, { ok: boolean; invoices: number }>({
+  auth: "user",
+  args: { id: v.id("Client") },
+  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 clients.");
+    }
+    const client = await ctx.db.get("Client", args.id);
+    if (!client) return { ok: true, invoices: 0 };
+
+    const invoices = (await ctx.db.unsafe.list("Invoice")) as unknown as InvoiceRow[];
+    const linked = invoices.filter((i) => i.clientId === args.id).length;
+    if (linked > 0) return { ok: false, invoices: linked };
+
+    await ctx.db.unsafe.delete("Client", args.id);
+    return { ok: true, invoices: 0 };
+  },
+});

package/templates/agency/functions/deleteInvoice.ts

@@ -0,0 +1,19 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// deleteInvoice — owner-only. Removes a bill outright (e.g. a draft created in
+// error). No cascade — invoices don't own anything.
+export default mutation<{ id: string }, { ok: boolean }>({
+  auth: "user",
+  args: { id: v.id("Invoice") },
+  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 invoice = await ctx.db.get("Invoice", args.id);
+    if (!invoice) return { ok: true };
+    await ctx.db.unsafe.delete("Invoice", args.id);
+    return { ok: true };
+  },
+});

package/templates/agency/functions/deleteProject.ts

@@ -0,0 +1,20 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// deleteProject — owner-only. Removes a case study. Any invoice that referenced
+// it keeps its denormalized `projectTitle` (so the bill still reads sensibly),
+// it just no longer links anywhere — we don't cascade-delete money records.
+export default mutation<{ id: string }, { ok: boolean }>({
+  auth: "user",
+  args: { id: v.id("Project") },
+  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 project = await ctx.db.get("Project", args.id);
+    if (!project) return { ok: true };
+    await ctx.db.unsafe.delete("Project", args.id);
+    return { ok: true };
+  },
+});

package/templates/agency/functions/inquiriesForOwner.ts

@@ -0,0 +1,31 @@
+import { query } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import type { InquiryRow, OwnerInquiriesResult } from "../lib/agency";
+
+// inquiriesForOwner — the owner's view of every project lead, INCLUDING the
+// prospect's name, email, company, and budget. The one function allowed to
+// return that PII, gated to the configured owner (PYLON_OWNER_EMAIL via
+// ctx.env). A query has no `ctx.error`, so a non-owner gets `{ authorized:
+// false }` (a bare throw would surface as a stripped HANDLER_ERROR) and NO data.
+//
+// The dashboard calls it with `callFn` and re-fetches whenever the public
+// Capacity row changes — so booking a lead (which moves the counter) refreshes
+// the pipeline without a page reload, while contact details never travel over
+// entity sync.
+export default query({
+  auth: "user",
+  async handler(ctx): Promise<OwnerInquiriesResult> {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    const email = (me?.email as string | undefined) ?? null;
+    if (!emailMatchesOwner(email, ctx.env.PYLON_OWNER_EMAIL)) {
+      return { authorized: false };
+    }
+
+    const rows = (await ctx.db.unsafe.list("Inquiry")) as unknown as InquiryRow[];
+    const inquiries = rows
+      .map((r) => ({ ...r }))
+      .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+
+    return { authorized: true, inquiries };
+  },
+});

package/templates/agency/functions/invoicesForOwner.ts

@@ -0,0 +1,27 @@
+import { query } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import type { InvoiceRow, OwnerInvoicesResult } from "../lib/agency";
+
+// invoicesForOwner — the owner's billing. Invoices hold money + client data, so
+// the entity denies all client access; this owner-gated query is the only way
+// to read them. Like the other owner queries it returns `{ authorized: false }`
+// for a non-owner (a query has no `ctx.error`) rather than throwing. Sorted
+// newest-first by issue date, falling back to creation time.
+export default query({
+  auth: "user",
+  async handler(ctx): Promise<OwnerInvoicesResult> {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    const email = (me?.email as string | undefined) ?? null;
+    if (!emailMatchesOwner(email, ctx.env.PYLON_OWNER_EMAIL)) {
+      return { authorized: false };
+    }
+
+    const rows = (await ctx.db.unsafe.list("Invoice")) as unknown as InvoiceRow[];
+    const key = (i: InvoiceRow) => i.issuedAt || i.createdAt;
+    const invoices = rows
+      .map((r) => ({ ...r }))
+      .sort((a, b) => (key(a) < key(b) ? 1 : key(a) > key(b) ? -1 : 0));
+
+    return { authorized: true, invoices };
+  },
+});

package/templates/agency/functions/seedCapacity.ts

@@ -0,0 +1,26 @@
+import { mutation } from "@pylonsync/functions";
+import { siteConfig } from "../lib/site.config";
+
+// seedCapacity — create the single Capacity row from config on first visit
+// (idempotent). The landing page calls this on mount; once a row exists it's a
+// no-op, so it's safe to call on every load. A lock keeps two concurrent
+// first-visits from creating two rows.
+//
+// Public so an anonymous first visitor seeds it — it only ever writes the
+// config's booking window + open-slot count, never reads or returns anything
+// sensitive.
+export default mutation<Record<string, never>, { seeded: boolean }>({
+  auth: "public",
+  async handler(ctx) {
+    await ctx.db.advisoryLock("agency_seed_capacity");
+    const existing = await ctx.db.unsafe.list("Capacity");
+    if (existing.length > 0) return { seeded: false };
+
+    await ctx.db.unsafe.insert("Capacity", {
+      label: siteConfig.capacity.label,
+      openSlots: siteConfig.capacity.openSlots,
+      updatedAt: new Date().toISOString(),
+    });
+    return { seeded: true };
+  },
+});

package/templates/agency/functions/seedProjects.ts

@@ -0,0 +1,41 @@
+import { mutation } from "@pylonsync/functions";
+import { siteConfig } from "../lib/site.config";
+import { slugify } from "../lib/agency";
+
+// seedProjects — create the portfolio from config on first visit (idempotent).
+// The public pages call it on mount; once any Project row exists it's a no-op,
+// so it's safe to call on every load. A lock keeps two concurrent first-visits
+// from double-seeding.
+//
+// Public so an anonymous first visitor seeds it: Projects are public marketing
+// content (no PII), and this only ever writes the config's case studies.
+export default mutation<Record<string, never>, { seeded: number }>({
+  auth: "public",
+  async handler(ctx) {
+    await ctx.db.advisoryLock("agency_seed_projects");
+    const existing = await ctx.db.unsafe.list("Project");
+    if (existing.length > 0) return { seeded: 0 };
+
+    const now = new Date().toISOString();
+    let order = 0;
+    for (const p of siteConfig.work.items) {
+      await ctx.db.unsafe.insert("Project", {
+        title: p.title,
+        slug: p.slug || slugify(p.title),
+        client: p.client,
+        summary: p.summary,
+        year: p.year ?? null,
+        tags: p.tags.join(", "),
+        selected: p.selected ?? false,
+        published: true,
+        order: order++,
+        challenge: p.challenge ?? null,
+        approach: p.approach ?? null,
+        outcome: p.outcome ?? null,
+        liveUrl: p.liveUrl ?? null,
+        createdAt: now,
+      });
+    }
+    return { seeded: order };
+  },
+});

package/templates/agency/functions/seedStudioBackoffice.ts

@@ -0,0 +1,74 @@
+import { mutation } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import { siteConfig } from "../lib/site.config";
+import { lineItemsTotal, slugify, type ProjectRow } from "../lib/agency";
+
+// seedStudioBackoffice — owner-only, idempotent. Fills the dashboard's CRM +
+// billing with the demo clients/invoices from config so it isn't an empty shell
+// on first sign-in. Private data (PII + money) is only ever seeded for the
+// signed-in owner — never by an anonymous visitor — which is why this is
+// owner-gated, unlike the public seedProjects.
+//
+// Invoices link to clients by name and to projects by slug; we resolve those to
+// ids here. Projects may already be seeded (the public site calls seedProjects);
+// if a project isn't present yet, the invoice still carries its title and just
+// doesn't deep-link.
+export default mutation<Record<string, never>, { seeded: boolean }>({
+  auth: "user",
+  async handler(ctx) {
+    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 seed the back-office.");
+    }
+
+    await ctx.db.advisoryLock("agency_seed_backoffice");
+    const existingClients = await ctx.db.unsafe.list("Client");
+    if (existingClients.length > 0) return { seeded: false };
+
+    const now = new Date().toISOString();
+
+    // Clients first — keep a name → id map for the invoices.
+    const clientIdByName = new Map<string, string>();
+    for (const c of siteConfig.backoffice.clients) {
+      const id = await ctx.db.unsafe.insert("Client", {
+        name: c.name,
+        company: c.company ?? null,
+        email: c.email ?? null,
+        phone: c.phone ?? null,
+        status: c.status ?? "prospect",
+        notes: c.notes ?? null,
+        createdAt: now,
+      });
+      clientIdByName.set(c.name, id);
+    }
+
+    // Resolve project links by slug (config slug, or derived from the title).
+    const projects = (await ctx.db.unsafe.list("Project")) as unknown as ProjectRow[];
+    const projectBySlug = new Map(projects.map((p) => [p.slug, p]));
+    const titleBySlug = new Map(
+      siteConfig.work.items.map((p) => [p.slug || slugify(p.title), p.title]),
+    );
+
+    for (const inv of siteConfig.backoffice.invoices) {
+      const clientId = clientIdByName.get(inv.client);
+      if (!clientId) continue; // skip an invoice whose client wasn't seeded
+      const project = inv.projectSlug ? projectBySlug.get(inv.projectSlug) : undefined;
+      await ctx.db.unsafe.insert("Invoice", {
+        number: inv.number,
+        clientId,
+        clientName: inv.client,
+        projectId: project?.id ?? null,
+        projectTitle: project?.title ?? (inv.projectSlug ? titleBySlug.get(inv.projectSlug) ?? null : null),
+        lineItems: JSON.stringify(inv.lineItems),
+        amountCents: lineItemsTotal(inv.lineItems),
+        status: inv.status ?? "draft",
+        issuedAt: inv.issuedAt ?? null,
+        dueAt: inv.dueAt ?? null,
+        notes: null,
+        createdAt: now,
+      });
+    }
+
+    return { seeded: true };
+  },
+});

package/templates/agency/functions/setCapacity.ts

@@ -0,0 +1,32 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// setCapacity — owner-only. Set the booking window label and how many project
+// slots are open (e.g. at the start of a new quarter). The update syncs to
+// every open landing page, so the hero counter reflects it live. Creates the
+// row if it doesn't exist yet.
+export default mutation<
+  { label: string; openSlots: number },
+  { ok: boolean; openSlots: number }
+>({
+  auth: "user",
+  args: { label: v.string(), openSlots: v.int() },
+  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 capacity.");
+    }
+    const label = args.label.trim().slice(0, 60);
+    const openSlots = Math.max(0, Math.trunc(args.openSlots));
+
+    await ctx.db.advisoryLock("agency_capacity");
+    const cap = ((await ctx.db.unsafe.list("Capacity")) as unknown as { id: string }[])[0];
+    const now = new Date().toISOString();
+    if (cap) {
+      await ctx.db.unsafe.update("Capacity", cap.id, { label, openSlots, updatedAt: now });
+    } else {
+      await ctx.db.unsafe.insert("Capacity", { label, openSlots, updatedAt: now });
+    }
+    return { ok: true, openSlots };
+  },
+});

package/templates/agency/functions/setInvoiceStatus.ts

@@ -0,0 +1,27 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// setInvoiceStatus — owner-only. Move a bill along its lifecycle
+// (draft → sent → paid, or → overdue) without re-opening the full editor. The
+// dashboard's per-invoice status menu calls this.
+const STATUSES = new Set(["draft", "sent", "paid", "overdue"]);
+
+export default mutation<{ id: string; status: string }, { ok: boolean }>({
+  auth: "user",
+  args: { id: v.id("Invoice"), status: 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 status = args.status.trim();
+    if (!STATUSES.has(status)) {
+      throw ctx.error("INVALID_ARGS", "Status must be draft, sent, paid, or overdue.");
+    }
+    const invoice = await ctx.db.get("Invoice", args.id);
+    if (!invoice) throw ctx.error("NOT_FOUND", "Invoice not found.");
+
+    await ctx.db.unsafe.update("Invoice", args.id, { status });
+    return { ok: true };
+  },
+});

package/templates/agency/functions/setProjectFlags.ts

@@ -0,0 +1,35 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// setProjectFlags — owner-only. A quick toggle for the two flags the owner flips
+// most: `selected` (feature it on the homepage) and `published` (show it on the
+// public site at all). Separate from the full upsertProject so the dashboard can
+// flip a switch without round-tripping the whole form. Pass only the flag(s) you
+// want to change.
+export default mutation<
+  { id: string; selected?: boolean; published?: boolean },
+  { ok: boolean }
+>({
+  auth: "user",
+  args: {
+    id: v.id("Project"),
+    selected: v.optional(v.boolean()),
+    published: v.optional(v.boolean()),
+  },
+  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 project = await ctx.db.get("Project", args.id);
+    if (!project) throw ctx.error("NOT_FOUND", "Project not found.");
+
+    const patch: Record<string, boolean> = {};
+    if (typeof args.selected === "boolean") patch.selected = args.selected;
+    if (typeof args.published === "boolean") patch.published = args.published;
+    if (Object.keys(patch).length > 0) {
+      await ctx.db.unsafe.update("Project", args.id, patch);
+    }
+    return { ok: true };
+  },
+});

package/templates/agency/functions/submitInquiry.ts

@@ -0,0 +1,55 @@
+import { mutation, v } from "@pylonsync/functions";
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// submitInquiry — a prospect's "start a project" lead. A `mutation` (it writes
+// the Inquiry row transactionally). `auth: "public"` — a prospect has no
+// account.
+//
+// PRIVACY: it returns only `{ ok }`, never an Inquiry row or anyone's details.
+// Submitting does NOT consume a capacity slot — a lead isn't a booking. The
+// owner books it from the dashboard, which is what decrements the live counter.
+export default mutation<
+  {
+    name: string;
+    email: string;
+    company?: string;
+    projectType?: string;
+    budget?: string;
+    message?: string;
+  },
+  { ok: boolean }
+>({
+  auth: "public",
+  args: {
+    name: v.string(),
+    email: v.string(),
+    company: v.optional(v.string()),
+    projectType: v.optional(v.string()),
+    budget: v.optional(v.string()),
+    message: v.optional(v.string()),
+  },
+  async handler(ctx, args) {
+    const name = args.name.trim();
+    const email = args.email.trim().toLowerCase();
+    if (name.length < 1 || name.length > 120) {
+      throw ctx.error("INVALID_ARGS", "Please enter your name.");
+    }
+    if (!EMAIL_RE.test(email) || email.length > 254) {
+      throw ctx.error("INVALID_ARGS", "Please enter a valid email address.");
+    }
+    const clip = (s: string | undefined, max: number) => (s ? s.trim().slice(0, max) : null);
+
+    await ctx.db.unsafe.insert("Inquiry", {
+      name,
+      email,
+      company: clip(args.company, 160),
+      projectType: clip(args.projectType, 80),
+      budget: clip(args.budget, 80),
+      message: clip(args.message, 4000),
+      status: "new",
+      createdAt: new Date().toISOString(),
+    });
+    return { ok: true };
+  },
+});

package/templates/agency/functions/upsertClient.ts

@@ -0,0 +1,73 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import type { ClientRow } from "../lib/agency";
+
+// upsertClient — owner-only. Create a CRM contact or edit one (pass `id`). When
+// a client's name or company changes, any invoice that referenced it keeps its
+// denormalized `clientName` from when it was issued — invoices are a financial
+// record and shouldn't silently rewrite themselves; the link by `clientId`
+// still resolves for navigation.
+type Args = {
+  id?: string;
+  name: string;
+  company?: string;
+  email?: string;
+  phone?: string;
+  status?: string;
+  notes?: string;
+};
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const STATUSES = new Set(["prospect", "active", "past"]);
+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()),
+    name: v.string(),
+    company: v.optional(v.string()),
+    email: v.optional(v.string()),
+    phone: v.optional(v.string()),
+    status: 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 clients.");
+    }
+    const name = args.name.trim();
+    if (name.length < 1 || name.length > 120) {
+      throw ctx.error("INVALID_ARGS", "A client name is required (up to 120 chars).");
+    }
+    const email = clip(args.email, 254);
+    if (email && !EMAIL_RE.test(email)) {
+      throw ctx.error("INVALID_ARGS", "Enter a valid email address.");
+    }
+    const status = STATUSES.has((args.status ?? "").trim()) ? args.status!.trim() : "prospect";
+
+    const patch = {
+      name,
+      company: clip(args.company, 160),
+      email,
+      phone: clip(args.phone, 40),
+      status,
+      notes: clip(args.notes, 2000),
+    };
+
+    if (args.id) {
+      const existing = (await ctx.db.get("Client", args.id)) as ClientRow | null;
+      if (!existing) throw ctx.error("NOT_FOUND", "Client not found.");
+      await ctx.db.unsafe.update("Client", args.id, patch);
+      return { ok: true, id: args.id };
+    }
+
+    const id = await ctx.db.unsafe.insert("Client", {
+      ...patch,
+      createdAt: new Date().toISOString(),
+    });
+    return { ok: true, id };
+  },
+});