Introduce spans of events

[Yopi]

Backend:

• Adds a hierarchical grouping of events (via parent_event_id).
• Allows ingestion with a external_id as an idempotency key. Events with the same external_id are not reingested
• Allows ingestion of a parent_id either as a Polar event.id or as a external_id. We do the lookup on our side to allow both sides.

Frontend:

• Add display of nested events (in one level for now)
• Add pagination of nested events

[vercel]

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

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
polar	Ignored	Preview		Nov 3, 2025 2:24pm
polar-sandbox	Ignored	Preview		Nov 3, 2025 2:24pm

[emilwidlund]

Great work on this!

I wonder if we should rename external_event_id to idempotency_key instead? I wonder if that better conveys the purpose of it. But that's just my 2 cents :)

[pieterbeulque]

@Yopi one thing I noticed during your demo was that with the pagination, the 6 children for a span became 10 children when you clicked "Show more", is that a bug in the pagination logic?

[Yopi]

@Yopi one thing I noticed during your demo was that with the pagination, the 6 children for a span became 10 children when you clicked "Show more", is that a bug in the pagination logic?

Good catch! It's the 10 children that goes to 13 children, because we actually don't know how many there are. It's a bit complicated to get the full counts in the recursive function. We could try a bit more to do it in a good way, or we could work with the UX. The button shows up if the count is the same as the limit of children (https://github.com/polarsource/polar/pull/7609/files#diff-bd567ed3816662d20cecb8b5111fa9c68085ed30b08458815dc178d840a09ad5R44)

[pieterbeulque]

Then what if you have exactly 10 child events? 🤔

[Yopi]

Then what if you have exactly 10 child events? 🤔

Haha exactly. If we think it's decent enough to do this without real pagination we could select one more to be able to determine if more exists and pass that to the frontend.

[Yopi]

I was reading our docs, and this type of pagination strays a bit from our promise on how we do pages (page, limit, max_count), but on the other hand I don't think it's feasible for us to get a max count for each depth. I pushed a change now that we can at least know if there are more children to load or not and maybe that's fine.

I can check how this looks and behaves in the SDK.

[github-actions]

📦 Next.js Bundle Analysis for web

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

[github-actions]

📦 Next.js Bundle Analysis for web

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

[github-actions]

📦 Next.js Bundle Analysis for web

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

[pieterbeulque]

I like it! The API is backwards compatible in this shape, right? (i.e. everything new is optional?)

[pieterbeulque]

Actually, should external_id be unique only for the specified event name?

This would horribly break parent_event_id, sorry.

[Yopi]

I like it! The API is backwards compatible in this shape, right? (i.e. everything new is optional?)

Precisely, everything new is optional!