feat(streams): add starter_pack user stream source with tag-aware IDs

[Orlandohub]

Summary

• fix [Task]: Starter Packs — starter_pack user stream source with tag-aware stream IDs #2386
• Adds the core stream plumbing for Starter Packs: a 4-part user stream ID format (source:all:all:tag1,tag2) so recommendations for an ordered tag list get their own Dexie cache row.
• Targets the live source=starter_pack directly: feat(api): starter pack stream, users by interest tags pubky-nexus#1024 is deployed on staging (verified 2026-08-21 — 200 with ordered comma-separated tags, 400 when tags is missing). An earlier revision of this PR shipped a temporary starter_pack_mock namespace behind a STARTER_PACK_SOURCE_LIVE flag; that machinery was removed in 57f2a7e once staging went live, which also made [Task]: Starter Packs — swap to live starter_pack source + E2E happy path #2390 (the swap issue) unnecessary.
• Unblocks the onboarding UI issues ([Feature]: Starter Packs — onboarding "Tags of interest" step #2387, [Feature]: Starter Packs — onboarding "Follow your best matches" step + Follow All & landing feed #2388), which consume buildStarterPackStreamId without touching service internals.

Changes

• buildStarterPackStreamId(tags) (model helper): canonicalizes labels (trim/lowercase) and validates the full tag contract (1–5 tags, 1–20 chars, no banned chars) via Err.validation; emits starter_pack:all:all:<tags>.
• createUserStreamParams: parses 4-part starter pack IDs, enforces all:all timeframe/reach segments, rejects noncanonical hand-built IDs; invalid-format fallthrough converted from raw Error to Err.validation.
• NexusUserStreamService.fetch: dispatches starter_pack → new userStreamApi.starterPack (source=starter_pack&tags=…); switch default is now a never-checked Err.validation.
• Config: STARTER_PACK_MAX_TAGS = 5 (Nexus contract) in src/config/nexus.ts.
• Types: StarterPackStreamId extends the UserStreamId union; STARTER_PACK enum member and TUserStreamStarterPackParams in the Nexus service types.

Test plan

• npm run typecheck — clean
• ESLint + Prettier on touched files — clean
• Helper suite: canonicalization, tag ordering, every rejection class (empty, over-limit, whitespace, overlength, delimiter-bearing, noncanonical)
• Parser suite: ordered tags param, all:all segment enforcement, invalid timeframe/reach/source/label cases with AppError category/code assertions
• Service suite: starter pack ID → source=starter_pack&tags=… via mocked queryNexus; endpoint count 10 → 11
• Application suite (fake-indexeddb): reversed tag orders persist as distinct Dexie rows
• Staging smoke: GET /v0/stream/users/ids?source=starter_pack&tags=bitcoin,art,music → 200 with user IDs; missing tags → 400

Notes

• One pre-existing test was updated: the old "4+ parts is invalid" case now asserts the starter-pack-specific rejection; a 5-part case covers the format fallthrough.

[greptile-apps]

Greptile Summary

Adds tag-aware starter-pack user stream identifiers, parsing, Nexus dispatch, and isolated Dexie cache keys while temporarily routing the feature through most_followed.

• Canonicalizes and validates ordered starter-pack tags.
• Supports live and temporary mock stream namespaces.
• Adds Nexus URL generation and service dispatch for starter-pack streams.
• Covers validation, dispatch, pagination parameters, and cache isolation with tests.

Confidence Score: 5/5

The PR appears safe to merge; no concrete blocking or independently actionable non-blocking issue was identified.

The builder, parser, Nexus dispatch, and local cache all preserve the full ordered stream identity, while the temporary mock behavior consistently and intentionally aliases every tag selection to most_followed.

Important Files Changed

Filename	Overview
src/config/nexus.ts	Adds the backend tag limit and temporary live-source feature flag with explicit mock-to-live cache isolation.
src/core/models/stream/user/userStream.helper.ts	Adds the canonical starter-pack stream-ID builder and validates tag count and labels.
src/core/models/stream/user/userStream.types.ts	Extends user stream identifiers with distinct live and mock starter-pack namespaces.
src/core/services/nexus/stream/users/userStream.utils.ts	Parses and validates four-part starter-pack IDs and produces source-specific Nexus parameters.
src/core/services/nexus/stream/users/userStream.ts	Dispatches live starter packs to the new endpoint and temporary mock streams to most_followed.
src/core/services/nexus/stream/users/userStream.api.ts	Adds URL construction for Nexus starter-pack requests.
src/core/application/stream/users/users.test.ts	Verifies tag-order and mock/live namespaces remain isolated in Dexie.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Tags["Ordered interest tags"] --> Builder["buildStarterPackStreamId"]
  Builder --> MockId["starter_pack_mock:all:all:tags"]
  Builder -. "when live flag flips" .-> LiveId["starter_pack:all:all:tags"]
  MockId --> Parser["createUserStreamParams"]
  LiveId --> Parser
  Parser --> MockApi["most_followed request<br/>without tags"]
  Parser --> LiveApi["starter_pack request<br/>with ordered tags"]
  MockApi --> Nexus["Nexus"]
  LiveApi --> Nexus
  Nexus --> Dexie["Dexie row keyed by full stream ID"]

Loading

_{Reviews (1): Last reviewed commit: "feat(streams): add starter_pack user str..." | Re-trigger Greptile}

[github-actions]

🚀 Preview Deployment

URL: https://pubky-app-pr-2391-fzxmjul7ya-oa.a.run.app

pubky-app-pr-2391 • 57f2a7e