@pylonsync/create-pylon 0.3.344 → 0.3.346

package/templates/helpdesk/functions/replyToTicket.ts

@@ -0,0 +1,55 @@
+import { mutation, v } from "@pylonsync/functions";
+
+/**
+ * Post an agent message on a ticket.
+ *
+ * A mutation rather than a bare insert because a reply changes the ticket too:
+ * the first public reply stamps `firstRespondedAt`, which is what the SLA state
+ * is computed from. Doing that client-side would let a slow or offline tab
+ * decide when the clock stopped.
+ *
+ * An INTERNAL note deliberately does NOT stop the clock — the customer is still
+ * waiting, and a team that could clear its SLA by talking to itself would have
+ * an SLA worth nothing.
+ */
+export default mutation<
+  { ticketId: string; body: string; internal?: boolean },
+  { ok: true; id: string }
+>({
+  auth: "user",
+  args: {
+    ticketId: v.id("Ticket"),
+    body: v.string(),
+    internal: v.optional(v.boolean()),
+  },
+  async handler(ctx, args) {
+    const body = args.body.trim();
+    if (!body) throw ctx.error("INVALID_ARGS", "A reply needs a body.");
+
+    const ticket = await ctx.db.get("Ticket", args.ticketId);
+    if (!ticket) throw ctx.error("NOT_FOUND", "Ticket not found.");
+
+    const internal = args.internal ?? false;
+    const now = new Date().toISOString();
+
+    const id = await ctx.db.insert("Message", {
+      ticketId: args.ticketId,
+      body,
+      fromCustomer: false,
+      internal,
+      authorId: ctx.auth.userId,
+      createdAt: now,
+    });
+
+    const patch: Record<string, unknown> = { updatedAt: now };
+    if (!internal && !ticket.firstRespondedAt) {
+      patch.firstRespondedAt = now;
+    }
+    // Replying to something nobody owns takes ownership — the common case, and
+    // it stops two agents answering the same ticket.
+    if (!ticket.assigneeId) patch.assigneeId = ctx.auth.userId;
+    await ctx.db.update("Ticket", args.ticketId, patch);
+
+    return { ok: true, id: id as string } as const;
+  },
+});

package/templates/helpdesk/functions/seedWorkspace.ts

@@ -0,0 +1,52 @@
+import { mutation } from "@pylonsync/functions";
+import { shapeSeed } from "../lib/seed";
+
+/**
+ * Fill a brand-new helpdesk with a realistic queue, once.
+ *
+ * An empty inbox demonstrates nothing about triage, SLA, or the thread view.
+ * The client calls this after sign-in; it returns immediately if any ticket
+ * already exists, so it is safe on every load and can never duplicate the
+ * fixtures or touch real data.
+ *
+ * Delete this function and lib/seed.ts once real tickets arrive.
+ */
+export default mutation<Record<string, never>, { seeded: boolean }>({
+  auth: "user",
+  args: {},
+  async handler(ctx) {
+    const existing = await ctx.db.query("Ticket", { $limit: 1 });
+    if (existing.length > 0) return { seeded: false };
+
+    const seed = shapeSeed();
+    const me = ctx.auth.userId;
+
+    const customerIds = new Map<string, string>();
+    for (const customer of seed.customers) {
+      const id = await ctx.db.insert("Customer", customer.row);
+      customerIds.set(customer.key, id as string);
+    }
+
+    const ticketIds = new Map<string, string>();
+    for (const ticket of seed.tickets) {
+      const id = await ctx.db.insert("Ticket", {
+        ...ticket.row,
+        customerId: customerIds.get(ticket.customer) ?? null,
+        // Answered tickets are assigned to whoever is seeding; the unanswered
+        // ones stay unassigned so the queue has something to pick up.
+        assigneeId: ticket.row.firstRespondedAt ? me : null,
+      });
+      ticketIds.set(ticket.key, id as string);
+    }
+
+    for (const message of seed.messages) {
+      await ctx.db.insert("Message", {
+        ...message.row,
+        ticketId: ticketIds.get(message.ticket) ?? null,
+        authorId: message.row.fromCustomer ? null : me,
+      });
+    }
+
+    return { seeded: true };
+  },
+});

package/templates/helpdesk/functions/setTicketState.ts

@@ -0,0 +1,58 @@
+import { mutation, v } from "@pylonsync/functions";
+import { isValidPriority, isValidStatus } from "../lib/tickets";
+
+/**
+ * Change a ticket's status, priority, or assignee.
+ *
+ * One mutation for all three because they share the same validation and the
+ * same `updatedAt` bump, and because a queue that accepts an unknown status
+ * strands the ticket in a filter nothing renders. Every value is checked
+ * server-side — the UI only ever offers known ones, but the endpoint is
+ * reachable directly.
+ *
+ * `assigneeId: null` explicitly unassigns; omitting it leaves the owner alone.
+ */
+export default mutation<
+  {
+    ticketId: string;
+    status?: string;
+    priority?: string;
+    assigneeId?: string | null;
+  },
+  { ok: true }
+>({
+  auth: "user",
+  args: {
+    ticketId: v.id("Ticket"),
+    status: v.optional(v.string()),
+    priority: v.optional(v.string()),
+    assigneeId: v.optional(v.id("User")),
+  },
+  async handler(ctx, args) {
+    const ticket = await ctx.db.get("Ticket", args.ticketId);
+    if (!ticket) throw ctx.error("NOT_FOUND", "Ticket not found.");
+
+    const patch: Record<string, unknown> = { updatedAt: new Date().toISOString() };
+
+    if (args.status !== undefined) {
+      if (!isValidStatus(args.status)) {
+        throw ctx.error("INVALID_ARGS", `Unknown status "${args.status}".`);
+      }
+      patch.status = args.status;
+    }
+
+    if (args.priority !== undefined) {
+      if (!isValidPriority(args.priority)) {
+        throw ctx.error("INVALID_ARGS", `Unknown priority "${args.priority}".`);
+      }
+      patch.priority = args.priority;
+    }
+
+    if (args.assigneeId !== undefined) {
+      patch.assigneeId = args.assigneeId || null;
+    }
+
+    await ctx.db.update("Ticket", args.ticketId, patch);
+    return { ok: true } as const;
+  },
+});

package/templates/helpdesk/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/helpdesk/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/helpdesk/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;
+}

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));
+}