kiosker-python-api 1.2.0__tar.gz

kiosker_python_api-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Top North AB
+
+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.

kiosker_python_api-1.2.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: kiosker-python-api
+Version: 1.2.0
+Summary: A python wrapper for the Kiosker API
+Project-URL: Homepage, https://kiosker.io
+Project-URL: Documentation, https://docs.kiosker.io
+Project-URL: Repository, https://github.com/Top-North/kiosker-python.git
+Project-URL: Issues, https://github.com/Top-North/kiosker-python/issues
+Author-email: Martin Claesson <martin@topnorth.se>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,kiosk,kiosker,kiosker pro
+Requires-Dist: httpx
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Python wrapper for Kiosker API
+Python wrapper for Kiosker API-integration.
+
+---
+
+### Installation
+
+```shell
+pip3 install kiosker-python
+```
+
+---
+
+### Setup
+
+```python
+from kiosker.api import KioskerAPI
+api = KioskerAPI('10.0.1.100', 'token')
+```
+
+---
+
+### Functions
+
+#### Get Status
+```python
+status = api.status()
+
+print('Status:')
+print(f'Device ID: {status.device_id}')
+print(f'Model: {status.model}')
+print(f'OS version: {status.os_version}')
+print(f'Battery level: {status.battery_level}%')
+print(f'Battery state: {status.battery_state}')
+print(f'Last interaction: {status.last_interaction}')
+print(f'Last motion: {status.last_motion}')
+print(f'Last status update: {status.last_update}')
+print(f'Screensaver pause: {status.screensaver_pause}')
+```
+**Description**: Retrieves the current status of the kiosk.
+
+#### Ping the API
+```python
+result = api.ping()
+print(f"Ping successful: {result}")
+```
+**Description**: Checks if the API is reachable. Returns `True` if successful, otherwise raises an error.
+
+#### Navigate to a URL
+```python
+result = api.navigate_url('https://example.com')
+print(f"Navigation result: {result}")
+```
+**Description**: Navigates the kiosk to the specified URL.
+
+#### Refresh the Page
+```python
+result = api.navigate_refresh()
+print(f"Refresh result: {result}")
+```
+**Description**: Refreshes the current page on the kiosk.
+
+#### Navigate Home
+```python
+result = api.navigate_home()
+print(f"Home navigation result: {result}")
+```
+**Description**: Navigates the kiosk to the home page.
+
+#### Navigate Forward
+```python
+result = api.navigate_forward()
+print(f"Navigate forward result: {result}")
+```
+**Description**: Navigates forward in the browser's history.
+
+#### Navigate Backward
+```python
+result = api.navigate_backward()
+print(f"Navigate backward result: {result}")
+```
+**Description**: Navigates backward in the browser's history.
+
+#### Print
+```python
+result = api.print()
+print(f"Print result: {result}")
+```
+**Description**: Sends a print command to the kiosk.
+
+#### Clear Cookies
+```python
+result = api.clear_cookies()
+print(f"Cookies cleared: {result}")
+```
+**Description**: Clears all cookies stored on the kiosk.
+
+#### Clear Cache
+```python
+result = api.clear_cache()
+print(f"Cache cleared: {result}")
+```
+**Description**: Clears the cache on the kiosk.
+
+#### Interact with Screensaver
+```python
+result = api.screensaver_interact()
+print(f"Screensaver interaction result: {result}")
+```
+**Description**: Simulates user interaction with the screensaver to prevent it from activating.
+
+#### Set Screensaver State
+```python
+result = api.screensaver_set_state(disabled=True)
+print(f"Screensaver disabled: {result}")
+```
+**Description**: Enables or disables the screensaver.
+
+#### Get Screensaver State
+```python
+state = api.screensaver_get_state()
+print(f"Screensaver state: {state}")
+```
+**Description**: Retrieves the current state of the screensaver (enabled or disabled).
+
+#### Set Blackout
+```python
+from kiosker.data import Blackout
+
+blackout = Blackout(
+    visible=True,                   # Required: show blackout screen
+    text="Maintenance in progress", # Optional: text to display
+    background="#000000",           # Optional: background color (hex)
+    foreground="#FFFFFF",           # Optional: foreground/text color (hex)
+    icon="warning",                 # Optional: icon name (SF Symbol)
+    expire=60,                      # Optional: time in seconds before blackout expires
+    dismissible=True,               # Optional: allow user to dismiss blackout with a button
+    buttonBackground="#FF0000",     # Optional: button background color (hex)
+    buttonForeground="#FFFFFF",     # Optional: button text color (hex)
+    buttonText="OK",                # Optional: button label
+    sound="1003"                    # Optional: sound to play (SystemSoundID)
+)
+result = api.blackout_set(blackout)
+print(f"Blackout set: {result}")
+```
+**Description**: Sets a blackout screen with customizable text, colors, expiration time, and optional button/sound options.
+
+#### Get Blackout State
+```python
+blackout_state = api.blackout_get()
+print(f"Blackout state: {blackout_state}")
+```
+**Description**: Retrieves the current state of the blackout screen.
+
+#### Clear Blackout
+```python
+result = api.blackout_clear()
+print(f"Blackout cleared: {result}")
+```
+**Description**: Clears the blackout screen.
+
+---
+
+### Objects
+
+#### `Status`
+Represents the current status of the kiosk.
+
+**Attributes**:
+- `battery_level` (int): Battery percentage.
+- `battery_state` (str): Current battery state (e.g., charging, discharging).
+- `model` (str): Device model.
+- `os_version` (str): Operating system version.
+- `last_interaction` (datetime): Timestamp of the last user interaction.
+- `last_motion` (Optional[datetime]): Timestamp of the last detected motion.
+- `last_update` (datetime): Timestamp of the last status update.
+- `device_id` (str): Unique identifier for the device.
+- `screensaver_pause` (Optional[bool]): Whether the screensaver is paused.
+
+#### `Result`
+Represents the result of an API operation.
+
+**Attributes**:
+- `error` (bool): Indicates if an error occurred.
+- `reason` (Optional[str]): Reason for the error, if any.
+- `function` (Optional[str]): Name of the function that caused the error.
+
+#### `Blackout`
+Represents a blackout screen configuration.
+
+**Attributes**:
+- `visible` (bool): Whether the blackout screen is visible.
+- `text` (Optional[str]): Text to display on the blackout screen.
+- `background` (str): Background color in hex format.
+- `foreground` (str): Foreground color in hex format.
+- `icon` (Optional[str]): Icon to display on the blackout screen.
+- `expire` (int): Time in seconds before the blackout screen expires.
+
+---
+
+### Development
+1. Clone the project
+
+2. Create a virtual environment
+```shell
+python3 -m venv venv
+```
+
+3. Activate the virtual environment
+```shell
+source venv/bin/activate
+```
+
+4. Install dependencies
+```shell
+pip install wheel setuptools twine pytest httpx
+```
+
+5. Run tests
+```shell
+HOST="0.0.0.0" TOKEN="" pytest -s
+```
+
+6. Build the library
+```shell
+python -m build --sdist
+```
+
+7. Upload to test
+```shell
+twine upload --repository testpypi dist/*
+```
+
+---
+
+### API Documentation
+- [Docs](https://docs.kiosker.io/#/api)
+- [Definition](https://swagger.kiosker.io)
+
+---
+
+### Get Kiosker for iOS on the App Store
+- [Kiosker](https://apps.apple.com/us/app/kiosker-fullscreen-web-kiosk/id1481691530?uo=4&at=11l6hc&ct=fnd)
+- [Kiosker Pro](https://apps.apple.com/us/app/kiosker-pro-web-kiosk/id1446738885?uo=4&at=11l6hc&ct=fnd)

kiosker_python_api-1.2.0/README.md

@@ -0,0 +1,244 @@
+# Python wrapper for Kiosker API
+Python wrapper for Kiosker API-integration.
+
+---
+
+### Installation
+
+```shell
+pip3 install kiosker-python
+```
+
+---
+
+### Setup
+
+```python
+from kiosker.api import KioskerAPI
+api = KioskerAPI('10.0.1.100', 'token')
+```
+
+---
+
+### Functions
+
+#### Get Status
+```python
+status = api.status()
+
+print('Status:')
+print(f'Device ID: {status.device_id}')
+print(f'Model: {status.model}')
+print(f'OS version: {status.os_version}')
+print(f'Battery level: {status.battery_level}%')
+print(f'Battery state: {status.battery_state}')
+print(f'Last interaction: {status.last_interaction}')
+print(f'Last motion: {status.last_motion}')
+print(f'Last status update: {status.last_update}')
+print(f'Screensaver pause: {status.screensaver_pause}')
+```
+**Description**: Retrieves the current status of the kiosk.
+
+#### Ping the API
+```python
+result = api.ping()
+print(f"Ping successful: {result}")
+```
+**Description**: Checks if the API is reachable. Returns `True` if successful, otherwise raises an error.
+
+#### Navigate to a URL
+```python
+result = api.navigate_url('https://example.com')
+print(f"Navigation result: {result}")
+```
+**Description**: Navigates the kiosk to the specified URL.
+
+#### Refresh the Page
+```python
+result = api.navigate_refresh()
+print(f"Refresh result: {result}")
+```
+**Description**: Refreshes the current page on the kiosk.
+
+#### Navigate Home
+```python
+result = api.navigate_home()
+print(f"Home navigation result: {result}")
+```
+**Description**: Navigates the kiosk to the home page.
+
+#### Navigate Forward
+```python
+result = api.navigate_forward()
+print(f"Navigate forward result: {result}")
+```
+**Description**: Navigates forward in the browser's history.
+
+#### Navigate Backward
+```python
+result = api.navigate_backward()
+print(f"Navigate backward result: {result}")
+```
+**Description**: Navigates backward in the browser's history.
+
+#### Print
+```python
+result = api.print()
+print(f"Print result: {result}")
+```
+**Description**: Sends a print command to the kiosk.
+
+#### Clear Cookies
+```python
+result = api.clear_cookies()
+print(f"Cookies cleared: {result}")
+```
+**Description**: Clears all cookies stored on the kiosk.
+
+#### Clear Cache
+```python
+result = api.clear_cache()
+print(f"Cache cleared: {result}")
+```
+**Description**: Clears the cache on the kiosk.
+
+#### Interact with Screensaver
+```python
+result = api.screensaver_interact()
+print(f"Screensaver interaction result: {result}")
+```
+**Description**: Simulates user interaction with the screensaver to prevent it from activating.
+
+#### Set Screensaver State
+```python
+result = api.screensaver_set_state(disabled=True)
+print(f"Screensaver disabled: {result}")
+```
+**Description**: Enables or disables the screensaver.
+
+#### Get Screensaver State
+```python
+state = api.screensaver_get_state()
+print(f"Screensaver state: {state}")
+```
+**Description**: Retrieves the current state of the screensaver (enabled or disabled).
+
+#### Set Blackout
+```python
+from kiosker.data import Blackout
+
+blackout = Blackout(
+    visible=True,                   # Required: show blackout screen
+    text="Maintenance in progress", # Optional: text to display
+    background="#000000",           # Optional: background color (hex)
+    foreground="#FFFFFF",           # Optional: foreground/text color (hex)
+    icon="warning",                 # Optional: icon name (SF Symbol)
+    expire=60,                      # Optional: time in seconds before blackout expires
+    dismissible=True,               # Optional: allow user to dismiss blackout with a button
+    buttonBackground="#FF0000",     # Optional: button background color (hex)
+    buttonForeground="#FFFFFF",     # Optional: button text color (hex)
+    buttonText="OK",                # Optional: button label
+    sound="1003"                    # Optional: sound to play (SystemSoundID)
+)
+result = api.blackout_set(blackout)
+print(f"Blackout set: {result}")
+```
+**Description**: Sets a blackout screen with customizable text, colors, expiration time, and optional button/sound options.
+
+#### Get Blackout State
+```python
+blackout_state = api.blackout_get()
+print(f"Blackout state: {blackout_state}")
+```
+**Description**: Retrieves the current state of the blackout screen.
+
+#### Clear Blackout
+```python
+result = api.blackout_clear()
+print(f"Blackout cleared: {result}")
+```
+**Description**: Clears the blackout screen.
+
+---
+
+### Objects
+
+#### `Status`
+Represents the current status of the kiosk.
+
+**Attributes**:
+- `battery_level` (int): Battery percentage.
+- `battery_state` (str): Current battery state (e.g., charging, discharging).
+- `model` (str): Device model.
+- `os_version` (str): Operating system version.
+- `last_interaction` (datetime): Timestamp of the last user interaction.
+- `last_motion` (Optional[datetime]): Timestamp of the last detected motion.
+- `last_update` (datetime): Timestamp of the last status update.
+- `device_id` (str): Unique identifier for the device.
+- `screensaver_pause` (Optional[bool]): Whether the screensaver is paused.
+
+#### `Result`
+Represents the result of an API operation.
+
+**Attributes**:
+- `error` (bool): Indicates if an error occurred.
+- `reason` (Optional[str]): Reason for the error, if any.
+- `function` (Optional[str]): Name of the function that caused the error.
+
+#### `Blackout`
+Represents a blackout screen configuration.
+
+**Attributes**:
+- `visible` (bool): Whether the blackout screen is visible.
+- `text` (Optional[str]): Text to display on the blackout screen.
+- `background` (str): Background color in hex format.
+- `foreground` (str): Foreground color in hex format.
+- `icon` (Optional[str]): Icon to display on the blackout screen.
+- `expire` (int): Time in seconds before the blackout screen expires.
+
+---
+
+### Development
+1. Clone the project
+
+2. Create a virtual environment
+```shell
+python3 -m venv venv
+```
+
+3. Activate the virtual environment
+```shell
+source venv/bin/activate
+```
+
+4. Install dependencies
+```shell
+pip install wheel setuptools twine pytest httpx
+```
+
+5. Run tests
+```shell
+HOST="0.0.0.0" TOKEN="" pytest -s
+```
+
+6. Build the library
+```shell
+python -m build --sdist
+```
+
+7. Upload to test
+```shell
+twine upload --repository testpypi dist/*
+```
+
+---
+
+### API Documentation
+- [Docs](https://docs.kiosker.io/#/api)
+- [Definition](https://swagger.kiosker.io)
+
+---
+
+### Get Kiosker for iOS on the App Store
+- [Kiosker](https://apps.apple.com/us/app/kiosker-fullscreen-web-kiosk/id1481691530?uo=4&at=11l6hc&ct=fnd)
+- [Kiosker Pro](https://apps.apple.com/us/app/kiosker-pro-web-kiosk/id1446738885?uo=4&at=11l6hc&ct=fnd)

kiosker_python_api-1.2.0/build/lib/kiosker/api.py

@@ -0,0 +1,26 @@
+from math import radians, cos, sin, asin, sqrt
+
+
+# Test
+def haversine(lon1: float, lat1: float, lon2: float, lat2: float) -> float:
+    """
+    Calculate the great circle distance between two points on the 
+    earth (specified in decimal degrees), returns the distance in
+    kilometers.
+    All arguments must be of equal length.
+    :param lon1: longitude of first place
+    :param lat1: latitude of first place
+    :param lon2: longitude of second place
+    :param lat2: latitude of second place
+    :return: distance in kilometers between the two sets of coordinates
+    """
+    # Convert decimal degrees to radians
+    lon1, lat1, lon2, lat2 = map(radians, [lon1, lat1, lon2, lat2])
+
+    # Haversine formula
+    dlon = lon2 - lon1
+    dlat = lat2 - lat1
+    a = sin(dlat/2)**2 + cos(lat1) * cos(lat2) * sin(dlon/2)**2
+    c = 2 * asin(sqrt(a))
+    r = 6371 # Radius of earth in kilometers
+    return c * r

kiosker_python_api-1.2.0/build/lib/tests/test_api.py

@@ -0,0 +1,7 @@
+from kiosker import api
+
+def test_haversine():
+    # Amsterdam to Berlin
+    assert api.haversine(
+        4.895168, 52.370216, 13.404954, 52.520008
+    ) == 576.6625818456291

kiosker_python_api-1.2.0/kiosker/__init__.py

@@ -0,0 +1,2 @@
+from .api import KioskerAPI
+from .data import Status, Result, Blackout

kiosker_python_api-1.2.0/kiosker/api.py

@@ -0,0 +1,103 @@
+import httpx
+from .data import Status, Result, Blackout, ScreensaverState
+
+API_PATH = '/api/v1'
+
+class KioskerAPI:
+    def __init__(self, host, token, port=8081, ssl=False):
+        if ssl:
+            self.conf_host = f'https://{host}:{port}'
+        else:
+            self.conf_host = f'http://{host}:{port}'
+
+        self.conf_headers = {'accept': 'application/json',
+                             'Authorization': f'Bearer {token}'}
+        
+    def _get(self, path: str):
+        r = httpx.get(f'{self.conf_host}{API_PATH}{path}', headers=self.conf_headers)
+        if r.status_code == 200:
+            return r.json()
+        elif r.status_code == 401:
+            raise RuntimeError("Unauthorized")
+        elif r.status_code == 403:
+            raise RuntimeError("IP not allowed")
+        else:
+            r.raise_for_status()
+            
+    def _post(self, path: str, json=None):
+        if json is None:
+            json = {}
+        r = httpx.post(f'{self.conf_host}{API_PATH}{path}', headers=self.conf_headers, json=json)
+        if r.status_code == 200:
+            return r.json()
+        elif r.status_code == 401:
+            raise RuntimeError("Unauthorized")
+        elif r.status_code == 403:
+            raise RuntimeError("IP not allowed")
+        elif r.status_code == 400:
+            raise RuntimeError("Bad request")
+        else:
+            r.raise_for_status()
+
+    def status(self):
+        status_data = self._get('/status').get('status')
+        return Status.from_dict(status_data)
+
+    def ping(self):
+        response_json = self._get('/ping')
+        result = Result.from_dict(response_json)
+        if result.error is False:
+            return True
+        else:
+            raise RuntimeError(f'Ping error: {result.reason}')
+    
+    # Navigation
+    def navigate_home(self):
+        return Result.from_dict(self._post('/navigate/home'))
+    
+    def navigate_refresh(self):
+        return Result.from_dict(self._post('/navigate/refresh'))
+    
+    def navigate_forward(self):
+        return Result.from_dict(self._post('/navigate/forward'))
+    
+    def navigate_backward(self):
+        return Result.from_dict(self._post('/navigate/backward'))
+    
+    def navigate_url(self, url: str):
+        return Result.from_dict(self._post('/navigate/url', json={'url': url}))
+    
+    # Print
+    def print(self):
+        return Result.from_dict(self._post('/print'))
+    
+    # Clear
+    def clear_cookies(self):
+        return Result.from_dict(self._post('/clear/cookies'))
+    
+    def clear_cache(self):
+        return Result.from_dict(self._post('/clear/cache'))
+    
+    # Screensaver
+    def screensaver_interact(self):
+        return Result.from_dict(self._post('/screensaver/interact'))
+    
+    def screensaver_set_disabled_state(self, disabled: bool):
+        return Result.from_dict(self._post('/screensaver/state', json={'disabled': disabled}))
+    
+    def screensaver_get_state(self):
+        screensaver_status_data = self._get('/screensaver/state').get('screensaver')
+        return ScreensaverState.from_dict(screensaver_status_data)
+    
+    # Blackout
+    def blackout_set(self, blackout: Blackout):
+        return Result.from_dict(self._post('/blackout', json=blackout.to_dict()))
+    
+    def blackout_get(self):
+        blackout_data = self._get('/blackout/state').get('blackout')
+        if blackout_data is None:
+            return None
+        return Blackout.from_dict(blackout_data)
+    
+    def blackout_clear(self):
+        return Result.from_dict(self._post('/blackout', json={'visible': False}))