@faith-tools/bible-sdk 0.0.0-stage → 0.7.0

package/dist/types/providers.d.ts

@@ -0,0 +1,62 @@
+import { Effect } from "effect";
+import { ScriptureError, type BibleDisplayProvider, type BibleVersion } from "./data-types.js";
+export type { BibleVersion } from "./data-types.js";
+/** Provider-owned HTML must be safe to insert into a shadow root. */
+export type PassageDisplay = {
+    html: string;
+    version: BibleVersion;
+    attribution: string;
+    /** Optional safe HTML for linked attribution; plain attribution remains available. */
+    attributionHtml?: string;
+    direction?: "ltr" | "rtl";
+    containerAttributes?: Readonly<Record<string, string>>;
+    stylesheets?: readonly {
+        kind: "bible" | "font";
+        href: string;
+    }[];
+    /** Preserved for existing YouVersion scripture-load consumers. */
+    yvpBibleVersion?: unknown;
+};
+/** Both built-in providers and custom providers use this contract. */
+export interface BibleProvider {
+    readonly id: string;
+    readonly defaultVersionId: string;
+    /** Native Effect operations, supplied by built-ins. Promise-only custom providers remain supported. */
+    readonly effects?: BibleDisplayProvider;
+    getPassage(versionId: string, passageId: string): Promise<PassageDisplay>;
+    /** Optional for passage-only custom providers. Required by the version picker. */
+    listVersions?(): Promise<BibleVersion[]>;
+}
+export type ProviderOptions = {
+    /** Default: helloao. YouVersion must be selected explicitly. */
+    provider?: "helloao" | "youversion" | BibleProvider;
+    /** The selected provider's version ID, such as BSB for HelloAO. */
+    bibleVersionId?: string;
+    yvpPublicAppKey?: string;
+    yvpBibleVersionId?: number;
+    yvpApiHost?: string;
+};
+export declare const providerDefaults: ProviderOptions;
+export declare function createHelloAOProvider(): BibleProvider & {
+    readonly effects: BibleDisplayProvider;
+};
+export declare const helloaoProvider: BibleProvider & {
+    readonly effects: BibleDisplayProvider;
+};
+/** The SDK is loaded only when this provider is used. No YouVersion requests run by default. */
+export declare function createYouVersionProvider({ yvpPublicAppKey, yvpApiHost }: Pick<ProviderOptions, "yvpPublicAppKey" | "yvpApiHost">): BibleProvider & {
+    readonly effects: BibleDisplayProvider;
+};
+export declare function resolveProvider(options: ProviderOptions): BibleProvider;
+export declare const resolveProviderEffect: (options: ProviderOptions) => Effect.Effect<BibleProvider, ScriptureError, never>;
+export declare const listBibleVersionsEffect: (options?: ProviderOptions | undefined) => Effect.Effect<{
+    readonly id: string;
+    readonly abbreviation: string;
+    readonly title: string;
+    readonly language?: string | undefined;
+    readonly languageName?: string | undefined;
+}[], ScriptureError, never>;
+/** Lists versions available from the configured provider, never a cross-provider guess. */
+export declare function listBibleVersions(options?: ProviderOptions): Promise<BibleVersion[]>;
+export declare const fetchDisplayEffect: (provider: BibleProvider, versionId: string, passageId: string) => Effect.Effect<PassageDisplay, ScriptureError, never>;
+export declare function fetchDisplay(provider: BibleProvider, versionId: string, passageId: string): Promise<PassageDisplay>;

package/dist/types/runtime.d.ts

@@ -0,0 +1,18 @@
+import { Context, Duration, Effect, Schema } from "effect";
+import { ScriptureError, type BibleDisplayProvider } from "./data-types.js";
+import type { BibleProvider } from "./providers.js";
+export declare const decodeResponse: <S extends Schema.Constraint & {
+    DecodingServices: never;
+}>(schema: S) => (value: unknown) => Effect.Effect<S["Type"], ScriptureError, S["DecodingServices"]>;
+/** Override per program, including in tests. The timeout bounds the entire retry sequence. */
+export declare const RequestPolicy: Context.Reference<{
+    timeout: Duration.Input;
+    retries: number;
+}>;
+export declare function requestError(cause: unknown): ScriptureError;
+/** The only Promise boundary for upstream SDKs. Pass the signal when the SDK supports it. */
+export declare const request: <A>(operation: string, load: (signal: AbortSignal) => PromiseLike<A>, retry?: boolean | undefined) => Effect.Effect<A, ScriptureError, never>;
+/** Promise methods are compatibility edges, not the implementation of built-in providers. */
+export declare function withPromises(effects: BibleDisplayProvider): BibleProvider & {
+    readonly effects: BibleDisplayProvider;
+};

