@pylonsync/create-pylon 0.3.343 → 0.3.345

package/templates/helpdesk/lib/seed.ts

@@ -0,0 +1,185 @@
+// Demo data for a brand-new helpdesk.
+//
+// An empty inbox shows you nothing about triage, SLA, or the thread view. The
+// first sign-in seeds a realistic queue — including one ticket already past its
+// first-response window, so the breach state is visible rather than theoretical.
+//
+// Pure data + pure shaping; `functions/seedWorkspace.ts` stays a thin wrapper.
+
+export interface SeedCustomer {
+  key: string;
+  name: string;
+  email: string;
+  company: string;
+}
+
+export interface SeedTicket {
+  key: string;
+  customer: string;
+  subject: string;
+  status: string;
+  priority: string;
+  /** Hours since it arrived. */
+  age: number;
+  /** Hours since the first agent reply; null means nobody has answered. */
+  respondedAgo: number | null;
+}
+
+export interface SeedMessage {
+  ticket: string;
+  body: string;
+  fromCustomer: boolean;
+  internal?: boolean;
+  /** Hours ago. */
+  age: number;
+}
+
+export const SEED_CUSTOMERS: SeedCustomer[] = [
+  { key: "dana", name: "Dana Whitfield", email: "dana@northwind.co", company: "Northwind Logistics" },
+  { key: "tom", name: "Tom Alvarez", email: "tom@riverbed.coffee", company: "Riverbed Coffee" },
+  { key: "priya", name: "Priya Raman", email: "priya@hallmarkdental.com", company: "Hallmark Dental" },
+  { key: "ben", name: "Ben Osei", email: "ben@quarry.design", company: "Quarry Design Co" },
+  { key: "lena", name: "Lena Fischer", email: "lena@beaconproperty.com", company: "Beacon Property" },
+];
+
+export const SEED_TICKETS: SeedTicket[] = [
+  // Urgent, unanswered, 3h old against a 1h target — a live breach on first load.
+  {
+    key: "export",
+    customer: "dana",
+    subject: "Export is timing out on large date ranges",
+    status: "open",
+    priority: "urgent",
+    age: 3,
+    respondedAgo: null,
+  },
+  {
+    key: "invite",
+    customer: "tom",
+    subject: "Can't invite a second manager to the account",
+    status: "open",
+    priority: "high",
+    age: 6,
+    respondedAgo: 5,
+  },
+  {
+    key: "invoice",
+    customer: "priya",
+    subject: "Invoice shows last month's plan",
+    status: "pending",
+    priority: "normal",
+    age: 26,
+    respondedAgo: 24,
+  },
+  {
+    key: "sso",
+    customer: "ben",
+    subject: "SSO with Google Workspace — is it supported?",
+    status: "open",
+    priority: "normal",
+    age: 14,
+    respondedAgo: null,
+  },
+  {
+    key: "mobile",
+    customer: "lena",
+    subject: "Mobile layout cuts off the listing photos",
+    status: "solved",
+    priority: "low",
+    age: 120,
+    respondedAgo: 110,
+  },
+  {
+    key: "webhook",
+    customer: "dana",
+    subject: "Webhook retries are firing twice",
+    status: "closed",
+    priority: "high",
+    age: 300,
+    respondedAgo: 290,
+  },
+];
+
+export const SEED_MESSAGES: SeedMessage[] = [
+  {
+    ticket: "export",
+    body: "Pulling a 90-day export just spins and eventually errors. 30 days is fine. This is blocking our month-end reporting.",
+    fromCustomer: true,
+    age: 3,
+  },
+  {
+    ticket: "invite",
+    body: "I added marcus@northwind.co but he never got the email and doesn't show in the members list.",
+    fromCustomer: true,
+    age: 6,
+  },
+  {
+    ticket: "invite",
+    body: "Thanks Tom — I can see the invite was created but the delivery bounced. Re-sending now and checking the domain's SPF record.",
+    fromCustomer: false,
+    age: 5,
+  },
+  {
+    ticket: "invite",
+    body: "Their MX is misconfigured — flagging for the infra team rather than sending again blind.",
+    fromCustomer: false,
+    internal: true,
+    age: 5,
+  },
+  {
+    ticket: "invoice",
+    body: "We upgraded on the 3rd but the invoice still lists the old plan. Can you re-issue?",
+    fromCustomer: true,
+    age: 26,
+  },
+  {
+    ticket: "invoice",
+    body: "Re-issued and emailed — the proration lands on next month's invoice.",
+    fromCustomer: false,
+    age: 24,
+  },
+  {
+    ticket: "sso",
+    body: "We're standardising on Google Workspace this quarter. Does your plan include SAML, or only OAuth sign-in?",
+    fromCustomer: true,
+    age: 14,
+  },
+];
+
+export interface ShapedSeed {
+  customers: Array<{ key: string; row: Record<string, unknown> }>;
+  tickets: Array<{ key: string; customer: string; row: Record<string, unknown> }>;
+  messages: Array<{ ticket: string; row: Record<string, unknown> }>;
+}
+
+export function shapeSeed(now: number = Date.now()): ShapedSeed {
+  const hoursAgo = (hours: number) => new Date(now - hours * 3_600_000).toISOString();
+
+  return {
+    customers: SEED_CUSTOMERS.map((c) => ({
+      key: c.key,
+      row: { name: c.name, email: c.email, company: c.company, createdAt: hoursAgo(720) },
+    })),
+    tickets: SEED_TICKETS.map((t) => ({
+      key: t.key,
+      customer: t.customer,
+      row: {
+        subject: t.subject,
+        status: t.status,
+        priority: t.priority,
+        firstRespondedAt: t.respondedAgo === null ? null : hoursAgo(t.respondedAgo),
+        createdAt: hoursAgo(t.age),
+        updatedAt: hoursAgo(t.respondedAgo ?? t.age),
+      },
+    })),
+    messages: SEED_MESSAGES.map((m) => ({
+      ticket: m.ticket,
+      row: {
+        body: m.body,
+        fromCustomer: m.fromCustomer,
+        internal: m.internal ?? false,
+        createdAt: hoursAgo(m.age),
+      },
+    })),
+  };
+}

