YouVersion.UsfmReferences.Unofficial 3.1.1

YouVersion Platform SDK for .NET

An unofficial .NET SDK for the YouVersion Platform REST API — typed HTTP clients, OAuth/PKCE authentication, and Blazor components for browsing Bible versions, reading passages, and managing highlights.

Not affiliated with or endorsed by YouVersion / Life.Church. This is an independent, community implementation built against YouVersion's public Platform API.

See it in action: PlatformTestApp is a full working sample app. It shows both the all-in-one <BibleReader> component and a composite reader built from the individual pickers, so you can see exactly how to assemble your own UI — including the OAuth/PKCE sign-in flow and click-to-highlight components. If you're not using Blazor, PlatformConsoleSample is a minimal console app showing the same API clients called directly from a plain .NET Generic Host.

Packages

See each package's own README (linked above, and published alongside it on NuGet) for installation and usage details.

Which package(s) do I need?

In short: install the highest package in the list that matches what you're building — its NuGet dependencies pull in everything below it automatically. Only reach for Platform.API / Platform.SDK.Services directly if you're deliberately building your own UI layer instead of using Platform.SDK.Components.

Architecture

Platform.API.Models        (POCO/records, zero dependencies)
        ^
        |
Platform.API                (typed HTTP clients, OAuth+PKCE, caching decorators, DI wiring)
        ^
        |
Platform.SDK.Services        (service abstractions + BibleReaderStateService)
        ^
        |
Platform.SDK.Components      (Razor components: pickers, BibleReader, YouVersionAuth)
        ^
        |
PlatformTestApp              (Blazor Server sample host, OAuth endpoints, demo pages)

Dependency direction is enforced automatically, not just by convention: an architecture-fitness test (Platform.API.Tests/Architecture/ApiClientBoundaryTests.cs) fails the build if PlatformTestApp / Platform.SDK.Components reference Platform.API client types directly instead of going through Platform.SDK.Services.

See docs/adr/ for the reasoning behind this and other architectural decisions (caching, rate limiting, package naming/versioning, the auth session abstraction).

PlatformTestApp is a working sample host demonstrating two consumption patterns — the all-in-one <BibleReader> component (/) and manual step-by-step composition (/custom-reader) — plus the full OAuth/PKCE sign-in flow.

Quickstart

dotnet add package YouVersion.Platform.API.Models.Unofficial
dotnet add package YouVersion.Platform.API.Unofficial

builder.Services.AddYouVersionApiClients(options =>
{
    options.AppKey = builder.Configuration["YouVersionApi:AppKey"]!;
});

For the full Blazor UI layer (pickers, reader, highlighting) add YouVersion.Platform.SDK.Components.Unofficial instead — it pulls in Services and API transitively. See Platform.API/README.md for OAuth setup and Platform.SDK.Components/README.md for the component walkthrough.

Versioning & Releases

Package versions are derived automatically from git tags via MinVer (Directory.Build.props) — there is no hand-edited version number to keep in sync across five projects. To cut a release: tag the commit vX.Y.Z (e.g. v1.0.0) and push the tag; publishing to NuGet.org happens via .github/workflows/nuget-publish.yml, triggered by publishing a GitHub Release against that tag. Untagged commits build as 0.0.0-alpha.0.N prereleases automatically — safe to build and test locally or in CI, but not intended to be published.

YouVersion.UsfmReferences.Unofficial carries its own explicit <Version> (not MinVer-derived) since it tracks the upstream Python library's release cadence independently of the Platform.* packages.

Status: tagged releases have been cut (v0.1.0, v0.1.1, v0.1.2) and all five packages are published and consumable from NuGet.org. See CHANGELOG.md for what shipped in each release.

Building & testing

dotnet build
dotnet test

CI (.github/workflows/ci.yml) builds each library in dependency order, packs them to a local NuGet feed, runs the full test suite, and builds PlatformTestApp against the packed output — so the sample app exercises the same NuGet-consumer experience real consumers will get, not just project references.

License

MIT — see LICENSE.