Bible SDK

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

AO Lab 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 createAOLabProvider from @faith-tools/bible-sdk/providers/ao-lab.

Use aoLabProvider, createAOLabProvider(), and provider: "ao-lab" for new code. The old helloaoProvider, createHelloAOProvider(), /providers/helloao import path, and provider: "helloao" input remain supported as deprecated aliases. Daily-verse selection uses calendarSource: "ao-lab"; calendarSource: "helloao" is also a deprecated alias. Returned provider IDs (including event details and daily calendar provenance) remain helloao, and tracing identifiers and upstream URLs stay unchanged. This additive migration does not change the source or its data.

import { createScriptureClient } from "@faith-tools/bible-sdk/data"; import { createFetchBibleProvider } from "@faith-tools/bible-sdk/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.

Browser components use your server. Create an endpoint on your backend or a compatible serverless function. The component requests passages from that endpoint; only your server sends the private key to API.Bible. See the passage component example.

Install the official SDK alongside Bible SDK on a Node 20+ or Bun server. This adapter uses the node export condition; other server runtimes need Node-compatible package resolution:

pnpm add @faith-tools/bible-sdk @americanbible/api-bible-sdk

Each application supplies its own registered API.Bible account/key and applicable licenses. Bible SDK supplies adapter code, not shared-account access. Keep the key in a server secret, never a browser bundle, VITE_* variable, element attribute, URL, or log. The adapter export rejects browser resolution and construction; that does not replace keeping secrets out of client code.

// Server code only. The same provider works with /data/effect. import { createBibleClient } from "@americanbible/api-bible-sdk"; import { createScriptureClient } from "@faith-tools/bible-sdk/data"; import { createApiBibleProvider } from "@faith-tools/bible-sdk/providers/api-bible"; const apiKey = process.env.API_DOT_BIBLE_API_KEY; if (!apiKey) throw new Error("Set the server's API.Bible key."); const scripture = createScriptureClient({ provider: createApiBibleProvider({ client: createBibleClient({ apiKey, retry: { maxAttempts: 1 } }), defaultVersionId: "bba9f40183526463-01", // BSB; verify access for your app. }), }); const passage = await scripture.getPassage({ passageId: "JHN.3.16-18" }); // Your application renders text/attribution, preserves publisher metadata, // and reports passage.reporting.token on each actual web display.

Set upstream maxAttempts: 1 so Effect owns retries and deadlines. Avoid SDK hooks/custom transports that log credentials or response bodies. Choose defaultVersionId from your account's listVersions() results. No edition is chosen automatically. Chapters exclude intro entries; plain text preserves scriptural superscriptions and poetry line breaks, not style-derived indentation, alignment, italics, or small caps. It omits editorial headings and notes. Numbering remains unknown. Incomplete endpoint coverage fails rather than silently claiming the whole range; upstream passages can be limited to 200 verses.

Application obligations: review the Terms, AUP and account agreements, and each translation's metadata. Returned instructions are guidance, not certification of compliance.

• Display reporting: report reporting.token for each actual web view to FUMS, including cache hits, not fetches/prefetches. The host owns device/session IDs and privacy requirements. No analytics are sent automatically.
• Attribution: show attribution and links below Scripture, identify the translation, and provide the required linked copyright/about page. Preserve publisher.copyrightHtml and publisher.infoHtml; sanitize this untrusted upstream HTML before rendering. Keep the visible API.Bible source link.
• Caching and removal: discovery/publisher caches refresh after 14 days. Refresh downstream copies by cache.expiresAt (epoch milliseconds), never retain metadata/content over 30 days without refresh, and honor shorter removal/revocation deadlines. Some requests require removal within 24 hours; termination provisions can require immediate deletion. A TTL is not offline permission.
• Plan and content restrictions: Starter is noncommercial even for public-domain editions. Each app owner accepts the required account agreements, including the Statement of Orthodoxy, and checks licenses, content integrity, territorial/export restrictions, and economic sanctions. Violations can lead to suspension/revocation, removal duties, audits, fees, and indemnification.
• DRM and AI: the terms require application-level DRM restricting copying/distribution, printing over 100 verses, territory and device counts, without specifying a universally compliant implementation. A private key alone does not satisfy that obligation. Express Licensing guidance restricts copyrighted and Creative Commons Scripture in LLM prompts as well as training. Public-domain runtime prompts are permitted; confirm training, TTS, and exports separately.

API.Bible in the passage component

The same server provider implements getPassageDisplay(versionId, passageId). It requests native HTML once, validates coverage, sanitizes unsafe markup, and preserves USX classes for poetry, scriptural titles, small caps, italics, and tables. The component loads a reviewed, commit-pinned copy of the official Scripture Styles inside its shadow root. This CSS is optional under API.Bible's guidance, not a required design. Customize it with --scripture-*; theme, verse-number, heading, and direction controls still work. Omit red-letter to keep the official muted .wj styling, use red-letter="on" to color marked words of Jesus red, or use red-letter="off" for the text color. These controls require the translation to supply words-of-Jesus markers. Hiding editorial headings leaves scriptural Psalm titles visible.

