feedback-hub 1.0.0__py3-none-any.whl

feedback_hub/__init__.py

@@ -0,0 +1,117 @@
+"""feedback-hub - Multi-framework GitHub issue submission library.
+
+Each app uses its native UI; all submit directly to GitHub Issues.
+
+Quick start (wxPython)::
+
+    from feedback_hub import load_schema
+    from feedback_hub.wx_dialog import FeedbackDialog
+
+    schema = load_schema({"app": "MyApp", "github_repo": "org/repo", "fields": [...]})
+    dlg = FeedbackDialog(parent, schema=schema, github_token=TOKEN)
+    dlg.ShowModal()
+    dlg.Destroy()
+
+Quick start (Flask)::
+
+    from feedback_hub.flask_blueprint import make_blueprint
+
+    feedback_bp = make_blueprint(app_name="MyApp", github_repo="org/repo")
+    app.register_blueprint(feedback_bp, url_prefix="/feedback")
+
+Quick start (headless / CLI)::
+
+    from feedback_hub import submit
+
+    issue_url, error = submit(
+        app="MyApp",
+        github_repo="org/repo",
+        github_token=TOKEN,
+        summary="Something is broken",
+        message="Details here",
+        category="Bug Report",
+    )
+"""
+from feedback_hub._github import GitHubConfig, resolve_token
+from feedback_hub._schema import AppSchema, FieldSchema, build_entry, load_schema
+from feedback_hub._storage import list_all, save
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AppSchema",
+    "FieldSchema",
+    "GitHubConfig",
+    "build_entry",
+    "list_all",
+    "load_schema",
+    "resolve_token",
+    "save",
+    "submit",
+]
+
+
+def submit(
+    *,
+    app: str,
+    github_repo: str,
+    github_token: str = "",
+    summary: str = "",
+    message: str,
+    category: str = "feedback",
+    name: str = "",
+    email: str = "",
+    app_version: str = "",
+    github_labels: list[str] | None = None,
+    github_assignee: str = "",
+    metadata: dict | None = None,
+    db_path=None,
+) -> tuple:
+    """Headless submission -- no UI required.
+
+    Returns ``(issue_url, error_message)``.
+    """
+    from datetime import UTC, datetime
+    from pathlib import Path
+
+    from feedback_hub._github import create_issue
+    from feedback_hub._storage import save as _save, update_github_sync
+
+    token = resolve_token(github_token)
+    entry = {
+        "app": app,
+        "version": app_version,
+        "platform": "",
+        "category": category,
+        "name": name,
+        "email": email,
+        "summary": summary,
+        "message": message,
+        "metadata": metadata,
+        "timestamp": datetime.now(UTC).isoformat(),
+    }
+
+    _db = db_path or Path.home() / ".local" / "share" / "feedback-hub" / "feedback.db"
+    try:
+        row_id = _save(entry, Path(_db))
+    except Exception:
+        row_id = None
+
+    if not token:
+        return None, "GitHub token not configured"
+
+    cfg = GitHubConfig(
+        token=token,
+        repo=github_repo,
+        assignee=github_assignee,
+        labels=github_labels or ["needs-triage"],
+    )
+    number, url, error = create_issue(entry, cfg)
+
+    if row_id is not None:
+        try:
+            update_github_sync(row_id, issue_number=number, issue_url=url, error=error, db_path=Path(_db))
+        except Exception:
+            pass
+
+    return url, error

feedback_hub/_github.py

