carterkit 0.1.0__py3-none-any.whl

carterkit/client.py

@@ -0,0 +1,138 @@
+"""carter_connect — minimal Connect+ hub client. Wraps MeshSocket + E2EE so a maker
+connects hardware to the Connect+ relay in a few lines. Transparent encryption when an
+e2ee_key is provided (broadcasts AND request replies); cleartext otherwise.
+
+Also exposes `notify_http(...)` and `CarterClient.notify(...)` for sending a one-shot
+push to every device on a Connect+ account (POST /alerts/notify). `notify_http` is
+stdlib-only (urllib) so a cron job can fire a notification without the MeshSocket stack."""
+import asyncio
+import base64
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+try:
+    from meshsocket import MeshSocket          # pip install meshsocket
+    from .e2ee import E2EESession
+except ImportError:  # keep notify_http importable without the MeshSocket/crypto stack
+    MeshSocket = None
+    E2EESession = None
+
+
+class CarterNotifyError(Exception):
+    """Raised when /alerts/notify rejects a send. `status` is the HTTP code (0 for a
+    client-side/config error); `detail` is the server body or a description."""
+    def __init__(self, status, detail):
+        super().__init__(f"notify failed ({status}): {detail}")
+        self.status = status
+        self.detail = detail
+
+
+def notify_http(validator_url, session_jwt, title, body, *, channel=None, category=None,
+                badge=None, sound="default", data=None, _send=None):
+    """Send a one-shot push to every device on the account (POST /alerts/notify).
+
+    Stdlib-only. `validator_url` is the Connect+ validator base URL; `session_jwt` is the
+    Connect+ account session token (NOT the MeshSocket auth token). Returns the parsed
+    `{"sent": N, "stale": M}` response. Raises CarterNotifyError on an HTTP error or
+    ValueError on invalid title/body. `_send` is a test seam: a callable
+    (url, headers, body_bytes) -> dict that bypasses the network."""
+    if not title or len(title) > 256:
+        raise ValueError("title must be non-empty and <= 256 chars")
+    if not body or len(body) > 256:
+        raise ValueError("body must be non-empty and <= 256 chars")
+
+    payload = {"title": title, "body": body, "sound": sound}
+    if channel is not None:
+        payload["channel"] = channel
+    if category is not None:
+        payload["category"] = category
+    if badge is not None:
+        payload["badge"] = badge
+    if data is not None:
+        payload["data"] = data
+
+    url = validator_url.rstrip("/") + "/alerts/notify"
+    headers = {"Authorization": session_jwt, "Content-Type": "application/json"}
+    body_bytes = json.dumps(payload).encode()
+
+    if _send is not None:
+        return _send(url, headers, body_bytes)
+
+    req = urllib.request.Request(url, data=body_bytes, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        raise CarterNotifyError(e.code, e.read().decode(errors="replace")) from None
+
+
+class CarterClient:
+    def __init__(self, gateway_url, token, channel, role="device", name="hub", e2ee_key=None,
+                 validator_url=None, session_jwt=None):
+        if MeshSocket is None:
+            raise ImportError("MeshSocket is unavailable; run `pip install meshsocket`. "
+                              "(notify_http does not need it.)")
+        self._sock = MeshSocket(url=gateway_url, name=name, auth_token=token,
+                                channel=channel, role=role, can_broadcast=True, can_route=False)
+        self._session = (E2EESession(base64.b64decode(e2ee_key), is_device_side=(role in ("device", "hub")))
+                         if e2ee_key else None)
+        # Connect+ validator credentials for notify(); distinct from the mesh auth token.
+        self._validator_url = validator_url
+        self._session_jwt = session_jwt
+
+    def _open(self, payload):
+        if self._session and isinstance(payload, dict) and E2EESession.is_envelope(payload):
+            return self._session.open(payload)
+        return payload
+
+    def _seal(self, data):
+        return self._session.seal(data) if (self._session and data is not None) else data
+
+    def on(self, msg_type, handler):
+        """Register a command handler. handler(data: dict) gets DECRYPTED data and may return a
+        dict reply (auto-encrypted). Sync or async handlers are supported."""
+        async def wrapper(payload):
+            data = self._open(payload)
+            result = handler(data)
+            if asyncio.iscoroutine(result):
+                result = await result
+            return self._seal(result) if result is not None else None
+        self._sock.on(msg_type, wrapper)
+
+    def on_broadcast(self, handler):
+        """Register a handler for relayed broadcasts. handler(data: dict) gets DECRYPTED data."""
+        async def wrapper(payload):
+            result = handler(self._open(payload))
+            if asyncio.iscoroutine(result):
+                await result
+            return None
+        self._sock.on("broadcast", wrapper)
+
+    async def broadcast(self, msg_type, data):
+        await self._sock.send("broadcast_request", self._seal({**data, "msg_type": msg_type}))
+
+    async def request(self, command, data, timeout=5.0):
+        reply = await self._sock.request(command, self._seal(data), timeout=timeout)
+        return self._open(reply) if reply is not None else None
+
+    async def notify(self, title, body, *, channel=None, category=None,
+                     badge=None, sound="default", data=None):
+        """Send a one-shot push to every device on the account. Requires `validator_url`
+        and `session_jwt` to have been passed to the constructor (the mesh auth token is
+        NOT the session JWT — distinct credentials). Returns `{"sent": N, "stale": M}`."""
+        if not self._validator_url or not self._session_jwt:
+            raise CarterNotifyError(0, "notify() requires validator_url and session_jwt "
+                                       "on the CarterClient constructor")
+        return await asyncio.to_thread(
+            notify_http, self._validator_url, self._session_jwt, title, body,
+            channel=channel, category=category, badge=badge, sound=sound, data=data)
+
+    async def connect(self):
+        await self._sock.start()
+        await self._sock.wait_until_ready()
+
+    async def close(self):
+        await self._sock.stop()

carterkit/codegen.py

@@ -0,0 +1,188 @@
+"""Backend codegen — generate a MeshSocket service that speaks to a given layout.
+
+A layout declares the events its controls fire (actions) and the events/valuePaths
+its display controls listen for (sync). From that contract we can emit a runnable
+Python service skeleton (handles the actions, emits the telemetry) and a REST-poll
+adapter template. Pure string generation.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+def _walk_controls(layout: dict) -> list[dict]:
+    out: list[dict] = []
+
+    def walk(children):
+        for ch in children or []:
+            if not isinstance(ch, dict):
+                continue
+            out.append(ch)
+            if ch.get("type") == "group":
+                walk(ch.get("children"))
+
+    for tab in layout.get("tabs", []):
+        walk(tab.get("children"))
+    return out
+
+
+def analyze_layout(layout: dict) -> dict:
+    """Extract the wire contract: {actions: {event: mode}, emits: {event: [valuePaths]}}."""
+    actions: dict[str, str] = {}
+    emits: dict[str, set] = {}
+    for ch in _walk_controls(layout):
+        a = ch.get("action")
+        if isinstance(a, dict) and a.get("event"):
+            actions.setdefault(a["event"], a.get("mode", "send"))
+        for s in ch.get("sync") or []:
+            if isinstance(s, dict) and s.get("valuePath"):
+                emits.setdefault(s.get("event") or "broadcast", set()).add(s["valuePath"])
+    return {"actions": actions, "emits": {k: sorted(v) for k, v in emits.items()}}
+
+
+def _ident(event: str) -> str:
+    s = re.sub(r"\W+", "_", event).strip("_")
+    return s or "evt"
+
+
+def _connection(layout: dict) -> tuple[str, str]:
+    c = layout.get("connection") or {}
+    return c.get("url") or "ws://localhost:8765", c.get("token") or ""
+
+
+def generate_service_stub(layout: dict) -> str:
+    """A runnable Python MeshSocket service skeleton for this layout."""
+    spec = analyze_layout(layout)
+    url, token = _connection(layout)
+    name = layout.get("name", "service")
+
+    handlers = []
+    for event, mode in sorted(spec["actions"].items()):
+        fn = f"on_{_ident(event)}"
+        reply = "    return {\"ok\": True}" if mode == "request" else "    return None"
+        handlers.append(
+            f'@socket.on("{event}")\n'
+            f'async def {fn}(payload):\n'
+            f'    # action from a control (mode={mode})\n'
+            f'    print("[action] {event}:", payload)\n'
+            f'{reply}\n')
+    handlers_block = "\n".join(handlers) if handlers else "# (layout fires no actions)\n"
+
+    emit_lines = []
+    for event, paths in sorted(spec["emits"].items()):
+        emit_lines.append(f'        frame = {{}}')
+        for p in paths:
+            emit_lines.append(f'        _set(frame, "{p}", round(random.uniform(0, 100), 2))')
+        send = ('await socket.send("broadcast_request", frame)' if event == "broadcast"
+                else f'await socket.send("{event}", frame)')
+        emit_lines.append(f'        {send}')
+    emit_block = "\n".join(emit_lines) if emit_lines else "        pass  # no sync controls"
+
+    return f'''#!/usr/bin/env python3
+"""Auto-generated MeshSocket service for layout "{name}".
+
+Handles the actions its controls fire and emits the telemetry they listen for.
+Fill in the TODOs with your real device/data logic.
+"""
+import asyncio
+import random
+
+from meshsocket import MeshSocket  # pip install meshsocket
+
+URL = "{url}"
+TOKEN = "{token}"
+
+
+def _set(d, dotted, value):
+    parts = dotted.split(".")
+    cur = d
+    for p in parts[:-1]:
+        cur = cur.setdefault(p, {{}})
+    cur[parts[-1]] = value
+
+
+socket = MeshSocket(url=URL, name="{_ident(name)}-service", auth_token=TOKEN,
+                    channel="home", role="server", can_broadcast=True)
+
+
+{handlers_block}
+
+async def telemetry_loop():
+    while True:
+        # TODO: replace random values with real readings
+{emit_block}
+        await asyncio.sleep(1.0)
+
+
+async def main():
+    asyncio.create_task(socket.start())
+    await socket.wait_until_ready()
+    await telemetry_loop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+'''
+
+
+def generate_rest_adapter(layout: dict, base_url: str = "https://api.example.com") -> str:
+    """A REST-poll → MeshSocket adapter template mapping API fields to the layout's
+    sync valuePaths."""
+    spec = analyze_layout(layout)
+    paths = sorted({p for ps in spec["emits"].values() for p in ps})
+    mapping = "\n".join(f'        _set(frame, "{p}", data.get("{p.split(".")[-1]}"))'
+                        for p in paths) or "        pass  # map API fields here"
+    url, token = _connection(layout)
+    return f'''#!/usr/bin/env python3
+"""Auto-generated REST -> MeshSocket adapter for "{layout.get('name','layout')}".
+
+Polls a REST API and pushes the fields the layout's controls listen for.
+"""
+import asyncio
+import urllib.request
+import json
+
+from meshsocket import MeshSocket  # pip install meshsocket
+
+API = "{base_url}"
+URL = "{url}"
+TOKEN = "{token}"
+
+
+def _set(d, dotted, value):
+    parts = dotted.split(".")
+    cur = d
+    for p in parts[:-1]:
+        cur = cur.setdefault(p, {{}})
+    cur[parts[-1]] = value
+
+
+socket = MeshSocket(url=URL, name="rest-adapter", auth_token=TOKEN,
+                    channel="home", role="server", can_broadcast=True)
+
+
+def fetch():
+    with urllib.request.urlopen(API, timeout=10) as r:
+        return json.loads(r.read())
+
+
+async def loop():
+    while True:
+        data = await asyncio.to_thread(fetch)
+        frame = {{}}
+{mapping}
+        await socket.send("broadcast_request", frame)
+        await asyncio.sleep(2.0)
+
+
+async def main():
+    asyncio.create_task(socket.start())
+    await socket.wait_until_ready()
+    await loop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+'''

carterkit/controldocs/accordion.md

@@ -0,0 +1,99 @@
+---
+type: accordion
+label: Accordion
+icon: list.bullet.below.rectangle
+category: controls
+defaultSpan: [3, 2]
+fields:
+  - name: accordionMode
+    type: enum
+    values: [single, multi]
+    default: single
+    description: Whether one or many sections can be open
+  - name: expandedIndex
+    type: number
+    default: 0
+    description: Section open on load (-1 = all collapsed)
+  - name: showChevron
+    type: bool
+    default: true
+    description: Show the disclosure chevron
+themeFields:
+  - name: surfacePrimary
+    type: color
+    default: "#FFFFFF0F"
+    description: Section card background
+  - name: accentColor
+    type: color
+    default: "#667eea"
+    description: Chevron color
+---
+
+# Accordion
+
+A vertical stack of collapsible **sections**. Each section is a [[group-def|group]] whose
+`label` is the header and whose grid of children is the expandable body. In `single` mode the
+open section index is the control value (so it **syncs** and fires **actions**); in `multi`
+mode sections open independently.
+
+## Type
+`"accordion"`
+
+## Relevant Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `panels` | [[group-def]][] | — | The sections, each a group definition |
+| `accordionMode` | string | `"single"` | `"single"` (one open) or `"multi"` (many) |
+| `expandedIndex` | number | `0` | Section open on load; `-1` = all collapsed |
+| `showChevron` | bool | `true` | Show the disclosure chevron |
+| `defaultValue` | number | — | Initial open index (overrides `expandedIndex` if set) |
+| `containerAnimation` | object | — | Motion customization (see below) |
+
+In `single` mode, an incoming [[sync]] opens a section (cascading through intermediate
+sections on a multi-step jump); toggling fires the [[actions|action]] with the index (`-1`
+when collapsing). In `multi` mode the open set is local UI state and the value reflects only
+the last-toggled index.
+
+## Animation Customization
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `profile` | string | `bouncy` | Base spring profile |
+| `duration` | number | — | Override expand/collapse seconds |
+| `bounce` | number | — | Spring bounce 0–1 |
+| `multiStep` | bool | `true` | Cascade through sections on a multi-step jump (single mode) |
+| `stepInterval` | number | `0.12` | Seconds per intermediate step |
+| `chevronRotation` | number | `90` | Chevron rotation° when expanded |
+
+## Examples
+
+### Single-open settings, synced
+```json
+{
+  "type": "accordion",
+  "id": "settings",
+  "position": [0, 0],
+  "span": [4, 2],
+  "accordionMode": "single",
+  "expandedIndex": 0,
+  "containerAnimation": { "profile": "smooth", "chevronRotation": 90 },
+  "panels": [
+    { "type": "group", "id": "display", "label": "Display", "position": [0,0], "grid": { "columns": 1, "rows": 1 },
+      "children": [ { "type": "slider", "id": "bright", "position": [0,0], "label": "Brightness", "min": 0, "max": 100 } ] },
+    { "type": "group", "id": "network", "label": "Network", "position": [0,0], "grid": { "columns": 1, "rows": 1 },
+      "children": [ { "type": "toggle", "id": "wifi", "position": [0,0], "label": "Wi-Fi" } ] }
+  ]
+}
+```
+
+## Theming
+Sections are glass cards from the active [[theming|theme]]; the chevron uses `accentColor`.
+
+## Related
+- [[group-def]] — each section is a group
+- [[carousel]] — horizontal paging
+- [[flip-card]] — flip between faces
+- [[actions]] — `{{value}}` section index
+- [[sync]] — drive the open section from the server
+- [[animations]] — base animation profiles

carterkit/controldocs/actions.md

@@ -0,0 +1,51 @@
+---
+type: actions
+label: Actions
+icon: bolt.fill
+category: system
+fields:
+  - name: method
+    type: string
+    description: Transport method (meshsocket)
+  - name: mode
+    type: string
+    description: Send mode (request, broadcast)
+  - name: event
+    type: string
+    description: Event name to fire
+  - name: payload
+    type: object
+    description: Data to send (supports {{value}} substitution)
+---
+
+How controls send commands to the server.
+
+## Definition
+
+```json
+"action": {
+  "method": "meshsocket",
+  "mode": "request",
+  "event": "set_power",
+  "payload": { "state": "{{value}}" }
+}
+```
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| `request` | Send + await response |
+| `broadcast` | Fire and forget |
+
+## Substitution
+
+`{{value}}` in any string becomes the current control value:
+- [[toggle]]: `"true"` / `"false"`
+- [[slider]]: `"75.0"`
+- [[picker]]: `"Ocean"`
+
+## Related
+
+- [[control-def]] — every control can have an action
+- [[long-press]] — alternate action on long press

carterkit/controldocs/animations.md

@@ -0,0 +1,41 @@
+---
+type: animations
+label: Animations
+icon: sparkles
+category: system
+fields:
+  - name: profile
+    type: string
+    description: Named animation preset
+  - name: duration
+    type: number
+    description: Custom duration override
+---
+
+Transition and interaction animations.
+
+## Profiles
+
+| Name | SwiftUI |
+|------|---------|
+| `snappy` | `.snappy` |
+| `smooth` | `.smooth(duration: 0.35)` |
+| `bouncy` | `.bouncy(duration: 0.5)` |
+| `gentle` | `.easeInOut(duration: 0.25)` |
+| `instant` | `.linear(duration: 0)` |
+
+## Usage
+
+```json
+"animation": "bouncy"
+```
+
+Or custom:
+```json
+"animation": { "profile": "smooth", "duration": 0.5 }
+```
+
+## Related
+
+- [[visibility]] — uses `gentle` for show/hide
+- [[control-def]] — any control can override its animation

carterkit/controldocs/appearance.md

@@ -0,0 +1,67 @@
+---
+type: appearance
+label: Appearance
+icon: macwindow
+category: models
+---
+
+The `appearance` block on a [[layout-config|layout]] controls the app shell — color scheme, header bar, status bar, and background image. Colors and control styling live in [[theming|theme]]; appearance is about the chrome around your grid.
+
+```json
+"appearance": {
+  "colorScheme": "system",
+  "showHeader": true,
+  "statusBarStyle": "auto",
+  "header": { "style": "transparent" },
+  "backgroundImage": { "asset": "bg", "blur": 20, "opacity": 0.5 }
+}
+```
+
+## Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `colorScheme` | `dark` / `light` / `system` | `system` | `system` follows the device and adapts the palette live. `dark`/`light` pin the whole app. |
+| `showHeader` | bool | `true` | Show or hide the header bar |
+| `statusBarStyle` | `auto` / `light` / `dark` | `auto` | Status bar content color |
+| `header` | object | transparent | Header bar style (see below) |
+| `backgroundImage` | object | — | Page background image (see below) |
+
+## Header
+
+Omit `header` for a **transparent** bar — the page background shows through the bar and the status bar. Provide a color/gradient for a filled bar that **extends up into the status bar**.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `style` | `transparent` / `material` / `color` | Inferred as `color` when `light`/`dark` are set; otherwise `transparent` |
+| `light` | color or color[] | Fill for light mode — a hex string or a 2+ color gradient |
+| `dark` | color or color[] | Fill for dark mode |
+
+```json
+"header": {
+  "style": "color",
+  "dark":  ["#0A0F1E", "#0E1A33"],
+  "light": "#EAF0FBF2"
+}
+```
+
+- **transparent** — no fill; seamless with the page. No divider.
+- **material** — frosted glass bar (stays within the safe area).
+- **color** — solid or gradient fill that bleeds into the status bar. If the active mode's fill is missing, it falls back to transparent.
+
+## Background Image
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `url` | string | — | Remote image URL (loaded async) |
+| `asset` | string | — | Bundled image asset name |
+| `contentMode` | `fill` / `fit` | `fill` | Scaling mode |
+| `blur` | number | — | Gaussian blur radius |
+| `opacity` | number | `1.0` | Image opacity (0–1) |
+| `overlay` | color | — | Hex overlay for readability (e.g. `"#00000080"`) |
+
+The image sits above the page background/gradient and below all controls, on every tab.
+
+## Related
+- [[theming]] — Colors, fonts, per-control styling, light/dark variants
+- [[layout-config]] — Where `appearance` lives