# Prayer Collection

A comprehensive collection of traditional Roman Catholic prayers in multiple languages, organized as structured JSON files with flexible label-based classification.

## Overview

This NPM package provides **57 traditional Catholic prayers** in 8 languages (Latin, English, Spanish, French, German, Italian, Portuguese, Polish) with rich metadata and a flexible multi-label classification system.

**Key Features:**
- 🌍 **Multilingual Support** - 8 languages per prayer
- 🏷️ **Flexible Classification** - Multi-label system with categories and tags
- 🌐 **Universal Compatibility** - Works in Node.js and browsers (React, Vue, etc.)
- 📦 **Zero Runtime Dependencies** - Pure static data imports
- 🔍 **Type-Safe** - Full TypeScript definitions included
- ⚡ **Optimized** - Tree-shakeable, bundler-friendly

## Quick Start

### Installation

```bash
npm install @codexcommunion/prayer-collection
```

### Basic Usage

```javascript
const { getPrayerById, getPrayersByLabel, getPrayerText } = require('@codexcommunion/prayer-collection');

// Get a specific prayer
const ourFather = getPrayerById('our-father');
console.log(ourFather.metadata.title); // "Our Father"

// Get all core prayers
const corePrayers = getPrayersByLabel('core');
console.log(corePrayers.length); // 4

// Get prayer text in a specific language
const prayerText = getPrayerText('hail-mary', 'la');
console.log(prayerText); // "Ave Maria..."
```

### TypeScript

```typescript
import { Prayer, getPrayerById, getPrayerText, LanguageCode } from '@codexcommunion/prayer-collection';

const prayer: Prayer | null = getPrayerById('hail-mary');
const text: string | null = getPrayerText('hail-mary', 'la' as LanguageCode);
```

## Current Collection

**57 prayers available** across 11 theological categories with rich metadata and multilingual translations.

**📋 Complete Prayer List:** [lib/prayer-index.json](lib/prayer-index.json) (generated by `npm run build`)  
**🔮 Planned Additions:** [pending_prayers.md](pending_prayers.md)

## Documentation

### For Users
- **[API Reference](docs/API_REFERENCE.md)** → Points to [index.d.ts](index.d.ts) for complete API
- **[Usage Examples](docs/USAGE_EXAMPLES.md)** → Quick-start code for Node.js, React, Vue
- **[Prayer Organization](docs/PRAYER_ORGANIZATION.md)** → Classification system overview

### For Contributors
- **[Contributing Guide](CONTRIBUTING.md)** → GitHub issue or PR workflow
- **[Data Structure](docs/DATA_STRUCTURE.md)** → JSON prayer format
- **[Architecture](docs/ARCHITECTURE.md)** → Build system and validation

### Reference Files (Self-Documenting)
- **[index.d.ts](index.d.ts)** → TypeScript types and JSDoc for all functions
- **[prayer-schema.json](prayer-schema.json)** → JSON Schema for validation and IDE autocomplete
- **[lib/prayer-index.json](lib/prayer-index.json)** → Auto-generated list of all prayers
- **[scripts/](scripts/)** → Build and validation implementation

## Key Concepts

### Prayer Classification

Prayers use a **multi-label system**:
- **Primary Category**: Main theological focus (e.g., `marian`, `christological`, `saints`)
- **Labels**: Multiple classification tags (e.g., `["core", "rosary", "daily"]`)
- **Importance**: Liturgical significance (`essential`, `common`, `devotional`)

See [Prayer Organization](docs/PRAYER_ORGANIZATION.md) for complete details.

### Language Support

8 languages supported using ISO 639-1 codes:
- `la` (Latin), `en` (English), `es` (Spanish), `fr` (French)
- `de` (German), `it` (Italian), `pt` (Portuguese), `pl` (Polish)

### Browser Compatibility

✅ **Works everywhere** - Node.js, React, Vue, Angular, Svelte, vanilla JavaScript  
✅ **No configuration needed** - Works with all modern bundlers (Webpack, Vite, Rollup, etc.)  
✅ **Static data imports** - No filesystem operations at runtime

## API Quick Reference

```javascript
// Core functions
getAllPrayers()                          // Get all prayers
getPrayerById(id)                        // Get specific prayer
getPrayerText(id, language)              // Get prayer text

// Filtering
getPrimaryCategories()                   // List all categories
getPrayersByPrimaryCategory(category)    // Filter by category
getPrayersByLabel(label)                 // Filter by label
getPrayersByImportance(importance)       // Filter by importance

// Utilities
searchPrayers(term, language)            // Search prayers
getSupportedLanguages()                  // List supported languages
getLabels()                              // List all labels
```

See [API Reference](docs/API_REFERENCE.md) for complete documentation.

## Development

### Build Commands

```bash
npm run build           # Generate static data and validate
npm run validate        # Run comprehensive validation
npm run validate:schema # Run JSON Schema validation (requires: npm install -D ajv)
npm test               # Run API function tests
npm run test:browser   # Test browser compatibility
```

### IDE Support

VS Code users get automatic validation and auto-completion! The workspace is configured to use `prayer-schema.json` for all prayer files.

### Adding New Prayers

1. Create JSON file in `prayers/` directory (filename must match prayer ID)
2. Follow the [data structure](docs/DATA_STRUCTURE.md) or use IDE auto-completion
3. Run `npm run build` and `npm run validate`
4. Commit changes

See [Architecture](docs/ARCHITECTURE.md) for detailed development workflow.

## Publishing

The `prepublishOnly` hook automatically runs validation before publishing:

```bash
npm version patch  # or minor, major
npm publish
```

See [Architecture](docs/ARCHITECTURE.md) for the complete publishing workflow.

## Examples

### React Hook Example

```jsx
import { useState, useEffect } from 'react';
import { getPrayersByLabel, getPrayerText } from '@codexcommunion/prayer-collection';

function DailyPrayers() {
  const [prayers, setPrayers] = useState([]);
  
  useEffect(() => {
    setPrayers(getPrayersByLabel('daily'));
  }, []);
  
  return (
    <div>
      {prayers.map(p => (
        <div key={p.metadata.id}>
          <h3>{p.metadata.title}</h3>
          <p>{getPrayerText(p.metadata.id, 'en')}</p>
        </div>
      ))}
    </div>
  );
}
```

More examples in [Usage Examples](docs/USAGE_EXAMPLES.md).

## License

CodexCommunion Digital Code License (CCCL) v1.0 - see [LICENSE](LICENSE) file for details.

This license permits free use, modification, and distribution for any lawful purpose, with restrictions against use that promotes blasphemy, heresy, or content hostile to the Catholic Church.

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.