Track completed exports from an Astro server endpoint

A concrete Astro endpoint pattern for recording completed exports in Butters, with server-only credentials, stable user IDs, and a clear failure policy.

3 min read
A blue server connected to a coral browser window and a yellow progress ring.

An export finishes in your Astro app. The customer has a download, but your team still needs a simple answer to a different question: did it complete, and for whom? Record the outcome where the export finishes. A browser click only proves that someone asked for an export.

This example adds one Butters event to an existing server endpoint. It assumes your app already authenticates the requester and writes the export file. The small functions marked as application code are the places to connect your own auth and export logic.

Keep the key on the server

Install the SDK with npm install @getbutters/js. Create a secret event key and copy your project ID from Butters. Put both in the server environment:

BUTTERS_API_KEY=ev_your_secret_key
BUTTERS_PROJECT_ID=your_project_id

Use the server entry point. A pk_ publishable key belongs to browser tracking; this endpoint needs a secret ev_ key. Never prefix this variable with PUBLIC_.

Report the result after the work

Create src/pages/api/exports.ts. If the rest of your Astro site is static, add an adapter and keep prerender = false so this route runs on demand.

import type { APIRoute } from 'astro'
import { Butters } from '@getbutters/js/server'
import { requireUser, createExport } from '../../lib/exports'

export const prerender = false

const butters = new Butters({
  key: import.meta.env.BUTTERS_API_KEY,
  project: import.meta.env.BUTTERS_PROJECT_ID,
})

export const POST: APIRoute = async ({ request }) => {
  const user = await requireUser(request)
  const exportFile = await createExport(user.id)

  await butters.track('exports', 'Customer export completed', {
    user_id: user.id,
    metadata: { export_id: exportFile.id },
    url: exportFile.adminUrl,
  })

  return Response.json({ downloadUrl: exportFile.downloadUrl })
}

requireUser and createExport are your application functions, not SDK exports. The first must reject unauthorized requests; the second must return a completed export, not merely a queued job. If your export runs in a background worker, move the track call into that worker's completion path instead of the HTTP endpoint.

The server client has a fixed key and project. Pass user_id on each event: a module-level identify() call would mix users across concurrent requests. The metadata stores an internal export ID so a teammate can find the corresponding record. Keep personal data and download tokens out of metadata and URLs.

Decide what happens when reporting fails

The code above awaits Butters before returning. If the event API fails, the request fails even though the export may already exist. That can be the right choice for a workflow that requires an audit trail, but it can also encourage a user to retry and create another export.

For a best-effort activity feed, catch the reporting failure separately and return the completed export:

try {
  await butters.track('exports', 'Customer export completed', {
    user_id: user.id,
    metadata: { export_id: exportFile.id },
  })
} catch (error) {
  console.error('Export event failed', error)
}

return Response.json({ downloadUrl: exportFile.downloadUrl })

Use one policy or the other deliberately. The SDK does not retry automatically, because a timeout can happen after the server accepted an event. If you need guaranteed delivery, write an outbox record in the same transaction as your export status change and drain it with a worker. A feed call by itself is not a durable queue.

Check the integration

Run one export and confirm that the feed shows one “Customer export completed” event with the expected user and export ID. Then force the export operation to fail. No completed event should appear. Finally, block the Butters API in a test environment and confirm that your chosen reporting-failure policy matches what users see.

Astro's on-demand rendering guide explains the adapter and prerender setting. The Butters JavaScript SDK guide covers the server client and event fields.