@youversion/platform-core 1.16.0 → 1.18.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @youversion/platform-core@1.16.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
+> @youversion/platform-core@1.18.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
 > tsup src/index.ts --format cjs,esm --dts
 
 CLI Building entry: src/index.ts
@@ -8,11 +8,11 @@
 CLI Target: es2022
 CJS Build start
 ESM Build start
-ESM dist/index.js 50.50 KB
-ESM ⚡️ Build success in 51ms
-CJS dist/index.cjs 53.58 KB
-CJS ⚡️ Build success in 51ms
+ESM dist/index.js 53.00 KB
+ESM ⚡️ Build success in 41ms
+CJS dist/index.cjs 56.12 KB
+CJS ⚡️ Build success in 41ms
 DTS Build start
-DTS ⚡️ Build success in 1959ms
-DTS dist/index.d.cts 33.42 KB
-DTS dist/index.d.ts  33.42 KB
+DTS ⚡️ Build success in 1707ms
+DTS dist/index.d.cts 34.06 KB
+DTS dist/index.d.ts  34.06 KB

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @youversion/platform-core
 
+## 1.18.0
+
+### Minor Changes
+
+- b8c6e1b: In our BibleCard component, we've added an error UI to make it more clear when an error has occurred fetching the Bible verse.
+
+## 1.17.1
+
+### Patch Changes
+
+- a7100fd: We've added support for footnotes in Bible book introduction chapters. This is a rare occurance, but an example can be found in Joshua's introduction chapter when using the TPT Bible Version
+
+## 1.17.0
+
+### Minor Changes
+
+- c3d673e: added error ui for faild verses
+
+### Patch Changes
+
+- a5f91bf: Add cross-book chapter navigation to Bible Reader toolbar with prev/next buttons, intro chapter support, and accessible aria-labels
+
 ## 1.16.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -34,7 +34,8 @@ __export(index_exports, {
   YouVersionAPI: () => YouVersionAPI,
   YouVersionAPIUsers: () => YouVersionAPIUsers,
   YouVersionPlatformConfiguration: () => YouVersionPlatformConfiguration,
-  YouVersionUserInfo: () => YouVersionUserInfo
+  YouVersionUserInfo: () => YouVersionUserInfo,
+  getAdjacentChapter: () => getAdjacentChapter
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1663,6 +1664,72 @@ var YouVersionAPI = class {
     return request;
   }
 };
+
+// src/getAdjacentChapter.ts
+function isIntroChapter(chapterId) {
+  return chapterId.toLowerCase().includes("intro");
+}
+function getAdjacentChapter(books, currentBookId, currentChapterId, direction) {
+  if (books.length === 0) return null;
+  const bookIndex = books.findIndex((b) => b.id === currentBookId);
+  if (bookIndex === -1) return null;
+  const book = books[bookIndex];
+  const chapters = book.chapters ?? [];
+  return direction === "next" ? getNext(books, bookIndex, book, chapters, currentChapterId) : getPrevious(books, bookIndex, book, chapters, currentChapterId);
+}
+function getNext(books, bookIndex, book, chapters, currentChapterId) {
+  if (isIntroChapter(currentChapterId)) {
+    const firstCanonical2 = chapters.find((c) => !isIntroChapter(c.id));
+    if (firstCanonical2) {
+      return { bookId: book.id, chapterId: firstCanonical2.id };
+    }
+  }
+  if (!isIntroChapter(currentChapterId)) {
+    const idx = chapters.findIndex((c) => c.id === currentChapterId);
+    if (idx !== -1 && idx < chapters.length - 1) {
+      const next = chapters[idx + 1];
+      if (!isIntroChapter(next.id)) {
+        return { bookId: book.id, chapterId: next.id };
+      }
+    }
+  }
+  const nextBook = books[bookIndex + 1];
+  if (!nextBook) return null;
+  const nextChapters = nextBook.chapters ?? [];
+  const firstCanonical = nextChapters.find((c) => !isIntroChapter(c.id));
+  return firstCanonical ? { bookId: nextBook.id, chapterId: firstCanonical.id } : null;
+}
+function getPrevious(books, bookIndex, book, chapters, currentChapterId) {
+  if (isIntroChapter(currentChapterId)) {
+    return lastCanonicalOfPreviousBook(books, bookIndex);
+  }
+  const idx = chapters.findIndex((c) => c.id === currentChapterId);
+  if (idx === -1) return null;
+  const firstCanonicalIdx = chapters.findIndex((c) => !isIntroChapter(c.id));
+  const isFirstCanonical = idx === firstCanonicalIdx;
+  if (isFirstCanonical) {
+    if (book.intro) {
+      return { bookId: book.id, chapterId: book.intro.id };
+    }
+    return lastCanonicalOfPreviousBook(books, bookIndex);
+  }
+  if (idx > 0) {
+    return { bookId: book.id, chapterId: chapters[idx - 1].id };
+  }
+  return null;
+}
+function lastCanonicalOfPreviousBook(books, bookIndex) {
+  const prevBook = books[bookIndex - 1];
+  if (!prevBook) return null;
+  const prevChapters = prevBook.chapters ?? [];
+  for (let i = prevChapters.length - 1; i >= 0; i--) {
+    const ch = prevChapters[i];
+    if (!isIntroChapter(ch.id)) {
+      return { bookId: prevBook.id, chapterId: ch.id };
+    }
+  }
+  return null;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiClient,
@@ -1679,5 +1746,6 @@ var YouVersionAPI = class {
   YouVersionAPI,
   YouVersionAPIUsers,
   YouVersionPlatformConfiguration,
-  YouVersionUserInfo
+  YouVersionUserInfo,
+  getAdjacentChapter
 });

