From c43228831d523938e78a6bc8953b741fef53acf2 Mon Sep 17 00:00:00 2001 From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com> Date: Fri, 10 Apr 2026 17:23:54 -0400 Subject: [PATCH] Add unified payment status, ACH auto-clear, and categorized dashboard - processPaymentCsv: switch from BatchWrite to upsert, auto-mark ACH payments as Cleared when send date has passed - slackAppHome: categorize payments into Scheduled/Outstanding/Cleared sections using unified status field - Add seed scripts for bulk-loading Stampli and bank CSV exports --- scripts/seed-bank-status.js | 141 +++++++++++++++++++++++++++++++++ scripts/seed-from-csv.js | 150 ++++++++++++++++++++++++++++++++++++ src/processPaymentCsv.js | 87 ++++++++++++++------- src/slackAppHome.js | 113 ++++++++++++++------------- template.yaml | 1 + 5 files changed, 414 insertions(+), 78 deletions(-) create mode 100644 scripts/seed-bank-status.js create mode 100644 scripts/seed-from-csv.js diff --git a/scripts/seed-bank-status.js b/scripts/seed-bank-status.js new file mode 100644 index 0000000..5ad1045 --- /dev/null +++ b/scripts/seed-bank-status.js @@ -0,0 +1,141 @@ +/** + * Seed bank status data from BoA exports into DynamoDB. + * + * Usage: + * node scripts/seed-bank-status.js \ + * --cleared "Bank Export.csv" \ + * --outstanding "PrintIssuesForInquiry.csv" \ + * --issued "Positive Pay Import original.csv" + * + * All flags are optional — supply whichever files you have. + * + * Updates existing payment records: + * - status: overwritten to "Cleared" | "Outstanding" | "Issued" + * - paid_date: date the check cleared (from Bank Export) + */ + +import { readFileSync } from "fs"; +import { parse } from "csv-parse/sync"; +import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; +import { DynamoDBDocumentClient, UpdateCommand } from "@aws-sdk/lib-dynamodb"; + +const TABLE_NAME = "PaymentsDashboard"; +const ddb = DynamoDBDocumentClient.from(new DynamoDBClient()); + +function parseArgs() { + const args = process.argv.slice(2); + const result = {}; + for (let i = 0; i < args.length; i += 2) { + const flag = args[i].replace(/^--/, ""); + result[flag] = args[i + 1]; + } + return result; +} + +function readCSV(filePath) { + const text = readFileSync(filePath, "utf-8"); + return parse(text, { columns: true, skip_empty_lines: true, trim: true }); +} + +// Normalize short dates like "1/27/26" → "2026-01-27" +function toISODate(dateStr) { + if (!dateStr) return null; + dateStr = dateStr.trim(); + + // Already ISO-ish: 04/13/2026 + let parts = dateStr.split("/"); + if (parts.length === 3) { + let [mm, dd, yyyy] = parts; + if (yyyy.length === 2) yyyy = `20${yyyy}`; + return `${yyyy}-${mm.padStart(2, "0")}-${dd.padStart(2, "0")}`; + } + return null; +} + +async function updateStatus(checkNumber, status, paidDate) { + const pk = `payment#${checkNumber}`; + const expr = ["#status = :s"]; + const names = { "#status": "status" }; + const values = { ":s": status }; + + if (paidDate) { + expr.push("paid_date = :pd"); + values[":pd"] = paidDate; + } + + await ddb.send( + new UpdateCommand({ + TableName: TABLE_NAME, + Key: { pk }, + UpdateExpression: `SET ${expr.join(", ")}`, + ExpressionAttributeNames: names, + ExpressionAttributeValues: values, + }) + ); +} + +async function main() { + const flags = parseArgs(); + const statusMap = new Map(); // checkNumber → { status, paidDate } + + // 1. Positive Pay Import (lowest priority) — "Issued" + // Format: check_number, date, ?, ?, amount (no headers) + if (flags.issued) { + console.log(`Reading positive pay import: ${flags.issued}`); + const text = readFileSync(flags.issued, "utf-8"); + const rows = parse(text, { skip_empty_lines: true, trim: true }); + for (const row of rows) { + const checkNumber = row[0]?.trim(); + if (!checkNumber) continue; + statusMap.set(checkNumber, { status: "Issued", paidDate: null }); + } + console.log(` ${rows.length} positive pay entries`); + } + + // 2. Outstanding Issues (medium priority) — "Outstanding" + if (flags.outstanding) { + console.log(`Reading outstanding issues: ${flags.outstanding}`); + const rows = readCSV(flags.outstanding); + for (const row of rows) { + const checkNumber = (row["Check Number"] || "").trim(); + if (!checkNumber) continue; + statusMap.set(checkNumber, { status: "Outstanding", paidDate: null }); + } + console.log(` ${rows.length} outstanding entries`); + } + + // 3. Bank Export / Cleared (highest priority) — "Cleared" + // Duplicates exist (same check appears twice); just take the first paid date. + if (flags.cleared) { + console.log(`Reading bank export (cleared): ${flags.cleared}`); + const rows = readCSV(flags.cleared); + const seen = new Set(); + let deduped = 0; + for (const row of rows) { + const checkNumber = (row["Check Number"] || "").trim(); + if (!checkNumber) continue; + if (seen.has(checkNumber)) { + deduped++; + continue; + } + seen.add(checkNumber); + const paidDate = toISODate(row["Paid Date"] || row["CD Volume Number"] || ""); + statusMap.set(checkNumber, { status: "Cleared", paidDate }); + } + console.log(` ${seen.size} unique cleared checks (${deduped} duplicates skipped)`); + } + + // Write to DynamoDB + let count = 0; + for (const [checkNumber, { status, paidDate }] of statusMap) { + await updateStatus(checkNumber, status, paidDate); + count++; + } + + console.log(`\nDone — ${count} payments updated with bank status.`); +} + +main().catch((err) => { + console.error(err); + process.exit(1); +}); diff --git a/scripts/seed-from-csv.js b/scripts/seed-from-csv.js new file mode 100644 index 0000000..8c0edf7 --- /dev/null +++ b/scripts/seed-from-csv.js @@ -0,0 +1,150 @@ +/** + * Seed DynamoDB PaymentsDashboard table from Stampli CSV exports. + * + * Usage: + * node scripts/seed-from-csv.js [csv-file2] ... + * + * Reads one or more Stampli CSV exports and upserts every row into the + * PaymentsDashboard table. Skips CashPro API calls entirely — this is + * purely for populating the DB so the Slack App Home has data to display. + */ + +import { readFileSync } from "fs"; +import { parse } from "csv-parse/sync"; +import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; +import { + DynamoDBDocumentClient, + UpdateCommand, + PutCommand, +} from "@aws-sdk/lib-dynamodb"; + +const TABLE_NAME = "PaymentsDashboard"; +const ddb = DynamoDBDocumentClient.from(new DynamoDBClient()); + +function toISODate(mdyDate) { + const parts = String(mdyDate || "").split("/"); + if (parts.length !== 3) return null; + const [mm, dd, yyyy] = parts; + return `${yyyy}-${mm.padStart(2, "0")}-${dd.padStart(2, "0")}`; +} + +const parseAmount = (value) => { + const num = parseFloat(String(value || "0").replace(/,/g, "").trim()); + return isNaN(num) ? 0 : num; +}; + +async function seedFile(filePath) { + const csvText = readFileSync(filePath, "utf-8"); + const rows = parse(csvText, { + columns: true, + skip_empty_lines: true, + trim: true, + }); + + const normalizedRows = rows.map((row) => { + const clean = {}; + for (const [k, v] of Object.entries(row)) { + clean[String(k).trim()] = typeof v === "string" ? v.trim() : v; + } + return clean; + }); + + let count = 0; + let skipped = 0; + + for (const row of normalizedRows) { + const checkNumber = (row["Check Number"] || "").trim(); + if (!checkNumber) { + skipped++; + continue; + } + + const method = (row["Method"] || "").trim(); + let status = (row["Status"] || "").trim(); + const sendOn = (row["Send Payment On"] || "").trim(); + + // ACH payments clear automatically on their send date — + // mark as Cleared unless voided/canceled + const cancelStatuses = ["canceled", "cancelled", "marked as void"]; + if (method === "ACH" && !cancelStatuses.includes(status.toLowerCase())) { + const sendDate = toISODate(sendOn); + const today = new Date().toISOString().slice(0, 10); + if (sendDate && sendDate <= today) { + status = "Cleared"; + } + } + + // Amount in USD is blank for canceled payments — fall back to Amount + const amount = parseAmount(row["Amount in USD"] || row["Amount"]); + const pk = `payment#${checkNumber}`; + + await ddb.send( + new UpdateCommand({ + TableName: TABLE_NAME, + Key: { pk }, + UpdateExpression: ` + SET #method = :method, + payee = :payee, + check_number = :check_number, + invoice_numbers = :invoice_numbers, + send_payment_on = :send_payment_on, + amount_usd = :amount_usd, + #status = :status, + company_subsidiary = :company_subsidiary + `, + ExpressionAttributeNames: { + "#method": "method", + "#status": "status", + }, + ExpressionAttributeValues: { + ":method": method, + ":payee": (row["Payee"] || "").trim(), + ":check_number": checkNumber, + ":invoice_numbers": (row["Invoice Numbers"] || "").trim(), + ":send_payment_on": (row["Send Payment On"] || "").trim(), + ":amount_usd": amount, + ":status": status, + ":company_subsidiary": (row["Company/Subsidiary"] || "").trim(), + }, + }) + ); + count++; + } + + console.log(` ${filePath}: ${count} upserted, ${skipped} skipped (no check number)`); + return count; +} + +async function main() { + const files = process.argv.slice(2); + if (!files.length) { + console.error("Usage: node scripts/seed-from-csv.js [csv-file2] ..."); + process.exit(1); + } + + let total = 0; + for (const f of files) { + console.log(`Processing ${f}...`); + total += await seedFile(f); + } + + // Update metadata + await ddb.send( + new PutCommand({ + TableName: TABLE_NAME, + Item: { + pk: "metadata", + file_name: "seed-from-csv", + last_updated: new Date().toISOString(), + last_file_count: total, + }, + }) + ); + + console.log(`\nDone — ${total} total payments seeded.`); +} + +main().catch((err) => { + console.error(err); + process.exit(1); +}); diff --git a/src/processPaymentCsv.js b/src/processPaymentCsv.js index bab2cd0..7b0492d 100644 --- a/src/processPaymentCsv.js +++ b/src/processPaymentCsv.js @@ -1,12 +1,20 @@ import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"; import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; -import { DynamoDBDocumentClient, BatchWriteCommand, PutCommand } from "@aws-sdk/lib-dynamodb"; +import { DynamoDBDocumentClient, UpdateCommand, PutCommand } from "@aws-sdk/lib-dynamodb"; import { parse } from "csv-parse/sync"; const s3 = new S3Client(); const ddb = DynamoDBDocumentClient.from(new DynamoDBClient()); const TABLE_NAME = process.env.TABLE_NAME; +// Convert MM/DD/YYYY to YYYY-MM-DD +function toISODate(mdyDate) { + const parts = String(mdyDate).split("/"); + if (parts.length !== 3) return null; + const [mm, dd, yyyy] = parts; + return `${yyyy}-${mm.padStart(2, "0")}-${dd.padStart(2, "0")}`; +} + export const handler = async (event) => { const record = event.Records[0]; const bucket = record.s3.bucket.name; @@ -36,33 +44,60 @@ export const handler = async (event) => { return isNaN(num) ? 0 : num; }; - const payments = normalizedRows.map((row) => ({ - pk: `payment#${(row["Check Number"] || "").trim()}`, - method: (row["Method"] || "").trim(), - payee: (row["Payee"] || "").trim(), - check_number: (row["Check Number"] || "").trim(), - invoice_numbers: (row["Invoice Numbers"] || "").trim(), - send_payment_on: (row["Send Payment On"] || "").trim(), - amount_usd: parseAmount(row["Amount in USD"]), - status: (row["Status"] || "").trim(), - company_subsidiary: (row["Company/Subsidiary"] || "").trim(), - })); + const cancelStatuses = ["voided", "cancelled", "canceled", "marked as void"]; - // Write payments in batches of 25 (DynamoDB BatchWrite limit) - const batches = []; - for (let i = 0; i < payments.length; i += 25) { - const batch = payments.slice(i, i + 25).map((item) => ({ - PutRequest: { Item: item }, - })); - batches.push(batch); - } + // Upsert each payment + let count = 0; + for (const row of normalizedRows) { + const checkNumber = (row["Check Number"] || "").trim(); + if (!checkNumber) continue; + + const method = (row["Method"] || "").trim(); + let status = (row["Status"] || "").trim(); + const sendOn = (row["Send Payment On"] || "").trim(); + + // ACH payments clear automatically on their send date + if (method === "ACH" && !cancelStatuses.includes(status.toLowerCase())) { + const sendDate = toISODate(sendOn); + const today = new Date().toISOString().slice(0, 10); + if (sendDate && sendDate <= today) { + status = "Cleared"; + } + } + + const pk = `payment#${checkNumber}`; - for (const batch of batches) { await ddb.send( - new BatchWriteCommand({ - RequestItems: { [TABLE_NAME]: batch }, + new UpdateCommand({ + TableName: TABLE_NAME, + Key: { pk }, + UpdateExpression: ` + SET #method = :method, + payee = :payee, + check_number = :check_number, + invoice_numbers = :invoice_numbers, + send_payment_on = :send_payment_on, + amount_usd = :amount_usd, + #status = :status, + company_subsidiary = :company_subsidiary + `, + ExpressionAttributeNames: { + "#method": "method", + "#status": "status", + }, + ExpressionAttributeValues: { + ":method": method, + ":payee": (row["Payee"] || "").trim(), + ":check_number": checkNumber, + ":invoice_numbers": (row["Invoice Numbers"] || "").trim(), + ":send_payment_on": sendOn, + ":amount_usd": parseAmount(row["Amount in USD"]), + ":status": status, + ":company_subsidiary": (row["Company/Subsidiary"] || "").trim(), + }, }) ); + count++; } // Update metadata record @@ -73,11 +108,11 @@ export const handler = async (event) => { pk: "metadata", file_name: key.split("/").pop(), last_updated: new Date().toISOString(), - last_file_count: payments.length, + last_file_count: count, }, }) ); - console.log(`Upserted ${payments.length} payments from ${key}`); - return { statusCode: 200, body: `Upserted ${payments.length} payments` }; + console.log(`Upserted ${count} payments from ${key}`); + return { statusCode: 200, body: `Upserted ${count} payments` }; }; diff --git a/src/slackAppHome.js b/src/slackAppHome.js index ea978c3..7ac45e4 100644 --- a/src/slackAppHome.js +++ b/src/slackAppHome.js @@ -83,7 +83,6 @@ export const handler = async (event) => { }; function buildHomeView(payments, metadata) { - const formatCurrency = (value) => new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format( Number(value || 0) @@ -98,88 +97,97 @@ function buildHomeView(payments, metadata) { return new Date(yyyy, mm - 1, dd); }; - const formatDateKey = (date) => { - const y = date.getFullYear(); - const m = String(date.getMonth() + 1).padStart(2, "0"); - const d = String(date.getDate()).padStart(2, "0"); - return `${y}-${m}-${d}`; - }; - - const formatDisplayDate = (dateKey) => { - const [y, m, d] = dateKey.split("-").map(Number); - const dt = new Date(y, m - 1, d); - return dt.toLocaleDateString("en-US", { - weekday: "short", - month: "short", - day: "numeric", - }); - }; + const formatDisplayDate = (date) => + date.toLocaleDateString("en-US", { weekday: "short", month: "short", day: "numeric" }); const today = new Date(); today.setHours(0, 0, 0, 0); - const futurePayments = payments.filter((p) => { + // Categorize payments by status + const scheduled = []; + const outstanding = []; + const cleared = []; + + const skipStatuses = ["voided", "cancelled", "canceled", "marked as void"]; + + for (const p of payments) { + if (p.method !== "ACH" && p.method !== "Check") continue; + const dt = parseMDYLocal(p.send_payment_on); - return dt && dt >= today && (p.method === "ACH" || p.method === "Check"); - }); + if (!dt) continue; - const groupByMethodAndDay = (methodName) => { - const grouped = {}; + const status = (p.status || "").toLowerCase(); - for (const payment of futurePayments) { - if (payment.method !== methodName) continue; - const dt = parseMDYLocal(payment.send_payment_on); - if (!dt) continue; - const key = formatDateKey(dt); + // Skip voided/cancelled payments entirely + if (skipStatuses.includes(status)) continue; - if (!grouped[key]) grouped[key] = { count: 0, total: 0 }; - grouped[key].count += 1; - grouped[key].total += payment.amount_usd; + if (status === "cleared") { + cleared.push(p); + } else if (status === "outstanding") { + outstanding.push(p); + } else if (dt < today) { + // Past due date but not yet confirmed cleared — outstanding + outstanding.push(p); + } else { + scheduled.push(p); } + } - return Object.keys(grouped) - .sort() - .map((dateKey) => ({ - date_key: dateKey, - display_date: formatDisplayDate(dateKey), - count: grouped[dateKey].count, - total: Number(grouped[dateKey].total.toFixed(2)), - })); + // Sort by date + const byDate = (a, b) => { + const da = parseMDYLocal(a.send_payment_on); + const db = parseMDYLocal(b.send_payment_on); + return (da || 0) - (db || 0); }; + scheduled.sort(byDate); + outstanding.sort(byDate); + cleared.sort(byDate); - const achDays = groupByMethodAndDay("ACH"); - const checkDays = groupByMethodAndDay("Check"); - - const buildDayBlocks = (title, days) => { - const total = days.reduce((sum, d) => sum + d.total, 0); - const count = days.reduce((sum, d) => sum + d.count, 0); + const buildSectionBlocks = (title, emoji, items) => { + const total = items.reduce((sum, p) => sum + p.amount_usd, 0); const blocks = [ { type: "section", text: { type: "mrkdwn", - text: `*${title}*\n${count} payments • ${formatCurrency(total)}`, + text: `*${emoji} ${title}*\n${items.length} payments • ${formatCurrency(total)}`, }, }, { type: "divider" }, ]; - if (!days.length) { + if (!items.length) { blocks.push({ type: "section", - text: { type: "mrkdwn", text: "_No upcoming payments found._" }, + text: { type: "mrkdwn", text: "_None_" }, }); blocks.push({ type: "divider" }); return blocks; } - for (const day of days) { + // Group by date + const grouped = {}; + for (const p of items) { + const dt = parseMDYLocal(p.send_payment_on); + const key = dt ? dt.toISOString().split("T")[0] : "unknown"; + if (!grouped[key]) grouped[key] = { date: dt, payments: [] }; + grouped[key].payments.push(p); + } + + for (const key of Object.keys(grouped).sort()) { + const group = grouped[key]; + const dayTotal = group.payments.reduce((sum, p) => sum + p.amount_usd, 0); + const dateLabel = group.date ? formatDisplayDate(group.date) : "Unknown"; + blocks.push({ type: "section", fields: [ - { type: "mrkdwn", text: `*${day.display_date}*` }, - { type: "mrkdwn", text: `${day.count} payments • ${formatCurrency(day.total)}` }, + { type: "mrkdwn", text: `*${dateLabel}*` }, + { + type: "mrkdwn", + text: `${group.payments.length} payments • ${formatCurrency(dayTotal)}`, + }, ], }); } @@ -203,8 +211,9 @@ function buildHomeView(payments, metadata) { ], }, { type: "divider" }, - ...buildDayBlocks("ACH", achDays), - ...buildDayBlocks("Check", checkDays), + ...buildSectionBlocks("Scheduled", ":calendar:", scheduled), + ...buildSectionBlocks("Outstanding", ":warning:", outstanding), + ...buildSectionBlocks("Cleared", ":white_check_mark:", cleared), ], }; } diff --git a/template.yaml b/template.yaml index 0802d96..384e817 100644 --- a/template.yaml +++ b/template.yaml @@ -131,6 +131,7 @@ Resources: Properties: FunctionName: payments-processPaymentCsv Handler: src/processPaymentCsv.handler + Timeout: 120 VpcConfig: SubnetIds: - !Ref PrivateSubnet