Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.
TypeScript analyticsanalytics-dashboardclickhouseelixirgoogle-analyticsmarketingopen-source-analyticsphoenixplausible-analyticspostgresqlprivacyprivacy-friendlyself-hostedsimple-analyticsstatisticstailwindcssweb-analyticswebsite-analyticswebsite-statswebsite-tracking
Annotations: BE (#6478)
Artur Pata3d135c9a5345
diff --git a/lib/plausible/annotations/annotation.ex b/lib/plausible/annotations/annotation.exnew file mode 100644index 0000000000..b01e13bd61--- /dev/null+++ b/lib/plausible/annotations/annotation.ex@@ -0,0 +1,206 @@+defmodule Plausible.Annotations.Annotation do+ @moduledoc """+ Schema for annotations. Annotations are notes attached to a point on the graph.++ Annotations can have two granularities, date or minute.++ To create date granularity annotations, only the date part must be specified for `datetime` field.+ It's interpreted to be for that date, no matter what happens with the site timezone.++ Examples:+ - `{"granularity": "date", "datetime": "2026-06-30", ...}`.++ To create minute granularity annotations, the full datetime needs to be specified for `datetime` field.+ It can be set in local time, as a naive datetime string ("2026-06-29 10:00:00"), in which case it's+ interpreted as that datetime in the site's timezone and stored as that particular moment in UTC.+ Alternatively, it can be sent with TZ information ("2026-05-31T12:00:00Z", "2026-05-31T10:00:00-02:00"),+ in which case it's interpreted to be that particular moment and stored as that in UTC.++ Examples:+ - `{"granularity": "minute", "datetime": "2026-06-29 10:00:00", ...}`+ - `{"granularity": "minute", "datetime": "2026-06-29T12:00:00Z", ...}`+ """++ use Plausible+ use Ecto.Schema+ import Ecto.Changeset++ @annotation_types [:personal, :site]+ @annotation_granularities [:date, :minute]++ @type t() :: %__MODULE__{}++ schema "annotations" do+ field :note, :string+ field :type, Ecto.Enum, values: @annotation_types+ field :date, :date, virtual: true+ field :datetime, :utc_datetime+ field :granularity, Ecto.Enum, values: @annotation_granularities++ # owner ID can be null (aka note is dangling) when the original owner is deassociated from the site+ # the note is dangling until another user edits it: the editor becomes the new owner+ belongs_to :owner, Plausible.Auth.User, foreign_key: :owner_id+ belongs_to :site, Plausible.Site++ timestamps()+ end++ def create_changeset(attrs, site, owner) do+ %__MODULE__{}+ |> changeset(attrs, site.timezone)+ |> put_assoc(:site, site)+ |> put_assoc(:owner, owner)+ end++ def update_changeset(annotation, attrs, owner) do+ changeset =+ annotation+ |> changeset(attrs, annotation.site.timezone)++ # Users that can edit site annotations can edit+ # 1) dangling site annotations (owner_id: nil),+ # 2) site annotations owned by other users,+ # in both cases becoming the new owners.+ case fetch_field!(changeset, :owner_id) do+ nil -> changeset |> put_assoc(:owner, owner)+ # This case works around Ecto's limitations in overwriting owner association+ _ -> changeset |> put_change(:owner_id, owner.id)+ end+ end++ def changeset(annotation, attrs, site_timezone) do+ annotation+ |> cast(attrs, [:note, :type])+ |> cast(attrs, [:date, :datetime, :granularity], force_changes: true)+ |> validate_required([:note, :type, :granularity])+ |> validate_length(:note, count: :bytes, min: 1, max: 255)+ |> maybe_coerce_naive_datetime(site_timezone)+ |> coerce_datetime()+ end++ # If `datetime` is a naive ISO 8601 string (no UTC offset or Z suffix), interpret+ # it as a local time in the site's timezone and convert to UTC before the changeset+ # runs. This lets callers supply times in their local context without manually+ # computing offsets.+ #+ # DST edge cases:+ # - gap (spring-forward): the missing hour is resolved to just-after the gap+ # - ambiguous (fall-back): the earlier of the two possibilities is used+ #+ # All other `datetime` values (bare dates, full UTC strings, invalid strings) pass+ # through unchanged and are handled downstream by the changeset.+ defp maybe_coerce_naive_datetime(changeset, timezone) do+ with false <- is_nil(get_change(changeset, :datetime)),+ dt when is_binary(dt) <- changeset.params["datetime"],+ {:error, _} <- DateTime.from_iso8601(dt),+ {:ok, naive_dt} <- NaiveDateTime.from_iso8601(dt) do+ case DateTime.from_naive(naive_dt, timezone) do+ {:ok, local_dt} ->+ force_change(changeset, :datetime, to_utc(local_dt))++ {:ambiguous, first, _second} ->+ force_change(changeset, :datetime, to_utc(first))++ {:gap, _just_before, just_after} ->+ force_change(changeset, :datetime, to_utc(just_after))++ {:error, _} ->+ add_error(+ changeset,+ :datetime,+ "cannot be parsed for the site timezone \"#{timezone}\""+ )+ end+ else+ _ -> changeset+ end+ end++ defp to_utc(%DateTime{} = dt), do: DateTime.shift_zone!(dt, "Etc/UTC")++ defp coerce_datetime(%{valid?: true} = changeset) do+ granularity = get_change(changeset, :granularity)+ datetime = get_change(changeset, :datetime)+ date = get_change(changeset, :date)++ case coerce_for_granularity(granularity, date, datetime) do+ {:ok, %DateTime{} = utc_dt} ->+ put_change(changeset, :datetime, utc_dt)++ {:error, :not_supplied, field} ->+ add_error(changeset, field, "must be supplied for chosen granularity")++ {:error, :both_set} ->+ add_error(changeset, :granularity, "expects either date or datetime to be set")++ :skip ->+ changeset+ end+ end++ defp coerce_datetime(changeset), do: changeset++ defp coerce_for_granularity(:date, %Date{} = date, nil),+ do: {:ok, serialize_date_granularity_datetime(date)}++ defp coerce_for_granularity(:minute, nil, %DateTime{} = dt),+ do: {:ok, dt}++ defp coerce_for_granularity(:date, nil, _),+ do: {:error, :not_supplied, :date}++ defp coerce_for_granularity(:minute, _, nil),+ do: {:error, :not_supplied, :datetime}++ defp coerce_for_granularity(granularity, _date, _datetime)+ when granularity in [:date, :minute],+ do: {:error, :both_set}++ defp coerce_for_granularity(_granularity, _date, _datetime), do: :skip++ def serialize_date_granularity_datetime(%Date{} = date),+ do: DateTime.new!(date, ~T[00:00:00], "Etc/UTC")++ # Used only by encoder+ @doc false+ def localize(annotation, timezone)++ # For date granularity, the UTC date component IS the annotation date — callers+ # store UTC midnight of their intended local date, so no timezone shift is needed.+ # Return just the Date so the JSON response matches the bare-date input format.+ def localize(%{granularity: :date} = annotation, _timezone) do+ %{annotation | datetime: parse_date_granularity_datetime(annotation.datetime)}+ end++ # For minute granularity, shift the stored UTC moment to the site's local timezone+ # and strip the offset so the response is a naive local time string.+ def localize(%{granularity: :minute} = annotation, timezone) do+ naive_local =+ annotation.datetime+ |> DateTime.shift_zone!(timezone)+ |> DateTime.to_naive()++ %{annotation | datetime: naive_local}+ end++ defp parse_date_granularity_datetime(%DateTime{} = datetime),+ do: DateTime.to_date(datetime)+end++defimpl Jason.Encoder, for: Plausible.Annotations.Annotation do+ def encode(annotation, opts) do+ %{+ id: annotation.id,+ note: annotation.note,+ type: annotation.type,+ datetime: annotation.datetime,+ granularity: annotation.granularity,+ owner_id: annotation.owner_id,+ owner_name: if(annotation.owner_id, do: annotation.owner.name),+ inserted_at: annotation.inserted_at,+ updated_at: annotation.updated_at+ }+ |> Plausible.Annotations.Annotation.localize(annotation.site.timezone)+ |> Jason.Encode.map(opts)+ end+enddiff --git a/lib/plausible/annotations/annotations.ex b/lib/plausible/annotations/annotations.exnew file mode 100644index 0000000000..64d38b0387--- /dev/null+++ b/lib/plausible/annotations/annotations.ex@@ -0,0 +1,340 @@+defmodule Plausible.Annotations do+ @moduledoc """+ Module for accessing Annotations.+ """+ alias Plausible.Annotations.Annotation+ alias Plausible.Auth.User+ alias Plausible.Repo+ alias Plausible.Stats.DateTimeRange+ import Ecto.Query++ @roles_with_personal_annotations [:billing, :viewer, :editor, :admin, :owner, :super_admin]+ @roles_with_maybe_site_annotations [:editor, :admin, :owner, :super_admin]++ @type error_not_enough_permissions() :: :not_enough_permissions+ @type error_annotation_not_found() :: :annotation_not_found+ @type error_annotation_limit_reached() :: :annotations_limit_reached+ @type error_invalid_annotation() :: {:invalid_annotation, Keyword.t()}++ @max_annotations 500++ @spec roles_with_personal_annotations() :: [atom()]+ def roles_with_personal_annotations(), do: @roles_with_personal_annotations++ @spec roles_with_maybe_site_annotations() :: [atom()]+ def roles_with_maybe_site_annotations(), do: @roles_with_maybe_site_annotations++ @spec site_annotations_available?(Plausible.Site.t()) :: boolean()+ def site_annotations_available?(site),+ # this feature is bundled with SiteSegments+ do: Plausible.Billing.Feature.SiteSegments.check_availability(site.team) == :ok++ @spec get_all_for_site(Plausible.Site.t(), atom(), User.t() | nil, DateTimeRange.t()) ::+ {:error, error_not_enough_permissions()} | {:ok, list(Annotation.t())}+ def get_all_for_site(site, site_role, user, range_in_site_tz) do+ fields = [:id, :note, :type, :datetime, :granularity, :site_id, :inserted_at, :updated_at]++ cond do+ site_role in [:public] ->+ annotations =+ Repo.all(+ from(annotation in Annotation,+ inner_join: site in assoc(annotation, :site),+ select: ^fields,+ where: annotation.site_id == ^site.id,+ where: annotation.type == :site,+ order_by: [desc: annotation.updated_at, desc: annotation.id],+ preload: [site: site]+ )+ |> filter_by_range(range_in_site_tz)+ )++ {:ok, annotations}++ site_role in roles_with_personal_annotations() or+ site_role in roles_with_maybe_site_annotations() ->+ fields = fields ++ [:owner_id]++ annotations =+ Repo.all(+ from(annotation in Annotation,+ inner_join: site in assoc(annotation, :site),+ left_join: owner in assoc(annotation, :owner),+ select: ^fields,+ where: annotation.site_id == ^site.id,+ where:+ annotation.type == :site or+ (annotation.type == :personal and annotation.owner_id == ^user.id),+ order_by: [desc: annotation.updated_at, desc: annotation.id],+ preload: [site: site, owner: owner]+ )+ |> filter_by_range(range_in_site_tz)+ )++ {:ok, annotations}++ true ->+ {:error, :not_enough_permissions}+ end+ end++ @spec get_one(User.t() | nil, Plausible.Site.t(), atom(), pos_integer() | nil) ::+ {:ok, Annotation.t()}+ | {:error, error_not_enough_permissions() | error_annotation_not_found()}+ def get_one(nil, _site, _site_role, _annotation_id) do+ {:error, :not_enough_permissions}+ end++ def get_one(user, site, site_role, annotation_id) do+ if site_role in roles_with_personal_annotations() do+ case do_get_one(user, site, annotation_id) do+ %Annotation{} = annotation -> {:ok, annotation}+ nil -> {:error, :annotation_not_found}+ end+ else+ {:error, :not_enough_permissions}+ end+ end++ @spec insert_one(User.t() | nil, Plausible.Site.t(), atom(), map()) ::+ {:ok, Annotation.t()}+ | {:error,+ error_not_enough_permissions()+ | error_invalid_annotation()+ | error_annotation_limit_reached()}+ def insert_one(nil, _site, _site_role, _params) do+ {:error, :not_enough_permissions}+ end++ def insert_one(user, site, site_role, params) do+ changeset = Annotation.create_changeset(params, site, user)+ annotation_type = Ecto.Changeset.get_field(changeset, :type)++ with :ok <- can_insert_one?(site, site_role, annotation_type),+ {:ok, annotation} <- Repo.insert(changeset) do+ {:ok, Repo.preload(annotation, [:site, :owner])}+ else+ {:error, %Ecto.Changeset{errors: errors}} ->+ {:error, {:invalid_annotation, errors}}++ {:error, _type} = error ->+ error+ end+ end++ @spec update_one(User.t() | nil, Plausible.Site.t(), atom(), pos_integer(), map()) ::+ {:ok, Annotation.t()}+ | {:error,+ error_not_enough_permissions()+ | error_invalid_annotation()+ | error_annotation_not_found()}+ def update_one(nil, _site, _site_role, _annotation_id, _params) do+ {:error, :not_enough_permissions}+ end++ def update_one(user, site, site_role, annotation_id, params) do+ with {:ok, annotation} <- get_one(user, site, site_role, annotation_id),+ changeset = Annotation.update_changeset(annotation, params, user),+ new_annotation_type = Ecto.Changeset.get_field(changeset, :type),+ :ok <- can_update_one?(site, site_role, new_annotation_type, annotation.type),+ {:ok, annotation} <- Repo.update(changeset) do+ {:ok, Repo.preload(annotation, [:site, :owner])}+ else+ {:error, %Ecto.Changeset{errors: errors}} ->+ {:error, {:invalid_annotation, errors}}++ {:error, _type} = error ->+ error+ end+ end++ @spec delete_one(User.t() | nil, Plausible.Site.t(), atom(), pos_integer()) ::+ {:ok, Annotation.t()}+ | {:error,+ error_not_enough_permissions()+ | error_annotation_not_found()}+ def delete_one(nil, _site, _site_role, _annotation_id) do+ {:error, :not_enough_permissions}+ end++ def delete_one(user, site, site_role, annotation_id) do+ with {:ok, annotation} <- get_one(user, site, site_role, annotation_id) do+ cond do+ annotation.type == :site and site_role in roles_with_maybe_site_annotations() ->+ {:ok, do_delete_one(annotation)}++ annotation.type == :personal and site_role in roles_with_personal_annotations() ->+ {:ok, do_delete_one(annotation)}++ true ->+ {:error, :not_enough_permissions}+ end+ end+ end++ @spec after_user_removed_from_site(Plausible.Site.t(), User.t()) :: :ok+ def after_user_removed_from_site(site, user) do+ Repo.delete_all(+ from(annotation in Annotation,+ where: annotation.site_id == ^site.id,+ where: annotation.owner_id == ^user.id,+ where: annotation.type == :personal+ )+ )++ Repo.update_all(+ from(annotation in Annotation,+ where: annotation.site_id == ^site.id,+ where: annotation.owner_id == ^user.id,+ where: annotation.type == :site,+ update: [set: [owner_id: nil]]+ ),+ []+ )++ :ok+ end++ @spec after_user_removed_from_team(Plausible.Teams.Team.t(), User.t()) :: :ok+ def after_user_removed_from_team(team, user) do+ team_sites_q =+ from(+ site in Plausible.Site,+ where: site.team_id == ^team.id,+ where: parent_as(:annotation).site_id == site.id+ )++ Repo.delete_all(+ from(annotation in Annotation,+ as: :annotation,+ where: annotation.owner_id == ^user.id,+ where: annotation.type == :personal,+ where: exists(team_sites_q)+ )+ )++ Repo.update_all(+ from(annotation in Annotation,+ as: :annotation,+ where: annotation.owner_id == ^user.id,+ where: annotation.type == :site,+ where: exists(team_sites_q),+ update: [set: [owner_id: nil]]+ ),+ []+ )++ :ok+ end++ @spec user_removed(User.t()) :: :ok+ def user_removed(user) do+ Repo.delete_all(+ from(annotation in Annotation,+ as: :annotation,+ where: annotation.owner_id == ^user.id,+ where: annotation.type == :personal+ )+ )++ # Site annotations are set to owner=null via ON DELETE SET NULL++ :ok+ end++ defp filter_by_range(query, range_in_site_tz) do+ # Minute granularity annotations are stored for the particular UTC moment they're for,+ # so they must be in the range of the UTC query period.+ minute_granularity_range =+ range_in_site_tz |> DateTimeRange.to_timezone("Etc/UTC")++ # Date granularity annotations are stored for the UTC midnight of the date they're for,+ # so the range for querying these must reflect that.+ [date_granularity_range_first, date_granularity_range_last] =+ [range_in_site_tz.first, range_in_site_tz.last]+ |> Enum.map(fn utc_datetime ->+ utc_datetime |> DateTime.to_date() |> Annotation.serialize_date_granularity_datetime()+ end)++ from(annotation in query,+ where:+ (annotation.granularity == :minute and+ annotation.datetime >= ^minute_granularity_range.first and+ annotation.datetime <= ^minute_granularity_range.last) or+ (annotation.granularity == :date and+ annotation.datetime >=+ ^date_granularity_range_first and+ annotation.datetime <=+ ^date_granularity_range_last)+ )+ end++ defp do_get_one(user, site, annotation_id)++ defp do_get_one(_user, _site, nil) do+ nil+ end++ defp do_get_one(user, site, annotation_id) do+ query =+ from(annotation in Annotation,+ where: annotation.site_id == ^site.id,+ where: annotation.id == ^annotation_id,+ where:+ annotation.type == :site or+ (annotation.type == :personal and annotation.owner_id == ^user.id),+ preload: [:site, :owner]+ )++ Repo.one(query)+ end++ defp do_delete_one(annotation) do+ annotation+ |> Repo.preload([:site, :owner])+ |> Repo.delete!()+ end++ defp can_update_one?(site, site_role, new_annotation_type, existing_annotation_type) do+ updating_to_site_annotation? = new_annotation_type == :site++ cond do+ (existing_annotation_type == :site or+ updating_to_site_annotation?) and site_role in roles_with_maybe_site_annotations() and+ site_annotations_available?(site) ->+ :ok++ existing_annotation_type == :personal and not updating_to_site_annotation? and+ site_role in roles_with_personal_annotations() ->+ :ok++ true ->+ {:error, :not_enough_permissions}+ end+ end++ defp can_insert_one?(site, site_role, annotation_type) do+ cond do+ count_annotations(site.id) >= @max_annotations ->+ {:error, :annotations_limit_reached}++ annotation_type == :site and site_role in roles_with_maybe_site_annotations() and+ site_annotations_available?(site) ->+ :ok++ annotation_type == :personal and+ site_role in roles_with_personal_annotations() ->+ :ok++ true ->+ {:error, :not_enough_permissions}+ end+ end++ defp count_annotations(site_id) do+ from(annotation in Annotation,+ where: annotation.site_id == ^site_id+ )+ |> Repo.aggregate(:count, :id)+ end+enddiff --git a/lib/plausible/helpers/changeset.ex b/lib/plausible/helpers/changeset.exindex e7b6d88221..41fb055689 100644--- a/lib/plausible/helpers/changeset.ex+++ b/lib/plausible/helpers/changeset.ex@@ -10,4 +10,25 @@ defmodule Plausible.ChangesetHelpers doend)end)end++ @doc """+ iex> serialize_first_error([{"name", {"should be at most %{count} byte(s)", [count: 255]}}])+ "name should be at most 255 byte(s)"+ """+ def serialize_first_error(errors) do+ {field, {message, opts}} = List.first(errors)++ formatted_message =+ Enum.reduce(opts, message, fn {key, value}, acc ->+ placeholder = "%{#{key}}"++ if String.contains?(acc, placeholder) do+ String.replace(acc, placeholder, to_string(value))+ else+ acc+ end+ end)++ "#{field} #{formatted_message}"+ endenddiff --git a/lib/plausible/segments/segments.ex b/lib/plausible/segments/segments.exindex de247316b4..8b1556e41c 100644--- a/lib/plausible/segments/segments.ex+++ b/lib/plausible/segments/segments.ex@@ -461,19 +461,4 @@ defmodule Plausible.Segments dodef site_segments_available?(%Plausible.Site{} = site),do: Plausible.Billing.Feature.SiteSegments.check_availability(site.team) == :ok-- @doc """- iex> serialize_first_error([{"name", {"should be at most %{count} byte(s)", [count: 255]}}])- "name should be at most 255 byte(s)"- """- def serialize_first_error(errors) do- {field, {message, opts}} = List.first(errors)-- formatted_message =- Enum.reduce(opts, message, fn {key, value}, acc ->- String.replace(acc, "%{#{key}}", to_string(value))- end)-- "#{field} #{formatted_message}"- endenddiff --git a/lib/plausible/teams/memberships.ex b/lib/plausible/teams/memberships.exindex 26460c8af3..b318642256 100644--- a/lib/plausible/teams/memberships.ex+++ b/lib/plausible/teams/memberships.ex@@ -167,6 +167,7 @@ defmodule Plausible.Teams.Memberships doRepo.delete!(guest_membership)prune_guests(guest_membership.team_membership.team)Plausible.Segments.after_user_removed_from_site(site, user)+ Plausible.Annotations.after_user_removed_from_site(site, user)end)send_site_member_removed_email(guest_membership)diff --git a/lib/plausible/teams/memberships/leave.ex b/lib/plausible/teams/memberships/leave.exindex c0b94fdb51..18436fcf6b 100644--- a/lib/plausible/teams/memberships/leave.ex+++ b/lib/plausible/teams/memberships/leave.ex@@ -22,6 +22,11 @@ defmodule Plausible.Teams.Memberships.Leave doteam_membership.team,team_membership.user)++ Plausible.Annotations.after_user_removed_from_team(+ team_membership.team,+ team_membership.user+ )end)if Keyword.get(opts, :send_email?, true) dodiff --git a/lib/plausible/teams/memberships/remove.ex b/lib/plausible/teams/memberships/remove.exindex 28bf1eedbf..52261f3650 100644--- a/lib/plausible/teams/memberships/remove.ex+++ b/lib/plausible/teams/memberships/remove.ex@@ -23,6 +23,11 @@ defmodule Plausible.Teams.Memberships.Remove doteam_membership.team,team_membership.user)++ Plausible.Annotations.after_user_removed_from_team(+ team_membership.team,+ team_membership.user+ )end)if Keyword.get(opts, :send_email?, true) dodiff --git a/lib/plausible/timezones.ex b/lib/plausible/timezones.exindex 030c41c95b..1998f90a03 100644--- a/lib/plausible/timezones.ex+++ b/lib/plausible/timezones.ex@@ -8,6 +8,9 @@ defmodule Plausible.Timezones doTimex.is_valid_timezone?(tz)end+ @spec zone_list() :: [String.t()]+ def zone_list, do: Tzdata.zone_list()+@spec options(DateTime.t()) :: [{:key, String.t()}, {:value, String.t()}, {:offset, integer()}]def options(now \\ DateTime.utc_now()) doTzdata.zone_list()diff --git a/lib/plausible_web/controllers/api/internal/annotations_controller.ex b/lib/plausible_web/controllers/api/internal/annotations_controller.exnew file mode 100644index 0000000000..bbd1dac6fd--- /dev/null+++ b/lib/plausible_web/controllers/api/internal/annotations_controller.ex@@ -0,0 +1,149 @@+defmodule PlausibleWeb.Api.Internal.AnnotationsController do+ @moduledoc """+ Internal API controller for annotations.+ """+ use Plausible+ use PlausibleWeb, :controller+ use PlausibleWeb.Plugs.ErrorHandler+ alias Plausible.Annotations+ alias Plausible.ChangesetHelpers+ alias Plausible.Stats.{ApiQueryParser, QueryPeriod}+ alias PlausibleWeb.Api.Helpers, as: H++ plug(PlausibleWeb.Plugs.FeatureFlagCheckPlug, [:annotations])++ def index(conn, params) do+ user = conn.assigns.current_user+ site = conn.assigns.site+ site_role = conn.assigns.site_role++ with {:ok, input_date_range} <- parse_input_date_range(params),+ {:ok, relative_date} <- parse_relative_date(params) do+ now = DateTime.utc_now(:second)++ range_in_site_tz =+ QueryPeriod.build_range_for_site(input_date_range, site, relative_date, now)++ case Annotations.get_all_for_site(site, site_role, user, range_in_site_tz) do+ {:ok, result} ->+ json(conn, result)++ {:error, :not_enough_permissions} ->+ json(conn, "Not enough permissions to get annotations")+ end+ else+ {:error, message} -> H.bad_request(conn, message)+ end+ end++ defp parse_input_date_range(%{+ "date_range_start" => start,+ "date_range_end" => end_+ })+ when is_binary(start) and is_binary(end_) do+ case ApiQueryParser.parse_input_date_range([start, end_]) do+ {:ok, parsed} -> {:ok, parsed}+ {:error, %{message: message}} -> {:error, message}+ end+ end++ defp parse_input_date_range(%{"date_range" => "realtime"}), do: {:ok, :realtime}+ defp parse_input_date_range(%{"date_range" => "realtime_30m"}), do: {:ok, :realtime_30m}++ defp parse_input_date_range(%{"date_range" => date_range}) do+ case ApiQueryParser.parse_input_date_range(date_range) do+ {:ok, parsed} -> {:ok, parsed}+ {:error, %{message: message}} -> {:error, message}+ end+ end++ defp parse_input_date_range(_), do: {:error, "Required 'date_range' parameter missing"}++ defp parse_relative_date(%{"relative_date" => date}) when is_binary(date) do+ case Date.from_iso8601(date) do+ {:ok, date} -> {:ok, date}+ _ -> {:error, "Failed to convert '#{date}' to date"}+ end+ end++ defp parse_relative_date(_), do: {:ok, nil}++ def create(conn, params) do+ user = conn.assigns.current_user+ site = conn.assigns.site+ site_role = conn.assigns.site_role++ case Annotations.insert_one(user, site, site_role, params) do+ {:error, :not_enough_permissions} ->+ H.not_enough_permissions(conn, "Not enough permissions to create annotation")++ {:error, :annotations_limit_reached} ->+ H.not_enough_permissions(conn, "Annotations limit reached")++ {:error, {:invalid_annotation, errors}} when is_list(errors) ->+ conn+ |> put_status(400)+ |> json(%{+ error: ChangesetHelpers.serialize_first_error(errors)+ })++ {:ok, annotation} ->+ json(conn, annotation)+ end+ end++ def update(conn, params) do+ user = conn.assigns.current_user+ site = conn.assigns.site+ site_role = conn.assigns.site_role+ annotation_id = normalize_annotation_id_param(params["annotation_id"])++ case Annotations.update_one(user, site, site_role, annotation_id, params) do+ {:error, :not_enough_permissions} ->+ H.not_enough_permissions(conn, "Not enough permissions to edit annotation")++ {:error, :annotation_not_found} ->+ annotation_not_found(conn, params["annotation_id"])++ {:error, {:invalid_annotation, errors}} when is_list(errors) ->+ conn+ |> put_status(400)+ |> json(%{+ error: ChangesetHelpers.serialize_first_error(errors)+ })++ {:ok, annotation} ->+ json(conn, annotation)+ end+ end++ def delete(conn, params) do+ user = conn.assigns.current_user+ site = conn.assigns.site+ site_role = conn.assigns.site_role+ annotation_id = normalize_annotation_id_param(params["annotation_id"])++ case Annotations.delete_one(user, site, site_role, annotation_id) do+ {:error, :not_enough_permissions} ->+ H.not_enough_permissions(conn, "Not enough permissions to delete annotation")++ {:error, :annotation_not_found} ->+ annotation_not_found(conn, params["annotation_id"])++ {:ok, annotation} ->+ json(conn, annotation)+ end+ end++ @spec normalize_annotation_id_param(any()) :: nil | pos_integer()+ defp normalize_annotation_id_param(input) do+ case Integer.parse(input) do+ {int_value, ""} when int_value > 0 -> int_value+ _ -> nil+ end+ end++ defp annotation_not_found(%Plug.Conn{} = conn, annotation_id_param) do+ H.not_found(conn, "Annotation not found with ID #{inspect(annotation_id_param)}")+ end+enddiff --git a/lib/plausible_web/controllers/api/internal/segments_controller.ex b/lib/plausible_web/controllers/api/internal/segments_controller.exindex 30e55c336c..623ebf8788 100644--- a/lib/plausible_web/controllers/api/internal/segments_controller.ex+++ b/lib/plausible_web/controllers/api/internal/segments_controller.ex@@ -6,6 +6,7 @@ defmodule PlausibleWeb.Api.Internal.SegmentsController douse PlausibleWeb, :controlleruse PlausibleWeb.Plugs.ErrorHandleralias PlausibleWeb.Api.Helpers, as: H+ alias Plausible.ChangesetHelpersalias Plausible.Segmentsdef create(@@ -29,7 +30,7 @@ defmodule PlausibleWeb.Api.Internal.SegmentsController doconn|> put_status(400)|> json(%{- error: Segments.serialize_first_error(errors)+ error: ChangesetHelpers.serialize_first_error(errors)}){:ok, segment} ->@@ -63,7 +64,7 @@ defmodule PlausibleWeb.Api.Internal.SegmentsController doconn|> put_status(400)|> json(%{- error: Segments.serialize_first_error(errors)+ error: ChangesetHelpers.serialize_first_error(errors)}){:ok, segment} ->diff --git a/lib/plausible_web/plugs/feature_flag_check_plug.ex b/lib/plausible_web/plugs/feature_flag_check_plug.exnew file mode 100644index 0000000000..c04e23e38d--- /dev/null+++ b/lib/plausible_web/plugs/feature_flag_check_plug.ex@@ -0,0 +1,31 @@+defmodule PlausibleWeb.Plugs.FeatureFlagCheckPlug do+ @moduledoc """+ plug(PlausibleWeb.Plugs.FeatureFlagCheckPlug, [:flag_foo, :flag_bar])+ to halt any API connections with 404 where conn.assigns.current_user or conn.assigns.site+ don't have both feature flags true.+ """+ def init(feature_flags) when is_list(feature_flags) and length(feature_flags) > 0 do+ feature_flags+ end++ def init(_),+ do: raise(ArgumentError, "The first argument must be a non-empty list of feature flags")++ def call(%Plug.Conn{} = conn, flags) do+ if validate(conn.assigns[:current_user], conn.assigns.site, flags) do+ conn+ else+ PlausibleWeb.Api.Helpers.not_found(conn, "Not found")+ end+ end++ defp validate(nil = _current_user, site, flags),+ do: Enum.all?(flags, fn flag -> FunWithFlags.enabled?(flag, for: site) end)++ defp validate(current_user, site, flags),+ do:+ Enum.all?(flags, fn flag ->+ FunWithFlags.enabled?(flag, for: current_user) ||+ FunWithFlags.enabled?(flag, for: site)+ end)+enddiff --git a/lib/plausible_web/router.ex b/lib/plausible_web/router.exindex d91ed83205..a6939bfef3 100644--- a/lib/plausible_web/router.ex+++ b/lib/plausible_web/router.ex@@ -303,6 +303,14 @@ defmodule PlausibleWeb.Router dodelete "/:segment_id", SegmentsController, :deleteget "/:segment_id/shared-links", SegmentsController, :get_related_shared_linksend++ scope "/:domain/annotations", PlausibleWeb.Api.Internal,+ private: %{allow_consolidated_views: true} do+ get "/", AnnotationsController, :index+ post "/", AnnotationsController, :create+ patch "/:annotation_id", AnnotationsController, :update+ delete "/:annotation_id", AnnotationsController, :delete+ endendscope "/api/v1/stats", PlausibleWeb.Api,diff --git a/lib/plausible_web/templates/stats/stats.html.heex b/lib/plausible_web/templates/stats/stats.html.heexindex 633430e04a..6a8058bb7d 100644--- a/lib/plausible_web/templates/stats/stats.html.heex+++ b/lib/plausible_web/templates/stats/stats.html.heex@@ -26,8 +26,9 @@data-props-available={to_string(Plausible.Billing.Feature.Props.check_availability(@site.team) == :ok)}- data-site-segments-available={- to_string(Plausible.Billing.Feature.SiteSegments.check_availability(@site.team) == :ok)+ data-site-segments-available={to_string(Plausible.Segments.site_segments_available?(@site))}+ data-site-annotations-available={+ to_string(Plausible.Annotations.site_annotations_available?(@site))}data-revenue-goals={Jason.encode!(@revenue_goals)}data-funnels={Jason.encode!(@funnels)}diff --git a/test/plausible/annotations/annotation_test.exs b/test/plausible/annotations/annotation_test.exsnew file mode 100644index 0000000000..07b30ecdef--- /dev/null+++ b/test/plausible/annotations/annotation_test.exs@@ -0,0 +1,163 @@+defmodule Plausible.Annotations.AnnotationTest do+ use ExUnit.Case, async: true+ alias Plausible.Annotations.Annotation++ describe "changeset/3 for date granularity" do+ for {dt, expected_errors} <- [+ {"2026-06-30T00:00:00", [date: {"must be supplied for chosen granularity", []}]},+ {"2026-06-30T00:00:00Z", [date: {"must be supplied for chosen granularity", []}]},+ {~U[2026-06-30 14:30:00Z], [date: {"must be supplied for chosen granularity", []}]},+ {"2026-07-05", [datetime: {"is invalid", [type: :utc_datetime, validation: :cast]}]},+ {~D[2026-07-06], [datetime: {"is invalid", [type: :utc_datetime, validation: :cast]}]}+ ] do+ test "rejects datetime #{dt} with appropriate error" do+ changeset =+ Annotation.changeset(+ %Annotation{},+ %{+ note: "feature released",+ type: "personal",+ granularity: "date",+ datetime: unquote(Macro.escape(dt))+ },+ "Etc/UTC"+ )++ assert changeset.errors == unquote(Macro.escape(expected_errors))+ end+ end++ test "rejects invalid date value" do+ changeset =+ Annotation.changeset(+ %Annotation{},+ %{+ note: "feature released",+ type: "personal",+ granularity: "date",+ date: "2026-13-45"+ },+ "Etc/UTC"+ )++ assert [date: {"is invalid", _}] = changeset.errors+ end++ for {d, expected} <- [+ {"2026-06-30", ~U[2026-06-30 00:00:00Z]},+ {~D[2026-07-01], ~U[2026-07-01 00:00:00Z]}+ ] do+ test "accepts date #{d}, parsing it to that date at UTC midnight (#{expected})" do+ changeset =+ Annotation.changeset(+ %Annotation{},+ %{+ note: "feature released",+ type: "personal",+ granularity: "date",+ date: unquote(Macro.escape(d))+ },+ Enum.random(Plausible.Timezones.zone_list())+ )++ assert changeset.valid?+ assert changeset.changes.datetime == unquote(Macro.escape(expected))+ end+ end+ end++ describe "changeset/3 for minute granularity" do+ for d <- ["2026-07-05", ~D[2026-07-06]] do+ test "requires :datetime to be present, given date: #{d}" do+ changeset =+ Annotation.changeset(+ %Annotation{},+ %{+ note: "feature released",+ type: "personal",+ granularity: "minute",+ date: unquote(Macro.escape(d))+ },+ "Etc/UTC"+ )++ assert changeset.errors == [datetime: {"must be supplied for chosen granularity", []}]+ end+ end++ for {dt, tz, message} <- [+ {"2026-06-30", "Etc/UTC", "is invalid"},+ {~D[2026-07-01], "Etc/UTC", "is invalid"},+ {"invalid", "Etc/UTC", "is invalid"},+ {"2026-06-30T14:30:00", "Invalid/Timezone",+ "cannot be parsed for the site timezone \"Invalid/Timezone\""}+ ] do+ test "rejects invalid :datetime, given #{dt} for timezone #{tz}" do+ changeset =+ Annotation.changeset(+ %Annotation{},+ %{+ note: "feature released",+ type: "personal",+ granularity: "minute",+ datetime: unquote(Macro.escape(dt))+ },+ unquote(tz)+ )++ assert [datetime: {unquote(message), _}] = changeset.errors+ end+ end++ for {dt, expected, tz} <- [+ {"2026-06-30T14:30:00Z", ~U[2026-06-30 14:30:00Z],+ Enum.random(Plausible.Timezones.zone_list())},+ {"2026-06-30T10:00:00-02:00", ~U[2026-06-30 12:00:00Z],+ Enum.random(Plausible.Timezones.zone_list())},+ {~U[2026-06-30 14:30:00Z], ~U[2026-06-30 14:30:00Z],+ Enum.random(Plausible.Timezones.zone_list())},+ {"2026-06-30T14:30:00", ~U[2026-06-30 14:30:00Z], "Etc/UTC"},+ {"2026-06-30T14:30:00", ~U[2026-06-30 11:30:00Z], "Europe/Tallinn"}+ ] do+ test "accepts :datetime #{dt} and parses it to #{expected} UTC point in time for the site with timezone #{tz}" do+ changeset =+ Annotation.changeset(+ %Annotation{},+ %{+ note: "feature released",+ type: "personal",+ granularity: "minute",+ datetime: unquote(Macro.escape(dt))+ },+ unquote(tz)+ )++ assert changeset.valid?+ assert changeset.changes.datetime == unquote(Macro.escape(expected))+ end+ end+ end++ describe "changeset/3 when both date and datetime are provided" do+ for granularity <- ["date", "minute"] do+ test "rejects both being set for #{granularity} granularity" do+ changeset =+ Annotation.changeset(+ %Annotation{},+ %{+ note: "feature released",+ type: "personal",+ granularity: unquote(granularity),+ date: "2026-06-30",+ datetime: "2026-06-30T14:30:00Z"+ },+ "Etc/UTC"+ )++ assert changeset.errors == [+ granularity: {"expects either date or datetime to be set", []}+ ]+ end+ end+ end+enddiff --git a/test/plausible/billing/feature_test.exs b/test/plausible/billing/feature_test.exsindex 82dfab0a4e..c74e0e4cfa 100644--- a/test/plausible/billing/feature_test.exs+++ b/test/plausible/billing/feature_test.exs@@ -1,5 +1,4 @@defmodule Plausible.Billing.FeatureTest do- alias Plausible.Billing.Feature.SiteSegmentsuse Plausible.DataCasealias Plausible.Billing.Feature.{diff --git a/test/plausible_web/controllers/api/internal_controller/annotations_controller_test.exs b/test/plausible_web/controllers/api/internal_controller/annotations_controller_test.exsnew file mode 100644index 0000000000..4821624af3--- /dev/null+++ b/test/plausible_web/controllers/api/internal_controller/annotations_controller_test.exs@@ -0,0 +1,727 @@+defmodule PlausibleWeb.Api.Internal.AnnotationsControllerTest do+ use PlausibleWeb.ConnCase, async: true+ use Plausible.Repo++ describe "GET /api/:domain/annotations" do+ setup [:create_user, :log_in]++ test "returns 400 when date_range is missing", %{conn: conn, user: user} do+ site = new_site(owner: user)++ conn = get(conn, "/api/#{site.domain}/annotations")++ assert %{"error" => _} = json_response(conn, 400)+ end++ test "returns 400 when date_range is unrecognized", %{conn: conn, user: user} do+ site = new_site(owner: user)++ conn = get(conn, "/api/#{site.domain}/annotations?date_range=banana")++ assert %{"error" => _} = json_response(conn, 400)+ end++ test "private site returns 404 for non-member", %{conn: conn} do+ private_site = new_site()++ conn =+ get(+ conn,+ "/api/#{private_site.domain}/annotations?date_range=day&relative_date=2026-01-04"+ )++ assert json_response(conn, 404)+ end++ test "only site annotations are shown when viewing a public site, with owners info hidden",+ %{conn: conn} do+ site_owner = new_user()+ public_site = new_site(public: true, owner: site_owner)+ insert(:annotation, site: public_site, owner: site_owner, type: :site, note: "site note")+ insert(:annotation, site: public_site, owner: site_owner, type: :personal, note: "private")++ conn =+ get(+ conn,+ "/api/#{public_site.domain}/annotations?date_range=day&relative_date=2026-01-04"+ )++ assert_matches [+ ^strict_map(%{+ "id" => ^any(:pos_integer),+ "note" => "site note",+ "type" => "site",+ "datetime" => "2026-01-04",+ "granularity" => "date",+ "owner_id" => nil,+ "owner_name" => nil,+ "inserted_at" => ^any(:iso8601_naive_datetime),+ "updated_at" => ^any(:iso8601_naive_datetime)+ })+ ] = json_response(conn, 200)+ end++ test "personal annotations of the user and all site annotations are shown with annotation owner info when viewing their site, sorted by updated_at, ascending",+ %{conn: conn, user: user} do+ site = new_site()+ other_user = new_user()+ add_guest(site, user: user, role: :viewer)++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ note: "mine",+ inserted_at: ~U[2026-07-01 10:00:00Z],+ updated_at: ~U[2026-07-01 10:00:00Z]+ )++ insert(:annotation,+ site: site,+ owner: other_user,+ type: :personal,+ note: "not mine",+ inserted_at: ~U[2026-07-01 10:00:00Z],+ updated_at: ~U[2026-07-01 11:00:00Z]+ )++ insert(:annotation,+ site: site,+ owner: other_user,+ type: :site,+ note: "shared",+ inserted_at: ~U[2026-07-01 10:00:00Z],+ updated_at: ~U[2026-07-01 12:00:00Z]+ )++ insert(:annotation,+ site: site,+ owner: nil,+ type: :site,+ note: "dangling",+ inserted_at: ~U[2026-07-01 10:00:00Z],+ updated_at: ~U[2026-07-01 13:00:00Z]+ )++ conn = get(conn, "/api/#{site.domain}/annotations?date_range=day&relative_date=2026-01-04")++ results = json_response(conn, 200)++ assert_matches [+ ^strict_map(%{+ "id" => ^any(:pos_integer),+ "note" => "dangling",+ "type" => "site",+ "datetime" => "2026-01-04",+ "granularity" => "date",+ "owner_id" => nil,+ "owner_name" => nil,+ "inserted_at" => ^any(:iso8601_naive_datetime),+ "updated_at" => ^any(:iso8601_naive_datetime)+ }),+ ^strict_map(%{+ "id" => ^any(:pos_integer),+ "note" => "shared",+ "type" => "site",+ "datetime" => "2026-01-04",+ "granularity" => "date",+ "owner_id" => ^other_user.id,+ "owner_name" => ^other_user.name,+ "inserted_at" => ^any(:iso8601_naive_datetime),+ "updated_at" => ^any(:iso8601_naive_datetime)+ }),+ ^strict_map(%{+ "id" => ^any(:pos_integer),+ "note" => "mine",+ "type" => "personal",+ "datetime" => "2026-01-04",+ "granularity" => "date",+ "owner_id" => ^user.id,+ "owner_name" => ^user.name,+ "inserted_at" => ^any(:iso8601_naive_datetime),+ "updated_at" => ^any(:iso8601_naive_datetime)+ })+ ] = results+ end++ test "filters out annotations outside a 28d window", %{conn: conn, user: user} do+ site = new_site(owner: user)++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :date,+ datetime: ~U[2026-06-26 00:00:00Z],+ note: "in range"+ )++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :date,+ datetime: ~U[2026-05-01 00:00:00Z],+ note: "out of range"+ )++ conn =+ get(conn, "/api/#{site.domain}/annotations?date_range=28d&relative_date=2026-06-29")++ results = json_response(conn, 200)+ assert Enum.map(results, & &1["note"]) == ["in range"]+ end++ test "filters by a custom [from,to] date_range", %{conn: conn, user: user} do+ site = new_site(owner: user)++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :date,+ datetime: ~U[2026-06-22 00:00:00Z],+ note: "in range"+ )++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :date,+ datetime: ~U[2026-06-26 00:00:00Z],+ note: "out of range"+ )++ conn =+ get(+ conn,+ "/api/#{site.domain}/annotations?date_range_start=2026-06-20&date_range_end=2026-06-25"+ )++ results = json_response(conn, 200)+ assert Enum.map(results, & &1["note"]) == ["in range"]+ end++ test "filters minute granularity annotations to be within the UTC datetime range",+ %{conn: conn, user: user} do+ # NY is UTC-4 in June (DST).+ # Full day of 2026-06-28 -> [~U[2026-06-28 04:00:00Z], ~U[2026-06-29 03:59:59]].+ site = new_site(owner: user, timezone: "America/New_York")++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :minute,+ # 11:00 local — inside the UTC window+ datetime: ~U[2026-06-28 15:00:00Z],+ note: "in window"+ )++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :minute,+ # next-day 01:00 local — past the UTC window end+ datetime: ~U[2026-06-29 05:00:00Z],+ note: "past window"+ )++ conn =+ get(conn, "/api/#{site.domain}/annotations?date_range=day&relative_date=2026-06-28")++ results = json_response(conn, 200)+ assert Enum.map(results, & &1["note"]) == ["in window"]+ end++ test "filters date granularity annotations that are within the local date range",+ %{conn: conn, user: user} do+ site = new_site(owner: user, timezone: "Asia/Tokyo")++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :date,+ datetime: ~U[2026-06-29 00:00:00Z],+ note: "in range"+ )++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :date,+ datetime: ~U[2026-06-30 00:00:00Z],+ note: "out of range"+ )++ conn =+ get(conn, "/api/#{site.domain}/annotations?date_range=7d&relative_date=2026-06-30")++ results = json_response(conn, 200)+ assert Enum.map(results, & &1["note"]) == ["in range"]+ end++ test "fetches annotations for realtime date_range", %{conn: conn, user: user} do+ site = new_site(owner: user)++ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :minute,+ datetime: DateTime.utc_now(),+ note: "now"+ )++ conn = get(conn, "/api/#{site.domain}/annotations?date_range=realtime")++ results = json_response(conn, 200)+ assert Enum.map(results, & &1["note"]) == ["now"]+ end+ end++ describe "POST /api/:domain/annotations" do+ setup [:create_user, :log_in, :create_site]++ test "rejects missing note", %{conn: conn, site: site} do+ conn =+ post(conn, "/api/#{site.domain}/annotations", %{+ "type" => "personal",+ "granularity" => "date",+ "datetime" => "2026-01-04"+ })++ assert json_response(conn, 400) == %{"error" => "note can't be blank"}+ end++ test "rejects empty note", %{conn: conn, site: site} do+ conn =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => "",+ "type" => "personal",+ "granularity" => "date",+ "datetime" => "2026-01-04"+ })++ assert json_response(conn, 400) == %{"error" => "note can't be blank"}+ end++ test "rejects note over 255 bytes", %{conn: conn, site: site} do+ conn =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => String.duplicate("a", 256),+ "type" => "personal",+ "granularity" => "date",+ "datetime" => "2026-01-04"+ })++ assert json_response(conn, 400) == %{"error" => "note should be at most 255 byte(s)"}+ end++ test "rejects missing datetime", %{conn: conn, site: site} do+ conn =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => "feature released",+ "type" => "personal",+ "granularity" => "date"+ })++ assert json_response(conn, 400) == %{+ "error" => "date must be supplied for chosen granularity"+ }+ end++ test "rejects unknown granularity", %{conn: conn, site: site} do+ conn =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => "feature released",+ "type" => "personal",+ "granularity" => "hour",+ "datetime" => "2026-01-04T00:00:00Z"+ })++ assert json_response(conn, 400) == %{"error" => "granularity is invalid"}+ end++ test "rejects missing granularity", %{conn: conn, site: site} do+ conn =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => "feature released",+ "type" => "personal",+ "datetime" => "2026-01-04T00:00:00Z"+ })++ assert json_response(conn, 400) == %{"error" => "granularity can't be blank"}+ end++ test "rejects unknown type as insufficient permissions", %{conn: conn, site: site} do+ conn =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => "feature released",+ "type" => "team",+ "granularity" => "date",+ "datetime" => "2026-01-04"+ })++ assert json_response(conn, 403) == %{+ "error" => "Not enough permissions to create annotation"+ }+ end++ for {params, error} <- [+ {+ %{"granularity" => "date", "datetime" => "2026-01-04T00:00:00Z"},+ "date must be supplied for chosen granularity"+ },+ {+ %{"granularity" => "date", "datetime" => "2026-01-04T00:00:00"},+ "date must be supplied for chosen granularity"+ },+ {+ %{"granularity" => "date", "date" => ""},+ "date must be supplied for chosen granularity"+ },+ {+ %{"granularity" => "date", "date" => "2026-1-4"},+ "date is invalid"+ },+ {+ %{"granularity" => "date", "date" => "2026-13-45"},+ "date is invalid"+ },+ {+ %{"granularity" => "date", "date" => "not-a-date"},+ "date is invalid"+ },+ {+ %{"granularity" => "minute", "datetime" => "2026-01-04"},+ "datetime is invalid"+ },+ {+ %{"granularity" => "minute", "datetime" => "not-a-datetime"},+ "datetime is invalid"+ },+ {+ %{"granularity" => "minute", "datetime" => ""},+ "datetime must be supplied for chosen granularity"+ },+ {+ %{"granularity" => "minute", "datetime" => "2026-13-45T14:30:00Z"},+ "datetime is invalid"+ }+ ] do+ test "rejects #{inspect(params)} with error #{error}", %{conn: conn, site: site} do+ conn =+ post(+ conn,+ "/api/#{site.domain}/annotations",+ Map.merge(+ %{"note" => "feature released", "type" => "personal"},+ unquote(Macro.escape(params))+ )+ )++ assert json_response(conn, 400) == %{"error" => unquote(error)}+ end+ end++ test "accepts bare date string when granularity is date",+ %{conn: conn, site: site} do+ response =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => "feature released",+ "type" => "personal",+ "granularity" => "date",+ "date" => "2026-01-04"+ })+ |> json_response(200)++ assert_matches ^strict_map(%{+ "id" => ^any(:pos_integer),+ "note" => "feature released",+ "type" => "personal",+ "granularity" => "date",+ "datetime" => "2026-01-04",+ "owner_id" => ^any(:pos_integer),+ "owner_name" => ^any(:string),+ "inserted_at" => ^any(:iso8601_naive_datetime),+ "updated_at" => ^any(:iso8601_naive_datetime)+ }) = response+ end++ test "accepts full datetime string when granularity is minute",+ %{conn: conn, site: site} do+ # Site is Etc/UTC by default; UTC moment is returned as naive local time+ response =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => "feature released",+ "type" => "personal",+ "granularity" => "minute",+ "datetime" => "2026-01-04T14:32:00Z"+ })+ |> json_response(200)++ assert response["datetime"] == "2026-01-04T14:32:00"+ end++ test "converts naive local time to UTC and returns it back as local time",+ %{conn: conn, user: user} do+ # America/New_York is UTC-5 in January; input and output should be the same+ # local time (round-trip), while the DB stores the UTC equivalent.+ site = new_site(owner: user, timezone: "America/New_York")++ response =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => "feature released",+ "type" => "personal",+ "granularity" => "minute",+ "datetime" => "2026-01-04T14:30:00"+ })+ |> json_response(200)++ assert response["datetime"] == "2026-01-04T14:30:00"++ reloaded = Plausible.Repo.get!(Plausible.Annotations.Annotation, response["id"])+ assert reloaded.granularity == :minute+ assert reloaded.datetime == ~U[2026-01-04 19:30:00Z]+ end++ test "UTC datetime string is stored as UTC and returned as site local time",+ %{conn: conn, user: user} do+ # America/New_York is UTC-5 in January, so 14:30 UTC = 09:30 local+ site = new_site(owner: user, timezone: "America/New_York")++ response =+ post(conn, "/api/#{site.domain}/annotations", %{+ "note" => "feature released",+ "type" => "personal",+ "granularity" => "minute",+ "datetime" => "2026-01-04T14:30:00Z"+ })+ |> json_response(200)++ assert response["datetime"] == "2026-01-04T09:30:00"+ end+ end++ describe "PATCH /api/:domain/annotations/:annotation_id" do+ setup [:create_user, :log_in, :create_site]++ test "rejects granularity change from date to minute without a new datetime",+ %{conn: conn, site: site, user: user} do+ annotation =+ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :date,+ datetime: ~U[2026-06-15 00:00:00Z]+ )++ conn =+ patch(conn, "/api/#{site.domain}/annotations/#{annotation.id}", %{+ "granularity" => "minute"+ })++ assert json_response(conn, 400) == %{+ "error" => "datetime must be supplied for chosen granularity"+ }++ reloaded = Plausible.Repo.get!(Plausible.Annotations.Annotation, annotation.id)+ assert reloaded.granularity == :date+ assert reloaded.datetime == ~U[2026-06-15 00:00:00Z]+ end++ test "rejects granularity change from minute to date without a new datetime",+ %{conn: conn, site: site, user: user} do+ annotation =+ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :minute,+ datetime: ~U[2026-06-15 14:30:00Z]+ )++ conn =+ patch(conn, "/api/#{site.domain}/annotations/#{annotation.id}", %{+ "granularity" => "date"+ })++ assert json_response(conn, 400) == %{+ "error" => "date must be supplied for chosen granularity"+ }++ reloaded = Plausible.Repo.get!(Plausible.Annotations.Annotation, annotation.id)+ assert reloaded.granularity == :minute+ assert reloaded.datetime == ~U[2026-06-15 14:30:00Z]+ end++ test "accepts granularity change from date to minute with a new datetime",+ %{conn: conn, site: site, user: user} do+ annotation =+ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :date,+ datetime: ~U[2026-06-15 00:00:00Z]+ )++ response =+ patch(conn, "/api/#{site.domain}/annotations/#{annotation.id}", %{+ "granularity" => "minute",+ "datetime" => "2026-06-15T14:30:00Z"+ })+ |> json_response(200)++ assert response["granularity"] == "minute"+ assert response["datetime"] == "2026-06-15T14:30:00"++ reloaded = Plausible.Repo.get!(Plausible.Annotations.Annotation, annotation.id)+ assert reloaded.granularity == :minute+ assert reloaded.datetime == ~U[2026-06-15 14:30:00Z]+ end++ test "accepts granularity change from minute to date with a new datetime",+ %{conn: conn, site: site, user: user} do+ annotation =+ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :minute,+ datetime: ~U[2026-06-15 14:30:00Z]+ )++ response =+ patch(conn, "/api/#{site.domain}/annotations/#{annotation.id}", %{+ "granularity" => "date",+ "date" => "2026-06-20"+ })+ |> json_response(200)++ assert response["granularity"] == "date"+ assert response["datetime"] == "2026-06-20"++ reloaded = Plausible.Repo.get!(Plausible.Annotations.Annotation, annotation.id)+ assert reloaded.granularity == :date+ assert reloaded.datetime == ~U[2026-06-20 00:00:00Z]+ end++ test "converts naive local time to UTC and returns it back as local time",+ %{conn: conn, user: user} do+ # America/New_York is UTC-4 in June (DST), so input and output are the same+ site = new_site(owner: user, timezone: "America/New_York")++ annotation =+ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :minute,+ datetime: ~U[2026-01-01 00:00:00Z]+ )++ response =+ patch(conn, "/api/#{site.domain}/annotations/#{annotation.id}", %{+ "granularity" => "minute",+ "datetime" => "2026-06-15T10:00:00"+ })+ |> json_response(200)++ assert response["datetime"] == "2026-06-15T10:00:00"++ reloaded = Plausible.Repo.get!(Plausible.Annotations.Annotation, annotation.id)+ assert reloaded.granularity == :minute+ assert reloaded.datetime == ~U[2026-06-15 14:00:00Z]+ end++ test "accepts bare date string when granularity is date",+ %{conn: conn, site: site, user: user} do+ annotation =+ insert(:annotation,+ site: site,+ owner: user,+ type: :personal,+ granularity: :date,+ datetime: ~U[2026-01-01 00:00:00Z]+ )++ response =+ patch(conn, "/api/#{site.domain}/annotations/#{annotation.id}", %{+ "granularity" => "date",+ "date" => "2026-06-15"+ })+ |> json_response(200)++ assert response["datetime"] == "2026-06-15"+ end++ for {casename, note_has_owner?} <- [+ {"dangling site note", false},+ {"site note left by other user", true}+ ] do+ test "users with site note permissions can edit a #{casename}, becoming its new owner",+ %{+ conn: conn,+ site: site,+ user: user+ } do+ note_owner =+ if(unquote(note_has_owner?),+ do:+ site.team+ |> add_member(+ user: new_user(name: "other user"),+ role: :editor+ ),+ else: nil+ )++ annotation =+ insert(:annotation,+ owner: note_owner,+ site: site,+ type: :site,+ granularity: :date,+ datetime: "2026-06-01T00:00:00Z"+ )++ response =+ patch(conn, "/api/#{site.domain}/annotations/#{annotation.id}", %{+ "note" => "updated"+ })+ |> json_response(200)++ assert_matches ^strict_map(%{+ "id" => ^annotation.id,+ "note" => "updated",+ "type" =>+ ^any(+ :string,+ ~r/#{annotation.type}/+ ),+ "granularity" =>+ ^any(+ :string,+ ~r/#{annotation.granularity}/+ ),+ "datetime" => "2026-06-01",+ "owner_id" => ^user.id,+ "owner_name" => ^user.name,+ "inserted_at" =>+ ^any(+ :string,+ ~r/#{Calendar.strftime(annotation.inserted_at, "%Y-%m-%dT%H:%M:%S")}/+ ),+ "updated_at" => ^any(:iso8601_naive_datetime)+ }) = response+ end+ end+ end+enddiff --git a/test/plausible_web/controllers/api/internal_controller/segments_controller_test.exs b/test/plausible_web/controllers/api/internal_controller/segments_controller_test.exsindex e73d58a3cf..ddbf41a4c5 100644--- a/test/plausible_web/controllers/api/internal_controller/segments_controller_test.exs+++ b/test/plausible_web/controllers/api/internal_controller/segments_controller_test.exs@@ -358,44 +358,58 @@ defmodule PlausibleWeb.Api.Internal.SegmentsControllerTest do}) = responseend- test "the last editor of a dangling site segment (segment with owner_id: nil) becomes the new owner",- %{- conn: conn,- user: user- } do- site = new_site()- add_guest(site, user: user, role: :editor)+ for {casename, segment_has_owner?} <- [+ {"dangling site segment", false},+ {"site segment by other user", true}+ ] do+ test "the last editor of a #{casename} becomes the new owner",+ %{+ conn: conn,+ site: site,+ user: user+ } do+ segment_owner =+ if(unquote(segment_has_owner?),+ do:+ site.team+ |> add_member(+ user: new_user(name: "other user"),+ role: :editor+ ),+ else: nil+ )- segment =- insert(:segment,- site: site,- name: "original name",- type: :site,- owner: nil- )+ segment =+ insert(:segment,+ site: site,+ name: "original name",+ type: :site,+ owner: segment_owner+ )- response =- patch(conn, "/api/#{site.domain}/segments/#{segment.id}", %{"name" => "updated name"})- |> json_response(200)+ response =+ patch(conn, "/api/#{site.domain}/segments/#{segment.id}", %{"name" => "updated name"})+ |> json_response(200)- assert_matches ^strict_map(%{- "id" => ^segment.id,- "name" => "updated name",- "type" =>- ^any(- :string,- ~r/#{segment.type}/- ),- "owner_id" => ^user.id,- "owner_name" => ^user.name,- "segment_data" => ^segment.segment_data,- "inserted_at" =>- ^any(- :string,- ~r/#{Calendar.strftime(segment.inserted_at, "%Y-%m-%dT%H:%M:%S")}/- ),- "updated_at" => ^any(:iso8601_naive_datetime)- }) = response+ assert_matches ^strict_map(%{+ "id" => ^segment.id,+ "name" => "updated name",+ "type" =>+ ^any(+ :string,+ ~r/#{segment.type}/+ ),+ "owner_id" => ^user.id,+ "owner_name" => ^user.name,+ "segment_data" => ^segment.segment_data,+ "inserted_at" =>+ ^any(+ :string,+ ~r/#{Calendar.strftime(segment.inserted_at, "%Y-%m-%dT%H:%M:%S")}/+ ),+ "updated_at" => ^any(:iso8601_naive_datetime)+ }) = response+ endendtest "cannot move segment to another site by passing site_id param", %{@@ -403,19 +417,19 @@ defmodule PlausibleWeb.Api.Internal.SegmentsControllerTest douser: user,site: site} do- victim_site = new_site()+ other_site = new_site()segment = insert(:segment, site: site, owner: user, type: :personal, name: "test segment")patch(conn, "/api/#{site.domain}/segments/#{segment.id}", %{"name" => "updated name","type" => "personal","segment_data" => %{"filters" => [["is", "visit:entry_page", ["/blog"]]], "labels" => %{}},- "site_id" => victim_site.id+ "site_id" => other_site.id})reloaded = Repo.reload!(segment)assert reloaded.site_id == site.id- assert reloaded.site_id != victim_site.id+ assert reloaded.site_id != other_site.idendenddiff --git a/test/plausible_web/plugs/feature_flag_check_plug_test.exs b/test/plausible_web/plugs/feature_flag_check_plug_test.exsnew file mode 100644index 0000000000..ead037ed4b--- /dev/null+++ b/test/plausible_web/plugs/feature_flag_check_plug_test.exs@@ -0,0 +1,46 @@+defmodule PlausibleWeb.Plugs.FeatureFlagCheckPlugTest do+ use PlausibleWeb.ConnCase, async: true+ use Plausible.Teams.Test+ alias PlausibleWeb.Plugs.{AuthorizeSiteAccess, FeatureFlagCheckPlug}++ setup [:create_user, :log_in, :create_site]++ test "returns 404 when any of the expected feature flags is not enabled", %{+ conn: conn,+ site: site+ } do+ # currently enabled flags are defined test/test_helper.exs+ required_flags =+ FeatureFlagCheckPlug.init([:missing_feature_flag, :annotations])++ conn =+ conn+ |> get_conn_with_current_user_and_site(site)+ |> FeatureFlagCheckPlug.call(required_flags)++ assert conn.halted+ assert %{"error" => "Not found"} == json_response(conn, 404)+ end++ test "passes conn when required flags are enabled", %{+ conn: conn,+ site: site+ } do+ # currently enabled flags are defined test/test_helper.exs+ required_flags = FeatureFlagCheckPlug.init([:annotations])++ conn =+ conn+ |> get_conn_with_current_user_and_site(site)+ |> FeatureFlagCheckPlug.call(required_flags)++ assert !conn.halted+ end++ defp get_conn_with_current_user_and_site(%Plug.Conn{} = conn, %Plausible.Site{} = site) do+ conn+ |> bypass_through(PlausibleWeb.Router)+ |> get("/plug-tests/api-basic?site=#{site.domain}")+ |> AuthorizeSiteAccess.call(AuthorizeSiteAccess.init({:all_roles, "site"}))+ end+enddiff --git a/test/support/factory.ex b/test/support/factory.exindex 5396ee4475..a70c8f9b9b 100644--- a/test/support/factory.ex+++ b/test/support/factory.ex@@ -1,4 +1,7 @@defmodule Plausible.Factory do+ @moduledoc """+ See https://ecto.hexdocs.pm/test-factories.html+ """use ExMachina.Ecto, repo: Plausible.Reporequire Plausible.Billing.Subscription.Statusalias Plausible.Billing.Subscription@@ -392,6 +395,16 @@ defmodule Plausible.Factory do}end+ def annotation_factory do+ %Plausible.Annotations.Annotation{+ note: "a test annotation",+ type: :site,+ datetime: ~U[2026-01-04 00:00:00Z],+ date: ~D[2026-01-04],+ granularity: :date+ }+ end+defp hash_key() doKeyword.fetch!(Application.get_env(:plausible, PlausibleWeb.Endpoint),diff --git a/test/test_helper.exs b/test/test_helper.exsindex bd6ac0e85e..63f401e791 100644--- a/test/test_helper.exs+++ b/test/test_helper.exs@@ -13,6 +13,8 @@ if Mix.env() != :e2e_test doApplication.ensure_all_started(:double)+ FunWithFlags.enable(:annotations)+Ecto.Adapters.SQL.Sandbox.mode(Plausible.Repo, :manual)end