pushmetrics-cli 0.1.0__py3-none-any.whl

pm/config.py

@@ -0,0 +1,192 @@
+"""Profile configuration for the PushMetrics CLI.
+
+Profiles live at `$PM_CONFIG_HOME/config.toml` (defaults to `~/.pm/config.toml`).
+Built-in profile names (`default`, `local`, plus the harness-only `agent`)
+provide sensible api_url and auth0_domain values. A profile needs only
+`api_url` for token login (`pm login --token`, PM_API_TOKEN); auth0_domain
+and auth0_client_id matter only for browser (device-flow) login. A `staging`
+built-in existed until 2026-07 but pointed at an environment that was never
+stood up (no DNS, no deploy pipeline).
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import click
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+DEFAULT_CONFIG_DIR = Path.home() / ".pm"
+CONFIG_DIR = Path(os.environ.get("PM_CONFIG_HOME") or DEFAULT_CONFIG_DIR)
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+
+def is_default_config_home() -> bool:
+    return CONFIG_DIR.resolve() == DEFAULT_CONFIG_DIR.resolve()
+
+
+def keyring_account(profile: str) -> str:
+    """The OS-keyring account name for ``profile`` in the active config home.
+
+    The keyring is per user, not per directory, so two config homes (a
+    scratch PM_CONFIG_HOME, CI, a second tool) used to share one slot per
+    profile name: a process with its own config home authenticated with the
+    user's stored PAT, and its `pm logout` deleted it (security S9). The
+    default home keeps the bare profile name, so every existing stored PAT,
+    cookie and cached JWT keeps working with no re-login; any other home
+    gets its own namespace derived from its resolved path.
+    """
+    if is_default_config_home():
+        return profile
+    digest = hashlib.sha256(str(CONFIG_DIR.resolve()).encode("utf-8")).hexdigest()[:12]
+    return f"{profile}@{digest}"
+
+
+def describe_config_home() -> str:
+    """One line naming the active config home, for diagnosing which
+    credentials a command can see."""
+    if is_default_config_home():
+        return f"{CONFIG_DIR} (default)"
+    return f"{CONFIG_DIR} (PM_CONFIG_HOME; credentials stored separately from {DEFAULT_CONFIG_DIR})"
+
+# Every key a profile section may carry; the single source `config set`
+# validates against. Matches the Profile dataclass fields below (minus name).
+PROFILE_KEYS = frozenset({"api_url", "auth0_domain", "auth0_client_id", "auth0_audience"})
+
+DEFAULT_PROFILES: Dict[str, Dict[str, Any]] = {
+    "default": {
+        # The API lives on the apex host. app.pushmetrics.io answers every
+        # path with a 301 to https://pushmetrics.io/app (path dropped), and
+        # the CLI never follows redirects (it would re-send the Authorization
+        # header), so a first-run `pm login --token` against the old host
+        # failed with "Token exchange failed: 301".
+        "api_url": "https://pushmetrics.io",
+        "auth0_domain": "auth.pushmetrics.io",
+    },
+    "local": {
+        # 127.0.0.1 (not "localhost") — Windows resolves localhost via IPv6 first
+        # and a missing AAAA can add ~2s per fresh connection.
+        "api_url": "http://127.0.0.1:8090",
+        "auth0_domain": "staging.auth.pushmetrics.io",
+    },
+    # Profile used by the prefect agent when running pm under a delegation
+    # JWT (PM_API_JWT). api_url is normally overridden by the PM_API_URL env
+    # var in the container; the auth0 fields are unused because the
+    # credential is supplied — never the device-flow login.
+    "agent": {
+        "api_url": "http://127.0.0.1:8090",
+        "auth0_domain": "agent.local",
+    },
+}
+
+
+@dataclass
+class Profile:
+    name: str
+    api_url: str
+    # Browser (device-flow) login only; token login never reads these.
+    auth0_domain: Optional[str] = None
+    auth0_client_id: Optional[str] = None
+    auth0_audience: Optional[str] = None
+
+    @property
+    def audience(self) -> Optional[str]:
+        if self.auth0_audience:
+            return self.auth0_audience
+        return f"https://{self.auth0_domain}/api/v2/" if self.auth0_domain else None
+
+
+def _ensure_dir() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _serialize_toml(data: Dict[str, Dict[str, Any]]) -> str:
+    """Tiny TOML writer for our flat profile schema. Avoids pulling in tomli_w."""
+    lines = []
+    for profile_name, fields in data.items():
+        lines.append(f"[{profile_name}]")
+        for key, value in fields.items():
+            if value is None:
+                continue
+            if isinstance(value, bool):
+                lines.append(f"{key} = {str(value).lower()}")
+            elif isinstance(value, (int, float)):
+                lines.append(f"{key} = {value}")
+            else:
+                escaped = str(value).replace("\\", "\\\\").replace('"', '\\"')
+                lines.append(f'{key} = "{escaped}"')
+        lines.append("")
+    return "\n".join(lines)
+
+
+def load_all() -> Dict[str, Dict[str, Any]]:
+    if not CONFIG_FILE.exists():
+        return {}
+    with CONFIG_FILE.open("rb") as f:
+        return tomllib.load(f)
+
+
+def save_all(data: Dict[str, Dict[str, Any]]) -> None:
+    _ensure_dir()
+    CONFIG_FILE.write_text(_serialize_toml(data), encoding="utf-8")
+
+
+def get_profile(name: str) -> Profile:
+    """Resolve a profile by name. Layering: env vars > config file > built-in defaults."""
+    file_data = load_all()
+    file_profile = file_data.get(name, {})
+    default_profile = DEFAULT_PROFILES.get(name, {})
+
+    if not file_profile and not default_profile:
+        known = sorted(set(file_data) | set(DEFAULT_PROFILES))
+        raise click.ClickException(
+            f"Unknown profile: {name!r}. Known profiles: {', '.join(known)}. "
+            f"Create it with `pm config set {name} api_url https://pushmetrics.io`."
+        )
+
+    merged: Dict[str, Any] = {**default_profile, **file_profile}
+
+    api_url = os.environ.get("PM_API_URL") or merged.get("api_url")
+    auth0_domain = os.environ.get("PM_AUTH0_DOMAIN") or merged.get("auth0_domain")
+    auth0_client_id = os.environ.get("PM_AUTH0_CLIENT_ID") or merged.get("auth0_client_id")
+    auth0_audience = merged.get("auth0_audience")
+
+    # api_url is the only field every command needs. auth0_domain is checked
+    # where browser login uses it (pm.auth.device_flow), so a profile created
+    # with the one line the "Unknown profile" error suggests works for
+    # token login as written.
+    if not api_url:
+        raise click.ClickException(
+            f"Profile {name!r} has no api_url. "
+            f"Set it with `pm config set {name} api_url https://pushmetrics.io`, "
+            f"or set PM_API_URL."
+        )
+
+    return Profile(
+        name=name,
+        api_url=api_url.rstrip("/"),
+        auth0_domain=auth0_domain,
+        auth0_client_id=auth0_client_id,
+        auth0_audience=auth0_audience,
+    )
+
+
+def set_profile_field(profile_name: str, key: str, value: str) -> None:
+    """Write one profile key to the config file; unknown keys are refused."""
+    if key not in PROFILE_KEYS:
+        raise click.ClickException(
+            f"Unknown profile key {key!r}. Valid keys: {', '.join(sorted(PROFILE_KEYS))}."
+        )
+    data = load_all()
+    block = data.setdefault(profile_name, {})
+    block[key] = value
+    save_all(data)

pm/errors.py

@@ -0,0 +1,228 @@
+"""Structured error envelope for the pm CLI (pm-tool plan §2.7).
+
+CLI errors return a parseable JSON shape with an explicit `retry:` field so
+the agent (or a human looking at JSON output) can recover without re-fetching
+help. Used for validation failures, allowlist denials, replay-guard blocks,
+type canonicalization mismatches, and any other structured failure.
+
+Envelope shape::
+
+    {
+      "ok": false,
+      "error_code": "<closed-set string>",
+      "message": "<human-readable summary>",
+      "received": "<what the user passed, if relevant>",
+      "did_you_mean": ["<suggestion>", ...],
+      "allowed": ["<valid value>", ...],
+      "retry": "<exact next command line, if available>",
+      "example": {<inline body example>},
+      "help": "pm help <relevant verb>"
+    }
+
+Optional fields are omitted from the envelope when not set — keeps the
+output small for the common case.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass, field
+from typing import Any
+
+import click
+
+
+# Closed set of error codes. New entries go here; call sites can't invent
+# their own. Keeps the agent-facing surface stable for retry / recovery.
+ERROR_CODES: frozenset[str] = frozenset({
+    # Type discriminator
+    "unknown_block_type",
+    "ambiguous_type_override",
+    # Body validation
+    "block_schema_validation_failed",
+    "type_body_mismatch",
+    # Resource state
+    "not_found",
+    # Authorization / policy
+    "forbidden",
+    "replay_disabled",
+    "action_denied",
+    # CLI grammar
+    "argv_invalid",
+})
+
+
+@dataclass
+class PMError(Exception):
+    """Base for structured CLI errors. Construct with the relevant fields;
+    raise where the failure happens; catch at the command handler boundary
+    and call ``emit_error(err)`` to print the envelope + exit non-zero.
+
+    Subclasses can preset ``error_code`` for ergonomics; the dataclass
+    fields stay flexible so call sites pick exactly the envelope shape
+    they want.
+    """
+    error_code: str
+    message: str
+    received: str | None = None
+    did_you_mean: list[str] = field(default_factory=list)
+    allowed: list[str] = field(default_factory=list)
+    retry: str | None = None
+    example: Any = None
+    help: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.error_code not in ERROR_CODES:
+            raise ValueError(
+                f"Unknown error_code: {self.error_code!r}. "
+                f"Add to ERROR_CODES in cli/pm/errors.py first."
+            )
+        # Exception.__init__ wants a message arg — the dataclass doesn't
+        # call it for us.
+        super().__init__(self.message)
+
+    def envelope(self) -> dict[str, Any]:
+        """Return the JSON-serializable envelope dict. Optional fields
+        omitted when not set."""
+        out: dict[str, Any] = {
+            "ok": False,
+            "error_code": self.error_code,
+            "message": self.message,
+        }
+        if self.received is not None:
+            out["received"] = self.received
+        if self.did_you_mean:
+            out["did_you_mean"] = self.did_you_mean
+        if self.allowed:
+            out["allowed"] = self.allowed
+        if self.retry is not None:
+            out["retry"] = self.retry
+        if self.example is not None:
+            out["example"] = self.example
+        if self.help is not None:
+            out["help"] = self.help
+        return out
+
+
+def emit_error(err: PMError, *, exit_code: int = 1) -> None:
+    """Print the structured envelope to stderr as a single JSON line and
+    exit with a non-zero status. Used by command handlers' exception path.
+
+    JSON goes to stderr (not stdout) so that stdout stays clean for piped
+    success results; the agent reads both streams, but humans piping
+    output expect errors out-of-band.
+    """
+    click.echo(json.dumps(err.envelope(), separators=(",", ":")), err=True)
+    sys.exit(exit_code)
+
+
+# ── Human-facing API / network error rendering ───────────────────────
+#
+# Every command ends up at the API; when the API says no, the first line
+# keeps the exact ``API <METHOD> <url> failed: <status> <body>`` text
+# (CONTRACT: the prefect cli_adapter scrapes ``failed:\s*(\d{3})`` from
+# stderr to classify auth denials), and a second ``Hint:`` line names the
+# next action a person can take. The hint is what makes a first run with
+# only a PAT recoverable without reading the source.
+
+SUPPORT_EMAIL = "support@pushmetrics.io"
+
+
+def _hint_for_status(status: int, group: str | None) -> str | None:
+    listing = f"`pm {group} list`" if group else "the matching `pm <resource> list`"
+    if status == 400:
+        return (
+            "The server rejected the request body or flags. "
+            + (f"`pm {group} --help` lists what it accepts." if group else "")
+        ).strip()
+    if status == 403:
+        return (
+            "You do not have permission for this in the active workspace. "
+            "Check which user, token and workspace you are using "
+            "(`pm whoami`, `pm config list`)."
+        )
+    if status == 404 and group == "workspace":
+        return "`pm workspace list` shows the workspaces you can access."
+    if status == 404:
+        return (
+            f"Nothing with that id is visible in the active workspace. "
+            f"{listing} shows what exists."
+        )
+    if status == 429:
+        return "Too many requests. Wait a minute and retry."
+    if status >= 500:
+        return (
+            "PushMetrics returned a server error. Retry in a minute; if it "
+            f"keeps failing, email {SUPPORT_EMAIL} with the command and the time."
+        )
+    return None
+
+
+# FAB's bare status phrases (response_403() -> {"message": "Forbidden"},
+# response_404() -> {"message": "Not found"}) explain nothing; they keep the
+# generic next-action hint. Anything else is a sentence written for the user.
+_BARE_STATUS_MESSAGES = frozenset({
+    "forbidden", "not found", "unauthorized", "bad request",
+    # The one textual 403 reachable from pm (non-member workspace switch):
+    # a fact with no next action, so the hint follows it.
+    "you don't belong to this workspace",
+})
+
+
+def _is_bare_status_message(message: str) -> bool:
+    return message.strip().rstrip(".").lower() in _BARE_STATUS_MESSAGES
+
+
+# A server message longer than this is a stack trace or an error page, not
+# a sentence for a person; cap it so it cannot flood a terminal or an agent
+# transcript (same bound pm.log applies to logged bodies).
+_SERVER_MESSAGE_MAX = 500
+
+
+def _server_message(body: str) -> str | None:
+    """The sentence a PushMetrics/FAB error body carries, if any: under
+    ``message`` (FAB's response_4xx helpers) or ``error`` (older PushMetrics
+    views, e.g. the non-member workspace switch)."""
+    try:
+        parsed = json.loads(body or "")
+    except ValueError:
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    message = next(
+        (v for v in (parsed.get("message"), parsed.get("error")) if isinstance(v, str) and v.strip()),
+        None,
+    )
+    if message is None:
+        return None
+    message = message.strip()
+    if len(message) > _SERVER_MESSAGE_MAX:
+        message = message[:_SERVER_MESSAGE_MAX] + "…"
+    return message
+
+
+def describe_api_error(exc: Exception, *, group: str | None = None) -> str:
+    """Render a ``PMApiError`` for a person: the original line, then a hint.
+
+    When the body carries a server ``message`` it replaces the raw JSON on
+    the first line, and on 403 a message that is more than FAB's bare
+    "Forbidden" also replaces the generic hint: a policy refusal ("This
+    token is bound to workspace 3 ...") is already the explanation. The
+    ``failed: <status>`` text stays in place either way.
+
+    ``exc`` is typed loosely so this module stays importable without the
+    client package; callers pass ``pm.client.base.PMApiError``.
+    """
+    status = int(getattr(exc, "status", 0) or 0)
+    message = _server_message(getattr(exc, "body", "") or "")
+    if message:
+        method = getattr(exc, "method", "") or ""
+        path = getattr(exc, "path", "") or ""
+        from pm.client.base import api_error_prefix
+
+        first_line = f"{api_error_prefix(method, path)}: {status} {message}"
+    else:
+        first_line = str(exc)
+    explained = bool(message) and not _is_bare_status_message(message)
+    hint = None if (explained and status == 403) else _hint_for_status(status, group)
+    return f"{first_line}\nHint: {hint}" if hint else first_line

