[Feature] Implement Async Nano Banana Webhook Processing with Dead-Letter Queue & Polling Fallback

[Darkvader-ship-it]

Estimated Effort: 2 weeks / 6 days

Impacted Subsystems / Files:

• app/api/webhooks/nanobanana/route.ts
• lib/forge-nanobanana.ts
• lib/server-data-paths.ts

Context & Problem Statement:
When image generation takes longer than Vercel serverless execution limits (10s/60s), the current implementation in lib/forge-nanobanana.ts times out, causing the client to lose payment confirmation context even though the AI engine eventually completes.

Technical Requirements & Scope:

1. Refactor app/api/webhooks/nanobanana/route.ts to receive async generation callbacks.
2. Implement persistent job state tracking stored in .data/generation-jobs.json.
3. Build client polling endpoint allowing frontend to query job status by transaction hash.
4. Implement dead-letter queue mechanism to record failed webhook callbacks for retry.

Multi-File Change Surface:
Modifies webhook endpoint app/api/webhooks/nanobanana/route.ts, lib/forge-nanobanana.ts, and frontend polling hooks in app/forge/page.tsx.

Acceptance Criteria:

• Image generation jobs exceeding 60s complete asynchronously without request failure.
• Webhook signatures verified against NANOBANANA_WEBHOOK_SECRET.
• Failed jobs automatically recorded in dead-letter store with full error trace.

Suggested Approach / Investigation Steps:

1. Define async job state schema and webhook signature validator.
2. Implement store operations in lib/generation-job-store.ts.
3. Connect client UI to poll generation job status until completed.

---

[Peace-001]

@Peace-001 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Good day maintainer, I will like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Peace-001 to this issue.

[Emelie-Dev]

@Emelie-Dev has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi, I would love to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Emelie-Dev to this issue.

[drips-wave]

Congratulations, @Peace-001! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Peace-001: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