Package Exports
- azubiheft-api
Readme
π azubiheft-api
The ultimate TypeScript/Node.js API client for azubiheft.de Automate your German apprenticeship training records (Berichtsheft) with ease!
π Quick Start
npm install azubiheft-apiimport { Session, Entry, EntryType } from 'azubiheft-api';
const session = new Session();
await session.login({ username: 'your-username', password: 'your-password' });
// Create a report entry
const entry = new Entry(
new Date(),
'Learned advanced TypeScript patterns and API design',
'08:00',
EntryType.BETRIEB
);
await session.writeReports([entry]);
console.log('π Report submitted successfully!');π Features
π Authentication & Session Management
- Secure login/logout with persistent cookie sessions
- Automatic session validation and renewal
- Built-in authentication error handling
π Comprehensive Report Management
- Create single or batch report entries
- Read existing reports with optional HTML formatting
- Delete individual entries or entire days
- Support for all standard subject types
π·οΈ Dynamic Subject Management
- Add custom subjects beyond the default ones
- Delete user-created subjects
- List all available subjects (static + dynamic)
- Subject ID resolution by name
β° Advanced Time Utilities
- Parse and validate time strings (HH:MM format)
- Convert between different time representations
- Add/subtract time durations with overflow protection
- ISO week calculations for German calendar system
π‘οΈ Type Safety & Error Handling
- Full TypeScript support with strict typing
- Custom error classes for different scenarios
- Comprehensive input validation
- Detailed error messages for debugging
π¦ Modern Package Design
- Dual module support (CommonJS + ES Modules)
- Tree-shakeable exports
- Source maps and declaration files
- Zero-config TypeScript integration
π Documentation
π― Core Concepts
Session Management
The Session class is your main entry point for all API interactions. It manages authentication, cookies, and HTTP requests automatically.
import { Session } from 'azubiheft-api';
const session = new Session({
baseUrl: 'https://www.azubiheft.de', // Optional: custom base URL
timeout: 30000, // Optional: request timeout in ms
userAgent: 'MyApp/1.0.0' // Optional: custom user agent
});Report Entries
Report entries represent individual training activities. Each entry contains:
- Date: When the activity took place
- Message: Description of what was done
- Time Spent: Duration in HH:MM format (max 19:59)
- Type: Subject/category ID (1-7 for built-in types, higher for custom)
import { Entry, EntryType } from 'azubiheft-api';
const workEntry = new Entry(
new Date('2024-01-15'),
'Implemented REST API endpoints for user management',
'06:30',
EntryType.BETRIEB
);
const schoolEntry = new Entry(
new Date('2024-01-15'),
'Attended software architecture seminar',
'01:30',
EntryType.SCHULE
);π§ API Reference
Session Class
Authentication Methods
// Login with credentials
await session.login({
username: 'your-username',
password: 'your-password'
});
// Check authentication status
const isLoggedIn = await session.isLoggedIn();
// Logout and clean up session
await session.logout();Report Management Methods
// Write a single report
await session.writeReport(
new Date(), // date
'Daily activities', // message
'08:00', // timeSpent
EntryType.BETRIEB // entryType
);
// Write multiple reports at once
const entries = [entry1, entry2, entry3];
await session.writeReports(entries);
// Get reports for a specific date
const reports = await session.getReport(new Date());
// Get reports with HTML formatting preserved
const formattedReports = await session.getReport(new Date(), true);
// Delete all reports for a date
await session.deleteReport(new Date());
// Delete specific report (1-based index)
await session.deleteReport(new Date(), 1);Subject Management Methods
// Get all available subjects
const subjects = await session.getSubjects();
// Add a custom subject
await session.addSubject('Machine Learning');
// Delete a custom subject by ID
await session.deleteSubject('customSubjectId');
// Find subject ID by name
const subjectId = await session.getArtIdFromText('Betrieb');
// Get week ID for calendar calculations
const weekId = await session.getReportWeekId(new Date());Entry Class
// Create entry with validation
const entry = new Entry(date, message, timeSpent, type);
// Validate entry data
entry.validate(); // throws error if invalid
// Create from plain object
const entry2 = Entry.fromObject({
date: new Date(),
message: 'Task description',
timeSpent: '04:30',
type: 1
});
// Convert to plain object
const data = entry.toObject();
// Create modified copy
const modifiedEntry = entry.with({
timeSpent: '05:00',
message: 'Updated description'
});
// String representation
console.log(entry.toString());
// Equality comparison
const isEqual = entry1.equals(entry2);TimeHelper Class
import { TimeHelper } from 'azubiheft-api';
// Date formatting
const dateStr = TimeHelper.dateTimeToString(new Date()); // "20240115"
const timestamp = TimeHelper.getActualTimestamp(); // "1705123456"
// Time string operations
const total = TimeHelper.addTimeStrings('04:30', '03:15'); // "07:45"
const diff = TimeHelper.subtractTimeStrings('08:00', '02:30'); // "05:30"
// Time conversions
const minutes = TimeHelper.timeStringToMinutes('08:45'); // 525
const timeStr = TimeHelper.minutesToTimeString(525); // "08:45"
// Duration from milliseconds
const duration = TimeHelper.millisecondsToTimeString(8 * 60 * 60 * 1000); // "08:00"
// Validation
TimeHelper.validateTimeString('25:00'); // throws error
TimeHelper.validateTimeString('08:30'); // returns true
// ISO week calculations
const { year, week } = TimeHelper.getISOWeek(new Date());
// Parse date strings
const date = TimeHelper.stringToDateTime('20240115');
const { hours, minutes } = TimeHelper.parseTimeString('08:30');π·οΈ Built-in Subject Types
import { EntryType, STATIC_SUBJECTS } from 'azubiheft-api';
// Enum values
EntryType.BETRIEB // 1 - Company work
EntryType.SCHULE // 2 - School/vocational college
EntryType.UBA // 3 - Inter-company training
EntryType.URLAUB // 4 - Vacation/holiday
EntryType.FEIERTAG // 5 - Public holiday
EntryType.ARBEITSUNFAHIG // 6 - Sick leave
EntryType.FREI // 7 - Free time
// Static subjects array
console.log(STATIC_SUBJECTS);
// [
// { id: '1', name: 'Betrieb' },
// { id: '2', name: 'Schule' },
// { id: '3', name: 'ΓBA' },
// { id: '4', name: 'Urlaub' },
// { id: '5', name: 'Feiertag' },
// { id: '6', name: 'ArbeitsunfΓ€hig' },
// { id: '7', name: 'Frei' }
// ]π¨ Error Handling
The library provides specific error types for different scenarios:
import {
AuthError,
NotLoggedInError,
ValueTooLargeError,
ApiError,
ParseError,
NetworkError,
NotFoundError,
isAuthError,
isNotLoggedInError
} from 'azubiheft-api';
try {
await session.login({ username: 'invalid', password: 'wrong' });
} catch (error) {
if (isAuthError(error)) {
console.log('π Authentication failed:', error.message);
// Handle login failure
} else if (error instanceof NetworkError) {
console.log('π Network issue:', error.message);
// Handle network problems
} else if (error instanceof ApiError) {
console.log('π‘ API error:', error.message, 'Status:', error.statusCode);
// Handle API-specific errors
}
}
// Automatic retry with backoff
async function loginWithRetry(credentials, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
await session.login(credentials);
return;
} catch (error) {
if (isAuthError(error)) {
throw error; // Don't retry auth failures
}
if (i === maxRetries - 1) throw error;
await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
}
}
}π¨ TypeScript Integration
Perfect TypeScript support out of the box:
import type {
Subject,
ReportEntry,
SessionOptions,
LoginCredentials,
Entry as IEntry
} from 'azubiheft-api';
// Type-safe configuration
const config: SessionOptions = {
baseUrl: 'https://custom-azubiheft.com',
timeout: 60000
};
// Type-safe data handling
const subjects: Subject[] = await session.getSubjects();
const reports: ReportEntry[] = await session.getReport(new Date());
// Generic utility function
async function processReports<T>(
session: Session,
date: Date,
processor: (reports: ReportEntry[]) => T
): Promise<T> {
const reports = await session.getReport(date);
return processor(reports);
}π― Examples & Use Cases
Check out our comprehensive examples in the /examples folder:
- Basic Usage - Getting started guide
- Batch Operations - Bulk report management
- Subject Management - Custom subjects
- Error Handling - Robust error handling
- Advanced Automation - Complex workflows
- Time Calculations - Working with time
- Weekly Reports - Week-based operations
- Data Export - Export and analysis
- CLI Tool - Command-line interface
- Web Integration - Web app integration
π§ Installation & Setup
Prerequisites
- Node.js 16.0.0 or higher
- TypeScript 5.0+ (for development)
- Valid azubiheft.de account
Installation
# Install the package
npm install azubiheft-api
# For TypeScript projects (types included automatically)
npm install azubiheft-api
npm install -D typescript @types/node
# For development/contribution
git clone https://github.com/StandartCoder/azubiheft-api.git
cd azubiheft-api
npm install
npm run buildEnvironment Setup
Create a .env file for your credentials (never commit this!):
AZUBIHEFT_USERNAME=your-username
AZUBIHEFT_PASSWORD=your-password
AZUBIHEFT_BASE_URL=https://www.azubiheft.deπ Migration from Python Version
Migrating from the Python version? Check our Migration Guide for a smooth transition.
Key Differences
| Python | TypeScript/Node.js |
|---|---|
requests |
axios |
BeautifulSoup |
cheerio |
| Synchronous | Async/await |
| Duck typing | Static typing |
session.writeReport() |
await session.writeReport() |
π€ Contributing
We welcome contributions! Please read our Contributing Guide for details.
Development Setup
git clone https://github.com/StandartCoder/azubiheft-api.git
cd azubiheft-api
npm install
npm run dev # Start development modeAvailable Scripts
npm run build # Build for production
npm run dev # Development with watch mode
npm run clean # Clean build directory
npm run test # Run tests (coming soon)
npm run lint # Lint code (coming soon)π Additional Resources
- API Documentation - Complete API reference
- Troubleshooting Guide - Common issues and solutions
- FAQ - Frequently asked questions
- Changelog - Version history
- Security Policy - Security guidelines
π License
This project is licensed under the MIT License - see the LICENSE file for details.
β οΈ Disclaimer
This is an unofficial API client for azubiheft.de. Use responsibly and respect the platform's terms of service. The authors are not responsible for any misuse or violations of the platform's policies.
π Acknowledgments
- Thanks to the azubiheft.de platform for providing digital training record management
- Inspired by the need for automation in German apprenticeship documentation
- Built with β€οΈ for the developer and apprentice community
Made with π and TypeScript
β Star us on GitHub | π Report Issues | π¬ Discussions