Skip to content

feat(web): add dynamic OpenGraph truth cards and social PNG download - #1868

Merged
JOY (JOY) merged 1 commit into
devfrom
feat/1865-og-truth-cards
Nov 22, 2026
Merged

JOY (JOY) merged 1 commit into
devfrom
feat/1865-og-truth-cards

Conversation

@JOY

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

Copy link
Copy Markdown
Contributor

Summary

Implement Package 8A Feature F3 (approved by JOY on 2026-11-22 from Docs/Proposals/2026-11-22-de-xuat-tinh-nang-moi-phase-8.html):

  • Validated, Rate-Limited Truth Card Endpoint (/api/v1/rate/og + apps/web/src/lib/og-truth-card.tsx):
    • Generates dark-theme (#0f1113 canvas, #161a1e surface, #FF2E29 brand accent) PNG cards for 3 verified catalog entity types: product (verified floor price across X / 22 retail chains, cross-store spread, Deal Radar badge, Bayesian buyer stars, Rate Lab score, 6-axis review trust signal, and fake-sale trap status), versus (head-to-head 2-device comparison with overall star scores, criterion wins, and floor prices), and deals (Deal Radar summary across 22 retail chains).
    • Supports format=og (1200x630) and format=social (1080x1350 4:5 portrait) across vi, en, and cs with full Vietnamese and Czech diacritics and zero external network calls (strict Geist-Regular.ttf cmap allowlist + \p{Cf} format stripping + NFC normalization).
    • Security & anti-DoS hardening: closed query key allowlist rejecting arbitrary user text (title, price, cache-busting params) and non-canonical enum/whitespace/control permutations (400), catalog-backed resolution via withRateDataCache (404 when unknown), eager PNG stream materialization inside try/catch (500 masked with Cache-Control: no-store), BoundedSlidingWindowRateLimiter (60/min, 429 + Retry-After: 60), and Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400.
  • OpenGraph & Twitter Card Metadata + 1-Click Social PNG Download:
    • Wires openGraph.images and twitter (summary_large_image, @rate_vn) in generateCategoryProductMetadata (covering smartphones, tablets, laptops, smartwatches, earbuds), /compare/[versus]/page.tsx, and /deals/page.tsx.
    • Adds a 1-click "Download truth card (PNG)" action inside ProductShareAuditButton.tsx ("productDetail" locale namespace across vi, en, and cs, including ?v= variant selection parity).

Review Gate

  • Independent Fresh-Context Subagent 1 (Security & DoS Reviewer, bcd532cc-fef2-44e3-8954-a65f8cc107fa): 0 P0, 4 P1, 1 P2, 0 P3 in Round 1 (exact Geist-Regular.ttf cmap + \p{Cf} filter blocking U+00AD outbound font probes, eager PNG buffer materialization inside try/catch, strict canonical enum query parsing + Object.prototype slug blocklist, RATE_ITEM_MODEL canonical versus pair resolution, and ItemModelUnavailableError-only catch). All 5 findings fixed and covered by unit tests.
  • Independent Fresh-Context Subagent 2 (SEO, OG, Font & A11y Reviewer, dc4594fc-0b1a-400d-8f67-a092fe02c88b): 0 P0, 4 P1, 2 P2, 2 P3 in Round 1 (Geist-Regular.ttf cmap allowlist, canonical Item versus pairs, itemFromStats multi-variant Item floor price parity + ?v= variant download resolution, /deals limit: 50 cache/KPI parity, undotted _ product slug support, Satori flexShrink: 0 / flex: 1 layout guards, English sentence case, and formatNumber review count grouping). All findings fixed.
  • Codex CLI note: Local Codex CLI is currently out of quota until Nov 25, 2026, so two independent fresh-context subagent reviews were executed instead.

Verification

  • pnpm --filter @repo/web test (including 18 offline PNG renders across product/versus/deals x vi/en/cs x 1200x630/1080x1350 verified with sharp metadata, PNG magic bytes, and external-fetch interception)
  • pnpm typecheck
  • pnpm lint
  • pnpm build

Closes #1865
Claimant: antigravity:0a1440be-c5c8-4ac0-8916-8f45aad1d36c


📌 TL;DR

This PR introduces a dynamic "Truth Card" Open Graph image generation system that renders server-side PNGs for product, comparison, and deals pages to enhance social sharing. It includes a new API route with strict security validation, rate limiting, and offline rendering capabilities, along with a new UI button for users to download these cards.

🎯 Type of Change

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

🔍 Changes Walkthrough

File Summary of Changes
apps/web/locales/{cs,en,vi}.json Added translation keys for the new "Download Truth Card" button and tooltip.
apps/web/src/app/[locale]/compare/[versus]/page.tsx Updated generateMetadata to use buildOgTruthCardImage for dynamic OG images and added Twitter card metadata.
apps/web/src/app/[locale]/deals/page.tsx Updated generateMetadata to use buildOgTruthCardImage for dynamic OG images and added Twitter card metadata.
apps/web/src/app/[locale]/smartphones/[slug]/page.tsx Replaced static product image logic with buildOgTruthCardImage for dynamic OG images; added slug prop to ProductShareAuditButton.
apps/web/src/app/api/v1/rate/og/route.ts New API Route: Handles GET requests for OG truth cards. Includes rate limiting, strict query validation, and resolvers for product, versus, and deals data.
apps/web/src/components/leaderboard/ProductShareAuditButton.tsx Added slug prop and a new "Download Truth Card" button that triggers a PNG download via the new API route.
apps/web/src/lib/__tests__/product-detail-copy.test.ts Added tests for the new download URL resolver and locale copy validation.
apps/web/src/lib/__tests__/seo.test.ts Added extensive tests for OG truth card query parsing, security validation, PNG rendering (offline check), and API route behavior (200, 400, 404, 429, 500).
apps/web/src/lib/og-truth-card.tsx New Library: Contains the core logic for rendering OG truth cards using next/og (Satori). Includes data types, strict query parsing, text sanitization, and localized copy dictionaries.

📊 Architectural Flow

sequenceDiagram
    participant User
    participant UI as ProductShareAuditButton
    participant API as /api/v1/rate/og
    participant Resolver as Data Resolvers
    participant Renderer as renderOgTruthCardPng

    User->>UI: Click "Download Truth Card"
    UI->>UI: resolveShareAuditOgDownloadUrl()
    UI->>API: GET /api/v1/rate/og?type=product&slug=...&download=1
    API->>API: Rate Limit Check
    API->>API: parseOgTruthCardQuery (Strict Validation)
    API->>Resolver: resolveProduct(slug)
    Resolver-->>API: ProductTruthCardData
    API->>Renderer: renderOgTruthCardHttpResponse(data)
    Renderer->>Renderer: Satori/Next OG (Offline PNG Render)
    Renderer-->>API: PNG Buffer
    API-->>UI: 200 OK (image/png, Content-Disposition: attachment)
    UI->>User: Trigger Browser Download
Loading

Implement /api/v1/rate/og and og-truth-card.tsx for product, 1v1 versus,
and Deal Radar cards across vi/en/cs in 1200x630 and 1080x1350 formats,
wire openGraph and twitter metadata, and add 1-click social PNG download
to ProductShareAuditButton.

Closes #1865

@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
rate Ready Ready Preview Nov 22, 2026 3:25pm UTC

Request Review

@coderabbitai

coderabbitai Bot commented Nov 22, 2026

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 54 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

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: f0541f7d-79a9-4eb7-a4ad-c3e796557286
Commits

Reviewing files that changed from the base of the PR and between d896a99 and 7755067.

Files selected for processing: 12

  • apps/web/locales/cs.json
  • apps/web/locales/en.json
  • apps/web/locales/vi.json
  • apps/web/src/app/[locale]/compare/[versus]/page.tsx
  • apps/web/src/app/[locale]/deals/page.tsx
  • apps/web/src/app/[locale]/smartphones/[slug]/page.tsx
  • apps/web/src/app/api/v1/rate/og/route.ts
  • apps/web/src/components/leaderboard/ProductShareAuditButton.tsx
  • apps/web/src/lib/__tests__/product-detail-copy.test.ts
  • apps/web/src/lib/__tests__/seo.test.ts
  • apps/web/src/lib/og-truth-card.tsx
  • apps/web/src/lib/seo.ts
  • 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

@JOY

Copy link
Copy Markdown
Contributor Author

PO acceptance: merge at 7755067

@JOY
JOY (JOY) merged commit 1c75b42 into dev Nov 22, 2026
20 checks passed
@JOY
JOY (JOY) deleted the feat/1865-og-truth-cards branch November 22, 2026 15:37

This branch was successfully deployed

1 active deployment
Preview — 7755067f Deployed Nov 22, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:frontend Frontend / Next.js / UI

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(web): add dynamic OpenGraph truth cards and social PNG download

1 participant