@youversion/platform-core 0.4.2 → 0.4.4

package/.env.example

@@ -1,7 +1,5 @@
-YVP_API_BASE_URL=https://api-dev.youversion.com
-
 # Your application ID from YouVersion Platform
-YVP_APP_ID=""
+YVP_APP_KEY="ADD_YOUR_APP_KEY_HERE"
 
-# Optional: Authentication token for endpoints that require it
-YVP_AUTH_TOKEN=""
+# This should be left untouched unless you're helping test YouVersion's backend APIs.
+YVP_API_HOST=api.youversion.com

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @youversion/platform-core@0.4.2 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/core
+> @youversion/platform-core@0.4.4 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 39.89 KB
-CJS ⚡️ Build success in 36ms
-ESM dist/index.js 37.89 KB
-ESM ⚡️ Build success in 36ms
+CJS dist/index.cjs 39.59 KB
+CJS ⚡️ Build success in 39ms
+ESM dist/index.js 37.59 KB
+ESM ⚡️ Build success in 41ms
 DTS Build start
-DTS ⚡️ Build success in 2476ms
-DTS dist/index.d.cts 34.20 KB
-DTS dist/index.d.ts  34.20 KB
+DTS ⚡️ Build success in 2375ms
+DTS dist/index.d.cts 34.08 KB
+DTS dist/index.d.ts  34.08 KB

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @youversion/platform-core
 
