mastodon-api phase 2: activitypub __client read routes, home timeline + notifications

[davidwkeith]

Package(s) affected

@dwk/activitypub, @dwk/mastodon-api

Scope

Phase 2 of the approved design in spec/mastodon-client-api.md (#327, PR #347). Deliverable: the conformance/pixelfed-qa.md step-4 like + reply are visible in a real client app — the read gap that motivated #327.

• @dwk/activitypub (all additive): internal-header-gated GET <actor>/__client/timeline and __client/notifications DO routes — seq-keyed cursor pagination (max_seq/since_seq/min_seq + limit), SQL filtering on object_type, read-time JSON classification for the notification split, rows with verify_state = 'failed' never served.
• @dwk/activitypub: extend __stats with followers/following/statuses counts (wires the live counts into phase 1's verify_credentials).
• @dwk/activitypub: createActivitypubMastodonApi adapter export composing createMastodonApi over the internal seam (forwardedConfig + internal headers, the createActivitypubMcpTools mechanism); adds the @dwk/activitypub → @dwk/mastodon-api workspace dependency (the createSolidPodWebdav precedent).
• @dwk/mastodon-api: MastodonBackend seam; snowflake IDs (received_at_ms << 16) | (source << 15) | (seq & 0x7FFF) (source bit reserved now — resolved; v1 mints inbox IDs only); RFC 8288 Link header pagination honoring limit/max_id/since_id/min_id.
• Entity mapping (pure, fixture-tested against captured AS2 from real Mastodon/Pixelfed/Lemmy traffic): Status from Create/Announce rows (attachments, spoiler_text/sensitive, in_reply_to_id); relayed_by rows serialized as reblogs-by-the-group (MCP-spec provenance MUST); Notification split (follow/favourite/reblog/mention); best-effort remote Account synthesis with bundled default avatar/header; allowlist HTML sanitizer at read time.
• GET /api/v1/timelines/home, GET /api/v1/notifications, GET /api/v1/statuses/:id, GET /api/v1/accounts/:id (owner + actors already present in stored activities only; no outbound fetches in the request path).
• Conformance: conformance/mastodon-client-qa.md runbook (Pixelfed app + Tusky matrix; web clients stretch); mastodon-client-api suite in conformance/status.json (targets pixelfed-app, tusky, pending); conformance-target mount for /api/ + /oauth/*; changesets.

Acceptance

Manual, against the deployed conformance target: home timeline renders (media, CW, alt text) and notifications show a real Pixelfed account's like + reply — closing pixelfed-qa step 4's indirect-evidence gap.

References

• Design: spec/mastodon-client-api.md · Tracking: Mastodon-compatible Client API subset for @dwk/activitypub (real client login: notifications, timelines) #327 · Design PR: docs(activitypub): design mastodon-compatible client api subset (#327) #347 · Depends on phase 1: mastodon-api phase 1: package scaffold, app OAuth flow, instance + verify_credentials (real client login) #348

[davidwkeith]

Implemented and merged in #357 (read surface: __client DO routes, MastodonBackend seam, snowflake IDs + Link pagination, entity mapping, /api/v1 timelines/notifications/statuses/accounts routes), with follow-up hardening in #364 and #370. Closing; the manual client QA (conformance/mastodon-client-qa.md) remains tracked by #327 and the conformance gate.