reflex-junction 0.1.0__tar.gz

reflex_junction-0.1.0/.github/actions/basic-checks/action.yml

@@ -0,0 +1,13 @@
+name: 'Basic CI Checks'
+description: 'Runs basic CI checks (lint and typecheck) without secrets'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Run lint
+      run: task lint
+      shell: bash
+
+    - name: Run typecheck
+      run: task typecheck
+      shell: bash

reflex_junction-0.1.0/.github/actions/full-checks/action.yml

@@ -0,0 +1,47 @@
+name: 'Full CI Checks'
+description: 'Runs full CI including integration tests with secrets'
+inputs:
+  junction-api-key:
+    description: 'Junction (Vital) API key'
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Check env vars set
+      run: |
+        if [ -z "${{ inputs.junction-api-key }}" ]; then
+          echo "JUNCTION_API_KEY is not set"
+          exit 1
+        fi
+      shell: bash
+
+    - name: Create .env
+      run: |
+        echo "JUNCTION_API_KEY=${{ inputs.junction-api-key }}" >> .env
+      shell: bash
+
+    - name: DEBUG - check python version
+      run: uv sync && uv run python --version
+      shell: bash
+
+    - name: Run lint
+      run: task lint
+      shell: bash
+
+    - name: Run typecheck
+      run: task typecheck
+      shell: bash
+
+    - name: Initialize Reflex
+      run: uv run reflex init
+      working-directory: junction_demo
+      shell: bash
+
+    - name: Install playwright
+      run: uv run playwright install chromium
+      shell: bash
+
+    - name: Run tests
+      run: task test
+      shell: bash

reflex_junction-0.1.0/.github/actions/setup-python-env/action.yml

@@ -0,0 +1,28 @@
+name: 'Setup Python Environment'
+description: 'Sets up Python, uv, and Task for CI'
+inputs:
+  python-version:
+    description: 'Python version to setup'
+    required: true
+  github-token:
+    description: 'GitHub token for Task installation'
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "0.6.5"
+
+    - name: Install Task
+      uses: arduino/setup-task@v2
+      with:
+        version: 3.x
+        repo-token: ${{ inputs.github-token }}

reflex_junction-0.1.0/.github/workflows/_reusable-ci.yml

@@ -0,0 +1,54 @@
+name: Reusable CI
+
+on:
+  workflow_call:
+    inputs:
+      checkout_ref:
+        description: 'Git ref to checkout'
+        required: false
+        type: string
+        default: ''
+      checkout_repository:
+        description: 'Repository to checkout (for forks)'
+        required: false
+        type: string
+        default: ''
+      check_type:
+        description: 'Type of checks to run: basic or full'
+        required: true
+        type: string
+      environment:
+        description: 'Environment to use for secrets (only for full checks)'
+        required: false
+        type: string
+        default: ''
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-versions: ["3.11", "3.12", "3.13"]
+    environment: ${{ inputs.environment || null }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.checkout_ref || github.sha }}
+          repository: ${{ inputs.checkout_repository || github.repository }}
+
+      - name: Setup Python Environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-versions }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run Basic Checks
+        if: inputs.check_type == 'basic'
+        uses: ./.github/actions/basic-checks
+
+      - name: Run Full Checks
+        if: inputs.check_type == 'full'
+        uses: ./.github/actions/full-checks
+        with:
+          junction-api-key: ${{ secrets.JUNCTION_API_KEY }}

reflex_junction-0.1.0/.github/workflows/ci-forks.yml

@@ -0,0 +1,20 @@
+name: CI for Fork PRs
+
+on:
+  pull_request_target:
+    # Note: Repo must be set to require approval before running workflows from forks
+    # This only runs basic checks without secrets for safety
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  basic-checks:
+    uses: ./.github/workflows/_reusable-ci.yml
+    with:
+      checkout_ref: ${{ github.event.pull_request.head.sha }}
+      checkout_repository: ${{ github.event.pull_request.head.repo.full_name }}
+      check_type: 'basic'
+    secrets: inherit

reflex_junction-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+    # branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    uses: ./.github/workflows/_reusable-ci.yml
+    with:
+      check_type: 'full'
+      environment: 'demo'
+    secrets: inherit