pm/log.py

@@ -0,0 +1,63 @@
+"""Helpers for HTTP-call logging at DEBUG level.
+
+Logs method/URL on the way out, status + duration on the way back. Includes the
+response body only on 4xx/5xx so successful responses (which often carry tokens)
+don't get written to stderr.
+"""
+from __future__ import annotations
+
+import contextlib
+import logging
+import re
+import time
+
+import requests
+
+MAX_BODY = 500
+
+# The ONE secret pattern for the CLI: PATs, anything after "Bearer", and bare
+# JWTs (three base64url segments starting with the `{"` header prefix `eyJ`),
+# which a 4xx/5xx body or an Auth0 error page can echo verbatim. pm.auth.*
+# import redact_secrets from here; there is no second copy (security S4).
+_SECRET_RE = re.compile(
+    r"(pmpat_[A-Za-z0-9_\-]+"
+    r"|[Bb]earer\s+[A-Za-z0-9._\-]+"
+    r"|eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+)"
+)
+
+
+def redact_secrets(text: str) -> str:
+    """Replace PAT / Bearer-token / JWT substrings with a redaction marker."""
+    return _SECRET_RE.sub("<redacted>", text or "")
+
+
+def log_request(logger: logging.Logger, method: str, url: str) -> float:
+    """Log an outgoing request and return a perf_counter to feed into `log_response`."""
+    logger.debug("-> %s %s", method, url)
+    return time.perf_counter()
+
+
+def log_response(
+    logger: logging.Logger,
+    resp: requests.Response,
+    started: float | None = None,
+) -> None:
+    suffix = ""
+    if started is not None:
+        suffix = f" ({(time.perf_counter() - started) * 1000:.0f}ms)"
+    if resp.status_code >= 400:
+        body = redact_secrets((resp.text or "")[:MAX_BODY])
+        logger.debug("<- %d %s%s -- %s", resp.status_code, resp.url, suffix, body)
+    else:
+        logger.debug("<- %d %s%s", resp.status_code, resp.url, suffix)
+
+
+@contextlib.contextmanager
+def timed(logger: logging.Logger, label: str):
+    """Context manager: logs `[label] Nms` at DEBUG when the block exits."""
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        elapsed = (time.perf_counter() - start) * 1000
+        logger.debug("[%s] %.0fms", label, elapsed)