package/dist/index.d.cts

@@ -731,4 +731,19 @@ declare const BOOK_IDS: readonly ["GEN", "EXO", "LEV", "NUM", "DEU", "JOS", "JDG
  */
 declare const BOOK_CANON: Record<BookUsfm, Canon>;
 
-export { ApiClient, type ApiConfig, type AuthenticationScopes, type AuthenticationState, BOOK_CANON, BOOK_IDS, type BibleBook, type BibleBookIntro, type BibleChapter, BibleClient, type BibleIndex, type BibleIndexBook, type BibleIndexChapter, type BibleIndexVerse, type BiblePassage, type BibleVerse, type BibleVersion, type CANON, type Collection, type CreateHighlight, DEFAULT_LICENSE_FREE_BIBLE_VERSION, type DeleteHighlightOptions, type GetHighlightsOptions, type GetLanguagesOptions, type Highlight, type HighlightColor, HighlightsClient, type Language, LanguagesClient, MemoryStorageStrategy, SessionStorageStrategy, SignInWithYouVersionPermission, type SignInWithYouVersionPermissionValues, SignInWithYouVersionResult, type StorageStrategy, type User, type VOTD, YouVersionAPI, YouVersionAPIUsers, YouVersionPlatformConfiguration, YouVersionUserInfo, type YouVersionUserInfoJSON };
+type AdjacentChapterResult = {
+    bookId: string;
+    chapterId: string;
+} | null;
+/**
+ * Computes the next or previous chapter across book boundaries.
+ *
+ * @param books - Ordered array of Bible books with populated chapters
+ * @param currentBookId - USFM book ID (e.g., "JHN")
+ * @param currentChapterId - Chapter ID string (e.g., "1", "INTRO")
+ * @param direction - Navigation direction
+ * @returns Target book and chapter IDs, or null at Bible boundaries
+ */
+declare function getAdjacentChapter(books: BibleBook[], currentBookId: string, currentChapterId: string, direction: 'next' | 'previous'): AdjacentChapterResult;
+
+export { ApiClient, type ApiConfig, type AuthenticationScopes, type AuthenticationState, BOOK_CANON, BOOK_IDS, type BibleBook, type BibleBookIntro, type BibleChapter, BibleClient, type BibleIndex, type BibleIndexBook, type BibleIndexChapter, type BibleIndexVerse, type BiblePassage, type BibleVerse, type BibleVersion, type CANON, type Collection, type CreateHighlight, DEFAULT_LICENSE_FREE_BIBLE_VERSION, type DeleteHighlightOptions, type GetHighlightsOptions, type GetLanguagesOptions, type Highlight, type HighlightColor, HighlightsClient, type Language, LanguagesClient, MemoryStorageStrategy, SessionStorageStrategy, SignInWithYouVersionPermission, type SignInWithYouVersionPermissionValues, SignInWithYouVersionResult, type StorageStrategy, type User, type VOTD, YouVersionAPI, YouVersionAPIUsers, YouVersionPlatformConfiguration, YouVersionUserInfo, type YouVersionUserInfoJSON, getAdjacentChapter };

package/dist/index.d.ts

@@ -731,4 +731,19 @@ declare const BOOK_IDS: readonly ["GEN", "EXO", "LEV", "NUM", "DEU", "JOS", "JDG
  */
 declare const BOOK_CANON: Record<BookUsfm, Canon>;
 
-export { ApiClient, type ApiConfig, type AuthenticationScopes, type AuthenticationState, BOOK_CANON, BOOK_IDS, type BibleBook, type BibleBookIntro, type BibleChapter, BibleClient, type BibleIndex, type BibleIndexBook, type BibleIndexChapter, type BibleIndexVerse, type BiblePassage, type BibleVerse, type BibleVersion, type CANON, type Collection, type CreateHighlight, DEFAULT_LICENSE_FREE_BIBLE_VERSION, type DeleteHighlightOptions, type GetHighlightsOptions, type GetLanguagesOptions, type Highlight, type HighlightColor, HighlightsClient, type Language, LanguagesClient, MemoryStorageStrategy, SessionStorageStrategy, SignInWithYouVersionPermission, type SignInWithYouVersionPermissionValues, SignInWithYouVersionResult, type StorageStrategy, type User, type VOTD, YouVersionAPI, YouVersionAPIUsers, YouVersionPlatformConfiguration, YouVersionUserInfo, type YouVersionUserInfoJSON };
+type AdjacentChapterResult = {
+    bookId: string;
+    chapterId: string;
+} | null;
+/**
+ * Computes the next or previous chapter across book boundaries.
+ *
+ * @param books - Ordered array of Bible books with populated chapters
+ * @param currentBookId - USFM book ID (e.g., "JHN")
+ * @param currentChapterId - Chapter ID string (e.g., "1", "INTRO")
+ * @param direction - Navigation direction
+ * @returns Target book and chapter IDs, or null at Bible boundaries
+ */
+declare function getAdjacentChapter(books: BibleBook[], currentBookId: string, currentChapterId: string, direction: 'next' | 'previous'): AdjacentChapterResult;
+
+export { ApiClient, type ApiConfig, type AuthenticationScopes, type AuthenticationState, BOOK_CANON, BOOK_IDS, type BibleBook, type BibleBookIntro, type BibleChapter, BibleClient, type BibleIndex, type BibleIndexBook, type BibleIndexChapter, type BibleIndexVerse, type BiblePassage, type BibleVerse, type BibleVersion, type CANON, type Collection, type CreateHighlight, DEFAULT_LICENSE_FREE_BIBLE_VERSION, type DeleteHighlightOptions, type GetHighlightsOptions, type GetLanguagesOptions, type Highlight, type HighlightColor, HighlightsClient, type Language, LanguagesClient, MemoryStorageStrategy, SessionStorageStrategy, SignInWithYouVersionPermission, type SignInWithYouVersionPermissionValues, SignInWithYouVersionResult, type StorageStrategy, type User, type VOTD, YouVersionAPI, YouVersionAPIUsers, YouVersionPlatformConfiguration, YouVersionUserInfo, type YouVersionUserInfoJSON, getAdjacentChapter };

package/dist/index.js

@@ -1623,6 +1623,72 @@ var YouVersionAPI = class {
     return request;
   }
 };
+
+// src/getAdjacentChapter.ts
+function isIntroChapter(chapterId) {
+  return chapterId.toLowerCase().includes("intro");
+}
+function getAdjacentChapter(books, currentBookId, currentChapterId, direction) {
+  if (books.length === 0) return null;
+  const bookIndex = books.findIndex((b) => b.id === currentBookId);
+  if (bookIndex === -1) return null;
+  const book = books[bookIndex];
+  const chapters = book.chapters ?? [];
+  return direction === "next" ? getNext(books, bookIndex, book, chapters, currentChapterId) : getPrevious(books, bookIndex, book, chapters, currentChapterId);
+}
+function getNext(books, bookIndex, book, chapters, currentChapterId) {
+  if (isIntroChapter(currentChapterId)) {
+    const firstCanonical2 = chapters.find((c) => !isIntroChapter(c.id));
+    if (firstCanonical2) {
+      return { bookId: book.id, chapterId: firstCanonical2.id };
+    }
+  }
+  if (!isIntroChapter(currentChapterId)) {
+    const idx = chapters.findIndex((c) => c.id === currentChapterId);
+    if (idx !== -1 && idx < chapters.length - 1) {
+      const next = chapters[idx + 1];
+      if (!isIntroChapter(next.id)) {
+        return { bookId: book.id, chapterId: next.id };
+      }
+    }
+  }
+  const nextBook = books[bookIndex + 1];
+  if (!nextBook) return null;
+  const nextChapters = nextBook.chapters ?? [];
+  const firstCanonical = nextChapters.find((c) => !isIntroChapter(c.id));
+  return firstCanonical ? { bookId: nextBook.id, chapterId: firstCanonical.id } : null;
+}
+function getPrevious(books, bookIndex, book, chapters, currentChapterId) {
+  if (isIntroChapter(currentChapterId)) {
+    return lastCanonicalOfPreviousBook(books, bookIndex);
+  }
+  const idx = chapters.findIndex((c) => c.id === currentChapterId);
+  if (idx === -1) return null;
+  const firstCanonicalIdx = chapters.findIndex((c) => !isIntroChapter(c.id));
+  const isFirstCanonical = idx === firstCanonicalIdx;
+  if (isFirstCanonical) {
+    if (book.intro) {
+      return { bookId: book.id, chapterId: book.intro.id };
+    }
+    return lastCanonicalOfPreviousBook(books, bookIndex);
+  }
+  if (idx > 0) {
+    return { bookId: book.id, chapterId: chapters[idx - 1].id };
+  }
+  return null;
+}
+function lastCanonicalOfPreviousBook(books, bookIndex) {
+  const prevBook = books[bookIndex - 1];
+  if (!prevBook) return null;
+  const prevChapters = prevBook.chapters ?? [];
+  for (let i = prevChapters.length - 1; i >= 0; i--) {
+    const ch = prevChapters[i];
+    if (!isIntroChapter(ch.id)) {
+      return { bookId: prevBook.id, chapterId: ch.id };
+    }
+  }
+  return null;
+}
 export {
   ApiClient,
   BOOK_CANON,
@@ -1638,5 +1704,6 @@ export {
   YouVersionAPI,
   YouVersionAPIUsers,
   YouVersionPlatformConfiguration,
-  YouVersionUserInfo
+  YouVersionUserInfo,
+  getAdjacentChapter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-core",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "type": "module",
   "publishConfig": {
     "access": "public",

package/src/getAdjacentChapter.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from 'vitest';
+import { getAdjacentChapter } from './getAdjacentChapter';
+import type { BibleBook } from './schemas/book';
+
+function makeBook(
+  id: string,
+  chapterCount: number,
+  opts?: { hasIntro?: boolean; introInChapters?: boolean },
+): BibleBook {
+  const chapters = [];
+
+  if (opts?.introInChapters) {
+    chapters.push({ id: 'INTRO', passage_id: `${id}.INTRO`, title: 'Intro' });
+  }
+
+  for (let i = 1; i <= chapterCount; i++) {
+    chapters.push({ id: i.toString(), passage_id: `${id}.${i}`, title: i.toString() });
+  }
+
+  return {
+    id,
+    title: id,
+    full_title: id,
+    canon: 'old_testament',
+    chapters,
+    ...(opts?.hasIntro
+      ? { intro: { id: 'INTRO', passage_id: `${id}.INTRO`, title: 'Intro' } }
+      : {}),
+  } as BibleBook;
+}
+
+const GEN = makeBook('GEN', 50, { hasIntro: true });
+const EXO = makeBook('EXO', 40, { hasIntro: true });
+const LEV = makeBook('LEV', 27);
+const REV = makeBook('REV', 22);
+const books: BibleBook[] = [GEN, EXO, LEV, REV];
+
+describe('getAdjacentChapter', () => {
+  it('next chapter within same book', () => {
+    expect(getAdjacentChapter(books, 'GEN', '1', 'next')).toEqual({
+      bookId: 'GEN',
+      chapterId: '2',
+    });
+  });
+
+  it('next chapter cross-book, skipping intro', () => {
+    expect(getAdjacentChapter(books, 'GEN', '50', 'next')).toEqual({
+      bookId: 'EXO',
+      chapterId: '1',
+    });
+  });
+
+  it('next chapter at Bible end returns null', () => {
+    expect(getAdjacentChapter(books, 'REV', '22', 'next')).toBeNull();
+  });
+
+  it('next from intro → chapter 1 of same book', () => {
+    expect(getAdjacentChapter(books, 'GEN', 'INTRO', 'next')).toEqual({
+      bookId: 'GEN',
+      chapterId: '1',
+    });
+  });
+
+  it('previous chapter within same book', () => {
+    expect(getAdjacentChapter(books, 'GEN', '3', 'previous')).toEqual({
+      bookId: 'GEN',
+      chapterId: '2',
+    });
+  });
+
+  it('previous from chapter 1 when book has intro → intro of same book', () => {
+    expect(getAdjacentChapter(books, 'GEN', '1', 'previous')).toEqual({
+      bookId: 'GEN',
+      chapterId: 'INTRO',
+    });
+  });
+
+  it('previous from chapter 1 when book has no intro → last canonical of previous book', () => {
+    expect(getAdjacentChapter(books, 'LEV', '1', 'previous')).toEqual({
+      bookId: 'EXO',
+      chapterId: '40',
+    });
+  });
+
+  it('previous from intro → last canonical of previous book', () => {
+    expect(getAdjacentChapter(books, 'EXO', 'INTRO', 'previous')).toEqual({
+      bookId: 'GEN',
+      chapterId: '50',
+    });
+  });
+
+  it('previous at Bible start returns null', () => {
+    expect(getAdjacentChapter(books, 'GEN', 'INTRO', 'previous')).toBeNull();
+  });
+
+  it('previous at Bible start (chapter 1, no intro)', () => {
+    const booksNoIntro = [makeBook('GEN', 50), makeBook('EXO', 40)];
+    expect(getAdjacentChapter(booksNoIntro, 'GEN', '1', 'previous')).toBeNull();
+  });
+
+  it('empty books array returns null', () => {
+    expect(getAdjacentChapter([], 'GEN', '1', 'next')).toBeNull();
+  });
+
+  it('current book not found returns null', () => {
+    expect(getAdjacentChapter(books, 'FAKE', '1', 'next')).toBeNull();
+  });
+
+  it('handles intro chapter present in chapters array for next', () => {
+    const booksWithIntroInArray = [
+      makeBook('GEN', 50, { hasIntro: true, introInChapters: true }),
+      makeBook('EXO', 40),
+    ];
+    expect(getAdjacentChapter(booksWithIntroInArray, 'GEN', 'INTRO', 'next')).toEqual({
+      bookId: 'GEN',
+      chapterId: '1',
+    });
+  });
+
+  it('handles intro chapter present in chapters array for previous', () => {
+    const booksWithIntroInArray = [
+      makeBook('GEN', 50, { hasIntro: true, introInChapters: true }),
+      makeBook('EXO', 40, { hasIntro: true, introInChapters: true }),
+    ];
+    expect(getAdjacentChapter(booksWithIntroInArray, 'EXO', '1', 'previous')).toEqual({
+      bookId: 'EXO',
+      chapterId: 'INTRO',
+    });
+  });
+
+  it('cross-book next skips intro in chapters array of next book', () => {
+    const booksWithIntroInArray = [
+      makeBook('GEN', 50),
+      makeBook('EXO', 40, { hasIntro: true, introInChapters: true }),
+    ];
+    expect(getAdjacentChapter(booksWithIntroInArray, 'GEN', '50', 'next')).toEqual({
+      bookId: 'EXO',
+      chapterId: '1',
+    });
+  });
+
+  it('cross-book previous from book without intro goes to last chapter of previous book', () => {
+    const mixed = [
+      makeBook('GEN', 50, { hasIntro: true }),
+      makeBook('EXO', 40),
+      makeBook('LEV', 27, { hasIntro: true }),
+    ];
+    expect(getAdjacentChapter(mixed, 'EXO', '1', 'previous')).toEqual({
+      bookId: 'GEN',
+      chapterId: '50',
+    });
+  });
+});

package/src/getAdjacentChapter.ts

@@ -0,0 +1,121 @@
+import type { BibleBook } from './schemas/book';
+import type { BibleChapter } from './schemas/chapter';
+
+type AdjacentChapterResult = { bookId: string; chapterId: string } | null;
+
+function isIntroChapter(chapterId: string): boolean {
+  return chapterId.toLowerCase().includes('intro');
+}
+
+/**
+ * Computes the next or previous chapter across book boundaries.
+ *
+ * @param books - Ordered array of Bible books with populated chapters
+ * @param currentBookId - USFM book ID (e.g., "JHN")
+ * @param currentChapterId - Chapter ID string (e.g., "1", "INTRO")
+ * @param direction - Navigation direction
+ * @returns Target book and chapter IDs, or null at Bible boundaries
+ */
+export function getAdjacentChapter(
+  books: BibleBook[],
+  currentBookId: string,
+  currentChapterId: string,
+  direction: 'next' | 'previous',
+): AdjacentChapterResult {
+  if (books.length === 0) return null;
+
+  const bookIndex = books.findIndex((b) => b.id === currentBookId);
+  if (bookIndex === -1) return null;
+
+  const book = books[bookIndex]!;
+  const chapters: BibleChapter[] = book.chapters ?? [];
+
+  return direction === 'next'
+    ? getNext(books, bookIndex, book, chapters, currentChapterId)
+    : getPrevious(books, bookIndex, book, chapters, currentChapterId);
+}
+
+function getNext(
+  books: BibleBook[],
+  bookIndex: number,
+  book: BibleBook,
+  chapters: BibleChapter[],
+  currentChapterId: string,
+): AdjacentChapterResult {
+  // Next from intro → chapter 1 of same book
+  if (isIntroChapter(currentChapterId)) {
+    const firstCanonical = chapters.find((c) => !isIntroChapter(c.id));
+    if (firstCanonical) {
+      return { bookId: book.id, chapterId: firstCanonical.id };
+    }
+    // No canonical chapters — fall through to cross-book
+  }
+
+  if (!isIntroChapter(currentChapterId)) {
+    const idx = chapters.findIndex((c) => c.id === currentChapterId);
+    if (idx !== -1 && idx < chapters.length - 1) {
+      const next = chapters[idx + 1]!;
+      if (!isIntroChapter(next.id)) {
+        return { bookId: book.id, chapterId: next.id };
+      }
+    }
+  }
+
+  // Cross-book: first non-intro chapter of next book
+  const nextBook = books[bookIndex + 1];
+  if (!nextBook) return null;
+
+  const nextChapters: BibleChapter[] = nextBook.chapters ?? [];
+  const firstCanonical = nextChapters.find((c) => !isIntroChapter(c.id));
+  return firstCanonical ? { bookId: nextBook.id, chapterId: firstCanonical.id } : null;
+}
+
+function getPrevious(
+  books: BibleBook[],
+  bookIndex: number,
+  book: BibleBook,
+  chapters: BibleChapter[],
+  currentChapterId: string,
+): AdjacentChapterResult {
+  // Previous from intro → last canonical chapter of previous book
+  if (isIntroChapter(currentChapterId)) {
+    return lastCanonicalOfPreviousBook(books, bookIndex);
+  }
+
+  const idx = chapters.findIndex((c) => c.id === currentChapterId);
+  if (idx === -1) return null;
+
+  // Determine if we're on the first canonical chapter
+  const firstCanonicalIdx = chapters.findIndex((c) => !isIntroChapter(c.id));
+  const isFirstCanonical = idx === firstCanonicalIdx;
+
+  if (isFirstCanonical) {
+    // If book has an intro, go to intro
+    if (book.intro) {
+      return { bookId: book.id, chapterId: book.intro.id };
+    }
+    // No intro → cross-book
+    return lastCanonicalOfPreviousBook(books, bookIndex);
+  }
+
+  // Not at first canonical — go to previous chapter in same book
+  if (idx > 0) {
+    return { bookId: book.id, chapterId: chapters[idx - 1]!.id };
+  }
+
+  return null;
+}
+
+function lastCanonicalOfPreviousBook(books: BibleBook[], bookIndex: number): AdjacentChapterResult {
+  const prevBook = books[bookIndex - 1];
+  if (!prevBook) return null;
+
+  const prevChapters: BibleChapter[] = prevBook.chapters ?? [];
+  for (let i = prevChapters.length - 1; i >= 0; i--) {
+    const ch = prevChapters[i]!;
+    if (!isIntroChapter(ch.id)) {
+      return { bookId: prevBook.id, chapterId: ch.id };
+    }
+  }
+  return null;
+}

package/src/index.ts

@@ -14,3 +14,4 @@ export * from './YouVersionAPI';
 export * from './YouVersionPlatformConfiguration';
 export * from './types';
 export * from './utils/constants';
+export { getAdjacentChapter } from './getAdjacentChapter';