[adenarc]

Closes #451, part of NEARBuilders/nearbuilders.org#285

Adds a "Builders and projects" section to the public community page (/n/$slug), read from nearbuilders.org.

• The API builds the community path from the node and its parents (illinois/chicago, or illinois for a top-level one) and reads /v1/builders?cityNode= and /v1/projects?cityNode= server-side (new public getCommunityBuilders).
• Only items whose cityNode matches the path are kept. Production nearbuilders.org ignores the param today and returns everything, so this keeps the section on the empty state until feat: tag builders and projects with their citynode.app community nearbuilders.org#301 ships.
• If nearbuilders.org is down or slow (5s timeout), the section shows a quiet "couldn't load" note and the page still renders. Good results are cached for 2 minutes, the last good result is served for up to an hour during an outage, and failures back off for 30s.
• Shows up to 6 builders (name, avatar from their NEAR profile, account) and 6 projects (title, short description, logo), each linking to its nearbuilders.org page, plus "See all on NEAR Builders" when there are more. Empty state links to nearbuilders.org/join.
• Base URL is the nearbuildersUrl API variable, default https://nearbuilders.org.
• Strings in en/es/fr/zh. Read-only, no auth changes.

No changeset: main no longer has a .changeset folder.

Tested

• pnpm run typecheck, pnpm run lint, pnpm run test pass. New API integration tests (nested path, top-level path with the filter ignored, nearbuilders down, unknown node) and UI tests (list + links, empty state, down state), all with made-up data.

• Locally in the browser, with a stub of the two nearbuilders endpoints serving made-up builders/projects and three made-up communities in the dev DB: nested community list, empty state, nearbuilders-down state, signed out at desktop and 375px, and signed in. No console errors from this change.

• Against live nearbuilders.org (no stub): the API returns ok with no items in ~1s, and the page shows the empty state, signed out, no console errors.

• Review follow-ups: outage backoff (30s), shared in-flight request, stale fallback up to an hour, https-only logos, and no path when a community's parent chain is broken. All have unit tests.

Not tested

• Against a real nearbuilders.org with tags (fix(auth): swap wallet connector to gas-key-capable @hot-labs fork, drop fastnear patch #301 isn't deployed yet).
• "See all" goes to the full nearbuilders.org builders/projects list, since those pages don't filter by community yet.

Screenshots

[multi-review]

Multi Review · 8c627e2

Adds a public getCommunityBuilders endpoint. It builds the community path from the node's parent chain, fetches builders and projects from nearbuilders.org with a 5s timeout and a 2-minute cache of good results, and keeps only items tagged with that path. A new "Builders and projects" section on /n/$slug renders the result. The change is read-only and well contained: errors fall back to an "unavailable" state, logo URLs are limited to http(s), and the node lookup only exposes the same data as the already-public getNode. The one issue is low severity: failed fetches aren't cached.

1 issue(s)

What was checked (10 areas)

• getCommunityBuilders handler in api/src/index.ts and its use of nodes.getById (same data already public via getNode)
• communityPath loop: unknown node returns null, cycle guard and MAX_DEPTH, partial chain when a parent is missing
• createNearbuilders.forPath: cache hit/miss, error fallback to stale or unavailable, Effect.promise never rejects
• matchedPage total heuristic when the server ignores the filter and when it applies it, and how total is used in the UI (only for See all)
• request(): URL building, timeout, non-OK handling, pageSchema parse failure caught
• httpUrl sanitizing logoUrl; builder and project URLs built from the normalized baseUrl
• NearbuildersSection states (loading, error, unavailable, empty, list) and BuilderCard calling authClient.near.getProfile (same use as $accountId.tsx)
• SectionHeader props, useAuthClient and useApiClient exports, i18n keys
• nearbuildersUrl variable in the plugin config and bos.app.ts
• integration and UI tests against the implementation

Findings

• 🟡 Low api/src/services/nearbuilders.ts:175 No negative caching: while nearbuilders.org is down or slow, every community page view waits up to 5s and makes 2 new outbound requests
  forPath only caches successful loads. If nearbuilders.org hangs or returns errors, every getCommunityBuilders call (one per community page view and per client cache expiry) runs load() again. That means two fresh fetches that can each wait the full 5s AbortSignal.timeout before falling back to unavailable. Concurrent requests for the same path aren't merged either. During an outage the API keeps one request open for about 5s per page view and sends a steady stream of retries to the failing upstream, and users see the skeleton for 5s before the 'couldn't load' note.
  Suggested fix: Cache the unavailable result (or the stale fallback) for a short backoff window, e.g. 15–30s, and/or keep an in-flight promise per path so concurrent requests share one upstream call.

_{Comment @multi-review to re-review new commits, or @multi-review full for a full review.}