package/templates/helpdesk/lib/tickets.ts

@@ -0,0 +1,184 @@
+// The support model: statuses, priority, SLA, and the queue ordering.
+//
+// Pure — no React, no `db`. The rules that decide what an agent sees first are
+// the most important logic in a helpdesk, so they live where they can be tested
+// exhaustively without a server.
+
+export interface Status {
+  id: string;
+  label: string;
+  /** Solved and closed leave the queue. */
+  terminal?: boolean;
+}
+
+export const STATUSES: Status[] = [
+  { id: "open", label: "Open" },
+  { id: "pending", label: "Pending" },
+  { id: "solved", label: "Solved", terminal: true },
+  { id: "closed", label: "Closed", terminal: true },
+];
+
+export interface Priority {
+  id: string;
+  label: string;
+  /** Lower sorts first. */
+  rank: number;
+  /** Hours allowed for a first reply. */
+  firstResponseHours: number;
+}
+
+export const PRIORITIES: Priority[] = [
+  { id: "urgent", label: "Urgent", rank: 0, firstResponseHours: 1 },
+  { id: "high", label: "High", rank: 1, firstResponseHours: 4 },
+  { id: "normal", label: "Normal", rank: 2, firstResponseHours: 24 },
+  { id: "low", label: "Low", rank: 3, firstResponseHours: 72 },
+];
+
+export interface Ticket {
+  id: string;
+  subject: string;
+  status: string;
+  priority: string;
+  customerId?: string | null;
+  assigneeId?: string | null;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+  /** When an agent first replied; null while the customer is still waiting. */
+  firstRespondedAt?: string | null;
+}
+
+export function statusById(id: string): Status | undefined {
+  return STATUSES.find((s) => s.id === id);
+}
+
+export function priorityById(id: string): Priority | undefined {
+  return PRIORITIES.find((p) => p.id === id);
+}
+
+export function isValidStatus(id: string): boolean {
+  return STATUSES.some((s) => s.id === id);
+}
+
+export function isValidPriority(id: string): boolean {
+  return PRIORITIES.some((p) => p.id === id);
+}
+
+export function isOpen(ticket: { status: string }): boolean {
+  return !statusById(ticket.status)?.terminal;
+}
+
+export type SlaState = "met" | "due" | "breached" | "none";
+
+/**
+ * Where a ticket stands against its first-response target.
+ *
+ *   met      — an agent has already replied
+ *   breached — no reply and the window has passed
+ *   due      — no reply, inside the window
+ *   none     — terminal, or unparseable dates; nothing to chase
+ *
+ * A solved ticket that was answered late is still `met`: the SLA question is
+ * "did we reply", and re-flagging closed work just adds noise to the queue.
+ */
+export function slaState(
+  ticket: Ticket,
+  now: number = Date.now(),
+): SlaState {
+  if (!isOpen(ticket)) return "none";
+  if (ticket.firstRespondedAt) return "met";
+  const created = Date.parse(ticket.createdAt ?? "");
+  if (!Number.isFinite(created)) return "none";
+  const hours = priorityById(ticket.priority)?.firstResponseHours;
+  if (hours === undefined) return "none";
+  return now > created + hours * 3_600_000 ? "breached" : "due";
+}
+
+/** Minutes left before the first-response target, negative once breached. */
+export function minutesToBreach(
+  ticket: Ticket,
+  now: number = Date.now(),
+): number | null {
+  if (!isOpen(ticket) || ticket.firstRespondedAt) return null;
+  const created = Date.parse(ticket.createdAt ?? "");
+  const hours = priorityById(ticket.priority)?.firstResponseHours;
+  if (!Number.isFinite(created) || hours === undefined) return null;
+  return Math.round((created + hours * 3_600_000 - now) / 60_000);
+}
+
+/**
+ * Queue order: breached first, then by priority, then oldest first.
+ *
+ * Oldest-first within a priority is deliberate — sorting newest-first is how a
+ * ticket sits at the bottom of a busy queue for a week.
+ */
+export function queueOrder(tickets: Ticket[], now: number = Date.now()): Ticket[] {
+  return [...tickets].sort((a, b) => {
+    const aBreached = slaState(a, now) === "breached" ? 0 : 1;
+    const bBreached = slaState(b, now) === "breached" ? 0 : 1;
+    if (aBreached !== bBreached) return aBreached - bBreached;
+
+    const aRank = priorityById(a.priority)?.rank ?? 99;
+    const bRank = priorityById(b.priority)?.rank ?? 99;
+    if (aRank !== bRank) return aRank - bRank;
+
+    return (a.createdAt ?? "").localeCompare(b.createdAt ?? "");
+  });
+}
+
+export interface QueueCounts {
+  open: number;
+  pending: number;
+  solved: number;
+  closed: number;
+  unassigned: number;
+  breached: number;
+}
+
+export function counts(tickets: Ticket[], now: number = Date.now()): QueueCounts {
+  const result: QueueCounts = {
+    open: 0,
+    pending: 0,
+    solved: 0,
+    closed: 0,
+    unassigned: 0,
+    breached: 0,
+  };
+  for (const ticket of tickets) {
+    if (ticket.status in result) {
+      result[ticket.status as keyof QueueCounts] += 1;
+    }
+    if (isOpen(ticket) && !ticket.assigneeId) result.unassigned += 1;
+    if (slaState(ticket, now) === "breached") result.breached += 1;
+  }
+  return result;
+}
+
+export interface Filter {
+  status?: string;
+  priority?: string;
+  assigneeId?: string;
+  /** "unassigned" narrows to tickets with no agent. */
+  unassigned?: boolean;
+}
+
+export function applyFilter(tickets: Ticket[], filter: Filter): Ticket[] {
+  return tickets.filter((ticket) => {
+    if (filter.status && ticket.status !== filter.status) return false;
+    if (filter.priority && ticket.priority !== filter.priority) return false;
+    if (filter.assigneeId && ticket.assigneeId !== filter.assigneeId) return false;
+    if (filter.unassigned && ticket.assigneeId) return false;
+    return true;
+  });
+}
+
+/** "#1042" — short, stable, and greppable in an email thread. */
+export function ticketNumber(id: string, createdAt?: string | null): string {
+  // Derived from the id so it needs no counter and can't collide across
+  // concurrent inserts; the created date is only a tiebreaker for display.
+  let hash = 0;
+  const seed = `${id}${createdAt ?? ""}`;
+  for (let i = 0; i < seed.length; i += 1) {
+    hash = (hash * 31 + seed.charCodeAt(i)) | 0;
+  }
+  return `#${(Math.abs(hash) % 9000) + 1000}`;
+}

