@youversion/platform-core 1.1.0 → 1.2.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @youversion/platform-core@1.1.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
+> @youversion/platform-core@1.2.1 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
-CJS dist/index.cjs 42.47 KB
-CJS ⚡️ Build success in 31ms
-ESM dist/index.js 40.66 KB
-ESM ⚡️ Build success in 31ms
+ESM dist/index.js 41.09 KB
+ESM ⚡️ Build success in 34ms
+CJS dist/index.cjs 42.90 KB
+CJS ⚡️ Build success in 34ms
 DTS Build start
-DTS ⚡️ Build success in 1861ms
-DTS dist/index.d.cts 32.01 KB
-DTS dist/index.d.ts  32.01 KB
+DTS ⚡️ Build success in 2020ms
+DTS dist/index.d.cts 32.78 KB
+DTS dist/index.d.ts  32.78 KB

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @youversion/platform-core
 
+## 1.2.1
+
+### Patch Changes
+
+- e845974: fix: make country parameter optional for getLanguages
+
+  The country parameter is now optional when fetching languages, allowing developers to retrieve all available languages without filtering by country. This improves developer experience by providing a more flexible API while maintaining backward compatibility for existing code that provides a country filter.
+
+## 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

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);
@@ -405,13 +409,15 @@ var LanguagesClient = class {
   }
   /**
    * Fetches a collection of languages supported in the Platform.
-   * @param options Query parameters for pagination and filtering (country is required).
+   * @param options Query parameters for pagination and filtering.
    * @returns A collection of Language objects.
    */
