api

package
v0.38.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 6, 2026 License: MIT Imports: 70 Imported by: 0

Documentation

Overview

Package api serves the single-binary HTTP surface: event ingestion + the server-rendered dashboard. No web framework, no SPA build step — the whole UI is embedded in the binary and rendered fast on the server (the speed IS a feature).

Index

Constants

This section is empty.

Variables

View Source 
var Version = "0.1.0"

Version is the build version (overridable at build time via -ldflags).

Functions

func EventGloss added in v0.36.0 

func EventGloss(name string) string

EventGloss is the one-time explanation for events whose LABEL alone is still not enough.

"engaged" is the case that matters: it sounds like a judgement the tool made about the visitor, and nobody can act on it without knowing the rule. Returns "" when the label speaks for itself, so callers can render a gloss only where one is owed.

func EventIsAuto added in v0.36.0 

func EventIsAuto(name string) bool

EventIsAuto reports whether the SDK writes this event by itself.

The distinction the "$" was carrying, made available as a fact instead of a sigil: it is what separates "your product has no funnel yet" from "your product's funnel is bad", and the verdict card gets that wrong in the loudest possible way when it cannot tell them apart.

func EventLabel added in v0.36.0 

func EventLabel(name string) string

EventLabel turns an event name into something a human reads without being taught the schema.

This is the single change four independent cold readers hit in every pane. The dashboard's headline metric rendered as "$pageview → $engagement → $click 8%" — a sentence in a language none of them spoke. A left-nav item was literally named "$pageview → $engagement → $click". "$crawler" appeared in a column headed VISITOR, and one reader said it looked like a person named $crawler had visited the site. Three empty states told the reader to send "$identify" without saying that was code they had to write.

The "$" prefix is real and meaningful — it marks events the SDK captures on its own, as opposed to ones the product sends deliberately — but that is a fact about our implementation, and the dashboard is not the place to teach it. Two surfaces keep the raw names because there they ARE the interface: the SQL pane and the raw event stream, where you are writing against the schema.

Deliberately a translation at the render boundary, not a rename. The stored names, the API, the SDK and every query are untouched — renaming events would break every customer's instrumentation to fix a reading problem.

Types

type PathStep added in v0.37.0 

type PathStep struct {
	Path   string `json:"path"`
	People int    `json:"people"` // distinct people who reached it, IN ORDER
}

PathStep is one page in a proposed journey, with the evidence for it.

type ProposedFunnel added in v0.37.0 

type ProposedFunnel struct {
	Steps []PathStep `json:"steps"`
	// Confident is true only when the shape looks like a funnel rather than a list of popular
	// pages: each step must genuinely narrow, and the last step must be meaningfully rarer than
	// the first. Without that test, "the three busiest pages" gets proposed as a journey and the
	// suggestion is worse than none.
	Confident bool   `json:"confident"`
	Why       string `json:"why,omitempty"`
}

ProposedFunnel is a guess at what this product's conversion actually is.

func ProposeFunnel added in v0.37.0 

func ProposeFunnel(evs []event.Event) ProposedFunnel

ProposeFunnel builds a funnel suggestion from page paths.

The rule is ORDER-AWARE: a step only counts someone who reached it AFTER the previous one, which is what makes this a journey rather than three independent page-popularity numbers. A naive version that just counted visits per page would happily propose /pricing → / → /docs, three popular pages nobody walks in that order.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

func New 

func New(s store.Store) *Server

func (*Server) EvaluateAlerts 

func (s *Server) EvaluateAlerts()

func (*Server) Handler 

func (s *Server) Handler() http.Handler

func (*Server) SetAlerts 

func (s *Server) SetAlerts(a *alert.Store)

func (*Server) SetAliases added in v0.4.0 

func (s *Server) SetAliases(a *alias.Map)

SetAliases attaches the identity-stitching map (ingest records anon→user on $identify; the MCP import tool does the same for imported history).

func (*Server) SetAudit 

func (s *Server) SetAudit(l *audit.Log)

SetAudit swaps in a persistent audit log.