package/dist/types/scan.d.ts

@@ -0,0 +1,8 @@
+export declare const REF_CLASS = "scripture-inline-ref";
+/**
+ * Wraps every Bible reference under `root` in an `<a>` to its route.bible
+ * page. Returns the links it created. Safe to run more than once.
+ */
+export declare function wrapReferences(root: Node): HTMLAnchorElement[];
+/** Turns links from wrapReferences back into the plain text they replaced. */
+export declare function unwrapReferences(links: HTMLAnchorElement[]): void;

package/dist/types/scripture-passage.d.ts

@@ -0,0 +1,61 @@
+import { type BibleProvider, type ProviderOptions } from "./providers";
+export declare const SCRIPTURE_PASSAGE_TAG = "si-passage";
+export declare const BIBLE_PASSAGE_TAG = "bible-sk-passage";
+export declare const BIBLE_TOKENS: Record<string, string>;
+export type ReferenceLayout = "heading" | "citation" | "quote" | "none";
+/**
+ * Displays Scripture with its required attribution. Works in the page or inside a shadow root.
+ *
+ * Attributes choose what shows: `reference`, `verse-numbers="hide"`, `red-letter="off"`,
+ * `headings="hide"`, `direction`, and `theme`. CSS properties choose how it looks:
+ * `--scripture-font-size`, `--scripture-line-height`, `--scripture-font-family`, `--scripture-max-width`.
+ * Parts: `text`, `citation`, `version`, `attribution`, `quote`, `loader`, `error`.
+ */
+export declare class ScripturePassage extends HTMLElement {
+    static observedAttributes: string[];
+    private providerOverride?;
+    /** A custom provider for this passage. The provider attribute takes precedence. */
+    get bibleProvider(): BibleProvider | undefined;
+    set bibleProvider(provider: BibleProvider | undefined);
+    private generation;
+    /** The loaded passage, kept so a layout change re-renders without a request. */
+    private loaded;
+    private scheduled;
+    private cancelLoad?;
+    private cancelTheme?;
+    private cancelAnimation?;
+    private readonly systemDark;
+    private readonly onSystemTheme;
+    /** Holds everything the element shows, inside its shadow root. */
+    private readonly root;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private scheduleLoad;
+    private applyTheme;
+    /** "heading" (default), "citation", "quote", or "none". */
+    get referenceLayout(): ReferenceLayout;
+    /** Swaps the reference layout in place. Only the label moves, so there is no loader or grow. */
+    private relayout;
+    /** Builds the passage, its reference and version in the chosen layout, and its attribution. */
+    private compose;
+    private showLoading;
+    private showError;
+    private readonly load;
+    /** Resolves once every Bible stylesheet has loaded (or failed, so text still shows). */
+    private installStylesheets;
+    /**
+     * Grows from the loader's height to the passage's height after removing the loader.
+     * The text fades in with a light blur.
+     */
+    private growFrom;
+}
+/** Registers <bible-sk-passage> and its <si-passage> compatibility name. */
+export declare function defineScripturePassage(options?: ProviderOptions): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        "si-passage": ScripturePassage;
+        "bible-sk-passage": ScripturePassage;
+    }
+}

package/dist/types/version-input.d.ts

