prismcast 1.6.0 → 1.8.0

package/dist/config/userChannels.d.ts

@@ -7,6 +7,14 @@ export type UserChannel = Channel;
  * Map of channel keys to stored channel data (full definitions or deltas). This is the raw file format for channels.json.
  */
 export type UserChannelMap = StoredChannelMap;
+/**
+ * Tag registry state persisted in channels.json alongside channel data. Tracks user-created tags and user-deleted predefined tags. The runtime tag vocabulary
+ * is computed as: (PREDEFINED_TAGS - deletedTags) + tags, sorted alphabetically.
+ */
+export interface TagRegistry {
+    deletedTags: string[];
+    tags: string[];
+}
 /**
  * Result of loading user channels from the file.
  */
@@ -15,6 +23,7 @@ export interface UserChannelsLoadResult {
     parseError: boolean;
     parseErrorMessage?: string;
     providerSelections: Record<string, string>;
+    tagRegistry: TagRegistry;
 }
 /**
  * Returns the path to the user channels file.
@@ -33,14 +42,16 @@ export declare function hasChannelsParseError(): boolean;
 export declare function getChannelsParseErrorMessage(): string | undefined;
 /**
  * Loads user channels from the channels file. Returns an empty map if the file doesn't exist, and sets parseError if the file exists but contains invalid JSON.
- * The file can contain a special `providerSelections` key with user's provider preferences, which is extracted separately from channels.
- * @returns The loaded channels with parse status and provider selections.
+ * The file can contain metadata keys (`providerSelections`, `tagRegistry`) which are extracted separately from channel data.
+ * @returns The loaded channels with parse status, provider selections, and tag registry.
  */
 export declare function loadUserChannels(): Promise<UserChannelsLoadResult>;
 /**
  * Saves user channels to the channels file and updates the in-memory cache. Changes take effect immediately for new stream requests without requiring a server
- * restart. Creates the data directory if it doesn't exist. Provider selections are also saved if any exist. Empty deltas (no overridden fields) for predefined
- * channel keys are stripped before saving to avoid storing no-op entries.
+ * restart. Creates the data directory if it doesn't exist. Metadata keys (provider selections, tag registry) are also saved if they have content. No-op deltas
+ * for predefined channel keys are normalized before saving: fields that match the predefined value or null-clear a field the predefined doesn't have are
+ * stripped. If the delta becomes empty after normalization, the entry is removed entirely. This ensures that any code path that writes deltas (inline edit,
+ * auto-number, browse modal, full edit) produces clean channels.json output without each handler needing to optimize its own delta.
  * @param channels - The channels to save (full definitions or delta overrides).
  * @throws If the file cannot be written.
  */
@@ -92,8 +103,8 @@ export declare function resolveStoredChannel(key: string, stored: StoredChannel)
  */
 export declare function getChannelListing(): ChannelListingEntry[];
 /**
- * Returns all available channels (predefined + user), with user channels taking precedence on key conflicts. Disabled predefined channels are excluded unless they
- * have a user override. Built on top of getChannelListing() to ensure a single merging code path.
+ * Returns all available channels (predefined + user), with user channels taking precedence on key conflicts. Disabled predefined channels are excluded. Built on
+ * top of getChannelListing() to ensure a single merging code path.
  * @returns The merged channel map with disabled predefined channels filtered out.
  */
 export declare function getAllChannels(): ChannelMap;
@@ -102,6 +113,44 @@ export declare function getAllChannels(): ChannelMap;
  * @returns The stored channel map.
  */
 export declare function getUserChannels(): StoredChannelMap;
+/**
+ * Returns the current tag registry state.
+ * @returns A copy of the tag registry with user-created tags and deleted predefined tags.
+ */
+export declare function getTagRegistry(): TagRegistry;
+/**
+ * Updates the tag registry state in memory. Call saveUserChannels() after to persist the change.
+ * @param registry - The new tag registry state.
+ */
+export declare function setTagRegistry(registry: TagRegistry): void;
+/**
+ * Returns the active tag vocabulary: predefined tags minus user-deleted tags, plus user-created tags, sorted alphabetically. This is the single source of truth
+ * for which tags are visible, assignable, and queryable throughout the system. Tags not in this list are invisible to the UI and rejected by the ?tag= query
+ * parameter, even if they exist on channel definitions (vocabulary-as-lens model).
+ * @returns Sorted array of active tag strings.
+ */
+export declare function getActiveTagVocabulary(): string[];
+/**
+ * Returns a channel's effective tags — the intersection of the channel's assigned tags with the active vocabulary. Tags that exist on the channel but are not in
+ * the active vocabulary are filtered out, ensuring only assignable and queryable tags are visible in the UI and playlist responses.
+ * @param channel - The channel to get effective tags for.
+ * @returns Sorted array of effective tag strings, or empty array if the channel has no tags or none are in the active vocabulary.
+ */
+export declare function getChannelEffectiveTags(channel: Channel): string[];
+/**
+ * Applies a tag transformation across channels and persists the result. This is the single source of truth for batch tag mutations — delete, rename, and bulk
+ * toggle all route through this function. The caller provides a filter (which channels to transform) and a transform (how to modify each channel's tags). This
+ * function handles loading stored channel data, applying the transform, and saving. Delta normalization in saveUserChannels() handles predefined channel
+ * delta computation automatically — callers do not need to reason about deltas vs. full definitions.
+ * @param filter - Predicate selecting which listing entries to transform. Receives each ChannelListingEntry from getChannelListing().
+ * @param transform - Pure function mapping a channel's current resolved tags to its new tags. Receives the channel's current tags array (may be empty, ordering
+ *   not guaranteed). Must return the desired tags array (may be empty to clear all tags). The returned array is sorted before storage.
+ * @returns Object with the affected channel keys and success status. On parse error, returns an error message and empty affected keys.
+ */
+export declare function transformChannelTags(filter: (entry: ChannelListingEntry) => boolean, transform: (tags: string[]) => string[]): Promise<{
+    affectedKeys: string[];
+    error?: string;
+}>;
 /**
  * Returns the predefined channel definition for a key.
  * @param key - The channel key to look up.
@@ -114,6 +163,44 @@ export declare function getPredefinedChannel(key: string): Channel | undefined;
  * @returns True if the channel is predefined.
  */
 export declare function isPredefinedChannel(key: string): boolean;
