youversion · github-actions · Jul 8, 2026
diff --git a/.changeset/fix-highlights-api-contract.md b/.changeset/fix-highlights-api-contract.md
diff --git a/.changeset/missing-app-key-message.md b/.changeset/missing-app-key-message.md
diff --git a/.changeset/request-highlights-permission.md b/.changeset/request-highlights-permission.md
diff --git a/.changeset/verse-action-popover.md b/.changeset/verse-action-popover.md
diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md
@@ -1,5 +1,26 @@
 # @youversion/platform-core
 
+## 2.3.0
+
+### Minor Changes
+
+- d6ab2d5: Fix `HighlightsClient` to match the live highlights API contract. The client previously sent requests the API rejects on every call (401/400), so highlights could never be fetched, created, or deleted.
+  - Auth token is now sent as an `Authorization: Bearer <token>` header instead of a `lat` query parameter
+  - Query/body fields now use the API's `bible_id` naming on the wire (the SDK keeps `version_id` in its public types and maps at the boundary)
+  - `createHighlight` now sends the required `{ request_id, highlight: { ... } }` envelope (`request_id` is a unique per-request id the API requires)
+  - `getHighlights` now requires `version_id` and `passage_id` (verse or chapter USFM), and `deleteHighlight` requires `version_id`, matching the API's required parameters; `useHighlights` options are updated accordingly
+  - `getHighlights` now treats a `204` (no highlights for the passage) as an empty collection instead of throwing
+  - `createHighlight` normalizes `color` to lowercase before sending, since the API accepts lowercase hex only
+  - Added `getRecentColors()` (`GET /v1/highlights/recent-colors`) to `HighlightsClient` and exposed it from `useHighlights` for building color pickers
+  - API responses are validated with Zod and mapped from the wire shape
+
+- 683c123: Allow requesting YouVersion data-exchange permissions (e.g. `highlights`) at sign-in. These are intentionally not OIDC scopes: they ride alongside the standard `scope` param as repeatable `requested_permissions[]` query params on the authorize URL and are authorized via a separate per-app ACL rather than the token's scope claim.
+  - `YouVersionAPIUsers.signIn(redirectURL, scopes?, permissions?)` and the underlying PKCE authorization request builder now accept a `permissions` array typed as `SignInWithYouVersionPermissionValues[]`.
+  - `useYVAuth().signIn({ permissions })` forwards them from React.
+  - `<YouVersionAuthButton permissions={['highlights']} />` requests them from the sign-in button.
+
+  Scopes and permissions are separate arguments; existing calls that only pass scopes are unaffected.
+
 ## 2.2.0
 
 ### Minor Changes

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-core",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A type-safe TypeScript SDK for accessing the YouVersion Platform APIs. Get Bible content and build Bible-based applications.",
   "license": "Apache-2.0",
   "type": "module",

diff --git a/packages/hooks/CHANGELOG.md b/packages/hooks/CHANGELOG.md
@@ -1,5 +1,33 @@
 # @youversion/platform-react-hooks
 
+## 2.3.0
+
+### Minor Changes
+
+- d6ab2d5: Fix `HighlightsClient` to match the live highlights API contract. The client previously sent requests the API rejects on every call (401/400), so highlights could never be fetched, created, or deleted.
+  - Auth token is now sent as an `Authorization: Bearer <token>` header instead of a `lat` query parameter
+  - Query/body fields now use the API's `bible_id` naming on the wire (the SDK keeps `version_id` in its public types and maps at the boundary)
+  - `createHighlight` now sends the required `{ request_id, highlight: { ... } }` envelope (`request_id` is a unique per-request id the API requires)
+  - `getHighlights` now requires `version_id` and `passage_id` (verse or chapter USFM), and `deleteHighlight` requires `version_id`, matching the API's required parameters; `useHighlights` options are updated accordingly
+  - `getHighlights` now treats a `204` (no highlights for the passage) as an empty collection instead of throwing
+  - `createHighlight` normalizes `color` to lowercase before sending, since the API accepts lowercase hex only
+  - Added `getRecentColors()` (`GET /v1/highlights/recent-colors`) to `HighlightsClient` and exposed it from `useHighlights` for building color pickers
+  - API responses are validated with Zod and mapped from the wire shape
+
+- ab38fb5: Surface a clear error when `YouVersionProvider` is given a missing or empty `appKey` instead of rendering a blank page. The UI provider now renders a styled "Missing app key" message, and the hooks provider throws a descriptive error for hooks-only consumers.
+- 683c123: Allow requesting YouVersion data-exchange permissions (e.g. `highlights`) at sign-in. These are intentionally not OIDC scopes: they ride alongside the standard `scope` param as repeatable `requested_permissions[]` query params on the authorize URL and are authorized via a separate per-app ACL rather than the token's scope claim.
+  - `YouVersionAPIUsers.signIn(redirectURL, scopes?, permissions?)` and the underlying PKCE authorization request builder now accept a `permissions` array typed as `SignInWithYouVersionPermissionValues[]`.
+  - `useYVAuth().signIn({ permissions })` forwards them from React.
+  - `<YouVersionAuthButton permissions={['highlights']} />` requests them from the sign-in button.
+
+  Scopes and permissions are separate arguments; existing calls that only pass scopes are unaffected.
+
+### Patch Changes
+
+- Updated dependencies [d6ab2d5]
+- Updated dependencies [683c123]
+  - @youversion/platform-core@2.3.0
+
 ## 2.2.0
 
 ### Minor Changes

