prismcast 1.7.0 → 1.9.0

package/dist/config/services.d.ts

@@ -0,0 +1,202 @@
+import type { Channel, ChannelMap, ChannelSortField, ServiceGroup, SortDirection } from "../types/index.js";
+/**
+ * Gets the service tag for a channel key. For channels in a service group, reads the pre-computed tag from the group variant entry (computed at group-building
+ * time by buildServiceGroups). For standalone channels not in any group, derives the tag from the channel's URL domain. This function should not be called with
+ * :predefined synthetic keys — those only exist inside service groups and their tags are available via the group's variant entries.
+ * @param key - The channel key.
+ * @returns The service tag string.
+ */
+export declare function getServiceTagForChannel(key: string): string;
+/**
+ * Returns the auth domain for a channel key. Domain is the natural auth boundary — browser cookies and sessions scope to it. Multi-channel services work correctly
+ * because all their channels share one domain, and canonical channels work correctly because each has its own domain.
+ * @param key - The channel key.
+ * @returns The extracted domain from the channel's URL, or empty string if the channel or URL cannot be resolved.
+ */
+export declare function getAuthDomainForChannel(key: string): string;
+/**
+ * Returns all service tags for a channel (canonical tag + all variant suffix tags). Used to determine which services offer this channel.
+ * @param canonicalKey - The canonical channel key.
+ * @returns Array of service tag strings.
+ */
+export declare function getChannelServiceTags(canonicalKey: string): string[];
+/**
+ * Scans all service groups and collects unique service tags with display names. Display names are derived from the service field in DOMAIN_CONFIG entries that
+ * have a serviceTag.
+ * @returns Array of { displayName, domain, iconUrl, tag } objects sorted alphabetically by display name, with "direct" always first.
+ */
+export declare function getAllServiceTags(): {
+    displayName: string;
+    domain?: string;
+    iconUrl?: string;
+    tag: string;
+}[];
+/**
+ * Gets the current enabled service tags.
+ * @returns Copy of the enabled services array. Empty means no filter (all shown).
+ */
+export declare function getEnabledServices(): string[];
+/**
+ * Sets the enabled service tags. Empty array means "no filter" (all services shown).
+ * @param tags - The service tags to enable.
+ */
+export declare function setEnabledServices(tags: string[]): void;
+/**
+ * Checks if a service tag is currently enabled. Returns true if the tag is enabled, if no filter is active (empty set), or if the tag is "direct".
+ * @param tag - The service tag to check.
+ * @returns True if the service is available.
+ */
+export declare function isServiceTagEnabled(tag: string): boolean;
+/**
+ * Centralized availability check for the service filter. Returns true if the channel has at least one variant whose service tag is enabled.
+ * @param canonicalKey - The canonical channel key.
+ * @returns True if the channel passes the service filter.
+ */
+export declare function isChannelAvailableByService(canonicalKey: string): boolean;
+/**
+ * Builds service groups by scanning all channels and grouping by canonicalKey. Variant entries declare their canonical via the canonicalKey field (set by the
+ * flattener for predefined channels, by the browse modal for user channels, and by the one-time migration for pre-existing user entries). This is a single
+ * pass over the merged channel map — one field, one mechanism for both predefined and user-defined variant relationships.
+ *
+ * User overrides of predefined channels (same key, different object reference) produce a two-entry group with "Custom" and the original predefined version,
+ * even for single-service channels that don't have canonicalKey-based variants.
+ *
+ * After building groups, validates stored service selections against the new variant structure and reverts any stale selections to the canonical default. This
+ * catches all staleness sources in one place: service key renames across versions, variant removal in code, user-deleted custom variants, and reverted
+ * predefined overrides.
+ * @param channels - The merged channel map (predefined + user channels).
+ * @returns Canonical keys whose service selections were stale and reverted. Empty array if all selections are valid. The caller decides whether to persist.
+ */
+export declare function buildServiceGroups(channels: ChannelMap): string[];
+interface PredefinedChannelSummary {
+    canonicalKey: string;
+    name: string;
+    serviceCount: number;
+}
+/**
+ * Returns predefined channels whose canonical URL domain matches the given URL's domain. Used by the manual add form to show an inline hint when the user
+ * enters a URL that has predefined channels available. Returns an empty array when no predefined channels match.
+ * @param url - The URL to match against predefined channel domains.
+ * @returns Array of matching predefined channel summaries with canonical key, display name, and available service count.
+ */
+export declare function findPredefinedByDomain(url: string): PredefinedChannelSummary[];
+/**
+ * Returns the full domain-to-predefined-channel index for client-side embedding. Used by the channels panel to embed predefined match data so the manual add
+ * form can show inline hints without a server round-trip. The returned object is keyed by concise domain with arrays of channel summaries as values.
+ * @returns Record mapping domains to predefined channel summaries.
+ */
+export declare function getPredefinedDomainMap(): Record<string, PredefinedChannelSummary[]>;
+/**
+ * Resolves a URL to a friendly service display name. Checks built-in DOMAIN_CONFIG first for a stable, well-known service name, then falls back to
+ * getDomainConfig() which includes user domain mappings. This ordering prevents user domain overrides from corrupting display labels for predefined channel
+ * variants — a user mapping a built-in domain to a custom profile should not rename every service dropdown entry that uses that domain.
+ * @param url - The URL to resolve a service display name for.
+ * @returns The service display name, or the concise domain if no service name is configured.
+ */
+export declare function getServiceDisplayName(url: string): string;
+/**
+ * Resolves the service display label for a channel. Checks in order: explicit `service` field on the channel, the channel's explicit profile resolved via
+ * user domain mappings, then URL-based built-in display name. This ensures channels assigned to user-defined profiles show the profile's service name rather
+ * than the built-in name for the URL domain.
+ * @param channel - The channel to resolve a label for.
+ * @returns The service display label.
+ */
+export declare function getChannelServiceLabel(channel: Channel): string;
+export declare const VALID_SORT_FIELDS: Set<ChannelSortField>;
+/**
+ * Extracts a sortable string value from a channel for the specified sort field. Channel numbers are zero-padded to 6 digits for correct numeric ordering within a
+ * string comparison. Service values use the display label for human-meaningful sort order. This is the single source of truth for channel sort key extraction,
+ * shared by both the server-side table renderer and the M3U playlist generator.
+ * @param channel - Fallback channel definition, used only when the selected service variant cannot be resolved (e.g., key not in the merged channel map).
+ * @param key - The canonical channel key. Used for key-based sorting and to resolve the selected service variant internally.
+ * @param field - The sort field to extract.
+ * @returns A lowercase string suitable for comparison-based sorting.
+ */
+export declare function getChannelSortKey(channel: Channel, key: string, field: ChannelSortField): string;
+/**
+ * Compares two channels for sorting by the specified field and direction with a built-in channel name tiebreaker. The tiebreaker is always ascending so that rows
+ * within each group maintain a consistent alphabetical order regardless of the primary sort direction. This is the single comparator for all sort sites — server HTML
+ * render, client re-sort, and M3U playlist — to prevent ordering divergence.
+ * @param channelA - First channel definition.
+ * @param keyA - First channel key.
+ * @param channelB - Second channel definition.
+ * @param keyB - Second channel key.
+ * @param field - The sort field to compare.
+ * @param direction - Sort direction for the primary field.
+ * @returns A negative, zero, or positive number for sort ordering.
+ */
+export declare function compareChannelSort(channelA: Channel, keyA: string, channelB: Channel, keyB: string, field: ChannelSortField, direction: SortDirection): number;
+/**
+ * Gets the service group for a channel key. Works with both canonical and variant keys.
+ * @param key - Any channel key in the group.
+ * @returns The service group if the channel is part of a multi-service group, undefined otherwise.
+ */
+export declare function getServiceGroup(key: string): ServiceGroup | undefined;
+/**
+ * Checks if a channel key is a non-canonical service variant. Used to filter variants from channel listings.
+ * @param key - The channel key to check.
+ * @returns True if the key is a variant (not canonical) in a service group.
+ */
+export declare function isServiceVariant(key: string): boolean;
+/**
+ * Checks if a channel has multiple service options. Used to determine whether to show a service dropdown in the UI.
+ * @param key - The channel key to check.
+ * @returns True if the channel has more than one service variant.
+ */
+export declare function hasMultipleServices(key: string): boolean;
+/**
+ * Gets the canonical key for any channel key. For variant keys, returns the canonical key. For non-grouped or canonical keys, returns the input unchanged.
+ * Handles the PREDEFINED_SUFFIX used when a user has overridden a predefined channel.
+ * @param key - Any channel key.
+ * @returns The canonical key for the channel's service group, or the input key if not part of a group.
+ */
+export declare function getCanonicalKey(key: string): string;
+/**
+ * Sets the user's service selections. Called when loading from channels.json.
+ * @param selections - Service selections keyed by canonical channel key.
+ */
+export declare function setServiceSelections(selections: Record<string, string>): void;
+/**
+ * Gets all service selections.
+ * @returns Copy of the service selections object.
+ */
+export declare function getServiceSelections(): Record<string, string>;
+/**
+ * Gets the service selection for a specific channel.
+ * @param canonicalKey - The canonical channel key.
+ * @returns The selected service key, or undefined if using the default.
+ */
+export declare function getServiceSelection(canonicalKey: string): string | undefined;
+/**
+ * Sets the service selection for a channel.
+ * @param canonicalKey - The canonical channel key.
+ * @param serviceKey - The selected service key.
+ */
+export declare function setServiceSelection(canonicalKey: string, serviceKey: string): void;
+/**
+ * Resolves a canonical channel key to the actual channel key based on user selection. If the user has selected a specific service for this channel, returns that
+ * service's key. Otherwise returns the canonical key (default service). When the service filter is active, falls back to the first enabled variant if the stored
+ * selection's service is filtered out.
+ *
+ * This function is a pure resolver with no side effects. Stale selection cleanup is handled by buildServiceGroups(), which validates all stored selections
+ * against the rebuilt variant structure every time groups are rebuilt - both at startup and after runtime channel mutations.
+ * @param canonicalKey - The canonical channel key.
+ * @returns The resolved service key to use for streaming.
+ */
+export declare function resolveServiceKey(canonicalKey: string): string;
+/**
+ * Gets a channel with inheritance applied. For service variants, this merges the variant's properties with inherited properties from the canonical entry
+ * using the live channel data (which includes user overrides). Use `resolvePredefinedVariant()` when you need resolution against pure predefined data.
+ * @param key - The channel key (canonical or variant).
+ * @returns The complete channel with inheritance applied, or undefined if the channel doesn't exist.
+ */
+export declare function getResolvedChannel(key: string): Channel | undefined;
+/**
+ * Resolves a variant channel key against pure predefined data (ignoring user overrides). This is used for revert detection — when the user's edits match a
+ * variant's predefined definition, the custom override can be removed and the service selection switched to that variant. For canonical keys, returns the raw
+ * predefined channel. For variant keys, applies the same inheritance rules as `getResolvedChannel()` but against `PREDEFINED_CHANNELS` instead of `channelsRef`.
+ * @param key - The channel key (canonical or variant).
+ * @returns The channel with inheritance applied against predefined data, or undefined if the key has no predefined definition.
+ */
+export declare function resolvePredefinedVariant(key: string): Channel | undefined;
+export {};