@@ -0,0 +1,64 @@
+import { type BibleProvider, type BibleVersion, type ProviderOptions } from "./providers";
+export declare const VERSION_INPUT_TAG = "si-version-input";
+export declare const BIBLE_VERSION_INPUT_TAG = "bible-sk-version-input";
+export type VersionInputDetail = {
+    provider: string;
+    bibleVersionId: string;
+    bibleVersion: BibleVersion | null;
+};
+/** A form-associated translation picker. Search names/abbreviations, not provider IDs. */
+export declare class ScriptureVersionInput extends HTMLElement {
+    static formAssociated: boolean;
+    static observedAttributes: string[];
+    private readonly internals;
+    private readonly input;
+    private readonly language;
+    private readonly list;
+    private readonly status;
+    private readonly retry;
+    private versions;
+    private filtered;
+    private selected?;
+    private pendingValue?;
+    private provider?;
+    private override?;
+    private active;
+    private generation;
+    private scheduled;
+    private cancelLoad?;
+    private loading;
+    private failed;
+    private formDisabled;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    get value(): string;
+    set value(value: string);
+    get bibleProvider(): BibleProvider | undefined;
+    set bibleProvider(provider: BibleProvider | undefined);
+    get form(): HTMLFormElement | null;
+    get validity(): ValidityState;
+    get validationMessage(): string;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    focus(options?: FocusOptions): void;
+    formResetCallback(): void;
+    formDisabledCallback(disabled: boolean): void;
+    private defaultValue;
+    private updateDisabled;
+    private close;
+    private highlight;
+    private suggest;
+    private commit;
+    private scheduleLoad;
+    private readonly load;
+}
+/** Registers <bible-sk-version-input> and <si-version-input>, sharing provider defaults. */
+export declare function defineVersionInput(options?: ProviderOptions): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        "si-version-input": ScriptureVersionInput;
+        "bible-sk-version-input": ScriptureVersionInput;
+    }
+}

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@faith-tools/bible-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0",
+  "description": "Unified Bible data SDK with async and Effect APIs, plus drop-in Scripture web components.",
+  "license": "MIT",
+  "author": "Cameron Pak (https://cameronpak.com)",
+  "homepage": "https://bible-sdk.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cameronapak/bible-sdk.git"
+  },
+  "bugs": "https://github.com/cameronapak/bible-sdk/issues",
+  "keywords": [
+    "bible",
+    "scripture",
+    "web-components",
+    "youversion",
+    "bible-references"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./data": {
+      "types": "./dist/types/data.d.ts",
+      "default": "./dist/data.js"
+    },
+    "./data/effect": {
+      "types": "./dist/types/data-effect.d.ts",
+      "default": "./dist/data/effect.js"
+    },
+    "./providers/helloao": {
+      "types": "./dist/types/providers/helloao.d.ts",
+      "default": "./dist/providers/helloao.js"
+    },
+    "./providers/youversion": {
+      "types": "./dist/types/providers/youversion.d.ts",
+      "default": "./dist/providers/youversion.js"
+    },
+    "./providers/fetch-bible": {
+      "types": "./dist/types/providers/fetch-bible.d.ts",
+      "default": "./dist/providers/fetch-bible.js"
+    },
+    "./providers/api-bible": {
+      "types": "./dist/types/providers/api-bible.d.ts",
+      "browser": null,
+      "node": "./dist/providers/api-bible.js"
+    },
+    "./embed": "./dist/bible-sdk.js"
+  },
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@gracious.tech/fetch-client": "2.6.0",
+    "@youversion/platform-core": "^2.16.0",
+    "effect": "^4.1.2",
+    "free-use-bible-api": "^1.16.0",
+    "grab-bcv": "^0.1.8",
+    "sanitize-html": "^2.18.1"
+  },
+  "devDependencies": {
+    "@americanbible/api-bible-sdk": "2.0.2",
+    "@changesets/cli": "3.0.3",
+    "@effect/vitest": "4.1.2",
+    "@faith-tools/sensible-ui": "1.8.2",
+    "@types/sanitize-html": "^2.16.2",
+    "jsdom": "^30.1.3",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && vite build --mode lib && tsc -p tsconfig.build.json",
+    "build:site": "vite build --mode site",
+    "typecheck": "tsc --noEmit",
+    "check:data-types": "tsc --ignoreConfig --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 --lib ES2022,DOM scripts/check-data-types.ts",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm test && pnpm build && pnpm check:data-types && pnpm build:site",
+    "changeset": "changeset",
+    "version-packages": "changeset version && node scripts/sync-cdn-version.ts"
+  }
 }