package/templates/helpdesk/lib/utils.ts

@@ -0,0 +1,10 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+// `cn` — the shadcn class merger. clsx resolves conditional/array class
+// inputs; tailwind-merge then dedupes conflicting Tailwind utilities so
+// the last one wins (e.g. `cn("px-2", "px-4")` → "px-4"). Every shadcn
+// component routes its className through this.
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/helpdesk/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "__APP_NAME_KEBAB__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pylon dev",
+    "deploy": "pylon deploy",
+    "check": "tsc --noEmit",
+    "test": "pylon test"
+  },
+  "dependencies": {
+    "@pylonsync/react": "^__PYLON_VERSION__",
+    "@pylonsync/sdk": "^__PYLON_VERSION__",
+    "@pylonsync/functions": "^__PYLON_VERSION__",
+    "@pylonsync/client": "^__PYLON_VERSION__",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.3.0",
+    "@tailwindcss/cli": "^4.3.0",
+    "tw-animate-css": "^1.2.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.5.0",
+    "lucide-react": "^0.460.0",
+    "@radix-ui/react-dialog": "^1.1.4",
+    "@radix-ui/react-slot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/helpdesk/tests/components.test.tsx

@@ -0,0 +1,202 @@
+import { afterEach, describe, expect, test } from "bun:test";
+// This project uses the classic JSX transform, so .tsx tests import React.
+import React from "react";
+import { cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import { TicketList } from "../components/ticket-list";
+import { Thread } from "../components/thread";
+import { SlaIndicator } from "../components/sla-indicator";
+import type { Ticket } from "../lib/tickets";
+
+afterEach(cleanup);
+
+// Tier 2: components. No mocking needed — they take data as props and report
+// changes through callbacks, because the container owns `db`.
+
+const NOW = Date.parse("2026-07-27T12:00:00Z");
+const hoursAgo = (h: number) => new Date(NOW - h * 3_600_000).toISOString();
+const noName = () => null;
+
+const tickets: Ticket[] = [
+  {
+    id: "breached",
+    subject: "Export is timing out",
+    status: "open",
+    priority: "urgent",
+    createdAt: hoursAgo(3),
+  },
+  {
+    id: "calm",
+    subject: "Mobile layout is off",
+    status: "open",
+    priority: "low",
+    createdAt: hoursAgo(1),
+    firstRespondedAt: hoursAgo(1),
+  },
+];
+
+describe("TicketList", () => {
+  test("puts the breached ticket at the top", () => {
+    // The queue's whole job is to answer "what next" — newest-first would bury
+    // the overdue one.
+    render(
+      <TicketList
+        tickets={tickets}
+        customerName={noName}
+        assigneeName={noName}
+        now={NOW}
+        onSelect={() => {}}
+      />,
+    );
+    const rows = screen.getAllByRole("button");
+    expect(within(rows[0]).getByText("Export is timing out")).toBeDefined();
+  });
+
+  test("marks a ticket with no agent as unassigned", () => {
+    render(
+      <TicketList
+        tickets={tickets}
+        customerName={noName}
+        assigneeName={noName}
+        now={NOW}
+        onSelect={() => {}}
+      />,
+    );
+    expect(screen.getAllByText("Unassigned").length).toBe(2);
+  });
+
+  test("selecting a row reports its id", () => {
+    const picked: string[] = [];
+    render(
+      <TicketList
+        tickets={tickets}
+        customerName={noName}
+        assigneeName={noName}
+        now={NOW}
+        onSelect={(id) => picked.push(id)}
+      />,
+    );
+    fireEvent.click(screen.getByText("Mobile layout is off"));
+    expect(picked).toEqual(["calm"]);
+  });
+});
+
+describe("SlaIndicator", () => {
+  test("shows how far past the window a breach is", () => {
+    const { container } = render(
+      <SlaIndicator ticket={tickets[0]} now={NOW} />,
+    );
+    expect(container.textContent).toContain("over");
+  });
+
+  test("renders nothing once answered", () => {
+    // A badge on every row is a badge that means nothing.
+    const { container } = render(<SlaIndicator ticket={tickets[1]} now={NOW} />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  test("renders nothing for a closed ticket", () => {
+    const { container } = render(
+      <SlaIndicator
+        ticket={{ ...tickets[0], status: "closed" }}
+        now={NOW}
+      />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+});
+
+describe("Thread", () => {
+  const messages = [
+    { id: "m1", body: "It broke", fromCustomer: true, createdAt: hoursAgo(3) },
+    { id: "m2", body: "Looking now", fromCustomer: false, createdAt: hoursAgo(2) },
+    { id: "m3", body: "Their MX is wrong", fromCustomer: false, internal: true, createdAt: hoursAgo(1) },
+  ];
+
+  test("renders oldest first", () => {
+    render(
+      <Thread
+        messages={messages}
+        authorName={() => "Agent"}
+        customerName="Dana"
+        now={NOW}
+        onSend={() => {}}
+      />,
+    );
+    const articles = screen.getAllByRole("article");
+    expect(within(articles[0]).getByText("It broke")).toBeDefined();
+  });
+
+  test("marks an internal note so it can't be mistaken for a reply", () => {
+    render(
+      <Thread
+        messages={messages}
+        authorName={() => "Agent"}
+        customerName="Dana"
+        now={NOW}
+        onSend={() => {}}
+      />,
+    );
+    // Scoped to the message: the composer's toggle carries the same label, so a
+    // bare getByText would match twice and throw.
+    const notes = screen
+      .getAllByRole("article")
+      .filter((article) => within(article).queryByText("Internal note"));
+    expect(notes).toHaveLength(1);
+    expect(within(notes[0]).getByText("Their MX is wrong")).toBeDefined();
+  });
+
+  test("sends a public reply by default", () => {
+    const sent: Array<[string, boolean]> = [];
+    render(
+      <Thread
+        messages={[]}
+        authorName={() => "Agent"}
+        customerName="Dana"
+        now={NOW}
+        onSend={(body, internal) => sent.push([body, internal])}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText("Reply"), {
+      target: { value: "On it" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /send reply/i }));
+    expect(sent).toEqual([["On it", false]]);
+  });
+
+  test("the internal toggle switches the composer and the flag", () => {
+    // Sending an internal note to the customer is the expensive mistake here,
+    // so the mode has to be visible AND actually carried through.
+    const sent: Array<[string, boolean]> = [];
+    render(
+      <Thread
+        messages={[]}
+        authorName={() => "Agent"}
+        customerName="Dana"
+        now={NOW}
+        onSend={(body, internal) => sent.push([body, internal])}
+      />,
+    );
+    fireEvent.click(screen.getByLabelText("Internal note"));
+    fireEvent.change(screen.getByLabelText("Internal note", { selector: "textarea" }), {
+      target: { value: "MX is broken" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /add note/i }));
+    expect(sent).toEqual([["MX is broken", true]]);
+  });
+
+  test("an empty reply is not sent", () => {
+    const sent: unknown[] = [];
+    render(
+      <Thread
+        messages={[]}
+        authorName={() => "Agent"}
+        customerName="Dana"
+        now={NOW}
+        onSend={() => sent.push(1)}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText("Reply"), { target: { value: "   " } });
+    fireEvent.click(screen.getByRole("button", { name: /send reply/i }));
+    expect(sent).toEqual([]);
+  });
+});