refactor(api): retire GET/PUT /api/pages/:id/content (Issue #889 Phase 4)

[otomatty]

Phase 4 of #889 removes the legacy REST Y.Doc round-trip and the
API-side duplicate implementations now that all editing flows through
Hocuspocus.

• Delete GET/PUT /api/pages/:id/content route handlers (along with
  their lazy-migration / defense-in-depth normalization helpers).
• Delete duplicated server/api/src/services/snapshotService.ts and
  server/api/src/services/ydocWikiLinkNormalizer.ts; the prune helper
  used by snapshot restore is inlined into pageSnapshots.ts.
• Drop the cross-server drift detector ydocWikiLinkNormalizerSync.test.ts;
  Hocuspocus is now the sole owner of these implementations.
• Migrate NotePageView title persistence from
  getPageContent + putPageContent to the metadata-only
  updatePageMetadata (PUT /api/pages/:id); remove getPageContent /
  putPageContent from the API client and types.
• Refresh route / service / cache-key doc comments to reference the
  retained metadata route and the Hocuspocus normalization path.

https://claude.ai/code/session_018GADvyHXYY4Zem7Q7y8T6G

Summary by CodeRabbit

Release Notes

• Refactor

  • Consolidated page API endpoints for improved simplicity and consistency across the REST surface.
  • Removed legacy content synchronization route; real-time collaboration now handled exclusively through internal sync layer.
  • Simplified page metadata operations to a single update pathway.

• Documentation

  • Updated API documentation to reflect current endpoint structure and capabilities.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR retires the legacy REST Y.Doc sync endpoints (GET/PUT /api/pages/:id/content), consolidates Hocuspocus as the sole auto-snapshot and wiki-link normalization handler, removes the corresponding API-side services, standardizes the client API around metadata-only and public-content read paths, and migrates the NotePageView title-persistence flow to use the new updatePageMetadata endpoint.

Changes

Phase 4 Endpoint Retirement & Service Consolidation

Layer / File(s)	Summary
Remove API-side /content routes and services server/api/src/routes/pages.ts, server/api/src/routes/pageSnapshots.ts, server/api/src/__tests__/routes/pages.test.ts	The REST Y.Doc sync endpoints GET/PUT /api/pages/:id/content are removed from the pages route module. Snapshot auto-save service is deleted; snapshot-retention pruning logic is moved inline to the snapshots restore route. Test coverage is rewritten to drop /content assertions and validate metadata-only PUT /api/pages/:id, listing, creation, and public-content read routes. The pages route documentation is updated to reflect Hocuspocus ownership of Y.Doc state.
Delete snapshot and wiki-link normalizer services server/api/src/services/snapshotService.ts, server/api/src/services/ydocWikiLinkNormalizer.ts, server/api/src/__tests__/services/snapshotService.test.ts, server/api/src/__tests__/services/ydocWikiLinkNormalizer.test.ts	The maybeCreateSnapshot and pruneSnapshotsExceedingLimitSql exports and their test coverage are removed. The API-side applyWikiLinkMarksToYDoc function and its test coverage are removed, consolidating that responsibility to Hocuspocus.
Consolidate Hocuspocus as sole normalization handler server/hocuspocus/src/ydocWikiLinkNormalizer.ts, server/hocuspocus/src/ydocWikiLinkNormalizer.test.ts, server/hocuspocus/src/snapshotUtils.ts	Hocuspocus wiki-link normalizer docblock is updated to document it as the sole implementation after removing the API-side duplicate. The drift-detector test file is removed. Snapshot utilities documentation is updated to clarify that auto-snapshot creation is handled exclusively here after retiring /content routes and local mode. The test suite is renamed to reflect sole coverage responsibility.
Update client API types and methods src/lib/api/types.ts, src/lib/api/apiClient.ts	Legacy page-content types PageContentResponse and PutPageContentBody are removed. New UpdatePageMetadataBody and UpdatePageMetadataResponse type contracts are introduced for the metadata-only PUT /api/pages/:id endpoint, with updated_at as a required string in responses. Client methods getPageContent and putPageContent are deleted; PUT /api/pages/:id is documented as the canonical metadata-only REST entry point.
Update test mocks for removed client methods src/lib/api/apiClient.test.ts, src/lib/pageRepository/StorageAdapterPageRepository.test.ts, src/lib/sync/syncWithApi.test.ts, src/lib/ydocWikiLinkNormalizerSync.test.ts	Test fixtures and mocks remove stubs for the deleted getPageContent and putPageContent client methods. The drift-detector test file that asserted byte-equivalence between API and Hocuspocus wiki-link normalizers is removed entirely.
Migrate NotePageView to metadata-only title-save src/pages/NotePageView.tsx, src/pages/NotePageView.test.tsx	NotePageView title persistence now routes all changes through api.updatePageMetadata(page.id, { title: nextTitle }) instead of legacy getPageContent/putPageContent round-trips or useUpdatePage mutations. The useUpdatePage import and updatePageMutation variable are removed. Delete-success regression tests are reworked to verify pending/in-flight metadata saves are cancelled and in-flight failures do not produce destructive toasts. Title-save test assertions are updated to target updatePageMetadata for success/failure scenarios.
Update documentation across codebase server/api/src/routes/notes/crud.ts, server/api/src/services/pageGraphSyncService.ts, src/components/editor/TiptapEditor/useEditorLifecycle.ts	ETag-related comments are clarified to document that page-only edits (Hocuspocus saves, title renames, hard deletes) must invalidate the note's weak ETag. Graph-sync documentation is updated to state that only the Hocuspocus internal POST /api/internal/pages/:id/graph-sync trigger remains after retiring REST /content routes. Editor lifecycle comments remove references to client-side post-sync normalization, replacing them with references to server-side/Hocuspocus-only onLoadDocument normalization.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• otomatty/zedi#891: Both PRs modify NotePageView title-save and delete-success behavior, including regression tests for suppressing/cancelling pending in-flight saves after navigation.
• otomatty/zedi#888: Main PR builds directly on PR #888 by retiring the legacy /content endpoints that #888 was replacing with metadata-only and public-content routes.
• otomatty/zedi#887: Both PRs affect the wiki-link normalization implementation and pages route wiring; #887 adds server-side normalizer to legacy /content endpoints while main PR removes those endpoints and consolidates to Hocuspocus.

Poem

🐰 The rabbit hops, the paths align,
Y.Docs now sync in Hocuspocus's time,
Snapshots pile up in one steady place,
Wiki links marked with grace!
Old REST routes retire with a bound,
Metadata pure—cleaner ground!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically identifies the main change: retiring legacy REST endpoints for Y.Doc content (GET/PUT /api/pages/:id/content) and references the related issue and phase.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/issue-889-phase-4-DQQEB

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 17e57e5025

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve /api/pages/:id/content for MCP callers

Removing GET/PUT /api/pages/:id/content here breaks the in-repo MCP service, which still calls those routes in production code (server/mcp/src/client/httpClient.ts and server/mcp/src/tools/index.ts). After this commit, MCP tools like zedi_get_page and zedi_update_page_content will receive 404s against the updated API, so page read/update operations through MCP regress immediately unless the MCP client/tools are migrated in the same change.

Useful? React with 👍 / 👎.

[coderabbitai]

🧹 Nitpick comments (1)

server/api/src/services/pageGraphSyncService.ts (1)

13-18: ⚡ Quick win

Align remaining caller docs with the retired /content route statement.

Line 13 says internal HTTP is now the only trigger, but later in this file the syncPageGraphFromStoredYDoc doc still mentions the REST PUT /content path. Please update that stale line to keep the caller contract unambiguous.

Suggested doc-only patch

- * and by the REST PUT /content path (fire-and-forget).
+ * and by API-side fire-and-forget callers that schedule graph sync after persistence.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@server/api/src/services/pageGraphSyncService.ts` around lines 13 - 18, Update
the stale doc comment for syncPageGraphFromStoredYDoc to remove the reference to
the retired REST route `PUT /api/pages/:id/content` and instead state that the
function is invoked only via Hocuspocus internal HTTP after persistence; locate
the docblock above the syncPageGraphFromStoredYDoc function and replace the
sentence that mentions the REST `PUT /content` path so the caller contract
clearly reflects the current single trigger (Hocuspocus internal HTTP).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@server/api/src/services/pageGraphSyncService.ts`:
- Around line 13-18: Update the stale doc comment for
syncPageGraphFromStoredYDoc to remove the reference to the retired REST route
`PUT /api/pages/:id/content` and instead state that the function is invoked only
via Hocuspocus internal HTTP after persistence; locate the docblock above the
syncPageGraphFromStoredYDoc function and replace the sentence that mentions the
REST `PUT /content` path so the caller contract clearly reflects the current
single trigger (Hocuspocus internal HTTP).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a51bdd4f-80b8-4409-b6da-7dffd8cf3c6d

📥 Commits

Reviewing files that changed from the base of the PR and between 7885a59 and 17e57e5.

📒 Files selected for processing (22)

• server/api/src/__tests__/routes/notes/crud.test.ts
• server/api/src/__tests__/routes/pages.test.ts
• server/api/src/__tests__/services/snapshotService.test.ts
• server/api/src/__tests__/services/ydocWikiLinkNormalizer.test.ts
• server/api/src/routes/notes/crud.ts
• server/api/src/routes/pageSnapshots.ts
• server/api/src/routes/pages.ts
• server/api/src/services/pageGraphSyncService.ts
• server/api/src/services/snapshotService.ts
• server/api/src/services/ydocWikiLinkNormalizer.ts
• server/hocuspocus/src/snapshotUtils.ts
• server/hocuspocus/src/ydocWikiLinkNormalizer.test.ts
• server/hocuspocus/src/ydocWikiLinkNormalizer.ts
• src/components/editor/TiptapEditor/useEditorLifecycle.ts
• src/lib/api/apiClient.test.ts
• src/lib/api/apiClient.ts
• src/lib/api/types.ts
• src/lib/pageRepository/StorageAdapterPageRepository.test.ts
• src/lib/sync/syncWithApi.test.ts
• src/lib/ydocWikiLinkNormalizerSync.test.ts
• src/pages/NotePageView.test.tsx
• src/pages/NotePageView.tsx

💤 Files with no reviewable changes (8)

• src/lib/ydocWikiLinkNormalizerSync.test.ts
• server/api/src/tests/services/ydocWikiLinkNormalizer.test.ts
• server/api/src/services/ydocWikiLinkNormalizer.ts
• server/api/src/tests/services/snapshotService.test.ts
• server/api/src/services/snapshotService.ts
• src/lib/sync/syncWithApi.test.ts
• src/lib/api/types.ts
• src/lib/pageRepository/StorageAdapterPageRepository.test.ts

[gemini-code-assist]

Code Review

This pull request retires the 'local' collaboration mode by removing the legacy REST endpoints for Y.Doc content and consolidating metadata updates into the PUT /api/pages/:id endpoint. Content editing is now handled exclusively via Hocuspocus over WebSockets, allowing for the removal of duplicate auto-snapshotting and Y.Doc normalization logic from the API server. I have no feedback to provide.