`
+ ]
+ .filter(Boolean)
+ .join("\n")
+}
+
+/** The same letter as plain text, for clients that show the text part. */
+export const renderLetterText = (letter: Letter) =>
+ [
+ letter.salutation,
+ ...letter.paragraphs,
+ letter.cosigned &&
+ [letter.cosigned.lead, ...letter.cosigned.quote]
+ .join("\n\n")
+ .replace(/^(.*)$/gm, line => (line ? `> ${line}` : ">")),
+ letter.signature.join("\n"),
+ letter.footer
+ ]
+ .filter(Boolean)
+ .join("\n\n")
+
+/** The `emails` document for a letter, for the send-email extension. Click and
+ * open tracking are off per message: they would rewrite the links in a letter
+ * to a legislator. */
+export const buildLetterEmail = ({
+ letter,
+ author,
+ fromAddress,
+ to,
+ subjectPrefix,
+ createdAt
+}: {
+ letter: Letter
+ author: string
+ fromAddress: string
+ to: string[]
+ subjectPrefix: string
+ createdAt: unknown
+}) => {
+ const html = renderLetterHtml(letter)
+ return {
+ to,
+ cc: [letter.cc],
+ from: letterFrom(author, fromAddress),
+ replyTo: letter.replyTo,
+ // The extension reads headers from the document, not from `message`.
+ headers: {
+ "X-SMTPAPI": JSON.stringify({
+ category: ["constituent-letters"],
+ filters: {
+ opentrack: { settings: { enable: 0 } },
+ clicktrack: { settings: { enable: 0 } }
+ }
+ })
+ },
+ message: {
+ subject: subjectPrefix + letter.subject,
+ text: renderLetterText(letter),
+ html
+ },
+ createdAt
+ }
+}
diff --git a/functions/src/conferenceLetters/sendLetters.ts b/functions/src/conferenceLetters/sendLetters.ts
new file mode 100644
index 000000000..e18560a99
--- /dev/null
+++ b/functions/src/conferenceLetters/sendLetters.ts
@@ -0,0 +1,207 @@
+import { onSchedule } from "firebase-functions/v2/scheduler"
+import * as logger from "firebase-functions/logger"
+import { Conference } from "../conferences/types"
+import { resolveRecipients } from "../email/recipients"
+import { auth, db, Timestamp } from "../firebase"
+import { timeZone } from "../malegislature"
+import { stateOf } from "../conferenceUpdates/inputEvents"
+import { ConferenceInputEvent } from "../conferenceUpdates/types"
+import { Testimony } from "../testimony/types"
+import { hasLegislators, renderLetter } from "./letter"
+import { buildLetterEmail, dayWindow, SkipReason } from "./letters"
+
+const ALREADY_EXISTS = 6
+const DEFAULT_FROM = "notifications@mapletestimony.org"
+
+type Content = Record | undefined
+
+/** Reads shared by many inputs, fetched once per run. */
+const cached = (read: (key: string) => Promise) => {
+ const seen = new Map>()
+ return (key: string) => {
+ if (!seen.has(key)) seen.set(key, read(key))
+ return seen.get(key)!
+ }
+}
+
+const verifiedEmail = async (uid: string) => {
+ try {
+ const user = await auth.getUser(uid)
+ return user.emailVerified && user.email ? user.email : undefined
+ } catch (e) {
+ logger.warn(`No auth user ${uid}`, e)
+ return undefined
+ }
+}
+
+const create = async (
+ ref: FirebaseFirestore.DocumentReference,
+ data: object
+) => {
+ try {
+ await ref.create(data)
+ return true
+ } catch (e) {
+ if ((e as { code?: number }).code !== ALREADY_EXISTS) throw e
+ return false
+ }
+}
+
+const readerAuthor = (t: Testimony) => t.fullName ?? t.authorDisplayName
+
+/** The letter for one input, or why it is not sent. */
+async function prepare(
+ e: ConferenceInputEvent,
+ eventId: string,
+ lastFor: Map,
+ memberContent: (key: string) => Promise,
+ conferenceOf: (key: string) => Promise
+): Promise<{ skip: SkipReason } | { email: object }> {
+ // An input withdrawn and posted again in the window has two "added" events;
+ // only the last is mailed, with what is posted now.
+ if (lastFor.get(e.testimonyId) !== eventId) return { skip: "superseded" }
+
+ const [pubSnap, readerEmail, draft, conference] = await Promise.all([
+ db.doc(`/users/${e.authorUid}/publishedTestimony/${e.testimonyId}`).get(),
+ verifiedEmail(e.authorUid),
+ db
+ .collection(`/users/${e.authorUid}/draftTestimony`)
+ .where("conferenceId", "==", e.conferenceId)
+ .limit(1)
+ .get(),
+ conferenceOf(`${e.court}/${e.conferenceId}`)
+ ])
+ const pub = pubSnap.data() as Testimony | undefined
+ const state = pub && stateOf(pub)
+ if (!pub || !state) return { skip: "withdrawn" }
+ if (!readerEmail) return { skip: "noVerifiedEmail" }
+ if (!pub.representativeId && !pub.senatorId) return { skip: "noLegislator" }
+ if (!conference) return { skip: "noConference" }
+
+ // Only those who can receive it are written to, so the salutation names
+ // exactly who gets the letter. The member document's own name and district
+ // are used, as in the preview, falling back to the district recorded when
+ // the input was posted.
+ const reachable = await Promise.all(
+ [
+ [pub.representativeId, pub.representativeDistrict],
+ [pub.senatorId, pub.senatorDistrict]
+ ].map(async ([id, recorded]) => {
+ const content = id ? await memberContent(`${e.court}/${id}`) : undefined
+ const email: string | undefined = content?.EmailAddress?.trim()
+ return content?.Name && email
+ ? {
+ email,
+ member: {
+ name: content.Name as string,
+ district: (content.District ?? recorded ?? "") as string
+ }
+ }
+ : undefined
+ })
+ )
+ const [representative, senator] = reachable.map(m => m?.member)
+ if (!hasLegislators({ representative, senator })) {
+ return { skip: "noLegislatorEmail" }
+ }
+
+ let cosign: { author: string; content: string } | undefined
+ if (pub.cosignOfId && pub.cosignOfAuthorUid) {
+ const parent = (
+ await db
+ .doc(
+ `/users/${pub.cosignOfAuthorUid}/publishedTestimony/${pub.cosignOfId}`
+ )
+ .get()
+ ).data() as Testimony | undefined
+ if (!parent) return { skip: "withdrawn" }
+ cosign = { author: readerAuthor(parent), content: parent.content }
+ }
+
+ const author = readerAuthor(pub)
+ const letter = renderLetter({
+ author,
+ replyTo: (draft.docs[0]?.data().replyTo as string)?.trim() || readerEmail,
+ conference: conference.name ?? conference.title,
+ position: state.position,
+ content: pub.content,
+ cosign,
+ representative,
+ senator
+ })
+ const { to, subjectPrefix } = resolveRecipients(
+ reachable.flatMap(m => m?.email ?? [])
+ )
+ if (!to.length) return { skip: "noRecipients" }
+ return {
+ email: buildLetterEmail({
+ letter,
+ author,
+ fromAddress: process.env.LETTER_FROM ?? DEFAULT_FROM,
+ to,
+ subjectPrefix,
+ createdAt: Timestamp.now()
+ })
+ }
+}
+
+/** Mails each conference input added in the day before `now` to the reader's
+ * rep and senator, as the letter the reader previewed. A letter is the
+ * `emails` document /emails/letter_{input event id}, created, so a second run
+ * sends nothing again. An input that is not mailed is recorded, with why, at
+ * /conferenceLetterSkips/{input event id}. */
+export async function sendConferenceLetters(now = new Date()) {
+ const { start, end } = dayWindow(now)
+ const events = await db
+ .collection("/conferenceInputEvents")
+ .where("at", ">=", Timestamp.fromDate(start.toJSDate()))
+ .where("at", "<", Timestamp.fromDate(end.toJSDate()))
+ .get()
+
+ const added = events.docs
+ .map(doc => ({ id: doc.id, e: doc.data() as ConferenceInputEvent }))
+ .filter(({ e }) => e.change === "added")
+ .sort((a, b) => a.e.at.toMillis() - b.e.at.toMillis())
+ const lastFor = new Map(added.map(({ id, e }) => [e.testimonyId, id]))
+ const memberContent = cached(
+ async key =>
+ (
+ await db.doc(`/generalCourts/${key.replace("/", "/members/")}`).get()
+ ).data()?.content as Content
+ )
+ const conferenceOf = cached(
+ async key =>
+ (
+ await db
+ .doc(`/generalCourts/${key.replace("/", "/conferences/")}`)
+ .get()
+ ).data() as Conference | undefined
+ )
+
+ let sent = 0
+ for (const { id, e } of added) {
+ try {
+ const result = await prepare(e, id, lastFor, memberContent, conferenceOf)
+ if ("skip" in result) {
+ await create(db.doc(`/conferenceLetterSkips/${id}`), {
+ testimonyId: e.testimonyId,
+ authorUid: e.authorUid,
+ conferenceId: e.conferenceId,
+ reason: result.skip,
+ createdAt: Timestamp.now()
+ })
+ } else if (await create(db.doc(`/emails/letter_${id}`), result.email)) {
+ sent++
+ }
+ } catch (err) {
+ logger.error(`Letter for input event ${id} failed`, err)
+ }
+ }
+ logger.info(`Mailed ${sent} conference letters for ${start.toISODate()}`)
+ return sent
+}
+
+export const mailConferenceLetters = onSchedule(
+ { schedule: "0 9 * * *", timeZone, timeoutSeconds: 300 },
+ () => sendConferenceLetters().then(() => undefined)
+)
diff --git a/functions/src/conferenceUpdates/compileWeeklyUpdates.ts b/functions/src/conferenceUpdates/compileWeeklyUpdates.ts
new file mode 100644
index 000000000..bec39a2cd
--- /dev/null
+++ b/functions/src/conferenceUpdates/compileWeeklyUpdates.ts
@@ -0,0 +1,163 @@
+import { onSchedule } from "firebase-functions/v2/scheduler"
+import * as logger from "firebase-functions/logger"
+import { Conference } from "../conferences/types"
+import { db, Timestamp } from "../firebase"
+import { timeZone } from "../malegislature"
+import { resolveRecipients } from "../email/recipients"
+import { splitMemberName } from "../shared/names"
+import { takesTestimony } from "../shared/conferences"
+import { Testimony } from "../testimony/types"
+import { stateOf } from "./inputEvents"
+import { ConferenceInputEvent, ConferenceUpdate } from "./types"
+import {
+ buildConferenceUpdateEmail,
+ conferenceUpdateSubject,
+ renderConferenceUpdate,
+ renderConferenceUpdateText,
+ summarize,
+ tally,
+ weekWindow
+} from "./weeklyUpdate"
+
+const ALREADY_EXISTS = 6
+const REPLY_TO = "info@mapletestimony.org"
+const DEFAULT_FROM = "notifications@mapletestimony.org"
+
+/** "Sen. Crighton" or "Rep. Peisch", for a header's To line, and the address
+ * the update goes to, if the member document has one. */
+const conferee = async (court: number, c: Conference["conferees"][number]) => {
+ const snap = await db
+ .doc(`/generalCourts/${court}/members/${c.memberCode}`)
+ .get()
+ const name: string | undefined = snap.data()?.content?.Name
+ const email: string | undefined = snap.data()?.content?.EmailAddress?.trim()
+ return {
+ memberCode: c.memberCode,
+ email: email || undefined,
+ name: `${c.branch === "Senate" ? "Sen." : "Rep."} ${
+ name ? splitMemberName(name).surname : c.memberCode
+ }`,
+ chair: c.chair === true
+ }
+}
+
+/** Compiles the update for each appointed conference that had a
+ * change in the week before `now`, and stores it as
+ * /conferenceUpdates/{court}_{conferenceId}_{week start}. Creating it
+ * rather than setting it means a second run in the same week leaves the
+ * first update as it was. */
+export async function compileWeeklyUpdates(now = new Date()) {
+ const { start, end } = weekWindow(now)
+ const events = await db
+ .collection("/conferenceInputEvents")
+ .where("at", ">=", Timestamp.fromDate(start.toJSDate()))
+ .where("at", "<", Timestamp.fromDate(end.toJSDate()))
+ .get()
+
+ const eventsOf = new Map()
+ for (const doc of events.docs) {
+ const e = doc.data() as ConferenceInputEvent
+ const key = `${e.court}/${e.conferenceId}`
+ eventsOf.set(key, [...(eventsOf.get(key) ?? []), e])
+ }
+
+ let stored = 0
+ for (const [key, conferenceEvents] of eventsOf) {
+ const { court, conferenceId: id } = conferenceEvents[0]
+ try {
+ const snap = await db
+ .doc(`/generalCourts/${court}/conferences/${id}`)
+ .get()
+ const conference = snap.data() as Conference | undefined
+ if (!conference || !takesTestimony(conference)) continue
+
+ const published = await db
+ .collectionGroup("publishedTestimony")
+ .where("conferenceId", "==", id)
+ .select("court", "authorRole", "position", "version")
+ .get()
+ const standing = tally(
+ published.docs
+ .map(d => d.data() as Testimony)
+ .filter(t => t.court === court)
+ .flatMap(t => stateOf(t) ?? [])
+ )
+
+ const changes = summarize(conferenceEvents)
+ const conferees = await Promise.all(
+ conference.conferees.map(c => conferee(court, c))
+ )
+ const data = buildConferenceUpdateEmail({
+ conference,
+ conferees,
+ standing,
+ changes,
+ start,
+ now
+ })
+ const html = renderConferenceUpdate(data)
+ const reachable = conferees.filter(c => c.email)
+ const update: ConferenceUpdate = {
+ court,
+ conferenceId: id,
+ weekStart: Timestamp.fromDate(start.toJSDate()),
+ standing,
+ changes,
+ html,
+ delivery: {
+ sentTo: reachable.map(c => c.memberCode),
+ skipped: conferees.filter(c => !c.email).map(c => c.memberCode)
+ },
+ createdAt: Timestamp.now()
+ }
+
+ // One batch, so the update and its email exist together or not at all:
+ // a second run finds the update and sends nothing.
+ const updateRef = db
+ .collection("/conferenceUpdates")
+ .doc(`${court}_${id}_${start.toISODate()}`)
+ const batch = db.batch()
+ batch.create(updateRef, update)
+ const { to, subjectPrefix } = resolveRecipients(
+ reachable.map(c => c.email!)
+ )
+ if (to.length) {
+ batch.create(db.collection("emails").doc(updateRef.id), {
+ to,
+ from: `"MAPLE" <${process.env.CONFEREE_UPDATE_FROM ?? DEFAULT_FROM}>`,
+ replyTo: REPLY_TO,
+ // The extension reads headers from the document, not from `message`.
+ headers: {
+ "X-SMTPAPI": JSON.stringify({ category: ["conferee-update"] })
+ },
+ message: {
+ subject: subjectPrefix + conferenceUpdateSubject(data),
+ text: renderConferenceUpdateText(data),
+ html
+ },
+ createdAt: Timestamp.now()
+ })
+ } else {
+ logger.warn(`No recipients for the update to conference ${key}`)
+ }
+ try {
+ await batch.commit()
+ stored++
+ } catch (e) {
+ if ((e as { code?: number }).code !== ALREADY_EXISTS) throw e
+ }
+ } catch (e) {
+ logger.error(`Weekly update for conference ${key} failed`, e)
+ }
+ }
+ logger.info(`Stored ${stored} weekly conference updates`)
+}
+
+export const compileConferenceUpdates = onSchedule(
+ {
+ schedule: "0 8 * * 1", // Monday 8:00 AM
+ timeZone,
+ timeoutSeconds: 300
+ },
+ () => compileWeeklyUpdates()
+)
diff --git a/functions/src/conferenceUpdates/index.ts b/functions/src/conferenceUpdates/index.ts
new file mode 100644
index 000000000..767075aa3
--- /dev/null
+++ b/functions/src/conferenceUpdates/index.ts
@@ -0,0 +1,2 @@
+export { compileConferenceUpdates } from "./compileWeeklyUpdates"
+export { recordConferenceInput } from "./inputEvents"
diff --git a/functions/src/conferenceUpdates/inputEvents.test.ts b/functions/src/conferenceUpdates/inputEvents.test.ts
new file mode 100644
index 000000000..21641a79c
--- /dev/null
+++ b/functions/src/conferenceUpdates/inputEvents.test.ts
@@ -0,0 +1,73 @@
+import { conferenceInputEvent } from "./inputEvents"
+
+const pub = (over: Record = {}) =>
+ ({
+ conferenceId: "c1",
+ court: 194,
+ authorUid: "u1",
+ authorRole: "user",
+ position: "passSenateVersion",
+ version: 1,
+ ...over
+ } as Parameters[0])
+
+const state = (position = "passSenateVersion", version = 1) => ({
+ position,
+ group: "individual",
+ version
+})
+
+describe("conferenceInputEvent", () => {
+ it("records conference input being added", () => {
+ expect(conferenceInputEvent(undefined, pub(), "t1")).toEqual({
+ court: 194,
+ conferenceId: "c1",
+ testimonyId: "t1",
+ authorUid: "u1",
+ change: "added",
+ after: state()
+ })
+ })
+
+ it("records an edit with both sides", () => {
+ expect(
+ conferenceInputEvent(
+ pub(),
+ pub({ version: 2, position: "passNothing" }),
+ "t1"
+ )
+ ).toMatchObject({
+ change: "edited",
+ before: state(),
+ after: state("passNothing", 2)
+ })
+ })
+
+ it("records a deletion as a withdrawal", () => {
+ expect(conferenceInputEvent(pub(), undefined, "t1")).toMatchObject({
+ change: "withdrawn",
+ before: state()
+ })
+ })
+
+ it("ignores a write that keeps the version, such as a cosign tally", () => {
+ expect(
+ conferenceInputEvent(pub(), pub({ cosignCount: 3 }), "t1")
+ ).toBeUndefined()
+ })
+
+ it("ignores testimony that is not conference input", () => {
+ const bill = pub({ conferenceId: undefined, position: "endorse" })
+ expect(conferenceInputEvent(undefined, bill, "t1")).toBeUndefined()
+ expect(conferenceInputEvent(bill, undefined, "t1")).toBeUndefined()
+ })
+
+ it("groups authors as the site does", () => {
+ const group = (authorRole: string) =>
+ conferenceInputEvent(undefined, pub({ authorRole }), "t1")?.after?.group
+ expect(group("organization")).toBe("organization")
+ expect(group("legislator")).toBe("government")
+ expect(group("user")).toBe("individual")
+ expect(group("admin")).toBe("individual")
+ })
+})
diff --git a/functions/src/conferenceUpdates/inputEvents.ts b/functions/src/conferenceUpdates/inputEvents.ts
new file mode 100644
index 000000000..4e13d6e83
--- /dev/null
+++ b/functions/src/conferenceUpdates/inputEvents.ts
@@ -0,0 +1,68 @@
+import { onDocumentWritten } from "firebase-functions/v2/firestore"
+import { db, Timestamp } from "../firebase"
+import { ConferencePosition, Testimony } from "../testimony/types"
+import { authorGroupOf, ConferenceInputEvent, InputState } from "./types"
+
+type Publication = Pick<
+ Testimony,
+ "conferenceId" | "court" | "authorUid" | "authorRole" | "position" | "version"
+>
+
+export const stateOf = (t: Publication): InputState | undefined =>
+ ConferencePosition.guard(t.position)
+ ? {
+ position: t.position,
+ group: authorGroupOf(t.authorRole),
+ version: t.version
+ }
+ : undefined
+
+/** What a write to a publication means for the weekly update, or nothing.
+ * Only conference input counts, so a write to anything else has no event. A write
+ * that keeps the version, such as the cosign tally's, is not an edit. */
+export function conferenceInputEvent(
+ before: Publication | undefined,
+ after: Publication | undefined,
+ testimonyId: string
+): Omit | undefined {
+ const current = after ?? before
+ if (!current?.conferenceId) return undefined
+ const b = before && stateOf(before)
+ const a = after && stateOf(after)
+ if (!b && !a) return undefined
+ if (b && a && b.version === a.version) return undefined
+ return {
+ court: current.court,
+ conferenceId: current.conferenceId,
+ testimonyId,
+ authorUid: current.authorUid,
+ change: !b ? "added" : !a ? "withdrawn" : "edited",
+ ...(b && { before: b }),
+ ...(a && { after: a })
+ }
+}
+
+/** Records each change to conference input, for the weekly update to
+ * read. The event's id is the trigger event's, so a retry writes the same
+ * document. */
+export const recordConferenceInput = onDocumentWritten(
+ {
+ document: "/users/{userId}/publishedTestimony/{testimonyId}",
+ timeoutSeconds: 30,
+ retry: true
+ },
+ async event => {
+ const change = event.data
+ if (!change) return
+ const body = conferenceInputEvent(
+ change.before.data() as Publication | undefined,
+ change.after.data() as Publication | undefined,
+ event.params.testimonyId
+ )
+ if (!body) return
+ await db
+ .collection("/conferenceInputEvents")
+ .doc(event.id)
+ .set({ ...body, at: Timestamp.fromDate(new Date(event.time)) })
+ }
+)
diff --git a/functions/src/conferenceUpdates/types.ts b/functions/src/conferenceUpdates/types.ts
new file mode 100644
index 000000000..a47433450
--- /dev/null
+++ b/functions/src/conferenceUpdates/types.ts
@@ -0,0 +1,107 @@
+import {
+ InstanceOf,
+ Literal as L,
+ Array,
+ Number,
+ Optional,
+ Record,
+ Static,
+ String,
+ Union
+} from "runtypes"
+import { Role } from "../auth/types"
+import { Timestamp } from "../firebase"
+import { ConferencePosition } from "../testimony/types"
+
+/** The site's three kinds of author, as Public Input groups them. Mirrors
+ * `accountTypeOf` in components/conference/input/accounts.ts. */
+export type AuthorGroup = Static
+export const AuthorGroup = Union(
+ L("individual"),
+ L("organization"),
+ L("government")
+)
+export const authorGroups = AuthorGroup.alternatives.map(a => a.value)
+
+export const authorGroupOf = (role: Role): AuthorGroup =>
+ role === "organization"
+ ? "organization"
+ : role === "legislator"
+ ? "government"
+ : "individual"
+
+/** How many inputs, in all and by author group and position. In a change it
+ * is a signed difference. */
+export type Counts = Static
+export const Counts = Record({
+ total: Number,
+ byGroup: Record({
+ individual: Number,
+ organization: Number,
+ government: Number
+ }),
+ byPosition: Record({
+ passSomething: Number,
+ passSenateVersion: Number,
+ passHouseVersion: Number,
+ passNothing: Number
+ })
+})
+
+/** What a publication contributes to the update: the figures it is counted
+ * under. */
+export type InputState = Static
+export const InputState = Record({
+ position: ConferencePosition,
+ group: AuthorGroup,
+ version: Number
+})
+
+/** One conference input appearing, changing or going. Written by
+ * `recordConferenceInput`; the weekly update reads a week of them.
+ * Firestore: /conferenceInputEvents/{eventId} */
+export type ConferenceInputEvent = Static
+export const ConferenceInputEvent = Record({
+ court: Number,
+ conferenceId: String,
+ testimonyId: String,
+ authorUid: String,
+ change: Union(L("added"), L("edited"), L("withdrawn")),
+ before: Optional(InputState),
+ after: Optional(InputState),
+ at: InstanceOf(Timestamp)
+})
+
+/** What changed in a week, as the update says it. `net` is the resulting
+ * difference in the counts. */
+export type Changes = Static
+export const Changes = Record({
+ added: Number,
+ edited: Number,
+ withdrawn: Number,
+ net: Counts
+})
+
+/** Who an update was sent to, by member code. Skipped conferees have no
+ * email address on their member document. */
+export type Delivery = Static
+export const Delivery = Record({
+ sentTo: Array(String),
+ skipped: Array(String)
+})
+
+/** One conference's update for one week, stored so it can be sent.
+ * Firestore: /conferenceUpdates/{court}_{conferenceId}_{weekStart date} */
+export type ConferenceUpdate = Static
+export const ConferenceUpdate = Record({
+ court: Number,
+ conferenceId: String,
+ /** Monday 00:00, Eastern. The week runs to the next Monday. */
+ weekStart: InstanceOf(Timestamp),
+ /** The input on the conference when the update was compiled. */
+ standing: Counts,
+ changes: Changes,
+ html: String,
+ delivery: Delivery,
+ createdAt: InstanceOf(Timestamp)
+})
diff --git a/functions/src/conferenceUpdates/weeklyUpdate.test.ts b/functions/src/conferenceUpdates/weeklyUpdate.test.ts
new file mode 100644
index 000000000..62f8a66ff
--- /dev/null
+++ b/functions/src/conferenceUpdates/weeklyUpdate.test.ts
@@ -0,0 +1,192 @@
+import {
+ buildConferenceUpdateEmail,
+ conferenceUpdateSubject,
+ renderConferenceUpdate,
+ renderConferenceUpdateText,
+ summarize,
+ tally,
+ weekWindow
+} from "./weeklyUpdate"
+import { InputState } from "./types"
+
+const state = (over: Partial = {}): InputState => ({
+ position: "passSenateVersion",
+ group: "individual",
+ version: 1,
+ ...over
+})
+
+describe("weekWindow", () => {
+ it("is the Monday-to-Sunday week before the Monday on or before now", () => {
+ // Monday Sept 28, 2026, 8am Eastern
+ const { start, end } = weekWindow(new Date("2026-09-28T12:00:00Z"))
+ expect(start.toISODate()).toBe("2026-09-21")
+ expect(end.toISODate()).toBe("2026-09-28")
+ expect(end.toISO()).toContain("T00:00:00.000-04:00")
+ })
+
+ it("still ends on the Monday midday through the next Sunday", () => {
+ const { end } = weekWindow(new Date("2026-10-04T23:00:00Z"))
+ expect(end.toISODate()).toBe("2026-09-28")
+ })
+
+ it("keeps Monday midnight across the autumn clock change", () => {
+ const { start, end } = weekWindow(new Date("2026-11-02T15:00:00Z"))
+ expect(start.toISO()).toBe("2026-10-26T00:00:00.000-04:00")
+ expect(end.toISO()).toBe("2026-11-02T00:00:00.000-05:00")
+ })
+})
+
+describe("tally", () => {
+ it("counts input by group and position", () => {
+ const counts = tally([
+ state(),
+ state({ group: "organization", position: "passNothing" })
+ ])
+ expect(counts).toEqual({
+ total: 2,
+ byGroup: { individual: 1, organization: 1, government: 0 },
+ byPosition: {
+ passSomething: 0,
+ passSenateVersion: 1,
+ passHouseVersion: 0,
+ passNothing: 1
+ }
+ })
+ })
+})
+
+describe("summarize", () => {
+ it("adds new input", () => {
+ const c = summarize([
+ { after: state() },
+ { after: state({ group: "government" }) }
+ ])
+ expect(c).toMatchObject({ added: 2, edited: 0, withdrawn: 0 })
+ expect(c.net.total).toBe(2)
+ expect(c.net.byGroup).toEqual({
+ individual: 1,
+ organization: 0,
+ government: 1
+ })
+ })
+
+ it("moves an edit between positions without changing the total", () => {
+ const c = summarize([
+ {
+ before: state(),
+ after: state({ position: "passNothing", version: 2 })
+ }
+ ])
+ expect(c).toMatchObject({ added: 0, edited: 1 })
+ expect(c.net.total).toBe(0)
+ expect(c.net.byPosition).toMatchObject({
+ passSenateVersion: -1,
+ passNothing: 1
+ })
+ })
+
+ it("lowers the counts for a withdrawal", () => {
+ const c = summarize([{ before: state({ group: "organization" }) }])
+ expect(c).toMatchObject({ withdrawn: 1, edited: 0, added: 0 })
+ expect(c.net.total).toBe(-1)
+ expect(c.net.byGroup).toMatchObject({ organization: -1 })
+ })
+
+ it("is empty for no events", () => {
+ expect(summarize([])).toMatchObject({
+ added: 0,
+ edited: 0,
+ withdrawn: 0,
+ net: { total: 0 }
+ })
+ })
+})
+
+describe("the update email", () => {
+ const conference = {
+ court: 194,
+ id: "phone-free-schools",
+ title: "An Act relative to phones in schools",
+ name: "Phone-Free Schools",
+ senateBillId: "S2581",
+ houseBillId: "H5366"
+ }
+ const standing = tally([
+ state(),
+ state(),
+ state({ position: "passNothing", group: "organization" })
+ ])
+ const changes = summarize([
+ { after: state() },
+ { after: state({ position: "passNothing", group: "organization" }) }
+ ])
+ const data = buildConferenceUpdateEmail({
+ conference,
+ conferees: [
+ { name: "Sen. Crighton", chair: true },
+ { name: "Rep. Peisch", chair: false }
+ ],
+ standing,
+ changes,
+ start: weekWindow(new Date("2026-09-28T12:00:00Z")).start,
+ now: new Date("2026-09-28T12:00:00Z")
+ })
+
+ it("names the conference and the week in its subject", () => {
+ expect(conferenceUpdateSubject(data)).toBe(
+ `Public input on Phone-Free Schools: ${data.weekLabel}`
+ )
+ })
+
+ it("states the week, the bills and the figures", () => {
+ expect(data).toMatchObject({
+ bills: "S.2581 / H.5366",
+ weekLabel: "September 21–27, 2026",
+ sentLabel: "Monday, September 28, 2026",
+ total: 3,
+ totalDelta: "▲ 2"
+ })
+ expect(data.groups.map(g => [g.label, g.count, g.delta])).toEqual([
+ ["Individuals", 2, "▲ 1"],
+ ["Organizations", 1, "▲ 1"],
+ ["Government offices", 0, "—"]
+ ])
+ expect(data.changes).toContain("2 inputs added.")
+ expect(data.changes).toContain("Counted input went from 1 to 3.")
+ expect(data.changes).toContain("Don't pass anything: 0 → 1.")
+ })
+
+ it("renders the conferees, figures and a link to the page", () => {
+ const html = renderConferenceUpdate(data)
+ expect(html).toContain("Sen. Crighton (chair), Rep. Peisch")
+ expect(html).toContain("S.2581 / H.5366 — Phone-Free Schools")
+ expect(html).toContain(
+ 'href="https://mapletestimony.org/conferences/194/phone-free-schools"'
+ )
+ expect(html).toContain("Pass the Senate version")
+ expect(html).toContain("info@mapletestimony.org")
+ })
+
+ it("leaves out unsubscribing and the open questions", () => {
+ const html = renderConferenceUpdate(data).toLowerCase()
+ expect(html).not.toContain("unsubscribe")
+ expect(html).not.toContain("open questions")
+ })
+
+ it("says the same in its text part, a line per figure", () => {
+ const text = renderConferenceUpdateText(data)
+ expect(text).toContain("To: Sen. Crighton (chair), Rep. Peisch\n")
+ expect(text).toContain(
+ "Total testimonies: 3 (▲ 2 this week)\nIndividuals: 2 (▲ 1)\n"
+ )
+ expect(text).toContain("- 2 inputs added.\n")
+ expect(text).toContain(
+ "https://mapletestimony.org/conferences/194/phone-free-schools"
+ )
+ })
+
+ it("links the page without saying how many it holds", () => {
+ expect(renderConferenceUpdate(data)).not.toMatch(/Read all \d+/)
+ })
+})
diff --git a/functions/src/conferenceUpdates/weeklyUpdate.ts b/functions/src/conferenceUpdates/weeklyUpdate.ts
new file mode 100644
index 000000000..b75854d34
--- /dev/null
+++ b/functions/src/conferenceUpdates/weeklyUpdate.ts
@@ -0,0 +1,215 @@
+import * as fs from "fs"
+import * as handlebars from "handlebars"
+import { DateTime } from "luxon"
+import * as path from "path"
+import { Conference } from "../conferences/types"
+import { timeZone } from "../malegislature"
+import { ConferenceUpdateEmail } from "../notifications/emailTypes"
+import { CONFERENCE_STANCES } from "../shared/conferences"
+import { ConferencePosition } from "../testimony/types"
+import {
+ AuthorGroup,
+ authorGroups,
+ Changes,
+ ConferenceInputEvent,
+ Counts,
+ InputState
+} from "./types"
+
+const EMAIL_TEMPLATE_PATH = "../email/conferenceUpdateEmail.handlebars"
+
+/** The order the mockup lists them in. */
+const POSITION_ORDER: ConferencePosition[] = [
+ "passSenateVersion",
+ "passHouseVersion",
+ "passSomething",
+ "passNothing"
+]
+const POSITION_COLORS: Record = {
+ passSenateVersion: "#1A3185",
+ passHouseVersion: "#5B6FB8",
+ passSomething: "#1F7A4D",
+ passNothing: "#C71E32"
+}
+const GROUPS: Record = {
+ individual: "Individuals",
+ organization: "Organizations",
+ government: "Government offices"
+}
+
+/** The Monday-to-Sunday week, Eastern, that ended at the Monday on or before
+ * `now`. `end` is exclusive. */
+export function weekWindow(now: Date) {
+ const end = DateTime.fromJSDate(now, { zone: timeZone }).startOf("week")
+ return { start: end.minus({ weeks: 1 }), end }
+}
+
+const emptyCounts = (): Counts => ({
+ total: 0,
+ byGroup: { individual: 0, organization: 0, government: 0 },
+ byPosition: {
+ passSomething: 0,
+ passSenateVersion: 0,
+ passHouseVersion: 0,
+ passNothing: 0
+ }
+})
+
+const add = (counts: Counts, state: InputState | undefined, sign: 1 | -1) => {
+ if (!state) return
+ counts.total += sign
+ counts.byGroup[state.group] += sign
+ counts.byPosition[state.position] += sign
+}
+
+/** The counts for a conference's input. */
+export function tally(states: InputState[]): Counts {
+ const counts = emptyCounts()
+ states.forEach(s => add(counts, s, 1))
+ return counts
+}
+
+/** What a week's events add up to. Each event is input appearing
+ * (`added`), edited, or deleted (`withdrawn`). */
+export function summarize(
+ events: Pick[]
+): Changes {
+ const changes: Changes = {
+ added: 0,
+ edited: 0,
+ withdrawn: 0,
+ net: emptyCounts()
+ }
+ for (const { before, after } of events) {
+ add(changes.net, before, -1)
+ add(changes.net, after, 1)
+ if (!before) changes.added++
+ else if (after) changes.edited++
+ else changes.withdrawn++
+ }
+ return changes
+}
+
+const delta = (n: number) => (n > 0 ? `▲ ${n}` : n < 0 ? `▼ ${-n}` : "—")
+const plural = (n: number, one: string, many = `${one}s`) =>
+ `${n} ${n === 1 ? one : many}`
+
+const billLabel = (id: string) => id.replace(/^([A-Za-z]+)(\d+)$/, "$1.$2")
+
+const formatWeek = (start: DateTime) => {
+ const last = start.plus({ days: 6 })
+ return start.month === last.month
+ ? `${start.toFormat("LLLL d")}–${last.toFormat("d, yyyy")}`
+ : `${start.toFormat("LLLL d")} – ${last.toFormat("LLLL d, yyyy")}`
+}
+
+/** What the template shows. `before` is the standing at the start of the
+ * week, which is the standing now less the week's net change. */
+export function buildConferenceUpdateEmail({
+ conference,
+ conferees,
+ standing,
+ changes,
+ start,
+ now
+}: {
+ conference: Pick<
+ Conference,
+ "court" | "id" | "title" | "name" | "senateBillId" | "houseBillId"
+ >
+ conferees: { name: string; chair: boolean }[]
+ standing: Counts
+ changes: Changes
+ start: DateTime
+ now: Date
+}): ConferenceUpdateEmail {
+ const { net } = changes
+ const total = standing.total
+ const bar = POSITION_ORDER.filter(p => standing.byPosition[p] > 0)
+
+ const lines: string[] = []
+ if (changes.added) lines.push(`${plural(changes.added, "input")} added.`)
+ if (changes.edited) lines.push(`${plural(changes.edited, "input")} edited.`)
+ if (changes.withdrawn)
+ lines.push(`${plural(changes.withdrawn, "input")} withdrawn.`)
+ if (net.total)
+ lines.push(`Counted input went from ${total - net.total} to ${total}.`)
+ for (const p of POSITION_ORDER)
+ if (net.byPosition[p])
+ lines.push(
+ `${CONFERENCE_STANCES[p]}: ${
+ standing.byPosition[p] - net.byPosition[p]
+ } → ${standing.byPosition[p]}.`
+ )
+
+ return {
+ bills: `${billLabel(conference.senateBillId)} / ${billLabel(
+ conference.houseBillId
+ )}`,
+ title: conference.name ?? conference.title,
+ conferenceUrl: `https://mapletestimony.org/conferences/${conference.court}/${conference.id}`,
+ weekLabel: formatWeek(start),
+ sentLabel: DateTime.fromJSDate(now, { zone: timeZone }).toFormat(
+ "cccc, LLLL d, yyyy"
+ ),
+ conferees,
+ total,
+ totalDelta: delta(net.total),
+ groups: authorGroups.map(g => ({
+ label: GROUPS[g],
+ count: standing.byGroup[g],
+ delta: delta(net.byGroup[g])
+ })),
+ positions: bar.map(p => ({
+ label: CONFERENCE_STANCES[p],
+ count: standing.byPosition[p],
+ delta: delta(net.byPosition[p]),
+ width: Math.max(1, Math.round((standing.byPosition[p] / total) * 100)),
+ color: POSITION_COLORS[p]
+ })),
+ changes: lines
+ }
+}
+
+export const conferenceUpdateSubject = ({
+ title,
+ weekLabel
+}: Pick) =>
+ `Public input on ${title}: ${weekLabel}`
+
+let template: HandlebarsTemplateDelegate | undefined
+
+export const renderConferenceUpdate = (data: ConferenceUpdateEmail) =>
+ (template ??= handlebars.compile(
+ fs.readFileSync(path.join(__dirname, EMAIL_TEMPLATE_PATH), "utf8")
+ ))(data)
+
+/** The same update as plain text, section by section as the template. */
+export const renderConferenceUpdateText = (d: ConferenceUpdateEmail) =>
+ [
+ [
+ `To: ${d.conferees
+ .map(c => (c.chair ? `${c.name} (chair)` : c.name))
+ .join(", ")}`,
+ `Re: ${d.bills} — ${d.title} — conference committee`,
+ `Week of: ${d.weekLabel} · Sent: ${d.sentLabel}`
+ ].join("\n"),
+ `Public input on ${d.title}: where it stands, and what changed this week`,
+ "One summary a week from MAPLE, in place of individual emails. Everything here is drawn from testimony submitted publicly on MAPLE whose authors chose to share it with the committee.",
+ [
+ "1 · Where input stands",
+ `Total testimonies: ${d.total} (${d.totalDelta} this week)`,
+ ...d.groups.map(g => `${g.label}: ${g.count} (${g.delta})`),
+ "",
+ "Position on the bills",
+ ...d.positions.map(p => `${p.label}: ${p.count} (${p.delta})`)
+ ].join("\n"),
+ ["2 · What changed this week", ...d.changes.map(c => `- ${c}`)].join("\n"),
+ [
+ "3 · Read the testimony",
+ "Every submission is public on MAPLE with the author's stated position. Nothing in this summary is paraphrased from private input.",
+ d.conferenceUrl
+ ].join("\n"),
+ "How this is compiled. Counts and positions are from testimony submitted on MAPLE. Positions are the authors' own, not MAPLE's view.",
+ "MAPLE is nonpartisan infrastructure and takes no position on this or any bill. Questions, or a reply to this email: info@mapletestimony.org."
+ ].join("\n\n")
diff --git a/functions/src/email/conferenceUpdateEmail.handlebars b/functions/src/email/conferenceUpdateEmail.handlebars
new file mode 100644
index 000000000..ce9580c62
--- /dev/null
+++ b/functions/src/email/conferenceUpdateEmail.handlebars
@@ -0,0 +1,77 @@
+
+
+
+ Weekly update to the conferees
+
+
+
+
+
+
+
+ Weekly update to the conferees
+
+
+
+
+
To: {{#each conferees}}{{name}}{{#if chair}} (chair){{/if}}{{#unless @last}}, {{/unless}}{{/each}}
+
Re: {{bills}} — {{title}} — conference committee
+
Week of: {{weekLabel}} · Sent: {{sentLabel}}
+
+
+
+
+
Public input on {{title}}: where it stands, and what changed this week
+
One summary a week from MAPLE, in place of individual emails. Everything here is drawn from testimony submitted publicly on MAPLE whose authors chose to share it with the committee.