{"id":22109292,"url":"https://github.com/pruvonet/cronicle-client","last_synced_at":"2025-09-15T12:21:32.933Z","repository":{"id":34911813,"uuid":"189284600","full_name":"PruvoNet/cronicle-client","owner":"PruvoNet","description":"Light Cronicle node client with full TypeScript support","archived":false,"fork":false,"pushed_at":"2022-12-30T17:44:42.000Z","size":499,"stargazers_count":9,"open_issues_count":10,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-16T10:16:57.042Z","etag":null,"topics":["api","client","cronicle","node","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PruvoNet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-29T19:16:58.000Z","updated_at":"2024-08-18T15:19:49.000Z","dependencies_parsed_at":"2023-01-15T10:16:42.069Z","dependency_job_id":null,"html_url":"https://github.com/PruvoNet/cronicle-client","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PruvoNet%2Fcronicle-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PruvoNet%2Fcronicle-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PruvoNet%2Fcronicle-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PruvoNet%2Fcronicle-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PruvoNet","download_url":"https://codeload.github.com/PruvoNet/cronicle-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227529075,"owners_count":17783977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","cronicle","node","typescript"],"created_at":"2024-12-01T09:31:11.595Z","updated_at":"2024-12-01T09:31:14.248Z","avatar_url":"https://github.com/PruvoNet.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Npm Version](https://img.shields.io/npm/v/cronicle-client.svg?style=popout)](https://www.npmjs.com/package/cronicle-client)\n[![Build Status](https://travis-ci.org/PruvoNet/cronicle-client.svg?branch=master)](https://travis-ci.org/PruvoNet/cronicle-client)\n[![Coverage Status](https://coveralls.io/repos/github/PruvoNet/cronicle-client/badge.svg?branch=master)](https://coveralls.io/github/PruvoNet/cronicle-client?branch=master)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/58abd1713b064f4c9af7dc88d7178ebe)](https://www.codacy.com/app/regevbr/cronicle-client?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=PruvoNet/cronicle-client\u0026amp;utm_campaign=Badge_Grade)\n[![Known Vulnerabilities](https://snyk.io/test/github/PruvoNet/cronicle-client/badge.svg?targetFile=package.json)](https://snyk.io/test/github/PruvoNet/cronicle-client?targetFile=package.json)\n[![dependencies Status](https://david-dm.org/PruvoNet/cronicle-client/status.svg)](https://david-dm.org/PruvoNet/cronicle-client)\n[![devDependencies Status](https://david-dm.org/PruvoNet/cronicle-client/dev-status.svg)](https://david-dm.org/PruvoNet/cronicle-client?type=dev)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/PruvoNet/cronicle-client/blob/master/.github/logo.png?raw=true\" /\u003e\n\u003c/p\u003e\n\n\n# Cronicle client \nLight [Croncile](https://github.com/jhuckaby/Cronicle) node client with full TypeScript support\n\n## Main features\n- Fully typed api client for Cronicle\n- No dependencies (you need to install your own `request-promise` library)\n- Helper methods to build Timing objects for scheduling events\n- Type safety extendable for Categories, Plugins and Targets\n\n## Install\n\n```shell\nnpm install cronicle-client\n```\n\n--NOTICE--  \n`request-promise` is a peer dependency and must be installed by you (\u003e=1.0.0)\n\n--NOTICE--  \nIf you want to use the timing utils, you must also install `moment`\n\n## Quick example\n\n```typescript\nimport { CronicleClient, NumberedBoolean, BaseCategories, BaseTargets, getFutureUtcTiming, \n HttpPluginMethods, basePlugins, CronicleError, TargetAlgorithms} from 'cronicle-client';\n\nconst scheduler = new CronicleClient({\n  masterUrl: 'http://localhost:3012',\n  apiKey: '\u003cyour api key\u003e',\n});\n\nscheduler.createEvent({\n        plugin: basePlugins.urlplug,\n        title: 'test event1',\n        enabled: NumberedBoolean.TRUE,\n        algo: TargetAlgorithms.RANDOM,\n        category: BaseCategories.GENERAL,\n        target: BaseTargets.GENERAL,\n        timing: getFutureUtcTiming('2016-05-26T14:50:50.900Z'),\n        timezone: 'Etc/UTC',\n        params: {\n          method: HttpPluginMethods.POST,\n          timeout: '60',\n          headers:  'Content-Type: application/json',\n          data: JSON.stringify({ a: 1 }),\n          url: 'https://requestbin.com',\n        },\n      })\n      .then((data) =\u003e {\n        console.log(`Created event with id: ${data.id}`);\n        return scheduler.runEvent({ id: data.id });\n      })\n      .then((data) =\u003e {\n        console.log(`Started event with job id: ${data.ids[0]}`);\n      })\n      .catch((err: CronicleError) =\u003e {\n        console.log(`Cronicle error: ${err.code} - ${err.message}`);\n      });\n```\n\n## Extending with custom types example\n\n```typescript\nimport { CronicleClient, IHttpPluginData, IShellPluginData, ITestPluginData, NumberedBoolean,\n    getFutureUtcTiming, IPluginNames, CronicleError, TargetAlgorithms } from 'cronicle-client';\n\ninterface ICustomPluginData {\n  duration: string;\n  action: string;\n}\n\ninterface Plugins {\n  // Default plugins\n  urlplug: IHttpPluginData;\n  shellplug: IShellPluginData;\n  testplug: ITestPluginData;\n  // Custom plugins\n  mycustomplug: ICustomPluginData;\n}\n\nenum Categories {\n  // Default category\n  GENERAL = 'general',\n  // Custom categories...\n  TEST_CATEGORY = 'cjw6g085901', \n  TEST_CATEGORY2 = 'cjw6l8mnb02',\n}\n\nenum Targets {\n    // Default targets...\n    ALL = 'allgrp',\n    MAIN = 'maingrp',\n    // Custom targets...\n    AWS = 'awsgrp',\n    GCP = 'gcpgrp',\n}\n\nconst plugins: IPluginNames\u003cPlugins\u003e = {\n    urlplug: 'urlplug',\n    shellplug: 'shellplug',\n    testplug: 'testplug',\n    mycustomplug: 'mycustomplug',\n};\n\nconst scheduler = new CronicleClient\u003cCategories, Targets, Plugins\u003e({\n  masterUrl: 'http://localhost:3012',\n  apiKey: '\u003cyour api key\u003e',\n});\n\nscheduler.createEvent({\n        plugin: plugins.mycustomplug,\n        title: 'test event1',\n        enabled: NumberedBoolean.TRUE,\n        algo: TargetAlgorithms.RANDOM,\n        category: Categories.TEST_CATEGORY2,\n        target: Targets.AWS,\n        timing: getFutureUtcTiming('2016-05-26T14:50:50.900Z'),\n        timezone: 'Etc/UTC',\n        params: {\n          duration: '60',\n          action: JSON.stringify({ a: 1 }),\n        },\n      })\n      .then((data) =\u003e {\n        console.log(`Created event with id: ${data.id}`);\n        return scheduler.runEvent({ id: data.id });\n      })\n      .then((data) =\u003e {\n        console.log(`Started event with job id: ${data.ids[0]}`);\n      })\n      .catch((err: CronicleError) =\u003e {\n        console.log(`Cronicle error: ${err.code} - ${err.message}`);\n      });\n```\n\n## Documentation\n\n### Methods\n\nFor all api endpoints documentations, please refer to [Cronicle api reference](https://github.com/jhuckaby/Cronicle#api-reference)\n\n#### createEvent\n\nWhen creating an event, there is no unique restriction on the title/id.  \nWhile searching for an event using `getEvent`, the\napi allows you to search by title/id, which is great, but as of now (cronicle v0.89) it will return a single result.  \nThis imposes an issue when you don't enforce a unique title/id since you will get a random result (see [#186](https://github.com/jhuckaby/Cronicle/issues/186))  \nUntil this behaviour is fixed, you can tell the `createEvent` method to enforce uniqueness and it will fail if an event with the provided title/id already exists.  \nNote: if `id` is provided - it will be used as the unique key, otherwise `title` will be used.\n\n### Error handling\n\n`Croncile` will always return a valid HTTP response (code `200`).  \nTo raise an error, the `code` property of the response will be different than `0`.  \nIn such cases, the current method will be rejected with `CronicleError` with the proper error message and the \n`code` property.\n\n### Constructor\n\n#### Options\n\n| Parameter Name | Description |\n|----------------|-------------|\n| `masterUrl`    | The full url to the master Cronicle server\n| `apiKey`       | The api key to use (make sure it has relevant permissions enabled)\n\n#### Typings\n\nThe client can  enforce the proper usage of categories, targets and plugins (with their required parameters).  \nThis is done using optional generics:  \n\n| Generics Parameter Name  | Description |\n|--------------------------|-------------|\n| `Categories`             | Enum containing the ids of the categories available at you Cronicle server (Defaults to `BaseCategories`)\n| `Targets`                | Enum containing the ids of the targets available at you Cronicle server (Defaults to `BaseTargets`)\n| `Plugins`                | Interface containing mapping between plugin ids and the interface representing their required event params (Defaults to `IBasePlugins`)\n\n#### Examples\n\nExample constructor with defaults:\n```typescript\nconst scheduler = new CronicleClient({\n  masterUrl: 'http://localhost:3012',\n  apiKey: '\u003cyour api key\u003e',\n});\n```\n\nExample for setting the categories your server supports:\n```typescript\nenum Categories {\n  // Default category\n  GENERAL = 'general',\n  // Custom categories...\n  TEST_CATEGORY = 'cjw6g085901', \n  TEST_CATEGORY2 = 'cjw6l8mnb02',\n}\n```\n\nExample for setting the targets your server supports:\n```typescript\nenum Targets {\n    // Default targets...\n    ALL = 'allgrp',\n    MAIN = 'maingrp',\n    // Custom targets...\n    AWS = 'awsgrp',\n    GCP = 'gcpgrp',\n}\n```\n\nExample for setting the plugins your server supports:\n```typescript\ninterface ICustomPluginData {\n  duration: string;\n  action: string;\n}\n\ninterface Plugins {\n  // Default plugins\n  urlplug: IHttpPluginData;\n  shellplug: IShellPluginData;\n  testplug: ITestPluginData;\n  // Custom plugins\n  mycustomplug: ICustomPluginData;\n}\n```\n\nExample constructor with overrides:\n```typescript\nconst scheduler = new CronicleClient\u003cCategories, Targets, Plugins\u003e({\n  masterUrl: 'http://localhost:3012',\n  apiKey: '\u003cyour api key\u003e',\n});\n```\n\n### Timing utils\n\nTo support a wide variety of scheduling, the [timing object](https://github.com/jhuckaby/Cronicle#event-timing-object)\nan be very cumbersome...  \nTo make life easier (at least when you just want to schedule an event for a single future run) you can use the \n`getFutureTiming` and `getFutureUtcTiming` methods:\n\n--NOTICE--  \nIf you want to use the timing utils, you MUST `npm install --save moment`\n\nRunning:\n```typescript\ngetFutureUtcTiming(moment.utc('2016-05-26T14:50:50.900Z');\n```\n\nWill produce:\n```json\n{ \n  \"years\": [ 2016 ],\n  \"months\": [ 5 ],\n  \"days\": [ 26 ],\n  \"hours\": [ 14 ],\n  \"minutes\": [ 50 ]\n}\n```\n\n## Versions\n\nCronicle client supports Node 6 LTS and higher.\n\n## Contributing\n\nAll contributions are happily welcomed!  \nPlease make all pull requests to the `master` branch from your fork and ensure tests pass locally.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpruvonet%2Fcronicle-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpruvonet%2Fcronicle-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpruvonet%2Fcronicle-client/lists"}