Skip to content

There is no guide for coding agents to set up server-side collection #93

Open

Description

@simpleanalytics-agent

What

Customers set up server-side collection by pasting an AI prompt into their coding agent (spec §12). That prompt is a docs page written for coding agents, next to /install.md and /events.md, plus a page for people. Both are labelled beta.

The guide:

  1. Writes the integration into the customer's repository; for Next.js it uses @simpleanalytics/next.
  2. Asks which query parameters to add to the allowed list.
  3. Warns which cached or static pages are not counted.
  4. Ends by replaying about ten example curl requests in test mode against the customer's app (ChatGPT-User, Googlebot, a normal Chrome and others) and comparing each reply with the expected one.
  5. Lists what it could not do and points to https://simpleanalytics.com/contact. Nothing is sent to us automatically.

Why

Integrations live in the customer's repository and never update, so the instructions have to produce the exact payload at the first try.

Notes

  • Agreed design: simpleanalytics/ide-config#22, sections 1 to 4 and 12. Section 14.2: whether a Cloudflare Worker can send X-Forwarded-For unchanged.
  • The test-mode reply and the Next.js function come from the queue and next issues linked below.

Activity

  1. simpleanalytics-agent commented on Nov 18, 2026

    @simpleanalytics-agent
    ContributorAuthor

    Landed on feat/server-side-collection (456f438) in draft #94. This issue closes when that PR merges.

    What the pages say now: /server-side-collection.md guides a coding agent through writing an integration, or using @simpleanalytics/next for Next.js, then replaying 12 curl requests in test mode and comparing each reply's outcome and name. /server-side-collection explains the same to people, AI agent first. Both are labelled beta.

    • Validation: two rounds. Round 1 found that content types with parameters (application/json; charset=utf-8) were not skipped; the guide now compares the media type only. The re-check passed.
    • Open decisions: (a) the guide states only what Cloudflare documents about Workers; whether a Worker's X-Forwarded-For arrives unchanged needs a test with a deployed Worker.
    • Not run: a coding agent following the guide end to end against the real queue, since /requests is not live.
    • Later: the next README and docs page should link this guide first.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions