canvas 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

canvas-0.1.5.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.1
+Name: canvas
+Version: 0.1.5
+Summary: SDK to customize event-driven actions in your Canvas instance
+License: MIT
+Author: Canvas Team
+Author-email: engineering@canvasmedical.com
+Requires-Python: >=3.11,<3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: cookiecutter
+Requires-Dist: grpcio (>=1.60.1,<2.0.0)
+Requires-Dist: ipython (>=8.21.0,<9.0.0)
+Requires-Dist: jsonschema (>=4.21.1,<5.0.0)
+Requires-Dist: keyring
+Requires-Dist: pydantic (>=2.6.1,<3.0.0)
+Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
+Requires-Dist: redis (>=5.0.4,<6.0.0)
+Requires-Dist: requests
+Requires-Dist: restrictedpython (>=7.1,<8.0)
+Requires-Dist: statsd (>=4.0.1,<5.0.0)
+Requires-Dist: typer[all]
+Requires-Dist: websocket-client (>=1.7.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+### Getting Started
+
+Create a file `~/.canvas/credentials.ini` and add the client_id and client_secret credentials for each of your Canvas instances. You can define your default host with `is_default=true`. If no default is explicitly defined, the Canvas CLI will use the first instance in the file as the default for each of the CLI commands.
+
+**Example:**
+
+```
+[my-canvas-instance]
+client_id=myclientid
+client_secret=myclientsecret
+
+[my-dev-canvas-instance]
+client_id=devclientid
+client_secret=devclientsecret
+is_default=true
+
+[localhost]
+client_id=localclientid
+client_secret=localclientsecret
+```
+
+Next, you're ready to install canvas.
+
+`pip install canvas`
+
+**Usage**:
+
+```console
+$ canvas [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+- `--no-ansi`: Disable colorized output
+- `--version`
+- `--verbose`: Show extra output
+- `--install-completion`: Install completion for the current shell.
+- `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+- `--help`: Show this message and exit.
+
+**Commands**:
+
+- `init`: Create a new plugin
+- `install`: Install a plugin into a Canvas instance
+- `uninstall`: Uninstall a plugin from a Canvas instance
+- `list`: List all plugins from a Canvas instance
+- `validate-manifest`: Validate the Canvas Manifest json file
+- `logs`: Listen and print log streams from a Canvas instance
+
+## `canvas init`
+
+Create a new plugin.
+
+**Usage**:
+
+```console
+$ canvas init [OPTIONS]
+```
+
+**Options**:
+
+- `--help`: Show this message and exit.
+
+## `canvas install`
+
+Install a plugin into a Canvas instance.
+
+**Usage**:
+
+```console
+$ canvas install [OPTIONS] PLUGIN_NAME
+```
+
+**Arguments**:
+
+- `PLUGIN_NAME`: Path to plugin to install [required]
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+
+## `canvas uninstall`
+
+Uninstall a plugin from a Canvas instance..
+
+**Usage**:
+
+```console
+$ canvas uninstall [OPTIONS] NAME
+```
+
+**Arguments**:
+
+- `NAME`: Plugin name to delete [required]
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+
+## `canvas list`
+
+List all plugins from a Canvas instance.
+
+**Usage**:
+
+```console
+$ canvas list [OPTIONS]
+```
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+
+## `canvas validate-manifest`
+
+Validate the Canvas Manifest json file.
+
+**Usage**:
+
+```console
+$ canvas validate-manifest [OPTIONS] PACKAGE
+```
+
+**Arguments**:
+
+- `PLUGIN_NAME`: Path to plugin to install [required]
+
+**Options**:
+
+- `--help`: Show this message and exit.
+
+## `canvas logs`
+
+Listens and prints log streams from the instance.
+
+**Usage**:
+
+```console
+$ canvas logs [OPTIONS]
+```
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+

canvas-0.1.5.dist-info/RECORD

@@ -0,0 +1,66 @@
+canvas_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+canvas_cli/apps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+canvas_cli/apps/auth/__init__.py,sha256=gIwJ2qWvRlLqbiRkudrGqTKV-orlb8OTkG487qoRda4,105
+canvas_cli/apps/auth/tests.py,sha256=WK7hSLTK95gEweMRaj3RdPC-qSwjnuulxMUg6D0bY_k,4528
+canvas_cli/apps/auth/utils.py,sha256=IH5oZB3pdlb4_FRfCZKkNTncx_kdKagpiBqlhtM8h2U,5434
+canvas_cli/apps/logs/__init__.py,sha256=ehY9SRb6nBw81xZF50yyBlUZJtNR2VeVSNI5sFuWJ7o,64
+canvas_cli/apps/logs/logs.py,sha256=R4BSqRiSmuLBGCjprDHQL5lh9rBL7Ksc79cCNQW6jMY,1825
+canvas_cli/apps/plugin/__init__.py,sha256=72Gcu2T9GsRLPbBApS9V0ZKSzehEE3hqgU_pie2T50Y,190
+canvas_cli/apps/plugin/plugin.py,sha256=3nvrZknuMO1ROS1C0Lk6o1GNPcXhWXnP1UkJJ3OsZ2E,9360
+canvas_cli/apps/plugin/tests.py,sha256=_8fHTGlQermt4AVs20nsTYcs2bDRNEqr9CGE29pD6YQ,1035
+canvas_cli/conftest.py,sha256=ZnVUIT4K4VZ92eSLTS38W6N878SVzOEfGPxsp6Rls70,959
+canvas_cli/main.py,sha256=rk2xlrQacq59ELoeO_YDMUBHFOVqlWpnV19PC0iAX4k,2527
+canvas_cli/templates/plugins/default/cookiecutter.json,sha256=dWEB3wJ8U4bko8jX26PgLLg_jgWlafLTNqsGnY1PUcg,124
+canvas_cli/templates/plugins/default/{{ cookiecutter.__project_slug }}/CANVAS_MANIFEST.json,sha256=QOUpv31Wx_eSVms13-C-L7jZ4ulKFNpokshcScKUEmo,787
+canvas_cli/templates/plugins/default/{{ cookiecutter.__project_slug }}/README.md,sha256=7QdF2JWlWwq6Us9LzkO9XWJU4IU7Q6RD_w8ImcS-hrI,347
+canvas_cli/templates/plugins/default/{{ cookiecutter.__project_slug }}/protocols/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+canvas_cli/templates/plugins/default/{{ cookiecutter.__project_slug }}/protocols/my_protocol.py,sha256=V8knH-2KHdMHMxksVEjJHxr85uFf0ipUSXBZ20r4bxM,2202
+canvas_cli/tests.py,sha256=LgiHeVHF5lxlH_pNT962uk-5D-JqNhhuu1LhSz90nK8,285
+canvas_cli/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+canvas_cli/utils/context/__init__.py,sha256=HhYvI-hydP0mV18nJiU7uo5gk0yN7EYNgouxieoGDOE,102
+canvas_cli/utils/context/context.py,sha256=zJ-UnjztG3B1fE3tAc7xej1pPFNq6wGNB8pEOTLHzqo,5714
+canvas_cli/utils/context/tests.py,sha256=aNmAggwvjKV-1WrgIvp66M46EX2QCbbHmity3bSCBTg,4211
+canvas_cli/utils/print/__init__.py,sha256=zkRiQCUhPIB3wNGeJ1Hwfd12zJyvbRRiWqequJORvdE,88
+canvas_cli/utils/print/print.py,sha256=1lYglwBefZf0xONN-6PiWxe0ruNU31CTnzDJIhx_VAk,1829
+canvas_cli/utils/print/tests.py,sha256=4kqp_uMpUUjSXokD_Hxs2aMyx50_JzGABAQoNC4XTrM,2376
+canvas_cli/utils/urls/__init__.py,sha256=08hlrQhQ1pKBjlIRaC0j53IkgK723jfK8-j3djvR0ko,81
+canvas_cli/utils/urls/tests.py,sha256=opXDF2i3lXTdsKJ7ywIRzWDDzZ5KAO0JbGIR3hbJdoE,407
+canvas_cli/utils/urls/urls.py,sha256=KwWTh5ERrEsZEvdBrZpZB71xtyWkDuglpXUbycWmBOo,798
+canvas_cli/utils/validators/__init__.py,sha256=rBvSR2O1hWkNAnUBdcr-zUkmqT796_A61b9pnvEhwrM,113
+canvas_cli/utils/validators/manifest_schema.py,sha256=SIMpr_vTV8dtkO9cjsRnZZtRm5tgGkPR6QewTG8CztI,3117
+canvas_cli/utils/validators/tests.py,sha256=cZHLSx7oteOfLOoU1tXGvw88n6itcvUT2B3ZBg-bmEY,1206
+canvas_cli/utils/validators/validators.py,sha256=RKDKxIvZ1IuCPVuhQ1KHdpwu7aewAqT9ZX-nA-LZDdg,1614
+canvas_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+canvas_sdk/commands/__init__.py,sha256=4JTiljkBJ2Da2mU3_VAJ5dcpxg0X3QAocYJBBMJRpGc,1116
+canvas_sdk/commands/base.py,sha256=qVgZMBFwdHw6Y66TN68QNlrewr2RqYSpiD1RIPUqUyk,4141
+canvas_sdk/commands/commands/assess.py,sha256=uQgLwDp_9I8fjy3reA4g2RSvGY0Ee8UijfwpsvrMRS4,1636
+canvas_sdk/commands/commands/diagnose.py,sha256=3bg4ScNzTKJa7sXv3xH9VKQSF_srX_G3m-Xpe-VKzzQ,1382
+canvas_sdk/commands/commands/goal.py,sha256=WE5q8oFRtQmclqdCydG4WYW4hoodOvd9dEiSGkJfGqs,1527
+canvas_sdk/commands/commands/history_present_illness.py,sha256=TQ-upptwYy-EKAegqT5jyU7csQpOZeqzp8VfBZTO0mw,366
+canvas_sdk/commands/commands/medication_statement.py,sha256=Ww-WuMbvosfY7Uv8sTFUjPaBGxUoA-ptdcw6Q569DeY,937
+canvas_sdk/commands/commands/plan.py,sha256=Q-e4wqTL6zafG7tOk_9R0mi5pDGqVXKxgbFjsB8CS4Q,350
+canvas_sdk/commands/commands/prescribe.py,sha256=4EQHRhTtW_FHJDOaUgMu8lSgK8JKtUcNrOUs8hbTSdw,1574
+canvas_sdk/commands/commands/questionnaire.py,sha256=XmwpANCHRV_kV2B_X7xqAJ39yX7bn9iT8XHuVoFfLFk,553
+canvas_sdk/commands/commands/reason_for_visit.py,sha256=Zs2WKybbMWvimoZc4ehGxqXNWvX7c0snAe34adP2A4E,1252
+canvas_sdk/commands/commands/stop_medication.py,sha256=5AIPEBBqT1mhpQOcCPh3FJfVq487Qtq3fNrWXqNxqhM,627
+canvas_sdk/commands/commands/update_goal.py,sha256=yiOiHiSwfOzFUAz61C7i6WIJ2o-OUmjmXzm33GcIC3E,1499
+canvas_sdk/commands/constants.py,sha256=LVAuWvxDuDzsW74JUWIzy_lMLvte0_Grlldr-YCjgBw,176
+canvas_sdk/commands/tests/test_utils.py,sha256=gdW9e82-Z9Xm3LyYVa7Pd7sGreL-gtP854iC1UIhOEc,6287
+canvas_sdk/commands/tests/tests.py,sha256=3ZIsIi0GmXV3jm8QmEhLn_FwL8qpW6yt5jjq9FQwHPA,13863
+canvas_sdk/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+canvas_sdk/effects/__init__.py,sha256=w3-PimW34Li9b8l_aWCyM7X8-jxMIM3e0ttXg44CV2k,62
+canvas_sdk/effects/banner_alert/banner_alert.py,sha256=Vb23JpwAvfH5GoZpGcHzuWyNQ68cfLXOJjRgbPBaB_M,1013
+canvas_sdk/effects/banner_alert/constants.py,sha256=kfd113dGYDm-g_B5iZb47VNpJjioGqQZSNRoR_rsktw,436
+canvas_sdk/effects/base.py,sha256=h67VmsgMq_Dvr01w8UEf204UqiGjomYrMf_InHzibm4,688
+canvas_sdk/events/__init__.py,sha256=oh1hgaoXbWmPBUUvMb_F0n0Chf5L42ZkKIvvLf-Olzk,74
+canvas_sdk/protocols/__init__.py,sha256=GKtNMsJ5XaNOJUz9adE2_pONLeZqkZIrd9hXAU-jzvU,51
+canvas_sdk/protocols/base.py,sha256=A7K1IcCFU44M7ygwn2iD2LsM4xDlITxRZsDbDWRQPnE,260
+canvas_sdk/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+canvas_sdk/utils/__init__.py,sha256=sFuhqcWvXb2-33FOuXZgWuUeC5jZL2MDoqjGoQZGwd8,60
+canvas_sdk/utils/http.py,sha256=YOgUFp7FOFhbDwkGhCiD3JLZ342oNZR-qncMxv2qSjw,2159
+canvas_sdk/utils/tests.py,sha256=t3MScbIfzXkQttMIvj0dRzJlFVS8LFU8WgWRrChM-H0,1931
+canvas_sdk/views/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+canvas-0.1.5.dist-info/METADATA,sha256=b5qC30REXgMjT6HLvuNyYoBI4f4TBULVOXlrSNgcR-Q,3776
+canvas-0.1.5.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+canvas-0.1.5.dist-info/entry_points.txt,sha256=VSmSo1IZ3aEfL7enmLmlWSraS_IIkoXNVeyXzgRxFiY,46
+canvas-0.1.5.dist-info/RECORD,,

{canvas-0.1.4.dist-info → canvas-0.1.5.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.8.1
+Generator: poetry-core 1.9.0
 Root-Is-Purelib: true
 Tag: py3-none-any

canvas-0.1.5.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+canvas=canvas_cli.main:app
+

canvas_cli/apps/auth/__init__.py

@@ -0,0 +1,3 @@
+from canvas_cli.apps.auth.utils import get_or_request_api_token
+
+__all__ = ("get_or_request_api_token",)

canvas_cli/apps/auth/tests.py

@@ -0,0 +1,142 @@
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from canvas_cli.apps.auth import get_or_request_api_token
+
+
+@pytest.fixture
+def valid_token_response() -> Any:
+    class TokenResponse:
+        status_code = 200
+
+        def json(self) -> dict:
+            return {"access_token": "a-valid-api-token", "expires_in": 3600}
+
+    return TokenResponse()
+
+
+@pytest.fixture
+def error_token_response() -> Any:
+    class TokenResponse:
+        status_code = 500
+
+    return TokenResponse()
+
+
+@pytest.fixture
+def expired_token_response() -> Any:
+    class TokenResponse:
+        status_code = 200
+
+        def json(self) -> dict:
+            return {"access_token": "a-valid-api-token", "expires_in": -1}
+
+    return TokenResponse()
+
+
+@patch("keyring.get_password")
+@patch("requests.Session.post")
+@patch("canvas_cli.apps.auth.utils.is_token_valid")
+def test_get_or_request_api_token_uses_stored_token(
+    mock_is_token_valid: MagicMock,
+    mock_post: MagicMock,
+    mock_get_password: MagicMock,
+    valid_token_response: Any,
+) -> None:
+    mock_is_token_valid.return_value = True
+    mock_get_password.return_value = "a-stored-valid-token"
+    mock_post.return_value = valid_token_response
+
+    token = get_or_request_api_token("http://localhost:8000")
+
+    assert token == "a-stored-valid-token"
+    mock_post.assert_not_called()
+
+
+@patch("keyring.set_password")
+@patch("keyring.get_password")
+@patch("requests.Session.post")
+@patch("canvas_cli.apps.auth.utils.get_api_client_credentials")
+def test_get_or_request_api_token_requests_token_if_none_stored(
+    mock_client_credentials: MagicMock,
+    mock_post: MagicMock,
+    mock_get_password: MagicMock,
+    mock_set_password: MagicMock,
+    valid_token_response: Any,
+) -> None:
+    mock_client_credentials.return_value = "client_id=id&client_secret=secret"
+    mock_get_password.return_value = None
+    mock_post.return_value = valid_token_response
+
+    token = get_or_request_api_token("http://localhost:8000")
+
+    assert token == "a-valid-api-token"
+    mock_post.assert_called_once_with(
+        "http://localhost:8000/auth/token/",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        json=None,
+        data="grant_type=client_credentials&scope=system/Plugins.*&client_id=id&client_secret=secret",
+    )
+    mock_set_password.assert_called_with(
+        "canvas_cli.apps.auth.utils",
+        username="http://localhost:8000|token",
+        password="a-valid-api-token",
+    )
+
+
+@patch("keyring.get_password")
+@patch("requests.Session.post")
+@patch("canvas_cli.apps.auth.utils.get_api_client_credentials")
+def test_get_or_request_api_token_raises_exception_if_error_token_response(
+    mock_client_credentials: MagicMock,
+    mock_post: MagicMock,
+    mock_get_password: MagicMock,
+    error_token_response: Any,
+) -> None:
+    mock_client_credentials.return_value = "client_id=id&client_secret=secret"
+    mock_get_password.return_value = None
+    mock_post.return_value = error_token_response
+
+    with pytest.raises(Exception) as e:
+        get_or_request_api_token("http://localhost:8000")
+
+    assert "Unable to get a valid access token from the given host 'http://localhost:8000'" in repr(
+        e
+    )
+
+    mock_post.assert_called_once_with(
+        "http://localhost:8000/auth/token/",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        json=None,
+        data="grant_type=client_credentials&scope=system/Plugins.*&client_id=id&client_secret=secret",
+    )
+
+
+@patch("keyring.get_password")
+@patch("requests.Session.post")
+@patch("canvas_cli.apps.auth.utils.get_api_client_credentials")
+def test_get_or_request_api_token_raises_exception_if_expired_token(
+    mock_client_credentials: MagicMock,
+    mock_post: MagicMock,
+    mock_get_password: MagicMock,
+    expired_token_response: Any,
+) -> None:
+    mock_client_credentials.return_value = "client_id=id&client_secret=secret"
+    mock_get_password.return_value = None
+    mock_post.return_value = expired_token_response
+
+    with pytest.raises(Exception) as e:
+        get_or_request_api_token("http://localhost:8000")
+
+    assert (
+        "A valid token could not be acquired from the given host 'http://localhost:8000'" in repr(e)
+    )
+
+    mock_post.assert_called_once_with(
+        "http://localhost:8000/auth/token/",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        json=None,
+        data="grant_type=client_credentials&scope=system/Plugins.*&client_id=id&client_secret=secret",
+    )

canvas_cli/apps/auth/utils.py

@@ -0,0 +1,163 @@
+import configparser
+from datetime import datetime, timedelta
+from pathlib import Path
+from urllib.parse import urlparse
+
+import keyring
+import requests
+
+from canvas_sdk.utils import Http
+
+# Keyring namespace we'll use
+KEYRING_SERVICE = __name__
+
+CONFIG_PATH = Path.home() / ".canvas" / "credentials.ini"
+
+LOCALHOST = "http://localhost:8000"
+
+
+def get_password(username: str) -> str | None:
+    """Return the stored password for username, or None."""
+    return keyring.get_password(KEYRING_SERVICE, username)
+
+
+def set_password(username: str, password: str) -> None:
+    """Set the password for the given username."""
+    keyring.set_password(KEYRING_SERVICE, username=username, password=password)
+
+
+def delete_password(username: str) -> None:
+    """Delete the password for the given username."""
+    keyring.delete_password(KEYRING_SERVICE, username=username)
+
+
+def get_config() -> configparser.ConfigParser:
+    """Reads the config file and returns a ConfigParser object."""
+    config = configparser.ConfigParser()
+    if not config.read(CONFIG_PATH):
+        raise Exception(
+            f"""Please add your configuration file at '{CONFIG_PATH}' with the following format:
+
+            [my-canvas-subdomain]
+            client_id=myclientid
+            client_secret=myclientsecret
+
+            [my-dev-canvas-subdomain]
+            client_id=devclientid
+            client_secret=devclientsecret
+            is_default=true
+
+            [localhost]
+            client_id=localclientid
+            client_secret=localclientsecret
+            """
+        )
+    return config
+
+
+def read_config(host: str, property: str) -> str:
+    """Reads the config file and returns the property for a given section."""
+    config = get_config()
+    if host not in config:
+        raise Exception(f"'{host}' is not found in the configuration file at '{CONFIG_PATH}'")
+    return config.get(host, property)
+
+
+def get_api_client_credentials(host: str) -> str:
+    """Either return the given api_key, or fetch it from the keyring."""
+    hostname = urlparse(host).hostname
+
+    if not hostname:
+        raise ValueError("Could not parse hostname from URL")
+
+    instance = hostname.removesuffix(".canvasmedical.com")
+
+    client_id = read_config(instance, "client_id")
+    client_secret = read_config(instance, "client_secret")
+
+    return f"client_id={client_id}&client_secret={client_secret}"
+
+
+def get_default_host(host: str | None = None) -> str:
+    """Return the explicitly stated default host, or first if none is indicated."""
+    if host:
+        if "://" in host:
+            return host
+
+        if "localhost" in host:
+            return LOCALHOST
+
+        return f"https://{host}.canvasmedical.com"
+
+    config = get_config()
+    if not (hosts := config.sections()):
+        raise Exception(f"No hosts found in the configuration file at '{CONFIG_PATH}'")
+
+    first_default_host = next(
+        (host for host in hosts if config.getboolean(host, "is_default", fallback=False) is True),
+        hosts[0],
+    )
+    if first_default_host == "localhost":
+        return LOCALHOST
+
+    return f"https://{first_default_host}.canvasmedical.com"
+
+
+def request_api_token(host: str, api_client_credentials: str) -> dict:
+    """Request an api token using the provided client_id and client_secret."""
+    grant_type = "grant_type=client_credentials"
+    scope = "scope=system/Plugins.*"
+
+    http = Http()
+    token_response = http.post(
+        f"{host}/auth/token/",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        data=f"{grant_type}&{scope}&{api_client_credentials}",
+    )
+    if token_response.status_code != requests.codes.ok:
+        raise Exception(f"Unable to get a valid access token from the given host '{host}'")
+    return token_response.json()
+
+
+def is_token_valid(host_token_key: str, expiration_date: datetime | None = None) -> bool:
+    """True if the token has not expired yet."""
+    token_exp_date_key = f"{host_token_key}|exp_date"
+
+    if expiration_date:
+        if expiration_date <= datetime.now():
+            return False
+        set_password(token_exp_date_key, expiration_date.isoformat())
+        return True
+
+    stored_expiration_date = get_password(token_exp_date_key)
+    return (
+        stored_expiration_date is not None
+        and datetime.fromisoformat(stored_expiration_date) > datetime.now()
+    )
+
+
+def get_or_request_api_token(host: str | None = None) -> str:
+    """Returns an existing stored token if it has not expired, or requests a new one."""
+    if not (host := get_default_host(host)):
+        raise Exception(
+            f"Please specify a host or add one to the configuration file at '{CONFIG_PATH}'"
+        )
+
+    host_token_key = f"{host}|token"
+    token = get_password(host_token_key)
+
+    if token and is_token_valid(host_token_key):
+        return token
+
+    api_client_credentials = get_api_client_credentials(host)
+
+    if not (token_response := request_api_token(host, api_client_credentials)):
+        raise Exception(f"A token could not be acquired from the given host '{host}'")
+
+    token_expiration_date = datetime.now() + timedelta(seconds=token_response["expires_in"])
+    if not is_token_valid(host_token_key, token_expiration_date):
+        raise Exception(f"A valid token could not be acquired from the given host '{host}'")
+
+    new_token = token_response["access_token"]
+    set_password(host_token_key, new_token)
+    return new_token

canvas_cli/apps/logs/__init__.py

@@ -0,0 +1,3 @@
+from canvas_cli.apps.logs.logs import logs
+
+__all__ = ("logs",)

canvas_cli/apps/logs/logs.py

@@ -0,0 +1,59 @@
+from typing import Optional
+from urllib.parse import urlparse
+
+import typer
+import websocket
+
+from canvas_cli.apps.auth.utils import get_default_host, get_or_request_api_token
+from canvas_cli.utils.print import print
+
+
+def _on_message(ws: websocket.WebSocketApp, message: str) -> None:
+    print.json(message)
+
+
+def _on_error(ws: websocket.WebSocketApp, error: str) -> None:
+    print.json(f"Error: {error}", success=False)
+
+
+def _on_close(ws: websocket.WebSocketApp, close_status_code: str, close_msg: str) -> None:
+    print.json(f"Connection closed with status code {close_status_code}: {close_msg}")
+
+
+def _on_open(ws: websocket.WebSocketApp) -> None:
+    print.json("Connected to the logging service")
+
+
+def logs(
+    host: Optional[str] = typer.Option(
+        callback=get_default_host, help="Canvas instance to connect to", default=None
+    )
+) -> None:
+    """Listens and prints log streams from the instance."""
+    if not host:
+        raise typer.BadParameter("Please specify a host or add one to the configuration file")
+
+    token = get_or_request_api_token(host)
+
+    # Resolve the instance name from the Canvas host URL (e.g., extract
+    # 'example' from 'https://example.canvasmedical.com/')
+    hostname = urlparse(host).hostname
+    instance = hostname.removesuffix(".canvasmedical.com")
+
+    print.json(
+        f"Connecting to the log stream. Please be patient as there may be a delay before log messages appear."
+    )
+    websocket_uri = f"wss://logs.console.canvasmedical.com/{instance}?token={token}"
+
+    try:
+        ws = websocket.WebSocketApp(
+            websocket_uri,
+            on_message=_on_message,
+            on_error=_on_error,
+            on_close=_on_close,
+        )
+        ws.on_open = _on_open
+        ws.run_forever()
+
+    except KeyboardInterrupt:
+        raise typer.Exit(0)

canvas_cli/apps/plugin/__init__.py

@@ -0,0 +1,9 @@
+from canvas_cli.apps.plugin.plugin import (
+    init,
+    install,
+    list,
+    uninstall,
+    validate_manifest,
+)
+
+__all__ = ("uninstall", "init", "validate_manifest", "install", "list")