@youversion/platform-core 1.8.0 → 1.9.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @youversion/platform-core@1.8.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
+> @youversion/platform-core@1.9.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
@@ -13,6 +13,6 @@
 CJS dist/index.cjs 43.59 KB
 CJS ⚡️ Build success in 35ms
 DTS Build start
-DTS ⚡️ Build success in 1754ms
-DTS dist/index.d.cts 32.92 KB
-DTS dist/index.d.ts  32.92 KB
+DTS ⚡️ Build success in 1915ms
+DTS dist/index.d.cts 32.91 KB
+DTS dist/index.d.ts  32.91 KB

package/AGENTS.md

@@ -0,0 +1,79 @@
+# @youversion/platform-core
+
+## OVERVIEW
+Foundation package providing pure TypeScript API clients for YouVersion services with zero React dependencies.
+
+**Related packages:**
+- For React hooks wrapping these clients → see `packages/hooks/AGENTS.md`
+- For pre-built UI components → see `packages/ui/AGENTS.md`
+
+## STRUCTURE
+```
+schemas/                     # Zod schemas for all data types (schema-first design)
+client.ts                    # ApiClient - main HTTP client
+bible.ts                     # BibleClient - Bible data operations
+languages.ts                 # LanguagesClient - language data
+highlights.ts                # HighlightsClient - user highlights
+YouVersionAPI.ts             # Base YouVersion API client
+SignInWithYouVersionPKCE.ts  # PKCE auth implementation
+StorageStrategy.ts           # Storage interface (SessionStorage, MemoryStorage)
+```
+
+## PUBLIC API
+- `ApiClient`: Main HTTP client with auth handling
+- `BibleClient`: Fetch Bibles, chapters, verses, versions
+- `LanguagesClient`: Get available languages
+- `HighlightsClient`: Manage user highlights
+- `SignInWithYouVersionPKCE()`: PKCE auth flow function
+- `SessionStorage`, `MemoryStorage`: Storage strategies
+
+## DOs / DON'Ts
+
+✅ Do: Keep this package **framework-agnostic** (no React, no DOM, no browser-only APIs)
+✅ Do: Define all input/output types in `schemas/` using Zod; schemas are the single source of truth
+✅ Do: Reuse `YouVersionAPI` base client for new service clients
+✅ Do: Parse API responses with Zod schemas for validation
+
+❌ Don't: Import React, `window`, `document`, or browser storage APIs directly
+❌ Don't: Bypass Zod validation for API responses
+❌ Don't: Implement UI, hooks, or React state here
+
+## ADDING A NEW ENDPOINT OR CLIENT
+
+1. **Define types** in `schemas/` using Zod:
+   - Request payload schema
+   - Response schema
+2. **Extend or add a client**:
+   - Prefer extending existing clients (e.g., `BibleClient`) when the endpoint logically belongs there
+   - Otherwise, create `xyz.ts` with a new `XyzClient` that composes `YouVersionAPI`
+3. **Wire validation**:
+   - Parse API responses with the corresponding Zod schema
+   - Throw or return typed errors on validation failure
+4. **Export from public API**:
+   - Expose the new client/types from the main entry file so consumers can import them
+5. **Add tests**:
+   - Unit tests with MSW for mock responses
+   - Optional integration tests guarded by `INTEGRATION_TESTS=true`
+
+## HTTP & CONFIGURATION
+
+- HTTP client: Native `fetch` API
+- Base client: `YouVersionAPI` handles base URL, headers, auth tokens
+- All clients extend or compose `YouVersionAPI` for consistent HTTP behavior
+
+## CONVENTIONS
+- Schema-first: All types defined in schemas/*.ts using Zod
+- Zero React: Pure TypeScript, no React dependencies
+- Storage: Abstract via StorageStrategy interface
+- Auth: PKCE flow with pluggable storage backends
+- Error handling: Zod validation for all API responses
+
+## TESTING
+
+- Run tests: `pnpm --filter @youversion/platform-core test`
+- Framework: Vitest with Node environment
+- Mocking: MSW for API endpoints
+- Integration tests:
+  - Guarded by `INTEGRATION_TESTS=true`
+  - Only run in CI or when explicitly needed; default to mocked tests
+- Coverage: @vitest/coverage-v8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @youversion/platform-core
 
+## 1.9.0
+
+### Minor Changes
+
+- d4b0071: feat(hooks): Add useLanguage hook to retrieve a language from api
+
+## 1.8.1
+
+### Patch Changes
+
+- 607be3c: Refactor verse HTML transformation to support verse-level highlighting. Extract HTML processing logic to `verse-html-utils.ts` with new `wrapVerseContent()` function that wraps verse content in CSS-targetable `<span class="yv-v">` elements. Simplify footnote extraction using wrapped verse structure. Remove CSS rule preventing text wrapping. Add comprehensive test coverage for verse wrapping behavior.
+
 ## 1.8.0
 
 ### Minor Changes

package/dist/index.d.cts

@@ -166,7 +166,7 @@ declare const LanguageSchema: z.ZodObject<{
     }>>;
     writing_population: z.ZodOptional<z.ZodNumber>;
     speaking_population: z.ZodOptional<z.ZodNumber>;
-    default_bible_version_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    default_bible_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 type Language = Readonly<z.infer<typeof LanguageSchema>>;
 

package/dist/index.d.ts

@@ -166,7 +166,7 @@ declare const LanguageSchema: z.ZodObject<{
     }>>;
     writing_population: z.ZodOptional<z.ZodNumber>;
     speaking_population: z.ZodOptional<z.ZodNumber>;
-    default_bible_version_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    default_bible_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 type Language = Readonly<z.infer<typeof LanguageSchema>>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-core",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -30,8 +30,8 @@
     "tsup": "8.5.0",
     "typescript": "5.9.3",
     "vitest": "4.0.4",
-    "@internal/eslint-config": "0.0.0",
-    "@internal/tsconfig": "0.0.0"
+    "@internal/tsconfig": "0.0.0",
+    "@internal/eslint-config": "0.0.0"
   },
   "dependencies": {
     "zod": "4.1.12"

package/src/__tests__/MockLanguages.ts

@@ -14,7 +14,7 @@ export const mockLanguages: Language[] = [
     text_direction: 'ltr',
     writing_population: 1500000000,
     speaking_population: 1500000000,
-    default_bible_version_id: null,
+    default_bible_id: null,
   },
   {
     id: 'es',
@@ -29,7 +29,7 @@ export const mockLanguages: Language[] = [
     text_direction: 'ltr',
     writing_population: 500000000,
     speaking_population: 500000000,
-    default_bible_version_id: null,
+    default_bible_id: null,
   },
   {
     id: 'fr',
@@ -44,7 +44,7 @@ export const mockLanguages: Language[] = [
     text_direction: 'ltr',
     writing_population: 300000000,
     speaking_population: 300000000,
-    default_bible_version_id: null,
+    default_bible_id: null,
   },
   {
     id: 'de',
@@ -59,7 +59,7 @@ export const mockLanguages: Language[] = [
     text_direction: 'ltr',
     writing_population: 100000000,
     speaking_population: 100000000,
-    default_bible_version_id: null,
+    default_bible_id: null,
   },
   {
     id: 'sr-Latn',
@@ -74,7 +74,7 @@ export const mockLanguages: Language[] = [
     text_direction: 'ltr',
     writing_population: 8000000,
     speaking_population: 8000000,
-    default_bible_version_id: null,
+    default_bible_id: null,
   },
   // Add more languages to exceed the maximum page size and exercise pagination
   ...Array.from({ length: 120 }, (_, i) => ({
@@ -90,6 +90,6 @@ export const mockLanguages: Language[] = [
     text_direction: 'ltr' as const,
     writing_population: 1000000,
     speaking_population: 1000000,
-    default_bible_version_id: null,
+    default_bible_id: null,
   })),
 ];

package/src/schemas/language.ts

@@ -32,7 +32,7 @@ export const LanguageSchema = z.object({
   /** Speaking population count */
   speaking_population: z.number().int().optional(),
   /** Default Bible version ID for this language */
-  default_bible_version_id: z.number().int().nullable().optional(),
+  default_bible_id: z.number().int().nullable().optional(),
 });
 
 export type Language = Readonly<z.infer<typeof LanguageSchema>>;