@youversion/platform-core 0.4.1

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@youversion/platform-core",
+  "version": "0.4.1",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/youversion/platform-sdk-react",
+    "directory": "packages/core"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.4",
+    "dotenv-cli": "7.4.2",
+    "eslint": "9.38.0",
+    "jsdom": "^24.0.0",
+    "msw": "2.11.6",
+    "typescript": "5.9.3",
+    "vitest": "4.0.4",
+    "@internal/eslint-config": "0.0.0",
+    "@internal/tsconfig": "0.0.0"
+  },
+  "dependencies": {
+    "tsup": "8.5.0",
+    "zod": "4.1.12"
+  },
+  "scripts": {
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "lint": "eslint . --max-warnings 0",
+    "test": "dotenv -e .env.local -- vitest run",
+    "test:watch": "dotenv -e .env.local -- vitest",
+    "test:coverage": "dotenv -e .env.local -- vitest run --coverage"
+  }
+}

package/src/AuthenticationStrategy.ts

@@ -0,0 +1,78 @@
+/**
+ * Platform-agnostic authentication strategy interface
+ *
+ * Implementations should handle platform-specific authentication flows
+ * and return the callback URL containing the authentication result.
+ */
+export interface AuthenticationStrategy {
+  /**
+   * Opens the authentication flow and returns the callback URL
+   *
+   * @param authUrl - The YouVersion authorization URL to open
+   * @returns Promise that resolves to the callback URL with auth result
+   * @throws Error if authentication fails or is cancelled
+   */
+  authenticate(authUrl: URL): Promise<URL>;
+}
+
+/**
+ * Registry for platform-specific authentication strategies
+ *
+ * This singleton registry manages the current authentication strategy
+ * and ensures only one strategy is active at a time.
+ */
+export class AuthenticationStrategyRegistry {
+  private static strategy: AuthenticationStrategy | null = null;
+
+  /**
+   * Registers a platform-specific authentication strategy
+   *
+   * @param strategy - The authentication strategy to register
+   * @throws Error if strategy is null, undefined, or missing required methods
+   */
+  static register(strategy: AuthenticationStrategy): void {
+    if (!strategy) {
+      throw new Error('Authentication strategy cannot be null or undefined');
+    }
+
+    if (typeof strategy.authenticate !== 'function') {
+      throw new Error('Authentication strategy must implement authenticate method');
+    }
+
+    this.strategy = strategy;
+  }
+
+  /**
+   * Gets the currently registered authentication strategy
+   *
+   * @returns The registered authentication strategy
+   * @throws Error if no strategy has been registered
+   */
+  static get(): AuthenticationStrategy {
+    if (!this.strategy) {
+      throw new Error(
+        'No authentication strategy registered. Please register a platform-specific strategy using AuthenticationStrategyRegistry.register()',
+      );
+    }
+    return this.strategy;
+  }
+
+  /**
+   * Checks if a strategy is currently registered
+   *
+   * @returns true if a strategy is registered, false otherwise
+   */
+  static isRegistered(): boolean {
+    return this.strategy !== null;
+  }
+
+  /**
+   * Resets the registry by removing the current strategy
+   *
+   * This method is primarily intended for testing scenarios
+   * where you need to clean up between test cases.
+   */
+  static reset(): void {
+    this.strategy = null;
+  }
+}

package/src/SignInWithYouVersionResult.ts

