@churchapps/content-providers 0.4.1 → 0.5.1

package/dist/index.d.cts

@@ -19,7 +19,8 @@ interface ContentProviderConfig {
     scopes: string[];
     supportsDeviceFlow?: boolean;
     deviceAuthEndpoint?: string;
-    endpoints: EndpointsConfig;
+    /** @deprecated URL templates now live in each provider; kept optional for type compatibility. */
+    endpoints?: EndpointsConfig;
 }
 interface DeviceAuthorizationResponse {
     device_code: string;
@@ -234,31 +235,54 @@ interface IProvider {
     checkMediaLicense?(mediaId: string, auth?: ContentProviderAuthData | null): Promise<MediaLicenseResult | null>;
 }
 
-/**
- * Navigate to a specific item using a dot-notation path.
- * Path format: "0.2.1" means items[0].children[2].children[1]
- */
+/** Navigate to a specific item using dot-notation path (e.g. "0.2.1" → items[0].children[2].children[1]). */
 declare function navigateToPath(instructions: Instructions, path: string): InstructionItem | null;
 
+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>;
+}
+
+/** Map a raw OAuth token response to ContentProviderAuthData, stamping created_at. */
+declare function toAuthData(data: Record<string, unknown>, fallbacks?: {
+    refreshToken?: string;
+    scope?: string;
+}): ContentProviderAuthData;
 declare class TokenHelper {
     isAuthValid(auth: ContentProviderAuthData | null | undefined): boolean;
     isTokenExpired(auth: ContentProviderAuthData): boolean;
     refreshToken(config: ContentProviderConfig, auth: ContentProviderAuthData): Promise<ContentProviderAuthData | null>;
 }
 
