hindu-devotional-texts/src/types.ts

Hand-curated, typed, authoritative Hindu devotional content — aartis, chalisas, kathas, stotras, mantras, ashtottaras & sahasranamas, Vedic suktas, daily prayers, puja vidhi, Navratri, tirthas, the festival/ekadashi calendar, and full scriptures (Bhagavad

export type Deity =
  | 'ganesha'
  | 'shiva'
  | 'vishnu'
  | 'hanuman'
  | 'lakshmi'
  | 'krishna'
  | 'rama'
  | 'durga'
  | 'saraswati'
  | 'parvati'
  | 'kali'
  | 'surya'
  | 'brahma'
  | 'sai-baba'
  | 'santoshi-mata'
  | 'sita'
  | 'khatu-shyam'
  | 'vaishno-devi'
  | 'narasimha'
  | 'other'

export type Category =
  | 'aarti'
  | 'chalisa'
  | 'katha'
  | 'scripture'
  | 'mantra'
  | 'ashtottara'
  | 'sahasranama'
  | 'stotra'
  | 'prayer'
  | 'sukta'

// A string carried in both English and Hindi — the base bilingual unit used
// by the puja/ and navratri/ modules. It is the named form of the inline
// `{ en: string; hi: string }` shape already used by every `about` field in
// this file; existing interfaces keep the inline shape (structurally
// identical) so this addition is purely additive.
export interface Bilingual {
  en: string
  hi: string
}

// Verse used by scriptures. Devanagari is required; IAST, English, and
// Hindi are optional so contributors can add translations where
// appropriate (Bhagavad Geeta especially), without forcing them on
// shorter pieces like Eka Shloki Ramayanam or Nama Ramayanam. `english`
// and `hindi` are prose translations of the verse, not transliterations
// (IAST already carries the Roman-script transliteration).
export interface ScriptureVerse {
  devanagari: string
  iast?: string
  english?: string
  hindi?: string
}

// A single verse/stanza of a recitation. One field now; the object wrapper
// leaves room for `repeat?: number`, alternates, or audio keys later
// without a breaking change.
export interface RecitationVerse {
  text: string
}

// Aartis carry parallel English and Hindi verse arrays — independent
// recitation texts (Devanagari + Roman-script chant), not translations.
// `english[i]` and `hindi[i]` correspond to the same verse, so consumers
// can render them side-by-side by index.
export interface Recitation {
  slug: string
  deity: Deity
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  verses: {
    english: RecitationVerse[]
    hindi: RecitationVerse[]
  }
  about: { en: string; hi: string }
}

// Chalisas have up to four sections: optional `openingDoha` (couplets at
// the start), optional `soratha` (an inverted-meter couplet some chalisas
// place between the opening doha and the chaupai, e.g. Lakshmi Chalisa),
// required `chaupai` (the main 40-ish verses — the word "chalisa" comes
// from चालीस = 40), and optional `closingDoha` (couplets at the end).
// Some chalisas are chaupai-only (e.g. Durga); some have opening +
// closing doha (e.g. Ganesha); some add soratha on top (e.g. Lakshmi).
// Every section uses parallel English/Hindi arrays kept index-aligned.
export interface Chalisa {
  slug: string
  deity: Deity
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  openingDoha?: {
    english: RecitationVerse[]
    hindi: RecitationVerse[]
  }
  soratha?: {
    english: RecitationVerse[]
    hindi: RecitationVerse[]
  }
  chaupai: {
    english: RecitationVerse[]
    hindi: RecitationVerse[]
  }
  closingDoha?: {
    english: RecitationVerse[]
    hindi: RecitationVerse[]
  }
  about: { en: string; hi: string }
}

// A katha paragraph can be prose (English and/or Hindi) or an embedded
// shloka (Sanskrit Devanagari with optional IAST). At least one field
// must be set. Consumers render whichever fields are present — prose
// paragraphs typically use only `english` (and later `hindi`); shlokas
// use `sanskrit` + `iast`.
export interface KathaParagraph {
  english?: string
  hindi?: string
  sanskrit?: string
  iast?: string
}

// One item required for the puja (e.g. "Tulsi leaves", "Saffron").
// `english` is required; `hindi` is optional for items where the Hindi
// name is commonly used alongside (e.g. "Saffron (केसर)").
export interface SamagriItem {
  english: string
  hindi?: string
}

// One chapter (adhyay) of the katha narrative. `sampurna` is the
// closing line that traditionally ends each adhyay, e.g.
// "॥ Iti Shri Satyanarayana Vrat Katha Pratham Adhyay Sampurna ॥".
export interface KathaChapter {
  number: number
  titleEnglish: string
  titleHindi?: string
  paragraphs: KathaParagraph[]
  sampurna: string
}

// A katha is a vrat narrative with four parts: puja samagri (items
// needed), puja vidhi (procedure), the narrative itself broken into
// chapters/adhyays, and an `about` summary. `deity` is optional —
// vrat kathas like Karva Chauth aren't tied to a single deity.
export interface Katha {
  slug: string
  deity?: Deity
  titleEnglish: string
  titleHindi: string
  about: { en: string; hi: string }
  samagri: {
    intro?: KathaParagraph
    items: SamagriItem[]
  }
  vidhi: KathaParagraph[]
  chapters: KathaChapter[]
}

export interface Chapter {
  number: number
  titleEnglish?: string
  titleSanskrit?: string
  titleHindi?: string
  verses: ScriptureVerse[]
  // Traditional closing colophon (e.g. the Geeta's
  // `ॐ तत्सदिति श्रीमद्भगवद्गीतासूपनिषत्सु…अध्यायः`). Canonical formulaic
  // text, not an authored translation; `iast` is round-trip-verified.
  colophon?: {
    devanagari: string
    iast: string
  }
}

export interface Scripture {
  slug: string
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  deity?: Deity
  chapters: Chapter[]
  about: { en: string; hi: string }
}

// A mantra is a short, repeated chant — structurally distinct from
// stanzaed recitations. `deity` is optional because canonical mantras
// like Gayatri and Maha Mrityunjaya aren't tied to a single deity slot.
// IAST is required (not optional like elsewhere) because the chant is
// the surface — sandhi correctness matters more here than in any other
// category. `recommendedCount` is the classical mala size; consumers
// (e.g. dharmagya's Jaap screen) use it as the default repetition.
export interface Mantra {
  slug: string
  deity?: Deity
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  text: {
    devanagari: string
    iast: string
  }
  meaning: { en: string; hi: string }
  recommendedCount?: 108 | 1008
  about: { en: string; hi: string }
}

// One name in a namavali (litany of names) — the archana line a devotee
// offers per flower/akshat ("ॐ विघ्नराजाय नमः"). `number` is 1-indexed and
// dense. `archana` carries the full litany line — the form actually recited;
// the bare nominative ("विघ्नराज") is *not* a separate field: deriving it from
// the dative needs non-trivial Sanskrit-stem reasoning (-इने/-त्रे/-वे/-ये/-मते
// etc. all decline differently), so consumers that need a display label strip
// the "ॐ " prefix and " नमः" suffix at render time. IAST is optional in the
// type but in practice shipped on every name — machine-generated from the
// Devanagari with sanscript and round-trip-verified (Dev→IAST→Dev), the same
// bar the Geeta IAST meets. `meaning` is a short gloss most consumers skip.
// Shared element of the 108-name `Ashtottara` and the 1000-name `Sahasranama`
// (the PLAN's "shared Namavali interface").
export interface NamavaliName {
  number: number
  archana: string
  iast?: string
  meaning?: { en: string; hi: string }
}

// Back-compat alias: the ashtottara module and its consumers import
// `AshtottaraName`; it is structurally identical to `NamavaliName`.
export type AshtottaraName = NamavaliName

// 108-name litany (अष्टोत्तरशतनामावली) for a single deity. Recited at
// step ~12 of Shodashopachara, one name per flower/akshat offering.
// Optional `openingShloka` (the dhyana verse most ashtottaras open with)
// and `closingShloka` (the phala-shruti) are carried separately from
// the 108 names. `reviewPending` flags an ashtottara whose IAST has not
// been generated/verified; it is dropped once every name carries a
// round-trip-verified IAST (the bar the shipped Geeta IAST meets). All
// 17 shipped ashtottaras have passed that bar, so none currently set it.
export interface Ashtottara {
  slug: string
  deity: Deity
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  openingShloka?: {
    devanagari: string
    iast?: string
  }
  names: AshtottaraName[]
  closingShloka?: {
    devanagari: string
    iast?: string
  }
  reviewPending?: boolean
  about: { en: string; hi: string }
}

// A grouped run of verses inside a sahasranama's chantable `stotram`:
//   - `purva`       — पूर्वभाग, the invocation + Bhīṣma–Yudhiṣṭhira framing
//   - `dhyana`      — ध्यानम्, the meditation shlokas (śāntākāraṃ …)
//   - `stotram`     — the name-bearing shlokas (the 1000 names, as metered verse)
//   - `phalashruti` — फलश्रुतिः, the fruit-of-recitation (uttara bhāga)
// Verses reuse `ScriptureVerse`, so the IAST round-trip and the optional
// english/hindi translation slots match the scriptures module exactly. The
// ॥N॥ verse markers are kept inline in `devanagari` (as the Geeta keeps its
// ।।C.V।। markers). The technical nyāsa and the optional appended concluding
// shlokas of the full pāṭha are intentionally not shipped (see SOURCES.md).
export interface SahasranamaSection {
  key: 'purva' | 'dhyana' | 'stotram' | 'phalashruti'
  titleEnglish: string
  titleSanskrit?: string
  titleHindi?: string
  verses: ScriptureVerse[]
}

// 1000-name litany (सहस्रनामावली) for a single deity, shipped with BOTH
// canonical surfaces: the chantable `stotram` (dhyāna + name-bearing shlokas +
// phalaśruti, as metered verses) and the `namavali` (the 1000 individual
// "ॐ <name-dative> नमः" archana lines, offered one per flower/akshat). The two
// are the same recension and correspond name-for-name. Deity-keyed like the
// `Ashtottara`. IAST on both surfaces is machine-generated from the Devanagari
// and round-trip-verified (Dev→IAST→Dev), the bar the Geeta IAST meets.
// `reviewPending` carries until a human Sanskritist signs off on the
// (researched, cross-checked) Devanagari. NOTE: the 1000 count is the
// traditional count and *includes repeated names by design* (commentators read
// different aspects into a repeated name); it is not a count of 1000 distinct
// names.
export interface Sahasranama {
  slug: string
  deity: Deity
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  stotram: SahasranamaSection[]
  namavali: NamavaliName[]
  reviewPending?: boolean
  about: { en: string; hi: string }
}

// The genre of a stotra. `ashtakam` = an eight-verse hymn; `stotra` = a
// general hymn of praise; `stuti` = a shorter laud. Purely a display/grouping
// hint — it does not change the shape.
export type StotraForm = 'stotra' | 'ashtakam' | 'stuti'

// The language of a stotra's verse text. `sanskrit` (the default when unset) —
// the `iast` is a strict, round-trip-verified transliteration. `awadhi` — the
// text is Awadhi/Braj (e.g. the Hanuman stotras of Tulsidas), so `iast` is a
// **best-effort pronunciation romanization, not a strict IAST claim** (the
// retroflex flaps ड़/ढ़ have no IAST form), and is NOT round-trip-asserted —
// the same posture the Sundarkand romanization is held to. Consumers may use
// this to show a "transliteration is approximate" hint.
export type StotraLanguage = 'sanskrit' | 'awadhi'

// A stotra / stuti — a devotional hymn recited as continuous metered verse
// (distinct from a namavali's name-list or a mantra's single repeated chant).
// Verses reuse `ScriptureVerse`: `devanagari` is the verbatim text with the
// ॥N॥ verse marker kept inline (as the Geeta keeps its ।।C.V।। markers) +
// machine-generated, round-trip-verified `iast`; the optional `english` /
// `hindi` carry a per-stanza meaning gloss (researched, draft — never a copied
// translation). `deity?` is optional (a few stotras are multi-deity). Slug-
// keyed (many stotras aren't deity-exclusive and one deity has several), with
// reverse-lookup by deity. `reviewPending` carries until a human pass signs off
// on the meaning glosses (the Devanagari + IAST meet the Geeta bar already).
// `deity` is the primary association (used for the single-slot display and
// `getContentForDeity`); `deities` is the optional FULL association set for the
// handful of stotras a tradition reads as praising more than one deity (e.g.
// the Achyutashtakam, recited to both Vishnu and Krishna). `getStotrasForDeity`
// matches either, so such a stotra surfaces under every deity it names.
export interface Stotra {
  slug: string
  deity?: Deity
  deities?: Deity[]
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  form?: StotraForm
  // Defaults to Sanskrit when unset; `awadhi` flags that `iast` is a best-effort
  // pronunciation romanization (see `StotraLanguage`).
  language?: StotraLanguage
  verses: ScriptureVerse[]
  reviewPending?: boolean
  about: { en: string; hi: string }
}

// A grouped run of mantras inside a sūkta — typically an anuvāka (the
// Śrī Rudram's Namakam/Chamakam each have 11) or a logical section. Simple
// sūktas (e.g. Śrī Sūktam) ship a single section. Verses reuse
// `ScriptureVerse`, so the IAST slot + the optional english/hindi gloss match
// the scriptures and stotras modules. The ॥N॥ verse markers are kept inline in
// `devanagari`.
export interface SuktaSection {
  number: number //          1-indexed section / anuvāka number
  titleEnglish?: string
  titleSanskrit?: string
  titleHindi?: string
  verses: ScriptureVerse[]
}

// A Vedic sūkta — a hymn of mantras (ṛc / yajus) drawn from the Veda and
// recited in worship (Śrī Sūktam, Puruṣa Sūktam, Nārāyaṇa Sūktam, Durgā
// Sūktam, Mantra Puṣpam, the Śrī Rudram's Namakam + Chamakam). Distinct from
// the devotional `Stotra`: the text is Vedic Sanskrit carrying svara (accent)
// marks — udātta/anudātta/svarita (e.g. अ॒ग्निमी॑ळे). Because sanscript cannot
// round-trip the combining accent marks, the per-verse `iast` is a **best-
// effort pronunciation romanization, NOT a strict round-trippable IAST claim**
// — the same posture the Awadhi stotras and the Sundarkand romanization are
// held to (so the audit asserts IAST *presence*, not a Dev→IAST→Dev round-trip,
// for sūktas). `english`/`hindi` on each verse carry a researched per-mantra
// meaning gloss (draft — never a copied translation). `vedicSource` is the
// scriptural locus (Veda + recension, e.g. "Ṛgveda Khila 2.6") — the canonical
// origin of the hymn and part of the content, NOT a digitization/provenance
// source (those live only in SOURCES.md). `deity` is the primary association;
// `deities` is the optional full set for a sūkta a tradition reads as praising
// more than one form. Slug-keyed (like stotras), with reverse-lookup by deity.
// `reviewPending` carries until a human Sanskritist signs off on the (accented)
// Devanagari and the meaning glosses.
export interface Sukta {
  slug: string
  deity?: Deity
  deities?: Deity[]
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  vedicSource: Bilingual
  sections: SuktaSection[]
  reviewPending?: boolean
  about: { en: string; hi: string }
}

// When in the daily cycle a nitya-karma prayer is recited. These are
// functional/temporal slots, not a strict clock — `invocation` and `closing`
// frame any act of worship rather than a time of day.
export type PrayerOccasion =
  | 'morning' //    on waking (kara-darshana)
  | 'bath' //       on touching the earth / before bathing (bhumi-vandana)
  | 'meal' //       before eating (bhojana / anna-grahana)
  | 'evening' //    lamp-lighting at dusk (deepa-darshana)
  | 'night' //      bedtime (kshama-prarthana)
  | 'invocation' // at the start of any undertaking or worship
  | 'closing' //    at the end of worship (samarpana / surrender)

// A short daily prayer (nitya karma) — the everyday shlokas a home altar
// uses around the day's rhythm. Structurally a near-clone of `Mantra`
// (single Devanagari + IAST block, not a stanza array), but distinct in
// intent: a prayer is recited once at its occasion, not counted on a mala,
// so there is no `recommendedCount`, and an `occasion` tags when it is said.
// `deity` is optional — most daily prayers are universal (Karagre invokes
// three deities; Tvameva addresses the divine as all); a few are deity-tied
// (Vakratunda → Ganesha, Karacharana Kritam → Shiva). IAST is required and
// round-trip-verified against the Devanagari, the bar the Geeta IAST meets.
export interface Prayer {
  slug: string
  deity?: Deity
  occasion: PrayerOccasion
  titleEnglish: string
  titleHindi: string
  titleSanskrit?: string
  text: {
    devanagari: string
    iast: string
  }
  meaning: { en: string; hi: string }
  about: { en: string; hi: string }
}