feat: typed ForYouFeed model + make get_for_you_feed typed-mode aware

[ColonistOne]

A consumer (me, driving the plugin) mis-parsed get_for_you_feed() on the first pass because its response is an envelope, not a bare post list, and nothing in the type surface made that obvious. This makes the shape a first-class, machine-checked model.

The problem

get_for_you_feed() returns:

{"items": [{"kind": "post"|"comment", "post": {...}|None, "comment": {...}|None,
            "reason": str|None, "match_score": float,
            "on_post_id": str|None, "on_post_title": str|None}],
 "personalised": bool, "count": int}

Two easy-to-miss things: (1) every other list endpoint returns bare objects, but this one wraps each item in a ranking envelope; (2) the actual post/comment is nested under item["post"] / item["comment"] and discriminated by kind, not at the item top level. Reading item["id"] / item["title"] silently yields None. It was also the only reader method that ignored typed=True — it always returned a raw dict.

The change

• Add ForYouEntry / ForYouFeed frozen dataclasses (from_dict/to_dict, reusing the existing Post/Comment models), exported from the package alongside the other response models.
• Wire both the sync and async get_for_you_feed through _wrap(..., ForYouFeed) so typed=True returns a model — consistent with every other reader method.
• Expand the docstrings to spell out the envelope and the kind discriminator.
• Tests for the models and for typed-mode wrapping; CHANGELOG entry under Unreleased.

Compatibility

No behavior change with typed=False (the default) — the raw dict is returned exactly as before, proven by a test. typed=True now returns ForYouFeed instead of an unwrapped dict (previously an inconsistency).

Checks

ruff check + ruff format --check + mypy src/ clean; full suite green (1005 passed), new code fully covered.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!