Databuddy Integration

Workflow

1. Identify whether the user is integrating Databuddy in the browser, on the server, via REST API, or for LLM observability.
2. Prefer the highest-level supported API:
   • React/Vue component before custom script wiring
   • Node SDK before hand-rolled HTTP calls
   • @databuddy/ai before custom /llm instrumentation
3. Ask for or infer the minimum required credentials:
   • clientId for browser tracking and flags
   • DATABUDDY_API_KEY for server-side tracking, API access, and LLM observability
4. Give copy-pasteable setup with the correct env vars and endpoint defaults.
5. Include verification steps so the user can confirm events or API responses are working.

Core Public Defaults

• Browser/event ingestion base URL: https://basket.databuddy.cc
• LLM tracking endpoint: https://basket.databuddy.cc/llm
• Query API base URL: https://api.databuddy.cc/v1
• Feature flag API base URL: https://api.databuddy.cc
• Tracker script URL: https://cdn.databuddy.cc/databuddy.js

Credentials

• Browser SDKs usually need a clientId
• React SDK can auto-detect NEXT_PUBLIC_DATABUDDY_CLIENT_ID
• Vue examples commonly use VITE_DATABUDDY_CLIENT_ID
• Server SDKs and REST APIs use DATABUDDY_API_KEY
• Server-side website scoping may also use DATABUDDY_WEBSITE_ID or a per-event websiteId

Decision Rules

React / Next.js

• Use @databuddy/sdk/react
• Put <Databuddy /> near the app root
• Use tracker helpers from @databuddy/sdk for custom events

Vue

• Use @databuddy/sdk/vue
• Translate props to kebab-case in templates

Vanilla JS

• Use the CDN script when the app does not need a package install
• Configure behavior with data-* attributes

Server / Backend

• Use @databuddy/sdk/node
• Prefer apiKey auth
• Call flush() before exit in serverless or short-lived runtimes

Feature Flags

• Client-side flags in React use the SDK's flags helpers
• Server-side flag evaluation uses createServerFlagsManager from @databuddy/sdk/node with clientId (commonly DATABUDDY_CLIENT_ID)
• Flags are fetched from the main API host under /public/v1/flags (default base https://api.databuddy.cc), not from basket
• Feature flags need a website clientId, not API key-only auth

REST API

• Auth: x-api-key: dbdy_... (preferred), or Authorization: Bearer dbdy_...
• Query analytics from https://api.databuddy.cc/v1
• Send events to https://basket.databuddy.cc

LLM Observability

• Use @databuddy/ai for OpenAI, Anthropic, or Vercel AI SDK integrations
• Use DATABUDDY_API_KEY
• Only fall back to raw transport logic when the user needs a custom pipeline

Event Design Rules

• Track user intent, value moments, and operational outcomes, not every click by default
• Prefer a small number of stable event names with useful low-cardinality properties
• Use snake_case for event names and property keys
• Do not track PII or secrets in event properties
• Avoid high-cardinality raw values unless they are essential for a specific workflow
• If the user asks what to instrument, propose a minimal event taxonomy first instead of dumping many events into the app

Verification

• Browser SDK:
  • verify the Databuddy script loads
  • verify network requests reach basket.databuddy.cc
  • verify the correct clientId is configured
• Node SDK:
  • send one test event
  • call flush() if batching is enabled
  • confirm no auth or queue errors are logged
• REST API:
  • start with a simple authenticated query such as listing websites
  • then move to scoped analytics queries
• Feature flags:
  • wait for initialization before first read
  • test with a known flag key and user context

Response Style

• Default to practical integration guidance and working examples
• Avoid internal monorepo details unless the user is debugging Databuddy itself
• If the user says "API", determine whether they mean:
  • analytics query API
  • event ingestion endpoint
  • feature flags API
  • LLM observability endpoint