@youversion/platform-react-hooks 0.4.1

package/src/useLanguages.test.tsx

@@ -0,0 +1,296 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import type { ReactNode } from 'react';
+import { useLanguages } from './useLanguages';
+import { BibleSDKContext } from './context';
+import {
+  LanguagesClient,
+  ApiClient,
+  type Collection,
+  type Language,
+  type GetLanguagesOptions,
+} 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 };
+    }),
+    YouVersionPlatformConfiguration: {
+      get installationId() {
+        return 'auto-generated-uuid';
+      },
+    },
+  };
+});
+
+describe('useLanguages', () => {
+  const mockAppId = 'test-app-id';
+
+  const mockLanguages: Collection<Language> = {
+    data: [
+      {
+        id: 'en',
+        language: 'en',
+        script: null,
+        script_name: null,
+        aliases: [],
+        display_names: {
+          en: 'English',
+          es: 'Inglés',
+        },
+        scripts: ['Latn'],
+        variants: [],
+        countries: ['US'],
+        text_direction: 'ltr',
+        writing_population: 370000000,
+        speaking_population: 1500000000,
+        default_bible_version_id: 1,
+      },
+      {
+        id: 'es',
+        language: 'es',
+        script: null,
+        script_name: null,
+        aliases: [],
+        display_names: {
+          en: 'Spanish',
+          es: 'Español',
+        },
+        scripts: ['Latn'],
+        variants: [],
+        countries: ['ES'],
+        text_direction: 'ltr',
+        writing_population: 470000000,
+        speaking_population: 580000000,
+        default_bible_version_id: 128,
+      },
+    ],
+    next_page_token: null,
+  };
+
+  let mockGetLanguages: Mock;
+
+  const createWrapper = (contextValue: { appId: string }) => {
+    return ({ children }: { children: ReactNode }) => (
+      <BibleSDKContext.Provider value={contextValue}>{children}</BibleSDKContext.Provider>
+    );
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    mockGetLanguages = vi.fn().mockResolvedValue(mockLanguages);
+
+    (LanguagesClient as unknown as ReturnType<typeof vi.fn>).mockImplementation(function () {
+      return {
+        getLanguages: mockGetLanguages,
+      };
+    });
+
+    (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(
+        'BibleSDK context not found. Make sure your component is wrapped with BibleSDKProvider and an API key is provided.',
+      );
+    });
+
+    it('should throw error when appId is missing', () => {
+      const wrapper = createWrapper({
+        appId: '',
+      });
+
+      expect(() => renderHook(() => useLanguages({ country: 'US' }), { wrapper })).toThrow(
+        'BibleSDK context not found. Make sure your component is wrapped with BibleSDKProvider and an API key is provided.',
+      );
+    });
+  });
+
+  describe('client creation', () => {
+    it('should create LanguagesClient with correct ApiClient config', () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      renderHook(() => useLanguages({ country: 'US' }), { wrapper });
+
+      expect(ApiClient).toHaveBeenCalledWith({
+        appId: mockAppId,
+        installationId: 'auto-generated-uuid',
+      });
+      expect(LanguagesClient).toHaveBeenCalledWith(expect.objectContaining({ isApiClient: true }));
+    });
+
+    it('should memoize LanguagesClient instance', () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      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 currentAppId = mockAppId;
+
+      const wrapper = ({ children }: { children: ReactNode }) => (
+        <BibleSDKContext.Provider
+          value={{
+            appId: currentAppId,
+          }}
+        >
+          {children}
+        </BibleSDKContext.Provider>
+      );
+
+      const { rerender } = renderHook(() => useLanguages({ country: 'US' }), { wrapper });
+
+      expect(LanguagesClient).toHaveBeenCalledTimes(1);
+
+      currentAppId = 'new-app-id';
+      rerender();
+
+      expect(LanguagesClient).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('fetching languages', () => {
+    it('should fetch languages with required country', async () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useLanguages({ country: 'US' }), { wrapper });
+
+      expect(result.current.loading).toBe(true);
+      expect(result.current.languages).toBe(null);
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguages).toHaveBeenCalledWith({ country: 'US' });
+      expect(result.current.languages).toEqual(mockLanguages);
+    });
+
+    it('should fetch languages with all options', async () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const options: GetLanguagesOptions = {
+        country: 'US',
+        page_size: 10,
+        page_token: 'test_token',
+      };
+
+      const { result } = renderHook(() => useLanguages(options), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguages).toHaveBeenCalledWith(options);
+      expect(result.current.languages).toEqual(mockLanguages);
+    });
+
+    it('should refetch when options change', async () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result, rerender } = renderHook(({ options }) => useLanguages(options), {
+        wrapper,
+        initialProps: { options: { country: 'US' } },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguages).toHaveBeenCalledTimes(1);
+
+      rerender({ options: { country: 'ES' } });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguages).toHaveBeenCalledTimes(2);
+      expect(mockGetLanguages).toHaveBeenLastCalledWith({ country: 'ES' });
+    });
+
+    it('should not fetch when enabled is false', async () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useLanguages({ country: 'US' }, { enabled: false }), {
+        wrapper,
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguages).not.toHaveBeenCalled();
+      expect(result.current.languages).toBe(null);
+    });
+
+    it('should handle fetch errors', async () => {
+      const error = new Error('Failed to fetch languages');
+      mockGetLanguages.mockRejectedValueOnce(error);
+
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useLanguages({ country: 'US' }), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+      expect(result.current.languages).toBe(null);
+    });
+
+    it('should support manual refetch', async () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useLanguages({ country: 'US' }), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguages).toHaveBeenCalledTimes(1);
+
+      result.current.refetch();
+
+      await waitFor(() => {
+        expect(mockGetLanguages).toHaveBeenCalledTimes(2);
+      });
+    });
+  });
+});

