@youversion/platform-core 0.4.1

package/src/bible.ts

@@ -0,0 +1,272 @@
+import { z } from 'zod';
+import type { ApiClient } from './client';
+import type {
+  BibleBook,
+  BibleChapter,
+  Collection,
+  BibleVerse,
+  BibleVersion,
+  BiblePassage,
+  VOTD,
+  BibleIndex,
+  CANON,
+} from './types';
+
+/**
+ * Client for interacting with Bible API endpoints.
+ */
+export class BibleClient {
+  private client: ApiClient;
+
+  // Validation schemas
+  private versionIdSchema = z.number().int().positive('Version ID must be a positive integer');
+  private bookSchema = z
+    .string()
+    .trim()
+    .min(3, 'Book ID must be exactly 3 characters')
+    .max(3, 'Book ID must be exactly 3 characters');
+  private chapterSchema = z
+    .number()
+    .int('Chapter must be an integer')
+    .positive('Chapter must be a positive integer');
+  private verseSchema = z
+    .number()
+    .int('Verse must be an integer')
+    .positive('Verse must be a positive integer');
+  private languageRangesSchema = z
+    .string()
+    .trim()
+    .min(1, 'Language ranges must be a non-empty string');
+  private booleanSchema = z.boolean();
+
+  /**
+   * Creates a new BibleClient instance.
+   * @param client The API client to use for requests.
+   */
+  constructor(client: ApiClient) {
+    this.client = client;
+  }
+
+  private get rootPath(): string {
+    return `/${this.client.config.version}`;
+  }
+
+  /**
+   * Fetches a collection of Bible versions filtered by language ranges.
+   *
+   * @param language_ranges - A comma-separated list of language codes or ranges to filter the versions (required).
+   * @param license_id - Optional license ID to filter versions by license.
+   * @returns A promise that resolves to a collection of BibleVersion objects.
+   */
+  async getVersions(
+    language_ranges: string,
+    license_id?: string | number,
+  ): Promise<Collection<BibleVersion>> {
+    this.languageRangesSchema.parse(language_ranges);
+    const params: Record<string, string | number> = {
+      'language_ranges[]': language_ranges,
+    };
+    if (license_id !== undefined) {
+      params.license_id = license_id;
+    }
+    return this.client.get<Collection<BibleVersion>>(`${this.rootPath}/bibles`, params);
+  }
+
+  /**
+   * Fetches a Bible version by its ID.
+   * @param id The version ID.
+   * @returns The requested BibleVersion object.
+   */
+  async getVersion(id: number): Promise<BibleVersion> {
+    this.versionIdSchema.parse(id);
+    return this.client.get<BibleVersion>(`${this.rootPath}/bibles/${id}`);
+  }
+
+  /**
+   * Fetches all books for a given Bible version.
+   * @param versionId The version ID.
+   * @param canon Optional canon filter ('ot', 'nt', 'deuterocanon').
+   * @returns An array of BibleBook objects.
+   */
+  async getBooks(versionId: number, canon?: CANON): Promise<Collection<BibleBook>> {
+    this.versionIdSchema.parse(versionId);
+    return this.client.get<Collection<BibleBook>>(`${this.rootPath}/bibles/${versionId}/books`, {
+      ...(canon && { canon }),
+    });
+  }
+
+  /**
+   * Fetches a specific book by USFM code for a given version.
+   * @param versionId The version ID.
+   * @param book The Book Identifier code of the book.
+   * @returns The requested BibleBook object.
+   */
+  async getBook(versionId: number, book: string): Promise<BibleBook> {
+    this.versionIdSchema.parse(versionId);
+    this.bookSchema.parse(book);
+    return this.client.get<BibleBook>(`${this.rootPath}/bibles/${versionId}/books/${book}`);
+  }
+
+  /**
+   * Fetches all chapters for a specific book in a version.
+   * @param versionId The version ID.
+   * @param book The Book Identifier code of the book.
+   * @returns An array of BibleChapter objects.
+   */
+  async getChapters(versionId: number, book: string): Promise<Collection<BibleChapter>> {
+    this.versionIdSchema.parse(versionId);
+    this.bookSchema.parse(book);
+    return this.client.get<Collection<BibleChapter>>(
+      `${this.rootPath}/bibles/${versionId}/books/${book}/chapters`,
+    );
+  }
+
+  /**
+   * Fetches a specific chapter for a book in a version.
+   * @param versionId The version ID.
+   * @param book The Book Identifier code of the book (3 characters, e.g., "MAT").
+   * @param chapter The chapter number
+   * @returns The requested BibleChapter object.
+   */
+  async getChapter(versionId: number, book: string, chapter: number): Promise<BibleChapter> {
+    this.versionIdSchema.parse(versionId);
+    this.bookSchema.parse(book);
+    this.chapterSchema.parse(chapter);
+
+    return this.client.get<BibleChapter>(
+      `${this.rootPath}/bibles/${versionId}/books/${book}/chapters/${chapter}`,
+    );
+  }
+
+  /**
+   * Fetches all verses for a specific chapter in a book and version.
+   * @param versionId The version ID.
+   * @param book The Book Identifier code of the book (3 characters, e.g., "MAT").
+   * @param chapter The chapter number.
+   * @returns An array of BibleVerse objects.
+   */
+  async getVerses(
+    versionId: number,
+    book: string,
+    chapter: number,
+  ): Promise<Collection<BibleVerse>> {
+    this.versionIdSchema.parse(versionId);
+    this.bookSchema.parse(book);
+    this.chapterSchema.parse(chapter);
+
+    return this.client.get<Collection<BibleVerse>>(
+      `${this.rootPath}/bibles/${versionId}/books/${book}/chapters/${chapter}/verses`,
+    );
+  }
+
+  /**
+   * Fetches a specific verse from a chapter, book, and version.
+   * @param versionId The version ID.
+   * @param book The Book Identifier code of the book (3 characters, e.g., "MAT").
+   * @param chapter The chapter number.
+   * @param verse The verse number.
+   * @returns The requested BibleVerse object.
+   */
+  async getVerse(
+    versionId: number,
+    book: string,
+    chapter: number,
+    verse: number,
+  ): Promise<BibleVerse> {
+    this.versionIdSchema.parse(versionId);
+    this.bookSchema.parse(book);
+    this.chapterSchema.parse(chapter);
+    this.verseSchema.parse(verse);
+
+    return this.client.get<BibleVerse>(
+      `${this.rootPath}/bibles/${versionId}/books/${book}/chapters/${chapter}/verses/${verse}`,
+    );
+  }
+
+  /**
+   * Fetches a passage (range of verses) from the Bible using the passages endpoint.
+   * This is the new API format that returns HTML-formatted content.
+   * @param versionId The version ID.
+   * @param usfm The USFM reference (e.g., "JHN.3.1-2", "GEN.1", "JHN.3.16").
+   * @param format The format to return ("html" or "text", default: "html").
+   * @param include_headings Whether to include headings in the content.
+   * @param include_notes Whether to include notes in the content.
+   * @returns The requested BiblePassage object with HTML content.
+   * @example
+   * ```ts
+   * // Get a single verse
+   * const verse = await bibleClient.getPassage(111, "JHN.3.16");
+   *
+   * // Get a range of verses
+   * const verses = await bibleClient.getPassage(111, "JHN.3.1-5");
+   *
+   * // Get an entire chapter
+   * const chapter = await bibleClient.getPassage(111, "GEN.1");
+   * ```
+   */
+  async getPassage(
+    versionId: number,
+    usfm: string,
+    format: 'html' | 'text' = 'html',
+    include_headings?: boolean,
+    include_notes?: boolean,
+  ): Promise<BiblePassage> {
+    this.versionIdSchema.parse(versionId);
+    if (include_headings !== undefined) {
+      this.booleanSchema.parse(include_headings);
+    }
+    if (include_notes !== undefined) {
+      this.booleanSchema.parse(include_notes);
+    }
+    const params: Record<string, string | number | boolean> = {
+      format,
+    };
+    if (include_headings !== undefined) {
+      params.include_headings = include_headings;
+    }
+    if (include_notes !== undefined) {
+      params.include_notes = include_notes;
+    }
+    return this.client.get<BiblePassage>(
+      `${this.rootPath}/bibles/${versionId}/passages/${usfm}`,
+      params,
+    );
+  }
+
+  /**
+   * Fetches the indexing structure for a Bible version.
+   * @param versionId The version ID.
+   * @returns The BibleIndex object containing full hierarchy of books, chapters, and verses.
+   */
+  async getIndex(versionId: number): Promise<BibleIndex> {
+    this.versionIdSchema.parse(versionId);
+    return this.client.get<BibleIndex>(`${this.rootPath}/bibles/${versionId}/index`);
+  }
+
+  /**
+   * Fetches the verse of the day calendar for an entire year.
+   * @returns A collection of VOTD objects for all days of the year.
+   */
+  async getAllVOTDs(): Promise<Collection<VOTD>> {
+    return this.client.get<Collection<VOTD>>(`${this.rootPath}/verse_of_the_days`);
+  }
+
+  /**
+   * Fetches the passage_id for the Verse Of The Day.
+   * @param day The day of the year (1-366).
+   * @returns The day of the year and the passage_id for that day of the year
+   * @example
+   * ```ts
+   * // Get the passageId for the verse of the first day of the year.
+   * const passageId = await bibleClient.getVOTD(1);
+   *
+   * // Get the passageId for the verse of the 100th day of the year.
+   * const passageId = await bibleClient.getVOTD(100);
+   * ```
+   */
+  async getVOTD(day: number): Promise<VOTD> {
+    const daySchema = z.number().int().min(1).max(366);
+    daySchema.parse(day);
+    return this.client.get<VOTD>(`${this.rootPath}/verse_of_the_days/${day}`);
+  }
+}

