clarity-api 0.0.2__py2.py3-none-any.whl

clarity_api/__init__.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+# coding: utf-8
+from clarity_api.version import __version__, __author__, __credits__
+from clarity_api.clarity_api import Api
+from clarity_api.clarity_models import InputModel, Response
+
+"""
+Clarity API
+
+A Python Library for Exporting Data from Microsoft Clarity
+"""
+
+__version__ = __version__
+__author__ = __author__
+__credits__ = __credits__
+
+__all__ = [
+    "Api",
+]

clarity_api/clarity_api.py

@@ -0,0 +1,107 @@
+#!/usr/bin/python
+# coding: utf-8
+
+import requests
+import urllib3
+from typing import Union
+from pydantic import ValidationError
+
+try:
+    from clarity_api.clarity_models import InputModel, Response
+except ModuleNotFoundError:
+    from clarity_models import InputModel, Response
+try:
+    from clarity_api.decorators import require_auth
+except ModuleNotFoundError:
+    from decorators import require_auth
+try:
+    from clarity_api.exceptions import (
+        AuthError,
+        UnauthorizedError,
+        ParameterError,
+        MissingParameterError,
+    )
+except ModuleNotFoundError:
+    from exceptions import (
+        AuthError,
+        UnauthorizedError,
+        ParameterError,
+        MissingParameterError,
+    )
+try:
+    from clarity_api.utils import process_response
+except ModuleNotFoundError:
+    from utils import process_response
+
+
+class Api(object):
+
+    def __init__(
+        self,
+        url: str = None,
+        token: str = None,
+        verify: bool = True,
+    ):
+        if url is None:
+            raise MissingParameterError
+
+        self._session = requests.Session()
+        self.url = url
+        self.headers = None
+        self.verify = verify
+
+        if self.verify is False:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+        if token:
+            self.headers = {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            }
+        else:
+            raise MissingParameterError
+
+        response = self._session.get(
+            url=f"{self.url}/projects", headers=self.headers, verify=self.verify
+        )
+
+        if response.status_code == 403:
+            print(f"Unauthorized Error: {response.content}")
+            raise UnauthorizedError
+        elif response.status_code == 401:
+            print(f"Authentication Error: {response.content}")
+            raise AuthError
+        elif response.status_code == 404:
+            print(f"Parameter Error: {response.content}")
+            raise ParameterError
+
+    ####################################################################################################################
+    #                                              Data Export API                                                     #
+    ####################################################################################################################
+    @require_auth
+    def get_data_export(self, **kwargs) -> Union[Response, requests.Response]:
+        """
+        Retrieve data insights for a project
+
+        Args:
+            **kwargs: Additional keyword arguments to initialize the BranchModel.
+
+        Returns:
+            Response: The response object from the GET request.
+
+        Raises:
+            ParameterError: If the provided parameters are invalid based on the BranchModel.
+        """
+        input_model = InputModel(**kwargs)
+        try:
+            response = self._session.get(
+                url=f"{self.url}/export-data/api/v1/project-live-insights",
+                params=input_model.api_parameters,
+                headers=self.headers,
+                verify=self.verify,
+            )
+
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}")
+        response = process_response(response=response)
+        return response

clarity_api/clarity_models.py

