@youversion/platform-core 1.0.1 → 1.2.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @youversion/platform-core@1.0.1 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
+> @youversion/platform-core@1.2.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 40.66 KB
-ESM ⚡️ Build success in 45ms
-CJS dist/index.cjs 42.47 KB
-CJS ⚡️ Build success in 47ms
+CJS dist/index.cjs 42.87 KB
+CJS ⚡️ Build success in 31ms
+ESM dist/index.js 41.06 KB
+ESM ⚡️ Build success in 32ms
 DTS Build start
-DTS ⚡️ Build success in 1869ms
-DTS dist/index.d.cts 31.82 KB
-DTS dist/index.d.ts  31.82 KB
+DTS ⚡️ Build success in 1751ms
+DTS dist/index.d.cts 32.80 KB
+DTS dist/index.d.ts  32.80 KB

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @youversion/platform-core
 
+## 1.2.0
+
+### Minor Changes
+
+- a8a5dd7: feat: Add intro metadata to BibleBook
+  - Added optional `intro` field to BibleBook schema for retrieving book introduction metadata
+  - The intro field includes `id`, `passage_id`, and `title` properties when available
+  - Simplified type definitions by removing duplicate type files and using Zod schemas as single source of truth
+  - Updated Bible mocks and tests to cover the new intro field
+
+## 1.1.0
+
+### Minor Changes
+
+- efb1030: feat(core): make data objects that should be immutable readonly
+  - changed data types that come from api responses and should not
+    be mutated to be readonly.
+  - See the documentation on these types, https://developers.youversion.com/sdks/react#referenced-types
+
 ## 1.0.1
 
 ### Patch Changes

package/dist/index.cjs