Keep the provider on your server and expose safe displays through your own endpoint. Pass a browser provider to defineScripturePassage, not the server provider. There is no private-key attribute or built-in provider="api-bible" string option.

// Server route: GET /api/scripture. Use your server's routing convention. import { Effect } from "effect"; import { createBibleClient } from "@americanbible/api-bible-sdk"; import { createApiBibleProvider } from "@faith-tools/bible-sdk/providers/api-bible"; const provider = createApiBibleProvider({ client: createBibleClient({ apiKey: process.env.API_DOT_BIBLE_API_KEY!, retry: { maxAttempts: 1 } }), defaultVersionId: "bba9f40183526463-01", copyrightUrl: "/copyright/bible", // Build this page before serving Scripture. }); const allowedVersions = new Set([provider.defaultVersionId]); // Your licensed editions. export async function GET(request: Request) { const query = new URL(request.url).searchParams; const versionId = query.get("version") ?? provider.defaultVersionId; if (!allowedVersions.has(versionId)) return new Response("Edition unavailable", { status: 400 }); try { const value = query.has("versions") ? (await Effect.runPromise(provider.listVersions())).filter(({ id }) => allowedVersions.has(id)) : await Effect.runPromise(provider.getPassageDisplay(versionId, query.get("passage") ?? ""), { signal: request.signal }); return Response.json(value, { headers: { "Cache-Control": "no-store" } }); } catch { return new Response("Scripture unavailable", { status: 502 }); } } // Browser code. Requests go to your server, never to API.Bible with a private key. import { defineScripturePassage, type BibleProvider } from "@faith-tools/bible-sdk"; async function read(query: URLSearchParams) { const response = await fetch(`/api/scripture?${query}`); if (!response.ok) throw new Error("Scripture unavailable"); return response.json(); } const provider: BibleProvider = { id: "api-bible", defaultVersionId: "bba9f40183526463-01", getPassage: (version, passage) => read(new URLSearchParams({ version, passage })), listVersions: () => read(new URLSearchParams({ versions: "1" })), }; defineScripturePassage({ provider }); // <bible-sdk-passage passage-id="PSA.3.1-2"></bible-sdk-passage>

Add your app's authentication, rate limits, edition/access controls, and privacy-aware FUMS integration. This example does not create a public shared-key proxy. The translation picker can use the same browser provider through defineVersionInput({ provider }).

copyrightUrl is required for display, not plain-text data access. Every quotation page gets a visible link. Populate that page with sanitized publisher.copyrightHtml and publisher.infoHtml, the full translation name/abbreviation, the exact current dashboard/Appendix A citation, and a clickable rights-holder link. Raw metadata alone does not guarantee a complete notice. Applicable direct publisher formatting/citation agreements take precedence; resolve conflicts with API.Bible's remaining minimum requirements before use.

scripture-load.detail.reporting carries the FUMS token after rendering; detail.cache.expiresAt carries the absolute refresh deadline. Connect this to your actual-view reporter, including later cached displays. Rendered does not mean visible: hidden/offscreen components and prerenders need host visibility handling. Layout/theme changes do not fire another load event. No analytics are sent automatically. Cached displays refresh on the next load at the deadline; the host must refresh/remove long-lived mounted displays and honor earlier revocations. Expired server data causes an error instead of stale Scripture.

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

import { createScriptureClient } from "@faith-tools/bible-sdk/data"; import { createYouVersionProvider } from "@faith-tools/bible-sdk/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 an AO Lab or YouVersion provider object in the same way:

import { defineScripturePassage, defineVersionInput, scriptureInline } from "@faith-tools/bible-sdk"; import { createFetchBibleProvider } from "@faith-tools/bible-sdk/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 AO Lab by default and YouVersion through explicit settings:

<script src="https://cdn.jsdelivr.net/npm/@faith-tools/bible-sdk@0.10.0/dist/bible-sdk.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:

• AO Lab: 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.
• API.Bible: No unified license restriction flags are supplied. Review publisher notices and API.Bible account/content terms.

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 can remain in cause; do not expose them to readers. API.Bible discards upstream diagnostics and response-validation causes.

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.

• AO Lab 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.
• API.Bible discovery and publisher metadata expire after 14 days; passage payloads are not memoized. Other built-in cache entries retain their existing lifetime until clearing/eviction. Custom providers can set cacheTimeToLive to an Effect Duration.Input for discovery caches. API.Bible downstream caches must honor cache.expiresAt and any earlier removal request.
• 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. AO Lab and API.Bible receive 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/bible-sdk/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. createAOLabProvider() is also available from /providers/ao-lab. Pure parsing, formatting, and DOM updates remain ordinary synchronous code inside these Effect boundaries.