feat: add metrics.hits, with support for new instrumentation/content/hits endpoint (#410)

##  Intent

Add support support for Posit Connect's content hits endpoint (`GET
/v1/instrumentation/content/hits`)

Closes #403 

## Notes

  - Implementation lives in `metrics/hits.py`
- `from` and `to` parameters are named `start` and `end` in Python to
work around reserved keywords. The `rename_params` function shared
across all metrics classes has been collapsed into a single function.

## Tests

- Tests have been added which cover all of the new functionality.

---------

Co-authored-by: Taylor Steinberg <taylor@steinberg.xyz>

Author: toph-allen

src/posit/connect/metrics/hits.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing_extensions import (
+    Iterable,
+    Protocol,
+)
+
+from ..resources import Resource, ResourceSequence, _ResourceSequence
+from .rename_params import rename_params
+
+
+class Hit(Resource, Protocol):
+    pass
+
+
+class Hits(ResourceSequence[Hit], Protocol):
+    def fetch(
+        self,
+        *,
+        start: str = ...,
+        end: str = ...,
+    ) -> Iterable[Hit]:
+        """
+        Fetch all content hit records matching the specified conditions.
+
+        Parameters
+        ----------
+        start : str, not required
+            The timestamp that starts the time window of interest in RFC 3339 format.
+            Any hit information that happened prior to this timestamp will not be returned.
+            Example: "2025-05-01T00:00:00Z"
+        end : str, not required
+            The timestamp that ends the time window of interest in RFC 3339 format.
+            Any hit information that happened after this timestamp will not be returned.
+            Example: "2025-05-02T00:00:00Z"
+
+        Returns
+        -------
+        Iterable[Hit]
+            All content hit records matching the specified conditions.
+        """
+        ...
+
+    def find_by(
+        self,
+        *,
+        id: str = ...,  # noqa: A002
+        content_guid: str = ...,
+        user_guid: str = ...,
+        timestamp: str = ...,
+    ) -> Hit | None:
+        """
+        Find the first hit record matching the specified conditions.
+
+        There is no implied ordering, so if order matters, you should specify it yourself.
+
+        Parameters
+        ----------
+        id : str, not required
+            The ID of the activity record.
+        content_guid : str, not required
+            The GUID, in RFC4122 format, of the content this information pertains to.
+        user_guid : str, not required
+            The GUID, in RFC4122 format, of the user that visited the content.
+            May be null when the target content does not require a user session.
+        timestamp : str, not required
+            The timestamp, in RFC 3339 format, when the user visited the content.
+
+        Returns
+        -------
+        Hit | None
+            The first hit record matching the specified conditions, or `None` if no such record exists.
+        """
+        ...
+
+
+class _Hits(_ResourceSequence, Hits):
+    def fetch(
+        self,
+        **kwargs,
+    ) -> Iterable[Hit]:
+        """
+        Fetch all content hit records matching the specified conditions.
+
+        Parameters
+        ----------
+        start : str, not required
+            The timestamp that starts the time window of interest in RFC 3339 format.
+            Any hit information that happened prior to this timestamp will not be returned.
+            This corresponds to the `from` parameter in the API.
+            Example: "2025-05-01T00:00:00Z"
+        end : str, not required
+            The timestamp that ends the time window of interest in RFC 3339 format.
+            Any hit information that happened after this timestamp will not be returned.
+            This corresponds to the `to` parameter in the API.
+            Example: "2025-05-02T00:00:00Z"
+
+        Returns
+        -------
+        Iterable[Hit]
+            All content hit records matching the specified conditions.
+        """
+        params = rename_params(kwargs)
+        return super().fetch(**params)

src/posit/connect/metrics/metrics.py

@@ -1,6 +1,8 @@
 """Metric resources."""
 
 from .. import resources
+from ..context import requires
+from .hits import Hits, _Hits
 from .usage import Usage
 
 
@@ -16,3 +18,8 @@ class Metrics(resources.Resources):
     @property
     def usage(self) -> Usage:
         return Usage(self._ctx)
+
+    @property
+    @requires(version="2025.04.0")
+    def hits(self) -> Hits:
+        return _Hits(self._ctx, "v1/instrumentation/content/hits", uid="id")

src/posit/connect/metrics/rename_params.py

@@ -0,0 +1,22 @@
+def rename_params(params: dict) -> dict:
+    """Rename params from the internal to the external signature.
+
+    The API accepts `from` as a querystring parameter. Since `from` is a reserved word in Python, the SDK uses the name `start` instead. The querystring parameter `to` takes the same form for consistency.
+
+    Parameters
+    ----------
+    params : dict
+
+    Returns
+    -------
+    dict
+    """
+    if "start" in params:
+        params["from"] = params["start"]
+        del params["start"]
+
+    if "end" in params:
+        params["to"] = params["end"]
+        del params["end"]
+
+    return params

src/posit/connect/metrics/shiny_usage.py

@@ -4,6 +4,7 @@
 
 from ..cursors import CursorPaginator
 from ..resources import BaseResource, Resources
+from .rename_params import rename_params
 
 
 class ShinyUsageEvent(BaseResource):
@@ -171,27 +172,3 @@ def find_one(self, **kwargs) -> ShinyUsageEvent | None:
             for result in results
         )
         return next(visits, None)
-
-
-def rename_params(params: dict) -> dict:
-    """Rename params from the internal to the external signature.
-
-    The API accepts `from` as a querystring parameter. Since `from` is a reserved word in Python, the SDK uses the name `start` instead. The querystring parameter `to` takes the same form for consistency.
-
-    Parameters
-    ----------
-    params : dict
-
-    Returns
-    -------
-    dict
-    """
-    if "start" in params:
-        params["from"] = params["start"]
-        del params["start"]
-
-    if "end" in params:
-        params["to"] = params["end"]
-        del params["end"]
-
-    return params

src/posit/connect/metrics/visits.py

@@ -4,6 +4,7 @@
 
 from ..cursors import CursorPaginator
 from ..resources import BaseResource, Resources
+from .rename_params import rename_params
 
 
 class VisitEvent(BaseResource):
@@ -203,27 +204,3 @@ def find_one(self, **kwargs) -> VisitEvent | None:
             for result in results
         )
         return next(visits, None)
-
-
-def rename_params(params: dict) -> dict:
-    """Rename params from the internal to the external signature.
-
-    The API accepts `from` as a querystring parameter. Since `from` is a reserved word in Python, the SDK uses the name `start` instead. The querystring parameter `to` takes the same form for consistency.
-
-    Parameters
-    ----------
-    params : dict
-
-    Returns
-    -------
-    dict
-    """
-    if "start" in params:
-        params["from"] = params["start"]
-        del params["start"]
-
-    if "end" in params:
-        params["to"] = params["end"]
-        del params["end"]
-
-    return params

src/posit/connect/resources.py

@@ -136,7 +136,7 @@ def create(self, **attributes: Any) -> Any:
         response = self._ctx.client.post(self._path, json=attributes)
         result = response.json()
         uid = result[self._uid]
-        path = posixpath.join(self._path, uid)
+        path = posixpath.join(self._path, str(uid))
         return _Resource(self._ctx, path, **result)
 
     def fetch(self, **conditions) -> Iterable[Any]:
@@ -145,7 +145,7 @@ def fetch(self, **conditions) -> Iterable[Any]:
         resources = []
         for result in results:
             uid = result[self._uid]
-            path = posixpath.join(self._path, uid)
+            path = posixpath.join(self._path, str(uid))
             resource = _Resource(self._ctx, path, **result)
             resources.append(resource)
 
@@ -188,7 +188,7 @@ def fetch(self, **conditions):
             results = page.results
             for result in results:
                 uid = result[self._uid]
-                path = posixpath.join(self._path, uid)
+                path = posixpath.join(self._path, str(uid))
                 resource = _Resource(self._ctx, path, **result)
                 resources.append(resource)
             yield from resources

tests/posit/connect/__api__/v1/instrumentation/content/hits.json

@@ -0,0 +1,22 @@
+[
+  {
+    "id": 1001,
+    "content_guid": "bd1d2285-6c80-49af-8a83-a200effe3cb3",
+    "user_guid": "08e3a41d-1f8e-47f2-8855-f05ea3b0d4b2",
+    "timestamp": "2025-05-01T10:00:00-05:00",
+    "data": {
+      "path": "/dashboard",
+      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+    }
+  },
+  {
+    "id": 1002,
+    "content_guid": "bd1d2285-6c80-49af-8a83-a200effe3cb3",
+    "user_guid": "a5e2b41d-3f8e-47f2-9955-f05ea3b0d5c3",
+    "timestamp": "2025-05-01T10:05:00-05:00",
+    "data": {
+      "path": "/dashboard/details",
+      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
+    }
+  }
+]

tests/posit/connect/metrics/test_hits.py

@@ -0,0 +1,124 @@
+"""Tests for the hits metrics module."""
+
+import pytest
+import responses
+from responses import matchers
+
+from posit import connect
+
+from ..api import load_mock
+
+
+class TestHitsFetch:
+    @responses.activate
+    def test_fetch(self):
+        # Set up mock response
+        mock_get = responses.get(
+            "https://connect.example/__api__/v1/instrumentation/content/hits",
+            json=load_mock("v1/instrumentation/content/hits.json"),
+        )
+
+        # Create client with required version for hits API
+        c = connect.Client("https://connect.example", "12345")
+        c._ctx.version = "2025.04.0"
+
+        # Fetch hits
+        hits = list(c.metrics.hits.fetch())
+
+        # Verify request was made
+        assert mock_get.call_count == 1
+
+        # Verify results
+        assert len(hits) == 2
+        assert hits[0]["id"] == 1001
+        assert hits[0]["content_guid"] == "bd1d2285-6c80-49af-8a83-a200effe3cb3"
+        assert hits[0]["timestamp"] == "2025-05-01T10:00:00-05:00"
+        assert hits[0]["data"]["path"] == "/dashboard"
+
+    @responses.activate
+    def test_fetch_with_params(self):
+        # Set up mock response
+        mock_get = responses.get(
+            "https://connect.example/__api__/v1/instrumentation/content/hits",
+            json=load_mock("v1/instrumentation/content/hits.json"),
+            match=[
+                matchers.query_param_matcher(
+                    {
+                        "from": "2025-05-01T00:00:00Z",
+                        "to": "2025-05-02T00:00:00Z",
+                    }
+                ),
+            ],
+        )
+
+        # Create client with required version for hits API
+        c = connect.Client("https://connect.example", "12345")
+        c._ctx.version = "2025.04.0"
+
+        # Fetch hits with parameters
+        hits = list(
+            c.metrics.hits.fetch(**{"from": "2025-05-01T00:00:00Z", "to": "2025-05-02T00:00:00Z"})
+        )
+
+        # Verify request was made with proper parameters
+        assert mock_get.call_count == 1
+
+        # Verify results
+        assert len(hits) == 2
+
+
+class TestHitsFindBy:
+    @responses.activate
+    def test_find_by(self):
+        # Set up mock response
+        mock_get = responses.get(
+            "https://connect.example/__api__/v1/instrumentation/content/hits",
+            json=load_mock("v1/instrumentation/content/hits.json"),
+        )
+
+        # Create client with required version for hits API
+        c = connect.Client("https://connect.example", "12345")
+        c._ctx.version = "2025.04.0"
+
+        # Find hits by content_guid
+        hit = c.metrics.hits.find_by(content_guid="bd1d2285-6c80-49af-8a83-a200effe3cb3")
+
+        # Verify request was made
+        assert mock_get.call_count == 1
+
+        # Verify results
+        assert hit is not None
+        assert hit["id"] == 1001
+        assert hit["content_guid"] == "bd1d2285-6c80-49af-8a83-a200effe3cb3"
+
+    @responses.activate
+    def test_find_by_not_found(self):
+        # Set up mock response
+        mock_get = responses.get(
+            "https://connect.example/__api__/v1/instrumentation/content/hits",
+            json=load_mock("v1/instrumentation/content/hits.json"),
+        )
+
+        # Create client with required version for hits API
+        c = connect.Client("https://connect.example", "12345")
+        c._ctx.version = "2025.04.0"
+
+        # Try to find hit with non-existent content_guid
+        hit = c.metrics.hits.find_by(content_guid="non-existent-guid")
+
+        # Verify request was made
+        assert mock_get.call_count == 1
+
+        # Verify no result was found
+        assert hit is None
+
+
+class TestHitsVersionRequirement:
+    @responses.activate
+    def test_version_requirement(self):
+        # Create client with version that's too old
+        c = connect.Client("https://connect.example", "12345")
+        c._ctx.version = "2024.04.0"
+
+        with pytest.raises(RuntimeError):
+            h = c.metrics.hits