@youversion/platform-react-hooks 1.8.0 → 1.9.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @youversion/platform-react-hooks@1.8.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/hooks
+> @youversion/platform-react-hooks@1.9.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/hooks
 > tsc -p tsconfig.build.json
 

package/AGENTS.md

@@ -0,0 +1,183 @@
+# @youversion/platform-react-hooks
+
+## OVERVIEW
+React integration layer providing data fetching hooks with 3 core providers: YouVersionProvider, YouVersionAuthProvider, and ReaderProvider.
+
+**Depends on `@youversion/platform-core` for all API calls.** Hooks delegate to core clients; do not implement raw HTTP here.
+
+**Related packages:**
+- For lower-level API clients → see `packages/core/AGENTS.md`
+- For pre-built UI components → see `packages/ui/AGENTS.md`
+
+## STRUCTURE
+- `use*.ts` - Data fetching hooks (useBook, useChapter, usePassage, useVersion, etc.)
+- `context/` - Providers and contexts (separate files, exported via index.ts)
+- `utility/` - Helper functions (useDebounce, extractTextFromHTML, extractVersesFromHTML)
+
+## PUBLIC API
+- Data fetching hooks: useBook, useChapter, usePassage, useVersion, useVOTD, useVerse, useChapterNavigation, etc.
+- YouVersionProvider - Core SDK configuration
+- YouVersionAuthProvider - Authentication state
+- ReaderProvider - Reading session context
+- Utility functions exported from utility/index
+
+## PROVIDERS
+
+- **YouVersionProvider**
+  - Holds core SDK configuration (API base URL, clients)
+  - Wrap this around your app before using any data hooks
+
+- **YouVersionAuthProvider**
+  - Manages authentication state (userInfo, tokens, isLoading, error)
+  - Auth hooks like `useYVAuth` depend on this provider
+
+- **ReaderProvider**
+  - Manages Bible reading session state (currentVersion, currentChapter, currentBook, currentVerse)
+  - Hooks like `useChapterNavigation` depend on this provider
+
+## DOs / DON'Ts
+
+✅ Do: Use `YouVersionProvider` for configuration and access that config in hooks
+✅ Do: Wrap async data access in hooks rather than calling core clients directly in components
+✅ Do: Keep hooks **UI-agnostic** (no JSX returned, no direct DOM manipulation)
+✅ Do: Use the `useApiData` pattern for new data fetching hooks
+
+❌ Don't: Import components from `@youversion/platform-react-ui`
+❌ Don't: Talk directly to `fetch`/HTTP; always use `@youversion/platform-core`
+❌ Don't: Access `window.localStorage` directly for auth; rely on core's storage abstractions
+
+## DATA FETCHING PATTERN
+
+Hooks use a custom React Query-like pattern via `useApiData`:
+- Returns `{ data, loading, error, refetch }`
+- Provides caching and refetch capability
+- New hooks should follow this same pattern
+
+## CONVENTIONS
+- Context and Provider in separate files
+- All contexts exported via context/index.ts
+- TypeScript declarations generated separately (no bundling)
+- Build: tsc only
+
+## USAGE EXAMPLES
+
+### Provider Setup (Required)
+
+```tsx
+// Wrap your app with YouVersionProvider before using any hooks
+import { YouVersionProvider } from '@youversion/platform-react-hooks';
+
+function App() {
+  return (
+    <YouVersionProvider
+      appKey="your-app-key"
+      theme="light"                      // "light" | "dark"
+    >
+      <MyApp />
+    </YouVersionProvider>
+  );
+}
+
+// With authentication enabled
+function AppWithAuth() {
+  return (
+    <YouVersionProvider
+      appKey="your-app-key"
+      includeAuth={true}
+      authRedirectUrl="https://myapp.com/callback"
+    >
+      <MyApp />
+    </YouVersionProvider>
+  );
+}
+```
+
+### Data Fetching Hooks
+
+All data hooks return `{ data, loading, error, refetch }`:
+
+```tsx
+import { useChapter, useVersion, useVerseOfTheDay } from '@youversion/platform-react-hooks';
+
+// Fetch a Bible chapter
+function ChapterView() {
+  const { chapter, loading, error } = useChapter(
+    111,      // versionId (e.g., 111 = NIV)
+    'JHN',    // book (USFM abbreviation)
+    3         // chapter number
+  );
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  return <div>{chapter?.content}</div>;
+}
+
+// Fetch Bible version metadata
+function VersionInfo() {
+  const { version, loading } = useVersion(111);
+  if (loading) return <div>Loading...</div>;
+  return <div>{version?.name} ({version?.abbreviation})</div>;
+}
+
+// Fetch Verse of the Day
+function DailyVerse() {
+  const dayOfYear = Math.floor((Date.now() - new Date(new Date().getFullYear(), 0, 0).getTime()) / 86400000);
+  const { data: votd, loading, refetch } = useVerseOfTheDay(dayOfYear);
+
+  if (loading) return <div>Loading...</div>;
+  return (
+    <div>
+      <p>{votd?.verse.text}</p>
+      <button onClick={refetch}>Refresh</button>
+    </div>
+  );
+}
+```
+
+### Authentication Hook
+
+```tsx
+import { useYVAuth } from '@youversion/platform-react-hooks';
+
+function AuthExample() {
+  const { auth, userInfo, signIn, signOut } = useYVAuth();
+
+  if (auth.isLoading) return <div>Loading...</div>;
+
+  if (!auth.isAuthenticated) {
+    return (
+      <button onClick={() => signIn({ redirectUrl: window.location.origin + '/callback' })}>
+        Sign In with YouVersion
+      </button>
+    );
+  }
+
+  return (
+    <div>
+      <p>Welcome, {userInfo?.name}!</p>
+      <button onClick={signOut}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+### Conditional Fetching
+
+```tsx
+// Use the `enabled` option to conditionally fetch
+function ConditionalFetch({ versionId }: { versionId: number | null }) {
+  const { version, loading } = useVersion(versionId ?? 0, {
+    enabled: versionId !== null,  // Only fetch when versionId is provided
+  });
+
+  // ...
+}
+```
+
+## TESTING
+
+- Run tests: `pnpm --filter @youversion/platform-react-hooks test`
+- Framework: Vitest with jsdom environment
+- React Testing Library for component/hook tests
+- Mock object factories live in `__tests__/mocks` (not MSW - hooks delegate HTTP to core)
+- Use provider wrappers for tests so hooks see the same context as in the app

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @youversion/platform-react-hooks
 
+## 1.9.0
+
+### Minor Changes
+
+- d4b0071: feat(hooks): Add useLanguage hook to retrieve a language from api
+
+### Patch Changes
+
+- Updated dependencies [d4b0071]
+  - @youversion/platform-core@1.9.0
+
+## 1.8.1
+
+### Patch Changes
+
+- 607be3c: Refactor verse HTML transformation to support verse-level highlighting. Extract HTML processing logic to `verse-html-utils.ts` with new `wrapVerseContent()` function that wraps verse content in CSS-targetable `<span class="yv-v">` elements. Simplify footnote extraction using wrapped verse structure. Remove CSS rule preventing text wrapping. Add comprehensive test coverage for verse wrapping behavior.
+- Updated dependencies [607be3c]
+  - @youversion/platform-core@1.8.1
+
 ## 1.8.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from './usePassage';
 export * from './useVOTD';
 export * from './useHighlights';
 export * from './useLanguages';
+export * from './useLanguage';
 export * from './useTheme';
 export * from './useYVAuth';
 export * from './types/auth';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAG3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAG3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -18,6 +18,7 @@ export * from './usePassage';
 export * from './useVOTD';
 export * from './useHighlights';
 export * from './useLanguages';
+export * from './useLanguage';
 export * from './useTheme';
 // Auth hooks
 export * from './useYVAuth';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAE3B,aAAa;AACb,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAE3B,aAAa;AACb,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/useLanguage.d.ts

@@ -0,0 +1,9 @@
+import { type UseApiDataOptions } from './useApiData';
+import { type Language } from '@youversion/platform-core';
+export declare function useLanguage(languageId: string, apiOptions?: UseApiDataOptions): {
+    language: Language | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => void;
+};
+//# sourceMappingURL=useLanguage.d.ts.map

package/dist/useLanguage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLanguage.d.ts","sourceRoot":"","sources":["../src/useLanguage.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAG1D,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,iBAAiB,GAC7B;IACD,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAiBA"}

package/dist/useLanguage.js

@@ -0,0 +1,17 @@
+'use client';
+import { useApiData } from './useApiData';
+import {} from '@youversion/platform-core';
+import { useLanguagesClient } from './useLanguageClient';
+export function useLanguage(languageId, apiOptions) {
+    const languagesClient = useLanguagesClient();
+    const { data, loading, error, refetch } = useApiData(() => languagesClient.getLanguage(languageId), [languagesClient, languageId], {
+        enabled: apiOptions?.enabled !== false,
+    });
+    return {
+        language: data,
+        loading,
+        error,
+        refetch,
+    };
+}
+//# sourceMappingURL=useLanguage.js.map

package/dist/useLanguage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLanguage.js","sourceRoot":"","sources":["../src/useLanguage.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,UAAU,EAA0B,MAAM,cAAc,CAAC;AAClE,OAAO,EAAiB,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,UAAU,WAAW,CACzB,UAAkB,EAClB,UAA8B;IAO9B,MAAM,eAAe,GAAG,kBAAkB,EAAE,CAAC;IAE7C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,UAAU,CAClD,GAAG,EAAE,CAAC,eAAe,CAAC,WAAW,CAAC,UAAU,CAAC,EAC7C,CAAC,eAAe,EAAE,UAAU,CAAC,EAC7B;QACE,OAAO,EAAE,UAAU,EAAE,OAAO,KAAK,KAAK;KACvC,CACF,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,OAAO;QACP,KAAK;QACL,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/useLanguageClient.d.ts

@@ -0,0 +1,3 @@
+import { LanguagesClient } from '@youversion/platform-core';
+export declare function useLanguagesClient(): LanguagesClient;
+//# sourceMappingURL=useLanguageClient.d.ts.map

package/dist/useLanguageClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLanguageClient.d.ts","sourceRoot":"","sources":["../src/useLanguageClient.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEvE,wBAAgB,kBAAkB,IAAI,eAAe,CAkBpD"}

package/dist/useLanguageClient.js

@@ -0,0 +1,18 @@
+'use client';
+import { useContext, useMemo } from 'react';
+import { YouVersionContext } from './context';
+import { ApiClient, LanguagesClient } from '@youversion/platform-core';
+export function useLanguagesClient() {
+    const context = useContext(YouVersionContext);
+    return useMemo(() => {
+        if (!context?.appKey) {
+            throw new Error('YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.');
+        }
+        return new LanguagesClient(new ApiClient({
+            appKey: context.appKey,
+            apiHost: context.apiHost,
+            installationId: context.installationId,
+        }));
+    }, [context?.apiHost, context?.appKey, context?.installationId]);
+}
+//# sourceMappingURL=useLanguageClient.js.map

package/dist/useLanguageClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLanguageClient.js","sourceRoot":"","sources":["../src/useLanguageClient.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,UAAU,kBAAkB;IAChC,MAAM,OAAO,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAE9C,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,uHAAuH,CACxH,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,eAAe,CACxB,IAAI,SAAS,CAAC;YACZ,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc,EAAE,OAAO,CAAC,cAAc;SACvC,CAAC,CACH,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;AACnE,CAAC"}

package/dist/useLanguages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLanguages.d.ts","sourceRoot":"","sources":["../src/useLanguages.ts"],"names":[],"mappings":"AAMA,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,2BAA2B,CAAC;AAEnC,wBAAgB,YAAY,CAC1B,OAAO,GAAE,mBAAwB,EACjC,UAAU,CAAC,EAAE,iBAAiB,GAC7B;IACD,SAAS,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAgCA"}
+{"version":3,"file":"useLanguages.d.ts","sourceRoot":"","sources":["../src/useLanguages.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,2BAA2B,CAAC;AAGnC,wBAAgB,YAAY,CAC1B,OAAO,GAAE,mBAAwB,EACjC,UAAU,CAAC,EAAE,iBAAiB,GAC7B;IACD,SAAS,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAiBA"}

package/dist/useLanguages.js

@@ -1,22 +1,9 @@
 'use client';
-import { useMemo } from 'react';
-import { useContext } from 'react';
-import { YouVersionContext } from './context';
-import { LanguagesClient, ApiClient } from '@youversion/platform-core';
 import { useApiData } from './useApiData';
 import {} from '@youversion/platform-core';
+import { useLanguagesClient } from './useLanguageClient';
 export function useLanguages(options = {}, apiOptions) {
-    const context = useContext(YouVersionContext);
-    const languagesClient = useMemo(() => {
-        if (!context?.appKey) {
-            throw new Error('YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.');
-        }
-        return new LanguagesClient(new ApiClient({
-            appKey: context.appKey,
-            apiHost: context.apiHost,
-            installationId: context.installationId,
-        }));
-    }, [context?.apiHost, context?.appKey, context?.installationId]);
+    const languagesClient = useLanguagesClient();
     const { data, loading, error, refetch } = useApiData(() => languagesClient.getLanguages(options), [languagesClient, options?.country, options?.page_size, options?.page_token], {
         enabled: apiOptions?.enabled !== false,
     });

package/dist/useLanguages.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLanguages.js","sourceRoot":"","sources":["../src/useLanguages.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,UAAU,EAA0B,MAAM,cAAc,CAAC;AAClE,OAAO,EAIN,MAAM,2BAA2B,CAAC;AAEnC,MAAM,UAAU,YAAY,CAC1B,UAA+B,EAAE,EACjC,UAA8B;IAO9B,MAAM,OAAO,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAE9C,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,EAAE;QACnC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,uHAAuH,CACxH,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,eAAe,CACxB,IAAI,SAAS,CAAC;YACZ,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc,EAAE,OAAO,CAAC,cAAc;SACvC,CAAC,CACH,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;IAEjE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,UAAU,CAClD,GAAG,EAAE,CAAC,eAAe,CAAC,YAAY,CAAC,OAAO,CAAC,EAC3C,CAAC,eAAe,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,EAC5E;QACE,OAAO,EAAE,UAAU,EAAE,OAAO,KAAK,KAAK;KACvC,CACF,CAAC;IAEF,OAAO;QACL,SAAS,EAAE,IAAI;QACf,OAAO;QACP,KAAK;QACL,OAAO;KACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"useLanguages.js","sourceRoot":"","sources":["../src/useLanguages.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,UAAU,EAA0B,MAAM,cAAc,CAAC;AAClE,OAAO,EAIN,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,UAAU,YAAY,CAC1B,UAA+B,EAAE,EACjC,UAA8B;IAO9B,MAAM,eAAe,GAAG,kBAAkB,EAAE,CAAC;IAE7C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,UAAU,CAClD,GAAG,EAAE,CAAC,eAAe,CAAC,YAAY,CAAC,OAAO,CAAC,EAC3C,CAAC,eAAe,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,EAC5E;QACE,OAAO,EAAE,UAAU,EAAE,OAAO,KAAK,KAAK;KACvC,CACF,CAAC;IAEF,OAAO;QACL,SAAS,EAAE,IAAI;QACf,OAAO;QACP,KAAK;QACL,OAAO;KACR,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-react-hooks",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "@youversion/platform-core": "1.8.0"
+    "@youversion/platform-core": "1.9.0"
   },
   "peerDependencies": {
     "react": ">=19.1.0 <20.0.0"
@@ -37,8 +37,8 @@
     "jsdom": "27.0.1",
     "typescript": "5.9.3",
     "vitest": "4.0.4",
-    "@internal/eslint-config": "0.0.0",
-    "@internal/tsconfig": "0.0.0"
+    "@internal/tsconfig": "0.0.0",
+    "@internal/eslint-config": "0.0.0"
   },
   "scripts": {
     "dev": "tsc --watch",

package/src/index.ts

@@ -18,6 +18,7 @@ export * from './usePassage';
 export * from './useVOTD';
 export * from './useHighlights';
 export * from './useLanguages';
+export * from './useLanguage';
 export * from './useTheme';
 
 // Auth hooks

package/src/useLanguage.test.tsx

@@ -0,0 +1,116 @@
+import { renderHook, waitFor, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { useLanguage } from './useLanguage';
+import { type LanguagesClient } from '@youversion/platform-core';
+import { useLanguagesClient } from './useLanguageClient';
+
+vi.mock('./useLanguageClient');
+
+describe('useLanguage', () => {
+  const mockGetLanguage = vi.fn();
+
+  const mockLanguage = {
+    id: 'en',
+    language: 'en',
+    script: 'Latn',
+    script_name: 'Latin',
+    aliases: ['eng'],
+    display_names: { en: 'English' },
+    scripts: ['Latn'],
+    variants: [],
+    countries: ['US', 'GB', 'CA', 'AU'],
+    text_direction: 'ltr',
+    writing_population: 1500000000,
+    speaking_population: 1500000000,
+    default_bible_id: 111,
+  };
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    mockGetLanguage.mockResolvedValue(mockLanguage);
+
+    const mockClient: Partial<LanguagesClient> = { getLanguage: mockGetLanguage };
+    vi.mocked(useLanguagesClient).mockReturnValue(mockClient as LanguagesClient);
+  });
+
+  describe('fetching language', () => {
+    it('should fetch a language by id', async () => {
+      const { result } = renderHook(() => useLanguage('en'));
+
+      expect(result.current.loading).toBe(true);
+      expect(result.current.language).toBe(null);
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguage).toHaveBeenCalledWith('en');
+      expect(result.current.language).toEqual(mockLanguage);
+    });
+
+    it('should refetch when languageId changes', async () => {
+      const { result, rerender } = renderHook(({ languageId }) => useLanguage(languageId), {
+        initialProps: { languageId: 'en' },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguage).toHaveBeenCalledTimes(1);
+      expect(mockGetLanguage).toHaveBeenCalledWith('en');
+
+      rerender({ languageId: 'es' });
+
+      await waitFor(() => {
+        expect(mockGetLanguage).toHaveBeenCalledTimes(2);
+      });
+
+      expect(mockGetLanguage).toHaveBeenLastCalledWith('es');
+    });
+
+    it('should not fetch when enabled is false', async () => {
+      const { result } = renderHook(() => useLanguage('en', { enabled: false }));
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguage).not.toHaveBeenCalled();
+      expect(result.current.language).toBe(null);
+    });
+
+    it('should handle fetch errors', async () => {
+      const error = new Error('Failed to fetch language');
+      mockGetLanguage.mockRejectedValueOnce(error);
+
+      const { result } = renderHook(() => useLanguage('en'));
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+      expect(result.current.language).toBe(null);
+    });
+
+    it('should support manual refetch', async () => {
+      const { result } = renderHook(() => useLanguage('en'));
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguage).toHaveBeenCalledTimes(1);
+
+      act(() => {
+        result.current.refetch();
+      });
+
+      await waitFor(() => {
+        expect(mockGetLanguage).toHaveBeenCalledTimes(2);
+      });
+    });
+  });
+});

package/src/useLanguage.ts

@@ -0,0 +1,32 @@
+'use client';
+
+import { useApiData, type UseApiDataOptions } from './useApiData';
+import { type Language } from '@youversion/platform-core';
+import { useLanguagesClient } from './useLanguageClient';
+
+export function useLanguage(
+  languageId: string,
+  apiOptions?: UseApiDataOptions,
+): {
+  language: Language | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const languagesClient = useLanguagesClient();
+
+  const { data, loading, error, refetch } = useApiData<Language>(
+    () => languagesClient.getLanguage(languageId),
+    [languagesClient, languageId],
+    {
+      enabled: apiOptions?.enabled !== false,
+    },
+  );
+
+  return {
+    language: data,
+    loading,
+    error,
+    refetch,
+  };
+}

package/src/useLanguageClient.test.tsx

@@ -0,0 +1,112 @@
+import { renderHook } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ReactNode } from 'react';
+import { useLanguagesClient } from './useLanguageClient';
+import { YouVersionContext } from './context';
+import { LanguagesClient, ApiClient } from '@youversion/platform-core';
+
+// Mock the core package
+vi.mock('@youversion/platform-core', async () => {
+  const actual = await vi.importActual('@youversion/platform-core');
+  return {
+    ...actual,
+    LanguagesClient: vi.fn(function () {
+      return {};
+    }),
+    ApiClient: vi.fn(function () {
+      return { isApiClient: true };
+    }),
+  };
+});
+
+describe('useLanguagesClient', () => {
+  const mockAppKey = 'test-app-key';
+
+  const createWrapper = (contextValue: { appKey: string }) => {
+    return ({ children }: { children: ReactNode }) => (
+      <YouVersionContext.Provider value={contextValue}>{children}</YouVersionContext.Provider>
+    );
+  };
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    vi.mocked(LanguagesClient).mockImplementation(function () {
+      const mockClient: Partial<LanguagesClient> = { getLanguages: vi.fn() };
+      return mockClient;
+    });
+
+    vi.mocked(ApiClient).mockImplementation(function () {
+      const mockApiClient = { isApiClient: true };
+      return mockApiClient;
+    });
+  });
+
+  describe('context validation', () => {
+    it('should throw error when context is not provided', () => {
+      expect(() => renderHook(() => useLanguagesClient())).toThrow(
+        'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
+      );
+    });
+
+    it('should throw error when appKey is missing', () => {
+      const wrapper = createWrapper({
+        appKey: '',
+      });
+
+      expect(() => renderHook(() => useLanguagesClient(), { wrapper })).toThrow(
+        'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
+      );
+    });
+  });
+
+  describe('client creation', () => {
+    it('should create LanguagesClient with correct ApiClient config', () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      renderHook(() => useLanguagesClient(), { wrapper });
+
+      expect(ApiClient).toHaveBeenCalledWith({
+        appKey: mockAppKey,
+      });
+      expect(LanguagesClient).toHaveBeenCalledWith(expect.objectContaining({ isApiClient: true }));
+    });
+
+    it('should memoize LanguagesClient instance', () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { rerender } = renderHook(() => useLanguagesClient(), { wrapper });
+
+      rerender();
+
+      expect(LanguagesClient).toHaveBeenCalledTimes(1);
+    });
+
+    it('should create new LanguagesClient when context values change', () => {
+      let currentAppKey = mockAppKey;
+
+      const wrapper = ({ children }: { children: ReactNode }) => (
+        <YouVersionContext.Provider
+          value={{
+            appKey: currentAppKey,
+          }}
+        >
+          {children}
+        </YouVersionContext.Provider>
+      );
+
+      const { rerender } = renderHook(() => useLanguagesClient(), { wrapper });
+
+      expect(LanguagesClient).toHaveBeenCalledTimes(1);
+
+      currentAppKey = 'new-app-key';
+      rerender();
+
+      expect(LanguagesClient).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/src/useLanguageClient.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import { useContext, useMemo } from 'react';
+import { YouVersionContext } from './context';
+import { ApiClient, LanguagesClient } from '@youversion/platform-core';
+
+export function useLanguagesClient(): LanguagesClient {
+  const context = useContext(YouVersionContext);
+
+  return useMemo(() => {
+    if (!context?.appKey) {
+      throw new Error(
+        'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
+      );
+    }
+
+    return new LanguagesClient(
+      new ApiClient({
+        appKey: context.appKey,
+        apiHost: context.apiHost,
+        installationId: context.installationId,
+      }),
+    );
+  }, [context?.apiHost, context?.appKey, context?.installationId]);
+}

package/src/useLanguages.test.tsx

@@ -1,32 +1,21 @@
 import { renderHook, waitFor } from '@testing-library/react';
-import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 import type { ReactNode } from 'react';
 import { useLanguages } from './useLanguages';
 import { YouVersionContext } from './context';
 import {
-  LanguagesClient,
-  ApiClient,
+  type LanguagesClient,
   type Collection,
   type Language,
   type GetLanguagesOptions,
 } from '@youversion/platform-core';
+import { useLanguagesClient } from './useLanguageClient';
 
-// Mock the core package
-vi.mock('@youversion/platform-core', async () => {
-  const actual = await vi.importActual('@youversion/platform-core');
-  return {
-    ...actual,
-    LanguagesClient: vi.fn(function () {
-      return {};
-    }),
-    ApiClient: vi.fn(function () {
-      return { isApiClient: true };
-    }),
-  };
-});
+vi.mock('./useLanguageClient');
 
 describe('useLanguages', () => {
   const mockAppKey = 'test-app-key';
+  const mockGetLanguages = vi.fn();
 
   const mockLanguages: Collection<Language> = {
     data: [
@@ -46,7 +35,7 @@ describe('useLanguages', () => {
         text_direction: 'ltr',
         writing_population: 370000000,
         speaking_population: 1500000000,
-        default_bible_version_id: 1,
+        default_bible_id: 1,
       },
       {
         id: 'es',
@@ -64,14 +53,12 @@ describe('useLanguages', () => {
         text_direction: 'ltr',
         writing_population: 470000000,
         speaking_population: 580000000,
-        default_bible_version_id: 128,
+        default_bible_id: 128,
       },
     ],
     next_page_token: null,
   };
 
-  let mockGetLanguages: Mock;
-
   const createWrapper = (contextValue: { appKey: string }) => {
     return ({ children }: { children: ReactNode }) => (
       <YouVersionContext.Provider value={contextValue}>{children}</YouVersionContext.Provider>
@@ -79,91 +66,12 @@ describe('useLanguages', () => {
   };
 
   beforeEach(() => {
-    vi.clearAllMocks();
+    vi.resetAllMocks();
 
-    mockGetLanguages = vi.fn().mockResolvedValue(mockLanguages);
-
-    (LanguagesClient as unknown as ReturnType<typeof vi.fn>).mockImplementation(function () {
-      return {
-        getLanguages: mockGetLanguages,
-      };
-    });
+    mockGetLanguages.mockResolvedValue(mockLanguages);
 
-    (ApiClient as unknown as ReturnType<typeof vi.fn>).mockImplementation(function () {
-      return {
-        isApiClient: true,
-      };
-    });
-  });
-
-  describe('context validation', () => {
-    it('should throw error when context is not provided', () => {
-      expect(() => renderHook(() => useLanguages({ country: 'US' }))).toThrow(
-        'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
-      );
-    });
-
-    it('should throw error when appKey is missing', () => {
-      const wrapper = createWrapper({
-        appKey: '',
-      });
-
-      expect(() => renderHook(() => useLanguages({ country: 'US' }), { wrapper })).toThrow(
-        'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
-      );
-    });
-  });
-
-  describe('client creation', () => {
-    it('should create LanguagesClient with correct ApiClient config', () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
-      renderHook(() => useLanguages({ country: 'US' }), { wrapper });
-
-      expect(ApiClient).toHaveBeenCalledWith({
-        appKey: mockAppKey,
-      });
-      expect(LanguagesClient).toHaveBeenCalledWith(expect.objectContaining({ isApiClient: true }));
-    });
-
-    it('should memoize LanguagesClient instance', () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
-      const { result, rerender } = renderHook(() => useLanguages({ country: 'US' }), { wrapper });
-      const _firstRefetch = result.current.refetch;
-
-      rerender();
-      const _secondRefetch = result.current.refetch;
-
-      expect(LanguagesClient).toHaveBeenCalledTimes(1);
-    });
-
-    it('should create new LanguagesClient when context values change', () => {
-      let currentAppKey = mockAppKey;
-
-      const wrapper = ({ children }: { children: ReactNode }) => (
-        <YouVersionContext.Provider
-          value={{
-            appKey: currentAppKey,
-          }}
-        >
-          {children}
-        </YouVersionContext.Provider>
-      );
-
-      const { rerender } = renderHook(() => useLanguages({ country: 'US' }), { wrapper });
-
-      expect(LanguagesClient).toHaveBeenCalledTimes(1);
-
-      currentAppKey = 'new-app-key';
-      rerender();
-
-      expect(LanguagesClient).toHaveBeenCalledTimes(2);
-    });
+    const mockClient: Partial<LanguagesClient> = { getLanguages: mockGetLanguages };
+    vi.mocked(useLanguagesClient).mockReturnValue(mockClient as LanguagesClient);
   });
 
   describe('fetching languages', () => {

package/src/useLanguages.ts

@@ -1,15 +1,12 @@
 'use client';
 
-import { useMemo } from 'react';
-import { useContext } from 'react';
-import { YouVersionContext } from './context';
-import { LanguagesClient, ApiClient } from '@youversion/platform-core';
 import { useApiData, type UseApiDataOptions } from './useApiData';
 import {
   type GetLanguagesOptions,
   type Collection,
   type Language,
 } from '@youversion/platform-core';
+import { useLanguagesClient } from './useLanguageClient';
 
 export function useLanguages(
   options: GetLanguagesOptions = {},
@@ -20,22 +17,7 @@ export function useLanguages(
   error: Error | null;
   refetch: () => void;
 } {
-  const context = useContext(YouVersionContext);
-
-  const languagesClient = useMemo(() => {
-    if (!context?.appKey) {
-      throw new Error(
-        'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
-      );
-    }
-    return new LanguagesClient(
-      new ApiClient({
-        appKey: context.appKey,
-        apiHost: context.apiHost,
-        installationId: context.installationId,
-      }),
-    );
-  }, [context?.apiHost, context?.appKey, context?.installationId]);
+  const languagesClient = useLanguagesClient();
 
   const { data, loading, error, refetch } = useApiData<Collection<Language>>(
     () => languagesClient.getLanguages(options),

package/vitest.config.ts

@@ -11,6 +11,8 @@ export default defineConfig({
       provider: 'v8',
       reporter: ['text', 'json-summary'],
       reportsDirectory: './coverage',
+      all: true,
+      include: ['src/**/*.{ts,tsx}'],
     },
   },
 });