@youversion/platform-core 0.4.1

package/src/__tests__/highlights.test.ts

@@ -0,0 +1,485 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { ApiClient } from '../client';
+import { HighlightsClient } from '../highlights';
+import { YouVersionPlatformConfiguration } from '../YouVersionPlatformConfiguration';
+
+describe('HighlightsClient', () => {
+  let apiClient: ApiClient;
+  let highlightsClient: HighlightsClient;
+
+  beforeEach(() => {
+    apiClient = new ApiClient({
+      baseUrl: 'https://api-dev.youversion.com',
+      appId: 'test-app',
+      version: 'v1',
+      installationId: 'test-installation',
+    });
+    highlightsClient = new HighlightsClient(apiClient);
+    // Set a default token for tests that don't explicitly pass one
+    YouVersionPlatformConfiguration.setAccessToken('test-token');
+  });
+
+  afterEach(() => {
+    // Clean up token after each test
+    YouVersionPlatformConfiguration.setAccessToken(null);
+    vi.clearAllMocks(); // Reset all mocked calls between tests
+  });
+
+  describe('getHighlights', () => {
+    it('should fetch highlights with no options', async () => {
+      const highlights = await highlightsClient.getHighlights();
+
+      expect(highlights.data).toHaveLength(2);
+      expect(highlights.data[0]).toEqual({
+        version_id: 111,
+        passage_id: 'MAT.1.1',
+        color: 'fffe00',
+      });
+    });
+
+    it('should fetch highlights with version_id option', async () => {
+      const highlights = await highlightsClient.getHighlights({ version_id: 1 });
+
+      expect(highlights.data).toHaveLength(2);
+      expect(highlights.data[0]?.version_id).toBe(1);
+    });
+
+    it('should fetch highlights with passage_id option', async () => {
+      const highlights = await highlightsClient.getHighlights({ passage_id: 'JHN.3.16' });
+
+      expect(highlights.data).toHaveLength(2);
+      expect(highlights.data[0]?.passage_id).toBe('JHN.3.16');
+    });
+
+    it('should fetch highlights with both options', async () => {
+      const highlights = await highlightsClient.getHighlights({
+        version_id: 1,
+        passage_id: 'JHN.3.16',
+      });
+
+      expect(highlights.data).toHaveLength(2);
+      expect(highlights.data[0]?.version_id).toBe(1);
+      expect(highlights.data[0]?.passage_id).toBe('JHN.3.16');
+    });
+
+    it('should throw an error for invalid version_id', async () => {
+      await expect(highlightsClient.getHighlights({ version_id: 0 })).rejects.toThrow(
+        'Version ID must be a positive integer',
+      );
+      await expect(highlightsClient.getHighlights({ version_id: -1 })).rejects.toThrow(
+        'Version ID must be a positive integer',
+      );
+      await expect(highlightsClient.getHighlights({ version_id: 1.5 })).rejects.toThrow();
+    });
+
+    it('should throw an error for invalid passage_id', async () => {
+      await expect(highlightsClient.getHighlights({ passage_id: '' })).rejects.toThrow(
+        'Passage ID must be a non-empty string',
+      );
+      await expect(highlightsClient.getHighlights({ passage_id: '   ' })).rejects.toThrow(
+        'Passage ID must be a non-empty string',
+      );
+    });
+
+    it('should include lat parameter when token provided explicitly', async () => {
+      const fetchSpy = vi.spyOn(global, 'fetch');
+
+      const highlights = await highlightsClient.getHighlights({ version_id: 1 }, 'explicit-token');
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=explicit-token'),
+        expect.any(Object),
+      );
+      expect(highlights.data).toHaveLength(2);
+      expect(highlights.data[0]?.version_id).toBe(1);
+
+      fetchSpy.mockRestore();
+    });
+
+    it('should include lat parameter when token auto-retrieved from config', async () => {
+      YouVersionPlatformConfiguration.setAccessToken('config-token');
+      const fetchSpy = vi.spyOn(global, 'fetch');
+
+      const highlights = await highlightsClient.getHighlights({ version_id: 1 });
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=config-token'),
+        expect.any(Object),
+      );
+      expect(highlights.data).toHaveLength(2);
+      expect(highlights.data[0]?.version_id).toBe(1);
+
+      fetchSpy.mockRestore();
+    });
+
+    it('should throw an error when no token is available', async () => {
+      YouVersionPlatformConfiguration.setAccessToken(null);
+
+      await expect(highlightsClient.getHighlights({ version_id: 1 })).rejects.toThrow(
+        'Authentication required. Please provide a token or sign in before accessing highlights.',
+      );
+    });
+
+    it('should use explicit token over config token', async () => {
+      YouVersionPlatformConfiguration.setAccessToken('config-token');
+      const fetchSpy = vi.spyOn(global, 'fetch');
+      const highlights = await highlightsClient.getHighlights({ version_id: 1 }, 'explicit-token');
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=explicit-token'),
+        expect.any(Object),
+      );
+      expect(highlights.data).toHaveLength(2);
+      expect(highlights.data[0]?.version_id).toBe(1);
+
+      fetchSpy.mockRestore();
+    });
+  });
+
+  describe('createHighlight', () => {
+    it('should create a highlight', async () => {
+      const highlight = await highlightsClient.createHighlight({
+        version_id: 111,
+        passage_id: 'MAT.1.1',
+        color: 'fffe00',
+      });
+
+      expect(highlight).toEqual({
+        version_id: 111,
+        passage_id: 'MAT.1.1',
+        color: 'fffe00',
+      });
+    });
+
+    it('should throw an error for invalid version_id', async () => {
+      await expect(
+        highlightsClient.createHighlight({
+          version_id: 0,
+          passage_id: 'MAT.1.1',
+          color: 'fffe00',
+        }),
+      ).rejects.toThrow('Version ID must be a positive integer');
+
+      await expect(
+        highlightsClient.createHighlight({
+          version_id: -1,
+          passage_id: 'MAT.1.1',
+          color: 'fffe00',
+        }),
+      ).rejects.toThrow('Version ID must be a positive integer');
+    });
+
+    it('should throw an error for invalid passage_id', async () => {
+      await expect(
+        highlightsClient.createHighlight({
+          version_id: 111,
+          passage_id: '',
+          color: 'fffe00',
+        }),
+      ).rejects.toThrow('Passage ID must be a non-empty string');
+
+      await expect(
+        highlightsClient.createHighlight({
+          version_id: 111,
+          passage_id: '   ',
+          color: 'fffe00',
+        }),
+      ).rejects.toThrow('Passage ID must be a non-empty string');
+    });
+
+    it('should throw an error for invalid color', async () => {
+      await expect(
+        highlightsClient.createHighlight({
+          version_id: 111,
+          passage_id: 'MAT.1.1',
+          color: 'invalid',
+        }),
+      ).rejects.toThrow('Color must be a 6-character hex string without #');
+
+      await expect(
+        highlightsClient.createHighlight({
+          version_id: 111,
+          passage_id: 'MAT.1.1',
+          color: '#fffe00',
+        }),
+      ).rejects.toThrow('Color must be a 6-character hex string without #');
+
+      await expect(
+        highlightsClient.createHighlight({
+          version_id: 111,
+          passage_id: 'MAT.1.1',
+          color: 'fff',
+        }),
+      ).rejects.toThrow('Color must be a 6-character hex string without #');
+
+      await expect(
+        highlightsClient.createHighlight({
+          version_id: 111,
+          passage_id: 'MAT.1.1',
+          color: 'fffe00a',
+        }),
+      ).rejects.toThrow('Color must be a 6-character hex string without #');
+    });
+
+    it('should accept valid hex colors', async () => {
+      const validColors = ['fffe00', '5dff79', '00d6ff', 'FFC66F', 'ff95ef'];
+
+      for (const color of validColors) {
+        const highlight = await highlightsClient.createHighlight({
+          version_id: 111,
+          passage_id: 'MAT.1.1',
+          color,
+        });
+
+        expect(highlight.color).toBe(color);
+      }
+    });
+
+    it('should accept passage ranges in passage_id', async () => {
+      const highlight = await highlightsClient.createHighlight({
+        version_id: 111,
+        passage_id: 'MAT.1.1-5',
+        color: 'fffe00',
+      });
+
+      expect(highlight.passage_id).toBe('MAT.1.1-5');
+    });
+
+    it('should include lat parameter when token provided explicitly', async () => {
+      const fetchSpy = vi.spyOn(global, 'fetch');
+      const highlight = await highlightsClient.createHighlight(
+        {
+          version_id: 111,
+          passage_id: 'MAT.1.1',
+          color: 'fffe00',
+        },
+        'explicit-token',
+      );
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=explicit-token'),
+        expect.any(Object),
+      );
+      expect(highlight).toEqual({
+        version_id: 111,
+        passage_id: 'MAT.1.1',
+        color: 'fffe00',
+      });
+
+      fetchSpy.mockRestore();
+    });
+
+    it('should include lat parameter when token auto-retrieved from config', async () => {
+      YouVersionPlatformConfiguration.setAccessToken('config-token');
+      const fetchSpy = vi.spyOn(global, 'fetch');
+      const highlight = await highlightsClient.createHighlight({
+        version_id: 111,
+        passage_id: 'MAT.1.1',
+        color: 'fffe00',
+      });
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=config-token'),
+        expect.any(Object),
+      );
+      expect(highlight).toEqual({
+        version_id: 111,
+        passage_id: 'MAT.1.1',
+        color: 'fffe00',
+      });
+
+      fetchSpy.mockRestore();
+    });
+
+    it('should throw an error when no token is available', async () => {
+      YouVersionPlatformConfiguration.setAccessToken(null);
+
+      await expect(
+        highlightsClient.createHighlight({
+          version_id: 111,
+          passage_id: 'MAT.1.1',
+          color: 'fffe00',
+        }),
+      ).rejects.toThrow(
+        'Authentication required. Please provide a token or sign in before accessing highlights.',
+      );
+    });
+
+    it('should use explicit token over config token', async () => {
+      YouVersionPlatformConfiguration.setAccessToken('config-token');
+      const fetchSpy = vi.spyOn(global, 'fetch');
+      const highlight = await highlightsClient.createHighlight(
+        {
+          version_id: 111,
+          passage_id: 'MAT.1.1',
+          color: 'fffe00',
+        },
+        'explicit-token',
+      );
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=explicit-token'),
+        expect.any(Object),
+      );
+      expect(highlight).toEqual({
+        version_id: 111,
+        passage_id: 'MAT.1.1',
+        color: 'fffe00',
+      });
+
+      fetchSpy.mockRestore();
+    });
+  });
+
+  describe('deleteHighlight', () => {
+    it('should delete a highlight', async () => {
+      let capturedStatus: number | undefined;
+      const originalFetch = global.fetch;
+      const fetchSpy = vi.spyOn(global, 'fetch').mockImplementation(async (...args) => {
+        const response = await originalFetch(...args);
+        capturedStatus = response.status;
+        return response;
+      });
+
+      await highlightsClient.deleteHighlight('MAT.1.1');
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=test-token'),
+        expect.any(Object),
+      );
+      expect(capturedStatus).toBe(204);
+
+      fetchSpy.mockRestore();
+    });
+
+    it('should delete a highlight with version_id option', async () => {
+      let capturedStatus: number | undefined;
+      const originalFetch = global.fetch;
+      const fetchSpy = vi.spyOn(global, 'fetch').mockImplementation(async (...args) => {
+        const response = await originalFetch(...args);
+        capturedStatus = response.status;
+        return response;
+      });
+
+      await highlightsClient.deleteHighlight('MAT.1.1', { version_id: 111 });
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=test-token'),
+        expect.any(Object),
+      );
+      expect(capturedStatus).toBe(204);
+
+      fetchSpy.mockRestore();
+    });
+
+    it('should throw an error for invalid passage_id', async () => {
+      await expect(highlightsClient.deleteHighlight('')).rejects.toThrow(
+        'Passage ID must be a non-empty string',
+      );
+
+      await expect(highlightsClient.deleteHighlight('   ')).rejects.toThrow(
+        'Passage ID must be a non-empty string',
+      );
+    });
+
+    it('should throw an error for invalid version_id in options', async () => {
+      await expect(highlightsClient.deleteHighlight('MAT.1.1', { version_id: 0 })).rejects.toThrow(
+        'Version ID must be a positive integer',
+      );
+
+      await expect(highlightsClient.deleteHighlight('MAT.1.1', { version_id: -1 })).rejects.toThrow(
+        'Version ID must be a positive integer',
+      );
+    });
+
+    it('should accept passage ranges in passage_id', async () => {
+      let capturedStatus: number | undefined;
+      const originalFetch = global.fetch;
+      const fetchSpy = vi.spyOn(global, 'fetch').mockImplementation(async (...args) => {
+        const response = await originalFetch(...args);
+        capturedStatus = response.status;
+        return response;
+      });
+
+      await highlightsClient.deleteHighlight('MAT.1.1-5');
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=test-token'),
+        expect.any(Object),
+      );
+      expect(capturedStatus).toBe(204);
+
+      fetchSpy.mockRestore();
+    });
+
+    it('should include lat parameter when token provided explicitly', async () => {
+      let capturedStatus: number | undefined;
+      const originalFetch = global.fetch;
+      const fetchSpy = vi.spyOn(global, 'fetch').mockImplementation(async (...args) => {
+        const response = await originalFetch(...args);
+        capturedStatus = response.status;
+        return response;
+      });
+
+      await highlightsClient.deleteHighlight('MAT.1.1', undefined, 'explicit-token');
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=explicit-token'),
+        expect.any(Object),
+      );
+      expect(capturedStatus).toBe(204);
+
+      fetchSpy.mockRestore();
+    });
+
+    it('should include lat parameter when token auto-retrieved from config', async () => {
+      YouVersionPlatformConfiguration.setAccessToken('config-token');
+      let capturedStatus: number | undefined;
+      const originalFetch = global.fetch;
+      const fetchSpy = vi.spyOn(global, 'fetch').mockImplementation(async (...args) => {
+        const response = await originalFetch(...args);
+        capturedStatus = response.status;
+        return response;
+      });
+
+      await highlightsClient.deleteHighlight('MAT.1.1');
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=config-token'),
+        expect.any(Object),
+      );
+      expect(capturedStatus).toBe(204);
+
+      fetchSpy.mockRestore();
+    });
+
+    it('should throw an error when no token is available', async () => {
+      YouVersionPlatformConfiguration.setAccessToken(null);
+
+      await expect(highlightsClient.deleteHighlight('MAT.1.1')).rejects.toThrow(
+        'Authentication required. Please provide a token or sign in before accessing highlights.',
+      );
+    });
+
+    it('should use explicit token over config token', async () => {
+      YouVersionPlatformConfiguration.setAccessToken('config-token');
+      let capturedStatus: number | undefined;
+      const originalFetch = global.fetch;
+      const fetchSpy = vi.spyOn(global, 'fetch').mockImplementation(async (...args) => {
+        const response = await originalFetch(...args);
+        capturedStatus = response.status;
+        return response;
+      });
+
+      await highlightsClient.deleteHighlight('MAT.1.1', undefined, 'explicit-token');
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining('lat=explicit-token'),
+        expect.any(Object),
+      );
+      expect(capturedStatus).toBe(204);
+
+      fetchSpy.mockRestore();
+    });
+  });
+});

