things-api 0.1.0__py3-none-any.whl

things_api/__init__.py

@@ -0,0 +1 @@
+"""REST API for Things 3."""

things_api/app.py

@@ -0,0 +1,98 @@
+"""FastAPI application factory and entrypoint."""
+
+from __future__ import annotations
+
+import logging
+
+import uvicorn
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+from things_api.auth import require_token
+from things_api.config import Settings
+from things_api.models import HealthResponse
+from things_api.ratelimit import AuthRateLimiter
+from things_api.services.reader import ThingsReader
+from things_api.services.writer import ThingsWriter
+
+logger = logging.getLogger(__name__)
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    """Create and configure the FastAPI application."""
+    if settings is None:
+        settings = Settings()
+
+    app = FastAPI(
+        title="Things API",
+        description="REST API for Things 3 — expose your tasks over HTTP",
+        version="0.1.0",
+        docs_url=None,
+        redoc_url=None,
+        dependencies=[require_token(settings.things_api_token.get_secret_value())],
+    )
+
+    app.add_middleware(AuthRateLimiter, max_failures=10, window=60)
+
+    reader = ThingsReader(
+        db_path=str(settings.things_db_path) if settings.things_db_path else None,
+    )
+    writer = (
+        ThingsWriter(
+            auth_token=settings.things_auth_token.get_secret_value(),
+            verify_timeout=settings.things_verify_timeout,
+        )
+        if settings.write_enabled
+        else None
+    )
+
+    app.state.settings = settings
+    app.state.reader = reader
+    app.state.writer = writer
+
+    @app.exception_handler(RuntimeError)
+    async def runtime_error_handler(request: Request, exc: RuntimeError):
+        logger.exception("Unhandled runtime error")
+        return JSONResponse(
+            status_code=500,
+            content={"detail": "Internal server error"},
+        )
+
+    @app.get("/health", response_model=HealthResponse)
+    async def health():
+        try:
+            reader.inbox()
+            db_ok = True
+        except Exception:
+            db_ok = False
+
+        return HealthResponse(
+            status="healthy" if db_ok else "degraded",
+            read=db_ok,
+            write=settings.write_enabled,
+        )
+
+    from things_api.routers import todos, projects, lists, tags, areas, search
+    app.include_router(todos.router)
+    app.include_router(projects.router)
+    app.include_router(lists.router)
+    app.include_router(tags.router)
+    app.include_router(areas.router)
+    app.include_router(search.router)
+
+    return app
+
+
+def main() -> None:
+    """CLI entrypoint."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    settings = Settings()
+    app = create_app(settings)
+    uvicorn.run(
+        app,
+        host=settings.things_api_host,
+        port=settings.things_api_port,
+    )

things_api/auth.py

@@ -0,0 +1,26 @@
+"""Bearer token authentication."""
+
+import hmac
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+_scheme = HTTPBearer(auto_error=False)
+
+
+def require_token(expected_token: str):
+    """Return a FastAPI dependency that validates a Bearer token."""
+
+    async def _verify(
+        credentials: HTTPAuthorizationCredentials | None = Depends(_scheme),
+    ) -> None:
+        if credentials is None or not hmac.compare_digest(
+            credentials.credentials, expected_token
+        ):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid or missing API token",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+    return Depends(_verify)

things_api/config.py

@@ -0,0 +1,29 @@
+"""Application settings loaded from environment variables."""
+
+from pathlib import Path
+
+from pydantic import SecretStr
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Things API configuration.
+
+    All values can be set via environment variables or a .env file.
+    """
+
+    things_api_host: str = "0.0.0.0"
+    things_api_port: int = 5225
+    things_api_token: SecretStr
+    things_auth_token: SecretStr | None = None
+    things_db_path: Path | None = None
+    things_verify_timeout: float = 0.5
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+    @property
+    def write_enabled(self) -> bool:
+        """Whether write operations are available."""
+        return self.things_auth_token is not None and bool(
+            self.things_auth_token.get_secret_value()
+        )

things_api/models.py

