@youversion/platform-core 0.4.1

package/src/languages.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import type { ApiClient } from './client';
+import type { Collection, Language } from './types';
+
+/**
+ * Options for getting languages collection.
+ */
+export type GetLanguagesOptions = {
+  page_size?: number;
+  page_token?: string;
+  country: string; // ISO 3166-1 alpha-2 country code (required per OpenAPI spec)
+};
+
+/**
+ * Client for interacting with Languages API endpoints.
+ */
+export class LanguagesClient {
+  private client: ApiClient;
+
+  private languageIdSchema = z
+    .string()
+    .trim()
+    .min(1, 'Language ID must be a non-empty string')
+    .regex(
+      /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?$/,
+      'Language ID must match BCP 47 format (language or language+script)',
+    );
+  private countrySchema = z
+    .string()
+    .trim()
+    .length(2, 'Country code must be a 2-character ISO 3166-1 alpha-2 code')
+    .toUpperCase();
+
+  /**
+   * Creates a new LanguagesClient instance.
+   * @param client The API client to use for requests.
+   */
+  constructor(client: ApiClient) {
+    this.client = client;
+  }
+
+  private get rootPath(): string {
+    return `/${this.client.config.version}`;
+  }
+
+  /**
+   * Fetches a collection of languages supported in the Platform.
+   * @param options Query parameters for pagination and filtering (country is required).
+   * @returns A collection of Language objects.
+   */
+  async getLanguages(options: GetLanguagesOptions): Promise<Collection<Language>> {
+    const params: Record<string, string | number> = {};
+
+    // Country is required per OpenAPI spec
+    const country = this.countrySchema.parse(options.country);
+    params.country = country;
+
+    if (options.page_size !== undefined) {
+      const pageSizeSchema = z.number().int().positive();
+      pageSizeSchema.parse(options.page_size);
+      params.page_size = options.page_size;
+    }
+
+    if (options.page_token !== undefined) {
+      params.page_token = options.page_token;
+    }
+
+    return this.client.get<Collection<Language>>(`${this.rootPath}/languages`, params);
+  }
+
+  /**
+   * Fetches details about a specific language in the Platform.
+   * @param languageId The BCP 47 language code (optionally including script, e.g., "en" or "sr-Latn").
+   * @returns The requested Language object.
+   */
+  async getLanguage(languageId: string): Promise<Language> {
+    this.languageIdSchema.parse(languageId);
+    return this.client.get<Language>(`${this.rootPath}/languages/${languageId}`);
+  }
+}

package/src/schemas/bible-index.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { BookUsfmSchema, CanonSchema } from './book';
+
+const BibleIndexVerseSchema = z.object({
+  /** Verse identifier */
+  id: z.string(),
+  /** Verse title */
+  title: z.string(),
+});
+
+export type BibleIndexVerse = z.infer<typeof BibleIndexVerseSchema>;
+
+const BibleIndexChapterSchema = z.object({
+  /** Chapter identifier */
+  id: z.string(),
+  /** Chapter title */
+  title: z.string(),
+  /** Array of verses in this chapter */
+  verses: z.array(BibleIndexVerseSchema),
+});
+
+export type BibleIndexChapter = z.infer<typeof BibleIndexChapterSchema>;
+
+const BibleIndexBookSchema = z.object({
+  /** Book identifier */
+  id: BookUsfmSchema,
+  /** Book title */
+  title: z.string(),
+  /** Full book title */
+  full_title: z.string(),
+  /** Book abbreviation */
+  abbreviation: z.string(),
+  /** Canonical section */
+  canon: CanonSchema,
+  /** Array of chapters in this book */
+  chapters: z.array(BibleIndexChapterSchema),
+});
+
+export type BibleIndexBook = z.infer<typeof BibleIndexBookSchema>;
+
+const _BibleIndexSchema = z.object({
+  /** Text direction (e.g., "ltr") */
+  text_direction: z.string(),
+  /** Array of books with chapters and verses */
+  books: z.array(BibleIndexBookSchema),
+});
+
+export type BibleIndex = z.infer<typeof _BibleIndexSchema>;