package/src/client.ts

@@ -0,0 +1,162 @@
+import type { ApiConfig } from './types';
+
+type QueryParams = Record<string, string | number | boolean>;
+type RequestData = Record<string, string | number | boolean | object>;
+type RequestHeaders = Record<string, string>;
+
+/**
+ * ApiClient is a lightweight HTTP client for interacting with the API using fetch.
+ * It provides convenient methods for GET and POST requests with typed responses.
+ */
+export class ApiClient {
+  private baseURL: string;
+  private timeout: number;
+  private defaultHeaders: RequestHeaders;
+  public config: ApiConfig;
+
+  /**
+   * Creates an instance of ApiClient.
+   *
+   * @param config - The API configuration object containing baseUrl, timeout, and appId.
+   */
+  constructor(config: ApiConfig) {
+    this.config = {
+      version: config.version || 'v1',
+      ...config,
+    };
+    this.baseURL = config.baseUrl || 'https://api-dev.youversion.com';
+    this.timeout = config.timeout || 10000;
+    this.defaultHeaders = {
+      'Content-Type': 'application/json',
+      'X-YVP-App-Key': this.config.appId,
+      'X-YVP-Installation-Id': this.config.installationId || 'web-sdk-default',
+    };
+  }
+
+  /**
+   * Builds the query string from parameters
+   */
+  private buildQueryString(params?: QueryParams): string {
+    if (!params) return '';
+    const queryString = new URLSearchParams(
+      Object.entries(params).map(([key, value]) => [key, String(value)]),
+    ).toString();
+    return queryString ? `?${queryString}` : '';
+  }
+
+  /**
+   * Makes an HTTP request with timeout support
+   */
+  private async request<T>(url: string, options: RequestInit = {}): Promise<T> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+        headers: {
+          ...this.defaultHeaders,
+          ...options.headers,
+        },
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const isDevelopment = process.env.NODE_ENV === 'development';
+        let errorMessage = `HTTP error! status: ${response.status}`;
+        try {
+          const errorBody = await response.text();
+          if (errorBody) {
+            try {
+              const errorJson = JSON.parse(errorBody) as { message?: string; error?: string };
+              const detailedMessage = errorJson.message || errorJson.error || errorBody;
+              if (isDevelopment) {
+                errorMessage = detailedMessage;
+              } else {
+                errorMessage = `Request failed with status ${response.status}`;
+              }
+            } catch {
+              if (isDevelopment) {
+                errorMessage = errorBody;
+              }
+            }
+          }
+        } catch (error) {
+          if (isDevelopment && error instanceof Error) {
+            console.error('Failed to read error response:', error.message);
+          }
+        }
+        const error = Object.assign(new Error(errorMessage), {
+          status: response.status,
+          statusText: response.statusText,
+        });
+        throw error;
+      }
+
+      const contentType = response.headers.get('content-type');
+      if (contentType?.includes('application/json')) {
+        const data = (await response.json()) as T;
+        return data;
+      } else {
+        const text = await response.text();
+        return text as unknown as T;
+      }
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${this.timeout}ms`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Sends a GET request to the specified API path with optional query parameters.
+   *
+   * @typeParam T - The expected response type.
+   * @param path - The API endpoint path (relative to baseURL).
+   * @param params - Optional query parameters to include in the request.
+   * @returns A promise resolving to the response data of type T.
+   */
+  async get<T>(path: string, params?: QueryParams, headers?: RequestHeaders): Promise<T> {
+    const url = `${this.baseURL}${path}${this.buildQueryString(params)}`;
+    return this.request<T>(url, {
+      method: 'GET',
+      headers,
+    });
+  }
+
+  /**
+   * Sends a POST request to the specified API path with optional data and query parameters.
+   *
+   * @typeParam T - The expected response type.
+   * @param path - The API endpoint path (relative to baseURL).
+   * @param data - Optional request body data to send.
+   * @param params - Optional query parameters to include in the request.
+   * @returns A promise resolving to the response data of type T.
+   */
+  async post<T>(path: string, data?: RequestData, params?: QueryParams): Promise<T> {
+    const url = `${this.baseURL}${path}${this.buildQueryString(params)}`;
+    return this.request<T>(url, {
+      method: 'POST',
+      body: data ? JSON.stringify(data) : undefined,
+    });
+  }
+
+  /**
+   * Sends a DELETE request to the specified API path with optional query parameters.
+   *
+   * @typeParam T - The expected response type.
+   * @param path - The API endpoint path (relative to baseURL).
+   * @param params - Optional query parameters to include in the request.
+   * @returns A promise resolving to the response data of type T (may be empty for 204 responses).
+   */
+  async delete<T>(path: string, params?: QueryParams): Promise<T> {
+    const url = `${this.baseURL}${path}${this.buildQueryString(params)}`;
+    return this.request<T>(url, {
+      method: 'DELETE',
+    });
+  }
+}

package/src/highlight.ts

@@ -0,0 +1,16 @@
+import type { HighlightColor } from './types';
+
+export const HIGHLIGHT_COLORS: HighlightColor[] = [
+  { id: 0, color: '#fffe00', label: 'Yellow' },
+  { id: 1, color: '#5dff79', label: 'Green' },
+  { id: 2, color: '#00d6ff', label: 'Blue' },
+  { id: 3, color: '#ffc66f', label: 'Orange' },
+  { id: 4, color: '#ff95ef', label: 'Pink' },
+] as const;
+
+export function hexToRgba(hex: string, alpha: number): string {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}

package/src/highlights.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import type { ApiClient } from './client';
+import type { Collection, Highlight, CreateHighlight } from './types';
+import { YouVersionPlatformConfiguration } from './YouVersionPlatformConfiguration';
+
+/**
+ * Options for getting highlights.
+ */
+export type GetHighlightsOptions = {
+  version_id?: number;
+  passage_id?: string;
+};
+
+/**
+ * Options for deleting highlights.
+ */
+export type DeleteHighlightOptions = {
+  version_id?: number;
+};
+
+/**
+ * Client for interacting with Highlights API endpoints.
+ * Note: All endpoints require OAuth authentication with appropriate scopes.
+ */
+export class HighlightsClient {
+  private client: ApiClient;
+
+  private versionIdSchema = z.number().int().positive('Version ID must be a positive integer');
+  private passageIdSchema = z.string().trim().min(1, 'Passage ID must be a non-empty string');
+  private colorSchema = z
+    .string()
+    .regex(/^[0-9a-f]{6}$/i, 'Color must be a 6-character hex string without #');
+
+  /**
+   * Creates a new HighlightsClient instance.
+   * @param client The API client to use for requests.
+   */
+  constructor(client: ApiClient) {
+    this.client = client;
+  }
+
+  private get rootPath(): string {
+    return `/${this.client.config.version}`;
+  }
+
+  /**
+   * Gets the authentication token, either from the provided parameter or from the platform configuration.
+   * @param lat Optional explicit long access token. If not provided, retrieves from YouVersionPlatformConfiguration.
+   * @returns The authentication token.
+   * @throws Error if no token is available.
+   */
+  private getAuthToken(lat?: string): string {
+    if (lat) {
+      return lat;
+    }
+    const token = YouVersionPlatformConfiguration.accessToken;
+    if (!token) {
+      throw new Error(
+        'Authentication required. Please provide a token or sign in before accessing highlights.',
+      );
+    }
+    return token;
+  }
+
+  private validateVersionId(value: number): void {
+    try {
+      this.versionIdSchema.parse(value);
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        throw new Error('Version ID must be a positive integer');
+      }
+      throw error;
+    }
+  }
+
+  private validatePassageId(value: string): void {
+    try {
+      this.passageIdSchema.parse(value);
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        throw new Error('Passage ID must be a non-empty string');
+      }
+      throw error;
+    }
+  }
+
+  private validateColor(value: string): void {
+    try {
+      this.colorSchema.parse(value);
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        throw new Error('Color must be a 6-character hex string without #');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Fetches a collection of highlights for a user.
+   * The response will return a color per verse without ranges.
+   * Requires OAuth with read_highlights scope.
+   * @param options Query parameters for filtering highlights.
+   * @param lat Optional long access token. If not provided, retrieves from YouVersionPlatformConfiguration.
+   * @returns A collection of Highlight objects.
+   */
+  async getHighlights(
+    options?: GetHighlightsOptions,
+    lat?: string,
+  ): Promise<Collection<Highlight>> {
+    const token = this.getAuthToken(lat);
+    const params: Record<string, string | number> = {
+      lat: token,
+    };
+
+    if (options?.version_id !== undefined) {
+      this.validateVersionId(options.version_id);
+      params.version_id = options.version_id;
+    }
+
+    if (options?.passage_id !== undefined) {
+      this.validatePassageId(options.passage_id);
+      params.passage_id = options.passage_id;
+    }
+
+    return this.client.get<Collection<Highlight>>(`${this.rootPath}/highlights`, params);
+  }
+
+  /**
+   * Creates or updates a highlight on a passage.
+   * Verse ranges may be used in the passage_id attribute.
+   * Requires OAuth with write_highlights scope.
+   * @param data The highlight data to create or update.
+   * @param lat Optional long access token. If not provided, retrieves from YouVersionPlatformConfiguration.
+   * @returns The created or updated Highlight object.
+   */
+  async createHighlight(data: CreateHighlight, lat?: string): Promise<Highlight> {
+    this.validateVersionId(data.version_id);
+    this.validatePassageId(data.passage_id);
+    this.validateColor(data.color);
+
+    const token = this.getAuthToken(lat);
+
+    return this.client.post<Highlight>(`${this.rootPath}/highlights`, data, { lat: token });
+  }
+
+  /**
+   * Clears highlights for a passage.
+   * Requires OAuth with write_highlights scope.
+   * @param passageId The passage identifier (USFM format, e.g., "MAT.1.1" or "MAT.1.1-5").
+   * @param options Optional query parameters including bible_id.
+   * @param lat Optional long access token. If not provided, retrieves from YouVersionPlatformConfiguration.
+   * @returns Promise that resolves when highlights are deleted (204 response).
+   */
+  async deleteHighlight(
+    passageId: string,
+    options?: DeleteHighlightOptions,
+    lat?: string,
+  ): Promise<void> {
+    this.validatePassageId(passageId);
+
+    const token = this.getAuthToken(lat);
+    const params: Record<string, string | number> = {
+      lat: token,
+    };
+
+    if (options?.version_id !== undefined) {
+      this.validateVersionId(options.version_id);
+      params.version_id = options.version_id;
+    }
+
+    await this.client.delete<void>(`${this.rootPath}/highlights/${passageId}`, params);
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { ApiClient } from './client';
+export { BibleClient } from './bible';
+export { LanguagesClient, type GetLanguagesOptions } from './languages';
+export {
+  HighlightsClient,
+  type GetHighlightsOptions,
+  type DeleteHighlightOptions,
+} from './highlights';
+export { AuthClient } from './authentication';
+export * from './AuthenticationStrategy';
+export { WebAuthenticationStrategy } from './WebAuthenticationStrategy';
+export * from './StorageStrategy';
+export * from './Users';
+export * from './YouVersionUserInfo';
+export * from './SignInWithYouVersionResult';
+export * from './YouVersionAPI';
+export * from './URLBuilder';
+export * from './YouVersionPlatformConfiguration';
+export * from './types';
+export * from './utils/constants';