@spec allow(Plausible.Site.t(), [prop()] | prop()) ::
  {:ok, Plausible.Site.t()}
  | {:error, Ecto.Changeset.t()}
  | {:error, :upgrade_required}

Allows a prop key or a list of props keys to be included in ClickHouse queries. Allowing prop keys does not affect ingestion, as we don't want any data to be dropped or lost.

@spec allow_existing_props(Plausible.Site.t()) ::
  {:ok, Plausible.Site.t()} | {:error, :upgrade_required}

Allows the 300 most frequent props keys for a specific site over the past 6 months.

Returns the custom props allowed in queries for the given site. There are two factors deciding whether a custom property is allowed for a site.

1. Subscription plan including the props feature.

Internally used keys (i.e. ["url", "path"]) are always allowed, even for plans that don't include props. For any other props, access to the Custom Properties feature is required.

2. The site having an allowed_event_props list configured.

For customers with a configured allowed_event_props list, this function returns that list (+ internally used keys). That helps to filter out garbage props which people might not want to see in their dashboards.

With the bypass_setup? boolean option you can override the requirement of the site having set up props in the allowed_event_props list. For example, this is currently used for fetching allowed properties in Stats API queries in order to ensure the props feature access.

Since allowed_event_props was added after the props feature had already been used for a while, there are sites with allowed_event_props = nil. For those sites, all custom properties that exist in the database are allowed to be queried.

Returns whether the site has configured custom props or not.

@spec disallow(Plausible.Site.t(), [prop()] | prop()) ::
  {:ok, Plausible.Site.t()} | {:error, Ecto.Changeset.t()}

Removes previously allowed prop key(s) from the allow list. This means this prop key won't be included in ClickHouse queries. This doesn't drop any ClickHouse data, nor affects ingestion.

Lists prop keys used internally.

These props should be allowed by default, and should not be displayed in the props settings page. For example, url is a special prop key used for file downloads and outbound links. It doesn't make sense to remove this prop key from the allow list, or to suggest users to add this prop key.

@spec suggest_keys_to_allow(Plausible.Site.t(), non_neg_integer()) :: [String.t()]

Queries the events table to fetch the 300 most frequent prop keys for a specific site over the past 6 months, excluding keys that are already allowed.