@spec align_bucket_start(DateTime.t(), map(), String.t()) :: DateTime.t()

Floors a timestamp to a bucket boundary in the given timezone.

@spec breakdown_dimensions() :: [atom()]

The supported breakdown/conversion dimensions, in declaration order.

@spec bucket_interval(%{start_at: DateTime.t(), end_at: DateTime.t()}) :: map()

Selects a bucket interval for a window from the fixed ladder.

@spec conversion_breakdown(Ecto.UUID.t(), atom(), keyword()) :: [map()]

Sale-only conversion breakdown rows for a workspace window.

Each row: %{value:, sales:, visitors:, revenue_cents:, percentage:, conversion_rate:}. conversion_rate is sale conversions over converting visitors for the bucket (a float 0.0..1.0). visitors counts distinct canonical visitors among sale events (distinct from GoodAnalytics.Core.Audience's users, which counts canonical visitors across all events). Dimension must be in breakdown_dimensions/0; unsupported dimensions raise ArgumentError. Options: :window (required), :filters.

@spec conversion_dimensions() :: [atom()]

The dimensions conversion_breakdown/3 supports, in declaration order.

@spec event_filter_fields() :: [atom()]

The allowlisted event filter fields, in declaration order.

@spec kpis(Ecto.UUID.t(), keyword()) :: map()

Raw KPI counts for one window, merged with session headline metrics.

Returns %{visitors:, new_visitors:, pageviews:, revenue:, identification_rate:, sessions:, bounce_rate:, avg_duration:, engaged_rate:}. identification_rate is the simple in-window identified-over-total canonical-visitor ratio (a float in 0.0..1.0); callers that need a matured-cohort policy or period-over-period deltas layer those on top. Options: :window (required).

@spec pageviews(Ecto.UUID.t(), keyword()) :: non_neg_integer()

Counts pageview events in a workspace window. Options: :window.

@spec revenue(Ecto.UUID.t(), keyword()) :: non_neg_integer()

Sums sale-event revenue cents in a workspace window. Options: :window.

@spec session_metrics(Ecto.UUID.t(), keyword()) :: map()

Aggregates ga_sessions for a window into rate/duration metrics and entry/exit page tallies.

Returns %{sessions:, bounce_rate:, avg_duration:, engaged_rate:, entry_pages: %{path => count}, exit_pages: %{path => count}}. Rates are floats in 0.0..1.0; an empty window yields all-zero metrics and empty page maps. Options: :window (required), :filters, :include_page_tallies (boolean, default true; pass false to return only the headline aggregate without entry_pages/exit_pages, saving two queries).

@spec timeseries(
  Ecto.UUID.t(),
  :visitors | :pageviews | :revenue | :sessions | :engaged,
  keyword()
) ::
  [map()]

Returns zero-filled, timezone-aligned buckets for chart rendering.

Supported metrics are :visitors, :pageviews, :revenue, :sessions, and :engaged. Options: :window (%{start_at:, end_at:}, required), :timezone (string, default "Etc/UTC"), :bucket_interval (from bucket_interval/1, default derived from the window), :filters (keyword of {event_field, value} restricted to event_filter_fields/0).