feat: object-oriented rewrite — typed models with ActiveRecord behaviour

README.md

@@ -13,24 +13,116 @@ You need a username and password from Spond
 
 ### Example code
 
-```
+```python
 import asyncio
 from spond import spond
 
 username = 'my@mail.invalid'
 password = 'Pa55worD'
-group_id = 'C9DC791FFE63D7914D6952BE10D97B46'  # fake 
+group_id = 'C9DC791FFE63D7914D6952BE10D97B46'  # fake
 
 async def main():
-    s = spond.Spond(username=username, password=password)
-    group = await s.get_group(group_id)
-    print(group['name'])
-    await s.clientsession.close()
+    async with spond.Spond(username=username, password=password) as s:
+        group = await s.get_group(group_id)
+        print(group.name)
+        for member in group.members:
+            print(f"  {member.full_name}")
+            for guardian in member.guardians:
+                print(f"    guardian: {guardian.full_name}")
 
 asyncio.run(main())
+```
+
+> **Typed objects from v2.0 onwards.** `get_groups()`, `get_event()`,
+> `get_posts()`, etc. now return typed `Group` / `Event` / `Post` objects
+> with attribute access and per-instance methods. Existing dict-style
+> access (`group["name"]`) still works with a `DeprecationWarning`
+> through the v2.x line; the shim is removed in v3.0. See
+> [`DESIGN-oo-rewrite.md`](DESIGN-oo-rewrite.md) for the full design and
+> migration story.
+
+### Working with the typed objects
+
+```python
+async with spond.Spond(username, password) as s:
+    # Read: typed instances with attribute access
+    event = await s.get_event(uid)
+    print(event.heading, event.start_time, event.duration)
+
+    # Convenience properties — synchronous, no HTTP
+    if event.is_upcoming and not event.has_responded(my_uid):
+        print("you haven't responded yet")
+
+    # Resolve response uids to typed Member/Guardian objects
+    for member in await event.accepted_members():
+        print(f"  ✓ {member.full_name}")
+
+    # Update via kwargs (returns a new instance)
+    new_event = await event.update(heading="Renamed")
+
+    # ActiveRecord-style write surface — same shape for Event and Post
+    # (requires: from spond.event import Event; from spond.post import Post)
+    new_event = Event(heading="My new event",
+                     start_time=start, end_time=end, type="EVENT",
+                     owners=[{"id": my_pid, "response": "accepted"}],
+                     recipients={"group": {"id": group_id}})
+    await new_event.save(client=s)   # POST → uid populated; cache updated
+    assert new_event.uid
+
+    new_event.description = "Some details"
+    await new_event.save()           # mutate-in-place, then re-save
+
+    await new_event.delete()         # DELETE → pruned from cache
+
+    # Posts work the same way, with `add_comment` as a bonus:
+    post = Post(uid="", type="PLAIN", group_uid=group_id,
+                title="Hello", body="Welcome.")
+    await post.save(client=s)
+    comment = await post.add_comment("First!")
+    assert comment.uid and comment.text == "First!"
+    await post.delete()
+```
+
+### Identity / equality
 
+Typed instances use natural-key equality so they behave correctly in
+sets and as dict keys:
+
+```python
+a = await s.get_event(uid)
+b = await s.get_event(uid)
+assert a == b                  # same uid → equal, even if state differs
+assert {a, b} == {a}           # dedups via __hash__
+
+# Match is a subclass of Event; same uid → same entity
+assert isinstance(match, Event)
+assert match == event_with_same_uid
 ```
 
+For callers who need the old field-by-field comparison (e.g. "has the
+server state changed?"), use `model_equals(other)`.
+
+### Exception hierarchy
+
+```python
+from spond import (
+    SpondError,             # base — catch this for any SDK error
+    AuthenticationError,    # login failures
+    EventNotFoundError,     # also a KeyError, for backward compat
+    GroupNotFoundError,     # also a KeyError
+    PersonNotFoundError,    # also a KeyError
+    SpondAPIError,          # HTTP failures; also a ValueError
+)
+
+try:
+    event = await s.get_event(uid)
+except EventNotFoundError:
+    ...
+```
+
+Pre-OO `except KeyError:` / `except ValueError:` patterns continue to
+work — the typed exceptions multi-inherit from the stdlib classes.
+
 ## Key methods
 
 ### get_groups()

pyproject.toml

@@ -10,6 +10,7 @@ repository = 'https://github.com/Olen/Spond'
 [tool.poetry.dependencies]
 python = ">=3.11"
 aiohttp = ">=3.8.5"
+pydantic = ">=2.0"
 
 [tool.poetry.group.dev.dependencies]
 # Constraint on `python` is required: pdoc's transitive `markdown2` declares

spond/__init__.py

@@ -6,27 +6,33 @@
 
 from typing import Any, TypeAlias
 
+# Re-export the public exception surface from the dedicated module so
+# `from spond import AuthenticationError` keeps working for pre-OO callers,
+# and `from spond import SpondError, EventNotFoundError, ...` works for
+# new callers using the typed-exception hierarchy.
+from .exceptions import (
+    AuthenticationError,
+    ChatNotFoundError,
+    EventNotFoundError,
+    GroupNotFoundError,
+    PersonNotFoundError,
+    SpondAPIError,
+    SpondError,
+    SpondNotFoundError,
+)
+
 JSONDict: TypeAlias = dict[str, Any]
 """Simple alias for type hinting `dict`s that can be passed to/from JSON-handling functions."""
 
 
-class AuthenticationError(Exception):
-    """Raised when login to the Spond API fails.
-
-    Typical causes:
-
-    - Incorrect username/password.
-    - 2FA enabled on the account (the library does not currently support
-      Spond's TOTP flow).
-    - The account has hit Spond's login rate limit (`outOfLoginAttempts`).
-    - The Spond login API has changed shape and the response no longer
-      contains an `accessToken`.
-
-    The exception message includes any of the response's whitelisted
-    diagnostic fields (`error`, `errorKey`, `errorCode`, `message`) so
-    most error cases are self-explanatory. Other response fields — such
-    as 2FA challenge tokens and (masked) `phoneNumber` — are intentionally
-    dropped from the message to avoid leaking them into application logs.
-    """
-
-    pass
+__all__ = [
+    "AuthenticationError",
+    "ChatNotFoundError",
+    "EventNotFoundError",
+    "GroupNotFoundError",
+    "JSONDict",
+    "PersonNotFoundError",
+    "SpondAPIError",
+    "SpondError",
+    "SpondNotFoundError",
+]