func (*Server) SetCloudURL added in v0.12.1 

func (s *Server) SetCloudURL(u string)

SetCloudURL sets where the dashboard header's "Cloud ↗" link points. The hosted product passes the project's own page so a user who lands on their instance has a way back into their account. Empty (every self-hosted install) keeps the default link to smolanalytics.com, so a self-hoster never sees a cloud-specific or broken link.

func (*Server) SetCohorts 

func (s *Server) SetCohorts(st *cohort.Store)

SetCohorts swaps in a persistent cohort store (shared with MCP).

func (*Server) SetDefined added in v0.9.0 

func (s *Server) SetDefined(d *defined.Store)

SetDefined attaches the retroactive defined-events store (shared with MCP + the dashboard "save as event" builder).

func (*Server) SetDeploys added in v0.9.3 

func (s *Server) SetDeploys(d *deploys.Store)

SetDeploys attaches the store to both the HTTP server and the MCP server, so a marker recorded over HTTP is visible to the editor and vice-versa (one store, every surface). 

func (s *Server) SetExportLinks(st *exportlink.Store)

SetExportLinks attaches the one-time export-link store (minted by the create_export_link MCP tool, served by GET /export/{token}).

func (*Server) SetFlags added in v0.9.6 

func (s *Server) SetFlags(f *flag.Store)

SetFlags attaches the feature-flag store (shared with MCP + the SDK evaluate endpoint).

func (*Server) SetGSC added in v0.4.1 

func (s *Server) SetGSC(g *gsc.Store)

SetGSC attaches the Search Console store (dashboard card + MCP report).

func (*Server) SetGeo added in v0.9.1 

func (s *Server) SetGeo(g *geo.Resolver)

SetGeo enables ingest-time country resolution (the IP is used for one lookup and never stored, only the ISO code lands on the event).

func (*Server) SetGoals added in v0.4.0 

func (s *Server) SetGoals(g *goal.Store)

SetGoals attaches the goals store (dashboard card + MCP goal tools).

func (*Server) SetInsights 

func (s *Server) SetInsights(st *insights.Store)

SetInsights swaps in a persistent saved-reports store (shared with the MCP action tools, so "save this report" from the editor lands on the dashboard instantly).

func (*Server) SetMCPReadOnly added in v0.13.0 

func (s *Server) SetMCPReadOnly(v bool)

SetMCPReadOnly refuses every mutating MCP tool. The public demo serves /mcp with no credential on purpose (nothing is configured, so authorized() opens it), which also means any stranger could otherwise create flags, delete goals, mint export links or change retention on the very instance the marketing site renders.

func (*Server) SetReadKey added in v0.9.1 

func (s *Server) SetReadKey(k string)

SetReadKey sets the SECRET read/MCP key. It authorizes reads (GET /v1/* reports, the raw export) and MCP — everything that returns data. It must NEVER be embedded in client code; only the write key is public. This is what stops a scraped write key from reading data.

func (*Server) SetSettings 

func (s *Server) SetSettings(st *settings.Store)

SetSettings swaps in a persistent settings store (project, keys, session secret).

func (*Server) SetShares added in v0.4.0 

func (s *Server) SetShares(st *share.Store)

func (*Server) SetSurveys added in v0.9.9 

func (s *Server) SetSurveys(sv *survey.Store)

SetSurveys attaches the survey store (shared with MCP + the SDK active-surveys endpoint).

func (*Server) SetTrackPlan added in v0.3.0 

func (s *Server) SetTrackPlan(tp *trackplan.Store)

SetTrackPlan attaches the tracking-plan store (shared with the MCP instrumentation tools).

func (*Server) SetWebhooks 

func (s *Server) SetWebhooks(w *webhook.Store)

SetWebhooks / SetAlerts swap in the persistent notification stores (shared with MCP).

func (*Server) SetWriteKey 

func (s *Server) SetWriteKey(k string)

SetWriteKey gates event ingestion behind a write key (production). Empty = open (dev). The SDK passes the same key.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.