hindu-devotional-texts/src/puja/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

import type { Deity, Bilingual } from '../types.js'
import type { MantraSlug } from '../mantras/index.js'

// A mantra recited at a puja step, with its provenance flag. `jaapSlug`
// cross-references a preset in the `mantras/` module when the same mantra
// exists there (so a consumer can deep-link a jaap counter); it is `null`
// when the package carries no matching preset. `reviewPending` flagged a
// mantra whose IAST had not been checked; as of the 2026-05-29 pass it is
// dropped on every shipped mantra — the IAST was normalised to the project
// standard (anusvāra `ṃ`) and round-trip-verified against the Devanagari,
// the bar the Geeta IAST meets. The field stays optional so a future mantra
// can re-raise it before its IAST is verified.
export interface PujaMantra {
  jaapSlug: MantraSlug | null
  devanagari: string
  iast: string
  meaning: Bilingual
  reviewPending?: boolean
}

// A short Sanskrit step name shown as the step kicker, with localised gloss.
// `sanskrit` is the Devanagari name; `en` / `hi` are plain-language glosses.
export interface UpacharaName {
  sanskrit: string
  en: string
  hi: string
}

// One of the 16 canonical upacharas of the Shodashopachara sequence. The
// names and their order are stable across the major Agama-tradition sources;
// a puja parameterises the template by overriding the steps where its
// tradition diverges (e.g. Panchamrita snana, modaka naivedya).
export type UpacharaSlug =
  | 'dhyana-avahana' //  1 · meditation + invocation
  | 'asana' //          2 · seat
  | 'padya' //          3 · water for the feet
  | 'arghya' //         4 · water for the hands
  | 'achamana' //       5 · water to sip
  | 'madhuparka' //     6 · honey-curd-ghee
  | 'snana' //          7 · bath (plain water; Panchamrita for an extended puja)
  | 'vastra' //         8 · cloth / vesture
  | 'yajnopavita' //    9 · sacred thread
  | 'gandha' //        10 · sandalwood paste
  | 'pushpa-archana' //11 · flowers + name-archana
  | 'dhupa' //         12 · incense
  | 'deepa' //         13 · lamp
  | 'naivedya' //      14 · food offering
  | 'tambula' //       15 · betel leaf + areca
  | 'neerajanam-aarti' //16 · camphor-lamp aarti

// A single upachara step, parameterised per puja.
export interface Upachara {
  slug: UpacharaSlug
  name: UpacharaName
  // The plain-language instruction — what to actually do at this step.
  line: Bilingual
  // Optional Sanskrit mantra recited at this step.
  mantra?: PujaMantra
  // Optional cross-reference: `label.en` values from this puja's `samagri`
  // list that are used at this step.
  samagriRefs?: string[]
}

// A pre- or post-arc step — purification, sankalpa, kalash sthapana, prana
// pratishtha, havan, visarjana, etc. — that sits outside the 16-step core.
// `slug` is a free string (these steps vary per puja, unlike the fixed 16).
export interface ArcStep {
  slug: string
  name: UpacharaName
  line: Bilingual
  mantra?: PujaMantra
  // A note on when the step applies (e.g. Prana Pratishtha only for a new idol).
  conditional?: Bilingual
}

// A single puja-supply item, optionally grouped and optionally non-essential.
// Named `PujaSamagriItem` (not `SamagriItem`) to avoid colliding with the
// katha-module `SamagriItem` already exported from the package root — that
// type has a different shape (`{ english; hindi? }`).
export interface PujaSamagriItem {
  // The item itself; doubles as the stable key for an interactive checklist.
  label: Bilingual
  // Optional grouping header ("Vessels", "Offerings", "Naivedya", …).
  group?: Bilingual
  // `true` when the item is convenient but the puja is valid without it.
  optional?: boolean
}

// A deep-link surfaced under a puja's "after the puja" section. Tagged by
// `kind` so a consumer renders the matching affordance. `aarti` / `chalisa`
// / `mantra-jaap` resolve against this package; `muhurat` / `festival` /
// `vaar` are descriptors a consumer app maps to its own routes.
export type PostPujaLink =
  | { kind: 'aarti'; deity: Deity; label?: Bilingual }
  | { kind: 'chalisa'; deity: Deity; label?: Bilingual }
  | { kind: 'mantra-jaap'; jaapSlug: MantraSlug | null; customText?: string; label: Bilingual }
  | { kind: 'muhurat'; occasion: 'pradosh' | 'purnima' | 'ekadashi' | 'monday'; label: Bilingual; href?: string }
  | { kind: 'festival'; festivalName: string; label: Bilingual }
  | {
      kind: 'vaar'
      dayKey: 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday'
      label: Bilingual
    }

// A reference to a stotra / katha / aarti read within the puja — typically
// after the 16 upacharas and before the closing aarti.
export interface StotraKathaRef {
  kind: 'aarti' | 'chalisa' | 'katha' | 'stotra-text'
  deity?: Deity
  label: Bilingual
  note: Bilingual
}

// A festival name that, when surfaced on a consumer's festival list, should
// show an "open this puja" affordance. `needle` is a lower-cased substring
// matched (case-insensitively) against the festival name / description.
export interface FestivalMatch {
  needle: string
  note?: Bilingual
}

// A labelled regional / sectarian / practical footnote on a puja.
export interface VariantNote {
  label: Bilingual
  text: Bilingual
}

// A featured puja: when/why it is performed, its samagri checklist, the
// Sankalpa, the pre-arc, the 16-step Shodashopachara core, the post-arc, and
// sourcing + variant notes. Framed as one widely-kept home practice, not any
// single sampradaya's authoritative rite (see `PUJA_DISCLAIMER`).
export interface Puja {
  // URL / registry slug — the `puja/` registry is keyed by this value.
  slug: string
  // Display name ("Satyanarayan Katha Puja" / "सत्यनारायण कथा पूजा").
  name: Bilingual
  // A short "when · who · why" context chip shown above the title.
  kicker: Bilingual
  // When and why this puja is performed — one short paragraph each side.
  whenWhy: Bilingual
  // A roster `Deity` when one of the 19 is the puja's primary deity; omitted
  // when the deity is outside the roster (e.g. the Navagrahas).
  rosterDeity?: Deity
  // Interactive supplies checklist.
  samagri: PujaSamagriItem[]
  // The Sankalpa — the dedication recited at the start; carries `{gotra}` /
  // `{name}` / `{place}` / `{intention}` placeholders the reciter substitutes.
  sankalpa: Bilingual
  // Pre-arc: purification + Sankalpa + optional Kalash + Prana Pratishtha.
  preUpacharas: ArcStep[]
  // The 16-step Shodashopachara core sequence, parameterised for this puja.
  upacharas: Upachara[]
  // Post-arc: optional havan / katha / visarjana / Uttapana + closing.
  postUpacharas: ArcStep[]
  // A stotra / katha / aarti read within the puja.
  stotraKathaRef?: StotraKathaRef
  // Deep links surfaced under "after the puja".
  postPujaLinks: PostPujaLink[]
  // Festival names this puja answers — drives festival-list cross-links.
  festivalMatchers?: FestivalMatch[]
  // Source attribution — what the content was cross-validated against.
  sources: Bilingual
  // Regional / sectarian / practical footnotes.
  variantNotes: VariantNote[]
}