@youversion/platform-core 0.4.1

package/src/__tests__/URLBuilder.test.ts

@@ -0,0 +1,289 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { URLBuilder } from '../URLBuilder';
+import { YouVersionPlatformConfiguration } from '../YouVersionPlatformConfiguration';
+import type { SignInWithYouVersionPermissionValues } from '../types';
+
+describe('URLBuilder - Input Validation', () => {
+  let originalApiHost: string;
+  let originalInstallationId: string | undefined;
+
+  beforeEach(() => {
+    // Store original config
+    originalApiHost = YouVersionPlatformConfiguration.apiHost;
+    originalInstallationId = YouVersionPlatformConfiguration.installationId;
+
+    // Set test config
+    YouVersionPlatformConfiguration.apiHost = 'api-dev.youversion.com';
+    YouVersionPlatformConfiguration.installationId = 'test-installation-id';
+  });
+
+  afterEach(() => {
+    // Restore original config
+    YouVersionPlatformConfiguration.apiHost = originalApiHost;
+    YouVersionPlatformConfiguration.installationId = originalInstallationId;
+  });
+
+  describe('authURL - appId validation', () => {
+    it('should throw error for empty string appId', () => {
+      expect(() => {
+        URLBuilder.authURL('');
+      }).toThrow('appId must be a non-empty string');
+    });
+
+    it('should throw error for whitespace-only appId', () => {
+      expect(() => {
+        URLBuilder.authURL('   ');
+      }).toThrow('appId must be a non-empty string');
+    });
+
+    it('should throw error for tab/newline-only appId', () => {
+      expect(() => {
+        URLBuilder.authURL('\t\n  ');
+      }).toThrow('appId must be a non-empty string');
+    });
+
+    it('should throw descriptive error message', () => {
+      try {
+        URLBuilder.authURL('');
+        // Should not reach here
+        expect.fail('Should have thrown an error');
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toContain('appId');
+        expect((error as Error).message).toContain('non-empty string');
+      }
+    });
+
+    it('should accept valid non-empty appId', () => {
+      const url = URLBuilder.authURL('valid-app-id');
+
+      expect(url).toBeInstanceOf(URL);
+      expect(url.hostname).toBe('api-dev.youversion.com');
+      expect(url.pathname).toBe('/auth/login');
+      expect(url.searchParams.get('app_id')).toBe('valid-app-id');
+    });
+
+    it('should trim and accept appId with surrounding whitespace', () => {
+      // Note: The validation checks trim().length, so this should pass
+      const url = URLBuilder.authURL(' valid-app-id ');
+
+      expect(url).toBeInstanceOf(URL);
+      // The actual value passed has whitespace preserved in the URL
+      expect(url.searchParams.get('app_id')).toBe(' valid-app-id ');
+    });
+
+    it('should accept appId with special characters', () => {
+      const specialAppId = 'app-id_123.test';
+      const url = URLBuilder.authURL(specialAppId);
+
+      expect(url.searchParams.get('app_id')).toBe(specialAppId);
+    });
+  });
+
+  describe('authURL - URL construction', () => {
+    it('should construct correct base URL and pathname', () => {
+      const url = URLBuilder.authURL('test-app');
+
+      expect(url.protocol).toBe('https:');
+      expect(url.hostname).toBe('api-dev.youversion.com');
+      expect(url.pathname).toBe('/auth/login');
+    });
+
+    it('should include app_id in query parameters', () => {
+      const url = URLBuilder.authURL('my-app-id');
+
+      expect(url.searchParams.get('app_id')).toBe('my-app-id');
+    });
+
+    it('should include default language parameter', () => {
+      const url = URLBuilder.authURL('test-app');
+
+      expect(url.searchParams.get('language')).toBe('en');
+    });
+
+    it('should include installation ID when configured', () => {
+      YouVersionPlatformConfiguration.installationId = 'test-installation-123';
+      const url = URLBuilder.authURL('test-app');
+
+      expect(url.searchParams.get('x-yvp-installation-id')).toBe('test-installation-123');
+    });
+
+    it('should not include installation ID when not configured', () => {
+      YouVersionPlatformConfiguration.installationId = undefined;
+      const url = URLBuilder.authURL('test-app');
+
+      expect(url.searchParams.get('x-yvp-installation-id')).toBeNull();
+    });
+
+    it('should include required permissions when provided', () => {
+      const permissions = new Set<SignInWithYouVersionPermissionValues>([
+        'plans.read',
+        'user.read',
+      ]);
+      const url = URLBuilder.authURL('test-app', permissions);
+
+      const requiredPerms = url.searchParams.get('required_perms');
+      expect(requiredPerms).toBeTruthy();
+      expect(requiredPerms?.split(',')).toContain('plans.read');
+      expect(requiredPerms?.split(',')).toContain('user.read');
+    });
+
+    it('should include optional permissions when provided', () => {
+      const optionalPermissions = new Set<SignInWithYouVersionPermissionValues>(['moments.read']);
+      const url = URLBuilder.authURL('test-app', new Set(), optionalPermissions);
+
+      const optPerms = url.searchParams.get('opt_perms');
+      expect(optPerms).toBe('moments.read');
+    });
+
+    it('should include both required and optional permissions', () => {
+      const required = new Set<SignInWithYouVersionPermissionValues>(['user.read']);
+      const optional = new Set<SignInWithYouVersionPermissionValues>(['plans.read']);
+      const url = URLBuilder.authURL('test-app', required, optional);
+
+      expect(url.searchParams.get('required_perms')).toBe('user.read');
+      expect(url.searchParams.get('opt_perms')).toBe('plans.read');
+    });
+
+    it('should handle empty permission sets', () => {
+      const url = URLBuilder.authURL('test-app', new Set(), new Set());
+
+      expect(url.searchParams.get('required_perms')).toBeNull();
+      expect(url.searchParams.get('opt_perms')).toBeNull();
+    });
+  });
+
+  describe('userURL - accessToken validation', () => {
+    it('should throw error for empty string accessToken', () => {
+      expect(() => {
+        URLBuilder.userURL('');
+      }).toThrow('accessToken must be a non-empty string');
+    });
+
+    it('should throw error for whitespace-only accessToken', () => {
+      expect(() => {
+        URLBuilder.userURL('   ');
+      }).toThrow('accessToken must be a non-empty string');
+    });
+
+    it('should throw error for tab/newline-only accessToken', () => {
+      expect(() => {
+        URLBuilder.userURL('\t\n  ');
+      }).toThrow('accessToken must be a non-empty string');
+    });
+
+    it('should throw descriptive error message', () => {
+      try {
+        URLBuilder.userURL('');
+        expect.fail('Should have thrown an error');
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toContain('accessToken');
+        expect((error as Error).message).toContain('non-empty string');
+      }
+    });
+
+    it('should accept valid non-empty accessToken', () => {
+      const url = URLBuilder.userURL('valid-access-token-123');
+
+      expect(url).toBeInstanceOf(URL);
+      expect(url.hostname).toBe('api-dev.youversion.com');
+      expect(url.pathname).toBe('/auth/me');
+      expect(url.searchParams.get('lat')).toBe('valid-access-token-123');
+    });
+
+    it('should accept accessToken with special characters', () => {
+      const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test.signature';
+      const url = URLBuilder.userURL(token);
+
+      expect(url.searchParams.get('lat')).toBe(token);
+    });
+  });
+
+  describe('userURL - URL construction', () => {
+    it('should construct correct base URL and pathname', () => {
+      const url = URLBuilder.userURL('test-token');
+
+      expect(url.protocol).toBe('https:');
+      expect(url.hostname).toBe('api-dev.youversion.com');
+      expect(url.pathname).toBe('/auth/me');
+    });
+
+    it('should include access token in lat query parameter', () => {
+      const token = 'my-access-token-abc123';
+      const url = URLBuilder.userURL(token);
+
+      expect(url.searchParams.get('lat')).toBe(token);
+    });
+
+    it('should properly encode special characters in token', () => {
+      const tokenWithSpecialChars = 'token+with/special=chars';
+      const url = URLBuilder.userURL(tokenWithSpecialChars);
+
+      // URLSearchParams automatically encodes special characters
+      expect(url.searchParams.get('lat')).toBe(tokenWithSpecialChars);
+      expect(url.toString()).toContain('token%2Bwith%2Fspecial%3Dchars');
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should throw errors instead of returning null for invalid appId', () => {
+      // Verify that the method throws, not returns null
+      let threwError = false;
+      let returnValue: any;
+
+      try {
+        returnValue = URLBuilder.authURL('');
+      } catch {
+        threwError = true;
+      }
+
+      expect(threwError).toBe(true);
+      expect(returnValue).toBeUndefined();
+    });
+
+    it('should throw errors instead of returning null for invalid accessToken', () => {
+      let threwError = false;
+      let returnValue: any;
+
+      try {
+        returnValue = URLBuilder.userURL('');
+      } catch {
+        threwError = true;
+      }
+
+      expect(threwError).toBe(true);
+      expect(returnValue).toBeUndefined();
+    });
+
+    it('should wrap URL construction errors with descriptive message for authURL', () => {
+      // This is hard to trigger, but we can at least verify the pattern exists
+      // by checking that valid inputs don't trigger the catch block
+      expect(() => {
+        URLBuilder.authURL('valid-app-id');
+      }).not.toThrow(/Failed to construct auth URL/);
+    });
+
+    it('should wrap URL construction errors with descriptive message for userURL', () => {
+      expect(() => {
+        URLBuilder.userURL('valid-token');
+      }).not.toThrow(/Failed to construct user URL/);
+    });
+  });
+
+  describe('Return type validation', () => {
+    it('authURL should return URL object (not null)', () => {
+      const result = URLBuilder.authURL('test-app');
+
+      expect(result).toBeInstanceOf(URL);
+      expect(result).not.toBeNull();
+    });
+
+    it('userURL should return URL object (not null)', () => {
+      const result = URLBuilder.userURL('test-token');
+
+      expect(result).toBeInstanceOf(URL);
+      expect(result).not.toBeNull();
+    });
+  });
+});