-  async getLanguages(options) {
+  async getLanguages(options = {}) {
     const params = {};
-    const country = this.countrySchema.parse(options.country);
-    params.country = country;
+    if (options.country !== void 0) {
+      const country = this.countrySchema.parse(options.country);
+      params.country = country;
+    }
     if (options.page_size !== void 0) {
       const pageSizeSchema = import_zod2.z.number().int().positive();
       pageSizeSchema.parse(options.page_size);

package/dist/index.d.cts

@@ -23,6 +23,12 @@ declare const CanonSchema: z.ZodEnum<{
     deuterocanon: "deuterocanon";
 }>;
 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;
@@ -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>;
     /**
@@ -434,7 +449,7 @@ declare class BibleClient {
 type GetLanguagesOptions = {
     page_size?: number;
     page_token?: string;
-    country: string;
+    country?: string;
 };
 /**
  * Client for interacting with Languages API endpoints.
@@ -450,10 +465,10 @@ declare class LanguagesClient {
     constructor(client: ApiClient);
     /**
      * Fetches a collection of languages supported in the Platform.
-     * @param options Query parameters for pagination and filtering (country is required).
+     * @param options Query parameters for pagination and filtering.
      * @returns A collection of Language objects.
      */
-    getLanguages(options: GetLanguagesOptions): Promise<Collection<Language>>;
+    getLanguages(options?: GetLanguagesOptions): Promise<Collection<Language>>;
     /**
      * Fetches details about a specific language in the Platform.
      * @param languageId The BCP 47 language code (optionally including script, e.g., "en" or "sr-Latn").
@@ -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

@@ -23,6 +23,12 @@ declare const CanonSchema: z.ZodEnum<{
     deuterocanon: "deuterocanon";
 }>;
 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;
@@ -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>;
     /**
@@ -434,7 +449,7 @@ declare class BibleClient {
 type GetLanguagesOptions = {
     page_size?: number;
     page_token?: string;
-    country: string;
+    country?: string;
 };
 /**
  * Client for interacting with Languages API endpoints.
@@ -450,10 +465,10 @@ declare class LanguagesClient {
     constructor(client: ApiClient);
     /**
      * Fetches a collection of languages supported in the Platform.
-     * @param options Query parameters for pagination and filtering (country is required).
+     * @param options Query parameters for pagination and filtering.
      * @returns A collection of Language objects.
      */
-    getLanguages(options: GetLanguagesOptions): Promise<Collection<Language>>;
+    getLanguages(options?: GetLanguagesOptions): Promise<Collection<Language>>;
     /**
      * Fetches details about a specific language in the Platform.
      * @param languageId The BCP 47 language code (optionally including script, e.g., "en" or "sr-Latn").
@@ -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);
@@ -366,13 +370,15 @@ var LanguagesClient = class {
   }
   /**
    * Fetches a collection of languages supported in the Platform.
-   * @param options Query parameters for pagination and filtering (country is required).
+   * @param options Query parameters for pagination and filtering.
    * @returns A collection of Language objects.
    */
-  async getLanguages(options) {
+  async getLanguages(options = {}) {
     const params = {};
-    const country = this.countrySchema.parse(options.country);
-    params.country = country;
+    if (options.country !== void 0) {
+      const country = this.countrySchema.parse(options.country);
+      params.country = country;
+    }
     if (options.page_size !== void 0) {
       const pageSizeSchema = z2.number().int().positive();
       pageSizeSchema.parse(options.page_size);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-core",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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__/{MockLangauges.ts → MockLanguages.ts}

@@ -76,8 +76,8 @@ export const mockLanguages: Language[] = [
     speaking_population: 8000000,
     default_bible_version_id: null,
   },
-  // Add more languages to reach 25 for default page size when filtering by 'US'
-  ...Array.from({ length: 24 }, (_, i) => ({
+  // Add more languages to exceed the maximum page size and exercise pagination
+  ...Array.from({ length: 120 }, (_, i) => ({
     id: `lang${i + 1}`,
     language: `lang${i + 1}`,
     script: 'Latn',
@@ -86,7 +86,7 @@ export const mockLanguages: Language[] = [
     display_names: {},
     scripts: ['Latn'],
     variants: [],
-    countries: ['US'],
+    countries: i % 2 === 0 ? ['US', 'CA'] : ['BR'],
     text_direction: 'ltr' as const,
     writing_population: 1000000,
     speaking_population: 1000000,

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/__tests__/handlers.ts

@@ -1,6 +1,6 @@
 import { http, HttpResponse } from 'msw';
 import type { Collection, Highlight, Language } from '../types';
-import { mockLanguages } from './MockLangauges';
+import { mockLanguages } from './MockLanguages';
 import { mockVersions, mockVersionKJV } from './MockVersions';
 import { mockBibleGenesis, mockBibleBooks } from './MockBibles';
 import { mockChapterGenesis1, mockGenesisChapters } from './MockChapters';

package/src/__tests__/languages.test.ts

@@ -17,22 +17,23 @@ describe('LanguagesClient', () => {
   });
 
   describe('getLanguages', () => {
-    it('should fetch languages with required country param', async () => {
-      const languages = await languagesClient.getLanguages({ country: 'US' });
+    it('should fetch languages without country filter', async () => {
+      const languages = await languagesClient.getLanguages({ page_size: 99 });
 
       const { success } = LanguageSchema.safeParse(languages.data[0]);
       expect(success).toBe(true);
-      expect(languages.data).toHaveLength(25);
-      expect(languages.data[0]).toHaveProperty('countries', expect.arrayContaining(['US']));
+      expect(languages.data).toHaveLength(99);
+      expect(languages.next_page_token).not.toBeNull();
     });
 
-    it('should fetch languages with page_size option', async () => {
-      const languages = await languagesClient.getLanguages({ country: 'US', page_size: 10 });
+    it('should fetch languages with country filter', async () => {
+      const languages = await languagesClient.getLanguages({ country: 'US', page_size: 20 });
 
       const { success } = LanguageSchema.safeParse(languages.data[0]);
       expect(success).toBe(true);
-      expect(languages.data).toHaveLength(10);
-      expect(languages.next_page_token).toBe('eyJzdGFydCI6IDEwfQ==');
+      expect(languages.data).toHaveLength(20);
+      expect(languages.data.every((language) => language.countries?.includes('US'))).toBe(true);
+      expect(languages.next_page_token).not.toBeNull();
     });
 
     it('should throw an error for invalid country code - empty string', async () => {

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/languages.ts

@@ -8,7 +8,7 @@ import type { Collection, Language } from './types';
 export type GetLanguagesOptions = {
   page_size?: number;
   page_token?: string;
-  country: string; // ISO 3166-1 alpha-2 country code (required per OpenAPI spec)
+  country?: string; // ISO 3166-1 alpha-2 country code
 };
 
 /**
@@ -41,15 +41,16 @@ export class LanguagesClient {
 
   /**
    * Fetches a collection of languages supported in the Platform.
-   * @param options Query parameters for pagination and filtering (country is required).
+   * @param options Query parameters for pagination and filtering.
    * @returns A collection of Language objects.
    */
-  async getLanguages(options: GetLanguagesOptions): Promise<Collection<Language>> {
+  async getLanguages(options: GetLanguagesOptions = {}): Promise<Collection<Language>> {
     const params: Record<string, string | number> = {};
 
-    // Country is required per OpenAPI spec
-    const country = this.countrySchema.parse(options.country);
-    params.country = country;
+    if (options.country !== undefined) {
+      const country = this.countrySchema.parse(options.country);
+      params.country = country;
+    }
 
     if (options.page_size !== undefined) {
       const pageSizeSchema = z.number().int().positive();

package/src/schemas/book.ts

@@ -5,6 +5,16 @@ import { BibleChapterSchema } from './chapter';
 export const CanonSchema = z.enum(['old_testament', 'new_testament', 'deuterocanon']);
 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([
   ...BOOK_IDS.map((id) => z.literal(id)),
@@ -23,6 +33,8 @@ 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(),
 });

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 = Readonly<{
-  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 = Readonly<{
-  usfm: string;
-  title: string;
-  content?: string;
-}>;