@@ -0,0 +1,148 @@
+"""GitHub Issues API client.
+
+Framework-agnostic. Accepts a config and a prepared entry dict,
+posts it as a GitHub issue, returns (issue_number, issue_url, error).
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+from urllib import error as urlerror
+from urllib import request as urlrequest
+
+
+@dataclass(frozen=True, slots=True)
+class GitHubConfig:
+    token: str
+    repo: str
+    assignee: str = ""
+    labels: list[str] = field(default_factory=lambda: ["needs-triage"])
+
+
+def resolve_token(*candidates: str) -> str:
+    """Resolve GitHub token from candidates in priority order.
+
+    Candidates are tried first. Then standard env vars are checked.
+    This lets each app pass its own bundled fine-grained PAT as the
+    last candidate while still allowing env var overrides.
+
+    Safe to bundle issues-only fine-grained PATs in desktop apps:
+    worst case misuse is filing extra issues, not code/repo access.
+    """
+    for candidate in candidates:
+        if candidate and candidate.strip():
+            return candidate.strip()
+    for env_var in (
+        "FEEDBACK_HUB_GITHUB_TOKEN",
+        "SUPPORT_HUB_GITHUB_TOKEN",
+        "FEEDBACK_GITHUB_TOKEN",
+    ):
+        value = os.environ.get(env_var, "").strip()
+        if value:
+            return value
+    return ""
+
+
+def create_issue(
+    entry: dict[str, object],
+    config: GitHubConfig,
+) -> tuple[Optional[int], Optional[str], Optional[str]]:
+    """Post entry as a GitHub issue.
+
+    Returns (issue_number, issue_url, error_message).
+    On success error_message is None; on failure number and url are None.
+    """
+    if not config.token:
+        return None, None, "GitHub token not configured"
+
+    payload = _build_payload(entry, config)
+    req = urlrequest.Request(
+        f"https://api.github.com/repos/{config.repo}/issues",
+        data=json.dumps(payload).encode("utf-8"),
+        method="POST",
+        headers={
+            "Accept": "application/vnd.github+json",
+            "Authorization": f"Bearer {config.token}",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "Content-Type": "application/json",
+            "User-Agent": "feedback-hub/1.0",
+        },
+    )
+    try:
+        with urlrequest.urlopen(req, timeout=20) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+            return data.get("number"), data.get("html_url"), None
+    except urlerror.HTTPError as exc:
+        try:
+            details = exc.read().decode("utf-8")
+        except Exception:
+            details = str(exc)
+        return None, None, f"GitHub API error {exc.code}: {details}"
+    except Exception as exc:  # noqa: BLE001
+        return None, None, f"GitHub request failed: {exc}"
+
+
+def _build_payload(entry: dict[str, object], cfg: GitHubConfig) -> dict[str, object]:
+    app = str(entry.get("app", "Unknown")).strip()
+    category = str(entry.get("category", "feedback")).strip().lower()
+    summary = str(entry.get("summary") or entry.get("message", ""))[:120].strip()
+    title = f"[{app}] {category}: {summary}"
+
+    lines = [
+        "## Feedback Report",
+        "",
+        f"- **App**: `{app}`",
+        f"- **Version**: `{entry.get('version', 'unknown')}`",
+        f"- **Platform**: `{entry.get('platform', 'unknown')}`",
+        f"- **Category**: `{category}`",
+        f"- **Submitted**: `{entry.get('timestamp', 'unknown')}`",
+    ]
+
+    submitter_name = str(entry.get("name", "")).strip()
+    submitter_email = str(entry.get("email", "")).strip()
+    if submitter_name or submitter_email:
+        lines.append("")
+        lines.append("### Submitter")
+        if submitter_name:
+            lines.append(f"- **Name**: {submitter_name}")
+        if submitter_email:
+            lines.append(f"- **Email**: {submitter_email}")
+
+    lines += ["", "### Details", "", str(entry.get("message", "")).strip()]
+
+    extra_fields = entry.get("extra_fields")
+    if isinstance(extra_fields, dict):
+        rendered = []
+        for label, value in extra_fields.items():
+            if value and str(value).strip():
+                rendered.append(f"**{label}**: {value}")
+        if rendered:
+            lines += ["", "### Additional Information", ""]
+            lines += rendered
+
+    metadata = entry.get("metadata")
+    if isinstance(metadata, dict) and metadata:
+        lines += [
+            "",
+            "### Environment",
+            "```",
+            json.dumps(metadata, indent=2, sort_keys=True),
+            "```",
+        ]
+
+    lines += [
+        "",
+        "---",
+        "_Submitted via feedback-hub_",
+    ]
+
+    payload: dict[str, object] = {
+        "title": title,
+        "body": "\n".join(lines),
+        "labels": cfg.labels,
+    }
+    if cfg.assignee:
+        payload["assignees"] = [cfg.assignee]
+    return payload

feedback_hub/_schema.py

@@ -0,0 +1,160 @@
+"""Dynamic form schema system.
+
+Each app defines a schema (dict or JSON file) describing which fields
+to show and how to validate them.  The schema drives:
+  - wxPython dialog field generation
+  - Flask form rendering
+  - Validation rules
+  - GitHub issue formatting
+
+Minimal schema example::
+
+    {
+        "app": "ChapterForge",
+        "version": "2.0.0",
+        "github_repo": "BITS-ACB/chapterforge",
+        "github_labels": ["bug", "needs-triage"],
+        "categories": ["Bug Report", "Feature Request", "Accessibility Issue", "Other"],
+        "fields": [
+            {"name": "summary",  "label": "Summary",          "type": "text",     "required": true,  "max_length": 120},
+            {"name": "message",  "label": "What happened",    "type": "textarea", "required": true,  "max_length": 5000},
+            {"name": "expected", "label": "What you expected","type": "textarea", "required": false},
+            {"name": "steps",    "label": "Steps to reproduce","type": "textarea","required": false},
+            {"name": "version",  "label": "App version",      "type": "text",     "required": false, "default": "__app_version__"},
+            {"name": "platform", "label": "Operating system", "type": "text",     "required": false, "default": "__platform__"}
+        ]
+    }
+"""
+from __future__ import annotations
+
+import json
+import platform
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+
+@dataclass
+class FieldSchema:
+    name: str
+    label: str
+    type: str = "text"          # text | textarea | select | checkbox
+    required: bool = False
+    max_length: int = 0         # 0 = no limit
+    options: list[str] = field(default_factory=list)  # for select
+    default: str = ""
+    placeholder: str = ""
+
+
+@dataclass
+class AppSchema:
+    app: str
+    github_repo: str
+    github_labels: list[str] = field(default_factory=lambda: ["needs-triage"])
+    github_assignee: str = ""
+    version: str = ""
+    categories: list[str] = field(default_factory=lambda: [
+        "Bug Report", "Feature Request", "Accessibility Issue", "Other"
+    ])
+    fields: list[FieldSchema] = field(default_factory=list)
+
+    def resolve_defaults(self, app_version: str = "") -> dict[str, str]:
+        """Return a dict of field name -> resolved default value."""
+        os_str = f"{platform.system()} {platform.release()}"
+        py_str = sys.version.splitlines()[0]
+        magic = {
+            "__app_version__": app_version or self.version,
+            "__platform__": os_str,
+            "__python__": py_str,
+        }
+        return {
+            f.name: magic.get(f.default, f.default)
+            for f in self.fields
+        }
+
+    def validate(self, values: dict[str, str]) -> list[str]:
+        errors = []
+        for f in self.fields:
+            val = values.get(f.name, "").strip()
+            if f.required and not val:
+                errors.append(f"{f.label} is required.")
+            if f.max_length and len(val) > f.max_length:
+                errors.append(f"{f.label} must be {f.max_length} characters or fewer.")
+            if f.type == "select" and f.options and val and val not in f.options:
+                errors.append(f"{f.label} has an invalid value.")
+        return errors
+
+
+def load_schema(source: str | dict | Path) -> AppSchema:
+    """Load a schema from a dict, JSON string, or Path to a JSON file."""
+    if isinstance(source, Path):
+        raw = json.loads(source.read_text(encoding="utf-8"))
+    elif isinstance(source, str):
+        raw = json.loads(source)
+    else:
+        raw = source
+
+    fields = [
+        FieldSchema(
+            name=f["name"],
+            label=f.get("label", f["name"].title()),
+            type=f.get("type", "text"),
+            required=f.get("required", False),
+            max_length=f.get("max_length", 0),
+            options=f.get("options", []),
+            default=f.get("default", ""),
+            placeholder=f.get("placeholder", ""),
+        )
+        for f in raw.get("fields", [])
+    ]
+
+    return AppSchema(
+        app=raw["app"],
+        github_repo=raw["github_repo"],
+        github_labels=raw.get("github_labels", ["needs-triage"]),
+        github_assignee=raw.get("github_assignee", ""),
+        version=raw.get("version", ""),
+        categories=raw.get("categories", [
+            "Bug Report", "Feature Request", "Accessibility Issue", "Other"
+        ]),
+        fields=fields,
+    )
+
+
+def build_entry(
+    schema: AppSchema,
+    values: dict[str, str],
+    *,
+    name: str = "",
+    email: str = "",
+    category: str = "",
+    app_version: str = "",
+    metadata: Optional[dict[str, Any]] = None,
+    timestamp: str = "",
+) -> dict[str, object]:
+    """Build a normalized entry dict from submitted form values."""
+    from datetime import UTC, datetime
+
+    # The fields listed in the schema go into extra_fields so the
+    # GitHub formatter can render them with their human labels.
+    extra_fields = {
+        schema_field.label: values.get(schema_field.name, "")
+        for schema_field in schema.fields
+        if schema_field.name not in ("summary", "message", "version", "platform")
+        and values.get(schema_field.name, "").strip()
+    }
+
+    return {
+        "app": schema.app,
+        "version": values.get("version", app_version or schema.version),
+        "platform": values.get("platform", ""),
+        "category": category or "feedback",
+        "name": name,
+        "email": email,
+        "summary": values.get("summary", ""),
+        "message": values.get("message", ""),
+        "extra_fields": extra_fields or None,
+        "metadata": metadata,
+        "timestamp": timestamp or datetime.now(UTC).isoformat(),
+    }

feedback_hub/_storage.py

@@ -0,0 +1,137 @@
+"""SQLite-backed local storage for feedback entries.
+
+Stores every submission locally before attempting GitHub sync,
+so nothing is lost if the network call fails.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Optional
+
+log = logging.getLogger(__name__)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS feedback (
+    id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp           TEXT    NOT NULL,
+    app                 TEXT,
+    version             TEXT,
+    platform            TEXT,
+    category            TEXT,
+    name                TEXT,
+    email               TEXT,
+    summary             TEXT,
+    message             TEXT    NOT NULL,
+    extra_fields_json   TEXT,
+    metadata_json       TEXT,
+    github_issue_number INTEGER,
+    github_issue_url    TEXT,
+    github_sync_status  TEXT,
+    github_sync_error   TEXT,
+    github_synced_at    TEXT
+)
+"""
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    conn.execute(_SCHEMA)
+    existing = {row[1] for row in conn.execute("PRAGMA table_info(feedback)").fetchall()}
+    additions = {
+        "app": "TEXT",
+        "version": "TEXT",
+        "platform": "TEXT",
+        "summary": "TEXT",
+        "extra_fields_json": "TEXT",
+        "metadata_json": "TEXT",
+        "github_issue_number": "INTEGER",
+        "github_issue_url": "TEXT",
+        "github_sync_status": "TEXT",
+        "github_sync_error": "TEXT",
+        "github_synced_at": "TEXT",
+    }
+    for col, col_type in additions.items():
+        if col not in existing:
+            conn.execute(f"ALTER TABLE feedback ADD COLUMN {col} {col_type}")
+    conn.commit()
+
+
+def open_db(path: Path) -> sqlite3.Connection:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path))
+    conn.execute("PRAGMA journal_mode=WAL")
+    _ensure_schema(conn)
+    return conn
+
+
+def save(entry: dict[str, object], db_path: Path) -> int:
+    """Persist entry and return its row id."""
+    extra = entry.get("extra_fields")
+    metadata = entry.get("metadata")
+    conn = open_db(db_path)
+    cur = conn.execute(
+        """INSERT INTO feedback
+           (timestamp, app, version, platform, category, name, email,
+            summary, message, extra_fields_json, metadata_json)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+        (
+            str(entry.get("timestamp", datetime.now(UTC).isoformat())),
+            str(entry.get("app", "")),
+            str(entry.get("version", "")),
+            str(entry.get("platform", "")),
+            str(entry.get("category", "feedback")),
+            str(entry.get("name", "")),
+            str(entry.get("email", "")),
+            str(entry.get("summary", "")),
+            str(entry.get("message", "")),
+            json.dumps(extra, sort_keys=True) if isinstance(extra, dict) else "",
+            json.dumps(metadata, sort_keys=True) if isinstance(metadata, dict) else "",
+        ),
+    )
+    row_id = int(cur.lastrowid)
+    conn.commit()
+    conn.close()
+    return row_id
+
+
+def update_github_sync(
+    row_id: int,
+    *,
+    issue_number: Optional[int],
+    issue_url: Optional[str],
+    error: Optional[str],
+    db_path: Path,
+) -> None:
+    status = "synced" if issue_url else "failed"
+    conn = open_db(db_path)
+    conn.execute(
+        """UPDATE feedback
+           SET github_issue_number=?, github_issue_url=?,
+               github_sync_status=?, github_sync_error=?,
+               github_synced_at=?
+           WHERE id=?""",
+        (
+            issue_number,
+            issue_url,
+            status,
+            error,
+            datetime.now(UTC).isoformat(),
+            row_id,
+        ),
+    )
+    conn.commit()
+    conn.close()
+
+
+def list_all(db_path: Path) -> list[dict]:
+    if not db_path.exists():
+        return []
+    conn = open_db(db_path)
+    cur = conn.execute("SELECT * FROM feedback ORDER BY id DESC")
+    cols = [d[0] for d in cur.description]
+    rows = [dict(zip(cols, row)) for row in cur.fetchall()]
+    conn.close()
+    return rows

