Skip to content

chore(monthly): #290 P3 follow-ups — batch payment_account lookup, doc comment, expiry isolation, cron failure alerts (Refs #308) - #309

Merged
JOY (JOY) merged 1 commit into
devfrom
antigravity/308-monthly-plan-p3-followups
Nov 22, 2026
Merged

JOY (JOY) merged 1 commit into
devfrom
antigravity/308-monthly-plan-p3-followups

Conversation

@JOY

@JOY JOY (JOY) commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Refs #308

App-only (apps/web, zero DB migrations) cleanup batching all 4 non-blocking P3 follow-ups from #290 (#276 Monthly donations A):

What changes

  1. Per-campaign payment_account lookup batching & pruning (apps/web/src/server/contributions/index.ts, apps/web/src/app/me/contributions/page.tsx, apps/web/src/app/me/contributions/PlanList.tsx, apps/web/src/lib/plans.ts):
    • Added paymentAccounts() helper with campaign ID deduplication, bounded parallel concurrency (PAYMENT_ACCOUNT_BATCH_CONCURRENCY = 5, defensive finite-number guard), and per-campaign error isolation (failed lookups stay unknown instead of blocking or hiding other campaigns).
    • Skips give.payment_account RPCs on /me/contributions for ended plans or plans without a potentially payable current-month donation (already received/expired, not yet issued, non-live, or past ends_at), sharing currentPlanDonation() with PlanList and running usable-account and pledge-balance lookups in parallel with one consistent clock.
  2. Misplaced doc comment (apps/web/src/app/me/contributions/page.tsx):
    • Moved ContributionList's JSDoc block from above withUsableAccounts back directly above ContributionList.
  3. Expiry & cron batch/step isolation (apps/web/src/server/plans/jobs.ts, apps/web/src/app/api/cron/issue-plan-donations/route.ts, apps/web/src/app/api/cron/plan-notices/route.ts):
    • Isolated Step 1 and Step 2 in both issue-plan-donations (issue_plan_donations / expire_plan_donations) and plan-notices (plan_end_notices / plan_followups) within the shared 45 s budget so a failure in one step never stalls the other (while still returning HTTP 500 on step failure).
    • Updated expirePlanDonations() to drain multiple 500-row batches within budget, isolate batch errors/throws/malformed responses without losing earlier batch counts, and probe give.contributions (select("id")) when expire_plan_donations returns 0 (only while budget remains so maxDuration = 60 is preserved) to detect and flag stalled bad batches (expire_stalled: true, done: false).
  4. Structured zero-PII alerts on 'failed' outcomes (apps/web/src/server/plans/jobs.ts, both monthly cron routes, /me/contributions/page.tsx):
    • Added logPlanCronFailures() and logPlanStepFailure() emitting structured JSON error logs (plan_cron.failed_outcomes, plan_job.plan_failed, plan_job.expire_batch_stalled, plan_job.expire_batch_failed, plan_cron.step_failed) with strictly zero PII (never logging donor name, email, phone, IP, user ID, account number, reference code, or raw error.message).

Verification

  • pnpm format:check: clean
  • pnpm lint: clean
  • pnpm typecheck: clean
  • pnpm --filter @give/web exec vitest run --maxWorkers=2: 180 files / 2,650 tests pass (79 tests across the 6 touched suites)
  • pnpm build: clean
  • Independent fresh-context code review (e3e3788f-ca56-4a90-a6bd-b26c0af5b1bf): PASS (1 P2 budget guard on overdue probe + 4 P3 nits caught and fixed; re-verified 0 P0–P3 remaining)

📌 TL;DR

This PR hardens the monthly plan cron jobs by isolating step failures, implementing batched expiry with stall detection, and introducing structured zero-PII logging for observability. It also refactors the contributions page to deduplicate and bound payment account lookups, improving reliability and performance.

🎯 Type of Change

  • 🚀 New feature
  • 🐛 Bugfix
  • 🧹 Refactor
  • ⚡ Performance
  • 📚 Documentation
  • ⚙️ CI / Configuration

🔍 Changes Walkthrough

File Summary of Changes
apps/web/src/app/api/cron/issue-plan-donations/route.ts Refactored to isolate sweepPlans and expirePlanDonations failures. Added structured logging for step failures and cron outcomes. Updated response to include expire_stalled and detailed expiry status.
apps/web/src/app/api/cron/issue-plan-donations/route.test.ts Added tests for zero-PII alert emission on failed outcomes, stalled expiry detection, and step failure isolation.
apps/web/src/app/api/cron/plan-notices/route.ts Refactored to isolate plan_end_notices and plan_followups sweeps. Added structured logging for failures and outcomes.
apps/web/src/app/api/cron/plan-notices/route.test.ts Added tests for structured alerts on failed outcomes and step failure isolation.
apps/web/src/server/plans/jobs.ts Major Refactor:
1. Replaced raw console.error with structured JSON logging (logPlanError, logPlanWarn) to prevent PII leakage.
2. Added logPlanCronFailures and logPlanStepFailure helpers.
3. Rewrote expirePlanDonations to support batched processing (EXPIRE_BATCH_SIZE), budget-aware stopping, and stall detection via hasOverduePlanDonations.
4. Added ExpirePlansResult interface for detailed status reporting.
apps/web/src/server/plans/jobs.test.ts Updated tests to verify structured logging format (zero-PII). Added comprehensive tests for batched expiry, stall detection, and error isolation.
apps/web/src/server/contributions/index.ts Added paymentAccounts function for batched, deduplicated, and concurrency-bounded payment account lookups. Added PAYMENT_ACCOUNT_BATCH_CONCURRENCY constant.
apps/web/src/server/contributions/contributions.test.ts Added tests for paymentAccounts deduplication, error isolation, and concurrency limits.
apps/web/src/app/me/contributions/page.tsx Refactored withUsableAccounts to use the new paymentAccounts batch function. Optimized to only look up accounts for plans with payable current-month donations. Parallelized plan and pledge balance fetching.
apps/web/src/app/me/contributions/page.test.ts Added tests to verify payment account lookup optimization (skipping unnecessary lookups) and error isolation without PII leakage.
apps/web/src/app/me/contributions/PlanList.tsx Extracted currentPlanDonation helper for reusability. Re-exported vnMonthStart.
apps/web/src/lib/plans.ts Moved vnMonthStart utility here for shared access between client and server components.
apps/web/src/lib/plans.test.ts Added tests for vnMonthStart timezone boundary conditions.