@@ -232,7 +232,9 @@ var BibleClient = class {
    * Fetches all books for a given Bible version.
    * @param versionId The version ID.
    * @param canon Optional canon filter ("old_testament", 'new_testament', 'deuterocanon').
-   * @returns An array of BibleBook objects.
+   * @returns An array of BibleBook objects. Each book may include an optional `intro` field
+   *          containing metadata (id, passage_id, title) for the book's introduction when
+   *          available in the Bible version.
    */
   async getBooks(versionId, canon) {
     this.versionIdSchema.parse(versionId);
@@ -244,7 +246,9 @@ var BibleClient = class {
    * 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.
+   * @returns The requested BibleBook object, which may include an optional `intro` field
+   *          containing metadata (id, passage_id, title) for the book's introduction when
+   *          available. Use the `passage_id` with `getPassage()` to fetch intro content.
    */
   async getBook(versionId, book) {
     this.versionIdSchema.parse(versionId);

package/dist/index.d.cts

@@ -15,14 +15,20 @@ declare const BibleVersionSchema: z.ZodObject<{
     books: z.ZodArray<z.ZodUnion<readonly [...z.ZodLiteral<"GEN" | "EXO" | "LEV" | "NUM" | "DEU" | "JOS" | "JDG" | "RUT" | "1SA" | "2SA" | "1KI" | "2KI" | "1CH" | "2CH" | "EZR" | "NEH" | "EST" | "JOB" | "PSA" | "PRO" | "ECC" | "SNG" | "ISA" | "JER" | "LAM" | "EZK" | "DAN" | "HOS" | "JOL" | "AMO" | "OBA" | "JON" | "MIC" | "NAM" | "HAB" | "ZEP" | "HAG" | "ZEC" | "MAL" | "MAT" | "MRK" | "LUK" | "JHN" | "ACT" | "ROM" | "1CO" | "2CO" | "GAL" | "EPH" | "PHP" | "COL" | "1TH" | "2TH" | "1TI" | "2TI" | "TIT" | "PHM" | "HEB" | "JAS" | "1PE" | "2PE" | "1JN" | "2JN" | "3JN" | "JUD" | "REV" | "TOB" | "JDT" | "ESG" | "WIS" | "SIR" | "BAR" | "LJE" | "S3Y" | "SUS" | "BEL" | "1MA" | "2MA" | "3MA" | "4MA" | "1ES" | "2ES" | "MAN" | "PS2" | "ODA" | "PSS" | "3ES" | "EZA" | "5EZ" | "6EZ" | "DAG" | "PS3" | "2BA" | "LBA" | "JUB" | "ENO" | "1MQ" | "2MQ" | "3MQ" | "REP" | "4BA" | "LAO" | "LKA">[], z.ZodType<string & {}, unknown, z.core.$ZodTypeInternals<string & {}, unknown>>]>>;
     youversion_deep_link: z.ZodURL;
 }, z.core.$strip>;
-type BibleVersion = z.infer<typeof BibleVersionSchema>;
+type BibleVersion = Readonly<z.infer<typeof BibleVersionSchema>>;
 
 declare const CanonSchema: z.ZodEnum<{
     old_testament: "old_testament";
     new_testament: "new_testament";
     deuterocanon: "deuterocanon";
 }>;
-type Canon = z.infer<typeof CanonSchema>;
+type Canon = Readonly<z.infer<typeof CanonSchema>>;
+declare const BibleBookIntroSchema: z.ZodObject<{
+    id: z.ZodString;
+    passage_id: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>;
+type BibleBookIntro = Readonly<z.infer<typeof BibleBookIntroSchema>>;
 declare const BookUsfmSchema: z.ZodUnion<readonly [...z.ZodLiteral<"GEN" | "EXO" | "LEV" | "NUM" | "DEU" | "JOS" | "JDG" | "RUT" | "1SA" | "2SA" | "1KI" | "2KI" | "1CH" | "2CH" | "EZR" | "NEH" | "EST" | "JOB" | "PSA" | "PRO" | "ECC" | "SNG" | "ISA" | "JER" | "LAM" | "EZK" | "DAN" | "HOS" | "JOL" | "AMO" | "OBA" | "JON" | "MIC" | "NAM" | "HAB" | "ZEP" | "HAG" | "ZEC" | "MAL" | "MAT" | "MRK" | "LUK" | "JHN" | "ACT" | "ROM" | "1CO" | "2CO" | "GAL" | "EPH" | "PHP" | "COL" | "1TH" | "2TH" | "1TI" | "2TI" | "TIT" | "PHM" | "HEB" | "JAS" | "1PE" | "2PE" | "1JN" | "2JN" | "3JN" | "JUD" | "REV" | "TOB" | "JDT" | "ESG" | "WIS" | "SIR" | "BAR" | "LJE" | "S3Y" | "SUS" | "BEL" | "1MA" | "2MA" | "3MA" | "4MA" | "1ES" | "2ES" | "MAN" | "PS2" | "ODA" | "PSS" | "3ES" | "EZA" | "5EZ" | "6EZ" | "DAG" | "PS3" | "2BA" | "LBA" | "JUB" | "ENO" | "1MQ" | "2MQ" | "3MQ" | "REP" | "4BA" | "LAO" | "LKA">[], z.ZodType<string & {}, unknown, z.core.$ZodTypeInternals<string & {}, unknown>>]>;
 type BookUsfm = z.infer<typeof BookUsfmSchema>;
 declare const BibleBookSchema: z.ZodObject<{
@@ -35,6 +41,11 @@ declare const BibleBookSchema: z.ZodObject<{
         new_testament: "new_testament";
         deuterocanon: "deuterocanon";
     }>;
+    intro: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        passage_id: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>>;
     chapters: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         passage_id: z.ZodString;
@@ -46,8 +57,8 @@ declare const BibleBookSchema: z.ZodObject<{
         }, z.core.$strip>>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
-type BibleBook = z.infer<typeof BibleBookSchema>;
-type CANON = z.infer<typeof CanonSchema>;
+type BibleBook = Readonly<z.infer<typeof BibleBookSchema>>;
+type CANON = Readonly<z.infer<typeof CanonSchema>>;
 
 declare const BibleChapterSchema: z.ZodObject<{
     id: z.ZodString;
@@ -59,33 +70,33 @@ declare const BibleChapterSchema: z.ZodObject<{
         title: z.ZodString;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
-type BibleChapter = z.infer<typeof BibleChapterSchema>;
+type BibleChapter = Readonly<z.infer<typeof BibleChapterSchema>>;
 
 declare const BibleVerseSchema: z.ZodObject<{
     id: z.ZodString;
     passage_id: z.ZodString;
     title: z.ZodString;
 }, z.core.$strip>;
-type BibleVerse = z.infer<typeof BibleVerseSchema>;
+type BibleVerse = Readonly<z.infer<typeof BibleVerseSchema>>;
 
 declare const BiblePassageSchema: z.ZodObject<{
     id: z.ZodString;
     content: z.ZodString;
     reference: z.ZodString;
 }, z.core.$strip>;
-type BiblePassage = z.infer<typeof BiblePassageSchema>;
+type BiblePassage = Readonly<z.infer<typeof BiblePassageSchema>>;
 
 declare const VOTDSchema: z.ZodObject<{
     day: z.ZodNumber;
     passage_id: z.ZodString;
 }, z.core.$strip>;
-type VOTD = z.infer<typeof VOTDSchema>;
+type VOTD = Readonly<z.infer<typeof VOTDSchema>>;
 
 declare const BibleIndexVerseSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
 }, z.core.$strip>;
-type BibleIndexVerse = z.infer<typeof BibleIndexVerseSchema>;
+type BibleIndexVerse = Readonly<z.infer<typeof BibleIndexVerseSchema>>;
 declare const BibleIndexChapterSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -94,7 +105,7 @@ declare const BibleIndexChapterSchema: z.ZodObject<{
         title: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-type BibleIndexChapter = z.infer<typeof BibleIndexChapterSchema>;
+type BibleIndexChapter = Readonly<z.infer<typeof BibleIndexChapterSchema>>;
 declare const BibleIndexBookSchema: z.ZodObject<{
     id: z.ZodUnion<readonly [...z.ZodLiteral<"GEN" | "EXO" | "LEV" | "NUM" | "DEU" | "JOS" | "JDG" | "RUT" | "1SA" | "2SA" | "1KI" | "2KI" | "1CH" | "2CH" | "EZR" | "NEH" | "EST" | "JOB" | "PSA" | "PRO" | "ECC" | "SNG" | "ISA" | "JER" | "LAM" | "EZK" | "DAN" | "HOS" | "JOL" | "AMO" | "OBA" | "JON" | "MIC" | "NAM" | "HAB" | "ZEP" | "HAG" | "ZEC" | "MAL" | "MAT" | "MRK" | "LUK" | "JHN" | "ACT" | "ROM" | "1CO" | "2CO" | "GAL" | "EPH" | "PHP" | "COL" | "1TH" | "2TH" | "1TI" | "2TI" | "TIT" | "PHM" | "HEB" | "JAS" | "1PE" | "2PE" | "1JN" | "2JN" | "3JN" | "JUD" | "REV" | "TOB" | "JDT" | "ESG" | "WIS" | "SIR" | "BAR" | "LJE" | "S3Y" | "SUS" | "BEL" | "1MA" | "2MA" | "3MA" | "4MA" | "1ES" | "2ES" | "MAN" | "PS2" | "ODA" | "PSS" | "3ES" | "EZA" | "5EZ" | "6EZ" | "DAG" | "PS3" | "2BA" | "LBA" | "JUB" | "ENO" | "1MQ" | "2MQ" | "3MQ" | "REP" | "4BA" | "LAO" | "LKA">[], z.ZodType<string & {}, unknown, z.core.$ZodTypeInternals<string & {}, unknown>>]>;
     title: z.ZodString;
@@ -114,7 +125,7 @@ declare const BibleIndexBookSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-type BibleIndexBook = z.infer<typeof BibleIndexBookSchema>;
+type BibleIndexBook = Readonly<z.infer<typeof BibleIndexBookSchema>>;
 declare const _BibleIndexSchema: z.ZodObject<{
     text_direction: z.ZodString;
     books: z.ZodArray<z.ZodObject<{
@@ -137,7 +148,7 @@ declare const _BibleIndexSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-type BibleIndex = z.infer<typeof _BibleIndexSchema>;
+type BibleIndex = Readonly<z.infer<typeof _BibleIndexSchema>>;
 
 declare const LanguageSchema: z.ZodObject<{
     id: z.ZodString;
@@ -157,7 +168,7 @@ declare const LanguageSchema: z.ZodObject<{
     speaking_population: z.ZodOptional<z.ZodNumber>;
     default_bible_version_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
-type Language = z.infer<typeof LanguageSchema>;
+type Language = Readonly<z.infer<typeof LanguageSchema>>;
 
 declare const _UserSchema: z.ZodObject<{
     avatar_url: z.ZodString;
@@ -183,11 +194,11 @@ type CreateHighlight = z.infer<typeof _CreateHighlightSchema>;
 /**
  * Generic Collection type for paginated responses
  */
-type Collection<T> = {
+type Collection<T> = Readonly<{
     data: T[];
     next_page_token: string | null;
     total_size?: number;
-};
+}>;
 
 interface ApiConfig {
     apiHost?: string;
@@ -228,12 +239,12 @@ declare class SignInWithYouVersionResult {
 
 type SignInWithYouVersionPermissionValues = (typeof SignInWithYouVersionPermission)[keyof typeof SignInWithYouVersionPermission];
 interface AuthenticationState {
-    isAuthenticated: boolean;
-    isLoading: boolean;
-    accessToken: string | null;
-    idToken: string | null;
-    result: SignInWithYouVersionResult | null;
-    error: Error | null;
+    readonly isAuthenticated: boolean;
+    readonly isLoading: boolean;
+    readonly accessToken: string | null;
+    readonly idToken: string | null;
+    readonly result: SignInWithYouVersionResult | null;
+    readonly error: Error | null;
 }
 type AuthenticationScopes = 'profile' | 'email';
 
@@ -337,14 +348,18 @@ declare class BibleClient {
      * Fetches all books for a given Bible version.
      * @param versionId The version ID.
      * @param canon Optional canon filter ("old_testament", 'new_testament', 'deuterocanon').
-     * @returns An array of BibleBook objects.
+     * @returns An array of BibleBook objects. Each book may include an optional `intro` field
+     *          containing metadata (id, passage_id, title) for the book's introduction when
+     *          available in the Bible version.
      */
     getBooks(versionId: number, canon?: CANON): Promise<Collection<BibleBook>>;
     /**
      * 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.
+     * @returns The requested BibleBook object, which may include an optional `intro` field
+     *          containing metadata (id, passage_id, title) for the book's introduction when
+     *          available. Use the `passage_id` with `getPassage()` to fetch intro content.
      */
     getBook(versionId: number, book: string): Promise<BibleBook>;
     /**
@@ -706,4 +721,4 @@ 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 BibleChapter, BibleClient, type BibleIndex, type BibleIndexBook, type BibleIndexChapter, type BibleIndexVerse, type BiblePassage, type BibleVerse, type BibleVersion, type CANON, type Collection, type CreateHighlight, 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 };
+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, 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 };

package/dist/index.d.ts

@@ -15,14 +15,20 @@ declare const BibleVersionSchema: z.ZodObject<{
     books: z.ZodArray<z.ZodUnion<readonly [...z.ZodLiteral<"GEN" | "EXO" | "LEV" | "NUM" | "DEU" | "JOS" | "JDG" | "RUT" | "1SA" | "2SA" | "1KI" | "2KI" | "1CH" | "2CH" | "EZR" | "NEH" | "EST" | "JOB" | "PSA" | "PRO" | "ECC" | "SNG" | "ISA" | "JER" | "LAM" | "EZK" | "DAN" | "HOS" | "JOL" | "AMO" | "OBA" | "JON" | "MIC" | "NAM" | "HAB" | "ZEP" | "HAG" | "ZEC" | "MAL" | "MAT" | "MRK" | "LUK" | "JHN" | "ACT" | "ROM" | "1CO" | "2CO" | "GAL" | "EPH" | "PHP" | "COL" | "1TH" | "2TH" | "1TI" | "2TI" | "TIT" | "PHM" | "HEB" | "JAS" | "1PE" | "2PE" | "1JN" | "2JN" | "3JN" | "JUD" | "REV" | "TOB" | "JDT" | "ESG" | "WIS" | "SIR" | "BAR" | "LJE" | "S3Y" | "SUS" | "BEL" | "1MA" | "2MA" | "3MA" | "4MA" | "1ES" | "2ES" | "MAN" | "PS2" | "ODA" | "PSS" | "3ES" | "EZA" | "5EZ" | "6EZ" | "DAG" | "PS3" | "2BA" | "LBA" | "JUB" | "ENO" | "1MQ" | "2MQ" | "3MQ" | "REP" | "4BA" | "LAO" | "LKA">[], z.ZodType<string & {}, unknown, z.core.$ZodTypeInternals<string & {}, unknown>>]>>;
     youversion_deep_link: z.ZodURL;
 }, z.core.$strip>;
-type BibleVersion = z.infer<typeof BibleVersionSchema>;
+type BibleVersion = Readonly<z.infer<typeof BibleVersionSchema>>;
 
 declare const CanonSchema: z.ZodEnum<{
     old_testament: "old_testament";
     new_testament: "new_testament";
     deuterocanon: "deuterocanon";
 }>;
-type Canon = z.infer<typeof CanonSchema>;
+type Canon = Readonly<z.infer<typeof CanonSchema>>;
+declare const BibleBookIntroSchema: z.ZodObject<{
+    id: z.ZodString;
+    passage_id: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>;
+type BibleBookIntro = Readonly<z.infer<typeof BibleBookIntroSchema>>;
 declare const BookUsfmSchema: z.ZodUnion<readonly [...z.ZodLiteral<"GEN" | "EXO" | "LEV" | "NUM" | "DEU" | "JOS" | "JDG" | "RUT" | "1SA" | "2SA" | "1KI" | "2KI" | "1CH" | "2CH" | "EZR" | "NEH" | "EST" | "JOB" | "PSA" | "PRO" | "ECC" | "SNG" | "ISA" | "JER" | "LAM" | "EZK" | "DAN" | "HOS" | "JOL" | "AMO" | "OBA" | "JON" | "MIC" | "NAM" | "HAB" | "ZEP" | "HAG" | "ZEC" | "MAL" | "MAT" | "MRK" | "LUK" | "JHN" | "ACT" | "ROM" | "1CO" | "2CO" | "GAL" | "EPH" | "PHP" | "COL" | "1TH" | "2TH" | "1TI" | "2TI" | "TIT" | "PHM" | "HEB" | "JAS" | "1PE" | "2PE" | "1JN" | "2JN" | "3JN" | "JUD" | "REV" | "TOB" | "JDT" | "ESG" | "WIS" | "SIR" | "BAR" | "LJE" | "S3Y" | "SUS" | "BEL" | "1MA" | "2MA" | "3MA" | "4MA" | "1ES" | "2ES" | "MAN" | "PS2" | "ODA" | "PSS" | "3ES" | "EZA" | "5EZ" | "6EZ" | "DAG" | "PS3" | "2BA" | "LBA" | "JUB" | "ENO" | "1MQ" | "2MQ" | "3MQ" | "REP" | "4BA" | "LAO" | "LKA">[], z.ZodType<string & {}, unknown, z.core.$ZodTypeInternals<string & {}, unknown>>]>;
 type BookUsfm = z.infer<typeof BookUsfmSchema>;
 declare const BibleBookSchema: z.ZodObject<{
@@ -35,6 +41,11 @@ declare const BibleBookSchema: z.ZodObject<{
         new_testament: "new_testament";
         deuterocanon: "deuterocanon";
     }>;
+    intro: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        passage_id: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>>;
     chapters: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         passage_id: z.ZodString;
@@ -46,8 +57,8 @@ declare const BibleBookSchema: z.ZodObject<{
         }, z.core.$strip>>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
-type BibleBook = z.infer<typeof BibleBookSchema>;
-type CANON = z.infer<typeof CanonSchema>;
+type BibleBook = Readonly<z.infer<typeof BibleBookSchema>>;
+type CANON = Readonly<z.infer<typeof CanonSchema>>;
 
 declare const BibleChapterSchema: z.ZodObject<{
     id: z.ZodString;
@@ -59,33 +70,33 @@ declare const BibleChapterSchema: z.ZodObject<{
         title: z.ZodString;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
-type BibleChapter = z.infer<typeof BibleChapterSchema>;
+type BibleChapter = Readonly<z.infer<typeof BibleChapterSchema>>;
 
 declare const BibleVerseSchema: z.ZodObject<{
     id: z.ZodString;
     passage_id: z.ZodString;
     title: z.ZodString;
 }, z.core.$strip>;
-type BibleVerse = z.infer<typeof BibleVerseSchema>;
+type BibleVerse = Readonly<z.infer<typeof BibleVerseSchema>>;
 
 declare const BiblePassageSchema: z.ZodObject<{
     id: z.ZodString;
     content: z.ZodString;
     reference: z.ZodString;
 }, z.core.$strip>;
-type BiblePassage = z.infer<typeof BiblePassageSchema>;
+type BiblePassage = Readonly<z.infer<typeof BiblePassageSchema>>;
 
 declare const VOTDSchema: z.ZodObject<{
     day: z.ZodNumber;
     passage_id: z.ZodString;
 }, z.core.$strip>;
-type VOTD = z.infer<typeof VOTDSchema>;
+type VOTD = Readonly<z.infer<typeof VOTDSchema>>;
 
 declare const BibleIndexVerseSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
 }, z.core.$strip>;
-type BibleIndexVerse = z.infer<typeof BibleIndexVerseSchema>;
+type BibleIndexVerse = Readonly<z.infer<typeof BibleIndexVerseSchema>>;
 declare const BibleIndexChapterSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -94,7 +105,7 @@ declare const BibleIndexChapterSchema: z.ZodObject<{
         title: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-type BibleIndexChapter = z.infer<typeof BibleIndexChapterSchema>;
+type BibleIndexChapter = Readonly<z.infer<typeof BibleIndexChapterSchema>>;
 declare const BibleIndexBookSchema: z.ZodObject<{
     id: z.ZodUnion<readonly [...z.ZodLiteral<"GEN" | "EXO" | "LEV" | "NUM" | "DEU" | "JOS" | "JDG" | "RUT" | "1SA" | "2SA" | "1KI" | "2KI" | "1CH" | "2CH" | "EZR" | "NEH" | "EST" | "JOB" | "PSA" | "PRO" | "ECC" | "SNG" | "ISA" | "JER" | "LAM" | "EZK" | "DAN" | "HOS" | "JOL" | "AMO" | "OBA" | "JON" | "MIC" | "NAM" | "HAB" | "ZEP" | "HAG" | "ZEC" | "MAL" | "MAT" | "MRK" | "LUK" | "JHN" | "ACT" | "ROM" | "1CO" | "2CO" | "GAL" | "EPH" | "PHP" | "COL" | "1TH" | "2TH" | "1TI" | "2TI" | "TIT" | "PHM" | "HEB" | "JAS" | "1PE" | "2PE" | "1JN" | "2JN" | "3JN" | "JUD" | "REV" | "TOB" | "JDT" | "ESG" | "WIS" | "SIR" | "BAR" | "LJE" | "S3Y" | "SUS" | "BEL" | "1MA" | "2MA" | "3MA" | "4MA" | "1ES" | "2ES" | "MAN" | "PS2" | "ODA" | "PSS" | "3ES" | "EZA" | "5EZ" | "6EZ" | "DAG" | "PS3" | "2BA" | "LBA" | "JUB" | "ENO" | "1MQ" | "2MQ" | "3MQ" | "REP" | "4BA" | "LAO" | "LKA">[], z.ZodType<string & {}, unknown, z.core.$ZodTypeInternals<string & {}, unknown>>]>;
     title: z.ZodString;
@@ -114,7 +125,7 @@ declare const BibleIndexBookSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-type BibleIndexBook = z.infer<typeof BibleIndexBookSchema>;
+type BibleIndexBook = Readonly<z.infer<typeof BibleIndexBookSchema>>;
 declare const _BibleIndexSchema: z.ZodObject<{
     text_direction: z.ZodString;
     books: z.ZodArray<z.ZodObject<{
@@ -137,7 +148,7 @@ declare const _BibleIndexSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-type BibleIndex = z.infer<typeof _BibleIndexSchema>;
+type BibleIndex = Readonly<z.infer<typeof _BibleIndexSchema>>;
 
 declare const LanguageSchema: z.ZodObject<{
     id: z.ZodString;
@@ -157,7 +168,7 @@ declare const LanguageSchema: z.ZodObject<{
     speaking_population: z.ZodOptional<z.ZodNumber>;
     default_bible_version_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
-type Language = z.infer<typeof LanguageSchema>;
+type Language = Readonly<z.infer<typeof LanguageSchema>>;
 
 declare const _UserSchema: z.ZodObject<{
     avatar_url: z.ZodString;
@@ -183,11 +194,11 @@ type CreateHighlight = z.infer<typeof _CreateHighlightSchema>;
 /**
  * Generic Collection type for paginated responses
  */
-type Collection<T> = {
+type Collection<T> = Readonly<{
     data: T[];
     next_page_token: string | null;
     total_size?: number;
-};
+}>;
 
 interface ApiConfig {
     apiHost?: string;
@@ -228,12 +239,12 @@ declare class SignInWithYouVersionResult {
 
 type SignInWithYouVersionPermissionValues = (typeof SignInWithYouVersionPermission)[keyof typeof SignInWithYouVersionPermission];
 interface AuthenticationState {
-    isAuthenticated: boolean;
-    isLoading: boolean;
-    accessToken: string | null;
-    idToken: string | null;
-    result: SignInWithYouVersionResult | null;
-    error: Error | null;
+    readonly isAuthenticated: boolean;
+    readonly isLoading: boolean;
+    readonly accessToken: string | null;
+    readonly idToken: string | null;
+    readonly result: SignInWithYouVersionResult | null;
+    readonly error: Error | null;
 }
 type AuthenticationScopes = 'profile' | 'email';
 
@@ -337,14 +348,18 @@ declare class BibleClient {
      * Fetches all books for a given Bible version.
      * @param versionId The version ID.
      * @param canon Optional canon filter ("old_testament", 'new_testament', 'deuterocanon').
-     * @returns An array of BibleBook objects.
+     * @returns An array of BibleBook objects. Each book may include an optional `intro` field
+     *          containing metadata (id, passage_id, title) for the book's introduction when
+     *          available in the Bible version.
      */
     getBooks(versionId: number, canon?: CANON): Promise<Collection<BibleBook>>;
     /**
      * 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.
+     * @returns The requested BibleBook object, which may include an optional `intro` field
+     *          containing metadata (id, passage_id, title) for the book's introduction when
+     *          available. Use the `passage_id` with `getPassage()` to fetch intro content.
      */
     getBook(versionId: number, book: string): Promise<BibleBook>;
     /**
@@ -706,4 +721,4 @@ 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 BibleChapter, BibleClient, type BibleIndex, type BibleIndexBook, type BibleIndexChapter, type BibleIndexVerse, type BiblePassage, type BibleVerse, type BibleVersion, type CANON, type Collection, type CreateHighlight, 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 };
+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, 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 };

package/dist/index.js

@@ -193,7 +193,9 @@ var BibleClient = class {
    * Fetches all books for a given Bible version.
    * @param versionId The version ID.
    * @param canon Optional canon filter ("old_testament", 'new_testament', 'deuterocanon').
-   * @returns An array of BibleBook objects.
+   * @returns An array of BibleBook objects. Each book may include an optional `intro` field
+   *          containing metadata (id, passage_id, title) for the book's introduction when
+   *          available in the Bible version.
    */
   async getBooks(versionId, canon) {
     this.versionIdSchema.parse(versionId);
@@ -205,7 +207,9 @@ var BibleClient = class {
    * 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.
+   * @returns The requested BibleBook object, which may include an optional `intro` field
+   *          containing metadata (id, passage_id, title) for the book's introduction when
+   *          available. Use the `passage_id` with `getPassage()` to fetch intro content.
    */
   async getBook(versionId, book) {
     this.versionIdSchema.parse(versionId);

package/package.json

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

package/src/__tests__/MockBibles.ts

@@ -1,36 +1,13 @@
 import { mockGenesisChapters } from './MockChapters';
 
-export const mockBibleGenesis = {
-  id: 'GEN',
-  title: 'Genesis',
-  full_title: 'The First Book of Moses, Called Genesis',
-  abbreviation: 'Gen',
-  canon: 'old_testament',
-  chapters: mockGenesisChapters,
-};
-export const mockBibleBooks = [
+const baseBibleBooks = [
   {
     id: 'GEN',
     title: 'Genesis',
     full_title: 'The First Book of Moses, Called Genesis',
     abbreviation: 'Gen',
     canon: 'old_testament',
-    chapters: Array.from({ length: 50 }, (_, i) => {
-      const chapterNumber = i + 1;
-      return {
-        id: chapterNumber.toString(),
-        passage_id: `GEN.${chapterNumber}`,
-        title: chapterNumber.toString(),
-        verses: Array.from({ length: 31 }, (_, j) => {
-          const verseNumber = j + 1;
-          return {
-            id: verseNumber.toString(),
-            passage_id: `GEN.${chapterNumber}.${verseNumber}`,
-            title: verseNumber.toString(),
-          };
-        }),
-      };
-    }),
+    chapters: mockGenesisChapters,
   },
   {
     id: 'EXO',
@@ -1528,3 +1505,15 @@ export const mockBibleBooks = [
     }),
   },
 ];
+
+const addIntro = <T extends { id: string }>(book: T) => ({
+  ...book,
+  intro: {
+    id: 'INTRO',
+    passage_id: `${book.id}.INTRO`,
+    title: 'Intro',
+  },
+});
+
+export const mockBibleBooks = baseBibleBooks.map(addIntro);
+export const mockBibleGenesis = mockBibleBooks[0];

package/src/__tests__/bible.test.ts

@@ -77,6 +77,11 @@ describe('BibleClient', () => {
       expect(books.data[0]).toHaveProperty('title', 'Genesis');
       expect(books.data[0]).toHaveProperty('full_title', 'The First Book of Moses, Called Genesis');
       expect(books.data[0]).toHaveProperty('abbreviation', 'Gen');
+      expect(books.data[0]?.intro).toEqual({
+        id: 'INTRO',
+        passage_id: 'GEN.INTRO',
+        title: 'Intro',
+      });
       expect(books.data[0]).toHaveProperty('canon', 'old_testament');
       expect(books.data[0]?.chapters).toHaveLength(50);
     });
@@ -93,6 +98,12 @@ describe('BibleClient', () => {
       expect(book).toHaveProperty('id', 'GEN');
       expect(book).toHaveProperty('title', 'Genesis');
       expect(book).toHaveProperty('abbreviation', 'Gen');
+      expect(book).toHaveProperty('intro');
+      expect(book.intro).toEqual({
+        id: 'INTRO',
+        passage_id: 'GEN.INTRO',
+        title: 'Intro',
+      });
       expect(book).toHaveProperty('canon', 'old_testament');
     });
 

package/src/bible.ts

@@ -82,7 +82,9 @@ export class BibleClient {
    * Fetches all books for a given Bible version.
    * @param versionId The version ID.
    * @param canon Optional canon filter ("old_testament", 'new_testament', 'deuterocanon').
-   * @returns An array of BibleBook objects.
+   * @returns An array of BibleBook objects. Each book may include an optional `intro` field
+   *          containing metadata (id, passage_id, title) for the book's introduction when
+   *          available in the Bible version.
    */
   async getBooks(versionId: number, canon?: CANON): Promise<Collection<BibleBook>> {
     this.versionIdSchema.parse(versionId);
@@ -95,7 +97,9 @@ export class BibleClient {
    * 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.
+   * @returns The requested BibleBook object, which may include an optional `intro` field
+   *          containing metadata (id, passage_id, title) for the book's introduction when
+   *          available. Use the `passage_id` with `getPassage()` to fetch intro content.
    */
   async getBook(versionId: number, book: string): Promise<BibleBook> {
     this.versionIdSchema.parse(versionId);

package/src/schemas/bible-index.ts

@@ -8,7 +8,7 @@ const BibleIndexVerseSchema = z.object({
   title: z.string(),
 });
 
-export type BibleIndexVerse = z.infer<typeof BibleIndexVerseSchema>;
+export type BibleIndexVerse = Readonly<z.infer<typeof BibleIndexVerseSchema>>;
 
 const BibleIndexChapterSchema = z.object({
   /** Chapter identifier */
@@ -19,7 +19,7 @@ const BibleIndexChapterSchema = z.object({
   verses: z.array(BibleIndexVerseSchema),
 });
 
-export type BibleIndexChapter = z.infer<typeof BibleIndexChapterSchema>;
+export type BibleIndexChapter = Readonly<z.infer<typeof BibleIndexChapterSchema>>;
 
 const BibleIndexBookSchema = z.object({
   /** Book identifier */
@@ -36,7 +36,7 @@ const BibleIndexBookSchema = z.object({
   chapters: z.array(BibleIndexChapterSchema),
 });
 
-export type BibleIndexBook = z.infer<typeof BibleIndexBookSchema>;
+export type BibleIndexBook = Readonly<z.infer<typeof BibleIndexBookSchema>>;
 
 const _BibleIndexSchema = z.object({
   /** Text direction (e.g., "ltr") */
@@ -45,4 +45,4 @@ const _BibleIndexSchema = z.object({
   books: z.array(BibleIndexBookSchema),
 });
 
-export type BibleIndex = z.infer<typeof _BibleIndexSchema>;
+export type BibleIndex = Readonly<z.infer<typeof _BibleIndexSchema>>;

package/src/schemas/book.ts

@@ -3,7 +3,17 @@ import { BOOK_IDS } from '../utils/constants';
 import { BibleChapterSchema } from './chapter';
 
 export const CanonSchema = z.enum(['old_testament', 'new_testament', 'deuterocanon']);
-export type Canon = z.infer<typeof CanonSchema>;
+export type Canon = Readonly<z.infer<typeof CanonSchema>>;
+
+export const BibleBookIntroSchema = z.object({
+  /** Intro identifier */
+  id: z.string(),
+  /** Intro passage identifier */
+  passage_id: z.string(),
+  /** Intro title */
+  title: z.string(),
+});
+export type BibleBookIntro = Readonly<z.infer<typeof BibleBookIntroSchema>>;
 
 // https://github.com/colinhacks/zod/discussions/4934#discussioncomment-13858053
 export const BookUsfmSchema = z.union([
@@ -23,9 +33,11 @@ export const BibleBookSchema = z.object({
   abbreviation: z.string().optional(),
   /** Canonical section (new_testament, old_testament, deuterocanon) */
   canon: CanonSchema,
+  /** Intro metadata (optional) */
+  intro: BibleBookIntroSchema.optional(),
   /** Array of chapter identifiers (e.g., ["GEN.1", "GEN.2", "GEN.3"]) */
   chapters: z.array(BibleChapterSchema).optional(),
 });
 
-export type BibleBook = z.infer<typeof BibleBookSchema>;
-export type CANON = z.infer<typeof CanonSchema>;
+export type BibleBook = Readonly<z.infer<typeof BibleBookSchema>>;
+export type CANON = Readonly<z.infer<typeof CanonSchema>>;

package/src/schemas/chapter.ts

@@ -12,4 +12,4 @@ export const BibleChapterSchema = z.object({
   verses: z.array(BibleVerseSchema).optional(),
 });
 
-export type BibleChapter = z.infer<typeof BibleChapterSchema>;
+export type BibleChapter = Readonly<z.infer<typeof BibleChapterSchema>>;

package/src/schemas/collection.ts

@@ -21,8 +21,8 @@ const _CollectionSchema = <T extends z.ZodTypeAny>(
 /**
  * Generic Collection type for paginated responses
  */
-export type Collection<T> = {
+export type Collection<T> = Readonly<{
   data: T[];
   next_page_token: string | null;
   total_size?: number;
-};
+}>;

package/src/schemas/language.ts

@@ -35,4 +35,4 @@ export const LanguageSchema = z.object({
   default_bible_version_id: z.number().int().nullable().optional(),
 });
 
-export type Language = z.infer<typeof LanguageSchema>;
+export type Language = Readonly<z.infer<typeof LanguageSchema>>;

package/src/schemas/passage.ts

@@ -9,4 +9,4 @@ export const BiblePassageSchema = z.object({
   reference: z.string(),
 });
 
-export type BiblePassage = z.infer<typeof BiblePassageSchema>;
+export type BiblePassage = Readonly<z.infer<typeof BiblePassageSchema>>;

package/src/schemas/verse.ts

@@ -9,4 +9,4 @@ export const BibleVerseSchema = z.object({
   title: z.string(),
 });
 
-export type BibleVerse = z.infer<typeof BibleVerseSchema>;
+export type BibleVerse = Readonly<z.infer<typeof BibleVerseSchema>>;

package/src/schemas/version.ts

@@ -30,4 +30,4 @@ export const BibleVersionSchema = z.object({
   youversion_deep_link: z.url(),
 });
 
-export type BibleVersion = z.infer<typeof BibleVersionSchema>;
+export type BibleVersion = Readonly<z.infer<typeof BibleVersionSchema>>;

package/src/schemas/votd.ts

@@ -7,4 +7,4 @@ export const VOTDSchema = z.object({
   passage_id: z.string(),
 });
 
-export type VOTD = z.infer<typeof VOTDSchema>;
+export type VOTD = Readonly<z.infer<typeof VOTDSchema>>;

package/src/types/auth.ts

@@ -7,12 +7,12 @@ export type SignInWithYouVersionPermissionValues =
   (typeof SignInWithYouVersionPermission)[keyof typeof SignInWithYouVersionPermission];
 
 export interface AuthenticationState {
-  isAuthenticated: boolean;
-  isLoading: boolean;
-  accessToken: string | null;
-  idToken: string | null;
-  result: SignInWithYouVersionResult | null;
-  error: Error | null;
+  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';

package/src/types/index.ts

@@ -1,6 +1,6 @@
 // Re-export all schema-derived types from schemas
 export type { BibleVersion } from '../schemas/version';
-export type { BibleBook, CANON } from '../schemas/book';
+export type { BibleBook, BibleBookIntro, CANON } from '../schemas/book';
 export type { BibleChapter } from '../schemas/chapter';
 export type { BibleVerse } from '../schemas/verse';
 export type { BiblePassage } from '../schemas/passage';

package/src/types/book.ts

@@ -1,116 +0,0 @@
-export type BibleBook = {
-  id: BOOK_ID; // Book identifier (USFM)
-  title: string;
-  abbreviation?: string; // Book name abbreviation if provided by publisher
-  canon: CANON;
-  // eslint-disable-next-line @typescript-eslint/array-type -- Array<> syntax required for template literal type to represent chapter references
-  chapters?: Array<`${BOOK_ID}.${number | `INTRO${number}`}`>; // Ordered list of chapter ids for given Bible and book (e.g., ["GEN.1", "GEN.2", "3JN.INTRO1", "3JN.1"])
-};
-
-export type BOOK_ID =
-  | 'GEN'
-  | 'EXO'
-  | 'LEV'
-  | 'NUM'
-  | 'DEU'
-  | 'JOS'
-  | 'JDG'
-  | 'RUT'
-  | '1SA'
-  | '2SA'
-  | '1KI'
-  | '2KI'
-  | '1CH'
-  | '2CH'
-  | 'EZR'
-  | 'NEH'
-  | 'EST'
-  | 'JOB'
-  | 'PSA'
-  | 'PRO'
-  | 'ECC'
-  | 'SNG'
-  | 'ISA'
-  | 'JER'
-  | 'LAM'
-  | 'EZK'
-  | 'DAN'
-  | 'HOS'
-  | 'JOL'
-  | 'AMO'
-  | 'OBA'
-  | 'JON'
-  | 'MIC'
-  | 'NAM'
-  | 'HAB'
-  | 'ZEP'
-  | 'HAG'
-  | 'ZEC'
-  | 'MAL'
-  | 'MAT'
-  | 'MRK'
-  | 'LUK'
-  | 'JHN'
-  | 'ACT'
-  | 'ROM'
-  | '1CO'
-  | '2CO'
-  | 'GAL'
-  | 'EPH'
-  | 'PHP'
-  | 'COL'
-  | '1TH'
-  | '2TH'
-  | '1TI'
-  | '2TI'
-  | 'TIT'
-  | 'PHM'
-  | 'HEB'
-  | 'JAS'
-  | '1PE'
-  | '2PE'
-  | '1JN'
-  | '2JN'
-  | '3JN'
-  | 'JUD'
-  | 'REV'
-  | 'TOB'
-  | 'JDT'
-  | 'ESG'
-  | 'WIS'
-  | 'SIR'
-  | 'BAR'
-  | 'LJE'
-  | 'S3Y'
-  | 'SUS'
-  | 'BEL'
-  | '1MA'
-  | '2MA'
-  | '3MA'
-  | '4MA'
-  | '1ES'
-  | '2ES'
-  | 'MAN'
-  | 'PS2'
-  | 'ODA'
-  | 'PSS'
-  | '3ES'
-  | 'EZA'
-  | '5EZ'
-  | '6EZ'
-  | 'DAG'
-  | 'PS3'
-  | '2BA'
-  | 'LBA'
-  | 'JUB'
-  | 'ENO'
-  | '1MQ'
-  | '2MQ'
-  | '3MQ'
-  | 'REP'
-  | '4BA'
-  | 'LAO'
-  | 'LKA'
-  | (string & {});
-
-export type CANON = 'old_testament' | 'new_testament' | 'deuterocanon';

package/src/types/chapter.ts

@@ -1,5 +0,0 @@
-export type BibleChapter = {
-  usfm: string;
-  title: string;
-  content?: string;
-};