feedback_hub/compat_glow.py

@@ -0,0 +1,91 @@
+"""GLOW backward-compatibility shim.
+
+Replace the entire content of
+``web/src/acb_large_print_web/routes/feedback.py`` with::
+
+    from feedback_hub.compat_glow import feedback_bp
+
+That is the only change needed. All route names are preserved:
+    feedback.feedback_form
+    feedback.feedback_submit
+    feedback.feedback_submit_api
+    feedback.feedback_review
+
+The GLOW app also imports support_hub.create_support_issue and
+support_hub.load_support_hub_config in a few places. Those still work via::
+
+    from feedback_hub.compat_glow import create_support_issue, load_support_hub_config
+"""
+from __future__ import annotations
+
+import os
+
+from feedback_hub._github import GitHubConfig, create_issue, resolve_token
+from feedback_hub.flask_blueprint import make_blueprint
+
+
+def _glow_version() -> str:
+    try:
+        from acb_large_print_web.version import get_version
+        return get_version()
+    except Exception:
+        return ""
+
+
+feedback_bp = make_blueprint(
+    app_name="GLOW",
+    github_repo=os.environ.get("FEEDBACK_GITHUB_REPO", "Community-Access/support"),
+    github_labels=[
+        l.strip()
+        for l in os.environ.get("FEEDBACK_GITHUB_LABELS", "needs-triage").split(",")
+        if l.strip()
+    ],
+    github_assignee=os.environ.get("FEEDBACK_GITHUB_ASSIGNEE", ""),
+    app_version_fn=_glow_version,
+    blueprint_name="feedback",
+    extra_fields=[
+        {"name": "task", "label": "What were you trying to do", "type": "text", "max_length": 240},
+    ],
+)
+
+
+# Legacy API preserved for any GLOW code that imports from support_hub directly
+def load_support_hub_config():
+    """Backward-compatible stub returning a simple namespace."""
+    class _Cfg:
+        token = resolve_token()
+        repo = os.environ.get("FEEDBACK_GITHUB_REPO", "Community-Access/support")
+        assignee = os.environ.get("FEEDBACK_GITHUB_ASSIGNEE", "")
+        labels = [
+            l.strip()
+            for l in os.environ.get("FEEDBACK_GITHUB_LABELS", "needs-triage").split(",")
+            if l.strip()
+        ]
+        api_token = os.environ.get("FEEDBACK_API_TOKEN", "").strip()
+    return _Cfg()
+
+
+def create_support_issue(entry: dict) -> tuple:
+    """Backward-compatible wrapper over the new create_issue."""
+    cfg_raw = load_support_hub_config()
+    cfg = GitHubConfig(
+        token=cfg_raw.token,
+        repo=cfg_raw.repo,
+        assignee=cfg_raw.assignee,
+        labels=cfg_raw.labels,
+    )
+    # Map old GLOW entry keys to new format
+    mapped = {
+        "app": entry.get("source_app", "GLOW"),
+        "version": entry.get("source_version", ""),
+        "platform": entry.get("platform", ""),
+        "category": entry.get("category", "feedback"),
+        "name": entry.get("name", ""),
+        "email": entry.get("email", ""),
+        "summary": entry.get("summary", ""),
+        "message": entry.get("message", ""),
+        "timestamp": entry.get("timestamp", ""),
+        "extra_fields": {"Task": entry.get("task", "")} if entry.get("task") else None,
+    }
+    number, url, error = create_issue(mapped, cfg)
+    return number, url, error