diff --git a/packages/hooks/package.json b/packages/hooks/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-react-hooks",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "React hooks for accessing YouVersion Platform APIs with automatic loading/error states.",
   "license": "Apache-2.0",
   "type": "module",

diff --git a/packages/ui/CHANGELOG.md b/packages/ui/CHANGELOG.md
@@ -1,5 +1,31 @@
 # @youversion/platform-react-ui
 
+## 2.3.0
+
+### Minor Changes
+
+- ab38fb5: Surface a clear error when `YouVersionProvider` is given a missing or empty `appKey` instead of rendering a blank page. The UI provider now renders a styled "Missing app key" message, and the hooks provider throws a descriptive error for hooks-only consumers.
+- 683c123: Allow requesting YouVersion data-exchange permissions (e.g. `highlights`) at sign-in. These are intentionally not OIDC scopes: they ride alongside the standard `scope` param as repeatable `requested_permissions[]` query params on the authorize URL and are authorized via a separate per-app ACL rather than the token's scope claim.
+  - `YouVersionAPIUsers.signIn(redirectURL, scopes?, permissions?)` and the underlying PKCE authorization request builder now accept a `permissions` array typed as `SignInWithYouVersionPermissionValues[]`.
+  - `useYVAuth().signIn({ permissions })` forwards them from React.
+  - `<YouVersionAuthButton permissions={['highlights']} />` requests them from the sign-in button.
+
+  Scopes and permissions are separate arguments; existing calls that only pass scopes are unaffected.
+
+- af37b90: Add a verse action popover to `BibleReader`. Tapping verses selects them (shown with an underline) and opens a popover anchored to the last-selected verse with five highlight colors, Copy, and Share. Highlights apply a translucent fill, persist to `localStorage` per Bible version (shaped like the future highlight API), and can be removed individually. Copy/Share output mirrors bible.com formatting: the verse text in curly quotes, gaps in a non-contiguous selection joined with `...`, followed by the `Book Chapter:verses VERSION` reference. Share uses the Web Share API and falls back to copying where it isn't available.
+
+  `BibleReader` also accepts optional `onCopy` / `onShare` props. When provided, they receive the structured selection payload and suppress the default Web Share / clipboard flow, so React Native / Expo hosts can forward it across the native bridge (mirrors `VerseOfTheDay`'s `onShare`).
+
+  Note: `BibleTextViewProps.highlightedVerses` changed from `Record<number, boolean>` to `Record<number, string>` (verse number → highlight hex). This prop was never wired into shipped usage, so no released consumer is affected; the bump stays `minor`.
+
+### Patch Changes
+
+- Updated dependencies [d6ab2d5]
+- Updated dependencies [ab38fb5]
+- Updated dependencies [683c123]
+  - @youversion/platform-core@2.3.0
+  - @youversion/platform-react-hooks@2.3.0
+
 ## 2.2.0
 
 ### Minor Changes

diff --git a/packages/ui/package.json b/packages/ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-react-ui",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Pre-built React components for Bible applications with styling included.",
   "license": "Apache-2.0",
   "type": "module",