package/src/schemas/book.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { BOOK_IDS } from '../utils/constants';
+
+export const CanonSchema = z.enum([
+  'ot', // Old Testament
+  'nt', // New Testament
+  'dc', // Deuterocanon (Apocrypha)
+]);
+export type Canon = z.infer<typeof CanonSchema>;
+
+// https://github.com/colinhacks/zod/discussions/4934#discussioncomment-13858053
+export const BookUsfmSchema = z.union([
+  ...BOOK_IDS.map((id) => z.literal(id)),
+  z.string().length(3) as z.ZodType<string & {}>,
+]);
+export type BookUsfm = z.infer<typeof BookUsfmSchema>;
+
+export const BibleBookSchema = z.object({
+  /** Book identifier (e.g., "MAT") */
+  id: BookUsfmSchema,
+  /** Book title (e.g., "Genesis") */
+  title: z.string(),
+  /** Book abbreviation (e.g., "Gen") */
+  abbreviation: z.string().optional(),
+  /** Canonical section (new_testament, old_testament, deuterocanon) */
+  canon: CanonSchema,
+  /** Array of chapter identifiers (e.g., ["GEN.1", "GEN.2", "GEN.3"]) */
+  chapters: z
+    .array(z.string().regex(/^\w{3}\.\d+$/, { message: 'Chapter must be an integer string' }))
+    .optional(),
+});
+
+export type BibleBook = z.infer<typeof BibleBookSchema>;
+export type CANON = z.infer<typeof CanonSchema>;

package/src/schemas/chapter.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { BookUsfmSchema } from './book';
+
+export const BibleChapterSchema = z.object({
+  /** Chapter identifier (e.g., "1") */
+  id: z.string(),
+  /** Book identifier (e.g., "MAT") */
+  book_id: BookUsfmSchema,
+  /** Passage identifier (e.g., "MAT.1") */
+  passage_id: z.string(),
+  /** Chapter title (e.g., "1") */
+  title: z.string(),
+  /** Array of verse identifiers (e.g., ["1", "2", "3"]) */
+  verses: z
+    .array(
+      z
+        .string()
+        .regex(/^\d+$/, { message: 'Verse must be an integer string' })
+        .transform((val) => val as `${number}`),
+    )
+    .optional(),
+});
+
+export type BibleChapter = z.infer<typeof BibleChapterSchema>;

package/src/schemas/collection.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+/**
+ * Generic Collection schema for paginated responses
+ * Used across multiple API endpoints
+ * Based on official YouVersion API schema
+ */
+const _CollectionSchema = <T extends z.ZodTypeAny>(
+  itemSchema: T,
+): z.ZodObject<{
+  data: z.ZodArray<T>;
+  next_page_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  total_size: z.ZodOptional<z.ZodNumber>;
+}> =>
+  z.object({
+    data: z.array(itemSchema),
+    next_page_token: z.string().nullable().optional(), // Real API sometimes returns undefined
+    total_size: z.number().int().optional(), // Used by Languages endpoint
+  });
+
+/**
+ * Generic Collection type for paginated responses
+ */
+export type Collection<T> = {
+  data: T[];
+  next_page_token: string | null;
+  total_size?: number;
+};

package/src/schemas/highlight.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+const _HighlightSchema = z.object({
+  /** Bible version identifier */
+  version_id: z.number().int().positive(),
+  /** Passage identifier (e.g., "MAT.1.1") */
+  passage_id: z.string(),
+  /** Hex color code (6 digits, no #) */
+  color: z.string().regex(/^[0-9a-f]{6}$/),
+});
+
+export type Highlight = z.infer<typeof _HighlightSchema>;
+
+const _CreateHighlightSchema = z.object({
+  /** Bible version identifier */
+  version_id: z.number().int().positive(),
+  /** Passage identifier (e.g., "MAT.1.1") */
+  passage_id: z.string(),
+  /** Hex color code (6 digits, no #) */
+  color: z.string().regex(/^[0-9a-f]{6}$/),
+});
+
+export type CreateHighlight = z.infer<typeof _CreateHighlightSchema>;

package/src/schemas/index.ts

@@ -0,0 +1,11 @@
+export * from './bible-index';
+export * from './book';
+export * from './chapter';
+export * from './collection';
+export * from './highlight';
+export * from './language';
+export * from './passage';
+export * from './version';
+export * from './verse';
+export * from './votd';
+export * from './user';