-/**
- * 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 {
+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;
+}
+
+/** Base for providers; auth-flow methods are intentionally not here so consumers can feature-detect with `"method" in provider`. */
+declare abstract class BaseProvider implements IProvider {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract readonly logos: ProviderLogos;
+    abstract readonly config: ContentProviderConfig;
+    abstract readonly requiresAuth: boolean;
+    abstract readonly authTypes: AuthType[];
+    abstract readonly capabilities: ProviderCapabilities;
     private readonly apiHelper;
-    private apiRequest;
+    protected apiRequest<T>(path: string, auth?: ContentProviderAuthData | null, method?: "GET" | "POST", body?: unknown): Promise<T | null>;
+    abstract browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    supportsDeviceFlow(): boolean;
+}
+
+/** APlay Provider: media curriculum library with OAuth 2.0 auth. */
+declare class APlayProvider extends BaseProvider {
     readonly id = "aplay";
     readonly name = "APlay";
     readonly logos: ProviderLogos;
@@ -274,21 +298,12 @@ declare class APlayProvider implements IProvider {
     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>;
-    supportsDeviceFlow(): boolean;
 }
 
-/**
- * SignPresenter Provider
- *
- * Path structure:
- *   /playlists                    -> list playlists
- *   /playlists/{playlistId}       -> list messages (files)
- */
-declare class SignPresenterProvider implements IProvider {
-    private readonly apiHelper;
+/** Browses SignPresenter playlists → messages (files). */
+declare class SignPresenterProvider extends BaseProvider {
     private readonly oauthHelper;
     private readonly deviceFlowHelper;
-    private apiRequest;
     readonly id = "signpresenter";
     readonly name = "SignPresenter";
     readonly logos: ProviderLogos;
@@ -297,11 +312,11 @@ declare class SignPresenterProvider implements IProvider {
     readonly authTypes: AuthType[];
     readonly capabilities: ProviderCapabilities;
     browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    private extractList;
     private getPlaylists;
     private getMessages;
     getPlaylist(path: string, auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
     getInstructions(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    supportsDeviceFlow(): boolean;
     generateCodeVerifier(): string;
     buildAuthUrl(codeVerifier: string, redirectUri: string, state?: string): Promise<{
         url: string;
@@ -313,20 +328,11 @@ declare class SignPresenterProvider implements IProvider {
 }
 
 /**
- * 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}                                  -> individual add-ons
- *   /addons/{category}/{addOnId}                        -> single add-on file
+ * Path: /lessons → programs, /lessons/{id} → studies, /lessons/{id}/{id} → lessons,
+ * /lessons/{id}/{id}/{id} → venues, /lessons/{id}/{id}/{id}/{id} → files;
+ * /addons → categories, /addons/{cat} → items, /addons/{cat}/{id} → file.
  */
-declare class LessonsChurchProvider implements IProvider {
+declare class LessonsChurchProvider extends BaseProvider {
     readonly id = "lessonschurch";
     readonly name = "Lessons.church";
     readonly logos: ProviderLogos;
@@ -347,14 +353,11 @@ declare class LessonsChurchProvider implements IProvider {
     private getAddOnCategories;
     private getAddOnsByCategory;
     getInstructions(path: string, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    supportsDeviceFlow(): boolean;
 }
 
-declare class B1ChurchProvider implements IProvider {
-    private readonly apiHelper;
+declare class B1ChurchProvider extends BaseProvider {
     private readonly deviceFlowHelper;
     private readonly externalContentCache;
-    private apiRequest;
     readonly id = "b1church";
     readonly name = "B1.Church";
     readonly logos: ProviderLogos;
@@ -382,12 +385,10 @@ declare class B1ChurchProvider implements IProvider {
     private findItemByPath;
     private findPresentationByPath;
     getPlaylist(path: string, authData?: ContentProviderAuthData | null, resolution?: number): Promise<ContentFile[] | null>;
-    supportsDeviceFlow(): boolean;
 }
 
-declare class DropboxProvider implements IProvider {
+declare class DropboxProvider extends BaseProvider {
     private readonly oauthHelper;
-    private readonly apiHelper;
     readonly id = "dropbox";
     readonly name = "Dropbox";
     readonly logos: ProviderLogos;
@@ -403,9 +404,9 @@ declare class DropboxProvider implements IProvider {
     private resolveFileLinks;
     private checkIsLeaf;
     browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
+    private resolveMediaFiles;
     getPlaylist(path: string, auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
     getInstructions(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    supportsDeviceFlow(): boolean;
     generateCodeVerifier(): string;
     buildAuthUrl(codeVerifier: string, redirectUri: string, state?: string): Promise<{
         url: string;
@@ -416,22 +417,12 @@ declare class DropboxProvider implements IProvider {
     exchangeCodeForTokens(code: string, codeVerifier: string, redirectUri: string): Promise<ContentProviderAuthData | null>;
 }
 
-/**
- * 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;
+/** Browses Planning Center service types → plans → items. */
+declare class PlanningCenterProvider extends BaseProvider {
     readonly id = "planningcenter";
     readonly name = "Planning Center";
     readonly logos: ProviderLogos;
     readonly config: ContentProviderConfig;
-    private readonly ONE_WEEK_MS;
     readonly requiresAuth = true;
     readonly authTypes: AuthType[];
     readonly capabilities: ProviderCapabilities;
@@ -439,46 +430,32 @@ declare class PlanningCenterProvider implements IProvider {
     private getServiceTypes;
     private getPlans;
     private getPlanItems;
-    supportsDeviceFlow(): boolean;
 }
 
-/**
- * BibleProject Provider
- *
- * Path structure:
- *   /                              -> list collections
- *   /{collectionSlug}              -> list videos in collection
- *   /{collectionSlug}/{videoId}    -> single video
- */
-declare class BibleProjectProvider implements IProvider {
+/** BibleProject Provider: Bible education video content. */
+declare class BibleProjectProvider extends BaseProvider {
     readonly id = "bibleproject";
     readonly name = "The Bible Project";
     readonly logos: ProviderLogos;
     readonly config: ContentProviderConfig;
-    private data;
-    private getMuxThumbnail;
     readonly requiresAuth = false;
     readonly authTypes: AuthType[];
     readonly capabilities: ProviderCapabilities;
+    private data;
+    private getMuxThumbnail;
+    private videoToFile;
+    /** Resolve a path to its collection and files: all videos at depth 1, a single video at depth 2. */
+    private resolve;
     browse(path?: string | null, _auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
-    private getCollections;
-    private getLessonFolders;
-    private getVideoFile;
     getPlaylist(path: string, _auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
     getInstructions(path: string, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    supportsDeviceFlow(): boolean;
 }
 
 /**
- * HighVoltageKids Provider
- *
- * Path structure:
- *   /                                          -> list collections (Elementary, Preschool)
- *   /{collectionSlug}                          -> list studies
- *   /{collectionSlug}/{studyId}                -> list lessons
- *   /{collectionSlug}/{studyId}/{lessonId}     -> lesson files (leaf)
+ * Path structure: / → collections, /{collection} → studies, /{collection}/{study} → lessons,
+ * /{collection}/{study}/{lesson} → files (leaf).
  */
-declare class HighVoltageKidsProvider implements IProvider {
+declare class HighVoltageKidsProvider extends BaseProvider {
     readonly id = "highvoltagekids";
     readonly name = "High Voltage Kids";
     readonly logos: ProviderLogos;
@@ -490,21 +467,13 @@ declare class HighVoltageKidsProvider implements IProvider {
     browse(path?: string | null, _auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
     getPlaylist(path: string, _auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
     getInstructions(path: string, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    supportsDeviceFlow(): boolean;
 }
 
 /**
- * Jesus Film Project Provider
- *
- * Uses the public Arclight API to browse video content from jesusfilm.org.
- *
- * Path structure:
- *   /                                    -> categories (Feature Films, Series, Collections)
- *   /{category}                          -> list items in category
- *   /{category}/{id}                     -> single video (feature film) or container children (series/collection)
- *   /{category}/{...containerIds}/{id}   -> nested containers or single video (supports arbitrary depth)
+ * Path: / → categories, /{category} → items, /{category}/{id} → video or children,
+ * /{category}/{...ids}/{id} → nested containers or video.
  */
-declare class JesusFilmProvider implements IProvider {
+declare class JesusFilmProvider extends BaseProvider {
     readonly id = "jesusfilm";
     readonly name = "Jesus Film Project";
     readonly logos: ProviderLogos;
@@ -513,36 +482,24 @@ declare class JesusFilmProvider implements IProvider {
     readonly authTypes: AuthType[];
     readonly capabilities: ProviderCapabilities;
     private fetchApi;
+    private fetchCategoryComponents;
     browse(path?: string | null, _auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
     private getCategories;
     private getItemsInCategory;
     private getVideoFile;
     private getContainerChildren;
     private extractMuxPlaybackId;
-    getPlaylist(path: string, _auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
     private fetchVideoFiles;
     private fetchContainerVideoFiles;
+    getPlaylist(path: string, _auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
     private buildVideoInstructions;
     private buildContainerInstructions;
     getInstructions(path: string, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    supportsDeviceFlow(): boolean;
 }
 
-/**
- * CBN Provider
- *
- * Faith-based kids' video curriculum. Auth uses OAuth 2.0 Device Flow.
- *
- * Path structure:
- *   /                              -> single "Catalog" root folder
- *   /catalog                       -> course folders (GET /catalog)
- *   /catalog/{courseId}            -> lesson folders (GET /catalog/{courseId})
- *   /catalog/{courseId}/{lessonId} -> video files   (GET /lesson-playlist/{lessonId})
- */
-declare class CbnProvider implements IProvider {
-    private readonly apiHelper;
+/** Faith-based kids' video curriculum with OAuth 2.0 Device Flow auth. */
+declare class CbnProvider extends BaseProvider {
     private readonly deviceFlowHelper;
-    private apiRequest;
     readonly id = "cbn";
     readonly name = "CBN";
     readonly logos: ProviderLogos;
@@ -551,38 +508,16 @@ declare class CbnProvider implements IProvider {
     readonly authTypes: AuthType[];
     readonly capabilities: ProviderCapabilities;
     browse(path?: string | null, auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
-    private getCourses;
-    private getLessons;
-    private getVideos;
-    private fetchPlaylist;
+    /** Resolve a leaf path (/catalog/{courseId}/{lessonId}) to its playlist files. */
+    private resolveFiles;
     getPlaylist(path: string, auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
     getInstructions(path: string, auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
-    supportsDeviceFlow(): boolean;
     initiateDeviceFlow(): Promise<DeviceAuthorizationResponse | null>;
     pollDeviceFlowToken(deviceCode: string): Promise<DeviceFlowPollResult>;
 }
 
-/**
- * Life.Church Provider
- *
- * Browses the Life.Church kids curriculum from a static catalog generated by
- * scripts/scrape-lifechurch.ts (sourced from life.church/media/* + the
- * open.life.church weekly calendar).
- *
- * Path structure:
- *   /                                       -> "scheduled" folder + 4 series
- *   /scheduled                              -> this Sunday's scheduled lessons (one per age group)
- *   /scheduled/{scheduledId}                -> single video file (leaf)
- *   /{seriesId}                             -> units within the series
- *   /{seriesId}/{unitId}                    -> lessons within the unit
- *   /{seriesId}/{unitId}/{lessonId}         -> single video file (leaf)
- *
- * Video delivery: ContentFile.url is a direct mp4 on Life.Church's CDN
- * (https://d.life.church/.../{slug}_720p.mp4). Public, no auth, supports
- * range requests — plays in any standard mp4 player including
- * react-native-video.
- */
-declare class LifeChurchProvider implements IProvider {
+/** Browses Life.Church's kids curriculum from a static catalog (series → units → lessons), plus a weekly scheduled lesson index. */
+declare class LifeChurchProvider extends BaseProvider {
     readonly id = "lifechurch";
     readonly name = "Life.Church";
     readonly logos: ProviderLogos;
@@ -592,12 +527,12 @@ declare class LifeChurchProvider implements IProvider {
     readonly capabilities: ProviderCapabilities;
     private data;
     private findSeries;
-    private findUnit;
-    private findLesson;
     private findScheduled;
     /** Resolve a scheduled-lesson reference to the underlying lesson + unit + series. */
     private resolveScheduled;
     private lessonToFile;
+    /** Resolve a leaf-or-unit path to its files plus the name/section used for instructions. */
+    private resolve;
     browse(path?: string | null, _auth?: ContentProviderAuthData | null): Promise<ContentItem[]>;
     getPlaylist(path: string, _auth?: ContentProviderAuthData | null, _resolution?: number): Promise<ContentFile[] | null>;
     getInstructions(path: string, _auth?: ContentProviderAuthData | null): Promise<Instructions | null>;
@@ -605,7 +540,6 @@ declare class LifeChurchProvider implements IProvider {
      * Returns the most recent scheduled lesson from data.scheduledLessons.
      */
     getCurrentPlan(_auth?: ContentProviderAuthData | null): Promise<CurrentPlan | null>;
-    supportsDeviceFlow(): boolean;
 }
 
 declare function getProvider(providerId: string): IProvider | null;
@@ -616,11 +550,7 @@ declare function registerProvider(provider: IProvider): void;
  * Get provider configuration by ID (for backward compatibility).
  */
 declare function getProviderConfig(providerId: string): ContentProviderConfig | null;
-/**
- * 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.
- */
+/** Get available providers (implemented and coming soon), optionally filtered by IDs. */
 declare function getAvailableProviders(ids?: string[]): ProviderInfo[];
 
 /**
@@ -629,4 +559,4 @@ declare function getAvailableProviders(ids?: string[]): ProviderInfo[];
  */
 declare const VERSION: string;
 
-export { APlayProvider, type AuthType, B1ChurchProvider, BibleProjectProvider, CbnProvider, type ContentFile, type ContentFolder, type ContentItem, type ContentProviderAuthData, type ContentProviderConfig, type CurrentPlan, type DeviceAuthorizationResponse, type DeviceFlowPollResult, type DeviceFlowState, DropboxProvider, type EndpointValue, type EndpointsConfig, type FeedActionInterface, type FeedFileInterface, type FeedSectionInterface, type FeedVenueInterface, HighVoltageKidsProvider, type IProvider, type InstructionItem, type Instructions, JesusFilmProvider, LessonsChurchProvider, LifeChurchProvider, type MediaLicenseResult, type MediaLicenseStatus, type MessageFileInterface, type Plan, type PlanPresentation, type PlanSection, type PlanTimelineItem, PlanningCenterProvider, type ProviderCapabilities, type ProviderInfo, type ProviderLogos, SignPresenterProvider, TokenHelper, VERSION, type VenueActionInterface, type VenueActionsResponseInterface, type VenueSectionActionsInterface, getAllProviders, getAvailableProviders, getProvider, getProviderConfig, isContentFile, isContentFolder, navigateToPath, registerProvider };
+export { APlayProvider, type AuthType, B1ChurchProvider, BaseProvider, BibleProjectProvider, CbnProvider, type ContentFile, type ContentFolder, type ContentItem, type ContentProviderAuthData, type ContentProviderConfig, type CurrentPlan, type DeviceAuthorizationResponse, DeviceFlowHelper, type DeviceFlowPollResult, type DeviceFlowState, DropboxProvider, type EndpointValue, type EndpointsConfig, type FeedActionInterface, type FeedFileInterface, type FeedSectionInterface, type FeedVenueInterface, HighVoltageKidsProvider, type IProvider, type InstructionItem, type Instructions, JesusFilmProvider, LessonsChurchProvider, LifeChurchProvider, type MediaLicenseResult, type MediaLicenseStatus, type MessageFileInterface, OAuthHelper, type Plan, type PlanPresentation, type PlanSection, type PlanTimelineItem, PlanningCenterProvider, type ProviderCapabilities, type ProviderInfo, type ProviderLogos, SignPresenterProvider, TokenHelper, VERSION, type VenueActionInterface, type VenueActionsResponseInterface, type VenueSectionActionsInterface, getAllProviders, getAvailableProviders, getProvider, getProviderConfig, isContentFile, isContentFolder, navigateToPath, registerProvider, toAuthData };