📊 Architectural Flow

sequenceDiagram
    participant Cron as Cron Trigger
    participant Route as Cron Route Handler
    participant Jobs as Plan Jobs Service
    participant DB as Database (Supabase)
    participant Logs as Structured Logs (Zero-PII)

    Cron->>Route: GET /api/cron/issue-plan-donations
    Route->>Jobs: sweepPlans(db, "issue_plan_donations")
    
    loop Sweep Plans
        Jobs->>DB: rpc:issue_plan_donations
        alt Success
            DB-->>Jobs: { plan_id, outcome }
        else Failure
            DB-->>Jobs: { error }
            Jobs->>Logs: logPlanError (structured JSON)
            Jobs-->>Route: PlanJobError
        end
    end
    
    Jobs-->>Route: PlanSweep Result
    Route->>Logs: logPlanCronFailures (if failed > 0)

    Route->>Jobs: expirePlanDonations(db, now, budget)
    
    loop Batch Expiry (within budget)
        Jobs->>DB: rpc:expire_plan_donations
        alt Success
            DB-->>Jobs: count
            alt Count == 0
                Jobs->>DB: hasOverduePlanDonations (probe)
                DB-->>Jobs: boolean
                alt Overdue exists
                    Jobs->>Logs: logPlanError (stalled)
                end
            end
        else Failure
            DB-->>Jobs: { error }
            Jobs->>Logs: logPlanError (structured JSON)
            Jobs-->>Route: ExpirePlansResult (failed: true)
        end
    end
    
    Jobs-->>Route: ExpirePlansResult
    Route-->>Cron: JSON Response (status, done, expired, stalled)
Loading

… and alert on cron failures (Refs #308)

Addresses all 4 app-only P3 follow-ups from #290 (zero DB migrations):
- Add deduped, bounded-concurrency paymentAccounts() helper (max 5 in flight,
  per-campaign error isolation) and skip payment_account RPCs on /me/contributions
  for plans without a payable current-month donation; run usable-account and
  pledge-balance lookups in parallel with one consistent clock.
- Move misplaced ContributionList doc comment above ContributionList in
  apps/web/src/app/me/contributions/page.tsx.
- Isolate cron steps in issue-plan-donations and plan-notices within the shared
  deadline; drain multi-batch expire_plan_donations (500/batch), isolate batch
  errors without losing earlier counts, and detect/alert stalled bad batches
  without breaching the maxDuration budget.
- Emit structured zero-PII JSON error logs (plan_cron.failed_outcomes,
  plan_job.plan_failed, plan_job.expire_batch_stalled/failed) whenever monthly
  plan cron jobs record 'failed' outcomes or errors.
@JOY JOY (JOY) added line:money Product line: money po:agy Owned by Antigravity PO (mutual-exclusion parallel PO label) labels Nov 22, 2026

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

@vercel

vercel Bot commented Nov 22, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
give Ready Ready Preview Nov 22, 2026 10:01am UTC

Request Review

@coderabbitai

coderabbitai Bot commented Nov 22, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 582370f2-e9ed-46ad-984b-60db21d3c01a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

dos[bot]
dos Bot approved these changes Nov 22, 2026

@dos dos Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⏱️ Code Review completed (13 eligible files · 56,551 chars · 1 model call(s) · 2 PR unit(s))

Whole diff with bounded context at base 9deab36 / head a80257d.

✅ CLEAN_PASS: Complete diff reviewed

@JOY

Copy link
Copy Markdown
Contributor Author

PO acceptance: merge at a80257d

Verified on GitHub:

  • Required checks green: Verify build/Lint, Verify build/Build all apps (plus Vercel preview & DOScout green)
  • mergeStateStatus: CLEAN, 0 unresolved review threads; dos[bot] APPROVED
  • Two independent fresh-context flagship money-domain reviews approved at a80257d90ef49976da73a43239654422569fbf25 (zero blocking findings; deduped bounded payment_account lookup, multi-batch expiry isolation & stalled-batch probe within 45s budget, and zero-PII structured failure alerts verified).

@JOY
JOY (JOY) merged commit dd40557 into dev Nov 22, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

line:money Product line: money po:agy Owned by Antigravity PO (mutual-exclusion parallel PO label)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant