aa-daily-reflections
Version:
A lightweight Node.js library to fetch Daily Reflections from Alcoholics Anonymous (AA)
292 lines (206 loc) • 8.9 kB
Markdown
A lightweight, efficient Node.js library to fetch Daily Reflections from Alcoholics Anonymous (AA). This library provides both programmatic access through a JavaScript API and command-line interface.
[](https://badge.fury.io/js/aa-daily-reflections)
[](https://www.npmjs.com/package/aa-daily-reflections)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://github.com/paladini/aa-daily-reflections-api)
[](https://bundlephobia.com/package/aa-daily-reflections)
[](https://github.com/paladini/aa-daily-reflections-api/graphs/commit-activity)
[](https://github.com/paladini/aa-daily-reflections-api/pulls)
## ⚠️ Important Notice
This library fetches content from the public [AA.org](https://aa.org) API. Please use it responsibly and consider the following:
- **Respect the source**: This content is copyrighted by Alcoholics Anonymous World Services, Inc.
- **Rate limiting**: Don't make excessive requests to avoid overloading their servers
- **Educational use**: This library is intended for personal, educational, and recovery support purposes
- **No warranty**: This is an unofficial library and comes with no guarantees
## 🚀 Installation
```bash
npm install aa-daily-reflections
```
## 📖 Usage
### JavaScript/TypeScript API
```javascript
const { DailyReflections } = require('aa-daily-reflections');
// Create instance (default language: English)
const reflections = new DailyReflections();
// Get today's reflection
const todayReflection = await reflections.getToday();
console.log(todayReflection);
// Get reflection for specific date
const reflection = await reflections.getReflection(6, 25); // June 25th
console.log(reflection);
// Change language
reflections.setLanguage('es'); // Spanish
const spanishReflection = await reflections.getToday();
// Create instance with specific language
const frenchClient = new DailyReflections('fr');
const frenchReflection = await frenchClient.getToday();
```
```typescript
import DailyReflections, { DailyReflection, Language } from 'aa-daily-reflections';
const reflections = new DailyReflections('en');
const reflection: DailyReflection = await reflections.getReflection(12, 24);
console.log(`Title: ${reflection.title}`);
console.log(`Quote: ${reflection.quote}`);
console.log(`Reflection: ${reflection.reflection}`);
```
```bash
aa-daily
aa-daily 06/25
aa-daily -l es
aa-daily -d 12/24 -l fr
aa-daily --help
```
- **English** (`en`) - Default
- **Spanish** (`es`) - Español
- **French** (`fr`) - Français
```typescript
new DailyReflections(language?: Language)
```
- `language` (optional): Language code ('en', 'es', 'fr'). Default: 'en'
#### Methods
##### `getToday(): Promise<DailyReflection>`
Fetches today's daily reflection.
##### `getReflection(month: number, day: number): Promise<DailyReflection>`
Fetches the daily reflection for a specific date.
- `month`: Month number (1-12)
- `day`: Day number (1-31)
##### `setLanguage(language: Language): void`
Changes the language for future requests.
##### `getLanguage(): Language`
Returns the current language setting.
### Interface: DailyReflection
```typescript
interface DailyReflection {
title: string; // Title of the reflection
date: string; // Date in MM-DD format
day: number; // Day number
month: number; // Month number
monthName: string; // Month name
quote: string; // Main quote/passage
reference: string; // Source reference (book, page)
reflection: string; // Personal reflection text
copyright: string; // Copyright information
}
```
This library supports:
- ✅ Node.js 22.x
- ✅ Node.js 20.x
- ✅ Node.js 18.x
- ✅ Node.js 16.x
**Note**: Node.js 18+ has built-in fetch. For Node.js 16, the library will attempt to use `node-fetch` if available, or provide clear error messages if not.
The library is structured for maintainability and clean separation of concerns:
```
src/
├── index.ts
├── types.ts
├── utils/
│ ├── date.ts
│ ├── text.ts
│ └── url.ts
├── services/
│ └── http-client.ts
└── parsers/
└── reflection-parser.ts
```
Each module has focused responsibilities:
- **Utils**: Pure functions for common operations
- **Services**: Handle external dependencies (HTTP)
- **Parsers**: Transform API responses into clean data
- **Main class**: Orchestrates everything together
## 🔧 Development
```bash
# Clone the repository
git clone https://github.com/paladini/aa-daily-reflections.git
cd aa-daily-reflections
# Install dependencies
npm install
# Build the project
npm run build
# Run linting
npm run lint
# Fix linting issues
npm run lint:fix
```
## 📝 Examples
### Basic Usage
```javascript
const { DailyReflections } = require('aa-daily-reflections');
async function example() {
const reflections = new DailyReflections();
try {
const reflection = await reflections.getToday();
console.log(`📅 ${reflection.monthName} ${reflection.day}`);
console.log(`🎯 ${reflection.title}`);
console.log(`💬 "${reflection.quote}"`);
console.log(`📖 ${reflection.reference}`);
console.log(`📝 ${reflection.reflection}`);
} catch (error) {
console.error('Error fetching reflection:', error.message);
}
}
example();
```
```javascript
const { DailyReflections } = require('aa-daily-reflections');
async function robustExample() {
const reflections = new DailyReflections();
try {
const reflection = await reflections.getReflection(2, 30); // Invalid date
} catch (error) {
if (error.message.includes('not valid for month')) {
console.log('Invalid date provided');
} else if (error.message.includes('Failed to fetch')) {
console.log('Network or API error');
} else {
console.log('Unexpected error:', error.message);
}
}
}
```
```javascript
const { DailyReflections } = require('aa-daily-reflections');
async function multiLanguageExample() {
const languages = ['en', 'es', 'fr'];
for (const lang of languages) {
const client = new DailyReflections(lang);
const reflection = await client.getReflection(6, 25);
console.log(`\n--- ${lang.toUpperCase()} ---`);
console.log(reflection.title);
}
}
```
MIT License - see [LICENSE](LICENSE) file for details.
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## ⚠️ Disclaimer
This is an unofficial library. The Daily Reflections content is copyrighted by Alcoholics Anonymous World Services, Inc. This library simply provides a convenient interface to access publicly available content. Please respect their terms of service and use this tool responsibly.
## 🙏 Acknowledgments
- Alcoholics Anonymous World Services, Inc. for providing the Daily Reflections
- The AA community for their ongoing support and recovery resources
- All contributors who help improve this library
---
**Remember**: Recovery is a journey, and daily reflection is a powerful tool in that journey. Use this library to support your spiritual practice and growth. 🙏