Docs · The event schema
The event schema.
The schema on this page runs in the first body today. It is copied from the running code, not from a design document, and every type below appears in real events in the first body’s log.
Every meaningful fact about the business is one row in an append-only log. A lead captured, a board generated, a message approved, a payment made: each is one typed event, and every table the business uses is a view computed from the log. If a fact matters and is not an event, that is treated as a bug in the code that should have emitted it. Events are constructed through a single function that validates the payload against the schema for its type before the event is written, so a malformed event cannot enter the log.
01Reference
The envelope.
Every event is wrapped in the same envelope, and the envelope is venture-agnostic: the next body imports it unchanged and contributes its own payload types.
The slug of the body that emitted the event. The first body emits video.
string
When the event happened.
ISO 8601 datetime
The event type. The shape of the payload depends on it, and every type is listed below.
string
Who caused the event.
client | agent | human | system
Present when the event is attached to a job.
string · optional
The typed payload, validated against the schema for the event’s type.
object
02Reference
The event types.
Event types are named arm.noun.verb-past, where the arm is the part of the business that produced the event, so site.lead.captured reads as: the site captured a lead. The groups below are listed in funnel order, from a visitor’s first contact down to operations.
A visitor submitted the intake form. source records how they arrived: organic, outbound, oss-video, referral, or direct.
email · productUrl · audience · goal · lengthTier? · source · name? · briefChars? · uploadCount?
The lead clicked the confirmation link that was mailed to them.
The body produced a board of candidate videos, and the event records the size, the cost, and the wall-clock time of the batch.
candidateCount · generationCostUsd · wallClockMin
A lead opened their board. The token identifies which recipient’s board it was.
token · watchedCandidates
A lead watched one candidate, and the event records how much of it they watched.
candidateId · watchPct
A lead picked a candidate from the board.
candidateId · notes?
A lead gave explicit feedback on one candidate, with an optional stated reason.
candidateId · reaction (up | down) · reason?
Feedback on the board as a whole, including from leads who never picked. The verdict is one of picked, none-fit, wrong-style, wrong-message, price, timing, or other.
verdict · note?
A customer paid for an order at one of three tiers.
tier (launch | pro | flagship) · amountUsd
The first cut of a paid order is ready, with the render cost and the human minutes it took.
renderCostUsd · humanMinutes
The customer asked for a revision. The class records whether the round is included in the tier or is a change order.
round · class (included | change-order)
The finished video was delivered, with the total cost and the total human minutes across the job.
tier · totalCostUsd · totalHumanMinutes
The eyes arm is the part of the body that publishes content and watches how it performs.
The body published a video about an open-source library.
library · platform (x | youtube) · url
A later reading of that video’s performance, including whether the library’s maintainer engaged.
library · views · likes · maintainerEngaged
The body published an article, filed under a topic cluster.
slug · cluster
A later reading of an article’s search performance.
slug · impressions · clicks
The outbound arm is the part of the body that finds prospects and writes to them. Every outbound artifact carries a unique signed token, so a view can be attributed to the exact recipient who viewed it.
The body produced a personalized teaser for a prospect, and the event records what it cost.
company · token · costUsd
A draft message was staged in the approval queue.
company · contact
The owner approved the exact text of a staged message. The actor of this event is always human.
company
The approved message was sent.
company · token
The recipient viewed the teaser, and the token attributes the view to them.
company · token · watchPct
The recipient replied, with the sentiment recorded.
company · sentiment (positive | neutral | negative)
A job moved between states.
from · to · reason?
The body wrote a note to itself and logged that it did.
file · summary
Something needs attention, at one of three severities.
severity (info | warn | page) · message