feat(core): add searchUnified for GET /v1/search-unified by camrun91 · Pull Request #446 · youversion/platform-sdk-react

camrun91 · 2026-10-14T21:31:35Z

Summary

Add the live unified-search endpoint to core and React hooks so apps can load top verse references and related topics in one unpaginated request. Existing search methods and the Bible reader flow stay unchanged.

Scope

Export searchUnified, SearchClient.searchUnified, useUnifiedSearch, and their public types.
Validate request intents, nonempty verse/topic selections, and required response fields. Preserve unknown response intent strings.
Include contract tests, usage examples, release changesets, and the measured hooks-barrel size allowance.
Defer all Images support and its smoke page to a preserved private follow-up branch.

Verification

Forced build, typecheck, lint, 1,042 tests, size, tree-shaking, formatting, and changeset checks pass locally. Two opt-in live tests skipped; contract checks use mocks.
Hooks full barrel: 26.94 kB, below the 29.8 kB limit.

Hold merge until Cam authorizes it. YPE-6188 / YPE-6182.

Confidence Score: 5/5

The code appears safe to merge once Cam authorizes it.

Summary

Adds searchUnified and useUnifiedSearch for one unpaginated request returning verse references and related topics.

The core SDK returns verse references and related topics in one search snapshot.
React apps load unified search results with a new hook.

Diagram

sequenceDiagram
  participant App
  participant Hook as useUnifiedSearch
  participant Core as searchUnified
  participant API as Platform API
  App->>Hook: Query, version, languages, options
  Hook->>Core: Load snapshot
  Core->>Core: Check inputs
  Core->>API: GET /v1/search-unified
  API-->>Core: Verse references and topics
  Core->>Core: Check response and map fields
  Core-->>Hook: SearchUnifiedResponse
  Hook-->>App: data, loading, error, refetch

_{Reviews (9) · Last reviewed commit: "Merge branch 'main' into caml/ype-6188-s..." · Reviewed by Greptile}

Callers can request verses, topics, and images together. Image hits are id and passageId. Verse and topic hits stay the existing types.

changeset-bot · 2026-10-14T21:31:44Z

🦋 Changeset detected

Latest commit: 99e5d80

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-core	Minor
@youversion/platform-react-hooks	Minor
@youversion/platform-react-ui	Minor
vite-react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Keep the UI barrel aligned with new core runtime exports so check-public-exports passes.

Measured brotlied barrel is 21.55 kB. Set the limit to measured size plus ~10% headroom per CONTRIBUTING.

Default omitted verses/topics/images wire keys to empty arrays, drop invalid image hits per item (structural USFM on passage_id), and replace the runtime field-coverage object with a type-only check.

@ts-expect-error

Use the repo @ts-expect-error pattern for an invalid fields[] value instead of a typed assertion plus SAFETY comment.

Use false instead of never in the false branch so Record<..., true> rejects non-array field mappings.

Dustin-Kelley

🔥

Wire a vite-react page that calls SearchClient.searchUnified for images alone or with verses, and renders thin hits plus empty/error states.

Results was reading the live Fields control, so flipping mode after an images-only search showed a false empty verses section. Co-authored-by: cameron.b.llewellyn <cameron.b.llewellyn@gmail.com>

Build on PR446 core search with an additive React hook, image-aware coverage, and documented backend availability. Validate request intents and required response fields without requiring images on the wire. Amp-Thread-ID: https://ampcode.com/threads/T-01a15a0f-f2cd-72cf-a270-2102b3d073b2

Set the hooks full-barrel budget to measured 27.044 kB plus approximately 10% headroom, following CONTRIBUTING. Leave all narrow-import budgets unchanged. Amp-Thread-ID: https://ampcode.com/threads/T-01a15a0f-f2cd-72cf-a270-2102b3d073b2

Preserve verse/topic unified search, useUnifiedSearch, and contract validation while deferring Images types, mapping, tests, and smoke page. Amp-Thread-ID: https://ampcode.com/threads/T-01a15a0f-f2cd-72cf-a270-2102b3d073b2

cameronapak · 2026-10-20T18:22:38Z

@camrun91

request: Could you review the unified-search-only scope on this PR? The Images work has been separated because that API is still beta. All exact-head checks are green.

camrun91 · 2026-10-20T22:29:37Z

@camrun91

request: Could you review the unified-search-only scope on this PR? The Images work has been separated because that API is still beta. All exact-head checks are green.

Looks like you made the changes in this PR right?

cameronapak · 2026-10-21T00:13:47Z

@camrun91
request: Could you review the unified-search-only scope on this PR? The Images work has been separated because that API is still beta. All exact-head checks are green.