+## 0.4.4
+
+### Patch Changes
+
+- 8dee8f6: chore: allow setting apiHost from React code
+
+## 0.4.3
+
+### Patch Changes
+
+- 7b652f7: chore(docs): update documentation and readmes, and env var usage
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -1,369 +1,109 @@
-# @youversion/platform-core
+![License](https://img.shields.io/badge/license-Apache%20License%202.0-blue)
+![Node.js >= 20.0.0](https://img.shields.io/badge/Node.js-%3E%3D%2020.0.0-339933?logo=node.js&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
 
-A powerful, type-safe TypeScript library for interacting with Bible data. This package provides a comprehensive API client for fetching Bible versions, books, chapters, verses, and user authentication from the YouVersion Bible API.
+# @youversion/platform-core
 
-## 🚀 Features
+A type-safe TypeScript SDK for accessing the YouVersion Platform APIs. Get Bible content and build Bible-based applications.
 
-- **🔒 Type-safe API** - Full TypeScript support with comprehensive type definitions
-- **🌐 Multi-language support** - Access Bible versions in multiple languages
-- **📚 Complete Bible data** - Versions, books, chapters, verses, and metadata
-- **🔐 User authentication** - Secure user authentication with Long Access Tokens (LAT)
-- **⚡ Lightweight** - Minimal dependencies with tree-shaking support
-- **🎯 Easy to use** - Simple, intuitive API design
-- **📦 Modern packaging** - CommonJS and ES Module support
+## Overview
 
-## 📦 Installation
+`@youversion/platform-core` provides comprehensive API clients for the YouVersion Bible Platform. Access Bible versions, books, chapters, verses, language information, and Verse of the Day. Built with TypeScript for type safety and works in Node.js and browser environments.
 
-```bash
-# npm
-npm install @youversion/platform-core
+> **📚 Full Documentation:** [developers.youversion.com/sdks/react](https://developers.youversion.com/sdks/react)
 
-# yarn
-yarn add @youversion/platform-core
+## Installation
 
-# pnpm
+```bash
 pnpm add @youversion/platform-core
 ```
 
-## 🔑 Getting Started
+### Prerequisites
 
-Before using the library, you'll need to obtain an App ID from the [YouVersion Developer Portal](https://developers.youversion.com/). This is required for API authentication.
+- Node.js >= 20.0.0
+- YouVersion Platform App Key ([Get from platform.youversion.com](https://platform.youversion.com/))
 
-## 🏃 Quick Start
+## When to Use This Package
 
-```ts
-import { ApiClient, BibleClient } from '@youversion/platform-core'
+Use `@youversion/platform-core` when you need:
+- ✅ Direct access to YouVersion Platform APIs
+- ✅ Server-side/Node.js Bible data fetching
+- ✅ Full control over API calls and data handling
+- ✅ Minimal dependencies (works anywhere JavaScript runs)
 
-// Initialize the API client
-const apiClient = new ApiClient({
-  appId: 'YOUR_APP_ID', // Required: Get your App ID from https://developers.youversion.com/
-})
-
-// Create a Bible client
-const bibleClient = new BibleClient(apiClient)
+**Use other packages instead if:**
+- ❌ Building React components → Use [@youversion/platform-react-hooks](../hooks/README.md) for hooks with state management
+- ❌ Need ready-made UI → Use [@youversion/platform-react-ui](../ui/README.md) for production-ready components
 
-// Fetch Bible versions
-const versions = await bibleClient.getVersions('en*')
+## Related Packages
 
-// Get a specific version
-const version = await bibleClient.getVersion(206) // ESV
+- **[@youversion/platform-react-hooks](../hooks/README.md)** - React hooks wrapping this core SDK
+- **[@youversion/platform-react-ui](../ui/README.md)** - Pre-built React components
 
-// Fetch books for a version
-const books = await bibleClient.getBooks(206)
-
-// Get a specific chapter
-const chapter = await bibleClient.getChapter(206, 'GEN', 1)
-const chapterContent = await bibleClient.getPassage(206, chapter.passage_id)
-```
-
-## 🔧 Configuration
-
-### API Configuration
+## Quick Start
 
 ```ts
-import { ApiClient } from '@youversion/platform-core'
+import { ApiClient, BibleClient } from '@youversion/platform-core'
 
+// Initialize API client
 const apiClient = new ApiClient({
-  appId: 'YOUR_APP_ID', // Required: Get your App ID from https://developers.youversion.com/
-  baseUrl: 'https://api.youversion.com', // Optional: API base URL
-  timeout: 10000, // Optional: Request timeout in ms (default: 10000)
-  version: 'v1', // Optional: API version (default: "v1")
+  appKey: import.meta.env.YVP_APP_KEY,
 })
-```
-
-### Configuration Options
-
-| Option           | Type     | Default                            | Description                                                                               |
-| ---------------- | -------- | ---------------------------------- | ----------------------------------------------------------------------------------------- |
-| `appId`          | `string` | **Required**                       | Your application ID for API authentication. Get one at https://developers.youversion.com/ |
-| `baseUrl`        | `string` | `"https://api-dev.youversion.com"` | Base URL for the API                                                                      |
-| `timeout`        | `number` | `10000`                            | Request timeout in milliseconds                                                           |
-| `version`        | `string` | `"v1"`                             | API version to use                                                                        |
-
-## 📖 API Reference
-
-### BibleClient
-
-The main client for interacting with Bible data.
-
-#### Methods
-
-##### `getVersions(language_ranges: string): Promise<Collection<Version>>`
 
-Fetch available Bible versions filtered by language. The `language_ranges` parameter is required.
-
-```ts
-// Get all English versions
-const englishVersions = await bibleClient.getVersions('en*')
-
-// Get specific language versions
-const spanishVersions = await bibleClient.getVersions('es*')
-
-// Get multiple language versions
-const multiLangVersions = await bibleClient.getVersions('en*,es*,fr*')
-```
-
-##### `getVersion(id: number): Promise<Version>`
-
-Fetch a specific Bible version by ID.
-
-```ts
-const esv = await bibleClient.getVersion(111)
-console.log(esv.title) // "English Standard Version"
-```
-
-##### `getBooks(versionId: number): Promise<Collection<Book>>`
-
-Fetch all books for a specific Bible version.
-
-```ts
-const books = await bibleClient.getBooks(206)
-```
-
-##### `getBook(versionId: number, book: string): Promise<BibleBook>`
-
-Fetch a specific book by its USFM identifier.
-
-```ts
-const genesis = await bibleClient.getBook(111, 'GEN')
-console.log(genesis.title) // "Genesis"
-```
-
-##### `getChapters(versionId: number, book: string): Promise<Collection<BibleChapter>>`
+const bibleClient = new BibleClient(apiClient)
 
-Fetch all chapters for a specific book.
+// Get English Bible versions
+const versions = await bibleClient.getVersions('en*')
+console.log(versions.data[0].title)
 
-```ts
-const chapters = await bibleClient.getChapters(206, 'GEN')
+// Get a specific passage
+const passage = await bibleClient.getPassage(111, 'JHN.3.16')
+console.log(passage.content) // "For God so loved the world..."
 ```
 
-##### `getChapter(versionId: number, book: string, chapter: number): Promise<BibleChapter>`
-
-Fetch a specific chapter.
+## Features
 
-```ts
-const genesis1 = await bibleClient.getChapter(206, 'GEN', 1)
-const content = await bibleClient.getPassage(206, genesis1.passage_id)
-```
+- Retrieve Bible versions, books, chapters, verses, and passages
+- Get formatted passages with optional headings and notes
+- Access the complete Bible index structure
+- Query available languages by country
+- Get Verse of the Day
 
-##### `getVerses(versionId: number, book: string, chapter: number): Promise<Collection<BibleVerse>>`
-
-Fetch all verses for a specific chapter.
+## Configuration
 
 ```ts
-const verses = await bibleClient.getVerses(111, 'GEN', 1)
-verses.data.forEach((verse) => {
-  const passage = await bibleClient.getPassage(206, verse.passage_id)
+const apiClient = new ApiClient({
+  appKey: import.meta.env.YVP_APP_KEY, // Required
+  timeout: 10000, // Optional (default: 10000ms)
 })
 ```
 
-##### `getVerse(versionId: number, book: string, chapter: number, verse: number): Promise<BibleVerse>`
-
-Fetch a specific verse.
-
-```ts
-const verse = await bibleClient.getVerse(111, 'GEN', 1, 1)
-console.log('Verse reference:', verse.reference)
-const passage = await bibleClient.getPassage(111, verse.passage_id)
-console.log('Content:', passage.content) // "In the beginning, God created the heavens and the earth."
-```
-
-### AuthClient
-
-Client for user authentication and user data.
-
-#### Methods
-
-##### `getUser(lat: string): Promise<User>`
-
-Retrieve the current authenticated user using a Long Access Token.
-
-```ts
-import { AuthClient } from '@youversion/platform-core'
-
-const authClient = new AuthClient(apiClient)
-const user = await authClient.getUser('YOUR_LONG_ACCESS_TOKEN')
-```
-
-## 🔍 TypeScript Types
-
-The library provides comprehensive TypeScript types for all API responses:
-
-### Core Types
-
-```ts
-type BibleVersion = {
-  id: number
-  abbreviation: string
-  copyright_long: string
-  copyright_short: string
-  info: string
-  publisher_url: string
-  language_tag: string
-  local_abbreviation: string
-  local_title: string
-  title: string
-  books: Array<string>
-}
-
-interface BibleBook {
-  id: string
-  title: string
-  abbreviation: string
-  canon: string
-  chapters: Array<string>
-}
-
-interface BibleChapter {
-  id: string
-  book_id: string
-  passage_id: string
-  title: string
-  // ... additional fields
-}
-
-interface BibleVerse {
-  id: string
-  book_id: string
-  chapter_id: string
-  passage_id: string
-  reference: string
-  // ... additional fields
-}
-
-interface Collection<T> {
-  data: T[]
-  // ... pagination and metadata
-}
-```
-
-## 🎯 Common Use Cases
-
-### 1. Building a Bible Reading App
-
-```ts
-import { ApiClient, BibleClient } from '@youversion/platform-core'
-
-class BibleApp {
-  private bibleClient: BibleClient
-
-  constructor(appId: string) {
-    const apiClient = new ApiClient({ appId })
-    this.bibleClient = new BibleClient(apiClient)
-  }
-
-  async loadChapter(versionId: number, bookUsfm: string, chapterNum: number) {
-    const chapter = await this.bibleClient.getChapter(versionId, bookUsfm, chapterNum)
-    const verses = await this.bibleClient.getVerses(versionId, bookUsfm, chapterNum)
-
-    return {
-      chapter,
-      verses: verses.data,
-    }
-  }
-
-  async searchVersions(languageCode: string) {
-    const versions = await this.bibleClient.getVersions(`${languageCode}*`)
-    return versions.data
-  }
-}
-```
-
-### 2. Creating a Verse Reference Tool
+## Troubleshooting
 
-```ts
-async function getVerseReference(reference: string, versionId: number) {
-  // Parse reference like "GEN 1:1"
-  const [book, chapterVerse] = reference.split(' ')
-  const [chapter, verse] = chapterVerse.split(':')
-
-  const verseData = await bibleClient.getVerse(versionId, book, parseInt(chapter), parseInt(verse))
-  const passage = await bibleClient.getPassage(versionId, verseData.passage_id)
-
-  return {
-    reference,
-    content: passage.content,
-    version: await bibleClient.getVersion(versionId),
-  }
-}
-```
-
-### 3. Multi-language Bible Comparison
+### "Invalid appKey" Error
 
-```ts
-async function compareVerses(book: string, chapter: number, verse: number, versionIds: number[]) {
-  const comparisons = await Promise.all(
-    versionIds.map(async (versionId) => {
-      const [version, verseData] = await Promise.all([
-        bibleClient.getVersion(versionId),
-        bibleClient.getVerse(versionId, book, chapter, verse),
-      ])
-
-      const passage = await bibleClient.getPassage(versionId, verseData.passage_id)
-      return {
-        version: version.title,
-        language: version.language_tag,
-        content: passage.content,
-      }
-    })
-  )
-
-  return comparisons
-}
-```
+**Solution:** Verify your App Key from [platform.youversion.com](https://platform.youversion.com/). Check for typos or extra whitespace.
 
-## 🚦 Error Handling
+### "Version not found" Error (404)
 
-The library uses standard HTTP status codes and provides meaningful error messages:
+**Solution:** Verify the version ID exists:
 
 ```ts
-import { ApiClient, BibleClient } from '@youversion/platform-core'
-
-try {
-  const bibleClient = new BibleClient(new ApiClient({ appId: 'YOUR_APP_ID' })) // Get App ID from https://developers.youversion.com/
-  const version = await bibleClient.getVersion(999999) // Non-existent version
-} catch (error) {
-  if (error.response?.status === 404) {
-    console.error('Version not found')
-  } else if (error.response?.status === 401) {
-    console.error('Authentication failed - check your App ID')
-  } else {
-    console.error('An error occurred:', error.message)
-  }
-}
-```
-
-## 🔧 Development
-
-### Prerequisites
-
-- Node.js 18+
-- TypeScript 4.8+
-
-### Building
-
-```bash
-# Install dependencies
-npm install
-
-# Build the library
-npm run build
-
-# Run tests (from monorepo root for consistency)
-pnpm test
-
-# Run linting
-npm run lint
+const versions = await bibleClient.getVersions('en*')
+const validIds = versions.data.map(v => v.id)
+console.log('Valid version IDs:', validIds)
 ```
 
-## 📄 License
+## Development
 
-This package is part of the YouVersion Bible SDK and is subject to YouVersion's terms of service.
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development instructions.
 
-## 🤝 Contributing
+## License
 
-This is an internal YouVersion package. For issues or feature requests, please contact the YouVersion development team.
+See [LICENSE](../../LICENSE)
 
-## 📚 Related Packages
+## Support
 
-- `@youversion/platform-react-ui` - React UI components for Bible applications
+- GitHub Issues: [Create an issue](https://github.com/youversion/platform-sdk-react/issues)
+- Platform Docs: [platform.youversion.com](https://platform.youversion.com/)
+- Monorepo: [YouVersion Platform SDK](../../README.md)