@@ -0,0 +1,53 @@
+import type { SignInWithYouVersionPermissionValues } from './types';
+
+export const SignInWithYouVersionPermission = {
+  bibles: 'bibles',
+  highlights: 'highlights',
+  votd: 'votd',
+  demographics: 'demographics',
+  bibleActivity: 'bible_activity',
+} as const;
+
+export class SignInWithYouVersionResult {
+  public readonly accessToken: string | null;
+  public readonly permissions: SignInWithYouVersionPermissionValues[];
+  public readonly errorMsg: string | null;
+  public readonly yvpUserId: string | null;
+
+  constructor(url: URL) {
+    const queryParams = new URLSearchParams(url.search);
+
+    const status = queryParams.get('status');
+    const userId = queryParams.get('yvp_user_id');
+    const latValue = queryParams.get('lat');
+    const grants = queryParams.get('grants');
+
+    const perms =
+      grants
+        ?.split(',')
+        .map((grant) => grant.trim())
+        .filter((grant) =>
+          Object.values(SignInWithYouVersionPermission).includes(
+            grant as SignInWithYouVersionPermissionValues,
+          ),
+        )
+        .map((grant) => grant as SignInWithYouVersionPermissionValues) ?? [];
+
+    if (status === 'success' && latValue && userId) {
+      this.accessToken = latValue;
+      this.permissions = perms;
+      this.errorMsg = null;
+      this.yvpUserId = userId;
+    } else if (status === 'canceled') {
+      this.accessToken = null;
+      this.permissions = [];
+      this.errorMsg = null;
+      this.yvpUserId = null;
+    } else {
+      this.accessToken = null;
+      this.permissions = [];
+      this.errorMsg = 'Authentication failed';
+      this.yvpUserId = null;
+    }
+  }
+}

package/src/StorageStrategy.ts

