Pass gift through the page hit pipeline

[jonatansberg]

ref https://linear.app/ghost/issue/BER-3746/integrate-gift-link-usage-tracking-with-analytics

Ghost's Gift Links feature is moving usage tracking off a bespoke DB counter and onto the existing web-analytics pipeline, so gift numbers are measured the same way as every other page view. Gift reads carry one new dimension — gift (the gift-link token) — on the page_hit payload, so the data can:

• segment "gift traffic" in the normal reports, and
• count usage per individual link.

Why this PR is needed

The proxy rebuilds the payload field-by-field (pageHitRawPayloadFromRequest → transformPageHitRawToProcessed), so any field not explicitly threaded is silently dropped before it reaches Tinybird. This wires gift through end-to-end:

• schemas/v1/page-hit-raw.ts — gift on PayloadSchema (optional, nullable).
• transformations/page-hit-transformations.ts — copied in pageHitRawPayloadFromRequest(), defaulting to null.
• schemas/v1/page-hit-processed.ts — on PageHitProcessedSchema and the payload rebuilt in transformPageHitRawToProcessed().
• schemas/v1/page-hit-request.ts — declared explicitly (validation already admits it via additionalProperties: true) + a null default.

Covers both the inline and batch worker paths, since both run through these transforms. Absent on non-gift hits, where it defaults to null.

Notes for review

• gift is the gift-link token, a bearer credential — but first-party data the site owner already minted and shareable by design, so storing it in their own analytics is acceptable. Worth a thought on error-log / retention.
• Producer (Ghost ghost_head) and the Tinybird data-files (_mv_hits column, segment, per-link endpoint) are separate PRs on the Ghost repo. This PR is a safe no-op until those land.

Tests

tsc clean. page-hit-transformations.test.ts: the "all fields present" case now asserts gift passthrough, plus a new case for the absent → null default. (The 2 pre-existing SaltStoreFactory failures are unrelated Firestore/GCP-env tests.)

[coderabbitai]

Important

Review skipped

Draft detected.

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

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1f2a73c5-5386-4e20-aa85-786036f83aa7

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ber-3728-gift-id-passthrough

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}