Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

examples

README.md

📚 Azubiheft API Examples

This directory contains comprehensive examples demonstrating various features and use cases of the azubiheft-api package.

🎯 Example Overview

Example Description Complexity Key Features
01-basic-usage.ts Getting started guide ⭐ Beginner Login, basic CRUD operations
02-batch-operations.ts Bulk report management ⭐⭐ Intermediate Batch processing, templates
03-subject-management.ts Custom subjects ⭐⭐ Intermediate Subject CRUD, categorization
04-error-handling.ts Robust error handling ⭐⭐⭐ Advanced Retry logic, circuit breaker
05-advanced-automation.ts Complex workflows ⭐⭐⭐ Advanced AI content, workflow orchestration
06-time-calculations.ts Time management ⭐⭐ Intermediate Time tracking, German compliance
07-weekly-reports.ts Week-based operations ⭐⭐ Intermediate ISO weeks, analytics
08-data-export.ts Export and analysis ⭐⭐⭐ Advanced Multiple formats, backup
09-cli-tool.ts Command-line interface ⭐⭐⭐ Advanced CLI framework, interactive
10-web-integration.ts Web app integration ⭐⭐⭐ Advanced REST API, WebSockets

🚀 Quick Start

Prerequisites

# Install the package
npm install azubiheft-api

# Set up environment variables (recommended)
echo "AZUBIHEFT_USERNAME=your-username" > .env
echo "AZUBIHEFT_PASSWORD=your-password" >> .env

Running Examples

# Run a specific example
npm run build
node dist/examples/01-basic-usage.js

# Or with ts-node for development
npx ts-node examples/01-basic-usage.ts

# Run with custom parameters
node dist/examples/02-batch-operations.js --cleanup

📖 Example Details

🌟 01 - Basic Usage

Perfect starting point for new users

  • User authentication (login/logout)
  • Creating and validating report entries
  • Reading daily reports
  • Basic error handling patterns
  • Environment variable usage
import { Session, Entry, EntryType } from 'azubiheft-api';

const session = new Session();
await session.login({ username: '...', password: '...' });

const entry = new Entry(new Date(), 'Daily work', '08:00', EntryType.BETRIEB);
await session.writeReports([entry]);

📦 02 - Batch Operations

Efficient handling of multiple reports

  • Weekly report templates
  • Bulk report submission
  • Performance optimization
  • Batch validation and error handling
  • Progress tracking and summaries

Key features:

  • Generate reports for entire weeks
  • Template-based content creation
  • Bulk submission with error recovery
  • Performance monitoring

🏷️ 03 - Subject Management

Organizing and managing subjects

  • Built-in vs custom subjects
  • Subject categorization systems
  • Bulk subject operations
  • Duplicate detection and cleanup
  • Subject usage analytics

Categories covered:

  • Programming & Development
  • Learning & Education
  • Project Management
  • Specialized Skills

🚨 04 - Error Handling

Production-ready error management

  • Custom error types and type guards
  • Retry mechanisms with exponential backoff
  • Circuit breaker pattern implementation
  • Error logging and monitoring
  • Recovery strategies

Patterns demonstrated:

  • Graceful degradation
  • Automatic session recovery
  • Partial failure handling
  • Error boundaries

🤖 05 - Advanced Automation

Sophisticated automation workflows

  • Template-based report generation
  • AI-assisted content creation (mock)
  • Workflow orchestration
  • Smart scheduling suggestions
  • Performance analytics

Features:

  • Activity templates with variations
  • Weekly schedule automation
  • Intelligent content generation
  • Advanced analytics and insights

⏰ 06 - Time Calculations

Comprehensive time management

  • Complex time arithmetic and validation
  • German working time compliance
  • Time tracking and analysis
  • Calendar week calculations
  • Performance metrics

German regulations:

  • Maximum daily/weekly hours
  • Required break times
  • Overtime calculations
  • Compliance checking

📅 07 - Weekly Reports

Week-based data analysis

  • ISO week calculations
  • Weekly report compilation
  • Multi-week trending analysis
  • Holiday and vacation handling
  • Progress tracking

Analytics:

  • Weekly summaries
  • Monthly trends
  • Work vs school balance
  • Productivity insights

📤 08 - Data Export

Multiple export formats and backup

  • JSON, CSV, XML, HTML, Markdown exports
  • Data filtering and transformation
  • Analytics and insights generation
  • Backup and restore functionality
  • Integration-ready formats

Export capabilities:

  • Filtered data extraction
  • Rich analytics inclusion
  • Multiple format support
  • Backup/restore operations

🖥️ 09 - CLI Tool

Command-line interface framework

  • Interactive CLI commands
  • Configuration management
  • Progress indicators
  • Input validation
  • Help system

Commands:

  • login, logout, status
  • add, list, delete (reports)
  • subjects (management)
  • export, config, help

🌐 10 - Web Integration

Web application integration

  • Express.js REST API server
  • Authentication middleware
  • Real-time WebSocket updates
  • Frontend integration patterns
  • Security best practices

Features:

  • Session management
  • Rate limiting
  • Real-time updates
  • React component examples
  • Security considerations

🔧 Development Setup

Running in Development

# Install dependencies
npm install

# Build the project
npm run build

# Run examples with TypeScript
npx ts-node examples/01-basic-usage.ts

# Run with environment variables
AZUBIHEFT_USERNAME=myuser AZUBIHEFT_PASSWORD=mypass npx ts-node examples/01-basic-usage.ts

Environment Configuration

Create a .env file in the project root:

AZUBIHEFT_USERNAME=your-username
AZUBIHEFT_PASSWORD=your-password
AZUBIHEFT_BASE_URL=https://www.azubiheft.de

Example Parameters

Many examples support command-line parameters:

# Cleanup mode (for examples that create test data)
node dist/examples/02-batch-operations.js --cleanup
node dist/examples/03-subject-management.js --cleanup

# CLI tool example with commands
node dist/examples/09-cli-tool.js help
node dist/examples/09-cli-tool.js login

🎯 Use Cases by Example

Learning Path

  1. Start here: 01-basic-usage.ts - Learn the fundamentals
  2. Scale up: 02-batch-operations.ts - Handle multiple reports
  3. Organize: 03-subject-management.ts - Manage categories
  4. Robust code: 04-error-handling.ts - Production patterns
  5. Automate: 05-advanced-automation.ts - Sophisticated workflows

Specific Goals

Goal Recommended Examples
Personal automation 01, 02, 06
Team/company use 04, 05, 08, 10
Data analysis 06, 07, 08
Integration projects 09, 10
Learning the API 01, 03, 04

🛡️ Security Notes

  • Never hardcode credentials in source code
  • Use environment variables for sensitive data
  • Implement proper error handling to avoid credential leaks
  • Consider rate limiting for production use
  • Review the security examples in 10-web-integration.ts

🤝 Contributing

Want to add more examples? Please:

  1. Follow the existing naming convention (XX-description.ts)
  2. Include comprehensive comments and documentation
  3. Add error handling and validation
  4. Update this README with your example
  5. Test with real azubiheft.de credentials (be careful!)

📄 License

These examples are part of the azubiheft-api package and are licensed under the MIT License.

⚠️ Disclaimer

These examples use an unofficial API client. Use responsibly and respect azubiheft.de's terms of service.

Ready to automate your Berichtsheft? Start with 01-basic-usage.ts!

📚 Full Documentation | 🐛 Report Issues | 💬 Discussions