feat(communities): expose sync lifecycle state

[tomcasaburi]

Summary

• preserve the existing cached-data state semantics
• expose normalized community synchronization state and lifecycle timestamps
• document and test loading, retrying, success, failure, and cached-data behavior

Verification

• yarn build
• yarn type-check
• yarn lint (0 errors; existing warnings only)
• yarn test (1,123 passed, 6 skipped)
• focused community lifecycle tests and coverage

Closes #72

---

Note

Low Risk
Additive API and store fields with preserved state semantics; risk is mainly consumers misreading state vs syncState if they skip the docs.

Overview
useCommunity now returns syncState, hasCachedData, lastFetchAttemptAt, and lastSuccessfulFetchAt alongside the existing community fields. Cached-data state still stays succeeded when updatedAt is present, even during background refresh; syncState tracks the live fetch lifecycle (initializing → loading / retrying → succeeded / failed / stopped).

The communities store maintains per-community syncStatuses, updated from PKC updatingstatechange events (with waiting-retry mapped to retrying) and set to failed when addCommunityToStore throws. deleteCommunity clears sync status and errors for that key. Types add CommunitySyncState and extend UseCommunityResult.

README / llms-full.txt document the new fields and example usage; changelog entries for 0.1.29 / 0.1.30; tests cover the lifecycle, onlyIfCached, failures, and delete cleanup.

^{Reviewed by Cursor Bugbot for commit 02b0353. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Added synchronization status information to community data, including loading, retrying, success, failure, and stopped states.
  • Added indicators for cached data availability and timestamps for fetch attempts and successful fetches.

• Bug Fixes

  • Community synchronization failures are now reflected consistently.
  • Removed synchronization status when a community is deleted.

• Documentation

  • Updated usage guidance and examples for the expanded community data returned by useCommunity.
  • Added release documentation for version 0.1.30.

[coderabbitai]

📝 Walkthrough

Walkthrough

useCommunity now exposes per-community synchronization lifecycle, cache availability, and fetch timestamps. The store tracks these values across initialization, refresh, retry, success, failure, and deletion, while tests and documentation cover the expanded contract.

Changes

Community synchronization state

Layer / File(s)	Summary
Store synchronization tracking src/types.ts, src/stores/communities/communities-store.ts, src/stores/communities/communities-store.test.ts	Adds synchronization state types and per-community store metadata, updates lifecycle transitions and timestamps, removes status on deletion, and validates failure and client-state handling.
Hook result integration src/hooks/communities.ts, src/hooks/communities.test.ts	Exposes synchronization, cache, and timestamp fields from useCommunity, with tests covering lifecycle transitions, cached-only behavior, timestamps, and failures.
Public documentation updates README.md, llms-full.txt	Documents the expanded return contract, cached-data behavior, synchronization states, timestamps, usage example, and the 0.1.30 changelog header.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Community
  participant addCommunityToStore
  participant communitiesStore
  participant useCommunity
  Community->>addCommunityToStore: Emit update lifecycle events
  addCommunityToStore->>communitiesStore: Normalize and record sync status
  communitiesStore->>useCommunity: Provide sync status metadata
  useCommunity->>useCommunity: Return syncState, cache, and timestamps

Loading

Possibly related PRs

• bitsocialnet/bitsocial-react-hooks#49: Modifies the same community identification and store refresh paths.
• bitsocialnet/bitsocial-react-hooks#57: Modifies the communities store refresh and update flow.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR adds normalized sync state, cache flags, and timestamps, addressing the cached-data vs live-sync distinction in [#72].
Out of Scope Changes check	✅ Passed	The changed files stay focused on community sync state, docs, and tests; no clear unrelated code paths were added.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: exposing community sync lifecycle state.

✨ 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 feature/community-sync-lifecycle

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@src/stores/communities/communities-store.ts`:
- Around line 591-598: Update deleteCommunity’s setState cleanup to also remove
the deleted community’s entry from state.errors, alongside syncStatuses, and
return the cleaned errors map in the new state. Preserve the existing
communities and syncStatuses cleanup behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 74ec032d-b23e-479e-8671-1041ce079cb2

📥 Commits

Reviewing files that changed from the base of the PR and between 983ff33 and 898db2e.

📒 Files selected for processing (7)

• README.md
• llms-full.txt
• src/hooks/communities.test.ts
• src/hooks/communities.ts
• src/stores/communities/communities-store.test.ts
• src/stores/communities/communities-store.ts
• src/types.ts

[tomcasaburi]

Addressed the CodeRabbit finding in 02b0353: deleting a community now removes its stored errors together with its sync status, with a regression assertion. Reverified build, type-check, lint, the full 1,123-test suite, and full coverage (97.25% statements / 92.47% branches).