+/**
+ * Returns the East canonical key for a Pacific channel. Pacific canonicals are auto-generated by generatePacificDefinitions with a "p" suffix (e.g., "disneyp"
+ * from "disney"). When a Pacific canonical's logo or other brand-level metadata is unavailable, the East counterpart provides a fallback. Returns undefined
+ * when the key is not a Pacific canonical (doesn't end with "p" or the base key isn't predefined).
+ * @param key - The channel key to check.
+ * @returns The East canonical key if this is a Pacific channel, undefined otherwise.
+ */
+export declare function getEastCanonicalKey(key: string): string | undefined;
+/**
+ * Bulk-populates the logo cache from a stationId-to-URL map. Called by showInfo.ts after fetching logo data from the DVR. Existing entries are overwritten with
+ * fresh data to pick up any logo URL changes (e.g., network rebrands).
+ * @param logos - Map of Gracenote station ID to logo URL.
+ */
+export declare function setChannelLogos(logos: Map<string, string>): void;
+/**
+ * Sets a single logo cache entry. Called by showInfo.ts after a TMS station name search for a single channel (tier 2 population or channel add/edit).
+ * @param stationId - The Gracenote station ID.
+ * @param url - The logo URL.
+ */
+export declare function setChannelLogo(stationId: string, url: string): void;
+/**
+ * Clears the logo cache. Called on shutdown to release memory.
+ */
+export declare function clearChannelLogos(): void;
+/**
+ * Resolves a channel key to its effective Gracenote station ID. Pacific channels (e.g., "bravop") resolve to their east counterpart's station ID since
+ * they share the same brand logo. User channel overrides that change the stationId are reflected. Returns undefined if the channel has no stationId.
+ * @param channelKey - The channel key to resolve (e.g., "amc", "bravop").
+ * @returns The Gracenote station ID, or undefined.
+ */
+export declare function getChannelStationId(channelKey: string): string | undefined;
+/**
+ * Returns the logo URL for a channel from the cache. Pacific channels (e.g., "bravop") are resolved to their east counterpart automatically. The cache is
+ * populated by showInfo.ts from the Channels DVR API - this function only reads from it.
+ * @param channelKey - The channel key to look up (e.g., "amc", "bravop"). Pacific keys resolve to their east variant internally.
+ * @returns The logo URL if cached, undefined otherwise.
+ */
+export declare function getChannelLogo(channelKey: string): string | undefined;
 /**
  * Checks if a channel key exists in the user channels.
  * @param key - The channel key to check.
@@ -121,7 +208,8 @@ export declare function isPredefinedChannel(key: string): boolean;
  */
 export declare function isUserChannel(key: string): boolean;
 /**
- * Checks if a predefined channel is disabled.
+ * Checks if a predefined channel is disabled. The disabled state is determined solely by the disabledPredefined list in config — the user's explicit visibility
+ * intent. Property overrides (HDHR toggle, name change, tag edits) stored as deltas in channels.json are orthogonal and do not affect the enabled/disabled state.
  * @param key - The channel key to check.
  * @returns True if the channel is predefined and disabled.
  */
@@ -183,6 +271,14 @@ export declare function isChannelAvailable(key: string): boolean;
  * @returns Error message if invalid, undefined if valid.
  */
 export declare function validateChannelKey(key: string, isNew: boolean): string | undefined;
+/**
+ * Validates a channel number for range and uniqueness. Returns an error message if invalid, undefined if valid. Empty string means no channel number (valid).
+ * This is the single source of truth for channel number validation, shared by the full edit handler and the inline-edit handler.
+ * @param value - The channel number as a string (from form input or inline edit). Empty means "no number."
+ * @param excludeKey - The channel key being edited, excluded from the duplicate check.
+ * @returns Error message if invalid, undefined if valid.
+ */
+export declare function validateChannelNumber(value: string, excludeKey: string): string | undefined;
 /**
  * Validates a channel URL.
  * @param url - The URL to validate.
@@ -222,3 +318,8 @@ export declare function validateImportedChannels(data: unknown, validProfiles: s
  * @throws If the file cannot be written.
  */
 export declare function saveProviderSelections(): Promise<void>;
+/**
+ * Saves the current tag registry to the channels file. This triggers a full file save including all user channels.
+ * @throws If the file cannot be written.
+ */
+export declare function saveTagRegistry(): Promise<void>;