package/src/__tests__/languages.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ApiClient } from '../client';
+import { LanguagesClient } from '../languages';
+import { LanguageSchema } from '../schemas';
+
+describe('LanguagesClient', () => {
+  let apiClient: ApiClient;
+  let languagesClient: LanguagesClient;
+
+  beforeEach(() => {
+    apiClient = new ApiClient({
+      baseUrl: 'https://api-dev.youversion.com',
+      appId: process.env.YVP_APP_ID || '',
+      version: 'v1',
+      installationId: 'test-installation',
+    });
+    languagesClient = new LanguagesClient(apiClient);
+  });
+
+  describe('getLanguages', () => {
+    it('should fetch languages with required country param', async () => {
+      const languages = await languagesClient.getLanguages({ country: 'US' });
+
+      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']));
+    });
+
+    it('should fetch languages with page_size option', async () => {
+      const languages = await languagesClient.getLanguages({ country: 'US', page_size: 10 });
+
+      const { success } = LanguageSchema.safeParse(languages.data[0]);
+      expect(success).toBe(true);
+      expect(languages.data).toHaveLength(10);
+      expect(languages.next_page_token).toBe('eyJzdGFydCI6IDEwfQ==');
+    });
+
+    it('should fetch languages with page_token option', async () => {
+      const languages = await languagesClient.getLanguages({
+        country: 'US',
+        page_token: 'eyJzdGFydCI6IDEwMH0=',
+      });
+
+      const { success } = LanguageSchema.safeParse(languages.data[0]);
+      expect(success).toBe(true);
+      expect(languages.data).toHaveLength(25);
+    });
+
+    it('should uppercase country code', async () => {
+      const languages = await languagesClient.getLanguages({ country: 'us' });
+
+      expect(languages.data[0]?.countries).toContain('US');
+    });
+
+    it('should throw an error for invalid country code - empty string', async () => {
+      await expect(languagesClient.getLanguages({ country: '' })).rejects.toThrow(
+        'Country code must be a 2-character ISO 3166-1 alpha-2 code',
+      );
+    });
+
+    it('should throw an error for invalid country code - wrong length', async () => {
+      await expect(languagesClient.getLanguages({ country: 'USA' })).rejects.toThrow(
+        'Country code must be a 2-character ISO 3166-1 alpha-2 code',
+      );
+      await expect(languagesClient.getLanguages({ country: 'U' })).rejects.toThrow(
+        'Country code must be a 2-character ISO 3166-1 alpha-2 code',
+      );
+    });
+
+    it('should throw an error for invalid country code - whitespace', async () => {
+      await expect(languagesClient.getLanguages({ country: '  ' })).rejects.toThrow(
+        'Country code must be a 2-character ISO 3166-1 alpha-2 code',
+      );
+    });
+
+    it('should throw an error for invalid page_size - zero', async () => {
+      await expect(languagesClient.getLanguages({ country: 'US', page_size: 0 })).rejects.toThrow();
+    });
+
+    it('should throw an error for invalid page_size - negative', async () => {
+      await expect(
+        languagesClient.getLanguages({ country: 'US', page_size: -1 }),
+      ).rejects.toThrow();
+    });
+
+    it('should throw an error for invalid page_size - non-integer', async () => {
+      await expect(
+        languagesClient.getLanguages({ country: 'US', page_size: 1.5 }),
+      ).rejects.toThrow();
+    });
+  });
+
+  describe('getLanguage', () => {
+    it('should fetch a language by ID', async () => {
+      const language = await languagesClient.getLanguage('en');
+
+      const { success } = LanguageSchema.safeParse(language);
+      expect(success).toBe(true);
+      expect(language.id).toBe('en');
+      expect(language.language).toBe('en');
+    });
+
+    it('should fetch a language with script', async () => {
+      const language = await languagesClient.getLanguage('sr-Latn');
+
+      const { success } = LanguageSchema.safeParse(language);
+      expect(success).toBe(true);
+      expect(language.id).toBe('sr-Latn');
+      expect(language.language).toBe('sr');
+      expect(language.script).toBe('Latn');
+      expect(language.script_name).toBe('latinica');
+    });
+
+    it('should throw an error for invalid language ID - empty string', async () => {
+      await expect(languagesClient.getLanguage('')).rejects.toThrow(
+        'Language ID must be a non-empty string',
+      );
+    });
+
+    it('should throw an error for invalid language ID - whitespace', async () => {
+      await expect(languagesClient.getLanguage('   ')).rejects.toThrow(
+        'Language ID must be a non-empty string',
+      );
+    });
+
+    it('should throw an error for invalid language ID - invalid format', async () => {
+      await expect(languagesClient.getLanguage('invalid-format-123')).rejects.toThrow(
+        'Language ID must match BCP 47 format (language or language+script)',
+      );
+    });
+
+    it('should throw an error for invalid language ID - uppercase', async () => {
+      await expect(languagesClient.getLanguage('EN')).rejects.toThrow(
+        'Language ID must match BCP 47 format (language or language+script)',
+      );
+    });
+  });
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,17 @@
+import { beforeAll, afterEach, afterAll } from 'vitest';
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);
+
+beforeAll(() => {
+  server.listen();
+});
+
+afterEach(() => {
+  server.resetHandlers();
+});
+
+afterAll(() => {
+  server.close();
+});

package/src/authentication.ts

@@ -0,0 +1,27 @@
+import type { ApiClient } from './client';
+import type { User } from './types';
+
+/**
+ * Client for authentication-related API calls.
+ */
+export class AuthClient {
+  private client: ApiClient;
+
+  /**
+   * Creates an instance of AuthClient.
+   * @param client - The ApiClient instance to use for requests.
+   */
+  constructor(client: ApiClient) {
+    this.client = client;
+  }
+
+  /**
+   * Retrieves the current authenticated user.
+   *
+   * @param lat - The long access token (LAT) used for authentication.
+   * @returns A promise that resolves to the authenticated User.
+   */
+  async getUser(lat: string): Promise<User> {
+    return this.client.get<User>(`/auth/me`, { lat: lat });
+  }
+}