@youversion/platform-core 1.9.2 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-core",
-  "version": "1.9.2",
+  "version": "1.11.0",
   "type": "module",
   "publishConfig": {
     "access": "public",

package/src/__tests__/MockLanguages.ts

@@ -76,6 +76,21 @@ export const mockLanguages: Language[] = [
     speaking_population: 8000000,
     default_bible_id: null,
   },
+  {
+    id: 'por',
+    language: 'por',
+    script: 'Latn',
+    script_name: 'Latin',
+    aliases: ['pt'],
+    display_names: { en: 'Portuguese', pt: 'português' },
+    scripts: ['Latn'],
+    variants: [],
+    countries: ['PT', 'BR'],
+    text_direction: 'ltr',
+    writing_population: 250000000,
+    speaking_population: 250000000,
+    default_bible_id: null,
+  },
   // Add more languages to exceed the maximum page size and exercise pagination
   ...Array.from({ length: 120 }, (_, i) => ({
     id: `lang${i + 1}`,

package/src/__tests__/handlers.ts

@@ -45,7 +45,12 @@ export const handlers = [
       : mockLanguages;
 
     const defaultPageSize = 25;
-    const size = pageSize ? parseInt(pageSize, 10) : defaultPageSize;
+    const size =
+      pageSize === '*'
+        ? filteredLanguages.length
+        : pageSize
+          ? parseInt(pageSize, 10)
+          : defaultPageSize;
     let start = 0;
 
     if (pageToken) {

package/src/__tests__/languages.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { ApiClient } from '../client';
 import { LanguagesClient } from '../languages';
 import { LanguageSchema } from '../schemas';
@@ -60,6 +60,116 @@ describe('LanguagesClient', () => {
         'Country code must be a 2-character ISO 3166-1 alpha-2 code',
       );
     });
+
+    it('should normalize lowercase country codes to uppercase', async () => {
+      const getSpy = vi.spyOn(apiClient, 'get');
+
+      await languagesClient.getLanguages({ country: 'us', page_size: 5 });
+
+      expect(getSpy).toHaveBeenCalledWith(
+        '/v1/languages',
+        expect.objectContaining({ country: 'US' }),
+      );
+      getSpy.mockRestore();
+    });
+
+    it('should fetch languages with valid fields filter', async () => {
+      const languages = await languagesClient.getLanguages({
+        fields: ['id', 'language', 'script'],
+        page_size: 10,
+      });
+
+      expect(languages.data).toHaveLength(10);
+    });
+
+    it('should throw an error for invalid field name', async () => {
+      await expect(
+        languagesClient.getLanguages({
+          // @ts-expect-error - testing invalid field name
+          fields: ['id', 'invalid_field'],
+        }),
+      ).rejects.toThrow();
+    });
+
+    it('should return all languages with no pagination when page_size="*" and fields are valid', async () => {
+      const languages = await languagesClient.getLanguages({
+        fields: ['id', 'language'],
+        page_size: '*',
+      });
+
+      // page_size="*" should return all results with no next page token
+      expect(languages.next_page_token).toBeNull();
+      // Should return more than the default page size (25)
+      expect(languages.data.length).toBeGreaterThan(25);
+      // Should equal total_size since we're fetching all
+      expect(languages.data.length).toBe(languages.total_size);
+    });
+
+    it('should throw an error for page_size="*" without fields', async () => {
+      await expect(
+        languagesClient.getLanguages({
+          page_size: '*',
+        }),
+      ).rejects.toThrow('page_size="*" requires 1-3 fields to be specified');
+    });
+
+    it('should throw an error for page_size="*" with empty fields array', async () => {
+      await expect(
+        languagesClient.getLanguages({
+          fields: [],
+          page_size: '*',
+        }),
+      ).rejects.toThrow('page_size="*" requires 1-3 fields to be specified');
+    });
+
+    it('should throw an error for page_size="*" with more than 3 fields', async () => {
+      await expect(
+        languagesClient.getLanguages({
+          fields: ['id', 'language', 'script', 'script_name'],
+          page_size: '*',
+        }),
+      ).rejects.toThrow('page_size="*" requires 1-3 fields to be specified');
+    });
+
+    it('should allow page_size="*" with exactly 1 field', async () => {
+      const languages = await languagesClient.getLanguages({
+        fields: ['id'],
+        page_size: '*',
+      });
+      expect(languages.data.length).toBeGreaterThan(0);
+    });
+
+    it('should allow page_size="*" with exactly 3 fields', async () => {
+      const languages = await languagesClient.getLanguages({
+        fields: ['id', 'language', 'script'],
+        page_size: '*',
+      });
+      expect(languages.data.length).toBeGreaterThan(0);
+    });
+
+    it('should throw an error for invalid page_size - negative number', async () => {
+      await expect(
+        languagesClient.getLanguages({
+          page_size: -1,
+        }),
+      ).rejects.toThrow();
+    });
+
+    it('should throw an error for invalid page_size - zero', async () => {
+      await expect(
+        languagesClient.getLanguages({
+          page_size: 0,
+        }),
+      ).rejects.toThrow();
+    });
+
+    it('should throw an error for invalid page_size - decimal', async () => {
+      await expect(
+        languagesClient.getLanguages({
+          page_size: 10.5,
+        }),
+      ).rejects.toThrow();
+    });
   });
 
   describe('getLanguage', () => {
@@ -106,5 +216,43 @@ describe('LanguagesClient', () => {
         'Language ID must match BCP 47 format (language or language+script)',
       );
     });
+
+    it('should throw an error for invalid language ID - single character', async () => {
+      await expect(languagesClient.getLanguage('e')).rejects.toThrow(
+        'Language ID must match BCP 47 format (language or language+script)',
+      );
+    });
+
+    it('should throw an error for invalid language ID - too long without script', async () => {
+      await expect(languagesClient.getLanguage('engl')).rejects.toThrow(
+        'Language ID must match BCP 47 format (language or language+script)',
+      );
+    });
+
+    it('should throw an error for invalid language ID - invalid script format (lowercase)', async () => {
+      await expect(languagesClient.getLanguage('sr-latn')).rejects.toThrow(
+        'Language ID must match BCP 47 format (language or language+script)',
+      );
+    });
+
+    it('should throw an error for invalid language ID - script too short', async () => {
+      await expect(languagesClient.getLanguage('sr-Lat')).rejects.toThrow(
+        'Language ID must match BCP 47 format (language or language+script)',
+      );
+    });
+
+    it('should throw an error for invalid language ID - script too long', async () => {
+      await expect(languagesClient.getLanguage('sr-Latin')).rejects.toThrow(
+        'Language ID must match BCP 47 format (language or language+script)',
+      );
+    });
+
+    it('should accept valid 3-letter language code', async () => {
+      const language = await languagesClient.getLanguage('por');
+
+      const { success } = LanguageSchema.safeParse(language);
+      expect(success).toBe(true);
+      expect(language.id).toBe('por');
+    });
   });
 });

