osm-sdk 0.1.0.dev1__tar.gz

osm_sdk-0.1.0.dev1/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: Build and Test
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-and-test:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest -q
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/*
+          if-no-files-found: error

osm_sdk-0.1.0.dev1/.github/workflows/lint-pr-title.yml

@@ -0,0 +1,37 @@
+name: Lint Pull Request Title
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: write
+
+jobs:
+  pull-request-title-lint:
+    name: Lint Pull Request Title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Lint Pull Request Title
+        id: lint_pr_title
+        uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Sticky Pull Request Comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        if: always() && (steps.lint_pr_title.outputs.error_message != null)
+        with:
+          header: pr-title-lint-error
+          message: Pull request titles must follow the Conventional Commits specification.
+
+      - name: Delete Sticky Pull Request Comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        if: ${{ steps.lint_pr_title.outputs.error_message == null }}
+        with:
+          header: pr-title-lint-error
+          delete: true

osm_sdk-0.1.0.dev1/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish Package
+
+on:
+  release:
+    types: [ published ]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

osm_sdk-0.1.0.dev1/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+site/
+docs_site/
+dist/
+build/
+*.egg-info/
+
+# IDE/editor
+.idea/
+.vscode/
+
+# OS files
+.DS_Store
+Thumbs.db

osm_sdk-0.1.0.dev1/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to OSM SDK
+Contributions to OSM SDK are welcome!
+
+OSM SDK is a Python SDK for Online Scout Manager (OSM).
+
+This guide explains how to contribute to the project.
+
+## How to Contribute
+There are several ways to contribute to OSM SDK:
+- **Report bugs:** Find an issue and describe the problem you encountered
+- **Fix bugs:** Submit a pull request with a proposed fix
+- **Request features:** Suggest a new feature or improvement
+- **Improve documentation:** Submit a pull request with improved documentation
+
+## Submitting a Pull Request
+To submit a pull request, follow these steps:
+- Fork the repository
+- Create a new branch for your changes
+- Make your changes and write tests if applicable
+- Commit and push your changes to your fork
+- Submit a pull request to the `main` branch of this repository
+
+### Pull Request Title Convention
+To maintain a clean and automated changelog, this project requires pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/). Titles should be formatted as follows:
+`<type>: <description>`
+
+Common types include:
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Changes that do not affect the meaning of the code (white-space, formatting, etc.)
+- `refactor`: A code change that neither fixes a bug nor adds a feature
+- `test`: Adding missing tests or correcting existing tests
+- `chore`: Changes to the build process or auxiliary tools and libraries such as documentation generation
+
+## Testing Guidelines
+To ensure that changes work as expected, follow these steps:
+- Use the provided pytest test framework to write tests
+- Write tests for all new features or bug fixes
+- Ensure all tests pass before submitting a pull request
+
+## Release Process
+This project uses [setuptools-scm](https://setuptools-scm.readthedocs.io/) for versioning.
+
+Versions are automatically determined by Git tags in the format `vMAJOR.MINOR.PATCH`.
+To create a new release, use the GitHub UI to create a new "Release", which will automatically create the required Git tag and trigger the deployment workflow.
+
+## License
+By contributing to OSM SDK, you agree that your contributions will be licensed under the MIT License.

osm_sdk-0.1.0.dev1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Shephard
+
+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.

osm_sdk-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: osm-sdk
+Version: 0.1.0.dev1
+Summary: A Python SDK for Online Scout Manager (OSM)
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: email-validator>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: respx>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: build>=1.2.2; extra == "dev"
+Dynamic: license-file
+
+# OSM SDK
+
+OSM SDK is a Python SDK for Online Scout Manager (OSM).
+
+The project is provided as a PyPI package that is published on [pypi.org](https://pypi.org/project/osm-sdk/), and it can be installed by running:
+
+```bash
+pip install osm-sdk
+```
+
+## Requirements
+
+OSM SDK requires an OAuth Client ID and Oauth Secret.
+
+These can be generated within OSM, by going to Settings → My Account Details → Developer Tools → Create Application.
+
+Client Credentials Grant must be enabled for the application.
+
+## Quick Start
+
+```python
+from osm_sdk import OSMClient, OSMAttendanceStatus
+
+client = OSMClient(client_id="...", client_secret="...")
+
+section = client.get_section(name="Scouts")
+term = section.current_term()
+
+for member in term.list_members():
+    contacts = member.list_contacts()
+    print(f"Member: {member.full_name} has {len(contacts)} contacts.")
+
+for event in term.list_events():
+    attendance = event.list_attendance()
+    attending = [a for a in attendance if a.status == OSMAttendanceStatus.YES]
+    print(f"Event: {event.name}: {len(attending)} attending (out of {len(attendance)})")
+
+for meeting in term.list_meetings():
+    attendance = meeting.list_attendance()
+    attending = [a for a in attendance if a.status == OSMAttendanceStatus.YES]
+    print(f"Meeting: {meeting.name}: {len(attending)} attending (out of {len(attendance)})")
+```
+
+By default, `OSMClient` requests the scopes:
+`section:member:read section:event:read section:programme:read section:attendance:read`.
+
+## Documentation
+
+The public API is documented in [PUBLIC_API.md](PUBLIC_API.md).
+
+## Contributions
+
+Contributions are welcome! Read the [contributing guide](CONTRIBUTING.md) to get started.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

osm_sdk-0.1.0.dev1/PUBLIC_API.md

@@ -0,0 +1,114 @@
+# OSM SDK Public API
+
+## Table of Contents
+- [OSMClient](#osmclient)
+- [OSMSection](#osmsection)
+- [OSMTerm](#osmterm)
+- [OSMMember](#osmmember)
+- [OSMContact](#osmcontact)
+- [OSMEvent](#osmevent)
+- [OSMMeeting](#osmmeeting)
+- [OSMAttendance](#osmattendance)
+- [Enums](#enums)
+
+---
+
+## OSMClient
+
+### Methods
+- `get_sections() -> list[OSMSection]`
+- `get_section(name: str | None = None, *, section_id: str | None = None) -> OSMSection`
+- `close() -> None`
+
+## OSMSection
+
+### Properties
+- `id: str`
+- `name: str`
+
+### Methods
+- `list_terms() -> list[OSMTerm]`
+- `current_term() -> OSMTerm`
+- `list_members(*, waiting_list: bool = False) -> list[OSMMember]`
+
+## OSMTerm
+
+### Properties
+- `id: str`
+- `name: str`
+- `start_date: date`
+- `end_date: date`
+- `current: bool` (computed)
+
+### Methods
+- `list_members() -> list[OSMMember]`
+- `list_events() -> list[OSMEvent]`
+- `list_meetings() -> list[OSMMeeting]`
+
+## OSMMember
+
+### Properties
+- `id: str`
+- `first_name: str`
+- `last_name: str`
+- `type: OSMMemberType`
+- `date_of_birth: date | None`
+- `date_joined_movement: date | None`
+- `gender: str | None`
+- `address: str | None`
+- `postcode: str | None`
+- `primary_email: str | None`
+- `secondary_email: str | None`
+- `primary_phone: str | None`
+- `secondary_phone: str | None`
+- `full_name: str` (computed)
+
+### Methods
+- `list_contacts() -> list[OSMContact]`
+
+## OSMContact
+
+### Properties
+- `type: OSMContactType`
+- `first_name: str | None`
+- `last_name: str | None`
+- `full_name: str` (computed)
+- `relationship: str | None`
+- `primary_email: str | None`
+- `secondary_email: str | None`
+- `primary_phone: str | None`
+- `secondary_phone: str | None`
+- `postcode: str | None`
+- `address: str | None`
+
+## OSMEvent
+
+### Properties
+- `id: str`
+- `name: str`
+- `start_date: date`
+- `end_date: date`
+
+### Methods
+- `list_attendance() -> list[OSMAttendance]`
+
+## OSMMeeting
+
+### Properties
+- `id: str`
+- `name: str`
+- `date: date`
+
+### Methods
+- `list_attendance() -> list[OSMAttendance]`
+
+## OSMAttendance
+
+### Properties
+- `member: OSMMember`
+- `status: OSMAttendanceStatus`
+
+## Enums
+- `OSMAttendanceStatus` (`yes`, `no`, `unknown`)
+- `OSMContactType` (`PRIMARY_CONTACT`, `SECONDARY_CONTACT`, `EMERGENCY_CONTACT`)
+- `OSMMemberType` (`YOUNG_PERSON`, `YOUNG_LEADER`, `LEADER`)

osm_sdk-0.1.0.dev1/README.md

@@ -0,0 +1,57 @@
+# OSM SDK
+
+OSM SDK is a Python SDK for Online Scout Manager (OSM).
+
+The project is provided as a PyPI package that is published on [pypi.org](https://pypi.org/project/osm-sdk/), and it can be installed by running:
+
+```bash
+pip install osm-sdk
+```
+
+## Requirements
+
+OSM SDK requires an OAuth Client ID and Oauth Secret.
+
+These can be generated within OSM, by going to Settings → My Account Details → Developer Tools → Create Application.
+
+Client Credentials Grant must be enabled for the application.
+
+## Quick Start
+
+```python
+from osm_sdk import OSMClient, OSMAttendanceStatus
+
+client = OSMClient(client_id="...", client_secret="...")
+
+section = client.get_section(name="Scouts")
+term = section.current_term()
+
+for member in term.list_members():
+    contacts = member.list_contacts()
+    print(f"Member: {member.full_name} has {len(contacts)} contacts.")
+
+for event in term.list_events():
+    attendance = event.list_attendance()
+    attending = [a for a in attendance if a.status == OSMAttendanceStatus.YES]
+    print(f"Event: {event.name}: {len(attending)} attending (out of {len(attendance)})")
+
+for meeting in term.list_meetings():
+    attendance = meeting.list_attendance()
+    attending = [a for a in attendance if a.status == OSMAttendanceStatus.YES]
+    print(f"Meeting: {meeting.name}: {len(attending)} attending (out of {len(attendance)})")
+```
+
+By default, `OSMClient` requests the scopes:
+`section:member:read section:event:read section:programme:read section:attendance:read`.
+
+## Documentation
+
+The public API is documented in [PUBLIC_API.md](PUBLIC_API.md).
+
+## Contributions
+
+Contributions are welcome! Read the [contributing guide](CONTRIBUTING.md) to get started.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

osm_sdk-0.1.0.dev1/implementation-plan.md

@@ -0,0 +1,31 @@
+# OSM SDK: Technical Specification & Implementation Plan (Sync-Only TDD)
+
+This document is the authoritative specification for building the `osm-sdk`. Any agent or developer implementing this plan must follow these mandates strictly.
+
+## 1. Core Architectural Mandates
+- **Sync-Only Implementation**: To eliminate code duplication and maintainability overhead, the SDK is **Sync-Only**. No async support is required.
+- **Strict Anti-Hallucination**: The developer/agent **MUST NEVER** guess API endpoints, query parameters, or JSON structures. If the information is not provided in the current context, the agent **MUST STOP and ask the developer** for the "Ground Truth" (real JSON samples and endpoint URLs).
+- **Strict TDD**: Development proceeds in a failing test -> implementation -> verification loop. Tests MUST be based on real-world OSM payload samples.
+- **Strict Canonicalization**: All raw data from OSM is mapped into flat, strictly-typed Pydantic models with `extra="forbid"`. This is a hard security requirement to prevent PII leakage (medical, behavioral, etc.).
+- **Person-Centric API**: While the internal data is hierarchical (`Section -> Term -> Member`), the public API must be person-centric. Methods like `member.list_contacts()` must live on the `Member` object.
+- **Transparent Caching**: Tokens and Hierarchy data (`StartupData`) must be cached for the life of the client instance.
+
+---
+
+## Phase 1: Authentication & Hierarchy Discovery
+- **Authenticator**: Implement the `client_credentials` flow with token caching.
+- **Discovery**: Implement the `Startup` fetch to populate the internal `Section` and `Term` cache.
+- **Verification**: A "Smoke Test" that confirms credentials can successfully fetch the hierarchy.
+
+## Phase 3: The Public API Surface (Person-Centric)
+Implement the wrapper classes that provide the "Natural" API:
+- `OSMSection.list_terms()` / `OSMSection.current_term()`
+- `OSMTerm.list_members()` (Scoped to that term).
+- `OSMMember.list_contacts()` (Resolves the linkage table to return `List[Contact]`).
+- `OSMEvent.list_attendance()` (Scoped to that event).
+
+---
+
+## Communication Protocol
+- **Ambiguity = Question**: If any detail is missing, ASK.
+- **No Hallucinations**: Never guess a field name. If you haven't seen the JSON, you don't know the field.

osm_sdk-0.1.0.dev1/osm_sdk/__init__.py

@@ -0,0 +1,40 @@
+from .client import OSMClient
+from .errors import (
+    OSMAmbiguousMatchError,
+    OSMAPIError,
+    OSMAuthenticationError,
+    OSMDataError,
+    OSMError,
+    OSMNotFoundError,
+)
+from .models.attendance import OSMAttendance
+from .models.attendance_status import OSMAttendanceStatus
+from .models.contact import OSMContact
+from .models.contact_type import OSMContactType
+from .models.event import OSMEvent
+from .models.meeting import OSMMeeting
+from .models.member import OSMMember
+from .models.member_type import OSMMemberType
+from .models.section import OSMSection
+from .models.term import OSMTerm
+
+__all__ = [
+    "OSMClient",
+    "OSMAttendance",
+    "OSMContact",
+    "OSMContactType",
+    "OSMEvent",
+    "OSMMeeting",
+    "OSMMember",
+    "OSMMemberType",
+    "OSMSection",
+    "OSMTerm",
+    "OSMAttendanceStatus",
+    "OSMError",
+    "OSMAuthenticationError",
+    "OSMAPIError",
+    "OSMDataError",
+    "OSMNotFoundError",
+    "OSMAmbiguousMatchError",
+]
+

osm_sdk-0.1.0.dev1/osm_sdk/auth.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+import httpx
+
+from .errors import OSMAuthenticationError
+
+DEFAULT_TOKEN_URL = "https://www.onlinescoutmanager.co.uk/oauth/token"
+
+
+class Authenticator:
+    """OAuth2 client-credentials authenticator with in-memory token caching."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        scope: Optional[str] = None,
+        token_url: str = DEFAULT_TOKEN_URL,
+    ) -> None:
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._scope = scope
+        self._token_url = token_url
+        self._cached_token: Optional[str] = None
+        self._token_expires_at: Optional[datetime] = None
+
+    def get_access_token(self, http_client: httpx.Client) -> str:
+        if self._cached_token and self._token_is_valid():
+            return self._cached_token
+
+        payload = {"grant_type": "client_credentials"}
+        if self._scope:
+            payload["scope"] = self._scope
+        payload["client_id"] = self._client_id
+        payload["client_secret"] = self._client_secret
+
+        response = http_client.post(
+            self._token_url,
+            data=payload,
+            auth=(self._client_id, self._client_secret),
+            headers={"Accept": "application/json"},
+        )
+        if response.status_code < 200 or response.status_code >= 300:
+            raise OSMAuthenticationError(
+                f"OSM token request failed ({response.status_code}): {response.text}"
+            )
+
+        token_payload = response.json()
+        access_token = token_payload.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            raise OSMAuthenticationError(
+                "OSM token response did not include a valid 'access_token' field."
+            )
+
+        self._cached_token = access_token
+        self._token_expires_at = self._compute_expiry(token_payload.get("expires_in"))
+        return access_token
+
+    def _token_is_valid(self) -> bool:
+        if self._token_expires_at is None:
+            return True
+        return datetime.now(timezone.utc) < self._token_expires_at
+
+    @staticmethod
+    def _compute_expiry(expires_in: object) -> Optional[datetime]:
+        if not isinstance(expires_in, int):
+            return None
+        if expires_in <= 0:
+            return None
+        return datetime.now(timezone.utc) + timedelta(seconds=max(0, expires_in - 30))
+