@youversion/platform-core 1.20.1 → 1.21.0

package/src/bible-html-transformer.ts

@@ -0,0 +1,378 @@
+const NON_BREAKING_SPACE = '\u00A0';
+
+const FOOTNOTE_KEY_ATTR = 'data-footnote-key';
+
+const NEEDS_SPACE_BEFORE = /^[^\s.,;:!?)}\]'"'»›]/;
+
+const ALLOWED_TAGS = new Set([
+  'DIV',
+  'P',
+  'SPAN',
+  'SUP',
+  'SUB',
+  'EM',
+  'STRONG',
+  'I',
+  'B',
+  'SMALL',
+  'BR',
+  'SECTION',
+  'TABLE',
+  'THEAD',
+  'TBODY',
+  'TR',
+  'TD',
+  'TH',
+]);
+
+const DROP_ENTIRELY_TAGS = new Set([
+  'SCRIPT',
+  'STYLE',
+  'IFRAME',
+  'OBJECT',
+  'EMBED',
+  'SVG',
+  'MATH',
+  'FORM',
+  'INPUT',
+  'BUTTON',
+  'TEXTAREA',
+  'SELECT',
+  'TEMPLATE',
+  'LINK',
+  'META',
+  'BASE',
+  'NOSCRIPT',
+]);
+
+const ALLOWED_ATTRS = new Set(['class', 'v', 'colspan', 'rowspan', 'dir', 'usfm']);
+
+function sanitizeBibleHtmlDocument(doc: Document): void {
+  const root = doc.body ?? doc.documentElement;
+  for (const el of Array.from(root.querySelectorAll('*'))) {
+    const tag = el.tagName;
+
+    if (DROP_ENTIRELY_TAGS.has(tag)) {
+      el.remove();
+      continue;
+    }
+
+    if (!ALLOWED_TAGS.has(tag)) {
+      el.replaceWith(...Array.from(el.childNodes));
+      continue;
+    }
+
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      if (name.startsWith('on')) {
+        el.removeAttribute(attr.name);
+        continue;
+      }
+
+      if (!ALLOWED_ATTRS.has(name) && !name.startsWith('data-')) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+}
+
+/**
+ * Options for transforming Bible HTML. Requires DOM adapter functions
+ * to parse and serialize HTML, making the transformer runtime-agnostic.
+ */
+export type TransformBibleHtmlOptions = {
+  /** Parses an HTML string into a DOM Document */
+  parseHtml: (html: string) => Document;
+  /** Serializes a Document back to an HTML string */
+  serializeHtml: (doc: Document) => string;
+};
+
+/**
+ * The result of transforming Bible HTML.
+ *
+ * The returned HTML is self-contained — footnote data is embedded as attributes:
+ * - `data-verse-footnote="KEY"` marks the footnote position
+ * - `data-verse-footnote-content="HTML"` contains the footnote's inner HTML
+ *
+ * Consumers can access verse context by walking up from a footnote anchor
+ * to `.closest('.yv-v[v]')`.
+ */
+export type TransformedBibleHtml = {
+  /** The transformed HTML with footnotes replaced by marker elements */
+  html: string;
+};
+
+function wrapVerseContent(doc: Document): void {
+  function wrapParagraphContent(doc: Document, paragraph: Element, verseNum: string): void {
+    const children = Array.from(paragraph.childNodes);
+    if (children.length === 0) return;
+
+    const wrapper = doc.createElement('span');
+    wrapper.className = 'yv-v';
+    wrapper.setAttribute('v', verseNum);
+
+    const firstChild = children[0];
+    if (firstChild) {
+      paragraph.insertBefore(wrapper, firstChild);
+    }
+    children.forEach((child) => {
+      wrapper.appendChild(child);
+    });
+  }
+
+  function wrapParagraphsUntilBoundary(
+    doc: Document,
+    verseNum: string,
+    startParagraph: Element | null,
+    endParagraph?: Element | null,
+  ): void {
+    if (!startParagraph) return;
+
+    let currentParagraph: Element | null = startParagraph.nextElementSibling;
+
+    while (currentParagraph && currentParagraph !== endParagraph) {
+      const isHeading =
+        currentParagraph.classList.contains('yv-h') ||
+        currentParagraph.matches(
+          '.s1, .s2, .s3, .s4, .ms, .ms1, .ms2, .ms3, .ms4, .mr, .sp, .sr, .qa, .r',
+        );
+      if (isHeading) {
+        currentParagraph = currentParagraph.nextElementSibling;
+        continue;
+      }
+
+      if (currentParagraph.querySelector('.yv-v[v]')) break;
+
+      if (currentParagraph.classList.contains('p') || currentParagraph.tagName === 'P') {
+        wrapParagraphContent(doc, currentParagraph, verseNum);
+      }
+
+      currentParagraph = currentParagraph.nextElementSibling;
+    }
+  }
+
+  function handleParagraphWrapping(
+    doc: Document,
+    currentParagraph: Element | null,
+    nextParagraph: Element | null,
+    verseNum: string,
+  ): void {
+    if (!currentParagraph) return;
+
+    if (!nextParagraph) {
+      wrapParagraphsUntilBoundary(doc, verseNum, currentParagraph);
+      return;
+    }
+
+    if (currentParagraph !== nextParagraph) {
+      wrapParagraphsUntilBoundary(doc, verseNum, currentParagraph, nextParagraph);
+    }
+  }
+
+  function processVerseMarker(marker: Element, index: number, markers: Element[]): void {
+    const verseNum = marker.getAttribute('v');
+    if (!verseNum) return;
+
+    const nextMarker = markers[index + 1];
+
+    const nodesToWrap = collectNodesBetweenMarkers(marker, nextMarker);
+    if (nodesToWrap.length === 0) return;
+
+    const currentParagraph = marker.closest('.p, p, div.p');
+    const nextParagraph = nextMarker?.closest('.p, p, div.p') || null;
+    const doc = marker.ownerDocument;
+
+    wrapNodesInVerse(marker, verseNum, nodesToWrap);
+    handleParagraphWrapping(doc, currentParagraph, nextParagraph, verseNum);
+  }
+
+  function wrapNodesInVerse(marker: Element, verseNum: string, nodes: Node[]): void {
+    const wrapper = marker.ownerDocument.createElement('span');
+    wrapper.className = 'yv-v';
+    wrapper.setAttribute('v', verseNum);
+
+    const firstNode = nodes[0];
+    if (firstNode) {
+      marker.parentNode?.insertBefore(wrapper, firstNode);
+    }
+
+    nodes.forEach((node) => {
+      wrapper.appendChild(node);
+    });
+    marker.remove();
+  }
+
+  function shouldStopCollecting(node: Node, endMarker: Element | undefined): boolean {
+    if (node === endMarker) return true;
+    if (endMarker && node.nodeType === 1 && (node as Element).contains(endMarker)) return true;
+    return false;
+  }
+
+  function shouldSkipNode(node: Node): boolean {
+    return node.nodeType === 1 && (node as Element).classList.contains('yv-h');
+  }
+
+  function collectNodesBetweenMarkers(
+    startMarker: Element,
+    endMarker: Element | undefined,
+  ): Node[] {
+    const nodes: Node[] = [];
+    let current: Node | null = startMarker.nextSibling;
+
+    while (current && !shouldStopCollecting(current, endMarker)) {
+      if (shouldSkipNode(current)) {
+        current = current.nextSibling;
+        continue;
+      }
+      nodes.push(current);
+      current = current.nextSibling;
+    }
+
+    return nodes;
+  }
+
+  const verseMarkers = Array.from(doc.querySelectorAll('.yv-v[v]'));
+  verseMarkers.forEach(processVerseMarker);
+}
+
+function assignFootnoteKeys(doc: Document): void {
+  let introIdx = 0;
+  doc.querySelectorAll('.yv-n.f').forEach((fn) => {
+    const verseNum = fn.closest('.yv-v[v]')?.getAttribute('v');
+    fn.setAttribute(FOOTNOTE_KEY_ATTR, verseNum ?? `intro-${introIdx++}`);
+  });
+}
+
+function replaceFootnotesWithAnchors(doc: Document, footnotes: Element[]): void {
+  for (const fn of footnotes) {
+    const key = fn.getAttribute(FOOTNOTE_KEY_ATTR);
+    if (!key) continue;
+
+    const prev = fn.previousSibling;
+    const next = fn.nextSibling;
+
+    const prevText = prev?.textContent ?? '';
+    const nextText = next?.textContent ?? '';
+
+    const prevNeedsSpace = prevText.length > 0 && !/\s$/.test(prevText);
+    const nextNeedsSpace = nextText.length > 0 && NEEDS_SPACE_BEFORE.test(nextText);
+
+    if (prevNeedsSpace && nextNeedsSpace && fn.parentNode) {
+      fn.parentNode.insertBefore(doc.createTextNode(' '), fn);
+    }
+
+    const anchor = doc.createElement('span');
+    anchor.setAttribute('data-verse-footnote', key);
+    anchor.setAttribute('data-verse-footnote-content', fn.innerHTML);
+    fn.replaceWith(anchor);
+  }
+}
+
+function addNbspToVerseLabels(doc: Document): void {
+  doc.querySelectorAll('.yv-vlbl').forEach((label) => {
+    const text = label.textContent || '';
+    if (!text.endsWith(NON_BREAKING_SPACE)) {
+      label.textContent = text + NON_BREAKING_SPACE;
+    }
+  });
+}
+
+function fixIrregularTables(doc: Document): void {
+  doc.querySelectorAll('table').forEach((table) => {
+    const rows = table.querySelectorAll('tr');
+    if (rows.length === 0) return;
+
+    let maxColumns = 0;
+    rows.forEach((row) => {
+      let count = 0;
+      row.querySelectorAll('td, th').forEach((cell) => {
+        count += parseInt(cell.getAttribute('colspan') || '1', 10);
+      });
+      maxColumns = Math.max(maxColumns, count);
+    });
+
+    if (maxColumns > 1) {
+      rows.forEach((row) => {
+        const cells = row.querySelectorAll('td, th');
+        if (cells.length === 1) {
+          const existing = parseInt(cells[0]!.getAttribute('colspan') || '1', 10);
+          if (existing < maxColumns) {
+            cells[0]!.setAttribute('colspan', maxColumns.toString());
+          }
+        }
+      });
+    }
+  });
+}
+
+/**
+ * Transforms Bible HTML by cleaning up verse structure, extracting footnotes,
+ * and replacing them with self-contained anchor elements.
+ *
+ * Footnote data is embedded directly in the HTML via attributes:
+ * - `data-verse-footnote="KEY"` — the footnote key (verse number or `intro-N`)
+ * - `data-verse-footnote-content="HTML"` — the footnote's inner HTML content
+ *
+ * Verse context is available by walking up from a footnote anchor:
+ * `anchor.closest('.yv-v[v]')` returns the verse wrapper (null for intro footnotes).
+ *
+ * @param html - The raw Bible HTML from the YouVersion API
+ * @param options - DOM adapter options for parsing and serializing HTML
+ * @returns The transformed HTML
+ *
+ * @example
+ * ```ts
+ * import { transformBibleHtml } from '@youversion/platform-core';
+ *
+ * const result = transformBibleHtml(rawHtml, {
+ *   parseHtml: (html) => new DOMParser().parseFromString(html, 'text/html'),
+ *   serializeHtml: (doc) => doc.body.innerHTML,
+ * });
+ *
+ * console.log(result.html); // Clean HTML with self-contained footnote anchors
+ * ```
+ */
+export function transformBibleHtml(
+  html: string,
+  options: TransformBibleHtmlOptions,
+): TransformedBibleHtml {
+  const doc = options.parseHtml(html);
+
+  sanitizeBibleHtmlDocument(doc);
+  wrapVerseContent(doc);
+  assignFootnoteKeys(doc);
+
+  const footnotes = Array.from(doc.querySelectorAll('.yv-n.f'));
+  replaceFootnotesWithAnchors(doc, footnotes);
+
+  addNbspToVerseLabels(doc);
+  fixIrregularTables(doc);
+
+  const transformedHtml = options.serializeHtml(doc);
+  return { html: transformedHtml };
+}
+
+/**
+ * Transforms Bible HTML for browser environments using the native DOMParser API.
+ *
+ * @param html - The raw Bible HTML from the YouVersion API
+ * @returns The transformed HTML
+ *
+ * @example
+ * ```ts
+ * import { transformBibleHtmlForBrowser } from '@youversion/platform-core/browser';
+ *
+ * const result = transformBibleHtmlForBrowser(rawHtml);
+ * console.log(result.html); // Clean HTML with self-contained footnote anchors
+ * ```
+ */
+export function transformBibleHtmlForBrowser(html: string): TransformedBibleHtml {
+  if (typeof globalThis.DOMParser === 'undefined') {
+    throw new Error('DOMParser is required to transform Bible HTML in browser environments');
+  }
+
+  return transformBibleHtml(html, {
+    parseHtml: (h) => new DOMParser().parseFromString(h, 'text/html'),
+    serializeHtml: (doc) => doc.body.innerHTML,
+  });
+}

package/src/bible.ts

@@ -235,12 +235,18 @@ export class BibleClient {
   /**
    * Fetches a passage (range of verses) from the Bible using the passages endpoint.
    * This is the new API format that returns HTML-formatted content.
+   *
+   * Note: The HTML returned from the API contains inline footnote content that should
+   * be transformed before rendering. Use `transformBibleHtml()` or
+   * `transformBibleHtmlForBrowser()` to clean up the HTML and extract footnotes.
+   *
    * @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
@@ -251,6 +257,10 @@ export class BibleClient {
    *
    * // Get an entire chapter
    * const chapter = await bibleClient.getPassage(3034, "GEN.1");
+   *
+   * // Transform HTML before rendering
+   * const passage = await bibleClient.getPassage(3034, "JHN.3.16", "html", true, true);
+   * const transformed = transformBibleHtmlForBrowser(passage.content);
    * ```
    */
   async getPassage(

package/src/browser.ts

@@ -0,0 +1,4 @@
+export {
+  transformBibleHtmlForBrowser as transformBibleHtml,
+  type TransformedBibleHtml,
+} from './bible-html-transformer';

package/src/index.ts

@@ -15,3 +15,8 @@ export * from './YouVersionPlatformConfiguration';
 export * from './types';
 export * from './utils/constants';
 export { getAdjacentChapter } from './getAdjacentChapter';
+export {
+  transformBibleHtml,
+  type TransformBibleHtmlOptions,
+  type TransformedBibleHtml,
+} from './bible-html-transformer';

package/src/schemas/book.ts

@@ -1,11 +1,10 @@
 import { z } from 'zod';
-import { BOOK_IDS } from '../utils/constants';
+import { BOOK_IDS, CANON_IDS } from '../utils/constants';
 import { BibleChapterSchema } from './chapter';
 
-export const CanonSchema = z.enum(['old_testament', 'new_testament', 'deuterocanon']);
-export type Canon = Readonly<z.infer<typeof CanonSchema>>;
+export const CanonSchema = z.enum(CANON_IDS);
 
-export const BibleBookIntroSchema = z.object({
+const BibleBookIntroSchema = z.object({
   /** Intro identifier */
   id: z.string(),
   /** Intro passage identifier */
@@ -20,7 +19,6 @@ export const BookUsfmSchema = z.union([
   ...BOOK_IDS.map((id) => z.literal(id)),
   z.string().length(3) as z.ZodType<string & {}>,
 ]);
-export type BookUsfm = z.infer<typeof BookUsfmSchema>;
 
 export const BibleBookSchema = z.object({
   /** Book identifier (e.g., "MAT") */

package/src/server.ts

@@ -0,0 +1,2 @@
+export { transformBibleHtml } from './bible-html-transformer-server';
+export { type TransformedBibleHtml } from './bible-html-transformer';

package/src/types/index.ts

@@ -1,3 +1,8 @@
+import type {
+  SignInWithYouVersionPermission,
+  SignInWithYouVersionResult,
+} from '../SignInWithYouVersionResult';
+
 // Re-export all schema-derived types from schemas
 export type { BibleVersion } from '../schemas/version';
 export type { BibleBook, BibleBookIntro, CANON } from '../schemas/book';
@@ -16,11 +21,30 @@ export type { User } from '../schemas/user';
 export type { Highlight, CreateHighlight } from '../schemas/highlight';
 export type { Collection } from '../schemas/collection';
 
-// Re-export internal/non-API types
-export type { ApiConfig } from './api-config';
-export type {
-  AuthenticationState,
-  SignInWithYouVersionPermissionValues,
-  AuthenticationScopes,
-} from './auth';
-export type { HighlightColor } from './highlight';
+export interface ApiConfig {
+  apiHost?: string;
+  appKey: string;
+  timeout?: number;
+  installationId?: string;
+  redirectUri?: string;
+}
+
+export type SignInWithYouVersionPermissionValues =
+  (typeof SignInWithYouVersionPermission)[keyof typeof SignInWithYouVersionPermission];
+
+export interface AuthenticationState {
+  readonly isAuthenticated: boolean;
+  readonly isLoading: boolean;
+  readonly accessToken: string | null;
+  readonly idToken: string | null;
+  readonly result: SignInWithYouVersionResult | null;
+  readonly error: Error | null;
+}
+
+export type AuthenticationScopes = 'profile' | 'email';
+
+export interface HighlightColor {
+  id: number;
+  color: string;
+  label: string;
+}

package/src/utils/constants.ts

@@ -5,6 +5,8 @@
  */
 export const DEFAULT_LICENSE_FREE_BIBLE_VERSION = 3034 as const;
 
+export const CANON_IDS = ['old_testament', 'new_testament', 'deuterocanon'] as const;
+
 export const BOOK_IDS = [
   'GEN',
   'EXO',
@@ -113,13 +115,13 @@ export const BOOK_IDS = [
   'LKA',
 ] as const;
 
-// Import types for BOOK_CANON - moved CANON_IDS to schemas/book.ts to avoid circular dependency
-import type { Canon, BookUsfm } from '../schemas/book';
+type CanonId = (typeof CANON_IDS)[number];
+type KnownBookUsfm = (typeof BOOK_IDS)[number];
 
 /**
  * @see https://github.com/youversion/usfm-references/blob/main/usfm_references/books.py
  */
-export const BOOK_CANON: Record<BookUsfm, Canon> = {
+export const BOOK_CANON: Record<KnownBookUsfm, CanonId> = {
   GEN: 'old_testament',
   EXO: 'old_testament',
   LEV: 'old_testament',

package/src/__tests__/mocks/configuration.ts

@@ -1,53 +0,0 @@
-import { vi } from 'vitest';
-
-/**
- * Creates a mock YouVersionPlatformConfiguration for testing
- * Maintains internal state for access tokens and configuration
- */
-export const createMockPlatformConfiguration = (): {
-  accessToken: string | null;
-  idToken: string | null;
-  refreshToken: string | null;
-  appKey: string;
-  apiHost: string;
-  installationId: string | null;
-  expiryDate: Date | null;
-  clearAuthTokens: ReturnType<typeof vi.fn>;
-  saveAuthData: ReturnType<typeof vi.fn>;
-} => {
-  const config = {
-    accessToken: null as string | null,
-    idToken: null as string | null,
-    refreshToken: null as string | null,
-    appKey: '',
-    apiHost: 'test-api.example.com',
-    installationId: null as string | null,
-    expiryDate: null as Date | null,
-    clearAuthTokens: vi.fn(function (this: typeof config) {
-      this.accessToken = null;
-      this.idToken = null;
-      this.refreshToken = null;
-      this.expiryDate = null;
-    }),
-    saveAuthData: vi.fn(function (
-      this: typeof config,
-      accessToken: string | null,
-      refreshToken: string | null,
-      idToken: string | null,
-      expiryDate?: Date | null,
-    ) {
-      this.accessToken = accessToken;
-      this.refreshToken = refreshToken;
-      this.idToken = idToken;
-      if (expiryDate !== undefined) {
-        this.expiryDate = expiryDate;
-      }
-    }),
-  };
-
-  // Bind methods to maintain context
-  config.clearAuthTokens = config.clearAuthTokens.bind(config);
-  config.saveAuthData = config.saveAuthData.bind(config);
-
-  return config;
-};

package/src/__tests__/mocks/jwt.ts

@@ -1,93 +0,0 @@
-import { vi } from 'vitest';
-
-/**
- * Creates a mock JWT token for testing
- * @param payload The JWT payload to encode
- * @returns A mock JWT string with the format header.payload.signature
- */
-export const createMockJWT = (payload: Record<string, unknown>): string => {
-  // Use a simple encoding for testing (not real base64)
-  const header = 'mockHeader';
-  const body = JSON.stringify(payload);
-  const signature = 'mock-signature';
-  return `${header}.${body}.${signature}`;
-};
-
-/**
- * Creates a realistic-looking JWT token with proper base64url encoding
- * @param payload The JWT payload
- * @returns A properly formatted JWT token
- */
-export const createRealisticJWT = (payload: Record<string, unknown>): string => {
-  const header = { alg: 'HS256', typ: 'JWT' };
-
-  // Simple base64url encoding for testing
-  const base64urlEncode = (str: string) => {
-    if (typeof btoa !== 'undefined') {
-      return btoa(str).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
-    }
-    // Fallback for test environment
-    return Buffer.from(str)
-      .toString('base64')
-      .replace(/=/g, '')
-      .replace(/\+/g, '-')
-      .replace(/\//g, '_');
-  };
-
-  const headerEncoded = base64urlEncode(JSON.stringify(header));
-  const payloadEncoded = base64urlEncode(JSON.stringify(payload));
-  const signature = 'invalid-signature'; // Mock signature
-
-  return `${headerEncoded}.${payloadEncoded}.${signature}`;
-};
-
-/**
- * Sets up JWT-related mocks for atob/btoa functions
- * @param payload The expected JWT payload to decode
- */
-export const setupJWTMocks = (
-  payload: Record<string, unknown> = {},
-): { atob: ReturnType<typeof vi.fn>; btoa: ReturnType<typeof vi.fn> } => {
-  const atobMock = vi.fn((str: string) => {
-    // Handle base64 padding
-    let padded = str;
-    while (padded.length % 4 !== 0) {
-      padded += '=';
-    }
-
-    // For testing, just return the payload
-    if (str.includes('eyJ')) {
-      // Looks like a real base64 JWT part
-      return JSON.stringify(payload);
-    }
-
-    return str;
-  });
-
-  const btoaMock = vi.fn((str: string) => {
-    // Simple base64 encoding for testing
-    return `base64_${str.length}`;
-  });
-
-  vi.stubGlobal('atob', atobMock);
-  vi.stubGlobal('btoa', btoaMock);
-
-  return { atob: atobMock, btoa: btoaMock };
-};
-
-/**
- * Creates a mock JWT with standard claims
- * @param overrides Optional claim overrides
- */
-export const createMockJWTWithClaims = (overrides: Record<string, unknown> = {}): string => {
-  const defaultClaims = {
-    sub: '1234567890',
-    name: 'John Doe',
-    email: 'john@example.com',
-    profile_picture: 'https://example.com/avatar.jpg',
-    iat: 1516239022,
-    exp: 1516242622,
-  };
-
-  return createRealisticJWT({ ...defaultClaims, ...overrides });
-};