feedback_hub/flask_blueprint.py

@@ -0,0 +1,267 @@
+"""Flask Blueprint adapter.
+
+Drop-in replacement for GLOW's feedback.py routes.  Registers a blueprint
+that serves:
+  GET  /          -- feedback form (HTML)
+  POST /          -- form submission
+  POST /api       -- JSON submission (Bearer token auth)
+  GET  /review    -- protected review dashboard
+
+GLOW migration (non-breaking)::
+
+    # web/src/acb_large_print_web/routes/feedback.py
+    # Replace the entire file with:
+    from feedback_hub.flask_blueprint import make_blueprint
+    feedback_bp = make_blueprint(
+        app_name="GLOW",
+        github_repo="Community-Access/support",
+        app_version_fn=lambda: get_version(),
+    )
+
+All existing route names (feedback.feedback_form, feedback.feedback_submit,
+feedback.feedback_submit_api, feedback.feedback_review) are preserved.
+"""
+from __future__ import annotations
+
+import hmac
+import json
+import logging
+import os
+import platform
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Callable, Optional
+
+log = logging.getLogger(__name__)
+
+
+def make_blueprint(
+    *,
+    app_name: str,
+    github_repo: str,
+    github_labels: Optional[list[str]] = None,
+    github_assignee: str = "",
+    github_token: str = "",
+    app_version_fn: Optional[Callable[[], str]] = None,
+    db_path: Optional[Path] = None,
+    url_prefix: str = "/feedback",
+    blueprint_name: str = "feedback",
+    categories: Optional[list[str]] = None,
+    extra_fields: Optional[list[dict]] = None,
+):
+    """Create and return a configured Flask Blueprint.
+
+    Parameters
+    ----------
+    app_name:
+        Human name shown on the form and in GitHub issue titles.
+    github_repo:
+        ``owner/repo`` slug (e.g. ``BITS-ACB/chapterforge``).
+    github_token:
+        Optional token override. Falls back to env vars automatically.
+    app_version_fn:
+        Callable returning the current app version string.
+    db_path:
+        SQLite database path. Defaults to Flask's ``instance/feedback.db``.
+    categories:
+        Issue category choices shown in the form drop-down.
+    extra_fields:
+        List of ``{"name": ..., "label": ..., "type": ..., "required": ...}``
+        dicts for app-specific fields beyond the defaults.
+    """
+    from flask import (
+        Blueprint,
+        abort,
+        current_app,
+        jsonify,
+        render_template,
+        request,
+    )
+
+    from feedback_hub._github import GitHubConfig, create_issue, resolve_token
+    from feedback_hub._schema import AppSchema, FieldSchema, build_entry, load_schema
+    from feedback_hub._storage import (
+        save as _save,
+        update_github_sync as _update_sync,
+    )
+
+    bp = Blueprint(blueprint_name, __name__, template_folder="templates")
+
+    _categories = categories or [
+        "Bug Report",
+        "Feature Request",
+        "Accessibility Issue",
+        "Documentation",
+        "Other",
+    ]
+    _schema = AppSchema(
+        app=app_name,
+        github_repo=github_repo,
+        github_labels=github_labels or ["needs-triage"],
+        github_assignee=github_assignee,
+        categories=_categories,
+        fields=[
+            FieldSchema("summary", "Summary", "text", required=True, max_length=120),
+            FieldSchema("message", "Details", "textarea", required=True, max_length=5000),
+            *(
+                FieldSchema(
+                    f["name"],
+                    f.get("label", f["name"].title()),
+                    f.get("type", "text"),
+                    required=f.get("required", False),
+                    max_length=f.get("max_length", 0),
+                    options=f.get("options", []),
+                    default=f.get("default", ""),
+                )
+                for f in (extra_fields or [])
+            ),
+        ],
+    )
+
+    def _resolved_token() -> str:
+        return resolve_token(
+            github_token,
+            os.environ.get("SUPPORT_HUB_GITHUB_TOKEN", ""),
+            os.environ.get("FEEDBACK_GITHUB_TOKEN", ""),
+        )
+
+    def _get_db() -> Path:
+        if db_path:
+            return db_path
+        try:
+            return Path(current_app.instance_path) / "feedback.db"
+        except RuntimeError:
+            return Path("instance") / "feedback.db"
+
+    def _get_version() -> str:
+        if app_version_fn:
+            try:
+                return app_version_fn()
+            except Exception:
+                pass
+        return ""
+
+    def _submit(entry: dict) -> tuple[Optional[str], Optional[str]]:
+        """Store locally then sync to GitHub. Returns (issue_url, error)."""
+        try:
+            row_id = _save(entry, _get_db())
+        except Exception as exc:
+            log.exception("Failed to save feedback to SQLite")
+            return None, str(exc)
+
+        token = _resolved_token()
+        if not token:
+            return None, "GitHub token not configured"
+
+        cfg = GitHubConfig(
+            token=token,
+            repo=_schema.github_repo,
+            assignee=_schema.github_assignee,
+            labels=_schema.github_labels,
+        )
+        number, url, error = create_issue(entry, cfg)
+        try:
+            _update_sync(row_id, issue_number=number, issue_url=url, error=error, db_path=_get_db())
+        except Exception:
+            pass
+        return url, error
+
+    # ------------------------------------------------------------------
+    # Routes
+    # ------------------------------------------------------------------
+
+    @bp.route("/", methods=["GET"])
+    def feedback_form():
+        return render_template(
+            "feedback_hub/form.html",
+            schema=_schema,
+            error="",
+            values={},
+        )
+
+    @bp.route("/", methods=["POST"])
+    def feedback_submit():
+        values = {
+            f.name: request.form.get(f.name, "").strip()
+            for f in _schema.fields
+        }
+        errors = _schema.validate(values)
+        if errors:
+            return render_template(
+                "feedback_hub/form.html",
+                schema=_schema,
+                error=" ".join(errors),
+                values=values,
+            ), 400
+
+        entry = build_entry(
+            _schema,
+            values,
+            name=request.form.get("name", "").strip(),
+            email=request.form.get("email", "").strip(),
+            category=request.form.get("category", _categories[0]),
+            app_version=_get_version(),
+            metadata={
+                "source_channel": "web",
+                "user_agent": request.headers.get("User-Agent", ""),
+            },
+        )
+        issue_url, _error = _submit(entry)
+        return render_template(
+            "feedback_hub/thanks.html",
+            schema=_schema,
+            issue_url=issue_url,
+        )
+
+    @bp.route("/api", methods=["POST"])
+    def feedback_submit_api():
+        api_token = os.environ.get("FEEDBACK_HUB_API_TOKEN", "").strip() or \
+                    os.environ.get("FEEDBACK_API_TOKEN", "").strip()
+        if not api_token:
+            abort(404)
+        auth = request.headers.get("Authorization", "")
+        if not auth or not hmac.compare_digest(auth, f"Bearer {api_token}"):
+            return jsonify({"error": "Unauthorized"}), 403
+
+        payload = request.get_json(silent=True)
+        if not isinstance(payload, dict):
+            return jsonify({"error": "JSON object required"}), 400
+
+        values = {f.name: str(payload.get(f.name, "")).strip() for f in _schema.fields}
+        errors = _schema.validate(values)
+        if errors:
+            return jsonify({"error": " ".join(errors)}), 400
+
+        entry = build_entry(
+            _schema,
+            values,
+            name=str(payload.get("name", "")),
+            email=str(payload.get("email", "")),
+            category=str(payload.get("category", _categories[0])),
+            app_version=str(payload.get("version", _get_version())),
+            metadata=payload.get("metadata") if isinstance(payload.get("metadata"), dict) else None,
+        )
+        issue_url, sync_error = _submit(entry)
+        return jsonify({
+            "status": "accepted",
+            "issue_url": issue_url,
+            "github_sync_status": "synced" if issue_url else "failed",
+            "github_sync_error": sync_error,
+        }), 202
+
+    @bp.route("/review")
+    def feedback_review():
+        from feedback_hub._storage import list_all
+
+        password = os.environ.get("FEEDBACK_PASSWORD", "").strip()
+        if not password:
+            abort(404)
+        provided = request.args.get("key", "")
+        if not provided or not hmac.compare_digest(provided, password):
+            abort(403)
+
+        rows = list_all(_get_db())
+        return render_template("feedback_hub/review.html", schema=_schema, rows=rows)
+
+    return bp