Looks like you made the changes in this PR right?

Yep to use your existing PR and not re-create it

camrun91 · 2026-10-21T12:57:38Z

@camrun91
request: Could you review the unified-search-only scope on this PR? The Images work has been separated because that API is still beta. All exact-head checks are green.

Looks like you made the changes in this PR right?

Yep to use your existing PR and not re-create it

Cool wanted to make sure before I had the bots review it.

camrun91

requesting changes. nothing here is a big rewrite, but each item is a rule in this repo or a common practice for public sdk code. details are inline. the main risk is #1: a filtered search can fail if the api leaves out a key.

camrun91 · 2026-10-21T14:26:50Z

+export type SearchUnifiedOptions = z.infer<typeof SearchUnifiedOptionsSchema>;
+
+export const SearchUnifiedWireSchema = z.object({
+  verses: z.array(SearchVerseHitWireSchema),


verses and topics are required again. Commit dc951f8 undid the fix for Dustin's blocking comment. If the API leaves out a kind you did not request, fields: ['topics'] throws. user_intent and search_instead_for (lines 289 and 291) have the same problem. The other search schemas make them optional. Make these keys optional, and default them to [] or null. If the API always sends every key, add a live smoke test that proves it, and reply on Dustin's thread.

camrun91 · 2026-10-21T14:26:50Z

+
+export const SearchUnifiedWireSchema = z.object({
+  verses: z.array(SearchVerseHitWireSchema),
+  topics: z.array(z.extend(SearchTopicWireSchema, { id: z.nullable(z.int()) })),


One bad verse hit or topic makes the whole response fail. The JSDoc says the code removes bad references, but a null reference throws. Parse each hit by itself and drop the hits that fail. #454 needs this for images too.

camrun91 · 2026-10-21T14:26:50Z

+
+export type SearchUnifiedWire = z.infer<typeof SearchUnifiedWireSchema>;
+
+export const SearchUnifiedResponseSchema = z.object({


#454 adds a required images field to this type. After this PR ships, that change will break the types for consumers, because they build this type in HookOverrides and in mocks. Decide now: add images as an optional field, and write that in the JSDoc.

camrun91 · 2026-10-21T14:26:50Z

+  error: 'Search field must be verses or topics',
+});
+
+const SearchUnifiedFieldsSchema = z.pipe(


fields and languageRanges do not accept readonly arrays. fields: ['topics'] as const does not compile. Use readonly SearchUnifiedField[] and string | readonly string[], as useBibleSearch does. Please do the same in the hook props.

camrun91 · 2026-10-21T14:26:51Z

+import { useSearchClient } from './useSearchClient';
+import type { UseQueryResult } from './useQueryResult';
+
+export type UseUnifiedSearchProps = Readonly<


These props have no JSDoc. Add JSDoc for each prop. Include the 1 to 100 character limit, the versionId to bible_id mapping, and how the code normalizes language ranges. Also say that fields must not be empty. review-guidelines.md requires this for public props.

camrun91 · 2026-10-21T14:26:51Z

+  'fields[]'?: SearchUnifiedField[];
+};
+
+export async function searchUnified(


This exported function has no JSDoc. Add JSDoc, as SearchClient.searchUnified has.

camrun91 · 2026-10-21T14:26:51Z

+    [...keyBase, 'searchUnified', query, versionId, languageRanges, userIntent, fields],
+    () => client.searchUnified(query, versionId, languageRanges, { userIntent, fields }),
+    {
+      enabled: !override && apiOptions?.enabled !== false,


The hook sends a request when the query is empty, and it returns a validation error. useBibleSearch turns itself off for an invalid query. Do the same here: enable the query only when the trimmed query and the language ranges are valid. Then remove the enabled workaround from the README.

camrun91 · 2026-10-21T14:26:51Z

  parseUsfmReference,
  removeStorageItem,
  searchTopics,
+  searchUnified,


This line adds a public export, but no changeset lists @youversion/platform-react-ui. The UI changelog will not show it. Add a minor changeset for the UI package. CONTRIBUTING requires changesets for new features.

camrun91 · 2026-10-21T14:26:51Z

+    { versionId: 2 },
+    { languageRanges: ['es'] },
+    { fields: ['topics'] },
+    { userIntent: 'topical' },


This test checks only the final data after an input changes. ADR 0006 says the hook keeps the previous data and shows loading: true while the new query loads. docs/testing.md says tests must check this middle state. Make the stub wait until the test releases it. Check the previous data with loading: true, then release the stub.

cursoragent added 3 commits October 14, 2026 21:22

feat(core): add searchUnified for GET /v1/search-unified

746db68

Callers can request verses, topics, and images together. Image hits are id and passageId. Verse and topic hits stay the existing types.

test(core): cover searchUnified fields, mapping, and rejection

afd7074

chore(core): drop redundant searchUnified schema comments

1ac949f

cursoragent added 2 commits October 14, 2026 22:41

fix(ui): re-export searchUnified from package root

a0dff0a

Keep the UI barrel aligned with new core runtime exports so check-public-exports passes.

chore: raise core full-barrel size budget for searchUnified

d183dcb

Measured brotlied barrel is 21.55 kB. Set the limit to measured size plus ~10% headroom per CONTRIBUTING.

camrun91 marked this pull request as ready for review October 15, 2026 16:57

Merge branch 'main' into caml/ype-6188-search-unified-1037

9c2c641

camrun91 requested review from Dustin-Kelley, abharms and bmanquen October 15, 2026 16:58

Dustin-Kelley reviewed Oct 16, 2026

View reviewed changes

Comment thread packages/core/src/schemas/search.ts

Comment thread packages/core/src/schemas/search.ts Outdated

Comment thread packages/core/src/schemas/search.ts Outdated

Comment thread packages/core/src/schemas/search.ts Outdated

Comment thread packages/core/src/schemas/search.ts Outdated

cursoragent added 2 commits October 16, 2026 19:08

fix(core): harden searchUnified optional sections and image hits

56f4ed8

Default omitted verses/topics/images wire keys to empty arrays, drop invalid image hits per item (structural USFM on passage_id), and replace the runtime field-coverage object with a type-only check.

test(core): drop SAFETY cast in searchUnified fields rejection

b43364b

Use the repo @ts-expect-error pattern for an invalid fields[] value instead of a typed assertion plus SAFETY comment.

Dustin-Kelley reviewed Oct 16, 2026

View reviewed changes

Comment thread packages/core/src/schemas/search.ts Outdated

fix(core): make SearchUnified field coverage assert fail on mismatch

dda3064

Use false instead of never in the false branch so Record<..., true> rejects non-array field mappings.

Dustin-Kelley previously approved these changes Oct 16, 2026

View reviewed changes

feat(example): add searchUnified smoke page

81048e4

Wire a vite-react page that calls SearchClient.searchUnified for images alone or with verses, and renders thin hits plus empty/error states.

cursor Bot dismissed Dustin-Kelley’s stale review via 81048e4 October 19, 2026 12:25

greptile-apps Bot reviewed Oct 19, 2026

View reviewed changes

Comment thread examples/vite-react/src/pages/SearchUnifiedPage.tsx Outdated

fix(example): pin searchUnified results to submitted fields

45548f7

Results was reading the live Fields control, so flipping mode after an images-only search showed a false empty verses section. Co-authored-by: cameron.b.llewellyn <cameron.b.llewellyn@gmail.com>

Dustin-Kelley mentioned this pull request Oct 19, 2026

feat(core): add useSearch().unified youversion/platform-sdk-reactnative-expo#245

Draft

ampagent added 3 commits October 20, 2026 17:23

feat(search): ship unified search without Images beta scope

70a7489

Preserve verse/topic unified search, useUnifiedSearch, and contract validation while deferring Images types, mapping, tests, and smoke page. Amp-Thread-ID: https://ampcode.com/threads/T-01a15a0f-f2cd-72cf-a270-2102b3d073b2

cameronapak mentioned this pull request Oct 20, 2026

feat(search): add beta Images hits to unified search #454

Draft

4 tasks

Merge branch 'main' into caml/ype-6188-search-unified-1037

99e5d80

camrun91 commented Oct 21, 2026

View reviewed changes


		export type SearchUnifiedWire = z.infer<typeof SearchUnifiedWireSchema>;

		export const SearchUnifiedResponseSchema = z.object({

Conversation

camrun91 commented Oct 14, 2026 • edited by greptile-apps Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Scope

Verification

Confidence Score: 5/5

Summary

Diagram

Uh oh!

changeset-bot Bot commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Dustin-Kelley left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cameronapak commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

camrun91 commented Oct 20, 2026

Uh oh!

cameronapak commented Oct 21, 2026

Uh oh!

camrun91 commented Oct 21, 2026

Uh oh!

camrun91 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

camrun91 commented Oct 14, 2026 •

edited by greptile-apps Bot

Loading

changeset-bot Bot commented Oct 14, 2026 •

edited

Loading

cameronapak commented Oct 20, 2026 •

edited

Loading