@youversion/platform-core 1.2.1 → 1.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @youversion/platform-core@1.2.1 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
-ESM dist/index.js 41.09 KB
+ESM dist/index.js 41.47 KB
 ESM ⚡️ Build success in 34ms
-CJS dist/index.cjs 42.90 KB
-CJS ⚡️ Build success in 34ms
+CJS dist/index.cjs 43.29 KB
+CJS ⚡️ Build success in 35ms
 DTS Build start
-DTS ⚡️ Build success in 2020ms
-DTS dist/index.d.cts 32.78 KB
-DTS dist/index.d.ts  32.78 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,17 @@
 # @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

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;

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.

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.

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;

package/package.json

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

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/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}` : '';
   }