feedback_hub/wx_dialog.py

@@ -0,0 +1,246 @@
+"""wxPython native feedback dialog.
+
+Usage (ChapterForge, QUILL, any wxPython app)::
+
+    from feedback_hub.wx_dialog import FeedbackDialog
+    from feedback_hub import AppSchema, load_schema
+
+    schema = load_schema(Path("schemas/chapterforge.json"))
+    dlg = FeedbackDialog(parent, schema=schema, github_token=TOKEN)
+    dlg.ShowModal()
+    dlg.Destroy()
+
+The dialog submits directly to GitHub Issues -- no browser, no clipboard.
+"""
+from __future__ import annotations
+
+import platform
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+from feedback_hub._github import GitHubConfig, create_issue, resolve_token
+from feedback_hub._schema import AppSchema, build_entry
+from feedback_hub._storage import save as save_entry, update_github_sync
+
+
+class FeedbackDialog:
+    """Accessible wxPython dialog that submits issues directly to GitHub.
+
+    Requires wxPython to be importable. It is imported lazily so the
+    rest of feedback_hub works in environments without wx (e.g. GLOW).
+    """
+
+    def __init__(
+        self,
+        parent: Any,
+        *,
+        schema: AppSchema,
+        github_token: str = "",
+        db_path: Optional[Path] = None,
+        app_version: str = "",
+    ) -> None:
+        import wx
+
+        self._wx = wx
+        self._schema = schema
+        self._app_version = app_version or schema.version
+        self._db_path = db_path or (
+            Path.home() / "AppData" / "Roaming" / schema.app / "feedback.db"
+            if sys.platform == "win32"
+            else Path.home() / ".local" / "share" / schema.app.lower() / "feedback.db"
+        )
+        self._token = resolve_token(github_token)
+        self._dialog = wx.Dialog(
+            parent,
+            title=f"Report an Issue - {schema.app}",
+            size=(720, 680),
+        )
+        self._field_controls: dict[str, Any] = {}
+        self._build_ui()
+
+    # ------------------------------------------------------------------
+    # Public
+    # ------------------------------------------------------------------
+
+    def ShowModal(self) -> int:
+        return self._dialog.ShowModal()
+
+    def Destroy(self) -> None:
+        self._dialog.Destroy()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _build_ui(self) -> None:
+        wx = self._wx
+        schema = self._schema
+        dlg = self._dialog
+        panel = wx.Panel(dlg)
+        root = wx.BoxSizer(wx.VERTICAL)
+
+        # Instruction text
+        intro = wx.StaticText(
+            panel,
+            label=(
+                f"Describe your issue and it will be submitted directly to the "
+                f"{schema.app} issue tracker. No account required."
+            ),
+        )
+        intro.Wrap(660)
+        root.Add(intro, 0, wx.ALL | wx.EXPAND, 8)
+
+        # Name / email row
+        name_row = wx.BoxSizer(wx.HORIZONTAL)
+        name_label = wx.StaticText(panel, label="Your name (optional)")
+        self._name_ctrl = wx.TextCtrl(panel)
+        self._name_ctrl.SetName("Your name")
+        email_label = wx.StaticText(panel, label="Email (optional)")
+        self._email_ctrl = wx.TextCtrl(panel)
+        self._email_ctrl.SetName("Email address")
+        name_row.Add(name_label, 0, wx.ALIGN_CENTER_VERTICAL | wx.RIGHT, 4)
+        name_row.Add(self._name_ctrl, 1, wx.RIGHT, 16)
+        name_row.Add(email_label, 0, wx.ALIGN_CENTER_VERTICAL | wx.RIGHT, 4)
+        name_row.Add(self._email_ctrl, 1)
+        root.Add(name_row, 0, wx.LEFT | wx.RIGHT | wx.BOTTOM | wx.EXPAND, 8)
+
+        # Category
+        cat_label = wx.StaticText(panel, label="Category")
+        self._cat_ctrl = wx.Choice(panel, choices=schema.categories)
+        self._cat_ctrl.SetName("Issue category")
+        self._cat_ctrl.SetSelection(0)
+        root.Add(cat_label, 0, wx.LEFT | wx.RIGHT | wx.TOP, 8)
+        root.Add(self._cat_ctrl, 0, wx.LEFT | wx.RIGHT | wx.BOTTOM | wx.EXPAND, 8)
+
+        # Schema-driven fields
+        defaults = schema.resolve_defaults(self._app_version)
+        for f in schema.fields:
+            label = wx.StaticText(panel, label=f.label + (" *" if f.required else ""))
+            root.Add(label, 0, wx.LEFT | wx.RIGHT | wx.TOP, 8)
+            if f.type == "textarea":
+                ctrl = wx.TextCtrl(panel, style=wx.TE_MULTILINE, size=(-1, 90))
+            elif f.type == "select" and f.options:
+                ctrl = wx.Choice(panel, choices=f.options)
+            else:
+                ctrl = wx.TextCtrl(panel)
+
+            ctrl.SetName(f.label)
+            if isinstance(ctrl, wx.TextCtrl) and defaults.get(f.name):
+                ctrl.SetValue(defaults[f.name])
+            if f.placeholder and isinstance(ctrl, wx.TextCtrl):
+                ctrl.SetHint(f.placeholder)
+            root.Add(ctrl, 0, wx.LEFT | wx.RIGHT | wx.BOTTOM | wx.EXPAND, 8)
+            self._field_controls[f.name] = ctrl
+
+        # Buttons
+        buttons = wx.StdDialogButtonSizer()
+        self._submit_btn = wx.Button(dlg, wx.ID_OK, label="Submit Issue")
+        cancel_btn = wx.Button(dlg, wx.ID_CANCEL, label="Cancel")
+        buttons.AddButton(self._submit_btn)
+        buttons.AddButton(cancel_btn)
+        buttons.Realize()
+        root.Add(buttons, 0, wx.ALL | wx.EXPAND, 8)
+
+        panel.SetSizer(root)
+        panel.Layout()
+
+        self._submit_btn.Bind(wx.EVT_BUTTON, self._on_submit)
+        self._name_ctrl.SetFocus()
+
+    def _on_submit(self, _event: Any) -> None:
+        wx = self._wx
+        values = {}
+        for name, ctrl in self._field_controls.items():
+            if isinstance(ctrl, wx.Choice):
+                sel = ctrl.GetSelection()
+                values[name] = ctrl.GetString(sel) if sel != wx.NOT_FOUND else ""
+            else:
+                values[name] = ctrl.GetValue().strip()
+
+        cat_sel = self._cat_ctrl.GetSelection()
+        category = (
+            self._cat_ctrl.GetString(cat_sel)
+            if cat_sel != wx.NOT_FOUND
+            else self._schema.categories[0]
+        )
+
+        errors = self._schema.validate(values)
+        if errors:
+            wx.MessageBox(
+                "\n".join(errors),
+                f"{self._schema.app} - Validation Error",
+                wx.OK | wx.ICON_WARNING,
+                self._dialog,
+            )
+            return
+
+        entry = build_entry(
+            self._schema,
+            values,
+            name=self._name_ctrl.GetValue().strip(),
+            email=self._email_ctrl.GetValue().strip(),
+            category=category,
+            app_version=self._app_version,
+            metadata={
+                "python": sys.version.splitlines()[0],
+                "platform": platform.platform(),
+            },
+        )
+
+        # Store locally first
+        try:
+            row_id = save_entry(entry, self._db_path)
+        except Exception:
+            row_id = None
+
+        # Submit to GitHub
+        if not self._token:
+            wx.MessageBox(
+                "Your report was saved locally but could not be submitted to GitHub - "
+                "no token is configured.",
+                f"{self._schema.app} - Saved Locally",
+                wx.OK | wx.ICON_INFORMATION,
+                self._dialog,
+            )
+            self._dialog.EndModal(wx.ID_OK)
+            return
+
+        cfg = GitHubConfig(
+            token=self._token,
+            repo=self._schema.github_repo,
+            assignee=self._schema.github_assignee,
+            labels=self._schema.github_labels,
+        )
+        issue_number, issue_url, error = create_issue(entry, cfg)
+
+        if row_id is not None:
+            try:
+                update_github_sync(
+                    row_id,
+                    issue_number=issue_number,
+                    issue_url=issue_url,
+                    error=error,
+                    db_path=self._db_path,
+                )
+            except Exception:
+                pass
+
+        if issue_url:
+            wx.MessageBox(
+                f"Your report has been submitted successfully.\n\nIssue: {issue_url}",
+                f"{self._schema.app} - Thank You",
+                wx.OK | wx.ICON_INFORMATION,
+                self._dialog,
+            )
+        else:
+            wx.MessageBox(
+                "Your report was saved but could not be submitted to GitHub right now.\n"
+                "We will retry automatically on next launch.\n\n"
+                f"Error: {error}",
+                f"{self._schema.app} - Saved",
+                wx.OK | wx.ICON_WARNING,
+                self._dialog,
+            )
+
+        self._dialog.EndModal(wx.ID_OK)