@@ -0,0 +1,170 @@
+#!/usr/bin/python
+# coding: utf-8
+import logging
+
+from typing import Union, Dict, Optional, Any, List
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    AliasChoices,
+    Field,
+    field_validator,
+)
+
+try:
+    from clarity_api.decorators import require_auth
+except ModuleNotFoundError:
+    pass
+try:
+    from clarity_api.exceptions import (
+        AuthError,
+        UnauthorizedError,
+        ParameterError,
+        MissingParameterError,
+    )
+except ModuleNotFoundError:
+    pass
+
+logging.basicConfig(
+    level=logging.ERROR, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+
+
+class InputModel(BaseModel):
+    """
+    Pydantic model representing information about a branch.
+
+    Attributes:
+        numOfDays (Union[int, str]): The number of days to return.
+        dimension1 (str, optional): The first dimension parameters.
+        dimension2 (str, optional): The second dimension parameters.
+        dimension3 (str, optional): The third dimension parameters.
+        api_parameters (str): Additional API parameters for the group.
+
+    """
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+    numOfDays: Optional[Union[int, str]] = Field(
+        description="Number of days to save",
+        validation_alias=AliasChoices("numOfDays", "number_of_days"),
+        default=None,
+    )
+    dimension1: Optional[str] = Field(
+        description="Dimension 1",
+        validation_alias=AliasChoices("dimension1", "dimension_1"),
+        default=None,
+    )
+    dimension2: Optional[str] = Field(
+        description="Dimension 2",
+        validation_alias=AliasChoices("dimension2", "dimension_2"),
+        default=None,
+    )
+    dimension3: Optional[str] = Field(
+        description="Dimension 3",
+        validation_alias=AliasChoices("dimension3", "dimension_3"),
+        default=None,
+    )
+    api_parameters: Optional[Dict] = Field(description="API Parameters", default=None)
+
+    def model_post_init(self, __context):
+        """
+        Build the API parameters
+        """
+        self.api_parameters = {}
+        if self.numOfDays:
+            self.api_parameters["numOfDays"] = self.numOfDays
+        if self.dimension1:
+            self.api_parameters["dimension1"] = self.dimension1
+        if self.dimension2:
+            self.api_parameters["dimension2"] = self.dimension2
+        if self.dimension3:
+            self.api_parameters["dimension3"] = self.dimension3
+
+    @field_validator("numOfDays", mode="before")
+    def validate_number_of_days(cls, v):
+        """
+        Validate the 'number_of_days' parameter to ensure it is a valid integer.
+
+        Args:
+        - v: The value of 'number_of_days'.
+
+        Returns:
+        - int: The validated 'number_of_days'.
+
+        Raises:
+        - ParameterError: If 'number_of_days' is not a valid integer.
+        """
+        try:
+            v = int(v)
+        except Exception as e:
+            raise e
+        return v
+
+    @field_validator("dimension1", "dimension2", "dimension3", mode="before")
+    def validate_dimensions(cls, v):
+        """
+        Validate the 'dimensions' parameter to ensure it is a valid option.
+
+        Args:
+        - v: The value of 'dimensions'.
+
+        Returns:
+        - str: The validated 'dimensions'.
+
+        Raises:
+        - ParameterError: If 'dimensions' is not a valid option.
+        """
+        if v:
+            valid_dimensions = {
+                "browser": "Browser",
+                "device": "Device",
+                "country": "Country",
+                "os": "OS",
+                "source": "Source",
+                "medium": "Medium",
+                "campaign": "Campaign",
+                "channel": "Channel",
+                "url": "URL",
+            }
+            try:
+                return valid_dimensions[v.lower()]
+            except KeyError:
+                raise ValueError("Invalid dimension")
+
+
+class Information(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    totalSessionCount: str = Field(
+        default=None, description="The total number of sessions."
+    )
+    totalBotSessionCount: str = Field(
+        default=None, description="The total number of bot sessions."
+    )
+    distantUserCount: str = Field(default=None, description="The distant user count.")
+    PagesPerSessionPercentage: float = Field(
+        default=None, description="The pages per session percentage."
+    )
+    OS: str = Field(default=None, description="The operating system.")
+
+
+class Metric(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    metricName: str = Field(
+        default=None, description="The name of the returned metric."
+    )
+    information: List[Information] = Field(
+        default=None, description="Result containing available responses."
+    )
+
+
+class Response(BaseModel):
+    data: Optional[List[Metric]] = Field(default=None, description="Metrics returned.")
+    error: Optional[Any] = Field(default=None, description="Response error code")
+    status_code: Union[str, int] = Field(
+        default=None, description="Response status code"
+    )
+    json_output: Optional[Union[List, Dict]] = Field(
+        default=None, description="Response JSON data"
+    )
+    raw_output: Optional[bytes] = Field(default=None, description="Response Raw bytes")

clarity_api/decorators.py

@@ -0,0 +1,24 @@
+#!/usr/bin/python
+# coding: utf-8
+
+import functools
+
+try:
+    from clarity_api.exceptions import LoginRequiredError
+except ModuleNotFoundError:
+    from exceptions import LoginRequiredError
+
+
+def require_auth(function):
+    """
+    Wraps API calls in function that ensures headers are passed
+    with a token
+    """
+
+    @functools.wraps(function)
+    def wrapper(self, *args, **kwargs):
+        if not self.headers:
+            raise LoginRequiredError
+        return function(self, *args, **kwargs)
+
+    return wrapper

clarity_api/exceptions.py

@@ -0,0 +1,42 @@
+#!/usr/bin/python
+# coding: utf-8
+
+
+class AuthError(Exception):
+    """
+    Authentication error
+    """
+
+    pass
+
+
+class UnauthorizedError(AuthError):
+    """
+    Unauthorized error
+    """
+
+    pass
+
+
+class MissingParameterError(Exception):
+    """
+    Missing Parameter error
+    """
+
+    pass
+
+
+class ParameterError(Exception):
+    """
+    Parameter error
+    """
+
+    pass
+
+
+class LoginRequiredError(Exception):
+    """
+    Authentication error
+    """
+
+    pass

clarity_api/utils.py

@@ -0,0 +1,46 @@
+#!/usr/bin/python
+# coding: utf-8
+import logging
+from typing import Union
+
+import requests
+
+try:
+    from clarity_api.clarity_models import (
+        Response,
+    )
+except ModuleNotFoundError:
+    from clarity_models import (
+        Response,
+    )
+logging.basicConfig(
+    level=logging.ERROR, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+
+
+def process_response(response: requests.Response) -> Union[Response, requests.Response]:
+    response_error = None
+    try:
+        response.raise_for_status()
+    except Exception as response_error:
+        logging.error(f"Response Error: {response_error}")
+    status_code = response.status_code
+    raw_output = response.content
+    headers = response.headers
+    try:
+        response = response.json()
+    except Exception as response_error:
+        logging.error(f"JSON Conversion Error: {response_error}")
+    try:
+        response = Response(
+            information=response,
+            status_code=status_code,
+            raw_output=raw_output,
+            json_output=response,
+            headers=headers,
+            error=response_error,
+        )
+    except Exception as response_error:
+        logging.error(f"Response Model Application Error: {response_error}")
+
+    return response

clarity_api/version.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+# coding: utf-8
+
+__version__ = "0.0.2"
+__author__ = "Audel Rouhi"
+__credits__ = "Audel Rouhi"

clarity_api-0.0.2.dist-info/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2023 Audel Rouhi
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

clarity_api-0.0.2.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.1
+Name: clarity-api
+Version: 0.0.2
+Summary: Microsoft Clarity Data Export API
+Home-page: https://github.com/Knuckles-Team/clarity-api
+Author: Audel Rouhi
+Author-email: knucklessg1@gmail.com
+License: MIT
+Platform: UNKNOWN
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: Public Domain
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic[email] (>=2.5.2)
+Requires-Dist: requests (>=2.28.1)
+Requires-Dist: urllib3 (>=1.26.13)
+
+# Microsoft Clarity API
+
+![PyPI - Version](https://img.shields.io/pypi/v/clarity-api)
+![PyPI - Downloads](https://img.shields.io/pypi/dd/clarity-api)
+![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/clarity-api)
+![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/clarity-api)
+![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/clarity-api)
+![PyPI - License](https://img.shields.io/pypi/l/clarity-api)
+![GitHub](https://img.shields.io/github/license/Knuckles-Team/clarity-api)
+
+![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/clarity-api)
+![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/clarity-api)
+![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Knuckles-Team/clarity-api)
+![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/clarity-api)
+
+![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/clarity-api)
+![GitHub language count](https://img.shields.io/github/languages/count/Knuckles-Team/clarity-api)
+![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/clarity-api)
+![GitHub repo file count (file type)](https://img.shields.io/github/directory-file-count/Knuckles-Team/clarity-api)
+![PyPI - Wheel](https://img.shields.io/pypi/wheel/clarity-api)
+![PyPI - Implementation](https://img.shields.io/pypi/implementation/clarity-api)
+
+*Version: 0.0.2*
+
+**Microsoft Clarity Data Export API**
+
+This Python library allows you to work with the dashboard data. The data can be structured over a specified date range 
+and can break down insights by up to three dimensions.
+
+Find out more about the [Clarity Data Export API](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-data-export-api)
+
+This repository is actively maintained - Contributions are welcome!
+
+<details>
+  <summary><b>Getting Started:</b></summary>
+
+### Prerequisites
+- An active Microsoft Clarity account. [Learn how to sign up for Clarity](https://clarity.microsoft.com).
+- An API access token generated by the project's admin from the settings page.
+- Python3.8+
+
+### Obtaining Access Tokens
+**Note**: Only project admins can manage access tokens.
+
+1. Go to your Clarity project. Select `Settings` -> `Data Export` -> `Generate new API token`.
+2. Provide a descriptive name for the token for easy identification.
+
+## Parameters
+- `numOfDays`: (1, 2, or 3) The number of days for the data export since the API call, relating to the last 24, 48, or 72 hours, respectively.
+- `dimension1`: The first dimension to break down insights.
+- `dimension2`: The second dimension to break down insights.
+- `dimension3`: The third dimension to break down insights.
+
+#### Dimension Options:
+- Browser
+- Device
+- Country
+- OS
+- Source
+- Medium
+- Campaign
+- Channel
+- URL
+
+</details>
+
+<details>
+  <summary><b>Usage:</b></summary>
+
+```python
+#!/usr/bin/python
+# coding: utf-8
+import clarity_api
+
+# Use token generated from the steps above
+token = "<TOKEN>"
+url = "https://www.clarity.ms"
+client = clarity_api.Api(url=url, token=token)
+
+data = client.get_data_export(number_of_days=2, dimension_1="OS", dimension_2="Channel")
+print("Pydantic Object:", data)
+print("Raw Request Output:", data.raw_output)
+print("JSON Request Output:", data.json_output)
+print("Pydantic Object Model Dump:", data.model_dump())
+print("Request Status Code:", data.status_code)
+print("Request Error:", data.error)
+```
+
+</details>
+
+<details>
+  <summary><b>Installation Instructions:</b></summary>
+
+Install Python Package
+
+```bash
+python -m pip install clarity-api
+```
+
+</details>
+
+<details>
+  <summary><b>Tests:</b></summary>
+
+pre-commit check
+```bash
+pre-commit run --all-files
+```
+
+pytest
+```bash
+pytest ./test/test_clarity_models.py
+```
+</details>
+
+
+<details>
+  <summary><b>Repository Owners:</b></summary>
+
+
+<img width="100%" height="180em" src="https://github-readme-stats.vercel.app/api?username=Knucklessg1&show_icons=true&hide_border=true&&count_private=true&include_all_commits=true" />
+
+![GitHub followers](https://img.shields.io/github/followers/Knucklessg1)
+![GitHub User's stars](https://img.shields.io/github/stars/Knucklessg1)
+</details>
+
+

clarity_api-0.0.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+clarity_api/__init__.py,sha256=1RbQDB040YNxdutHk3zNzd-3rpEAZXxdsq4HxJzUdmc,391
+clarity_api/clarity_api.py,sha256=RNROb_rZ2d-iMQicWI2MGV3lJ_eq7OENFuHOtzuZNPE,3360
+clarity_api/clarity_models.py,sha256=llLMupvobbtAaa0FFDD7NFUEity3BUHBmiQcf9Ac1nI,5269
+clarity_api/decorators.py,sha256=teR4yHuA0h7QxKJFkwe4u_2n_-BR-oMXRZw1hhCCf_s,522
+clarity_api/exceptions.py,sha256=y0R-KHDuSSh1gmeRSuzlFrq6UHl8FPffi2-Sgq1AeIM,469
+clarity_api/utils.py,sha256=SnX5csZ7BP2mdx6ru904MtrOsIaJxTyalR5h-r7jWeE,1254
+clarity_api/version.py,sha256=tcG0SGm7vrK-3XSjl3-NHRbQZhx3tWy90U_dzAHPjpg,116
+clarity_api-0.0.2.dist-info/LICENSE,sha256=Z1xmcrPHBnGCETO_LLQJUeaSNBSnuptcDVTt4kaPUOE,1060
+clarity_api-0.0.2.dist-info/METADATA,sha256=B9zvMcYwAMz3W0_nm_7WjsNpMPePxnb_yO-3VuSi-WI,5076
+clarity_api-0.0.2.dist-info/WHEEL,sha256=z9j0xAa_JmUKMpmz72K0ZGALSM_n-wQVmGbleXx2VHg,110
+clarity_api-0.0.2.dist-info/top_level.txt,sha256=GzU1WAhzKvq2LNliEefbjBiag7nCE3A2W-vE2az0RiE,12
+clarity_api-0.0.2.dist-info/RECORD,,

clarity_api-0.0.2.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.37.1)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

clarity_api-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+clarity_api