Scripture Inline

import { createScriptureClient } from "@faith-tools/scripture-inline/data"; const scripture = createScriptureClient(); // Default BSB const passage = await scripture.getPassage({ passageId: "JHN.3.16" }); console.log(passage.text, passage.attribution);

HelloAO preserves headings, poetry, and words-of-Jesus formatting in native HTML when supplied by the translation. Its license notice, or the translation name linked to the license, appears below the displayed text. To create a separate provider instance, import createHelloAOProvider from @faith-tools/scripture-inline/providers/helloao.

import { createScriptureClient } from "@faith-tools/scripture-inline/data"; import { createFetchBibleProvider } from "@faith-tools/scripture-inline/providers/fetch-bible"; const scripture = createScriptureClient({ provider: createFetchBibleProvider({ usage: { commercial: false } }), }); // Default eng_bsb const passage = await scripture.getPassage({ passageId: "JHN.3.16" }); console.log(passage.text, passage.attribution);

Set usage.commercial to your application's actual use. The example declares noncommercial use. The derivatives, attributionless, and limitless filters default to false, false, and true. Filters are not legal permission; review each translation's terms. The adapter uses the official collection.

Get a public app key from YouVersion Platform. Replace YOUR_PUBLIC_APP_KEY in this example:

import { createScriptureClient } from "@faith-tools/scripture-inline/data"; import { createYouVersionProvider } from "@faith-tools/scripture-inline/providers/youversion"; const scripture = createScriptureClient({ provider: createYouVersionProvider({ yvpPublicAppKey: "YOUR_PUBLIC_APP_KEY" }), }); // Default 3034 const passage = await scripture.getPassage({ passageId: "JHN.3.16" }); console.log(passage.text, passage.attribution);

YouVersion requirements

YouVersion has no commercial-use flag. Its Platform terms do not grant Bible-content rights. Check the selected publisher's license and applicable Tool terms.

• Paid applications are permitted subject to conditions, including conspicuously stating that the YouVersion Bible App is free. This is neither blanket permission nor a blanket commercial prohibition.
• The terms prohibit using Tools with AI for open-ended user chat except to retrieve and display Scripture verbatim.
• The terms prohibit using Tools to train, develop, refine, or improve AI. Cases beyond expressly permitted uses need prior written YouVersion approval.
• AI-assisted engineering and content generation have separate permissions and conditions in those terms.

These requirements also appear in returned YouVersion instructions.

With a bundler, pass the same provider object to the components and reference finder. This example uses fetch.bible; use a HelloAO or YouVersion provider object in the same way:

import { defineScripturePassage, defineVersionInput, scriptureInline } from "@faith-tools/scripture-inline"; import { createFetchBibleProvider } from "@faith-tools/scripture-inline/providers/fetch-bible"; const provider = createFetchBibleProvider({ usage: { commercial: false } }); defineScripturePassage({ provider }); defineVersionInput({ provider }); scriptureInline({ provider });

For an individual passage or translation picker, assign element.bibleProvider = provider. Remove any provider attribute because it takes precedence. fetch.bible requires a bundler import; it is not a script-tag provider name.

Script tags support HelloAO by default and YouVersion through explicit settings:

<script src="https://cdn.jsdelivr.net/npm/@faith-tools/scripture-inline@0.5.0/dist/scripture-inline.js" data-provider="youversion" data-yvp-public-app-key="YOUR_PUBLIC_APP_KEY" data-bible-version-id="3034" ></script>

A standalone passage can set provider="youversion" and yvp-public-app-key="YOUR_PUBLIC_APP_KEY". With JavaScript, the equivalent options are { provider: "youversion", yvpPublicAppKey: "YOUR_PUBLIC_APP_KEY" }.

All built-in display providers add linked source credits. The fetch.bible adapter sanitizes native HTML, omits notes, loads its required stylesheet, and displays attribution separately.

Implement the exported BibleProvider interface with id, defaultVersionId, and getPassage(versionId, passageId): Promise<PassageDisplay>. Return safe html, version: { id, abbreviation, title }, and an attribution string. Optional fields are safe attributionHtml for links, direction, containerAttributes, and stylesheets. Providers must sanitize both HTML fields before returning them.

Pass the object as provider to defineScripturePassage() or scriptureInline(), or assign it to a passage's bibleProvider property. The provider attribute takes precedence.

To support the translation picker, also implement listVersions(): Promise<BibleVersion[]>. Assign the provider to its bibleProvider property or pass it to defineVersionInput(). Catalogs are scoped to the provider, including the YouVersion public app key and API host. Switching providers does not guess an equivalent translation. For a DOM-free provider, see Effect configuration and custom providers.