@@ -0,0 +1,81 @@
+/**
+ * Abstract storage strategy for auth-related data (callbacks, return URLs).
+ * Implementations can use different mechanisms (sessionStorage, memory, etc.)
+ *
+ * WARNING: Session storage has known XSS vulnerabilities. An attacker that gains
+ * script execution access (via XSS) can read all values in sessionStorage. Consider
+ * using a secure, HTTP-only cookie mechanism for production applications.
+ */
+export interface StorageStrategy {
+  setItem(key: string, value: string): void;
+  getItem(key: string): string | null;
+  removeItem(key: string): void;
+  clear(): void;
+}
+
+/**
+ * Default storage strategy using the browser's sessionStorage.
+ * This provides temporary storage for authentication state during a single session.
+ *
+ * SECURITY WARNING: SessionStorage is vulnerable to XSS attacks. If an attacker
+ * can inject JavaScript into your application, they can access all sessionStorage values.
+ * For production applications handling sensitive authentication tokens, consider:
+ * 1. Using secure, HTTP-only cookies instead
+ * 2. Storing tokens in memory only (with redirection to re-authenticate on page reload)
+ * 3. Using a custom storage backend that implements additional security measures
+ */
+export class SessionStorageStrategy implements StorageStrategy {
+  setItem(key: string, value: string): void {
+    if (typeof sessionStorage === 'undefined') {
+      console.warn('SessionStorage is not available in this environment');
+      return;
+    }
+    sessionStorage.setItem(key, value);
+  }
+
+  getItem(key: string): string | null {
+    if (typeof sessionStorage === 'undefined') {
+      return null;
+    }
+    return sessionStorage.getItem(key);
+  }
+
+  removeItem(key: string): void {
+    if (typeof sessionStorage === 'undefined') {
+      return;
+    }
+    sessionStorage.removeItem(key);
+  }
+
+  clear(): void {
+    if (typeof sessionStorage === 'undefined') {
+      return;
+    }
+    sessionStorage.clear();
+  }
+}
+
+/**
+ * In-memory storage strategy that stores data in a Map.
+ * This storage is cleared when the page is refreshed.
+ * Provides better XSS protection than sessionStorage but requires re-authentication on page reload.
+ */
+export class MemoryStorageStrategy implements StorageStrategy {
+  private store = new Map<string, string>();
+
+  setItem(key: string, value: string): void {
+    this.store.set(key, value);
+  }
+
+  getItem(key: string): string | null {
+    return this.store.get(key) ?? null;
+  }
+
+  removeItem(key: string): void {
+    this.store.delete(key);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}

package/src/URLBuilder.ts

@@ -0,0 +1,71 @@
+import type { SignInWithYouVersionPermissionValues } from './types';
+import { YouVersionPlatformConfiguration } from './YouVersionPlatformConfiguration';
+
+export class URLBuilder {
+  private static get baseURL(): URL {
+    return new URL(`https://${YouVersionPlatformConfiguration.apiHost}`);
+  }
+
+  static authURL(
+    appId: string,
+    requiredPermissions: Set<SignInWithYouVersionPermissionValues> = new Set<SignInWithYouVersionPermissionValues>(),
+    optionalPermissions: Set<SignInWithYouVersionPermissionValues> = new Set<SignInWithYouVersionPermissionValues>(),
+  ): URL {
+    if (typeof appId !== 'string' || appId.trim().length === 0) {
+      throw new Error('appId must be a non-empty string');
+    }
+
+    try {
+      const url = new URL(this.baseURL);
+      url.pathname = '/auth/login';
+
+      // Add query parameters
+      const searchParams = new URLSearchParams();
+      searchParams.append('app_id', appId);
+      searchParams.append('language', 'en'); // TODO: load from system
+
+      if (requiredPermissions.size > 0) {
+        const requiredList = Array.from(requiredPermissions).map((p) => p.toString());
+        searchParams.append('required_perms', requiredList.join(','));
+      }
+
+      if (optionalPermissions.size > 0) {
+        const optionalList = Array.from(optionalPermissions).map((p) => p.toString());
+        searchParams.append('opt_perms', optionalList.join(','));
+      }
+
+      const installationId = YouVersionPlatformConfiguration.installationId;
+      if (installationId) {
+        searchParams.append('x-yvp-installation-id', installationId);
+      }
+
+      url.search = searchParams.toString();
+      return url;
+    } catch (error) {
+      throw new Error(
+        `Failed to construct auth URL: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
+
+  static userURL(accessToken: string): URL {
+    if (typeof accessToken !== 'string' || accessToken.trim().length === 0) {
+      throw new Error('accessToken must be a non-empty string');
+    }
+
+    try {
+      const url = new URL(this.baseURL);
+      url.pathname = '/auth/me';
+
+      const searchParams = new URLSearchParams();
+      searchParams.append('lat', accessToken);
+
+      url.search = searchParams.toString();
+      return url;
+    } catch (error) {
+      throw new Error(
+        `Failed to construct user URL: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
+}

package/src/Users.ts

@@ -0,0 +1,137 @@
+import type { SignInWithYouVersionPermissionValues } from './types';
+import { SignInWithYouVersionResult } from './SignInWithYouVersionResult';
+import { YouVersionUserInfo } from './YouVersionUserInfo';
+import { YouVersionPlatformConfiguration } from './YouVersionPlatformConfiguration';
+import { YouVersionAPI } from './YouVersionAPI';
+import { URLBuilder } from './URLBuilder';
+import { AuthenticationStrategyRegistry } from './AuthenticationStrategy';
+
+const MAX_RETRY_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 1000;
+
+export class YouVersionAPIUsers {
+  /**
+   * Presents the YouVersion login flow to the user and returns the login result upon completion.
+   *
+   * This function authenticates the user with YouVersion, requesting the specified required and optional permissions.
+   * The function returns a promise that resolves when the user completes or cancels the login flow,
+   * returning the login result containing the authorization code and granted permissions.
+   *
+   * @param requiredPermissions - The set of permissions that must be granted by the user for successful login.
+   * @param optionalPermissions - The set of permissions that will be requested from the user but are not required for successful login.
+   * @returns A Promise resolving to a SignInWithYouVersionResult containing the authorization code and granted permissions upon successful login.
+   * @throws An error if authentication fails or is cancelled by the user.
+   */
+  static async signIn(
+    requiredPermissions: Set<SignInWithYouVersionPermissionValues>,
+    optionalPermissions: Set<SignInWithYouVersionPermissionValues>,
+  ): Promise<SignInWithYouVersionResult> {
+    // Validate inputs
+    if (!requiredPermissions || !(requiredPermissions instanceof Set)) {
+      throw new Error('Invalid requiredPermissions: must be a Set');
+    }
+    if (!optionalPermissions || !(optionalPermissions instanceof Set)) {
+      throw new Error('Invalid optionalPermissions: must be a Set');
+    }
+
+    const appId = YouVersionPlatformConfiguration.appId;
+    if (!appId) {
+      throw new Error('YouVersionPlatformConfiguration.appId must be set before calling signIn');
+    }
+
+    const url = URLBuilder.authURL(appId, requiredPermissions, optionalPermissions);
+
+    // Use the registered authentication strategy
+    const strategy = AuthenticationStrategyRegistry.get();
+    const callbackUrl = await strategy.authenticate(url);
+    const result = new SignInWithYouVersionResult(callbackUrl);
+
+    if (result.accessToken) {
+      YouVersionPlatformConfiguration.setAccessToken(result.accessToken);
+    }
+
+    return result;
+  }
+
+  static signOut(): void {
+    YouVersionPlatformConfiguration.setAccessToken(null);
+  }
+
+  /**
+   * Retrieves user information for the authenticated user using the provided access token.
+   *
+   * This function fetches the user's profile information from the YouVersion API, decoding it into a YouVersionUserInfo model.
+   *
+   * @param accessToken - The access token obtained from the login process.
+   * @returns A Promise resolving to a YouVersionUserInfo object containing the user's profile information.
+   * @throws An error if the URL is invalid, the network request fails, or the response cannot be decoded.
+   */
+  static async userInfo(accessToken: string): Promise<YouVersionUserInfo> {
+    // Validate access token
+    if (!accessToken || typeof accessToken !== 'string') {
+      throw new Error('Invalid access token: must be a non-empty string');
+    }
+
+    // Check for preview mode if configured
+    if (YouVersionPlatformConfiguration.isPreviewMode && accessToken === 'preview') {
+      return (
+        YouVersionPlatformConfiguration.previewUserInfo ||
+        new YouVersionUserInfo({
+          first_name: 'Preview',
+          last_name: 'User',
+          id: 'preview-user',
+          avatar_url: undefined,
+        })
+      );
+    }
+
+    const url = URLBuilder.userURL(accessToken);
+
+    const request = YouVersionAPI.addStandardHeaders(url);
+
+    // Retry logic for transient failures
+    let lastError: Error | null = null;
+    for (let attempt = 1; attempt <= MAX_RETRY_ATTEMPTS; attempt++) {
+      try {
+        const response = await fetch(request);
+
+        if (response.status === 401) {
+          throw new Error(
+            'Authentication failed: Invalid or expired access token. Please sign in again.',
+          );
+        }
+
+        if (response.status === 403) {
+          throw new Error('Access denied: Insufficient permissions to retrieve user information');
+        }
+
+        if (response.status !== 200) {
+          throw new Error(
+            `Failed to retrieve user information: Server responded with status ${response.status}`,
+          );
+        }
+
+        const data = (await response.json()) as YouVersionUserInfo;
+        return data;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error('Failed to parse server response');
+
+        // Don't retry on authentication errors
+        if (
+          error instanceof Error &&
+          (error.message.includes('401') || error.message.includes('403'))
+        ) {
+          throw error;
+        }
+
+        // Retry on network errors
+        if (attempt < MAX_RETRY_ATTEMPTS) {
+          await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS * attempt));
+          continue;
+        }
+      }
+    }
+
+    throw lastError || new Error('Failed to retrieve user information after multiple attempts');
+  }
+}

package/src/WebAuthenticationStrategy.ts

@@ -0,0 +1,127 @@
+import type { AuthenticationStrategy } from './AuthenticationStrategy';
+import { SessionStorageStrategy, type StorageStrategy } from './StorageStrategy';
+
+/* Web-based authentication strategy
+ * Uses redirect flow
+ */
+export class WebAuthenticationStrategy implements AuthenticationStrategy {
+  private redirectUri: string;
+  private callbackPath: string;
+  private timeout: number;
+  private storage: StorageStrategy;
+  private static pendingAuthResolve: ((url: URL) => void) | null = null;
+  private static pendingAuthReject: ((error: Error) => void) | null = null;
+  private static timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(options?: {
+    redirectUri?: string;
+    callbackPath?: string;
+    timeout?: number;
+    storage?: StorageStrategy;
+  }) {
+    this.callbackPath = options?.callbackPath ?? '/auth/callback';
+    this.redirectUri = options?.redirectUri ?? window.location.origin + this.callbackPath;
+    this.timeout = options?.timeout ?? 300000; // 5 minutes default
+    this.storage = options?.storage ?? new SessionStorageStrategy();
+  }
+
+  async authenticate(authUrl: URL): Promise<URL> {
+    // Update the redirect URI in the auth URL
+    authUrl.searchParams.set('redirect_uri', this.redirectUri);
+
+    return this.authenticateWithRedirect(authUrl);
+  }
+
+  /**
+   * Call this method when your app loads to handle the redirect callback
+   */
+  static handleCallback(callbackPath: string = '/auth/callback'): boolean {
+    const currentUrl = new URL(window.location.href);
+
+    // Check if this is a callback URL
+    if (currentUrl.pathname === callbackPath && currentUrl.searchParams.has('status')) {
+      // For web apps, use the HTTP URL directly (no need to convert to youversionauth scheme)
+      const callbackUrl = new URL(currentUrl.toString());
+
+      if (WebAuthenticationStrategy.pendingAuthResolve) {
+        WebAuthenticationStrategy.pendingAuthResolve(callbackUrl);
+        WebAuthenticationStrategy.cleanup();
+      } else {
+        // Store the callback URL for later retrieval
+        const storageStrategy = new SessionStorageStrategy();
+        storageStrategy.setItem('youversion-auth-callback', callbackUrl.toString());
+      }
+
+      const storageStrategy = new SessionStorageStrategy();
+      const returnUrl = storageStrategy.getItem('youversion-auth-return') ?? '/';
+      storageStrategy.removeItem('youversion-auth-return');
+      window.history.replaceState({}, '', returnUrl);
+
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Clean up pending authentication state
+   */
+  static cleanup(): void {
+    if (WebAuthenticationStrategy.timeoutId) {
+      clearTimeout(WebAuthenticationStrategy.timeoutId);
+      WebAuthenticationStrategy.timeoutId = null;
+    }
+    WebAuthenticationStrategy.pendingAuthResolve = null;
+    WebAuthenticationStrategy.pendingAuthReject = null;
+  }
+
+  /**
+   * Retrieve stored callback result if available
+   */
+  static getStoredCallback(): URL | null {
+    const storageStrategy = new SessionStorageStrategy();
+    const stored = storageStrategy.getItem('youversion-auth-callback');
+    if (stored) {
+      storageStrategy.removeItem('youversion-auth-callback');
+      try {
+        return new URL(stored);
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  private authenticateWithRedirect(authUrl: URL): Promise<URL> {
+    // Clean up any existing state
+    WebAuthenticationStrategy.cleanup();
+
+    // Store return URL in configured storage
+    this.storage.setItem('youversion-auth-return', window.location.href);
+
+    // Set up the promise that will be resolved when we come back
+    return new Promise((resolve, reject) => {
+      WebAuthenticationStrategy.pendingAuthResolve = resolve;
+      WebAuthenticationStrategy.pendingAuthReject = reject;
+
+      // Set up timeout
+      WebAuthenticationStrategy.timeoutId = setTimeout(() => {
+        WebAuthenticationStrategy.cleanup();
+        reject(new Error('Authentication timeout'));
+      }, this.timeout);
+
+      // Handle cases where navigation might fail
+      try {
+        // Redirect to auth URL
+        window.location.href = authUrl.toString();
+      } catch (error) {
+        WebAuthenticationStrategy.cleanup();
+        reject(
+          new Error(
+            `Failed to navigate to auth URL: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          ),
+        );
+      }
+    });
+  }
+}

package/src/YouVersionAPI.ts

@@ -0,0 +1,27 @@
+import { YouVersionPlatformConfiguration } from './YouVersionPlatformConfiguration';
+
+export class YouVersionAPI {
+  static addStandardHeaders(url: URL): Request {
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    };
+
+    // Add app ID header
+    const appId = YouVersionPlatformConfiguration.appId;
+    if (appId) {
+      headers['X-App-Id'] = appId;
+    }
+
+    // Add installation ID header
+    const installationId = YouVersionPlatformConfiguration.installationId;
+    if (installationId) {
+      headers['x-yvp-installation-id'] = installationId;
+    }
+
+    const request = new Request(url.toString(), {
+      headers,
+    });
+    return request;
+  }
+}