package/src/__tests__/YouVersionPlatformConfiguration.test.ts

@@ -0,0 +1,150 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+// Mock globals before importing the module
+const mockUUID = '550e8400-e29b-41d4-a716-446655440000';
+const mockRandomUUID = vi.fn(() => mockUUID);
+const mockGetItem = vi.fn();
+const mockSetItem = vi.fn();
+
+vi.stubGlobal('crypto', { randomUUID: mockRandomUUID });
+vi.stubGlobal('localStorage', { getItem: mockGetItem, setItem: mockSetItem });
+
+import { YouVersionPlatformConfiguration } from '../YouVersionPlatformConfiguration';
+
+describe('YouVersionPlatformConfiguration', () => {
+  beforeEach(() => {
+    // Reset all static properties
+    YouVersionPlatformConfiguration.appId = null;
+    YouVersionPlatformConfiguration.installationId = null;
+    YouVersionPlatformConfiguration.setAccessToken(null);
+    YouVersionPlatformConfiguration.apiHost = 'api-dev.youversion.com';
+    YouVersionPlatformConfiguration.isPreviewMode = false;
+    YouVersionPlatformConfiguration.previewUserInfo = null;
+
+    // Clear call history but keep implementation
+    mockRandomUUID.mockClear();
+    mockGetItem.mockClear();
+    mockSetItem.mockClear();
+
+    // Setup localStorage to return null by default (empty)
+    mockGetItem.mockReturnValue(null);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('appId', () => {
+    it('should get and set appId', () => {
+      expect(YouVersionPlatformConfiguration.appId).toBeNull();
+
+      YouVersionPlatformConfiguration.appId = 'test-app-id';
+      expect(YouVersionPlatformConfiguration.appId).toBe('test-app-id');
+
+      YouVersionPlatformConfiguration.appId = null;
+      expect(YouVersionPlatformConfiguration.appId).toBeNull();
+    });
+  });
+
+  describe('installationId', () => {
+    it('should get and set installationId when provided', () => {
+      const testId = 'test-installation-id';
+      YouVersionPlatformConfiguration.installationId = testId;
+
+      expect(YouVersionPlatformConfiguration.installationId).toBe(testId);
+    });
+
+    it('should generate and store UUID when installationId is null', () => {
+      YouVersionPlatformConfiguration.installationId = null;
+
+      expect(mockRandomUUID).toHaveBeenCalled();
+      expect(YouVersionPlatformConfiguration.installationId).toBe(mockUUID);
+    });
+
+    it('should generate and store UUID when installationId is empty string', () => {
+      YouVersionPlatformConfiguration.installationId = '';
+
+      expect(mockRandomUUID).toHaveBeenCalled();
+      expect(YouVersionPlatformConfiguration.installationId).toBe(mockUUID);
+    });
+
+    it('should use existing UUID from localStorage when installationId is null', () => {
+      const existingUUID = 'existing-uuid-from-storage';
+      mockGetItem.mockReturnValue(existingUUID);
+
+      YouVersionPlatformConfiguration.installationId = null;
+
+      expect(mockRandomUUID).not.toHaveBeenCalled();
+      expect(YouVersionPlatformConfiguration.installationId).toBe(existingUUID);
+    });
+
+    it('should generate new UUID when localStorage is empty', () => {
+      YouVersionPlatformConfiguration.installationId = null;
+
+      expect(mockRandomUUID).toHaveBeenCalled();
+      expect(YouVersionPlatformConfiguration.installationId).toBe(mockUUID);
+    });
+  });
+
+  describe('accessToken', () => {
+    it('should set and get access token', () => {
+      expect(YouVersionPlatformConfiguration.accessToken).toBeNull();
+
+      const token = 'test-access-token';
+      YouVersionPlatformConfiguration.setAccessToken(token);
+      expect(YouVersionPlatformConfiguration.accessToken).toBe(token);
+
+      YouVersionPlatformConfiguration.setAccessToken(null);
+      expect(YouVersionPlatformConfiguration.accessToken).toBeNull();
+    });
+  });
+
+  describe('apiHost', () => {
+    it('should get and set apiHost', () => {
+      expect(YouVersionPlatformConfiguration.apiHost).toBe('api-dev.youversion.com');
+
+      YouVersionPlatformConfiguration.apiHost = 'api.youversion.com';
+      expect(YouVersionPlatformConfiguration.apiHost).toBe('api.youversion.com');
+    });
+  });
+
+  describe('isPreviewMode', () => {
+    it('should get and set preview mode', () => {
+      expect(YouVersionPlatformConfiguration.isPreviewMode).toBe(false);
+
+      YouVersionPlatformConfiguration.isPreviewMode = true;
+      expect(YouVersionPlatformConfiguration.isPreviewMode).toBe(true);
+
+      YouVersionPlatformConfiguration.isPreviewMode = false;
+      expect(YouVersionPlatformConfiguration.isPreviewMode).toBe(false);
+    });
+  });
+
+  describe('UUID generation edge cases', () => {
+    it('should generate valid UUID format', () => {
+      YouVersionPlatformConfiguration.installationId = null;
+
+      const generatedId = YouVersionPlatformConfiguration.installationId;
+      expect(generatedId).toBe(mockUUID);
+      expect(generatedId).toMatch(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+      );
+    });
+  });
+
+  describe('multiple calls consistency', () => {
+    it('should return same UUID on multiple null assignments', () => {
+      YouVersionPlatformConfiguration.installationId = null;
+      const firstId = YouVersionPlatformConfiguration.installationId;
+
+      YouVersionPlatformConfiguration.installationId = null;
+      const secondId = YouVersionPlatformConfiguration.installationId;
+
+      expect(firstId).toBe(secondId);
+      expect(firstId).toBe(mockUUID);
+    });
+  });
+});

package/src/__tests__/authentication.test.ts

@@ -0,0 +1,174 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ApiClient } from '../client';
+import { AuthClient } from '../authentication';
+import { WebAuthenticationStrategy } from '../WebAuthenticationStrategy';
+
+describe('AuthClient', () => {
+  let apiClient: ApiClient;
+  let authClient: AuthClient;
+
+  beforeEach(() => {
+    global.fetch = vi.fn();
+    apiClient = new ApiClient({
+      baseUrl: 'https://api-dev.youversion.com',
+      appId: 'test-app-id',
+      version: 'v1',
+    });
+    authClient = new AuthClient(apiClient);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('getUser', () => {
+    it('should fetch user information', async () => {
+      const mockUser = {
+        id: '123',
+        first_name: 'John',
+        last_name: 'Doe',
+        avatar_url: 'https://example.com/avatar.jpg',
+      };
+
+      vi.mocked(global.fetch).mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockUser),
+        headers: {
+          get: vi.fn((name: string) => (name === 'content-type' ? 'application/json' : null)),
+        },
+      } as Response);
+
+      const user = await authClient.getUser('test-token');
+
+      expect(user).toEqual(mockUser);
+      expect(global.fetch).toHaveBeenCalledWith(
+        expect.stringContaining('/auth/me'),
+        expect.any(Object),
+      );
+    });
+  });
+});
+
+describe('WebAuthenticationStrategy', () => {
+  let strategy: WebAuthenticationStrategy;
+  const oldWindowLocation = window.location;
+
+  beforeEach(() => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    delete (window as any).location;
+    window.location = {
+      ...oldWindowLocation,
+      href: 'http://localhost:3000',
+      origin: 'http://localhost:3000',
+      pathname: '/',
+      assign: vi.fn(),
+      replace: vi.fn(),
+    } as Location;
+
+    const sessionStorageMock = (() => {
+      let store: Record<string, string> = {};
+      return {
+        getItem: vi.fn((key: string) => store[key] || null),
+        setItem: vi.fn((key: string, value: string) => {
+          store[key] = value;
+        }),
+        removeItem: vi.fn((key: string) => {
+          delete store[key];
+        }),
+        clear: vi.fn(() => {
+          store = {};
+        }),
+      };
+    })();
+
+    Object.defineProperty(window, 'sessionStorage', {
+      value: sessionStorageMock,
+      writable: true,
+    });
+
+    window.history.replaceState = vi.fn();
+
+    strategy = new WebAuthenticationStrategy({
+      callbackPath: '/auth/callback',
+      timeout: 5000,
+    });
+  });
+
+  afterEach(() => {
+    window.location = oldWindowLocation;
+    WebAuthenticationStrategy.cleanup();
+    vi.clearAllMocks();
+  });
+
+  describe('authenticate', () => {
+    it('should redirect to auth URL', () => {
+      const authUrl = new URL('https://auth.youversion.com/authorize');
+
+      void strategy.authenticate(authUrl);
+
+      expect(window.location.href).toContain('auth.youversion.com');
+      // eslint-disable-next-line @typescript-eslint/unbound-method
+      expect(sessionStorage.setItem).toHaveBeenCalledWith(
+        'youversion-auth-return',
+        'http://localhost:3000',
+      );
+    });
+  });
+
+  describe('handleCallback', () => {
+    it('should handle callback and return true', () => {
+      window.location.pathname = '/auth/callback';
+      window.location.href = 'http://localhost:3000/auth/callback?status=success';
+      // Add searchParams to mock location object for testing
+      Object.defineProperty(window.location, 'searchParams', {
+        value: new URLSearchParams('status=success'),
+        writable: true,
+        configurable: true,
+      });
+
+      const result = WebAuthenticationStrategy.handleCallback('/auth/callback');
+
+      expect(result).toBe(true);
+      // eslint-disable-next-line @typescript-eslint/unbound-method
+      expect(sessionStorage.setItem).toHaveBeenCalledWith(
+        'youversion-auth-callback',
+        expect.stringContaining('status=success'),
+      );
+    });
+
+    it('should return false for non-callback URLs', () => {
+      window.location.pathname = '/';
+      Object.defineProperty(window.location, 'searchParams', {
+        value: new URLSearchParams(''),
+        writable: true,
+        configurable: true,
+      });
+
+      const result = WebAuthenticationStrategy.handleCallback('/auth/callback');
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('getStoredCallback', () => {
+    it('should retrieve and remove stored callback', () => {
+      const callbackUrl = 'http://localhost:3000/auth/callback?status=success';
+      sessionStorage.setItem('youversion-auth-callback', callbackUrl);
+
+      const result = WebAuthenticationStrategy.getStoredCallback();
+
+      expect(result?.toString()).toBe(callbackUrl);
+      // eslint-disable-next-line @typescript-eslint/unbound-method
+      expect(sessionStorage.removeItem).toHaveBeenCalledWith('youversion-auth-callback');
+    });
+
+    it('should return null if no stored callback', () => {
+      const result = WebAuthenticationStrategy.getStoredCallback();
+
+      expect(result).toBeNull();
+    });
+  });
+});