License restriction keys remain provider-specific. Review missing or unfamiliar fields:

• HelloAO: attribution is required or not-required. commercialUse and derivatives are allowed or not-allowed. copyleft and publicDomain are booleans.
• fetch.bible: forbid_commercial, forbid_derivatives, forbid_attributionless, forbid_limitless, and forbid_other describe restrictions. true prohibits that use; false means the filter found no such restriction, not legal permission. forbid_derivatives: "same-license" requires share-alike. Multiple licenses are alternative filtered choices, not cumulative grants; select a suitable license.
• YouVersion: No unified license restriction flags are supplied.

To render plain text in a browser:

1. Assign passage.text to textContent. Never insert plain text or attribution as raw HTML.
2. Apply white-space: pre-wrap and the supplied direction and language.
3. Show passage.attribution.text and its links below the passage.

For native HTML, use the same provider object through the component display contract. Do not reconstruct HTML from flattened text. Native fetch.bible HTML requires its container and functional CSS. YouVersion HTML requires its returned container and stylesheets; do not download or self-host its font files.

fetch.bible uses KJV-normalized numbering and the Protestant 66-book canon. Its sourceLimitations identifies these documented trimmed ranges:

• Exodus 35:1–40:38: eng_bstj, eng_bstjb, and grc_lxx.
• Jeremiah 25:14–52:34: those editions plus eng_bst, eng_bstb, and grc_bre.

An overlapping range does not establish why a particular verse is empty. Psalm requests including verse 1 supplement TXT with native HTML's scriptural descriptive title, without editorial headings. No universal offline or persistent caching rights are established.

Async methods reject with the original ScriptureError for expected failures. Import it from /data and use try/catch with error instanceof ScriptureError. Programming defects are not converted to expected errors.

Its code distinguishes invalid_reference, unavailable, unsupported, authentication, rate_limit, network, timeout, and invalid_response. Original diagnostics remain in cause; do not expose them to readers.

Built-in requests retry network and rate-limit failures twice, with exponential delays starting at 100ms and a 15-second deadline for each request's entire retry sequence. Other expected failures do not retry. Override RequestPolicy with Effect.provideService. Legacy Promise-only custom providers have a deadline but no automatic retries.

Client discovery and built-in adapter payload caches each hold at most 256 entries, not a byte limit. Upstream response memoization is disabled; failed or malformed payloads can be downloaded again.

• HelloAO shares validated chapters. fetch.bible shares whole books and retains its collection catalog and loaded localized book-name metadata, whose size depends on the collection.
• Run client.clearCache(), or provide its Layer to scripture.clearCache, to clear that client's discovery and its provider's payload caches. This does not invalidate other clients' discovery or the components' separate display/catalog caches.
• The client does not memoize passage data or YouVersion attribution. Persistent caching is not provided.

Effects support fiber interruption and Effect.runPromise(program, { signal }). The simple async API does not expose an interruption option. HelloAO receives transport cancellation. YouVersion and fetch.bible SDKs do not expose transport cancellation: interruption stops waiting and ignores late results, not their underlying downloads. Components interrupt obsolete loads and use scoped listener/timer cleanup.

Named spans connect SDK, provider, and request operations to your application's Effect tracer. The SDK does not choose a telemetry backend or export to a hosted service. Inject providers through the BibleSource service and Layers for deterministic tests:

import { Effect } from "effect"; import { RequestPolicy, createScriptureClient, scripture } from "@faith-tools/scripture-inline/data/effect"; const client = createScriptureClient(); const program = scripture.getPassage({ passageId: "JHN.3.16" }).pipe( Effect.provide(client.layer), // Replace the Layer in tests Effect.provideService(RequestPolicy, { timeout: "5 seconds", retries: 1 }), Effect.withSpan("application.scripture"), ); const passage = await Effect.runPromise(program);

Custom BibleDataProvider implementations supply Effect-returning discovery and getPassageData methods, id, defaultVersionId, and a clearCache Effect value (Effect.void when unused), without a renderer. Use createScriptureClient({ provider }) or Layer.succeed(BibleSource, provider). Existing custom Promise-based display providers remain compatible; built-ins expose native operations through .effects. Missing data operations report unsupported. createHelloAOProvider() is also available from /providers/helloao. Pure parsing, formatting, and DOM updates remain ordinary synchronous code inside these Effect boundaries.