Interaction

interactions is a marketing/sales event log, not an agent runtime event. This name has tripped people up before — read this page once before assuming anything from it.

Schema (interactions)

Column	Type	Notes
id	UUID	PK
type	enum	user_signup | demo_request | notify_request | subscription_created
userId	UUID, nullable	Set when authenticated
userEmail	text	Captured at event time (may not match current user.email)
agentId	UUID, nullable	Set for agent-scoped events
agentName	text, nullable	Denormalized for email rendering
metadata	JSONB	Event-specific extras
notifiedAt	timestamptz, nullable	When the recipient fan-out completed
notifyError	text, nullable	Error if fan-out failed
createdAt	timestamptz

What writes here

Event source	Writes type
New signup (better-auth databaseHooks.user.create.after)	user_signup
POST /agents/:id/demo-request	demo_request
POST /agents/:id/waitlist	notify_request
Stripe checkout.session.completed webhook	subscription_created

What it does

On insert, InteractionsService.record() fans out an email to every row in interaction_recipients. The send is best-effort (no retry queue). Failures update notifyError.

Recipients

interaction_recipients holds the team email addresses that get notified. Managed via:

Verb	Path	Guard
GET	/admin/interactions/recipients	platform_admin
POST	/admin/interactions/recipients	platform_admin
PATCH	/admin/interactions/recipients/:id	platform_admin
DELETE	/admin/interactions/recipients/:id	platform_admin

Email column is unique.

Reading the feed

GET /admin/interactions?type=<type>&cursor=...&limit=20 — paginated, newest first. Admin only.

DTO

type InteractionDto = {
  id: string;
  type: "user_signup" | "demo_request" | "notify_request" | "subscription_created";
  userId: string | null;
  userEmail: string;
  agentId: string | null;
  agentName: string | null;
  metadata: Record<string, unknown>;
  notifiedAt: string | null;
  notifyError: string | null;
  createdAt: string;
};

What it isn't

• Not an agent runtime event log. The marketplace does not record per-user agent activity.
• Not a usage event. Quota consumption lives in usage_ledger (see Metric Definition & Quota).
• Not a CRM. This is a thin tee into team email so launches and demos don't go silent.

For agent runtime logs, the agent service is responsible (use your own analytics — agent-poc uses PostHog directly from posthog.js).