package/src/useLanguages.ts

@@ -0,0 +1,57 @@
+'use client';
+
+import { useMemo } from 'react';
+import { useContext } from 'react';
+import { BibleSDKContext } from './context';
+import {
+  LanguagesClient,
+  ApiClient,
+  YouVersionPlatformConfiguration,
+} from '@youversion/platform-core';
+import { useApiData, type UseApiDataOptions } from './useApiData';
+import {
+  type GetLanguagesOptions,
+  type Collection,
+  type Language,
+} from '@youversion/platform-core';
+
+export function useLanguages(
+  options: GetLanguagesOptions,
+  apiOptions?: UseApiDataOptions,
+): {
+  languages: Collection<Language> | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const context = useContext(BibleSDKContext);
+
+  const languagesClient = useMemo(() => {
+    if (!context?.appId) {
+      throw new Error(
+        'BibleSDK context not found. Make sure your component is wrapped with BibleSDKProvider and an API key is provided.',
+      );
+    }
+    return new LanguagesClient(
+      new ApiClient({
+        appId: context.appId,
+        installationId: YouVersionPlatformConfiguration.installationId,
+      }),
+    );
+  }, [context?.appId]);
+
+  const { data, loading, error, refetch } = useApiData<Collection<Language>>(
+    () => languagesClient.getLanguages(options),
+    [languagesClient, options?.country, options?.page_size, options?.page_token],
+    {
+      enabled: apiOptions?.enabled !== false,
+    },
+  );
+
+  return {
+    languages: data,
+    loading,
+    error,
+    refetch,
+  };
+}

package/src/usePassage.ts