feedback_hub-1.0.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: feedback-hub
+Version: 1.0.0
+Summary: Multi-framework GitHub issue submission library - native UI per framework, centralized GitHub backend
+Project-URL: Homepage, https://github.com/community-access/feedback-hub
+Project-URL: Documentation, https://community-access.github.io/feedback-hub
+Project-URL: Repository, https://github.com/community-access/feedback-hub
+Project-URL: Issues, https://github.com/community-access/feedback-hub/issues
+Author-email: "Blind Information Technology Solutions (BITS)" <info@chapterforge.org>
+License: MIT License
+        
+        Copyright (c) 2026 Blind Information Technology Solutions (BITS)
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: flask>=3.0; extra == 'dev'
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == 'flask'
+Provides-Extra: wx
+Requires-Dist: wxpython>=4.2; extra == 'wx'
+Description-Content-Type: text/markdown
+
+# feedback-hub
+
+Multi-framework GitHub issue submission library. Native UI per framework, centralized GitHub backend.
+
+- **wxPython apps** (ChapterForge, QUILL): native dialog, direct GitHub submission
+- **Flask apps** (GLOW): web form, direct GitHub submission
+- **CLI / headless**: function call, direct GitHub submission
+
+See [INTEGRATING.md](INTEGRATING.md) for integration guides.