@@ -0,0 +1,117 @@
+"""Pydantic request/response models for the Things API."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+# --- Requests ---
+
+
+class CreateTodoRequest(BaseModel):
+    """Create a new todo."""
+
+    title: str
+    notes: str | None = None
+    when: str | None = None
+    deadline: str | None = None
+    tags: list[str] | None = None
+    checklist_items: list[str] | None = None
+    list_id: str | None = None
+    list_title: str | None = None
+    heading: str | None = None
+    heading_id: str | None = None
+
+
+class UpdateTodoRequest(BaseModel):
+    """Update an existing todo. All fields optional."""
+
+    title: str | None = None
+    notes: str | None = None
+    prepend_notes: str | None = None
+    append_notes: str | None = None
+    when: str | None = None
+    deadline: str | None = None
+    tags: list[str] | None = None
+    add_tags: list[str] | None = None
+    checklist_items: list[str] | None = None
+    prepend_checklist_items: list[str] | None = None
+    append_checklist_items: list[str] | None = None
+    list_id: str | None = None
+    list_title: str | None = None
+    heading: str | None = None
+    heading_id: str | None = None
+
+
+class CreateProjectRequest(BaseModel):
+    """Create a new project."""
+
+    title: str
+    notes: str | None = None
+    when: str | None = None
+    deadline: str | None = None
+    tags: list[str] | None = None
+    area_id: str | None = None
+    area_title: str | None = None
+    todos: list[str] | None = None
+
+
+class UpdateProjectRequest(BaseModel):
+    """Update an existing project. All fields optional."""
+
+    title: str | None = None
+    notes: str | None = None
+    prepend_notes: str | None = None
+    append_notes: str | None = None
+    when: str | None = None
+    deadline: str | None = None
+    tags: list[str] | None = None
+    add_tags: list[str] | None = None
+    area_id: str | None = None
+    area_title: str | None = None
+
+
+class DeleteAction(str, Enum):
+    """Action when deleting (Things has no true deletion)."""
+
+    COMPLETE = "complete"
+    CANCEL = "cancel"
+
+
+class DeleteRequest(BaseModel):
+    """Body for DELETE endpoints."""
+
+    action: DeleteAction = DeleteAction.COMPLETE
+
+
+# --- Responses ---
+
+
+class TodoResponse(BaseModel):
+    """A Things todo item."""
+
+    model_config = {"extra": "allow"}
+
+    uuid: str
+    title: str
+    status: str
+
+
+class ProjectResponse(BaseModel):
+    """A Things project."""
+
+    model_config = {"extra": "allow"}
+
+    uuid: str
+    title: str
+    status: str
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: str
+    read: bool
+    write: bool

things_api/ratelimit.py

@@ -0,0 +1,55 @@
+"""In-memory rate limiter for failed authentication attempts."""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+
+
+class AuthRateLimiter(BaseHTTPMiddleware):
+    """Tracks 401 responses per client IP and blocks after too many failures.
+
+    Uses a sliding window: only failures within the last `window` seconds count.
+    Once `max_failures` is reached, subsequent requests from that IP receive
+    429 Too Many Requests until the window expires.
+    """
+
+    def __init__(self, app, max_failures: int = 10, window: int = 60) -> None:
+        super().__init__(app)
+        self._max_failures = max_failures
+        self._window = window
+        self._failures: dict[str, list[float]] = defaultdict(list)
+
+    def _client_ip(self, request: Request) -> str:
+        return request.client.host if request.client else "unknown"
+
+    def _prune(self, ip: str) -> None:
+        """Remove entries older than the window."""
+        cutoff = time.monotonic() - self._window
+        self._failures[ip] = [t for t in self._failures[ip] if t > cutoff]
+        if not self._failures[ip]:
+            del self._failures[ip]
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        ip = self._client_ip(request)
+        self._prune(ip)
+
+        if len(self._failures.get(ip, [])) >= self._max_failures:
+            return Response(
+                content='{"detail":"Too many failed attempts. Try again later."}',
+                status_code=429,
+                media_type="application/json",
+                headers={"Retry-After": str(self._window)},
+            )
+
+        response = await call_next(request)
+
+        if response.status_code == 401:
+            self._failures[ip].append(time.monotonic())
+
+        return response

things_api/routers/areas.py

@@ -0,0 +1,16 @@
+"""Area endpoints."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Request
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/areas", tags=["areas"])
+
+
+@router.get("")
+async def list_areas(request: Request, include_items: bool = False):
+    """List all areas."""
+    return request.app.state.reader.areas(include_items=include_items)