@@ -0,0 +1,48 @@
+"use client";
+
+import { useBibleClient } from "./useBibleClient";
+import { useApiData, type UseApiDataOptions } from "./useApiData";
+import type { BiblePassage } from "@youversion/platform-core";
+
+type usePassageProps = {
+  versionId: number;
+  usfm: string;
+  format?: "html" | "text";
+  include_headings?: boolean;
+  include_notes?: boolean;
+  options?: UseApiDataOptions;
+};
+
+export function usePassage({
+  versionId,
+  usfm,
+  format = "html",
+  include_headings = false,
+  include_notes = false,
+  options,
+}: usePassageProps): {
+  passage: BiblePassage | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const bibleClient = useBibleClient();
+
+  // Don't attempt to fetch if usfm is invalid
+  const isValidUsfm = Boolean(usfm) && usfm !== "undefined" && usfm !== "null";
+
+  const { data, loading, error, refetch } = useApiData<BiblePassage>(
+    () =>
+      bibleClient.getPassage(
+        versionId,
+        usfm,
+        format,
+        include_headings,
+        include_notes,
+      ),
+    [bibleClient, versionId, usfm, format, include_headings, include_notes],
+    { enabled: options?.enabled !== false && isValidUsfm },
+  );
+
+  return { passage: data, loading, error, refetch };
+}

package/src/useVOTD.test.tsx

