iptvnator/docs/architecture/stalker-store-api-baseline.md

Stalker Store API Baseline

This is the compatibility baseline for refactoring libs/portal/stalker/data-access/src/lib/stalker.store.ts.

Goal: keep this public surface stable while splitting to feature stores.

Source of Truth

• Store implementation: libs/portal/stalker/data-access/src/lib/stalker.store.ts
• Baseline created on current branch state before feature-store extraction.

Public State Signals

Direct signal properties currently exposed by signalStore:

• selectedContentType: 'vod' | 'itv' | 'radio' | 'series'
• selectedCategoryId: string | null | undefined
• selectedVodId: string | undefined
• selectedSerialId: string | undefined
• selectedItvId: string | undefined
• page: number
• searchPhrase: string
• currentPlaylist: PlaylistMeta | undefined
• totalCount: number
• selectedItem: StalkerVodSource | null | undefined
• vodCategories: StalkerCategoryItem[]
• seriesCategories: StalkerCategoryItem[]
• itvCategories: StalkerCategoryItem[]
• radioCategories: StalkerCategoryItem[]
• hasMoreChannels: boolean
• itvChannels: StalkerItvChannel[]
• radioChannels: StalkerItvChannel[]
• vodSeriesSeasons: StalkerVodSeriesSeason[]
• vodSeriesEpisodes: StalkerVodSeriesEpisode[]
• selectedVodSeriesSeasonId: string | undefined

Public Computed Selectors

• getPaginatedContent: StalkerContentItem[]
• isPaginatedContentLoading: boolean
• isPaginatedContentFailed: unknown
• getSerialSeasonsResource: StalkerSeason[]
• isSerialSeasonsLoading: boolean
• getVodSeriesSeasonsResource: StalkerVodSeriesSeason[]
• isVodSeriesSeasonsLoading: boolean
• getCategoryResource: StalkerCategoryItem[]
• isCategoryResourceLoading: boolean
• isCategoryResourceFailed: unknown
• getSelectedCategoryLabel: StalkerCategoryLabel ({ name, labelKey }; render with stalkerCategoryLabelText() inside a computed that reads injectTranslationTick())

Exposed Resources/Props

These are currently reachable on the store object and used internally by computed selectors:

• getCategoryResource (computed selector with stable array output)
• categoryResource (internal resource)
• getContentResource (resource)
• serialSeasonsResource (resource)
• vodSeriesSeasonsResource (resource)

Removed:

• makeStalkerRequest(...) — deleted with the endpoint-discovery work. It was production-dead (no caller outside its own spec) and carried a fourth private copy of the portal-mode branch. Every Stalker request goes through executeStalkerRequest() (stores/utils/stalker-request.utils.ts), which owns mode routing plus the lazy portal repair; no facade alias is provided because reinstating one would reintroduce the drift the shared predicate exists to prevent.
• limit, setLimit(...) and getTotalPages — deleted with the catalog pagination removal (#1392, #1395). Catalogs now accumulate server-paged results into one deduplicated list, so hasMoreContent (accumulated length vs total_items) answers what getTotalPages used to, and no caller reads a page size: the portal decides how large a page is. No facade alias is provided, because a surviving limit would advertise a client-side window that the append path does not honour.
• getSelectedCategoryName — replaced by getSelectedCategoryLabel. The every-item genre the store adds (category_id: '*') has no portal name: it carries a labelKey that the caller translates, so the label follows a runtime language switch. No alias is provided, because a name-only selector is empty for that entry, and translating in the root store would keep the language the list was loaded in.

During refactor:

• Keep compatibility for external callers that may read these directly.
• If moved/renamed internally, provide facade aliases.

Public Methods (Compatibility Contract)

• setSelectedContentType(type: 'vod' | 'itv' | 'radio' | 'series'): void
• setSelectedCategory(id: string | number | null): void
• setSelectedSerialId(id: string): void
• setSelectedVodId(id: string): void
• setSelectedItvId(id: string): void
• setPage(page: number): void
• setCurrentPlaylist(playlist: PlaylistMeta | undefined): Promise<void>
• setSelectedItem(selectedItem: StalkerVodSource | null | undefined): void
• clearSelectedItem(): void
• setCategories(type: 'vod' | 'series' | 'itv' | 'radio', categories: StalkerCategoryItem[]): void
• resetCategories(): void Clears only; it starts no request (called on portal switches and route teardown).
• reloadCategories(): void Refetches the current portal's categories after a reset that keeps the owner.
• setItvChannels(channels: StalkerItvChannel[]): void
• setRadioChannels(channels: StalkerItvChannel[]): void
• setSearchPhrase(phrase: string): void
• fetchVodSeriesEpisodes(videoId: string, seasonId: string): Promise<StalkerVodSeriesEpisode[]>
• getSelectedCategory(): { id: string | number; name: string; type: 'vod' | 'itv' | 'radio' | 'series' } Backed by withComputed for compatibility, not by withMethods.
• fetchLinkToPlay(portalUrl: string, macAddress: string, cmd: string, series?: number): Promise<string>
• getExpireDate(): Promise<string>
• resolveItvPlayback(item: StalkerPortalItem): Promise<ResolvedPortalPlayback>
• resolveRadioPlayback(item: StalkerPortalItem): Promise<ResolvedPortalPlayback>
• addToFavorites(item: any, onDone?: () => void): void
• removeFromFavorites(favoriteId: string, onDone?: () => void): void
• fetchMovieFileId(movieId: string): Promise<string | null>
• createLinkToPlayVod(cmd?: string, title?: string, thumbnail?: string, episodeNum?: number, episodeId?: number, startTime?: number): Promise<void>
• addToRecentlyViewed(item: any): void
• removeFromRecentlyViewed(itemId: number, onComplete?: () => void): void
• fetchChannelEpg(channelId: number | string, size?: number): Promise<EpgItem[]>

Current Consumers (Observed)

Top observed store API usage in app code:

• currentPlaylist (16 references)
• setSelectedContentType (9)
• selectedItem (9)
• setSelectedItem (7)
• setSelectedCategory (6)
• createLinkToPlayVod (6)
• removeFromFavorites (5)
• setPage (4)
• addToFavorites (4)
• fetchChannelEpg (3)
• plus lower-frequency calls for paging/resources/series/recent.

Consumer directories sampled:

• libs/portal/stalker/**
• libs/portal/xtream/feature/**
• libs/portal/catalog/feature/**
• libs/ui/components/**

Invariants to Preserve During Refactor

• Selection IDs (selectedVodId, selectedItvId) are synchronized in setSelectedItem.
• selectedSerialId is set only when selectedContentType is series, and is cleared for every other content type. serialSeasonsResource fires a get_ordered_list&type=series portal request on each change of that id, and it is the only episode source for a series selection — while VOD-context shapes (embedded series[], Ministra is_series) resolve their episodes elsewhere, so carrying the id there only wastes a request. The gate must stay on content type alone: gating it on item shape would leave a series-section item that happens to carry is_series/series[] with an empty episode list.
• setSelectedCategory(...) resets page to 0.
• getPaginatedContent() and getCategoryResource() always return arrays, even when the underlying request fails.
• Radio stores stations separately in radioChannels and falls back to a synthetic all-radio category when a portal does not support radio category responses.
• Request failures must surface through isPaginatedContentFailed() and isCategoryResourceFailed() rather than resource reads that throw.
• createLinkToPlayVod(...) continues to:
  • support episode playback metadata
  • append recently viewed
  • preserve external player payload shape
• Full-portal auth path continues through StalkerSessionService.
• Non-auth/simple path continues through DataService.sendIpcEvent(STALKER_REQUEST, ...).
• Resource-driven loading signals preserve existing names.