commit 2924cce27eaa8e622d4250e53647eddf2ca545f7 Author: Zhongwei Li Date: Sun Nov 30 08:50:13 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..fbc2ab4 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "cronjob-org", + "description": "Interacts with the cronjob.org API.", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Tim Green", + "email": "rawveg@gmail.com" + }, + "skills": [ + "./skills/cronjob-org" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..0d56c27 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# cronjob-org + +Interacts with the cronjob.org API. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..5c82307 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,56 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:rawveg/skillsforge-marketplace:cronjob-org", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "494c510f506d6a215942bbd7f04f8526d60db273", + "treeHash": "0122659b303177e38f337bff3e52504c00e2c9de81254bfaa388f196abfad94a", + "generatedAt": "2025-11-28T10:27:50.401755Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "cronjob-org", + "description": "Interacts with the cronjob.org API." + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "a20ea2e672d2aaa7591e2d9aca6400407852e68aef2f35d3c845d9f51423dc7a" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "cceeec8445fd549cd67e685e60408ca836ea2f9660db2ea1c7f377836a4adde2" + }, + { + "path": "skills/cronjob-org/plugin.json", + "sha256": "a96ae8a5931f9235e9d7bd71caba951a619904f3805e84f07e0f4f4dad0ea2bd" + }, + { + "path": "skills/cronjob-org/SKILL.md", + "sha256": "8189b3dbbac6e3d6f2e1c2eb0fcab56737af81b6d8cc5fead4d13b0e11ada792" + }, + { + "path": "skills/cronjob-org/references/api.md", + "sha256": "bf349e09822802c204a6c1cc7b0ed1248a1ff31fd4aade20bdd3d4bad4d3d46c" + }, + { + "path": "skills/cronjob-org/references/index.md", + "sha256": "aceb3e2dc46639c7c328c2482090917d79eb6bf96f74a6df8f438185345f661d" + } + ], + "dirSha256": "0122659b303177e38f337bff3e52504c00e2c9de81254bfaa388f196abfad94a" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/cronjob-org/SKILL.md b/skills/cronjob-org/SKILL.md new file mode 100644 index 0000000..9fa9871 --- /dev/null +++ b/skills/cronjob-org/SKILL.md @@ -0,0 +1,524 @@ +--- +name: cronjob-org +description: Cron-Job.org Documentation +--- + +# Cronjob-Org Skill + +Comprehensive assistance with the Cron-Job.org REST API for programmatically managing scheduled HTTP jobs. This skill provides guidance on creating, updating, deleting, and monitoring cron jobs through the official API. + +## When to Use This Skill + +This skill should be triggered when: +- **Creating automated HTTP requests** on a schedule using Cron-Job.org +- **Managing cron jobs programmatically** through the REST API +- **Implementing job monitoring** and execution history tracking +- **Setting up notifications** for job failures or successes +- **Working with API authentication** and rate limits +- **Debugging cron job executions** or analyzing performance metrics +- **Building integrations** that require scheduled HTTP calls +- **Configuring job schedules** using timezone-aware cron expressions + +## Key Concepts + +### API Authentication +- **API Keys**: Generated in the Cron-Job.org Console under Settings +- **Bearer Token**: API keys are sent via the `Authorization` header +- **IP Restrictions**: Optional IP allowlisting for enhanced security +- **Rate Limits**: 100 requests/day (default), 5,000 requests/day (sustaining members) + +### Job Object +A Job represents a scheduled HTTP request with: +- **URL**: The endpoint to call +- **Schedule**: Cron expression with timezone support +- **Settings**: Timeout, HTTP method, headers, authentication +- **State**: Enabled/disabled, execution status, history + +### Execution History +Each job execution creates a HistoryItem containing: +- **Timing**: Actual vs planned execution time, jitter, duration +- **Response**: HTTP status code, headers, body (if saveResponses enabled) +- **Performance**: DNS lookup, connection, SSL handshake, transfer times + +### Rate Limits +Different endpoints have different rate limits: +- **Job List/Details**: 5 requests/second +- **Job Creation**: 1 request/second, 5 requests/minute +- **History**: 5 requests/second + +## Quick Reference + +### 1. Authentication Setup + +```bash +# Set your API key as a bearer token in the Authorization header +Authorization: Bearer YOUR_API_KEY_HERE +``` + +**Notes:** +- API keys are generated in the Console → Settings +- Treat API keys as secrets (like passwords) +- Enable IP restrictions whenever possible for security + +### 2. List All Jobs (curl) + +```bash +curl -X GET https://api.cron-job.org/jobs \ + -H "Authorization: Bearer YOUR_API_KEY" +``` + +**Response:** +```json +{ + "jobs": [ + { + "jobId": 12345, + "enabled": true, + "title": "Daily Backup", + "url": "https://example.com/backup", + "lastStatus": 200, + "lastExecution": 1699920000, + "nextExecution": 1700006400 + } + ], + "jobsPartialError": false +} +``` + +**Rate Limit:** 5 requests/second + +### 3. Create a New Job (Python) + +```python +import requests + +API_KEY = "your_api_key_here" +headers = { + "Authorization": f"Bearer {API_KEY}", + "Content-Type": "application/json" +} + +job_data = { + "job": { + "url": "https://example.com/api/health-check", + "enabled": True, + "title": "Health Check", + "saveResponses": True, + "schedule": { + "timezone": "America/New_York", + "hours": [-1], # Every hour + "mdays": [-1], # Every day of month + "minutes": [0], # At minute 0 + "months": [-1], # Every month + "wdays": [-1] # Every day of week + } + } +} + +response = requests.post( + "https://api.cron-job.org/jobs", + headers=headers, + json=job_data +) + +print(f"Created job ID: {response.json()['jobId']}") +``` + +**Rate Limit:** 1 request/second, 5 requests/minute + +### 4. Update an Existing Job + +```python +import requests + +API_KEY = "your_api_key_here" +JOB_ID = 12345 + +headers = { + "Authorization": f"Bearer {API_KEY}", + "Content-Type": "application/json" +} + +# Only include fields you want to change +update_data = { + "job": { + "enabled": False, # Disable the job + "title": "Updated Title" + } +} + +response = requests.patch( + f"https://api.cron-job.org/jobs/{JOB_ID}", + headers=headers, + json=update_data +) + +print("Job updated successfully" if response.status_code == 200 else "Update failed") +``` + +**Rate Limit:** 5 requests/second + +### 5. Job with HTTP Authentication + +```json +{ + "job": { + "url": "https://api.example.com/protected", + "enabled": true, + "title": "Protected Endpoint", + "auth": { + "enable": true, + "user": "api_user", + "password": "secret_password" + } + } +} +``` + +**Notes:** +- Uses HTTP Basic Authentication +- Credentials are stored securely by Cron-Job.org + +### 6. Job with Custom Headers + +```json +{ + "job": { + "url": "https://api.example.com/webhook", + "enabled": true, + "title": "Webhook with Headers", + "extendedData": { + "headers": { + "X-API-Key": "your-api-key", + "Content-Type": "application/json", + "User-Agent": "MyCronJob/1.0" + }, + "body": "{\"event\": \"scheduled_check\"}" + }, + "requestMethod": 1 // 0=GET, 1=POST, 2=PUT, 3=PATCH, 4=DELETE, etc. + } +} +``` + +### 7. Job with Failure Notifications + +```json +{ + "job": { + "url": "https://example.com/critical-task", + "enabled": true, + "title": "Critical Task", + "notifications": { + "onFailure": true, + "onSuccess": false, + "onDisable": true + } + } +} +``` + +**Notification Options:** +- `onFailure`: Notify after job fails (set `onFailureMinutes` for threshold) +- `onSuccess`: Notify when job succeeds after previous failure +- `onDisable`: Notify when job is automatically disabled + +### 8. Get Job Execution History + +```python +import requests + +API_KEY = "your_api_key_here" +JOB_ID = 12345 + +headers = {"Authorization": f"Bearer {API_KEY}"} + +response = requests.get( + f"https://api.cron-job.org/jobs/{JOB_ID}/history", + headers=headers +) + +data = response.json() +print(f"Last {len(data['history'])} executions:") +for item in data['history']: + print(f" {item['date']}: Status {item['httpStatus']} ({item['duration']}ms)") + +print(f"\nNext executions: {data['predictions']}") +``` + +**Rate Limit:** 5 requests/second + +### 9. Schedule Examples + +**Every day at 2:30 AM EST:** +```json +{ + "schedule": { + "timezone": "America/New_York", + "hours": [2], + "mdays": [-1], + "minutes": [30], + "months": [-1], + "wdays": [-1] + } +} +``` + +**Every Monday and Friday at 9 AM UTC:** +```json +{ + "schedule": { + "timezone": "UTC", + "hours": [9], + "mdays": [-1], + "minutes": [0], + "months": [-1], + "wdays": [1, 5] // 0=Sunday, 1=Monday, ..., 6=Saturday + } +} +``` + +**Every 15 minutes:** +```json +{ + "schedule": { + "timezone": "UTC", + "hours": [-1], + "mdays": [-1], + "minutes": [0, 15, 30, 45], + "months": [-1], + "wdays": [-1] + } +} +``` + +### 10. Delete a Job + +```python +import requests + +API_KEY = "your_api_key_here" +JOB_ID = 12345 + +headers = {"Authorization": f"Bearer {API_KEY}"} + +response = requests.delete( + f"https://api.cron-job.org/jobs/{JOB_ID}", + headers=headers +) + +print("Job deleted" if response.status_code == 200 else "Delete failed") +``` + +**Rate Limit:** 5 requests/second + +## Reference Files + +This skill includes comprehensive documentation in `references/`: + +- **api.md** - Complete REST API reference including: + - Authentication and security + - Rate limits and quotas + - All API endpoints (jobs, history) + - Request/response formats + - Object schemas (Job, DetailedJob, JobSchedule, HistoryItem, etc.) + - HTTP status codes and error handling + - Timing statistics and performance metrics + +Use the reference file for: +- Detailed object schema documentation +- Complete list of request/response fields +- Advanced configuration options +- Troubleshooting API errors + +## Working with This Skill + +### For Beginners +1. Start by **reading the API authentication section** in `references/api.md` +2. Generate an API key in the Cron-Job.org Console +3. Use the **Quick Reference examples** above to: + - List your existing jobs + - Create a simple job with a basic schedule + - View execution history +4. Test with curl or Python before building integrations + +### For Intermediate Users +Focus on: +- **Custom headers and authentication** for API integrations +- **Notification settings** for failure alerting +- **Schedule optimization** using timezone-aware cron expressions +- **Execution history analysis** for monitoring job performance +- **Rate limit management** for high-volume applications + +### For Advanced Users +Explore: +- **Batch job management** with proper rate limit handling +- **Performance optimization** using timing statistics from HistoryItem +- **Error handling strategies** based on HTTP status codes +- **IP allowlisting** for production security +- **Sustaining membership** for higher API quotas (5,000 requests/day) + +### Navigation Tips +- Use `references/api.md` for complete endpoint documentation +- Check HTTP status codes section for error troubleshooting +- Review object schemas for all available configuration fields +- Reference the schedule examples for common cron patterns + +## Common Patterns + +### Pattern 1: Health Check Monitoring +Create a job that pings your service every 5 minutes and notifies on failure: + +```python +job = { + "url": "https://myapp.com/health", + "enabled": True, + "title": "App Health Check", + "saveResponses": False, + "schedule": { + "timezone": "UTC", + "hours": [-1], + "mdays": [-1], + "minutes": [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55], + "months": [-1], + "wdays": [-1] + }, + "notifications": { + "onFailure": True, + "onSuccess": True, + "onDisable": True + } +} +``` + +### Pattern 2: Daily Data Sync +Trigger a webhook at 3 AM daily with custom headers: + +```python +job = { + "url": "https://api.myapp.com/sync", + "enabled": True, + "title": "Daily Data Sync", + "requestMethod": 1, # POST + "extendedData": { + "headers": { + "X-Sync-Token": "secret", + "Content-Type": "application/json" + }, + "body": '{"action": "daily_sync"}' + }, + "schedule": { + "timezone": "America/Los_Angeles", + "hours": [3], + "mdays": [-1], + "minutes": [0], + "months": [-1], + "wdays": [-1] + } +} +``` + +### Pattern 3: Weekday Business Hours Job +Run a job every weekday at 9 AM and 5 PM: + +```python +job = { + "url": "https://example.com/business-task", + "enabled": True, + "title": "Business Hours Task", + "schedule": { + "timezone": "America/New_York", + "hours": [9, 17], + "mdays": [-1], + "minutes": [0], + "months": [-1], + "wdays": [1, 2, 3, 4, 5] # Monday-Friday + } +} +``` + +## HTTP Status Codes + +| Code | Description | +|------|-------------| +| 200 | OK - Request succeeded | +| 400 | Bad Request - Invalid request or input data | +| 401 | Unauthorized - Invalid API key | +| 403 | Forbidden - API key cannot be used from this origin | +| 404 | Not Found - Resource doesn't exist | +| 409 | Conflict - Resource already exists | +| 429 | Too Many Requests - Quota or rate limit exceeded | +| 500 | Internal Server Error | + +## Important Limits + +- **Daily Quota**: 100 requests/day (default), 5,000 requests/day (sustaining members) +- **Job Creation**: 1 request/second, 5 requests/minute +- **Other Endpoints**: 5 requests/second +- **Job Timeout**: Configurable per job (default system timeout applies) +- **Response Storage**: Enable `saveResponses` to store headers/body in history + +## Security Best Practices + +1. **Protect API Keys**: Treat them like passwords, never commit to version control +2. **Enable IP Restrictions**: Limit API access to specific IP addresses +3. **Use HTTPS**: All API communication is HTTPS-only +4. **Rotate Keys**: Periodically regenerate API keys +5. **Monitor Usage**: Track API request counts to avoid quota exhaustion + +## Resources + +### Official Documentation +- REST API Docs: https://docs.cron-job.org/rest-api.html +- Console: https://console.cron-job.org/ + +### Supported Timezones +See the official documentation for a complete list of supported timezone values (e.g., "UTC", "America/New_York", "Europe/London"). + +### Example Use Cases +- **API Health Checks**: Monitor service availability +- **Data Synchronization**: Trigger scheduled data imports/exports +- **Report Generation**: Generate and send periodic reports +- **Cache Warming**: Pre-load caches before peak traffic +- **Webhook Delivery**: Send scheduled webhook notifications +- **Backup Triggers**: Initiate automated backup processes + +## Troubleshooting + +### 401 Unauthorized +- Verify API key is correct +- Check Authorization header format: `Authorization: Bearer YOUR_KEY` +- Ensure API key hasn't been revoked + +### 403 Forbidden +- Check if IP restrictions are enabled +- Verify your IP address is allowlisted + +### 429 Too Many Requests +- Review rate limits for specific endpoint +- Implement exponential backoff +- Consider sustaining membership for higher limits + +### Job Not Executing +- Verify job is enabled +- Check schedule configuration +- Review `nextExecution` timestamp +- Check if job has been auto-disabled due to failures + +### Missing Response Data in History +- Ensure `saveResponses` is set to `true` +- Use the detailed history item endpoint for headers/body + +## Notes + +- All timestamps are Unix timestamps in seconds +- Schedule uses arrays where `[-1]` means "all values" (every hour, every day, etc.) +- Job execution times may have jitter (scheduling delay) - check `HistoryItem.jitter` +- Failed jobs may be automatically disabled based on notification settings +- Execution history is limited; use the API to retrieve recent items + +## Updating + +This skill was generated from official Cron-Job.org documentation. For the latest API changes: +1. Visit https://docs.cron-job.org/rest-api.html +2. Check for new endpoints or schema changes +3. Update your integration code accordingly diff --git a/skills/cronjob-org/plugin.json b/skills/cronjob-org/plugin.json new file mode 100644 index 0000000..5cb2a46 --- /dev/null +++ b/skills/cronjob-org/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "cronjob-org", + "description": "Interacts with the cronjob.org API.", + "version": "1.0.0", + "author": { + "name": "Tim Green", + "email": "rawveg@gmail.com" + }, + "homepage": "https://github.com/rawveg/claude-skills-marketplace", + "repository": "https://github.com/rawveg/claude-skills-marketplace", + "license": "MIT", + "keywords": ["cronjob-org", "cronjob.org", "Claude Code"], + "category": "productivity", + "strict": false +} diff --git a/skills/cronjob-org/references/api.md b/skills/cronjob-org/references/api.md new file mode 100644 index 0000000..9012582 --- /dev/null +++ b/skills/cronjob-org/references/api.md @@ -0,0 +1,241 @@ +# Cronjob-Org - Api + +**Pages:** 1 + +--- + +## REST API — cron-job.org documentation + +**URL:** https://docs.cron-job.org/rest-api.html + +**Contents:** +- REST API +- Introduction +- Limitations +- Requests + - Endpoint + - Authentication + - Content Type + - HTTP Status Codes + - Examples +- API Methods + +cron-job.org provides an API which enables users to programatically create, update, delete and view cron jobs. The API provides a REST-like interface with API-key based authorization and JSON request and response payload. Given this, the API should be easily usable from virtually any programming language. + +In order to prevent abuse of our service, we enforce a daily usage limit. By default, this limit is 100 requests per day, but can be increased upon request. For sustaining members, a higher limit of 5,000 requests per day applies. + +Apart from the daily request limit, individual rate limits might apply depending on the specific API call made. Those limits are mentioned in the documentation of the specific API method. + +The API endpoint is reachable via HTTPS at: + +All requests to the API must be authenticated via an API key supplied in the Authorization bearer token header. API keys can be retrieved/generated in the cron-job.org Console at “Settings”. An example header could look like: + +Access via a specific API key might be restricted to certain IP addresses, if configured in the Console. In this case, requests from non-allowlisted IP addresses will be rejected with an HTTP error code of 403. + +API keys are secrets, just like a password. They allow access to your cron-job.org account via the API and should always be treated confidentially. We highly recommend to also enable the IP address restriction whenever possible. + +In case a request requires a payload, it must be JSON-encoded and the Content-Type header must be set to application/json. In case the Content-Type header is missing or contains a different value, the request payload will be ignored. + +The following status codes can be returned by the API: + +OK: Request succeeded + +Bad request: Invalid request / invalid input data + +Unauthorized: Invalid API key + +Forbidden: API key cannot be used from this origin + +Not found: The requested resource could not be found + +Conflict, e.g. because a resource already exists + +API key quota, resource quota or rate limit exceeded + +Internal server error + +Example request via curl: + +Example request via Python: + +List all jobs in this account: + +List of jobs present in the account + +true in case some jobs could not be retrieved because of internal errors and the list might be incomplete, otherwise false + +Max. 5 requests per second. + +Retrieve detailed information for a specific cron job identified by its jobId: + +Max. 5 requests per second. + +Creating a new cron job: + +Job (only the url field is mandatory) + +Identifier of the created job + +Max. 1 request per second and 5 requests per minute. + +Updating a cron job identified by its jobId: + +Job delta (only include changed fields - unchanged fields can be left out) + +Max. 5 requests per second. + +Deleting a cron job identified by its jobId: + +Max. 5 requests per second. + +Retrieve the execution history for a specific cron job identified by its jobId: + +The last execution history items + +Unix timestamps (in seconds) of the predicted next executions (up to 3) + +Please note that the headers and body fields of the HistoryItem objects will not be populated. In order to retrieve headers and body, see Retrieving Job Execution History Item Details. + +Max. 5 requests per second. + +Retrieve details for a specific history item identified by its identifier for a specific cron job identified by its jobId: + +Max. 5 requests per second. + +The Job object represents a cron job. + +Job identifier (read only; ignored during job creation or update) + +Whether the job is enabled (i.e. being executed) or not + +Whether to save job response header/body or not + +Last execution status (read only) + +0 (Unknown / not executed yet) + +Last execution duration in milliseconds (read only) + +Unix timestamp of last execution (in seconds; read only) + +Unix timestamp of predicted next execution (in seconds), null if no prediction available (read only) + +Job timeout in seconds + +-1 (i.e. use default timeout) + +Whether to treat 3xx HTTP redirect status codes as success or not + +The identifier of the folder this job resides in + +* Value when field is omitted while creating a job. + +The DetailedJob object represents a cron job with detailed settings. It consists of all members of the Job object plus the following additional fields. + +HTTP authentication settings + +JobNotificationSettings + +Notification settings + +Extended request data + +The JobAuth object represents HTTP (basic) authentication settings for a job. + +Whether to enable HTTP basic authentication or not. + +HTTP basic auth username + +HTTP basic auth password + +* Value when field is omitted while creating a job. + +The JobNotificationSettings specifies notification settings for a job. + +Whether to send a notification on job failure or not. + +How many failures are required before a notification is sent (min 1). + +Whether to send a notification when the job succeeds after a prior failure or not. + +Whether to send a notification when the job has been disabled automatically or not. + +* Value when field is omitted while creating a job. + +The JobExtendedData holds extended request data for a job. + +Request headers (key-value dictionary) + +* Value when field is omitted while creating a job. + +Unknown / not executed yet + +Failed (could not connect to host) + +Failed (too much response data) + +Failed (internal errors) + +Failed (unknown reason) + +Monitoring job (used in a status monitor) + +The JobSchedule object represents the execution schedule of a job. + +Schedule time zone (see here for a list of supported values) + +Date/time (in job’s time zone) after which the job expires, i.e. after which it is not scheduled anymore (format: YYYYMMDDhhmmss, 0 = does not expire) + +Hours in which to execute the job (0-23; [-1] = every hour) + +Days of month in which to execute the job (1-31; [-1] = every day of month) + +Minutes in which to execute the job (0-59; [-1] = every minute) + +Months in which to execute the job (1-12; [-1] = every month) + +Days of week in which to execute the job (0=Sunday - 6=Saturday; [-1] = every day of week) + +* Value when field is omitted while creating a job. + +The HistoryItem object represents a job history log entry corresponding to one execution of the job. + +Identifier of the associated cron job + +Identifier of the history item + +Unix timestamp (in seconds) of the actual execution + +Unix timestamp (in seconds) of the planned/ideal execution + +Scheduling jitter in milliseconds + +Job URL at time of execution + +Actual job duration in milliseconds + +Detailed job status Description + +HTTP status code returned by the host, if any + +Raw response headers returned by the host (null if unavailable) + +Raw response body returned by the host (null if unavailable) + +Additional timing information for this request + +The HistoryItemStats object contains additional timing information for a job execution history item. + +Time from transfer start until name lookups completed (in microseconds) + +Time from transfer start until socket connect completed (in microseconds) + +Time from transfer start until SSL handshake completed (n microseconds) - 0 if not using SSL + +Time from transfer start until beginning of data transfer (in microseconds) + +Time from transfer start until the first response byte is received (in microseconds) + +Total transfer time (in microseconds) + +--- diff --git a/skills/cronjob-org/references/index.md b/skills/cronjob-org/references/index.md new file mode 100644 index 0000000..31d69d5 --- /dev/null +++ b/skills/cronjob-org/references/index.md @@ -0,0 +1,7 @@ +# Cronjob-Org Documentation Index + +## Categories + +### Api +**File:** `api.md` +**Pages:** 1