things_api/routers/lists.py

@@ -0,0 +1,51 @@
+"""Smart list endpoints — inbox, today, upcoming, anytime, someday, logbook."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Request
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["lists"])
+
+
+@router.get("/inbox")
+async def inbox(request: Request):
+    """Get inbox todos."""
+    return request.app.state.reader.inbox()
+
+
+@router.get("/today")
+async def today(request: Request):
+    """Get today's todos."""
+    return request.app.state.reader.today()
+
+
+@router.get("/upcoming")
+async def upcoming(request: Request):
+    """Get upcoming todos."""
+    return request.app.state.reader.upcoming()
+
+
+@router.get("/anytime")
+async def anytime(request: Request):
+    """Get anytime todos."""
+    return request.app.state.reader.anytime()
+
+
+@router.get("/someday")
+async def someday(request: Request):
+    """Get someday todos."""
+    return request.app.state.reader.someday()
+
+
+@router.get("/logbook")
+async def logbook(request: Request, period: str | None = None, limit: int | None = None):
+    """Get completed todos from the logbook."""
+    filters = {}
+    if period:
+        filters["last"] = period
+    if limit:
+        filters["limit"] = limit
+    return request.app.state.reader.logbook(**filters)

things_api/routers/projects.py

@@ -0,0 +1,111 @@
+"""Project CRUD endpoints."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from fastapi import APIRouter, HTTPException, Request, status
+from fastapi.responses import JSONResponse
+
+from things_api.models import (
+    CreateProjectRequest,
+    DeleteAction,
+    DeleteRequest,
+    UpdateProjectRequest,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/projects", tags=["projects"])
+
+
+@router.get("")
+async def list_projects(request: Request):
+    """List all projects."""
+    return request.app.state.reader.projects()
+
+
+@router.get("/{project_id}")
+async def get_project(request: Request, project_id: str):
+    """Get a project with its todos."""
+    result = request.app.state.reader.get(project_id)
+    if result is None:
+        raise HTTPException(status_code=404, detail="Project not found")
+    return result
+
+
+@router.post("")
+async def create_project(request: Request, body: CreateProjectRequest):
+    """Create a new project."""
+    writer = request.app.state.writer
+    if writer is None:
+        raise HTTPException(
+            status_code=503, detail="Write operations not configured"
+        )
+
+    params = body.model_dump(exclude_none=True)
+    if "todos" in params:
+        params["todos"] = "\n".join(params["todos"])
+
+    await writer.create_project(**params)
+
+    return JSONResponse(
+        status_code=status.HTTP_202_ACCEPTED,
+        content={"status": "accepted", "title": body.title},
+    )
+
+
+@router.put("/{project_id}")
+async def update_project(
+    request: Request, project_id: str, body: UpdateProjectRequest
+):
+    """Update an existing project."""
+    writer = request.app.state.writer
+    if writer is None:
+        raise HTTPException(
+            status_code=503, detail="Write operations not configured"
+        )
+
+    existing = request.app.state.reader.get(project_id)
+    if existing is None:
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    params = body.model_dump(exclude_none=True)
+    await writer.update_project(uuid=project_id, **params)
+
+    await asyncio.sleep(request.app.state.settings.things_verify_timeout)
+    updated = request.app.state.reader.get(project_id)
+    if updated:
+        return updated
+    return JSONResponse(
+        status_code=status.HTTP_202_ACCEPTED,
+        content={"status": "accepted", "uuid": project_id},
+    )
+
+
+@router.delete("/{project_id}")
+async def delete_project(
+    request: Request, project_id: str, body: DeleteRequest | None = None
+):
+    """Complete or cancel a project (irreversible).
+
+    Things 3 does not support true deletion. This endpoint marks the project as
+    completed (default) or cancelled. Pass {"action": "cancel"} to cancel instead.
+    """
+    writer = request.app.state.writer
+    if writer is None:
+        raise HTTPException(
+            status_code=503, detail="Write operations not configured"
+        )
+
+    existing = request.app.state.reader.get(project_id)
+    if existing is None:
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    action = body.action if body else DeleteAction.COMPLETE
+    if action == DeleteAction.CANCEL:
+        await writer.cancel_project(uuid=project_id)
+    else:
+        await writer.complete_project(uuid=project_id)
+
+    return {"status": action.value, "uuid": project_id}

things_api/routers/search.py

@@ -0,0 +1,61 @@
+"""Search endpoints."""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+
+from fastapi import APIRouter, HTTPException, Query, Request
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/search", tags=["search"])
+
+
+class SearchStatus(str, Enum):
+    INCOMPLETE = "incomplete"
+    COMPLETED = "completed"
+    CANCELED = "canceled"
+
+
+class SearchType(str, Enum):
+    TO_DO = "to-do"
+    PROJECT = "project"
+    HEADING = "heading"
+
+
+@router.get("")
+async def search(request: Request, q: str):
+    """Full-text search across todos."""
+    if not q.strip():
+        raise HTTPException(status_code=400, detail="Query parameter 'q' is required")
+    return request.app.state.reader.search(q)
+
+
+@router.get("/advanced")
+async def advanced_search(
+    request: Request,
+    status: SearchStatus | None = None,
+    tag: str | None = None,
+    area: str | None = None,
+    type: SearchType | None = None,
+    start_date: str = Query(None, pattern=r"^\d{4}-\d{2}-\d{2}$"),
+    deadline: str = Query(None, pattern=r"^\d{4}-\d{2}-\d{2}$"),
+    last: str = Query(None, pattern=r"^\d+[dwmy]$"),
+):
+    """Filtered search with multiple criteria."""
+    filters = {}
+    if status:
+        filters["status"] = status.value
+    if tag:
+        filters["tag"] = tag
+    if area:
+        filters["area"] = area
+    if type:
+        filters["type"] = type.value
+    if start_date:
+        filters["start_date"] = start_date
+    if deadline:
+        filters["deadline"] = deadline
+    if last:
+        filters["last"] = last
+    return request.app.state.reader.todos(**filters)

things_api/routers/tags.py

@@ -0,0 +1,22 @@
+"""Tag endpoints."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Request
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/tags", tags=["tags"])
+
+
+@router.get("")
+async def list_tags(request: Request, include_items: bool = False):
+    """List all tags."""
+    return request.app.state.reader.tags(include_items=include_items)
+
+
+@router.get("/{tag}/items")
+async def tag_items(request: Request, tag: str):
+    """Get items with a specific tag."""
+    return request.app.state.reader.tags_for_item(tag_title=tag)

