Data Exports | blade47/dub Wiki | doc0

Public

Data Exports | blade47/dub Wiki | doc0

Approach	Benefit	Cost
Synchronous CSV / ZIP (`GET`)	Immediate file download in browser; simpler request-response lifecycle without external queues.	Subject to Vercel/HTTP timeout limits (e.g., `maxDuration = 300` for analytics); risks memory exhaustion on large result sets.
Asynchronous QStash Worker (`POST`)	Handles unbounded datasets via chunked batch iteration; offloads heavy CPU/IO processing from HTTP request threads.	Requires webhook signature verification (`verifyQstashSignature`), storage upload management (`createDownloadableExport`), and email dispatch (`sendEmail`).

Route Path	Method	Max Synchronous Limit	Plan / Permission Requirements	QStash Offload URL
`/api/links/export`	`GET`	1,000 links	`links.read` permission	`/api/cron/export/links`
`/api/commissions/export`	`GET`	1,000 commissions	Default program ID	`/api/cron/export/commissions`
`/api/payouts/export`	`GET`	1,000 payouts	Default program ID	`/api/cron/export/payouts`
`/api/customers/export`	`GET`	1,000 customers	`business`, `advanced`, `enterprise`	`/api/cron/export/customers`
`/api/audit-logs/export`	`POST`	None (All queried)	`enterprise`, roles `owner`/`member`	None (Direct only)
`/api/program-applications/export`	`GET`	None (All queried)	`business`, `advanced`, `enterprise`	None (Direct only)

Design Choice	Benefit	Cost
Fixed synchronous export threshold (`MAX_*_TO_EXPORT = 1000`)	Protects server memory and request timeout limits by redirecting large reports to background workers.	Datasets slightly above 1,000 records require users to wait for asynchronous email delivery instead of immediate download.
Workspace permission wrappers (`withWorkspace`)	Centralizes tenant isolation, session extraction, and permission checks (`links.read`, plan checks).	Couples route handlers tightly to authentication middleware wrappers.
Dynamic schema column ordering (e.g. Program Applications)	Automatically aligns exported CSV headers with defined UI column configuration and sort maps.	Adds CPU overhead to map, sort, and parse record keys on every export request.

Export Endpoint	Batch Fetcher Function	Formatting Function	Hard Record Limit
`/api/cron/export/commissions`	`fetchCommissionsBatch()`	`formatCommissionsForExport()`	None (Full query)
`/api/cron/export/payouts`	`fetchPayoutsBatch()`	`formatPayoutsForExport()`	`100_000`
`/api/cron/export/links`	`fetchLinksBatch()`	`formatLinksForExport()`	None (Full query)
`/api/cron/export/customers`	`fetchCustomersBatch()`	`formatCustomersForExport()`	`100_000`
`/api/cron/export/partners`	`fetchPartnersBatch()`	`formatPartnersForExport()`	None (Full query)

Constant Name	Value / Members	Purpose
`DEFAULT_SKIP_ENDPOINTS`	`["count"]`	Excludes the basic count endpoint from standard analytics ZIP archives.
`PARTNER_PROFILE_SKIP_ENDPOINTS`	`["count", "top_partners", "top_groups", "top_partner_tags", "top_folders", "top_link_tags"]`	Excludes non-applicable dimensions when exporting partner profile analytics.

Constant Name	Value / Type	Purpose
`MAX_EVENTS_TO_EXPORT`	`1000`	Threshold that determines whether to process an event export synchronously or offload to background QStash workers.
`MAX_PARTNER_LINKS_FOR_LOCAL_FILTERING`	Constant from `@dub/constants`	Maximum number of partner links allowed before switching from explicit local link evaluation to partner-level query filters.
`defaultColumns["clicks"]`	`["timestamp", "link", "referer", "country", "device"]`	Default projected columns when exporting click events without an explicit column parameter.
`defaultColumns["leads"]`	`["timestamp", "event", "link", "customer", "referer"]`	Default projected columns when exporting lead events.
`defaultColumns["sales"]`	`["timestamp", "saleAmount", "event", "customer", "referer", "link"]`	Default projected columns when exporting sale events.

Constant Name	Value / Type	Purpose
`MAX_EVENTS_TO_EXPORT`	`1000`	Maximum event count for synchronous partner event exports before offloading via QStash.
`MAX_CUSTOMERS_TO_EXPORT`	`1000`	Maximum customer count for synchronous partner customer exports before background processing.
`MAX_CUSTOMERS_EXPORT_LIMIT`	`100_000`	Hard cap on total customer records processed by the background customer export worker.
`PAGE_SIZE`	`1000`	Chunk size used when paginating database queries in background customer export loops.

Export Domain	File Key Template	Content Type
Commissions	`exports/commissions/${generateRandomString(16)}.csv`	`text/csv`
Payouts	`exports/payouts/${generateRandomString(16)}.csv`	`text/csv`
Partner Customers	`exports/customers/partner/${generateRandomString(16)}.csv`	`text/csv`
Links	`exports/links/${generateRandomString(16)}.csv`	`text/csv`
Customers	`exports/customers/${generateRandomString(16)}.csv`	`text/csv`
Partners	`exports/partners/${generateRandomString(16)}.csv`	`text/csv`
Workspace Events	`exports/events/workspace/${generateRandomString(16)}.csv`	`text/csv`