@youversion/platform-core 1.2.0 → 1.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @youversion/platform-core@1.2.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
+> @youversion/platform-core@1.3.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
 > tsup src/index.ts --format cjs,esm --dts
 
 CLI Building entry: src/index.ts
@@ -8,11 +8,11 @@
 CLI Target: es2022
 CJS Build start
 ESM Build start
-CJS dist/index.cjs 42.87 KB
-CJS ⚡️ Build success in 31ms
-ESM dist/index.js 41.06 KB
-ESM ⚡️ Build success in 32ms
+ESM dist/index.js 41.47 KB
+ESM ⚡️ Build success in 34ms
+CJS dist/index.cjs 43.29 KB
+CJS ⚡️ Build success in 35ms
 DTS Build start
-DTS ⚡️ Build success in 1751ms
-DTS dist/index.d.cts 32.80 KB
-DTS dist/index.d.ts  32.80 KB
+DTS ⚡️ Build success in 1804ms
+DTS dist/index.d.cts 32.84 KB
+DTS dist/index.d.ts  32.84 KB

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @youversion/platform-core
 
+## 1.3.0
+
+### Minor Changes
+
+- b2b86c2: Add support for array query parameters in API client and improve language range handling
+  - **API Client**: Enhanced query string serialization to support array parameters, properly formatting them as repeated keys (e.g., `?param=one&param=two`)
+  - **Bible Client**: Updated `getVersions()` method to accept either a single language range string or an array of language ranges, providing more flexibility for filtering Bible versions
+  - **Schema**: Renamed language range schema to use plural naming convention for consistency
+  - **Testing**: Added comprehensive test coverage for query string building with both scalar and array parameters
+
+  This change maintains backward compatibility while providing more flexible API parameter handling.
+
+## 1.2.1
+
+### Patch Changes
+
+- e845974: fix: make country parameter optional for getLanguages
+
+  The country parameter is now optional when fetching languages, allowing developers to retrieve all available languages without filtering by country. This improves developer experience by providing a more flexible API while maintaining backward compatibility for existing code that provides a country filter.
+
 ## 1.2.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -69,9 +69,15 @@ var ApiClient = class {
    */
   buildQueryString(params) {
     if (!params) return "";
-    const queryString = new URLSearchParams(
-      Object.entries(params).map(([key, value]) => [key, String(value)])
-    ).toString();
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (Array.isArray(value)) {
+        value.forEach((item) => searchParams.append(key, String(item)));
+      } else {
+        searchParams.append(key, String(value));
+      }
+    });
+    const queryString = searchParams.toString();
     return queryString ? `?${queryString}` : "";
   }
   /**
@@ -205,14 +211,15 @@ var BibleClient = class {
   /**
    * Fetches a collection of Bible versions filtered by language ranges.
    *
-   * @param language_ranges - A comma-separated list of language codes or ranges to filter the versions (required).
+   * @param language_ranges - One or more language codes or ranges to filter the versions (required).
    * @param license_id - Optional license ID to filter versions by license.
    * @returns A promise that resolves to a collection of BibleVersion objects.
    */
   async getVersions(language_ranges, license_id) {
-    this.languageRangesSchema.parse(language_ranges);
+    const languageRangeArray = Array.isArray(language_ranges) ? language_ranges : [language_ranges];
+    const parsedLanguageRanges = import_zod.z.array(this.languageRangesSchema).nonempty("At least one language range is required").parse(languageRangeArray);
     const params = {
-      "language_ranges[]": language_ranges
+      "language_ranges[]": parsedLanguageRanges
     };
     if (license_id !== void 0) {
       params.license_id = license_id;
@@ -409,13 +416,15 @@ var LanguagesClient = class {
   }
   /**
    * Fetches a collection of languages supported in the Platform.
-   * @param options Query parameters for pagination and filtering (country is required).
+   * @param options Query parameters for pagination and filtering.
    * @returns A collection of Language objects.
    */
-  async getLanguages(options) {
+  async getLanguages(options = {}) {
     const params = {};
-    const country = this.countrySchema.parse(options.country);
-    params.country = country;
+    if (options.country !== void 0) {
+      const country = this.countrySchema.parse(options.country);
+      params.country = country;
+    }
     if (options.page_size !== void 0) {
       const pageSizeSchema = import_zod2.z.number().int().positive();
       pageSizeSchema.parse(options.page_size);

package/dist/index.d.cts

@@ -258,7 +258,8 @@ interface HighlightColor {
     label: string;
 }
 
-type QueryParams = Record<string, string | number | boolean>;
+type PrimitiveQueryParam = string | number | boolean;
+type QueryParams = Record<string, PrimitiveQueryParam | PrimitiveQueryParam[]>;
 type RequestData = Record<string, string | number | boolean | object>;
 type RequestHeaders = Record<string, string>;
 /**
@@ -333,11 +334,11 @@ declare class BibleClient {
     /**
      * Fetches a collection of Bible versions filtered by language ranges.
      *
-     * @param language_ranges - A comma-separated list of language codes or ranges to filter the versions (required).
+     * @param language_ranges - One or more language codes or ranges to filter the versions (required).
      * @param license_id - Optional license ID to filter versions by license.
      * @returns A promise that resolves to a collection of BibleVersion objects.
      */
-    getVersions(language_ranges: string, license_id?: string | number): Promise<Collection<BibleVersion>>;
+    getVersions(language_ranges: string | string[], license_id?: string | number): Promise<Collection<BibleVersion>>;
     /**
      * Fetches a Bible version by its ID.
      * @param id The version ID.
@@ -449,7 +450,7 @@ declare class BibleClient {
 type GetLanguagesOptions = {
     page_size?: number;
     page_token?: string;
-    country: string;
+    country?: string;
 };
 /**
  * Client for interacting with Languages API endpoints.
@@ -465,10 +466,10 @@ declare class LanguagesClient {
     constructor(client: ApiClient);
     /**
      * Fetches a collection of languages supported in the Platform.
-     * @param options Query parameters for pagination and filtering (country is required).
+     * @param options Query parameters for pagination and filtering.
      * @returns A collection of Language objects.
      */
-    getLanguages(options: GetLanguagesOptions): Promise<Collection<Language>>;
+    getLanguages(options?: GetLanguagesOptions): Promise<Collection<Language>>;
     /**
      * Fetches details about a specific language in the Platform.
      * @param languageId The BCP 47 language code (optionally including script, e.g., "en" or "sr-Latn").

package/dist/index.d.ts

@@ -258,7 +258,8 @@ interface HighlightColor {
     label: string;
 }
 
-type QueryParams = Record<string, string | number | boolean>;
+type PrimitiveQueryParam = string | number | boolean;
+type QueryParams = Record<string, PrimitiveQueryParam | PrimitiveQueryParam[]>;
 type RequestData = Record<string, string | number | boolean | object>;
 type RequestHeaders = Record<string, string>;
 /**
@@ -333,11 +334,11 @@ declare class BibleClient {
     /**
      * Fetches a collection of Bible versions filtered by language ranges.
      *
-     * @param language_ranges - A comma-separated list of language codes or ranges to filter the versions (required).
+     * @param language_ranges - One or more language codes or ranges to filter the versions (required).
      * @param license_id - Optional license ID to filter versions by license.
      * @returns A promise that resolves to a collection of BibleVersion objects.
      */
-    getVersions(language_ranges: string, license_id?: string | number): Promise<Collection<BibleVersion>>;
+    getVersions(language_ranges: string | string[], license_id?: string | number): Promise<Collection<BibleVersion>>;
     /**
      * Fetches a Bible version by its ID.
      * @param id The version ID.
@@ -449,7 +450,7 @@ declare class BibleClient {
 type GetLanguagesOptions = {
     page_size?: number;
     page_token?: string;
-    country: string;
+    country?: string;
 };
 /**
  * Client for interacting with Languages API endpoints.
@@ -465,10 +466,10 @@ declare class LanguagesClient {
     constructor(client: ApiClient);
     /**
      * Fetches a collection of languages supported in the Platform.
-     * @param options Query parameters for pagination and filtering (country is required).
+     * @param options Query parameters for pagination and filtering.
      * @returns A collection of Language objects.
      */
-    getLanguages(options: GetLanguagesOptions): Promise<Collection<Language>>;
+    getLanguages(options?: GetLanguagesOptions): Promise<Collection<Language>>;
     /**
      * Fetches details about a specific language in the Platform.
      * @param languageId The BCP 47 language code (optionally including script, e.g., "en" or "sr-Latn").

package/dist/index.js

@@ -30,9 +30,15 @@ var ApiClient = class {
    */
   buildQueryString(params) {
     if (!params) return "";
-    const queryString = new URLSearchParams(
-      Object.entries(params).map(([key, value]) => [key, String(value)])
-    ).toString();
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (Array.isArray(value)) {
+        value.forEach((item) => searchParams.append(key, String(item)));
+      } else {
+        searchParams.append(key, String(value));
+      }
+    });
+    const queryString = searchParams.toString();
     return queryString ? `?${queryString}` : "";
   }
   /**
@@ -166,14 +172,15 @@ var BibleClient = class {
   /**
    * Fetches a collection of Bible versions filtered by language ranges.
    *
-   * @param language_ranges - A comma-separated list of language codes or ranges to filter the versions (required).
+   * @param language_ranges - One or more language codes or ranges to filter the versions (required).
    * @param license_id - Optional license ID to filter versions by license.
    * @returns A promise that resolves to a collection of BibleVersion objects.
    */
   async getVersions(language_ranges, license_id) {
-    this.languageRangesSchema.parse(language_ranges);
+    const languageRangeArray = Array.isArray(language_ranges) ? language_ranges : [language_ranges];
+    const parsedLanguageRanges = z.array(this.languageRangesSchema).nonempty("At least one language range is required").parse(languageRangeArray);
     const params = {
-      "language_ranges[]": language_ranges
+      "language_ranges[]": parsedLanguageRanges
     };
     if (license_id !== void 0) {
       params.license_id = license_id;
@@ -370,13 +377,15 @@ var LanguagesClient = class {
   }
   /**
    * Fetches a collection of languages supported in the Platform.
-   * @param options Query parameters for pagination and filtering (country is required).
+   * @param options Query parameters for pagination and filtering.
    * @returns A collection of Language objects.
    */
-  async getLanguages(options) {
+  async getLanguages(options = {}) {
     const params = {};
-    const country = this.countrySchema.parse(options.country);
-    params.country = country;
+    if (options.country !== void 0) {
+      const country = this.countrySchema.parse(options.country);
+      params.country = country;
+    }
     if (options.page_size !== void 0) {
       const pageSizeSchema = z2.number().int().positive();
       pageSizeSchema.parse(options.page_size);

package/package.json

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

package/src/__tests__/{MockLangauges.ts → MockLanguages.ts}

@@ -76,8 +76,8 @@ export const mockLanguages: Language[] = [
     speaking_population: 8000000,
     default_bible_version_id: null,
   },
-  // Add more languages to reach 25 for default page size when filtering by 'US'
-  ...Array.from({ length: 24 }, (_, i) => ({
+  // Add more languages to exceed the maximum page size and exercise pagination
+  ...Array.from({ length: 120 }, (_, i) => ({
     id: `lang${i + 1}`,
     language: `lang${i + 1}`,
     script: 'Latn',
@@ -86,7 +86,7 @@ export const mockLanguages: Language[] = [
     display_names: {},
     scripts: ['Latn'],
     variants: [],
-    countries: ['US'],
+    countries: i % 2 === 0 ? ['US', 'CA'] : ['BR'],
     text_direction: 'ltr' as const,
     writing_population: 1000000,
     speaking_population: 1000000,

package/src/__tests__/bible.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
+import { http, HttpResponse } from 'msw';
 import { ApiClient } from '../client';
 import { BibleClient } from '../bible';
 import {
@@ -9,6 +10,8 @@ import {
   BibleVersionSchema,
   VOTDSchema,
 } from '../schemas';
+import { server } from './setup';
+import { mockVersions } from './MockVersions';
 
 describe('BibleClient', () => {
   let apiClient: ApiClient;
@@ -34,6 +37,50 @@ describe('BibleClient', () => {
       expect(hasNIV).toBe(true);
     });
 
+    it('should send multiple language ranges when provided', async () => {
+      server.use(
+        http.get('https://api.youversion.com/v1/bibles', ({ request }) => {
+          const url = new URL(request.url);
+          const languageRanges = url.searchParams.getAll('language_ranges[]');
+
+          expect(languageRanges).toEqual(['en*', 'es*']);
+
+          return HttpResponse.json({
+            data: mockVersions,
+            next_page_token: null,
+            total_size: mockVersions.length,
+          });
+        }),
+      );
+
+      const versions = await bibleClient.getVersions(['en*', 'es*']);
+
+      const { success } = BibleVersionSchema.safeParse(versions.data[0]);
+      expect(success).toBe(true);
+    });
+
+    it('should accept a wildcard language range', async () => {
+      server.use(
+        http.get('https://api.youversion.com/v1/bibles', ({ request }) => {
+          const url = new URL(request.url);
+          const languageRanges = url.searchParams.getAll('language_ranges[]');
+
+          expect(languageRanges).toEqual(['*']);
+
+          return HttpResponse.json({
+            data: mockVersions,
+            next_page_token: null,
+            total_size: mockVersions.length,
+          });
+        }),
+      );
+
+      const versions = await bibleClient.getVersions('*');
+
+      const { success } = BibleVersionSchema.safeParse(versions.data[0]);
+      expect(success).toBe(true);
+    });
+
     it('should throw an error for invalid language ranges', async () => {
       await expect(bibleClient.getVersions('')).rejects.toThrow(
         'Language ranges must be a non-empty string',
@@ -41,6 +88,9 @@ describe('BibleClient', () => {
       await expect(bibleClient.getVersions('   ')).rejects.toThrow(
         'Language ranges must be a non-empty string',
       );
+      await expect(bibleClient.getVersions([])).rejects.toThrow(
+        'At least one language range is required',
+      );
     });
   });
 

package/src/__tests__/client.test.ts

@@ -43,6 +43,45 @@ describe('ApiClient', () => {
     });
   });
 
+  describe('buildQueryString', () => {
+    const buildQueryString = (params?: Parameters<ApiClient['get']>[1]) =>
+      (
+        apiClient as unknown as {
+          buildQueryString: (params?: Parameters<ApiClient['get']>[1]) => string;
+        }
+      ).buildQueryString(params);
+
+    it('should serialize single scalar parameter', () => {
+      const query = buildQueryString({ param: 'value' });
+
+      expect(query).toBe('?param=value');
+    });
+
+    it('should serialize an array of length 1 as repeated key', () => {
+      const query = buildQueryString({ param: ['only'] });
+
+      expect(query).toBe('?param=only');
+    });
+
+    it('should serialize an array of length 2 as repeated keys', () => {
+      const query = buildQueryString({ param: ['one', 'two'] });
+
+      expect(query).toBe('?param=one&param=two');
+    });
+
+    it('should serialize an array of length 3 as repeated keys', () => {
+      const query = buildQueryString({ param: ['one', 'two', 'three'] });
+
+      expect(query).toBe('?param=one&param=two&param=three');
+    });
+
+    it('should handle both scalar and array parameters together', () => {
+      const query = buildQueryString({ param: 'value', list: ['one', 'two'] });
+
+      expect(query).toBe('?param=value&list=one&list=two');
+    });
+  });
+
   describe('get', () => {
     it('should make GET request and return data', async () => {
       server.use(
@@ -71,6 +110,22 @@ describe('ApiClient', () => {
 
       expect(result).toEqual({ param: 'value' });
     });
+
+    it('should include array query parameters as repeated keys', async () => {
+      server.use(
+        http.get('https://test_placeholder.youversion.com/test', ({ request }) => {
+          const url = new URL(request.url);
+          const params = url.searchParams.getAll('param');
+          return HttpResponse.json({ params });
+        }),
+      );
+
+      const result = await apiClient.get<{ params: string[] }>('/test', {
+        param: ['one', 'two'],
+      });
+
+      expect(result).toEqual({ params: ['one', 'two'] });
+    });
   });
 
   describe('post', () => {

package/src/__tests__/handlers.ts

@@ -1,6 +1,6 @@
 import { http, HttpResponse } from 'msw';
 import type { Collection, Highlight, Language } from '../types';
-import { mockLanguages } from './MockLangauges';
+import { mockLanguages } from './MockLanguages';
 import { mockVersions, mockVersionKJV } from './MockVersions';
 import { mockBibleGenesis, mockBibleBooks } from './MockBibles';
 import { mockChapterGenesis1, mockGenesisChapters } from './MockChapters';

package/src/__tests__/languages.test.ts

@@ -17,22 +17,23 @@ describe('LanguagesClient', () => {
   });
 
   describe('getLanguages', () => {
-    it('should fetch languages with required country param', async () => {
-      const languages = await languagesClient.getLanguages({ country: 'US' });
+    it('should fetch languages without country filter', async () => {
+      const languages = await languagesClient.getLanguages({ page_size: 99 });
 
       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']));
+      expect(languages.data).toHaveLength(99);
+      expect(languages.next_page_token).not.toBeNull();
     });
 
-    it('should fetch languages with page_size option', async () => {
-      const languages = await languagesClient.getLanguages({ country: 'US', page_size: 10 });
+    it('should fetch languages with country filter', async () => {
+      const languages = await languagesClient.getLanguages({ country: 'US', page_size: 20 });
 
       const { success } = LanguageSchema.safeParse(languages.data[0]);
       expect(success).toBe(true);
-      expect(languages.data).toHaveLength(10);
-      expect(languages.next_page_token).toBe('eyJzdGFydCI6IDEwfQ==');
+      expect(languages.data).toHaveLength(20);
+      expect(languages.data.every((language) => language.countries?.includes('US'))).toBe(true);
+      expect(languages.next_page_token).not.toBeNull();
     });
 
     it('should throw an error for invalid country code - empty string', async () => {

package/src/bible.ts

@@ -50,17 +50,23 @@ export class BibleClient {
   /**
    * Fetches a collection of Bible versions filtered by language ranges.
    *
-   * @param language_ranges - A comma-separated list of language codes or ranges to filter the versions (required).
+   * @param language_ranges - One or more language codes or ranges to filter the versions (required).
    * @param license_id - Optional license ID to filter versions by license.
    * @returns A promise that resolves to a collection of BibleVersion objects.
    */
   async getVersions(
-    language_ranges: string,
+    language_ranges: string | string[],
     license_id?: string | number,
   ): Promise<Collection<BibleVersion>> {
-    this.languageRangesSchema.parse(language_ranges);
-    const params: Record<string, string | number> = {
-      'language_ranges[]': language_ranges,
+    const languageRangeArray = Array.isArray(language_ranges) ? language_ranges : [language_ranges];
+
+    const parsedLanguageRanges = z
+      .array(this.languageRangesSchema)
+      .nonempty('At least one language range is required')
+      .parse(languageRangeArray);
+
+    const params: Record<string, string | number | string[]> = {
+      'language_ranges[]': parsedLanguageRanges,
     };
     if (license_id !== undefined) {
       params.license_id = license_id;

package/src/client.ts

@@ -1,6 +1,7 @@
 import type { ApiConfig } from './types';
 
-type QueryParams = Record<string, string | number | boolean>;
+type PrimitiveQueryParam = string | number | boolean;
+type QueryParams = Record<string, PrimitiveQueryParam | PrimitiveQueryParam[]>;
 type RequestData = Record<string, string | number | boolean | object>;
 type RequestHeaders = Record<string, string>;
 
@@ -41,9 +42,18 @@ export class ApiClient {
    */
   private buildQueryString(params?: QueryParams): string {
     if (!params) return '';
-    const queryString = new URLSearchParams(
-      Object.entries(params).map(([key, value]) => [key, String(value)]),
-    ).toString();
+
+    const searchParams = new URLSearchParams();
+
+    Object.entries(params).forEach(([key, value]) => {
+      if (Array.isArray(value)) {
+        value.forEach((item) => searchParams.append(key, String(item)));
+      } else {
+        searchParams.append(key, String(value));
+      }
+    });
+
+    const queryString = searchParams.toString();
     return queryString ? `?${queryString}` : '';
   }
 

package/src/languages.ts

@@ -8,7 +8,7 @@ import type { Collection, Language } from './types';
 export type GetLanguagesOptions = {
   page_size?: number;
   page_token?: string;
-  country: string; // ISO 3166-1 alpha-2 country code (required per OpenAPI spec)
+  country?: string; // ISO 3166-1 alpha-2 country code
 };
 
 /**
@@ -41,15 +41,16 @@ export class LanguagesClient {
 
   /**
    * Fetches a collection of languages supported in the Platform.
-   * @param options Query parameters for pagination and filtering (country is required).
+   * @param options Query parameters for pagination and filtering.
    * @returns A collection of Language objects.
    */
-  async getLanguages(options: GetLanguagesOptions): Promise<Collection<Language>> {
+  async getLanguages(options: GetLanguagesOptions = {}): Promise<Collection<Language>> {
     const params: Record<string, string | number> = {};
 
-    // Country is required per OpenAPI spec
-    const country = this.countrySchema.parse(options.country);
-    params.country = country;
+    if (options.country !== undefined) {
+      const country = this.countrySchema.parse(options.country);
+      params.country = country;
+    }
 
     if (options.page_size !== undefined) {
       const pageSizeSchema = z.number().int().positive();