@@ -0,0 +1,269 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import type { ReactNode } from 'react';
+import { useVerseOfTheDay } from './useVOTD';
+import { BibleSDKContext } from './context';
+import { BibleClient, ApiClient, type VOTD } from '@youversion/platform-core';
+
+const MOCK_INSTALLATION_ID = 'auto-generated-uuid';
+
+// Mock the core package
+vi.mock('@youversion/platform-core', async () => {
+  const actual = await vi.importActual('@youversion/platform-core');
+  return {
+    ...actual,
+    BibleClient: vi.fn(function () {
+      return {};
+    }),
+    ApiClient: vi.fn(function () {
+      return { isApiClient: true };
+    }),
+    YouVersionPlatformConfiguration: {
+      get installationId() {
+        return MOCK_INSTALLATION_ID;
+      },
+    },
+  };
+});
+
+describe('useVerseOfTheDay', () => {
+  const mockAppId = 'test-app-id';
+
+  const mockVOTD: VOTD = {
+    day: 1,
+    passage_id: 'ISA.43.19',
+  };
+
+  let mockGetVOTD: Mock;
+
+  const createWrapper = (contextValue: { appId: string }) => {
+    return ({ children }: { children: ReactNode }) => (
+      <BibleSDKContext.Provider value={contextValue}>{children}</BibleSDKContext.Provider>
+    );
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    mockGetVOTD = vi.fn().mockResolvedValue(mockVOTD);
+
+    (BibleClient as unknown as ReturnType<typeof vi.fn>).mockImplementation(function () {
+      return {
+        getVOTD: mockGetVOTD,
+      };
+    });
+
+    (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(() => useVerseOfTheDay(1))).toThrow(
+        'BibleSDK context not found. Make sure your component is wrapped with BibleSDKProvider and an API key is provided.',
+      );
+    });
+
+    it('should throw error when appId is missing', () => {
+      const wrapper = createWrapper({
+        appId: '',
+      });
+
+      expect(() => renderHook(() => useVerseOfTheDay(1), { wrapper })).toThrow(
+        'BibleSDK context not found. Make sure your component is wrapped with BibleSDKProvider and an API key is provided.',
+      );
+    });
+  });
+
+  describe('client creation', () => {
+    it('should create BibleClient with correct ApiClient config', () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      renderHook(() => useVerseOfTheDay(1), { wrapper });
+
+      expect(ApiClient).toHaveBeenCalledWith({
+        appId: mockAppId,
+        installationId: MOCK_INSTALLATION_ID,
+      });
+      expect(BibleClient).toHaveBeenCalledWith(expect.objectContaining({ isApiClient: true }));
+    });
+
+    it('should memoize BibleClient instance', () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result, rerender } = renderHook(() => useVerseOfTheDay(1), { wrapper });
+      const _firstRefetch = result.current.refetch;
+
+      rerender();
+      const _secondRefetch = result.current.refetch;
+
+      expect(BibleClient).toHaveBeenCalledTimes(1);
+    });
+
+    it('should create new BibleClient when context values change', () => {
+      let currentAppId = mockAppId;
+
+      const wrapper = ({ children }: { children: ReactNode }) => (
+        <BibleSDKContext.Provider
+          value={{
+            appId: currentAppId,
+          }}
+        >
+          {children}
+        </BibleSDKContext.Provider>
+      );
+
+      const { rerender } = renderHook(() => useVerseOfTheDay(1), { wrapper });
+
+      expect(BibleClient).toHaveBeenCalledTimes(1);
+
+      currentAppId = 'new-app-id';
+      rerender();
+
+      expect(BibleClient).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('fetching VOTD', () => {
+    it('should fetch VOTD for day 1', async () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useVerseOfTheDay(1), { wrapper });
+
+      expect(result.current.loading).toBe(true);
+      expect(result.current.data).toBe(null);
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVOTD).toHaveBeenCalledWith(1);
+      expect(result.current.data).toEqual(mockVOTD);
+    });
+
+    it('should fetch VOTD for day 100', async () => {
+      const mockVOTD100: VOTD = { day: 100, passage_id: 'PSA.23.1' };
+      mockGetVOTD.mockResolvedValueOnce(mockVOTD100);
+
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useVerseOfTheDay(100), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVOTD).toHaveBeenCalledWith(100);
+      expect(result.current.data).toEqual(mockVOTD100);
+    });
+
+    it('should fetch VOTD for day 366', async () => {
+      const mockVOTD366: VOTD = { day: 366, passage_id: 'REV.22.21' };
+      mockGetVOTD.mockResolvedValueOnce(mockVOTD366);
+
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useVerseOfTheDay(366), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVOTD).toHaveBeenCalledWith(366);
+      expect(result.current.data).toEqual(mockVOTD366);
+    });
+
+    it('should refetch when day changes', async () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result, rerender } = renderHook(({ day }) => useVerseOfTheDay(day), {
+        wrapper,
+        initialProps: { day: 1 },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVOTD).toHaveBeenCalledTimes(1);
+      expect(mockGetVOTD).toHaveBeenLastCalledWith(1);
+
+      rerender({ day: 100 });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVOTD).toHaveBeenCalledTimes(2);
+      expect(mockGetVOTD).toHaveBeenLastCalledWith(100);
+    });
+
+    it('should not fetch when enabled is false', async () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useVerseOfTheDay(1, { enabled: false }), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVOTD).not.toHaveBeenCalled();
+      expect(result.current.data).toBe(null);
+    });
+
+    it('should handle fetch errors', async () => {
+      const error = new Error('Failed to fetch VOTD');
+      mockGetVOTD.mockRejectedValueOnce(error);
+
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useVerseOfTheDay(1), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+      expect(result.current.data).toBe(null);
+    });
+
+    it('should support manual refetch', async () => {
+      const wrapper = createWrapper({
+        appId: mockAppId,
+      });
+
+      const { result } = renderHook(() => useVerseOfTheDay(1), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVOTD).toHaveBeenCalledTimes(1);
+
+      result.current.refetch();
+
+      await waitFor(() => {
+        expect(mockGetVOTD).toHaveBeenCalledTimes(2);
+      });
+    });
+  });
+});

package/src/useVOTD.ts

@@ -0,0 +1,19 @@
+'use client';
+
+import type { VOTD } from '@youversion/platform-core';
+import { useBibleClient } from './useBibleClient';
+import { useApiData, type UseApiDataOptions } from './useApiData';
+
+export function useVerseOfTheDay(
+  day: number,
+  options?: UseApiDataOptions,
+): { data: VOTD | null; loading: boolean; error: Error | null; refetch: () => void } {
+  const bibleClient = useBibleClient();
+
+  const { data, loading, error, refetch } = useApiData<VOTD>(
+    () => bibleClient.getVOTD(day),
+    [bibleClient, day],
+    { enabled: options?.enabled !== false },
+  );
+  return { data, loading, error, refetch };
+}