Public: anyone can read this; the crew can change it.
Every reminder signs off with the agent's name, brokerage, phone and email, and the README says how to make the app carry your own #41
Check · Review · Land · Live done — Landed and live in production.
mason/deal-clock:mason/36-every-reminder-signs-off-with-the-agent → main 2 commits fork 4 threads · 4 unresolved
14 files
changed +169
−11
README.md +17
| @@ -99,6 +99,23 @@ Signed out, `/` shows what deal-clock does, three short points, a still picture | ||
| 99 | 99 | samples return as they were, dated from today, and the deals you opened are |
| 100 | 100 | left alone. Only an admin sees it. In the terminal press R; over MCP, the `restore_samples` tool. |
| 101 | 101 | |
| 102 | ## Make it yours | |
| 103 | ||
| 104 | The app ships with a sample agent. To carry your own, set four settings | |
| 105 | (Settings → App → Environment): | |
| 106 | ||
| 107 | - `DEAL_CLOCK_AGENT`: your name. | |
| 108 | - `DEAL_CLOCK_BROKERAGE`: your brokerage. | |
| 109 | - `DEAL_CLOCK_PHONE`: your number (digits, spaces, `+ ( ) - .`). | |
| 110 | - `DEAL_CLOCK_EMAIL`: your email address. | |
| 111 | ||
| 112 | They show in the header (the phone and email are tap-to-call and | |
| 113 | tap-to-write), on the client timeline you hand to buyers and sellers, and in | |
| 114 | the terminal. Every new reminder draft ends with your name and brokerage, then | |
| 115 | your phone and email, so a party can call or write back straight from it. | |
| 116 | Reminders you already sent keep the words you approved. A phone or email that | |
| 117 | does not look right is ignored in favour of the sample, with a line in the log. | |
| 118 | ||
| 102 | 119 | ## What is real, and what is not yet |
| 103 | 120 | |
| 104 | 121 | - **Real:** the dates and their math, mark done, moves with their reasons, |
docs/TECHNICAL.md +5 −3
| @@ -6,9 +6,11 @@ everything technical, and `AGENTS.md` says how to add to it. | ||
| 6 | 6 | |
| 7 | 7 | ## Settings |
| 8 | 8 | |
| 9 | The name and brokerage in the header come from two settings | |
| 10 | (Settings → App → Environment): `DEAL_CLOCK_AGENT` and | |
| 11 | `DEAL_CLOCK_BROKERAGE`. Dates follow the server's time zone (`TZ`). | |
| 9 | The agent in the header, the client timeline and every reminder's sign-off | |
| 10 | comes from four settings (Settings → App → Environment): `DEAL_CLOCK_AGENT`, | |
| 11 | `DEAL_CLOCK_BROKERAGE`, `DEAL_CLOCK_PHONE` (digits, spaces, `+ ( ) - .`, at | |
| 12 | most 30 characters) and `DEAL_CLOCK_EMAIL` (one `@`, at most 254). A bad phone | |
| 13 | or email falls back to the sample with one line in the log. Dates follow the server's time zone (`TZ`). | |
| 12 | 14 | |
| 13 | 15 | ## Running it, the API, MCP and the terminal |
| 14 | 16 |
src/deals.test.ts +1 −1
| @@ -35,7 +35,7 @@ const db = openDb(mkdtempSync(join(tmpdir(), "app-deals-"))); | ||
| 35 | 35 | const anon: Who = { role: "anon" }; |
| 36 | 36 | const alice: Who = { role: "user", id: "u1", name: "alice" }; |
| 37 | 37 | const bob: Who = { role: "user", id: "u2", name: "bob" }; |
| 38 | const agent = { name: "Dana Whitfield", brokerage: "Harbor & Pine Realty" }; | |
| 38 | const agent = { name: "Dana Whitfield", brokerage: "Harbor & Pine Realty", phone: "(555) 010-0142", email: "[email protected]" }; | |
| 39 | 39 | |
| 40 | 40 | const open = (over: Record<string, unknown> = {}): DealView => { |
| 41 | 41 | const made = createDeal(db, alice, { |
src/env.ts +17
| @@ -30,8 +30,25 @@ export const publicOrigin: string = new URL( | ||
| 30 | 30 | export const forgeUrl: string | undefined = process.env.FORGE_URL; |
| 31 | 31 | /** The key the forge signs identities with (`who.ts`). Unset, everyone is anonymous. */ |
| 32 | 32 | export const identityKey: string = process.env.FORGE_APP_IDENTITY_KEY ?? ""; |
| 33 | /** The checks a phone and an email setting pass at boot. */ | |
| 34 | export const PHONE_PATTERN = /^[0-9 +().-]{1,30}$/; | |
| 35 | export const validPhone = (v: string): boolean => PHONE_PATTERN.test(v) && /\d/.test(v); | |
| 36 | export const validEmail = (v: string): boolean => | |
| 37 | v.length <= 254 && /^[A-Za-z0-9._+-]+@[A-Za-z0-9.-]+$/.test(v); | |
outdated
This regex lets |
||
| 38 | ||
| 39 | /** A setting that fails its check falls back to the sample, with one line in the log. */ | |
| 40 | function setting(name: string, fallback: string, ok: (v: string) => boolean): string { | |
| 41 | const v = (process.env[name] ?? "").trim(); | |
| 42 | if (v === "") return fallback; | |
| 43 | if (ok(v)) return v; | |
| 44 | console.warn(`${name} is not valid; using the sample value`); | |
| 45 | return fallback; | |
| 46 | } | |
| 47 | ||
| 33 | 48 | /** Whose deals these are: the agent and brokerage the header and every reminder name. */ |
| 34 | 49 | export const agent = { |
| 35 | 50 | name: process.env.DEAL_CLOCK_AGENT || "Dana Whitfield", |
| 36 | 51 | brokerage: process.env.DEAL_CLOCK_BROKERAGE || "Harbor & Pine Realty", |
| 52 | phone: setting("DEAL_CLOCK_PHONE", "(555) 010-0142", validPhone), | |
| 53 | email: setting("DEAL_CLOCK_EMAIL", "[email protected]", validEmail), | |
| 37 | 54 | } as const; |
src/pages/contact.ts added +7
| @@ -0,0 +1,7 @@ | ||
| 1 | /** The agent's phone and email as tap-to-call and tap-to-write links, escaped. */ | |
| 2 | ||
| 3 | import type { Agent } from "../reminders.ts"; | |
| 4 | import { escape } from "../http.ts"; | |
| 5 | ||
| 6 | export const contactLinks = (agent: Agent): string => | |
| 7 | `<a href="tel:${escape(agent.phone.replace(/[^0-9+]/g, ""))}">${escape(agent.phone)}</a> · <a href="mailto:${escape(agent.email)}">${escape(agent.email)}</a>`; |
src/pages/layout.ts +2
| @@ -16,6 +16,7 @@ import { | ||
| 16 | 16 | where, |
| 17 | 17 | } from "../env.ts"; |
| 18 | 18 | import { asset, escape } from "../http.ts"; |
| 19 | import { contactLinks } from "./contact.ts"; | |
| 19 | 20 | import { token, tokensHref } from "../tokens.ts"; |
| 20 | 21 | import type { Who } from "../who.ts"; |
| 21 | 22 | |
| @@ -68,6 +69,7 @@ ${plain || input.live === false ? "" : `<script type="module" src="${asset("live | ||
| 68 | 69 | <span class="brand-mark" aria-hidden="true"></span> |
| 69 | 70 | <span><b>${escape(agent.name)}</b><small>${escape(agent.brokerage)}</small></span> |
| 70 | 71 | </a> |
outdated
This tel/mailto markup is duplicated in |
||
| 72 | <p class="agent-contact">${contactLinks(agent)}</p> | |
| 71 | 73 | ${ |
| 72 | 74 | plain |
| 73 | 75 | ? "" |
src/pages/timeline.ts +2
| @@ -10,6 +10,7 @@ import { agent } from "../env.ts"; | ||
| 10 | 10 | import { escape } from "../http.ts"; |
| 11 | 11 | import { timelineRows } from "../timeline.ts"; |
| 12 | 12 | import type { Who } from "../who.ts"; |
| 13 | import { contactLinks } from "./contact.ts"; | |
| 13 | 14 | import { layout } from "./layout.ts"; |
| 14 | 15 | |
| 15 | 16 | export function timelinePage(input: { who: Who; deal: DealView; on: string }): string { |
| @@ -29,6 +30,7 @@ export function timelinePage(input: { who: Who; deal: DealView; on: string }): s | ||
| 29 | 30 | <section class="timeline"> |
| 30 | 31 | <h1>${escape(deal.address)}</h1> |
| 31 | 32 | <p class="summary">Key dates, prepared by ${escape(agent.name)}, ${escape(agent.brokerage)}</p> |
| 33 | <p class="summary">${contactLinks(agent)}</p> | |
| 32 | 34 | <ol class="timeline-list">${rows}</ol> |
| 33 | 35 | </section>`; |
| 34 | 36 | return layout({ body, who, path, heading: `Timeline · ${deal.address}`, plain: true, bodyClass: "timeline-page" }); |
src/reminders.ts +8 −2
| @@ -14,8 +14,14 @@ import type { DealView, DeadlineView, Moment, Party } from "./deals.ts"; | ||
| 14 | 14 | export interface Agent { |
| 15 | 15 | readonly name: string; |
| 16 | 16 | readonly brokerage: string; |
| 17 | readonly phone: string; | |
| 18 | readonly email: string; | |
| 17 | 19 | } |
| 18 | 20 | |
| 21 | /** How every draft ends: who to call or write back. */ | |
| 22 | export const signOff = (agent: Agent): string => | |
| 23 | `${agent.name}, ${agent.brokerage}\n${agent.phone} · ${agent.email}`; | |
| 24 | ||
| 19 | 25 | export interface Draft { |
| 20 | 26 | readonly deal_id: number; |
| 21 | 27 | readonly address: string; |
| @@ -71,7 +77,7 @@ function words( | ||
| 71 | 77 | if (moment === "late") { |
| 72 | 78 | return { |
| 73 | 79 | subject: `${deadline.label} — ${deal.address} — overdue`, |
| 74 | body: `Hi ${first(party.name)}, the ${deadline.label.toLowerCase()} for ${deal.address} was due ${spoken(deadline.due)} and has passed without being marked done. ${owed}Could you send me an update today on where it stands and when it will be done?\n\n${agent.name}, ${agent.brokerage}`, | |
| 80 | body: `Hi ${first(party.name)}, the ${deadline.label.toLowerCase()} for ${deal.address} was due ${spoken(deadline.due)} and has passed without being marked done. ${owed}Could you send me an update today on where it stands and when it will be done?\n\n${signOff(agent)}`, | |
| 75 | 81 | }; |
| 76 | 82 | } |
| 77 | 83 | const when = moment === "before" ? `in three days, on ${spoken(deadline.due)}` : `today, ${spoken(deadline.due)}`; |
| @@ -81,7 +87,7 @@ function words( | ||
| 81 | 87 | : `${owner === undefined ? PARTY_LABEL[deadline.owes] : owner.name} (${PARTY_LABEL[deadline.owes].toLowerCase()}) is on it; nothing is needed from you unless you hear otherwise.`; |
| 82 | 88 | return { |
| 83 | 89 | subject: `${deadline.label} — ${deal.address} — ${moment === "before" ? spoken(deadline.due) : "today"}`, |
| 84 | body: `Hi ${first(party.name)}, a reminder that the ${deadline.label.toLowerCase()} for ${deal.address} is ${when}. ${owed}${ask}\n\n${agent.name}, ${agent.brokerage}`, | |
| 90 | body: `Hi ${first(party.name)}, a reminder that the ${deadline.label.toLowerCase()} for ${deal.address} is ${when}. ${owed}${ask}\n\n${signOff(agent)}`, | |
| 85 | 91 | }; |
| 86 | 92 | } |
| 87 | 93 |
src/sample.test.ts +1 −1
| @@ -54,7 +54,7 @@ test("the sample deals hold an overdue date with its follow-up waiting", () => { | ||
| 54 | 54 | const alice: Who = { role: "user", id: "u1", name: "alice" }; |
| 55 | 55 | const listed = listDeals(db, alice); |
| 56 | 56 | if (!listed.ok) throw new Error(listed.message); |
| 57 | const agent = { name: "Dana", brokerage: "HP" }; | |
| 57 | const agent = { name: "Dana", brokerage: "HP", phone: "555", email: "[email protected]" }; | |
| 58 | 58 | const late = listed.value.flatMap((d) => drafts(d, agent)).filter((r) => r.moment === "late" && unsent(r)); |
| 59 | 59 | expect(late.length).toBeGreaterThan(0); |
| 60 | 60 | }); |
src/signoff.test.ts added +101
| @@ -0,0 +1,101 @@ | ||
| 1 | /** The agent's sign-off: on every new draft, never on words already approved. */ | |
| 2 | import { expect, test } from "bun:test"; | |
| 3 | import { mkdtempSync } from "node:fs"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { createDeal, getDeal, sendReminder } from "./deals.ts"; | |
| 7 | import { openDb } from "./db.ts"; | |
| 8 | import { validEmail, validPhone } from "./env.ts"; | |
| 9 | import { draftsFor, signOff } from "./reminders.ts"; | |
| 10 | import { timelinePage } from "./pages/timeline.ts"; | |
| 11 | import { terminal } from "./terminal.ts"; | |
| 12 | import type { Who } from "./who.ts"; | |
| 13 | ||
| 14 | const db = openDb(mkdtempSync(join(tmpdir(), "app-signoff-"))); | |
| 15 | const alice: Who = { role: "user", id: "u1", name: "alice" }; | |
| 16 | const dana = { name: "Dana", brokerage: "HP", phone: "(555) 010-0142", email: "[email protected]" }; | |
| 17 | const lee = { name: "Lee", brokerage: "Bay", phone: "+1 555 0199", email: "[email protected]" }; | |
| 18 | ||
| 19 | const made = createDeal(db, alice, { address: "1 Oak", buyer: "Ann Buyer", seller: "Sam Seller", contractDate: "2026-10-01", closingDate: "2026-11-20" }); | |
| 20 | if (!made.ok) throw new Error(made.message); | |
| 21 | const view = () => { | |
| 22 | const got = getDeal(db, alice, { id: made.value.id }); | |
| 23 | if (!got.ok) throw new Error(got.message); | |
| 24 | return got.value; | |
| 25 | }; | |
| 26 | ||
| 27 | test("a draft ends with a two-line sign-off", () => { | |
| 28 | expect(signOff(dana)).toBe("Dana, HP\n(555) 010-0142 · [email protected]"); | |
| 29 | const deal = view(); | |
| 30 | const draft = draftsFor(deal, deal.deadlines[0]!, dana)[0]!; | |
| 31 | expect(draft.body.endsWith("\n\nDana, HP\n(555) 010-0142 · [email protected]")).toBe(true); | |
| 32 | }); | |
| 33 | ||
| 34 | test("a sent reminder keeps its approved words; new drafts take the new agent", () => { | |
| 35 | const deal = view(); | |
| 36 | const deadline = deal.deadlines[0]!; | |
| 37 | const first = draftsFor(deal, deadline, dana)[0]!; | |
| 38 | const ask = { deadlineId: deadline.id, partyId: first.party_id, moment: first.moment, agent: dana }; | |
| 39 | expect(sendReminder(db, alice, ask).ok).toBe(true); | |
| 40 | const after = view(); | |
| 41 | const again = draftsFor(after, deadline, lee).find((d) => d.party_id === first.party_id && d.moment === first.moment)!; | |
| 42 | expect(again.body).toBe(first.body); | |
| 43 | const other = draftsFor(after, deadline, lee).find((d) => d.sent_at === null)!; | |
| 44 | expect(other.body).toContain("[email protected]"); | |
| 45 | expect(other.body).not.toContain("[email protected]"); | |
| 46 | }); | |
| 47 | ||
| 48 | test("the settings are checked at the boundary", () => { | |
| 49 | expect(validPhone("+1 (555) 010-0142")).toBe(true); | |
| 50 | expect(validPhone("call me")).toBe(false); | |
| 51 | expect(validPhone("1".repeat(31))).toBe(false); | |
| 52 | expect(validEmail("[email protected]")).toBe(true); | |
| 53 | expect(validEmail("a@@b.co")).toBe(false); | |
| 54 | expect(validEmail("nobody")).toBe(false); | |
| 55 | for (const bad of ["[email protected]?bcc=x", "[email protected]&x=1", "[email protected]#f", "[email protected]"]) expect(validEmail(bad)).toBe(false); | |
| 56 | expect(validEmail(`${"a".repeat(250)}@b.co`)).toBe(false); | |
| 57 | }); | |
| 58 | ||
| 59 | test("a bad phone or email falls back to the sample and logs, never crashes", async () => { | |
| 60 | const proc = Bun.spawn(["bun", "-e", 'import { agent } from "./src/env.ts"; console.log(JSON.stringify(agent))'], { | |
| 61 | env: { ...process.env, DEAL_CLOCK_PHONE: "<script>", DEAL_CLOCK_EMAIL: "x@y@z" }, | |
| 62 | stdout: "pipe", | |
| 63 | stderr: "pipe", | |
| 64 | }); | |
| 65 | const [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]); | |
| 66 | expect(await proc.exited).toBe(0); | |
| 67 | expect(JSON.parse(out).phone).toBe("(555) 010-0142"); | |
| 68 | expect(JSON.parse(out).email).toBe("[email protected]"); | |
| 69 | expect(err.match(/DEAL_CLOCK_/g)?.length).toBe(2); | |
| 70 | }); | |
| 71 | ||
| 72 | test("the client timeline links the phone and email, escaped", () => { | |
| 73 | const html = timelinePage({ who: alice, deal: view(), on: "2026-10-25" }); | |
| 74 | expect(html).toContain('href="tel:5550100142"'); | |
| 75 | expect(html).toContain('href="mailto:[email protected]"'); | |
| 76 | }); | |
| 77 | ||
| 78 | test("the header on every page shows the contact line, linked", async () => { | |
| 79 | const { layout } = await import("./pages/layout.ts"); | |
| 80 | const html = layout({ body: "<p>x</p>", who: alice, path: "/", heading: "x" }); | |
| 81 | expect(html).toContain('class="agent-contact"'); | |
| 82 | expect(html).toContain('href="tel:5550100142"'); | |
| 83 | expect(html).toContain('href="mailto:[email protected]"'); | |
| 84 | }); | |
| 85 | ||
| 86 | test("contactLinks escapes what it is given", async () => { | |
| 87 | const { contactLinks } = await import("./pages/contact.ts"); | |
| 88 | const html = contactLinks({ ...dana, phone: '1"><b>', email: "[email protected]" }); | |
| 89 | expect(html).not.toContain("<b>"); | |
| 90 | }); | |
| 91 | ||
| 92 | test("the terminal header and its client timeline print the phone and email", () => { | |
| 93 | const t = terminal(db, alice, { title: "deal-clock", where: "test", agent: dana, on: () => "2026-10-25" }); | |
| 94 | const strip = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, ""); | |
| 95 | expect(strip(t.screen().join("\n"))).toContain("(555) 010-0142 · [email protected]"); | |
| 96 | t.press("o"); | |
| 97 | t.press("t"); | |
| 98 | const screen = strip(t.screen().join("\n")); | |
| 99 | expect(screen).toContain("Client timeline"); | |
| 100 | expect(screen).toContain("(555) 010-0142 · [email protected]"); | |
| 101 | }); |
src/terminal.test.ts +1 −1
| @@ -14,7 +14,7 @@ import type { Who } from "./who.ts"; | ||
| 14 | 14 | |
| 15 | 15 | const db = openDb(mkdtempSync(join(tmpdir(), "app-terminal-"))); |
| 16 | 16 | const alice: Who = { role: "user", id: "u1", name: "alice" }; |
| 17 | const context = { title: "deal-clock", where: "test", agent: { name: "Dana", brokerage: "HP" } }; | |
| 17 | const context = { title: "deal-clock", where: "test", agent: { name: "Dana", brokerage: "HP", phone: "555", email: "[email protected]" } }; | |
| 18 | 18 | const plain = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, ""); |
| 19 | 19 | const lines = (t: Terminal): string[] => t.screen().map(plain); |
| 20 | 20 | const under = (t: Terminal): string => lines(t).find((l) => l.startsWith("▸")) ?? ""; |
src/terminal.ts +2 −2
| @@ -420,7 +420,7 @@ export function terminal( | ||
| 420 | 420 | const day = on(); |
| 421 | 421 | const all = deals(); |
| 422 | 422 | const lines = [ |
| 423 | `${bold(context.title)} ${context.agent.name}, ${context.agent.brokerage} ${dim(context.where)} ${dim(me.role === "anon" ? "guest" : `${me.name}${me.role === "admin" ? " (admin)" : ""}`)}`, | |
| 423 | `${bold(context.title)} ${context.agent.name}, ${context.agent.brokerage} ${dim(`${context.agent.phone} · ${context.agent.email}`)} ${dim(context.where)} ${dim(me.role === "anon" ? "guest" : `${me.name}${me.role === "admin" ? " (admin)" : ""}`)}`, | |
The header line and the client timeline line printed here have no test. Add terminal tests that assert the phone and email on both screens. |
||
| 424 | 424 | context.ssh === undefined ? dim("The terminal is off.") : dim(`connect: ${context.ssh}`), |
| 425 | 425 | `${spoken(day)} · ${all.length} deals · ${view === "dates" ? bold("[d] dates") : "[d] dates"} · ${view === "week" ? bold("[w] this week") : "[w] this week"} · ${view === "reminders" ? bold("[r] reminders today") : "[r] reminders today"}`, |
| 426 | 426 | "", |
| @@ -468,7 +468,7 @@ export function terminal( | ||
| 468 | 468 | const deal = openDeal(); |
| 469 | 469 | if (deal === undefined) lines.push(dim("That deal is gone.")); |
| 470 | 470 | else { |
| 471 | lines.push(bold(`Client timeline — ${deal.address}`), dim(`${context.agent.name}, ${context.agent.brokerage}`), ""); | |
| 471 | lines.push(bold(`Client timeline — ${deal.address}`), dim(`${context.agent.name}, ${context.agent.brokerage}`), dim(`${context.agent.phone} · ${context.agent.email}`), ""); | |
| 472 | 472 | timelineRows(deal, day).forEach((r) => |
| 473 | 473 | lines.push(` ${tint(r.urgency, `${r.spoken.padEnd(16)} ${r.status.padEnd(9)}`)} ${r.label} · ${r.name === undefined ? r.role : `${r.role}: ${r.name}`}`), |
| 474 | 474 | ); |
src/timeline.test.ts +1 −1
| @@ -64,7 +64,7 @@ test("the print rules are scoped to the timeline page", async () => { | ||
| 64 | 64 | }); |
| 65 | 65 | |
| 66 | 66 | test("the terminal shows the same dates and owners for the open deal, ", () => { |
| 67 | const t = terminal(db, alice, { title: "deal-clock", where: "test", agent: { name: "Dana", brokerage: "HP" }, on: () => "2026-10-25" }); | |
| 67 | const t = terminal(db, alice, { title: "deal-clock", where: "test", agent: { name: "Dana", brokerage: "HP", phone: "555", email: "[email protected]" }, on: () => "2026-10-25" }); | |
| 68 | 68 | const row = (): string => t.screen().join("\n").split("\n").find((l) => l.startsWith("▸")) ?? ""; |
| 69 | 69 | for (let i = 0; i < 300 && !row().includes("HOA review ends"); i++) t.press("j"); |
| 70 | 70 | t.press("o"); |
static/app.css +4
| @@ -27,6 +27,10 @@ body { | ||
| 27 | 27 | gap: var() var(); |
| 28 | 28 | margin-bottom: var(); |
| 29 | 29 | } |
| 30 | .agent-contact { | |
| 31 | margin: 0; | |
| 32 | font-size: var(, 0.875rem); | |
| 33 | } | |
| 30 | 34 | h1, |
| 31 | 35 | h2 { |
| 32 | 36 | margin: 0; |
new above
offline
This doc comment belongs on
agentbelow. Move it, and put the validators under their own comment.