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

npm install @akumzy/cron-api-sdk

Or with yarn:

yarn add @akumzy/cron-api-sdk

Quick Start

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

// 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

// 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

// 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

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.

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:

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

Error Handling

The SDK provides consistent error handling:

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:

# 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 file for details.

Support

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