package/src/schemas/language.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+export const LanguageSchema = z.object({
+  /** BCP 47 language identifier (e.g., "en") */
+  id: z
+    .string()
+    .regex(/^[a-z]{2,3}(?:-[A-Z][a-z]{3})?$/, 'BCP 47 id limited to language or language+script'),
+  /** ISO 639 language code */
+  language: z.string().regex(/^[a-z]{2,3}$/, 'ISO 639 canonical language subtag'),
+  /** ISO 15924 script code (e.g., "Latn") */
+  script: z
+    .string()
+    .regex(/^[A-Z][a-z]{3}$/, 'Script must match ISO 15924 format (e.g., "Latn")')
+    .nullable()
+    .optional(),
+  /** Script name (e.g., "Latin") */
+  script_name: z.string().nullable().optional(),
+  /** Language aliases */
+  aliases: z.array(z.string()).optional(),
+  /** Display names for different locales */
+  display_names: z.record(z.string(), z.string()).optional(),
+  /** Available scripts for this language (e.g., ["Cyrl", "Latn"]) */
+  scripts: z.array(z.string().regex(/^[A-Z][a-z]{3}$/, 'ISO 15924 script code')).optional(),
+  /** Language variants (e.g., ["1996", "fonipa"]) */
+  variants: z.array(z.string()).optional(),
+  /** ISO 3166-1 alpha-2 country codes (e.g., ["RS", "BA", "ME"]) */
+  countries: z.array(z.string().regex(/^[A-Z]{2}$/, 'ISO 3166-1 alpha-2 country code')).optional(),
+  /** Text direction (ltr or rtl) */
+  text_direction: z.enum(['ltr', 'rtl']).optional(),
+  /** Writing population count */
+  writing_population: z.number().int().optional(),
+  /** Speaking population count */
+  speaking_population: z.number().int().optional(),
+  /** Default Bible version ID for this language */
+  default_bible_version_id: z.number().int().nullable().optional(),
+});
+
+export type Language = z.infer<typeof LanguageSchema>;

package/src/schemas/passage.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+export const BiblePassageSchema = z.object({
+  /** Passage identifier (e.g., "MAT.1.1") */
+  id: z.string(),
+  /** Passage content text */
+  content: z.string(),
+  /** Bible version identifier */
+  bible_id: z.number().int().positive(),
+  /** Human-readable reference (e.g., "Matthew 1:1") */
+  human_reference: z.string(),
+});
+
+export type BiblePassage = z.infer<typeof BiblePassageSchema>;

package/src/schemas/user.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+const _UserSchema = z.object({
+  avatar_url: z.string(),
+  first_name: z.string(),
+  id: z.uuid(),
+  last_name: z.string(),
+});
+
+export type User = z.infer<typeof _UserSchema>;

package/src/schemas/verse.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { BookUsfmSchema } from './book';
+
+export const BibleVerseSchema = z.object({
+  /** Verse identifier (e.g., "1") */
+  id: z.string(),
+  /** Book identifier (e.g., "MAT") */
+  book_id: BookUsfmSchema,
+  /** Chapter identifier (e.g., "1") */
+  chapter_id: z.string(),
+  /** Passage identifier (e.g., "MAT.1.1") */
+  passage_id: z.string(),
+  /** Human-readable reference (e.g., "Matthew 1:1") */
+  reference: z.string(),
+});
+
+export type BibleVerse = z.infer<typeof BibleVerseSchema>;

package/src/schemas/version.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { BookUsfmSchema } from './book';
+
+export const BibleVersionSchema = z.object({
+  /** Bible version identifier */
+  id: z.number().int(),
+  /** Bible version abbreviation */
+  abbreviation: z.string(),
+  /** Long copyright text */
+  copyright_long: z.string(),
+  /** Short copyright text */
+  copyright_short: z.string(),
+  /** Bible information text */
+  info: z.string().nullable().optional(),
+  /** Publisher URL */
+  publisher_url: z.url().nullable().optional(),
+  /** Language tag (e.g., "en") */
+  language_tag: z.string(),
+  /** Localized abbreviation */
+  local_abbreviation: z.string(),
+  /** Localized title */
+  local_title: z.string(),
+  /** Full title */
+  title: z.string(),
+  /** Array of book identifiers (e.g., ["GEN", "EXO", "LEV"]) */
+  books: z.array(BookUsfmSchema),
+  /** YouVersion deep link URL */
+  youversion_deep_link: z.url(),
+});
+
+export type BibleVersion = z.infer<typeof BibleVersionSchema>;

package/src/schemas/votd.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+export const VOTDSchema = z.object({
+  /** Day of year (1-366) */
+  day: z.number().int().min(1).max(366),
+  /** Passage identifier (e.g., "JHN.3.16") */
+  passage_id: z.string(),
+});
+
+export type VOTD = z.infer<typeof VOTDSchema>;

package/src/types/api-config.ts

@@ -0,0 +1,9 @@
+export interface ApiConfig {
+  baseUrl?: string;
+  appId: string;
+  timeout?: number;
+  hostEnv?: string;
+  version?: string;
+  installationId?: string;
+  redirectUri?: string;
+}

package/src/types/auth.ts

@@ -0,0 +1,15 @@
+import type {
+  SignInWithYouVersionPermission,
+  SignInWithYouVersionResult,
+} from '../SignInWithYouVersionResult';
+
+export type SignInWithYouVersionPermissionValues =
+  (typeof SignInWithYouVersionPermission)[keyof typeof SignInWithYouVersionPermission];
+
+export interface AuthenticationState {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  accessToken: string | null;
+  result: SignInWithYouVersionResult | null;
+  error: Error | null;
+}

package/src/types/book.ts