pm/models/__init__.py

@@ -0,0 +1,31 @@
+"""Typed models for PushMetrics API responses.
+
+All models use `extra="allow"` so the backend can add fields without breaking
+the CLI; they're preserved through `model_dump()` so `--json` output stays
+complete.
+"""
+from pm.models.databases import Database
+from pm.models.favorites import Favorite
+from pm.models.folders import Folder
+from pm.models.organizations import Organization
+from pm.models.reports import Report
+from pm.models.runs import Run, RunTaskResult
+from pm.models.saved_blocks import SavedBlock
+from pm.models.users import Role, User
+from pm.models.webhooks import Webhook
+from pm.models.workspaces import Workspace
+
+__all__ = [
+    "Database",
+    "Favorite",
+    "Folder",
+    "Organization",
+    "Report",
+    "Role",
+    "Run",
+    "RunTaskResult",
+    "SavedBlock",
+    "User",
+    "Webhook",
+    "Workspace",
+]

pm/models/access_tokens.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AccessToken(BaseModel):
+    """A Personal Access Token's metadata (never the secret).
+
+    The backend (``AccessTokenRestApi._serialize``) exposes ``id`` as a hashid
+    string (used by the revoke route), plus the display ``token_prefix`` and the
+    lifecycle timestamps. The raw token itself is returned exactly once, at
+    create time, in a separate top-level ``token`` field — not on this model.
+    """
+    model_config = ConfigDict(extra="allow")
+
+    id: Optional[str] = None
+    name: Optional[str] = None
+    token_prefix: Optional[str] = None
+    kind: Optional[str] = None
+    workspace_id: Optional[int] = None
+    created_on: Optional[str] = None
+    last_used_on: Optional[str] = None
+    expires_on: Optional[str] = None