feedback_hub-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+feedback_hub/__init__.py,sha256=r6efyMZeNNVHyxX_15Lv-irdvy9adOjlrwtVPAnDpdo,3040
+feedback_hub/_github.py,sha256=Utn8kvEkbE1YDDBg-7gwyFyQR8GbRBUD50SY0Vpc7qs,4839
+feedback_hub/_schema.py,sha256=xGVeifv8wT_8GUyJTGbIqghpiv2iXgeSV791x3EEtvU,5708
+feedback_hub/_storage.py,sha256=-Ur0ncU8MPHNy2ReDyQfYjEC4AQbKgkWExerCcEoals,4104
+feedback_hub/compat_glow.py,sha256=ye4vSxbY8sROP17RGN24vYI_K9D7uln3sdE9pvxt_28,3077
+feedback_hub/flask_blueprint.py,sha256=iWNRBKXB2J3sey5p-E0dehhurPFJAp_GgzKjHb-KIGc,8744
+feedback_hub/wx_dialog.py,sha256=DcLpcVxfROm-9-L8E2CMuV4FEtD-wMI8tBWmvAJN3f8,8605
+feedback_hub-1.0.0.dist-info/METADATA,sha256=hTf1ctrP1rD3FWsWpcs9XS-dParV_sDCwB-n8zIkMVk,2609
+feedback_hub-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+feedback_hub-1.0.0.dist-info/licenses/LICENSE,sha256=aW5a-ckzPcVmKQLFJIiCDUJ71vO6IA5VUG9jOT_inKM,1102
+feedback_hub-1.0.0.dist-info/RECORD,,

feedback_hub-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

feedback_hub-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blind Information Technology Solutions (BITS)
+
+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.