@churchapps/content-provider-helper 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -26,12 +26,12 @@ interface DeviceAuthorizationResponse {
     interval?: number;
 }
 interface DeviceFlowState {
-    status: 'loading' | 'awaiting_user' | 'polling' | 'success' | 'error' | 'expired';
+    status: "loading" | "awaiting_user" | "polling" | "success" | "error" | "expired";
     deviceAuth?: DeviceAuthorizationResponse;
     error?: string;
     pollCount?: number;
 }
-type AuthType = 'none' | 'oauth_pkce' | 'device_flow' | 'form_login';
+type AuthType = "none" | "oauth_pkce" | "device_flow" | "form_login";
 interface ProviderLogos {
     light: string;
     dark: string;
@@ -46,17 +46,18 @@ interface ProviderInfo {
     capabilities: ProviderCapabilities;
 }
 interface ContentFolder {
-    type: 'folder';
+    type: "folder";
     id: string;
     title: string;
     image?: string;
-    providerData?: Record<string, unknown>;
+    isLeaf?: boolean;
+    path: string;
 }
 interface ContentFile {
-    type: 'file';
+    type: "file";
     id: string;
     title: string;
-    mediaType: 'video' | 'image';
+    mediaType: "video" | "image";
     image?: string;
     url: string;
     embedUrl?: string;
@@ -64,7 +65,10 @@ interface ContentFile {
     decryptionKey?: string;
     mediaId?: string;
     pingbackUrl?: string;
-    providerData?: Record<string, unknown>;
+    seconds?: number;
+    loop?: boolean;
+    loopVideo?: boolean;
+    streamUrl?: string;
 }
 type ContentItem = ContentFolder | ContentFile;
 declare function isContentFolder(item: ContentItem): item is ContentFolder;
@@ -76,7 +80,7 @@ type DeviceFlowPollResult = ContentProviderAuthData | {
 interface PlanPresentation {
     id: string;
     name: string;
-    actionType: 'play' | 'add-on' | 'other';
+    actionType: "play" | "add-on" | "other";
     files: ContentFile[];
 }
 interface PlanSection {
@@ -154,32 +158,172 @@ interface ProviderCapabilities {
     presentations: boolean;
     playlist: boolean;
     instructions: boolean;
-    expandedInstructions: boolean;
     mediaLicensing: boolean;
 }
-type MediaLicenseStatus = 'valid' | 'expired' | 'not_licensed' | 'unknown';
+type MediaLicenseStatus = "valid" | "expired" | "not_licensed" | "unknown";
 interface MediaLicenseResult {
     mediaId: string;
     status: MediaLicenseStatus;
     message?: string;
     expiresAt?: string | number;
 }
+/**
+ * Core provider interface - all providers should implement this
+ */
+interface IProvider {
+    readonly id: string;
+    readonly name: string;
+    readonly logos: ProviderLogos;
+    readonly config: ContentProviderConfig;
+    readonly requiresAuth: boolean;
+    readonly capabilities: ProviderCapabilities;
+    readonly authTypes: AuthType[];
+    browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    getPresentations(path: string, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPlaylist?(path: string, auth?: ContentProviderAuthData | null, resolution?: number): Promise<ContentFile[] | null>;
+    getInstructions?(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
+    checkMediaLicense?(mediaId: string, auth?: ContentProviderAuthData | null): Promise<MediaLicenseResult | null>;
+}
+/**
+ * @deprecated Use IProvider instead. This interface will be removed in a future version.
+ */
+interface IContentProvider {
+    readonly id: string;
+    readonly name: string;
+    readonly logos: ProviderLogos;
+    readonly config: ContentProviderConfig;
+    browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    getPresentations(path: string, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPlaylist(path: string, auth?: ContentProviderAuthData | null, resolution?: number): Promise<ContentFile[] | null>;
+    getInstructions(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
+    requiresAuth(): boolean;
+    getCapabilities(): ProviderCapabilities;
+    checkMediaLicense(mediaId: string, auth?: ContentProviderAuthData | null): Promise<MediaLicenseResult | null>;
+}
+/**
+ * @deprecated Use auth helpers directly (OAuthHelper, DeviceFlowHelper, TokenHelper) with provider.config.
+ * This interface will be removed in a future version.
+ */
+interface IAuthProvider {
+    getAuthTypes(): AuthType[];
+    isAuthValid(auth: ContentProviderAuthData | null | undefined): boolean;
+    isTokenExpired(auth: ContentProviderAuthData): boolean;
+    refreshToken(auth: ContentProviderAuthData): Promise<ContentProviderAuthData | null>;
+    generateCodeVerifier(): string;
+    generateCodeChallenge(verifier: string): Promise<string>;
+    buildAuthUrl(codeVerifier: string, redirectUri: string, state?: string): Promise<{
+        url: string;
+        challengeMethod: string;
+    }>;
+    exchangeCodeForTokens(code: string, codeVerifier: string, redirectUri: string): Promise<ContentProviderAuthData | null>;
+    supportsDeviceFlow(): boolean;
+    initiateDeviceFlow(): Promise<DeviceAuthorizationResponse | null>;
+    pollDeviceFlowToken(deviceCode: string): Promise<DeviceFlowPollResult>;
+    calculatePollDelay(baseInterval?: number, slowDownCount?: number): number;
+}
+
+declare function detectMediaType(url: string, explicitType?: string): "video" | "image";
+declare function createFolder(id: string, title: string, path: string, image?: string, isLeaf?: boolean): ContentFolder;
+declare function createFile(id: string, title: string, url: string, options?: {
+    mediaType?: "video" | "image";
+    image?: string;
+    muxPlaybackId?: string;
+    seconds?: number;
+    loop?: boolean;
+    loopVideo?: boolean;
+    streamUrl?: string;
+}): ContentFile;
+
+/**
+ * Path parsing utilities for content providers.
+ * Paths follow the format: /segment1/segment2/segment3/...
+ * Example: /lessons/programId/studyId/lessonId/venueId
+ */
+interface ParsedPath {
+    segments: string[];
+    depth: number;
+}
+/**
+ * Parse a path string into segments and depth.
+ * @param path - The path to parse (e.g., "/lessons/abc123/def456")
+ * @returns Object with segments array and depth count
+ */
+declare function parsePath(path: string | null | undefined): ParsedPath;
+/**
+ * Get a specific segment from a path by index.
+ * @param path - The path to parse
+ * @param index - Zero-based index of the segment to retrieve
+ * @returns The segment at the given index, or null if not found
+ */
+declare function getSegment(path: string | null | undefined, index: number): string | null;
+/**
+ * Build a path string from segments.
+ * @param segments - Array of path segments
+ * @returns Path string with leading slash
+ */
+declare function buildPath(segments: string[]): string;
+/**
+ * Append a segment to an existing path.
+ * @param basePath - The base path
+ * @param segment - The segment to append
+ * @returns New path with segment appended
+ */
+declare function appendToPath(basePath: string | null | undefined, segment: string): string;
 
-declare function detectMediaType(url: string, explicitType?: string): 'video' | 'image';
+/**
+ * Navigate to a specific item using a dot-notation path.
+ * Path format: "0.2.1" means items[0].children[2].children[1]
+ */
+declare function navigateToPath(instructions: Instructions, path: string): InstructionItem | null;
+/**
+ * Generate a path string for an item given its position in the tree.
+ * Used when selecting an item to store its path.
+ */
+declare function generatePath(indices: number[]): string;
+
+interface DurationEstimationConfig {
+    secondsPerImage: number;
+    wordsPerMinute: number;
+}
+declare const DEFAULT_DURATION_CONFIG: DurationEstimationConfig;
+/**
+ * Count words in text (splits on whitespace)
+ */
+declare function countWords(text: string): number;
+/**
+ * Estimate duration for image content
+ * @returns Duration in seconds (default: 15)
+ */
+declare function estimateImageDuration(config?: Partial<DurationEstimationConfig>): number;
+/**
+ * Estimate duration for text content based on word count
+ * @param text - The text content
+ * @param config - Optional configuration overrides
+ * @returns Duration in seconds
+ */
+declare function estimateTextDuration(text: string, config?: Partial<DurationEstimationConfig>): number;
+/**
+ * Estimate duration based on media type
+ * @param mediaType - "video" | "image" | "text"
+ * @param options - Text content or word count for text estimation
+ * @returns Duration in seconds (0 for video/unknown)
+ */
+declare function estimateDuration(mediaType: "video" | "image" | "text", options?: {
+    text?: string;
+    wordCount?: number;
+    config?: Partial<DurationEstimationConfig>;
+}): number;
 
 declare function presentationsToPlaylist(plan: Plan): ContentFile[];
-declare function presentationsToInstructions(plan: Plan): Instructions;
 declare function presentationsToExpandedInstructions(plan: Plan): Instructions;
 declare function instructionsToPlaylist(instructions: Instructions): ContentFile[];
 declare const expandedInstructionsToPlaylist: typeof instructionsToPlaylist;
 declare function instructionsToPresentations(instructions: Instructions, planId?: string): Plan;
 declare const expandedInstructionsToPresentations: typeof instructionsToPresentations;
-declare function collapseInstructions(instructions: Instructions, maxDepth?: number): Instructions;
 declare function playlistToPresentations(files: ContentFile[], planName?: string, sectionName?: string): Plan;
 declare function playlistToInstructions(files: ContentFile[], venueName?: string): Instructions;
 declare const playlistToExpandedInstructions: typeof playlistToInstructions;
 
-declare const FormatConverters_collapseInstructions: typeof collapseInstructions;
 declare const FormatConverters_expandedInstructionsToPlaylist: typeof expandedInstructionsToPlaylist;
 declare const FormatConverters_expandedInstructionsToPresentations: typeof expandedInstructionsToPresentations;
 declare const FormatConverters_instructionsToPlaylist: typeof instructionsToPlaylist;
@@ -188,28 +332,96 @@ declare const FormatConverters_playlistToExpandedInstructions: typeof playlistTo
 declare const FormatConverters_playlistToInstructions: typeof playlistToInstructions;
 declare const FormatConverters_playlistToPresentations: typeof playlistToPresentations;
 declare const FormatConverters_presentationsToExpandedInstructions: typeof presentationsToExpandedInstructions;
-declare const FormatConverters_presentationsToInstructions: typeof presentationsToInstructions;
 declare const FormatConverters_presentationsToPlaylist: typeof presentationsToPlaylist;
 declare namespace FormatConverters {
-  export { FormatConverters_collapseInstructions as collapseInstructions, FormatConverters_expandedInstructionsToPlaylist as expandedInstructionsToPlaylist, FormatConverters_expandedInstructionsToPresentations as expandedInstructionsToPresentations, FormatConverters_instructionsToPlaylist as instructionsToPlaylist, FormatConverters_instructionsToPresentations as instructionsToPresentations, FormatConverters_playlistToExpandedInstructions as playlistToExpandedInstructions, FormatConverters_playlistToInstructions as playlistToInstructions, FormatConverters_playlistToPresentations as playlistToPresentations, FormatConverters_presentationsToExpandedInstructions as presentationsToExpandedInstructions, FormatConverters_presentationsToInstructions as presentationsToInstructions, FormatConverters_presentationsToPlaylist as presentationsToPlaylist };
+  export { FormatConverters_expandedInstructionsToPlaylist as expandedInstructionsToPlaylist, FormatConverters_expandedInstructionsToPresentations as expandedInstructionsToPresentations, FormatConverters_instructionsToPlaylist as instructionsToPlaylist, FormatConverters_instructionsToPresentations as instructionsToPresentations, FormatConverters_playlistToExpandedInstructions as playlistToExpandedInstructions, FormatConverters_playlistToInstructions as playlistToInstructions, FormatConverters_playlistToPresentations as playlistToPresentations, FormatConverters_presentationsToExpandedInstructions as presentationsToExpandedInstructions, FormatConverters_presentationsToPlaylist as presentationsToPlaylist };
 }
 
-declare abstract class ContentProvider {
+interface FormatResolverOptions {
+    allowLossy?: boolean;
+}
+interface ResolvedFormatMeta {
+    isNative: boolean;
+    sourceFormat?: "playlist" | "presentations" | "instructions";
+    isLossy: boolean;
+}
+declare class FormatResolver {
+    private provider;
+    private options;
+    constructor(provider: IProvider, options?: FormatResolverOptions);
+    getProvider(): IProvider;
+    /** Extract the last segment from a path to use as fallback ID/title */
+    private getIdFromPath;
+    getPlaylist(path: string, auth?: ContentProviderAuthData | null): Promise<ContentFile[] | null>;
+    getPlaylistWithMeta(path: string, auth?: ContentProviderAuthData | null): Promise<{
+        data: ContentFile[] | null;
+        meta: ResolvedFormatMeta;
+    }>;
+    getPresentations(path: string, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPresentationsWithMeta(path: string, auth?: ContentProviderAuthData | null): Promise<{
+        data: Plan | null;
+        meta: ResolvedFormatMeta;
+    }>;
+    getInstructions(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
+    getInstructionsWithMeta(path: string, auth?: ContentProviderAuthData | null): Promise<{
+        data: Instructions | null;
+        meta: ResolvedFormatMeta;
+    }>;
+}
+
+declare class OAuthHelper {
+    generateCodeVerifier(): string;
+    generateCodeChallenge(verifier: string): Promise<string>;
+    buildAuthUrl(config: ContentProviderConfig, codeVerifier: string, redirectUri: string, state?: string): Promise<{
+        url: string;
+        challengeMethod: string;
+    }>;
+    exchangeCodeForTokens(config: ContentProviderConfig, providerId: string, code: string, codeVerifier: string, redirectUri: string): Promise<ContentProviderAuthData | null>;
+}
+
+declare class TokenHelper {
+    isAuthValid(auth: ContentProviderAuthData | null | undefined): boolean;
+    isTokenExpired(auth: ContentProviderAuthData): boolean;
+    refreshToken(config: ContentProviderConfig, auth: ContentProviderAuthData): Promise<ContentProviderAuthData | null>;
+}
+
+declare class DeviceFlowHelper {
+    supportsDeviceFlow(config: ContentProviderConfig): boolean;
+    initiateDeviceFlow(config: ContentProviderConfig): Promise<DeviceAuthorizationResponse | null>;
+    pollDeviceFlowToken(config: ContentProviderConfig, deviceCode: string): Promise<DeviceFlowPollResult>;
+    calculatePollDelay(baseInterval?: number, slowDownCount?: number): number;
+}
+
+declare class ApiHelper {
+    createAuthHeaders(auth: ContentProviderAuthData | null | undefined): Record<string, string> | null;
+    apiRequest<T>(config: ContentProviderConfig, _providerId: string, path: string, auth?: ContentProviderAuthData | null, method?: "GET" | "POST", body?: unknown): Promise<T | null>;
+}
+
+/**
+ * @deprecated Use IProvider interface instead. Providers should implement IProvider directly
+ * and use helper classes (OAuthHelper, TokenHelper, DeviceFlowHelper, ApiHelper) via composition.
+ * This class will be removed in a future version.
+ */
+declare abstract class ContentProvider implements IContentProvider, IAuthProvider {
     abstract readonly id: string;
     abstract readonly name: string;
     abstract readonly logos: ProviderLogos;
     abstract readonly config: ContentProviderConfig;
-    abstract browse(folder?: ContentFolder | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
-    abstract getPresentations(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
-    getPlaylist(folder: ContentFolder, auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
-    getInstructions(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    getExpandedInstructions(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
+    protected readonly oauthHelper: OAuthHelper;
+    protected readonly tokenHelper: TokenHelper;
+    protected readonly deviceFlowHelper: DeviceFlowHelper;
+    protected readonly apiHelper: ApiHelper;
+    abstract browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    abstract getPresentations(path: string, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPlaylist(path: string, auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
+    getInstructions(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
     requiresAuth(): boolean;
     getCapabilities(): ProviderCapabilities;
     checkMediaLicense(_mediaId: string, _auth?: ContentProviderAuthData | null): Promise<MediaLicenseResult | null>;
     getAuthTypes(): AuthType[];
     isAuthValid(auth: ContentProviderAuthData | null | undefined): boolean;
     isTokenExpired(auth: ContentProviderAuthData): boolean;
+    refreshToken(auth: ContentProviderAuthData): Promise<ContentProviderAuthData | null>;
     generateCodeVerifier(): string;
     generateCodeChallenge(verifier: string): Promise<string>;
     buildAuthUrl(codeVerifier: string, redirectUri: string, state?: string): Promise<{
@@ -217,174 +429,252 @@ declare abstract class ContentProvider {
         challengeMethod: string;
     }>;
     exchangeCodeForTokens(code: string, codeVerifier: string, redirectUri: string): Promise<ContentProviderAuthData | null>;
-    refreshToken(auth: ContentProviderAuthData): Promise<ContentProviderAuthData | null>;
     supportsDeviceFlow(): boolean;
     initiateDeviceFlow(): Promise<DeviceAuthorizationResponse | null>;
     pollDeviceFlowToken(deviceCode: string): Promise<DeviceFlowPollResult>;
     calculatePollDelay(baseInterval?: number, slowDownCount?: number): number;
     protected createAuthHeaders(auth: ContentProviderAuthData | null | undefined): Record<string, string> | null;
-    protected apiRequest<T>(path: string, auth?: ContentProviderAuthData | null, method?: 'GET' | 'POST', body?: unknown): Promise<T | null>;
-    protected createFolder(id: string, title: string, image?: string, providerData?: Record<string, unknown>): ContentFolder;
+    protected apiRequest<T>(path: string, auth?: ContentProviderAuthData | null, method?: "GET" | "POST", body?: unknown): Promise<T | null>;
+    protected createFolder(id: string, title: string, path: string, image?: string, isLeaf?: boolean): ContentFolder;
     protected createFile(id: string, title: string, url: string, options?: {
-        mediaType?: 'video' | 'image';
+        mediaType?: "video" | "image";
         image?: string;
         muxPlaybackId?: string;
-        providerData?: Record<string, unknown>;
+        seconds?: number;
+        loop?: boolean;
+        loopVideo?: boolean;
+        streamUrl?: string;
     }): ContentFile;
 }
 
-interface FormatResolverOptions {
-    allowLossy?: boolean;
-}
-interface ResolvedFormatMeta {
-    isNative: boolean;
-    sourceFormat?: 'playlist' | 'presentations' | 'instructions' | 'expandedInstructions';
-    isLossy: boolean;
-}
-declare class FormatResolver {
-    private provider;
-    private options;
-    constructor(provider: ContentProvider, options?: FormatResolverOptions);
-    getProvider(): ContentProvider;
-    getPlaylist(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<ContentFile[] | null>;
-    getPlaylistWithMeta(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<{
-        data: ContentFile[] | null;
-        meta: ResolvedFormatMeta;
-    }>;
-    getPresentations(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
-    getPresentationsWithMeta(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<{
-        data: Plan | null;
-        meta: ResolvedFormatMeta;
-    }>;
-    getInstructions(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    getInstructionsWithMeta(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<{
-        data: Instructions | null;
-        meta: ResolvedFormatMeta;
-    }>;
-    getExpandedInstructions(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    getExpandedInstructionsWithMeta(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<{
-        data: Instructions | null;
-        meta: ResolvedFormatMeta;
-    }>;
-}
-
-declare class APlayProvider extends ContentProvider {
+/**
+ * APlay Provider
+ *
+ * Path structure (variable depth based on module products):
+ *   /modules                                              -> list modules
+ *   /modules/{moduleId}                                   -> list products OR libraries (depends on module)
+ *   /modules/{moduleId}/products/{productId}              -> list libraries (if module has multiple products)
+ *   /modules/{moduleId}/products/{productId}/{libraryId}  -> media files
+ *   /modules/{moduleId}/libraries/{libraryId}             -> media files (if module has 0-1 products)
+ */
+declare class APlayProvider implements IProvider {
+    private readonly apiHelper;
+    private apiRequest;
     readonly id = "aplay";
     readonly name = "APlay";
     readonly logos: ProviderLogos;
     readonly config: ContentProviderConfig;
-    getCapabilities(): ProviderCapabilities;
-    browse(folder?: ContentFolder | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
-    private getProductFolders;
+    readonly requiresAuth = true;
+    readonly authTypes: AuthType[];
+    readonly capabilities: ProviderCapabilities;
+    browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    private getModules;
+    private getModuleContent;
     private getLibraryFolders;
     private getMediaFiles;
-    getPresentations(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPresentations(path: string, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPlaylist(path: string, auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
+    getInstructions(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
     checkMediaLicense(mediaId: string, auth?: ContentProviderAuthData | null): Promise<MediaLicenseResult | null>;
 }
 
-declare class SignPresenterProvider extends ContentProvider {
+/**
+ * SignPresenter Provider
+ *
+ * Path structure:
+ *   /playlists                    -> list playlists
+ *   /playlists/{playlistId}       -> list messages (files)
+ */
+declare class SignPresenterProvider implements IProvider {
+    private readonly apiHelper;
+    private apiRequest;
     readonly id = "signpresenter";
     readonly name = "SignPresenter";
     readonly logos: ProviderLogos;
     readonly config: ContentProviderConfig;
-    getCapabilities(): ProviderCapabilities;
-    browse(folder?: ContentFolder | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    readonly requiresAuth = true;
+    readonly authTypes: AuthType[];
+    readonly capabilities: ProviderCapabilities;
+    browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    private getPlaylists;
     private getMessages;
-    getPresentations(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPresentations(path: string, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPlaylist(path: string, auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
+    getInstructions(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
 }
 
-declare class LessonsChurchProvider extends ContentProvider {
+/**
+ * LessonsChurch Provider
+ *
+ * Path structure:
+ *   /lessons                                            -> programs
+ *   /lessons/{programId}                                -> studies
+ *   /lessons/{programId}/{studyId}                      -> lessons
+ *   /lessons/{programId}/{studyId}/{lessonId}           -> venues
+ *   /lessons/{programId}/{studyId}/{lessonId}/{venueId} -> playlist files
+ *
+ *   /addons                                             -> categories
+ *   /addons/{category}                                  -> add-on files
+ */
+declare class LessonsChurchProvider implements IProvider {
     readonly id = "lessonschurch";
     readonly name = "Lessons.church";
     readonly logos: ProviderLogos;
     readonly config: ContentProviderConfig;
-    requiresAuth(): boolean;
-    getCapabilities(): ProviderCapabilities;
-    getPlaylist(folder: ContentFolder, _auth?: ContentProviderAuthData | null, resolution?: number): Promise<ContentFile[] | null>;
-    protected apiRequest<T>(path: string): Promise<T | null>;
-    browse(folder?: ContentFolder | null, _auth?: ContentProviderAuthData | null, resolution?: number): Promise<ContentItem[]>;
+    readonly requiresAuth = false;
+    readonly authTypes: AuthType[];
+    readonly capabilities: ProviderCapabilities;
+    getPlaylist(path: string, _auth?: ContentProviderAuthData | null, resolution?: number): Promise<ContentFile[] | null>;
+    private apiRequest;
+    browse(path?: string | null, _auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    private browseLessons;
     private getPrograms;
     private getStudies;
     private getLessons;
     private getVenues;
     private getPlaylistFiles;
+    private browseAddOns;
     private getAddOnCategories;
     private getAddOnsByCategory;
     private convertAddOnToFile;
-    getPresentations(folder: ContentFolder, _auth?: ContentProviderAuthData | null, resolution?: number): Promise<Plan | null>;
-    getInstructions(folder: ContentFolder, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    getExpandedInstructions(folder: ContentFolder, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
+    getPresentations(path: string, _auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getInstructions(path: string, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
+    private normalizeItemType;
     private getEmbedUrl;
     private convertVenueToPlan;
 }
 
-declare class B1ChurchProvider extends ContentProvider {
+declare class B1ChurchProvider implements IProvider {
+    private readonly apiHelper;
+    private apiRequest;
     readonly id = "b1church";
     readonly name = "B1.Church";
     readonly logos: ProviderLogos;
     readonly config: ContentProviderConfig;
     private appBase;
-    requiresAuth(): boolean;
-    getCapabilities(): ProviderCapabilities;
-    buildAuthUrl(_codeVerifier: string, redirectUri: string, state?: string): Promise<{
+    readonly requiresAuth = true;
+    readonly authTypes: AuthType[];
+    readonly capabilities: ProviderCapabilities;
+    buildAuthUrl(codeVerifier: string, redirectUri: string, state?: string): Promise<{
         url: string;
         challengeMethod: string;
     }>;
+    exchangeCodeForTokensWithPKCE(code: string, redirectUri: string, codeVerifier: string): Promise<ContentProviderAuthData | null>;
     exchangeCodeForTokensWithSecret(code: string, redirectUri: string, clientSecret: string): Promise<ContentProviderAuthData | null>;
     refreshTokenWithSecret(authData: ContentProviderAuthData, clientSecret: string): Promise<ContentProviderAuthData | null>;
     initiateDeviceFlow(): Promise<DeviceAuthorizationResponse | null>;
     pollDeviceFlowToken(deviceCode: string): Promise<DeviceFlowPollResult>;
-    browse(folder?: ContentFolder | null, authData?: ContentProviderAuthData | null): Promise<ContentItem[]>;
-    getPresentations(folder: ContentFolder, authData?: ContentProviderAuthData | null): Promise<Plan | null>;
-    getInstructions(folder: ContentFolder, authData?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    getPlaylist(folder: ContentFolder, authData?: ContentProviderAuthData | null): Promise<ContentFile[]>;
+    browse(path?: string | null, authData?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    getPresentations(path: string, authData?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getInstructions(path: string, authData?: ContentProviderAuthData | null): Promise<Instructions | null>;
+    private processInstructionItems;
+    private findItemByPath;
+    private findPresentationByPath;
+    getPlaylist(path: string, authData?: ContentProviderAuthData | null, resolution?: number): Promise<ContentFile[] | null>;
 }
 
-declare class PlanningCenterProvider extends ContentProvider {
+/**
+ * PlanningCenter Provider
+ *
+ * Path structure:
+ *   /serviceTypes                            -> list service types
+ *   /serviceTypes/{serviceTypeId}            -> list plans
+ *   /serviceTypes/{serviceTypeId}/{planId}   -> plan items (leaf)
+ */
+declare class PlanningCenterProvider implements IProvider {
+    private readonly apiHelper;
+    private apiRequest;
     readonly id = "planningcenter";
     readonly name = "Planning Center";
     readonly logos: ProviderLogos;
     readonly config: ContentProviderConfig;
     private readonly ONE_WEEK_MS;
-    requiresAuth(): boolean;
-    getCapabilities(): ProviderCapabilities;
-    browse(folder?: ContentFolder | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    readonly requiresAuth = true;
+    readonly authTypes: AuthType[];
+    readonly capabilities: ProviderCapabilities;
+    browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    private getServiceTypes;
     private getPlans;
     private getPlanItems;
-    getPresentations(folder: ContentFolder, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPresentations(path: string, auth?: ContentProviderAuthData | null): Promise<Plan | null>;
     private convertToPresentation;
     private convertSongToPresentation;
     private convertMediaToPresentation;
     private formatDate;
+    getPlaylist(path: string, auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
+    getInstructions(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
 }
 
-declare class BibleProjectProvider extends ContentProvider {
+/**
+ * BibleProject Provider
+ *
+ * Path structure:
+ *   /                              -> list collections
+ *   /{collectionSlug}              -> list videos in collection
+ *   /{collectionSlug}/{videoId}    -> single video
+ */
+declare class BibleProjectProvider implements IProvider {
     readonly id = "bibleproject";
     readonly name = "The Bible Project";
     readonly logos: ProviderLogos;
     readonly config: ContentProviderConfig;
     private data;
-    requiresAuth(): boolean;
-    getCapabilities(): ProviderCapabilities;
-    browse(folder?: ContentFolder | null, _auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
-    getPresentations(folder: ContentFolder, _auth?: ContentProviderAuthData | null): Promise<Plan | null>;
-    getPlaylist(folder: ContentFolder, _auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
+    readonly requiresAuth = false;
+    readonly authTypes: AuthType[];
+    readonly capabilities: ProviderCapabilities;
+    browse(path?: string | null, _auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    private getCollections;
+    private getLessonFolders;
+    private getVideoFile;
+    getPresentations(path: string, _auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPlaylist(path: string, _auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
+    getInstructions(path: string, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
+    private slugify;
+}
+
+/**
+ * HighVoltageKids Provider
+ *
+ * Path structure:
+ *   /                                          -> list collections (Elementary, Preschool)
+ *   /{collectionSlug}                          -> list studies
+ *   /{collectionSlug}/{studyId}                -> list lessons
+ *   /{collectionSlug}/{studyId}/{lessonId}     -> lesson files (leaf)
+ */
+declare class HighVoltageKidsProvider implements IProvider {
+    readonly id = "highvoltagekids";
+    readonly name = "High Voltage Kids";
+    readonly logos: ProviderLogos;
+    readonly config: ContentProviderConfig;
+    private data;
+    readonly requiresAuth = false;
+    readonly authTypes: AuthType[];
+    readonly capabilities: ProviderCapabilities;
+    browse(path?: string | null, _auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    private getCollections;
+    private getStudyFolders;
     private getLessonFolders;
+    private getLessonFiles;
+    getPresentations(path: string, _auth?: ContentProviderAuthData | null): Promise<Plan | null>;
+    getPlaylist(path: string, _auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
+    getInstructions(path: string, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
     private slugify;
+    private groupFilesIntoActions;
+    private getBaseName;
 }
 
 /**
  * Get a provider by ID.
  */
-declare function getProvider(providerId: string): ContentProvider | null;
+declare function getProvider(providerId: string): IProvider | null;
 /**
  * Get all registered providers.
  */
-declare function getAllProviders(): ContentProvider[];
+declare function getAllProviders(): IProvider[];
 /**
  * Register a custom provider.
  */
-declare function registerProvider(provider: ContentProvider): void;
+declare function registerProvider(provider: IProvider): void;
 /**
  * Get provider configuration by ID (for backward compatibility).
  */
@@ -392,13 +682,14 @@ declare function getProviderConfig(providerId: string): ContentProviderConfig |
 /**
  * Get list of available providers with their info including logos and auth types.
  * Includes both implemented providers and coming soon providers.
+ * @param ids - Optional array of provider IDs to filter the results. If provided, only providers with matching IDs will be returned.
  */
-declare function getAvailableProviders(): ProviderInfo[];
+declare function getAvailableProviders(ids?: string[]): ProviderInfo[];
 
 /**
  * @churchapps/content-provider-helper
  * Helper classes for interacting with third party content providers
  */
-declare const VERSION = "0.0.1";
+declare const VERSION = "0.0.4";
 
-export { APlayProvider, type AuthType, B1ChurchProvider, BibleProjectProvider, type ContentFile, type ContentFolder, type ContentItem, ContentProvider, type ContentProviderAuthData, type ContentProviderConfig, type DeviceAuthorizationResponse, type DeviceFlowPollResult, type DeviceFlowState, type FeedActionInterface, type FeedFileInterface, type FeedSectionInterface, type FeedVenueInterface, FormatConverters, FormatResolver, type FormatResolverOptions, type InstructionItem, type Instructions, LessonsChurchProvider, type MediaLicenseResult, type MediaLicenseStatus, type Plan, type PlanPresentation, type PlanSection, PlanningCenterProvider, type ProviderCapabilities, type ProviderInfo, type ProviderLogos, type ResolvedFormatMeta, SignPresenterProvider, VERSION, type VenueActionInterface, type VenueActionsResponseInterface, type VenueSectionActionsInterface, collapseInstructions, detectMediaType, expandedInstructionsToPlaylist, expandedInstructionsToPresentations, getAllProviders, getAvailableProviders, getProvider, getProviderConfig, instructionsToPlaylist, instructionsToPresentations, isContentFile, isContentFolder, playlistToExpandedInstructions, playlistToInstructions, playlistToPresentations, presentationsToExpandedInstructions, presentationsToInstructions, presentationsToPlaylist, registerProvider };
+export { APlayProvider, ApiHelper, type AuthType, B1ChurchProvider, BibleProjectProvider, type ContentFile, type ContentFolder, type ContentItem, ContentProvider, type ContentProviderAuthData, type ContentProviderConfig, DEFAULT_DURATION_CONFIG, type DeviceAuthorizationResponse, DeviceFlowHelper, type DeviceFlowPollResult, type DeviceFlowState, type DurationEstimationConfig, type FeedActionInterface, type FeedFileInterface, type FeedSectionInterface, type FeedVenueInterface, FormatConverters, FormatResolver, type FormatResolverOptions, HighVoltageKidsProvider, type IAuthProvider, type IContentProvider, type IProvider, type InstructionItem, type Instructions, LessonsChurchProvider, type MediaLicenseResult, type MediaLicenseStatus, OAuthHelper, type Plan, type PlanPresentation, type PlanSection, PlanningCenterProvider, type ProviderCapabilities, type ProviderInfo, type ProviderLogos, type ResolvedFormatMeta, SignPresenterProvider, TokenHelper, VERSION, type VenueActionInterface, type VenueActionsResponseInterface, type VenueSectionActionsInterface, appendToPath, buildPath, countWords, createFile, createFolder, detectMediaType, estimateDuration, estimateImageDuration, estimateTextDuration, expandedInstructionsToPlaylist, expandedInstructionsToPresentations, generatePath, getAllProviders, getAvailableProviders, getProvider, getProviderConfig, getSegment, instructionsToPlaylist, instructionsToPresentations, isContentFile, isContentFolder, navigateToPath, parsePath, playlistToExpandedInstructions, playlistToInstructions, playlistToPresentations, presentationsToExpandedInstructions, presentationsToPlaylist, registerProvider };