reflex_junction-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types:
+      - completed
+    branches: [v*.*.*]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' && github.repository == 'Syntropy-Health/reflex-junction' }}
+    environment: deploy
+    permissions:
+      contents: write
+      id-token: write  # Required for PyPI trusted publishers
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.6.5"
+
+      - name: Install Task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build component
+        run: |
+          cd custom_components && uv run python -m reflex.utils.pyi_generator reflex_junction
+          cd .. && uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Uses trusted publishers (OIDC) — no token needed
+          # Falls back to PYPI_TOKEN if trusted publishers not configured
+          password: ${{ secrets.PYPI_TOKEN }}
+
+      - name: Publish docs
+        run: |
+          uv sync --dev
+          uv run mkdocs gh-deploy --force

reflex_junction-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# Reflex
+.web/
+*.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Build artifacts
+*.pyi
+
+# Node (from Reflex)
+node_modules/

reflex_junction-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.397
+    hooks:
+      - id: pyright
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    # uv version.
+    rev: 0.6.9
+    hooks:
+      - id: uv-lock

reflex_junction-0.1.0/LICENSE

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

reflex_junction-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: reflex-junction
+Version: 0.1.0
+Summary: Reflex custom component wrapping @tryvital/vital-link and integrating the Junction (Vital) health data SDK
+Project-URL: repository, https://github.com/Syntropy-Health/reflex-junction
+Author: Syntropy Health
+License-Expression: MIT
+License-File: LICENSE
+Keywords: health-data,junction,reflex,reflex-custom-components,vital
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: reflex>=0.8.0
+Requires-Dist: vital>=2.1.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![CI](https://github.com/Syntropy-Health/reflex-junction/actions/workflows/ci.yml/badge.svg)](https://github.com/Syntropy-Health/reflex-junction/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/reflex-junction.svg)](https://pypi.org/project/reflex-junction/)
+[![Python](https://img.shields.io/pypi/pyversions/reflex-junction.svg)](https://pypi.org/project/reflex-junction/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://syntropy-health.github.io/reflex-junction/)
+
+# reflex-junction
+
+A [Reflex](https://reflex.dev) custom component for integrating [Junction (Vital)](https://tryvital.io/) health data into your application. Connect wearables and health platforms (Oura, Fitbit, Apple Health, Garmin, etc.) with a few lines of Python.
+
+## Features
+
+- **JunctionState** — Reflex state management for the Vital API (user creation, provider connections, data refresh)
+- **JunctionUser** — Extended state with health data summaries (activity, sleep, body, meals, workouts)
+- **wrap_app()** — One-line integration that configures your entire Reflex app
+- **junction_provider()** — Component-level integration for wrapping specific pages
+- **Webhook support** — FastAPI router for receiving real-time health data events
+- **Link widget support** — Token generation for the Vital Link provider connection UI
+- **Multi-region** — US and EU sandbox/production environments
+
+## Installation
+
+```bash
+pip install reflex-junction
+```
+
+Or with your preferred package manager:
+
+```bash
+uv add reflex-junction
+poetry add reflex-junction
+```
+
+## Quick Start
+
+### 1. Get an API key
+
+Sign up at [tryvital.io](https://tryvital.io/) and grab your API key from the dashboard.
+
+### 2. Wrap your app
+
+```python
+import os
+import reflex as rx
+import reflex_junction as junction
+
+app = rx.App()
+
+junction.wrap_app(
+    app,
+    api_key=os.environ["JUNCTION_API_KEY"],
+    environment="sandbox",  # or "production"
+    register_user_state=True,
+)
+```
+
+### 3. Use Junction state in your pages
+
+```python
+def health_dashboard() -> rx.Component:
+    return rx.container(
+        rx.heading("Health Dashboard"),
+        rx.text(f"Connected: {junction.JunctionState.has_connections}"),
+        rx.foreach(
+            junction.JunctionState.connected_sources,
+            lambda p: rx.badge(p["name"]),
+        ),
+    )
+```
+
+## Usage
+
+### Using `junction_provider` directly
+
+For page-level integration instead of app-wide:
+
+```python
+import reflex_junction as junction
+
+def health_page() -> rx.Component:
+    return junction.junction_provider(
+        rx.container(
+            rx.text("Connected providers: "),
+            rx.text(junction.JunctionState.connected_sources.length()),
+        ),
+        api_key=os.environ["JUNCTION_API_KEY"],
+    )
+```
+
+### Webhook support
+
+Receive real-time events when health data updates:
+
+```python
+junction.wrap_app(
+    app,
+    api_key=os.environ["JUNCTION_API_KEY"],
+    register_webhooks=True,
+    webhook_secret=os.environ["JUNCTION_WEBHOOK_SECRET"],
+    webhook_prefix="/junction",  # POST /junction/webhooks
+)
+```
+
+### Environment options
+
+| Environment      | Description        |
+|------------------|--------------------|
+| `sandbox`        | US sandbox (default) |
+| `production`     | US production      |
+| `sandbox_eu`     | EU sandbox         |
+| `production_eu`  | EU production      |
+
+## API Reference
+
+### State Classes
+
+| Class | Description |
+|-------|-------------|
+| `JunctionState` | Core state — user creation, provider management, Link tokens |
+| `JunctionUser` | Extended state — health data summaries (activity, sleep, body, meals, workouts) |
+
+### Configuration Models
+
+| Class | Description |
+|-------|-------------|
+| `JunctionConfig` | Environment and region settings |
+| `LinkConfig` | Redirect URL and provider filter for the Link widget |
+| `ProviderInfo` | Provider metadata (name, slug, logo, auth_type) |
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `wrap_app(app, api_key, ...)` | One-line app integration with optional webhooks |
+| `junction_provider(*children, api_key, ...)` | Component wrapper for page-level integration |
+| `on_load(handlers)` | Wrap page on_load handlers to wait for Junction init |
+| `register_on_auth_change_handler(handler)` | Register handler to fire after Junction initializes |
+| `create_webhook_router(prefix, secret)` | Create a standalone FastAPI webhook router |
+| `register_webhook_api(app, secret, prefix)` | Register webhook endpoint on a Reflex app |
+
+### JunctionState Events
+
+| Event | Description |
+|-------|-------------|
+| `create_user(client_user_id)` | Create a Junction user mapped to your app's user |
+| `get_connected_providers()` | Fetch connected health data providers |
+| `disconnect_provider(provider)` | Disconnect a specific provider by slug |
+| `refresh_data()` | Trigger data sync from all connected providers |
+| `create_link_token(redirect_url)` | Generate a Link widget token |
+
+See the [full documentation](https://syntropy-health.github.io/reflex-junction/) for detailed guides.
+
+## Contributing
+
+Contributions welcome! We use [Taskfile](https://taskfile.dev/) for common tasks:
+
+```bash
+task install          # Install dev dependencies + pre-commit
+task test             # Run lint + typecheck + pytest
+task run              # Run the demo app
+task run-docs         # Serve docs locally at localhost:9000
+task bump-patch       # Bump patch version (bug fix)
+task bump-minor       # Bump minor version (new feature)
+```
+
+Workflow: Fork → feature branch → add tests → submit PR.
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2025 Syntropy Health

reflex_junction-0.1.0/README.md

@@ -0,0 +1,170 @@
+[![CI](https://github.com/Syntropy-Health/reflex-junction/actions/workflows/ci.yml/badge.svg)](https://github.com/Syntropy-Health/reflex-junction/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/reflex-junction.svg)](https://pypi.org/project/reflex-junction/)
+[![Python](https://img.shields.io/pypi/pyversions/reflex-junction.svg)](https://pypi.org/project/reflex-junction/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://syntropy-health.github.io/reflex-junction/)
+
+# reflex-junction
+
+A [Reflex](https://reflex.dev) custom component for integrating [Junction (Vital)](https://tryvital.io/) health data into your application. Connect wearables and health platforms (Oura, Fitbit, Apple Health, Garmin, etc.) with a few lines of Python.
+
+## Features
+
+- **JunctionState** — Reflex state management for the Vital API (user creation, provider connections, data refresh)
+- **JunctionUser** — Extended state with health data summaries (activity, sleep, body, meals, workouts)
+- **wrap_app()** — One-line integration that configures your entire Reflex app
+- **junction_provider()** — Component-level integration for wrapping specific pages
+- **Webhook support** — FastAPI router for receiving real-time health data events
+- **Link widget support** — Token generation for the Vital Link provider connection UI
+- **Multi-region** — US and EU sandbox/production environments
+
+## Installation
+
+```bash
+pip install reflex-junction
+```
+
+Or with your preferred package manager:
+
+```bash
+uv add reflex-junction
+poetry add reflex-junction
+```
+
+## Quick Start
+
+### 1. Get an API key
+
+Sign up at [tryvital.io](https://tryvital.io/) and grab your API key from the dashboard.
+
+### 2. Wrap your app
+
+```python
+import os
+import reflex as rx
+import reflex_junction as junction
+
+app = rx.App()
+
+junction.wrap_app(
+    app,
+    api_key=os.environ["JUNCTION_API_KEY"],
+    environment="sandbox",  # or "production"
+    register_user_state=True,
+)
+```
+
+### 3. Use Junction state in your pages
+
+```python
+def health_dashboard() -> rx.Component:
+    return rx.container(
+        rx.heading("Health Dashboard"),
+        rx.text(f"Connected: {junction.JunctionState.has_connections}"),
+        rx.foreach(
+            junction.JunctionState.connected_sources,
+            lambda p: rx.badge(p["name"]),
+        ),
+    )
+```
+
+## Usage
+
+### Using `junction_provider` directly
+
+For page-level integration instead of app-wide:
+
+```python
+import reflex_junction as junction
+
+def health_page() -> rx.Component:
+    return junction.junction_provider(
+        rx.container(
+            rx.text("Connected providers: "),
+            rx.text(junction.JunctionState.connected_sources.length()),
+        ),
+        api_key=os.environ["JUNCTION_API_KEY"],
+    )
+```
+
+### Webhook support
+
+Receive real-time events when health data updates:
+
+```python
+junction.wrap_app(
+    app,
+    api_key=os.environ["JUNCTION_API_KEY"],
+    register_webhooks=True,
+    webhook_secret=os.environ["JUNCTION_WEBHOOK_SECRET"],
+    webhook_prefix="/junction",  # POST /junction/webhooks
+)
+```
+
+### Environment options
+
+| Environment      | Description        |
+|------------------|--------------------|
+| `sandbox`        | US sandbox (default) |
+| `production`     | US production      |
+| `sandbox_eu`     | EU sandbox         |
+| `production_eu`  | EU production      |
+
+## API Reference
+
+### State Classes
+
+| Class | Description |
+|-------|-------------|
+| `JunctionState` | Core state — user creation, provider management, Link tokens |
+| `JunctionUser` | Extended state — health data summaries (activity, sleep, body, meals, workouts) |
+
+### Configuration Models
+
+| Class | Description |
+|-------|-------------|
+| `JunctionConfig` | Environment and region settings |
+| `LinkConfig` | Redirect URL and provider filter for the Link widget |
+| `ProviderInfo` | Provider metadata (name, slug, logo, auth_type) |
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `wrap_app(app, api_key, ...)` | One-line app integration with optional webhooks |
+| `junction_provider(*children, api_key, ...)` | Component wrapper for page-level integration |
+| `on_load(handlers)` | Wrap page on_load handlers to wait for Junction init |
+| `register_on_auth_change_handler(handler)` | Register handler to fire after Junction initializes |
+| `create_webhook_router(prefix, secret)` | Create a standalone FastAPI webhook router |
+| `register_webhook_api(app, secret, prefix)` | Register webhook endpoint on a Reflex app |
+
+### JunctionState Events
+
+| Event | Description |
+|-------|-------------|
+| `create_user(client_user_id)` | Create a Junction user mapped to your app's user |
+| `get_connected_providers()` | Fetch connected health data providers |
+| `disconnect_provider(provider)` | Disconnect a specific provider by slug |
+| `refresh_data()` | Trigger data sync from all connected providers |
+| `create_link_token(redirect_url)` | Generate a Link widget token |
+
+See the [full documentation](https://syntropy-health.github.io/reflex-junction/) for detailed guides.
+
+## Contributing
+
+Contributions welcome! We use [Taskfile](https://taskfile.dev/) for common tasks:
+
+```bash
+task install          # Install dev dependencies + pre-commit
+task test             # Run lint + typecheck + pytest
+task run              # Run the demo app
+task run-docs         # Serve docs locally at localhost:9000
+task bump-patch       # Bump patch version (bug fix)
+task bump-minor       # Bump minor version (new feature)
+```
+
+Workflow: Fork → feature branch → add tests → submit PR.
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2025 Syntropy Health