@akumzy/cron-api-sdk/README.md

TypeScript SDK for Cron API and Reminder services

# Cron API TypeScript SDK

A comprehensive TypeScript SDK for interacting with the Cron API and Reminder services.

## Features

- 🕒 **Full Cron Job Management** - Create, update, delete, and trigger cron jobs
- 📅 **Reminder System** - One-off and recurring reminders with timezone support
- 🔧 **Service Management** - Manage webhook endpoints for notifications
- 📊 **Logging & Monitoring** - Access execution logs and job history
- 🛡️ **Type Safety** - Full TypeScript support with comprehensive type definitions
- 🚀 **Easy to Use** - Simple, intuitive API with excellent developer experience
- 🔐 **Authentication** - Basic auth support for secure API access

## Installation

```bash
npm install @akumzy/cron-api-sdk
```

Or with yarn:

```bash
yarn add @akumzy/cron-api-sdk
```

## Quick Start

```typescript
import { CronApiSDK } from '@akumzy/cron-api-sdk';

// Create SDK instance
const sdk = CronApiSDK.create('http://localhost:8080', {
  username: 'your-username',
  password: 'your-password',
});

// Or for development
const sdk = CronApiSDK.createForDev({
  username: 'admin',
  password: 'admin',
});

// Test connection
await sdk.ping();
```

## Usage Examples

### Job Management

```typescript
// Create a new cron job
const job = await sdk.jobs.create({
  name: 'Daily Backup',
  schedule: '0 2 * * *', // Every day at 2 AM
  method: 'POST',
  url: 'https://api.example.com/backup',
  headers: {
    Authorization: 'Bearer token',
    'Content-Type': 'application/json',
  },
  payload: JSON.stringify({ action: 'backup' }),
  active: true,
});

// Get all jobs
const jobs = await sdk.jobs.getAll();

// Get specific job
const specificJob = await sdk.jobs.getById(1);

// Update a job
const updatedJob = await sdk.jobs.update({
  ...job,
  schedule: '0 3 * * *', // Change to 3 AM
});

// Trigger job manually
await sdk.jobs.trigger(job.id);

// Get job logs
const logs = await sdk.jobs.getLogs(job.id);

// Delete job
await sdk.jobs.delete(job.id);
```

### Service Management

```typescript
// Create a service endpoint
const service = await sdk.services.create({
  name: 'Slack Notifications',
  endpoint: 'https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK',
  description: 'Send notifications to Slack channel',
});

// Get all services
const services = await sdk.services.getAll();

// Update service
const updatedService = await sdk.services.update({
  ...service,
  description: 'Updated description',
});

// Delete service
await sdk.services.delete(service.id);
```

### Reminder Management

```typescript
// Create a one-off reminder
const oneOffReminder = await sdk.reminders.create({
  type: 'one-off',
  service_id: service.id,
  message: 'Important meeting tomorrow!',
  scheduled_time: new Date('2024-12-25T09:00:00Z').toISOString(),
});

// Create a recurring reminder
const recurringReminder = await sdk.reminders.create({
  type: 'recurring',
  service_id: service.id,
  message: 'Daily standup meeting',
  time: '09:00', // 9 AM
  timezones: ['America/New_York', 'Europe/London', 'Asia/Tokyo'],
});

// Get all reminders
const reminders = await sdk.reminders.getAll();

// Trigger reminder manually
await sdk.reminders.trigger(oneOffReminder.id);

// Get reminder logs
const reminderLogs = await sdk.reminders.getLogs(oneOffReminder.id);

// Delete reminder
await sdk.reminders.delete(oneOffReminder.id);
```

### Cron Expression Utilities

```typescript
import { CronUtils } from '@akumzy/cron-api-sdk';

// Validate cron expression
const isValid = CronUtils.validateCronExpression('0 9 * * 1-5');
console.log(isValid); // true

// Parse cron expression to human-readable format
const description = CronUtils.parseCronExpression('0 9 * * 1-5');
console.log(description); // "Every weekday at 9:00 AM"

// Use common expressions
const everyDay = CronUtils.commonExpressions.everyDay; // "0 0 * * *"

// Create cron expression
const expression = CronUtils.createCronExpression({
  minute: 30,
  hour: 14,
  dayOfWeek: 1, // Monday
});
console.log(expression); // "30 14 * * 1"

// Get next execution times
const nextRuns = CronUtils.getNextExecutions('0 9 * * 1-5', 5);
console.log(nextRuns); // Array of next 5 execution dates
```

## API Reference

### CronApiSDK

The main SDK class that provides access to all API clients.

```typescript
const sdk = new CronApiSDK({
  baseURL: 'http://localhost:8080',
  timeout: 10000, // optional, default 10s
  auth: {
    username: 'admin',
    password: 'password',
  },
  headers: {
    // optional additional headers
    'X-Custom-Header': 'value',
  },
});
```

### JobsClient

Manages cron jobs and their execution.

- `getAll()` - Get all jobs
- `getById(id)` - Get job by ID
- `create(job)` - Create new job
- `update(job)` - Update existing job
- `delete(id)` - Delete job
- `trigger(id)` - Manually trigger job
- `getLogs(id)` - Get job execution logs
- `getAllLogs()` - Get all job logs

### RemindersClient

Manages reminders and notifications.

- `getAll()` - Get all reminders
- `getById(id)` - Get reminder by ID
- `create(reminder)` - Create new reminder
- `update(reminder)` - Update existing reminder
- `delete(id)` - Delete reminder
- `trigger(id)` - Manually trigger reminder
- `getLogs(id)` - Get reminder execution logs
- `getAllLogs()` - Get all reminder logs

### ServicesClient

Manages service endpoints for webhooks.

- `getAll()` - Get all services
- `getById(id)` - Get service by ID
- `create(service)` - Create new service
- `update(service)` - Update existing service
- `delete(id)` - Delete service

## Types

The SDK includes comprehensive TypeScript types:

```typescript
import type { Job, JobLog, Reminder, ReminderType, ReminderStatus, Service, CronApiConfig } from '@akumzy/cron-api-sdk';
```

## Error Handling

The SDK provides consistent error handling:

```typescript
try {
  const job = await sdk.jobs.getById(999);
} catch (error) {
  console.error(error.message); // "API Error (404): Job not found"
}
```

## Development

To build the SDK locally:

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm run test

# Lint code
npm run lint

# Watch mode for development
npm run dev
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

For support and questions, please open an issue on the GitHub repository.