things_api/routers/todos.py

@@ -0,0 +1,133 @@
+"""Todo CRUD endpoints."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from fastapi import APIRouter, HTTPException, Request, status
+from fastapi.responses import JSONResponse
+
+from things_api.models import (
+    CreateTodoRequest,
+    DeleteAction,
+    DeleteRequest,
+    UpdateTodoRequest,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/todos", tags=["todos"])
+
+
+@router.get("")
+async def list_todos(
+    request: Request,
+    project_id: str | None = None,
+    area_id: str | None = None,
+    tag: str | None = None,
+    include_checklist: bool = False,
+):
+    """List all incomplete todos, with optional filters."""
+    reader = request.app.state.reader
+    filters = {}
+    if project_id:
+        filters["project"] = project_id
+    if area_id:
+        filters["area"] = area_id
+    if tag:
+        filters["tag"] = tag
+    if include_checklist:
+        filters["include_items"] = True
+    return reader.todos(**filters)
+
+
+@router.get("/{todo_id}")
+async def get_todo(request: Request, todo_id: str):
+    """Get a specific todo by ID."""
+    result = request.app.state.reader.get(todo_id)
+    if result is None:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    return result
+
+
+@router.post("")
+async def create_todo(request: Request, body: CreateTodoRequest):
+    """Create a new todo."""
+    writer = request.app.state.writer
+    if writer is None:
+        raise HTTPException(
+            status_code=503, detail="Write operations not configured"
+        )
+
+    params = body.model_dump(exclude_none=True)
+    if "checklist_items" in params:
+        params["checklist_items"] = "\n".join(params["checklist_items"])
+
+    await writer.create_todo(**params)
+
+    return JSONResponse(
+        status_code=status.HTTP_202_ACCEPTED,
+        content={"status": "accepted", "title": body.title},
+    )
+
+
+@router.put("/{todo_id}")
+async def update_todo(request: Request, todo_id: str, body: UpdateTodoRequest):
+    """Update an existing todo."""
+    writer = request.app.state.writer
+    if writer is None:
+        raise HTTPException(
+            status_code=503, detail="Write operations not configured"
+        )
+
+    existing = request.app.state.reader.get(todo_id)
+    if existing is None:
+        raise HTTPException(status_code=404, detail="Todo not found")
+
+    params = body.model_dump(exclude_none=True)
+    for list_field in (
+        "checklist_items",
+        "prepend_checklist_items",
+        "append_checklist_items",
+    ):
+        if list_field in params:
+            params[list_field] = "\n".join(params[list_field])
+
+    await writer.update_todo(uuid=todo_id, **params)
+
+    await asyncio.sleep(request.app.state.settings.things_verify_timeout)
+    updated = request.app.state.reader.get(todo_id)
+    if updated:
+        return updated
+    return JSONResponse(
+        status_code=status.HTTP_202_ACCEPTED,
+        content={"status": "accepted", "uuid": todo_id},
+    )
+
+
+@router.delete("/{todo_id}")
+async def delete_todo(
+    request: Request, todo_id: str, body: DeleteRequest | None = None
+):
+    """Complete or cancel a todo (irreversible).
+
+    Things 3 does not support true deletion. This endpoint marks the item as
+    completed (default) or cancelled. Pass {"action": "cancel"} to cancel instead.
+    """
+    writer = request.app.state.writer
+    if writer is None:
+        raise HTTPException(
+            status_code=503, detail="Write operations not configured"
+        )
+
+    existing = request.app.state.reader.get(todo_id)
+    if existing is None:
+        raise HTTPException(status_code=404, detail="Todo not found")
+
+    action = body.action if body else DeleteAction.COMPLETE
+    if action == DeleteAction.CANCEL:
+        await writer.cancel_todo(uuid=todo_id)
+    else:
+        await writer.complete_todo(uuid=todo_id)
+
+    return {"status": action.value, "uuid": todo_id}

things_api/services/reader.py

@@ -0,0 +1,73 @@
+"""Read-only access to Things 3 data via things.py."""
+
+from __future__ import annotations
+
+import things
+
+
+class ThingsReader:
+    """Wraps things.py, injecting db_path when configured."""
+
+    def __init__(self, db_path: str | None = None) -> None:
+        self._db_path = db_path
+
+    def _kwargs(self, **extra) -> dict:
+        """Build kwargs, adding filepath if configured."""
+        kw = {k: v for k, v in extra.items() if v is not None}
+        if self._db_path:
+            kw["filepath"] = self._db_path
+        return kw
+
+    def todos(self, **filters) -> list[dict]:
+        return things.todos(**self._kwargs(**filters))
+
+    def projects(self, **filters) -> list[dict]:
+        return things.projects(**self._kwargs(**filters))
+
+    def areas(self, include_items: bool = False) -> list[dict]:
+        return things.areas(**self._kwargs(include_items=include_items))
+
+    def tags(self, include_items: bool = False) -> list[dict]:
+        return things.tags(**self._kwargs(include_items=include_items))
+
+    def get(self, uuid: str) -> dict | None:
+        return things.get(uuid, **self._kwargs())
+
+    def search(self, query: str) -> list[dict]:
+        return things.search(query, **self._kwargs())
+
+    def inbox(self) -> list[dict]:
+        return things.inbox(**self._kwargs())
+
+    def today(self) -> list[dict]:
+        return things.today(**self._kwargs())
+
+    def upcoming(self) -> list[dict]:
+        return things.upcoming(**self._kwargs())
+
+    def anytime(self) -> list[dict]:
+        return things.anytime(**self._kwargs())
+
+    def someday(self) -> list[dict]:
+        return things.someday(**self._kwargs())
+
+    def logbook(self, **filters) -> list[dict]:
+        return things.logbook(**self._kwargs(**filters))
+
+    def completed(self, **filters) -> list[dict]:
+        return things.completed(**self._kwargs(**filters))
+
+    def canceled(self, **filters) -> list[dict]:
+        return things.canceled(**self._kwargs(**filters))
+
+    def trash(self) -> list[dict]:
+        return things.trash(**self._kwargs())
+
+    def deadlines(self) -> list[dict]:
+        return things.deadlines(**self._kwargs())
+
+    def checklist_items(self, todo_uuid: str) -> list[dict]:
+        return things.checklist_items(todo_uuid, **self._kwargs())
+
+    def tags_for_item(self, tag_title: str) -> list[dict]:
+        return things.tags(title=tag_title, include_items=True, **self._kwargs())

things_api/services/writer.py

@@ -0,0 +1,86 @@
+"""Write to Things 3 via the URL scheme."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from urllib.parse import quote, urlencode
+
+logger = logging.getLogger(__name__)
+
+
+class ThingsWriter:
+    """Creates and updates Things items via the URL scheme."""
+
+    def __init__(self, auth_token: str, verify_timeout: float = 0.5) -> None:
+        self._auth_token = auth_token
+        self._verify_timeout = verify_timeout
+
+    def _build_url(self, command: str, **params) -> str:
+        """Build a things:/// URL with encoded parameters."""
+        filtered = {}
+        for key, value in params.items():
+            if value is None:
+                continue
+            url_key = key.replace("_", "-")
+            if isinstance(value, list):
+                filtered[url_key] = ",".join(str(v) for v in value)
+            elif isinstance(value, bool):
+                filtered[url_key] = "true" if value else "false"
+            else:
+                filtered[url_key] = str(value)
+        qs = urlencode(filtered, quote_via=quote)
+        return f"things:///{command}?{qs}" if qs else f"things:///{command}"
+
+    async def _execute(self, url: str) -> None:
+        """Open a Things URL scheme command."""
+        redacted = url.replace(self._auth_token, "REDACTED")
+        redacted = redacted.replace(
+            quote(self._auth_token, safe=""), "REDACTED"
+        )
+        logger.info("Executing: %s", redacted)
+
+        proc = await asyncio.create_subprocess_exec(
+            "open", url,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        returncode = await proc.wait()
+        if returncode != 0:
+            stderr = await proc.stderr.read() if proc.stderr else b""
+            logger.error(
+                "URL scheme command failed (exit %d): %s",
+                returncode, stderr.decode(),
+            )
+            raise RuntimeError("Write operation failed")
+
+    async def create_todo(self, **params) -> None:
+        url = self._build_url("add", **params)
+        await self._execute(url)
+
+    async def update_todo(self, uuid: str, **params) -> None:
+        url = self._build_url(
+            "update", id=uuid, auth_token=self._auth_token, **params
+        )
+        await self._execute(url)
+
+    async def complete_todo(self, uuid: str) -> None:
+        await self.update_todo(uuid, completed=True)
+
+    async def cancel_todo(self, uuid: str) -> None:
+        await self.update_todo(uuid, canceled=True)
+
+    async def create_project(self, **params) -> None:
+        url = self._build_url("add-project", **params)
+        await self._execute(url)
+
+    async def update_project(self, uuid: str, **params) -> None:
+        url = self._build_url(
+            "update-project", id=uuid, auth_token=self._auth_token, **params
+        )
+        await self._execute(url)
+
+    async def complete_project(self, uuid: str) -> None:
+        await self.update_project(uuid, completed=True)
+
+    async def cancel_project(self, uuid: str) -> None:
+        await self.update_project(uuid, canceled=True)

things_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: things-api
+Version: 0.1.0
+Summary: REST API for Things 3 — expose your tasks over HTTP
+Project-URL: Homepage, https://github.com/jaydenk/things-api
+Project-URL: Documentation, https://github.com/jaydenk/things-api/tree/main/docs
+Project-URL: Issues, https://github.com/jaydenk/things-api/issues
+Project-URL: Changelog, https://github.com/jaydenk/things-api/blob/main/CHANGELOG.md
+Author: Jayden Kerr
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,gtd,rest,tasks,things,things3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1,>=0.135
+Requires-Dist: pydantic-settings<3,>=2.13
+Requires-Dist: things-py<2,>=1.0
+Requires-Dist: uvicorn[standard]<1,>=0.34
+Provides-Extra: test
+Requires-Dist: httpx>=0.28; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.25; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Things API
+
+REST API for [Things 3](https://culturedcode.com/things/) — expose your tasks over HTTP.
+
+Things API reads directly from the Things SQLite database via [things.py](https://github.com/thingsapi/things.py) and writes back through the [Things URL scheme](https://culturedcode.com/things/support/articles/2803573/). It runs as a lightweight FastAPI service on any Mac where Things is installed, giving you full programmatic access to your tasks from tools like [n8n](https://n8n.io/), [curl](https://curl.se/), or any HTTP client.
+
+## Getting started
+
+**Requirements:** macOS with [Things 3](https://culturedcode.com/things/) installed, Python 3.12+, and [uv](https://docs.astral.sh/uv/).
+
+### 1. Clone and install
+
+```sh
+git clone https://github.com/jaydenk/things-api.git
+cd things-api
+uv venv
+uv pip install -e .
+```
+
+### 2. Configure
+
+```sh
+cp env.example .env
+```
+
+Open `.env` and set your API token — this is the bearer token that authenticates every request:
+
+```dotenv
+THINGS_API_TOKEN=choose-a-secure-random-string
+```
+
+To enable write operations (creating, updating, completing todos), you also need a Things URL scheme auth token. To get one, open **Things > Settings > General > Enable Things URLs** and copy the token:
+
+```dotenv
+THINGS_AUTH_TOKEN=your-things-url-scheme-token
+```
+
+Without `THINGS_AUTH_TOKEN`, the API runs in **read-only mode**.
+
+See [docs/configuration.md](docs/configuration.md) for all configuration options.
+
+### 3. Run
+
+```sh
+uv run things-api
+```
+
+The server starts on `http://localhost:5225`.
+
+### 4. Try it
+
+```sh
+# Health check
+curl http://localhost:5225/health \
+  -H "Authorization: Bearer YOUR_TOKEN"
+
+# List today's tasks
+curl http://localhost:5225/today \
+  -H "Authorization: Bearer YOUR_TOKEN"
+
+# Create a todo (requires THINGS_AUTH_TOKEN)
+curl -X POST http://localhost:5225/todos \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Buy milk", "when": "today"}'
+```
+
+To run the server persistently (auto-start at login, auto-restart on crash), see the [deployment guide](docs/deployment.md).
+
+## Endpoints overview
+
+Every endpoint requires a valid `Authorization: Bearer <token>` header.
+
+| Resource | Endpoints | Description |
+|---|---|---|
+| **Todos** | `GET` `POST` `PUT` `DELETE` `/todos` | Full CRUD for todos |
+| **Projects** | `GET` `POST` `PUT` `DELETE` `/projects` | Full CRUD for projects |
+| **Smart lists** | `GET` `/inbox` `/today` `/upcoming` `/anytime` `/someday` `/logbook` | Read-only access to Things smart lists |
+| **Tags** | `GET` `/tags` | List tags and items by tag |
+| **Areas** | `GET` `/areas` | List areas |
+| **Search** | `GET` `/search` `/search/advanced` | Full-text and filtered search |
+| **Health** | `GET` `/health` | Service status and database connectivity |
+
+> **Note:** `DELETE` on todos and projects is **irreversible** — it completes or cancels the item. Things 3 does not support true deletion.
+
+See [docs/api-reference.md](docs/api-reference.md) for full endpoint details, request/response schemas, and query parameters.
+
+## Limitations
+
+- **macOS only** — Things 3 is a Mac app. The API must run on the same machine.
+- **GUI session required for writes** — Write operations invoke the Things URL scheme, which requires an active GUI session.
+- **No true deletion** — `DELETE` endpoints complete or cancel items instead.
+
+## Further documentation
+
+- [Configuration reference](docs/configuration.md) — All environment variables and their defaults
+- [API reference](docs/api-reference.md) — Full endpoint documentation with request/response details
+- [Deployment guide](docs/deployment.md) — Running as a launchd service, n8n integration
+- [Development guide](docs/development.md) — Setting up a dev environment, running tests
+- [Changelog](CHANGELOG.md) — Version history
+
+## Licence
+
+[MIT](./LICENSE)

things_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+things_api/__init__.py,sha256=H94apNAWCbc_PGWaUvvcX2yterpCmgpRi9yow12wjBw,29
+things_api/app.py,sha256=jm_2ENpMPsGo8J-HS7t81mnEWgLyTxN1smBTPFLgy6Q,2825
+things_api/auth.py,sha256=n95hJlhbPsp6aRKYmxtLcGCfXDqwBC8--a1e_uZdvyI,804
+things_api/config.py,sha256=Xu7EZvrMD0xOmKITVbXdtkoZJ-UwBnKp46JA3lB1Dq4,833
+things_api/models.py,sha256=MAjTs34vqhRHYax2iRLyzxSFqvL1MtpZC_2RGTMGTaU,2631
+things_api/ratelimit.py,sha256=wj8jCpor_jnd3KaPj7p7XTk0E9dhxDv22bsrUpmVaqg,1941
+things_api/routers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+things_api/routers/areas.py,sha256=pYZ67_O4dlKeQZlmt0usSy8TIvIT2_ac28GJZYY5i_E,388
+things_api/routers/lists.py,sha256=0mSZb2btM-s6Eps99cd6maxJkKuJOSbmq_wX3qMs1_g,1258
+things_api/routers/projects.py,sha256=1x5U5UibqVTfQykuUUu2GlW9Gir8YGWYwHHcB0mFkrQ,3322
+things_api/routers/search.py,sha256=CQnlNKZ9v_Wp9nUgH6omcFnLIWaNQCLJXvEitjeo28w,1596
+things_api/routers/tags.py,sha256=lH0WNZ1l_Mh7v1cuPuJkJiEXU1of8n_Q5Za98MYGnCU,567
+things_api/routers/todos.py,sha256=XjjFeNhmVEERxMinbT05dz6WyjAugK2tH3qxa-_2Ci0,3882
+things_api/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+things_api/services/reader.py,sha256=8derO3VekFJ9f5req5fBeathy0MSC5ER4W3iiqa9a6k,2407
+things_api/services/writer.py,sha256=cq6bmKb16bxg5GzPBq5cQXr_ZaxKl0UK625_TkBsYTs,3045
+things_api-0.1.0.dist-info/METADATA,sha256=cw2SHZIxCbmATbdiMXxhODhYPXMehFn8bLsJ2KKNMrM,5069
+things_api-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+things_api-0.1.0.dist-info/entry_points.txt,sha256=oZW5kJ2NnWHznrwxLZkkKoLB4BB-Tk4GJWRJ-yfguXU,51
+things_api-0.1.0.dist-info/licenses/LICENSE,sha256=JeD-u7MIr0sv5zfK1mRZlHxZZwmIEcYeDsWjR5w3uhA,1068
+things_api-0.1.0.dist-info/RECORD,,

things_api-0.1.0.dist-info/WHEEL

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

things_api-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+things-api = things_api.app:main

things_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT Licence
+
+Copyright (c) 2026 Jayden Kerr
+
+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.