package/src/languages.ts

@@ -1,12 +1,14 @@
 import { z } from 'zod';
 import type { ApiClient } from './client';
 import type { Collection, Language } from './types';
+import { LanguageSchema } from './schemas';
 
 /**
  * Options for getting languages collection.
  */
 export type GetLanguagesOptions = {
-  page_size?: number;
+  page_size?: number | '*';
+  fields?: (keyof Language)[];
   page_token?: string;
   country?: string; // ISO 3166-1 alpha-2 country code
 };
@@ -17,7 +19,7 @@ export type GetLanguagesOptions = {
 export class LanguagesClient {
   private client: ApiClient;
 
-  private languageIdSchema = z
+  private static readonly languageIdSchema = z
     .string()
     .trim()
     .min(1, 'Language ID must be a non-empty string')
@@ -25,12 +27,32 @@ export class LanguagesClient {
       /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?$/,
       'Language ID must match BCP 47 format (language or language+script)',
     );
-  private countrySchema = z
+  private static readonly countrySchema = z
     .string()
     .trim()
     .length(2, 'Country code must be a 2-character ISO 3166-1 alpha-2 code')
     .toUpperCase();
 
+  private static readonly GetLanguagesOptionsSchema = z
+    .object({
+      page_size: z.union([z.number(), z.literal('*')]).optional(),
+      fields: z.array(LanguageSchema.keyof()).optional(),
+      page_token: z.string().optional(),
+      country: LanguagesClient.countrySchema,
+    })
+    .refine(
+      (data) => {
+        if (data.page_size === '*') {
+          return data.fields && data.fields?.length >= 1 && data.fields?.length <= 3;
+        }
+        return true;
+      },
+      {
+        message: 'page_size="*" required 1-3 fields to be specified',
+        path: ['page_size', 'fields'],
+      },
+    );
+
   /**
    * Creates a new LanguagesClient instance.
    * @param client The API client to use for requests.
@@ -45,16 +67,30 @@ export class LanguagesClient {
    * @returns A collection of Language objects.
    */
   async getLanguages(options: GetLanguagesOptions = {}): Promise<Collection<Language>> {
-    const params: Record<string, string | number> = {};
+    const params: Record<string, string | number | (keyof Language)[]> = {};
 
     if (options.country !== undefined) {
-      const country = this.countrySchema.parse(options.country);
+      const country = LanguagesClient.countrySchema.parse(options.country);
       params.country = country;
     }
 
+    if (options.fields !== undefined) {
+      const fieldsSchema = z.array(LanguageSchema.keyof());
+      fieldsSchema.parse(options.fields);
+      params['fields[]'] = options.fields;
+    }
+
     if (options.page_size !== undefined) {
-      const pageSizeSchema = z.number().int().positive();
+      const pageSizeSchema = z.union([z.number().int().positive(), z.literal('*')]);
       pageSizeSchema.parse(options.page_size);
+
+      if (options.page_size === '*') {
+        const fieldsCount = options.fields?.length ?? 0;
+        if (fieldsCount < 1 || fieldsCount > 3) {
+          throw new Error('page_size="*" requires 1-3 fields to be specified');
+        }
+      }
+
       params.page_size = options.page_size;
     }
 
@@ -71,7 +107,7 @@ export class LanguagesClient {
    * @returns The requested Language object.
    */
   async getLanguage(languageId: string): Promise<Language> {
-    this.languageIdSchema.parse(languageId);
+    LanguagesClient.languageIdSchema.parse(languageId);
     return this.client.get<Language>(`/v1/languages/${languageId}`);
   }
 }