YouVersion.UsfmReferences 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.

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.

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
dotnet add package YouVersion.Platform.API

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

For the full Blazor UI layer (pickers, reader, highlighting) add YouVersion.Platform.SDK.Components 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 carries its own explicit <Version> (not MinVer-derived) since it tracks the upstream Python library's release cadence independently of the Platform.* packages.

Status: no tagged release has been cut yet — every package currently builds as a 0.0.0-alpha prerelease. The v1.0.0 tag is the remaining step before these packages are consumable from NuGet.org.

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.