pm/models/blocks.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Block(BaseModel):
+    """Block — the unit of work in a noteflow report.
+
+    `content_json` on the wire is a JSON-encoded string. `BlocksClient`
+    accepts it as a dict on create/update and serializes; on read it stays
+    a string so callers can parse on demand.
+    """
+    model_config = ConfigDict(extra="allow")
+
+    uid: Optional[str] = None
+    name: Optional[str] = None
+    verbose_name: Optional[str] = None
+    type: Optional[str] = None
+    content_json: Optional[Any] = None

pm/models/databases.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Database(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: Optional[int] = None
+    uid: Optional[str] = None
+    database_name: Optional[str] = None
+    backend: Optional[str] = None
+    expose_in_sqllab: Optional[bool] = None

pm/models/favorites.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Favorite(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    uid: Optional[str] = None
+    class_name: Optional[str] = None  # e.g. "Report"
+    obj_id: Optional[int] = None
+    item: Optional[Any] = None  # populated by post_add with the favorited object

pm/models/folders.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Folder(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: Optional[int] = None
+    uid: Optional[str] = None
+    name: Optional[str] = None
+    parent_id: Optional[int] = None

pm/models/integrations.py

@@ -0,0 +1,20 @@
+"""Pydantic model for `pm integration` responses.
+
+Mirrors what the backend's IntegrationRestApi (resource_name="integration",
+list_columns at superset/pushmetrics/views/integration/api.py:116) returns.
+Extra fields are allowed so backend additions don't break the CLI client.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Integration(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: Optional[int] = None
+    uid: Optional[str] = None
+    name: Optional[str] = None
+    type: Optional[str] = None

pm/models/organizations.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Organization(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: Optional[int] = None
+    uid: Optional[str] = None
+    name: Optional[str] = None

pm/models/recipients.py

@@ -0,0 +1,41 @@
+"""Recipient model — workspace CRM endpoint for message delivery targets.
+
+A Recipient is a named person/team with one or more destinations
+(email address, Slack channel). Used by email/slack block sends as
+the delivery target; also gated by ``tools_json.messaging_policy``
+(``recipients_only`` / ``recipients_only_with_approval``) on the
+agent side — see ``pm_tool._apply_messaging_policy``.
+"""
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RecipientDestination(BaseModel):
+    """One delivery channel attached to a Recipient."""
+
+    model_config = ConfigDict(extra="allow")
+
+    uid: Optional[str] = None
+    id: Optional[int] = None
+    destination_type: Optional[str] = None  # "email" | "slack" | ...
+    endpoint: Optional[str] = None
+    extra: Optional[Any] = None
+
+
+class Recipient(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    uid: Optional[str] = None
+    name: Optional[str] = None
+    # ``default_factory=list`` rather than ``= []`` — Pydantic handles
+    # mutable defaults safely but the bare literal still reads as a
+    # shared-state hazard to new readers; factory makes intent explicit.
+    destinations: List[RecipientDestination] = Field(default_factory=list)
+    tags: Optional[List[Any]] = None
+    extra: Optional[Any] = None
+    user_uid: Optional[str] = None
+    created_on_utc: Optional[str] = None
+    changed_on_utc: Optional[str] = None