@@ -0,0 +1,116 @@
+export type BibleBook = {
+  id: BOOK_ID; // Book identifier (USFM)
+  title: string;
+  abbreviation?: string; // Book name abbreviation if provided by publisher
+  canon: CANON;
+  // eslint-disable-next-line @typescript-eslint/array-type -- Array<> syntax required for template literal type to represent chapter references
+  chapters?: Array<`${BOOK_ID}.${number | `INTRO${number}`}`>; // Ordered list of chapter ids for given Bible and book (e.g., ["GEN.1", "GEN.2", "3JN.INTRO1", "3JN.1"])
+};
+
+export type BOOK_ID =
+  | 'GEN'
+  | 'EXO'
+  | 'LEV'
+  | 'NUM'
+  | 'DEU'
+  | 'JOS'
+  | 'JDG'
+  | 'RUT'
+  | '1SA'
+  | '2SA'
+  | '1KI'
+  | '2KI'
+  | '1CH'
+  | '2CH'
+  | 'EZR'
+  | 'NEH'
+  | 'EST'
+  | 'JOB'
+  | 'PSA'
+  | 'PRO'
+  | 'ECC'
+  | 'SNG'
+  | 'ISA'
+  | 'JER'
+  | 'LAM'
+  | 'EZK'
+  | 'DAN'
+  | 'HOS'
+  | 'JOL'
+  | 'AMO'
+  | 'OBA'
+  | 'JON'
+  | 'MIC'
+  | 'NAM'
+  | 'HAB'
+  | 'ZEP'
+  | 'HAG'
+  | 'ZEC'
+  | 'MAL'
+  | 'MAT'
+  | 'MRK'
+  | 'LUK'
+  | 'JHN'
+  | 'ACT'
+  | 'ROM'
+  | '1CO'
+  | '2CO'
+  | 'GAL'
+  | 'EPH'
+  | 'PHP'
+  | 'COL'
+  | '1TH'
+  | '2TH'
+  | '1TI'
+  | '2TI'
+  | 'TIT'
+  | 'PHM'
+  | 'HEB'
+  | 'JAS'
+  | '1PE'
+  | '2PE'
+  | '1JN'
+  | '2JN'
+  | '3JN'
+  | 'JUD'
+  | 'REV'
+  | 'TOB'
+  | 'JDT'
+  | 'ESG'
+  | 'WIS'
+  | 'SIR'
+  | 'BAR'
+  | 'LJE'
+  | 'S3Y'
+  | 'SUS'
+  | 'BEL'
+  | '1MA'
+  | '2MA'
+  | '3MA'
+  | '4MA'
+  | '1ES'
+  | '2ES'
+  | 'MAN'
+  | 'PS2'
+  | 'ODA'
+  | 'PSS'
+  | '3ES'
+  | 'EZA'
+  | '5EZ'
+  | '6EZ'
+  | 'DAG'
+  | 'PS3'
+  | '2BA'
+  | 'LBA'
+  | 'JUB'
+  | 'ENO'
+  | '1MQ'
+  | '2MQ'
+  | '3MQ'
+  | 'REP'
+  | '4BA'
+  | 'LAO'
+  | 'LKA'
+  | (string & {});
+
+export type CANON = 'old_testament' | 'new_testament' | 'deuterocanon';

package/src/types/chapter.ts

@@ -0,0 +1,5 @@
+export type BibleChapter = {
+  usfm: string;
+  title: string;
+  content?: string;
+};

package/src/types/highlight.ts

@@ -0,0 +1,9 @@
+/**
+ * Legacy type for highlight colors (constants only)
+ * Not an API response, so no schema needed
+ */
+export interface HighlightColor {
+  id: number;
+  color: string;
+  label: string;
+}

package/src/types/index.ts

@@ -0,0 +1,22 @@
+// Re-export all schema-derived types from schemas
+export type { BibleVersion } from '../schemas/version';
+export type { BibleBook, CANON } from '../schemas/book';
+export type { BibleChapter } from '../schemas/chapter';
+export type { BibleVerse } from '../schemas/verse';
+export type { BiblePassage } from '../schemas/passage';
+export type { VOTD } from '../schemas/votd';
+export type {
+  BibleIndex,
+  BibleIndexBook,
+  BibleIndexChapter,
+  BibleIndexVerse,
+} from '../schemas/bible-index';
+export type { Language } from '../schemas/language';
+export type { User } from '../schemas/user';
+export type { Highlight, CreateHighlight } from '../schemas/highlight';
+export type { Collection } from '../schemas/collection';
+
+// Re-export internal/non-API types
+export type { ApiConfig } from './api-config';
+export type { AuthenticationState, SignInWithYouVersionPermissionValues } from './auth';
+export type { HighlightColor } from './highlight';