diff --git a/CONFIGURATIONS.md b/CONFIGURATIONS.md new file mode 100644 index 0000000..b7e2aa6 --- /dev/null +++ b/CONFIGURATIONS.md @@ -0,0 +1,71 @@ +@TODO: review and update CLI parameters + +# Configuration parameters + +| PARAMETER | ALIAS | ENV/JSON | REQUIRED | DESCRIPTION | OPTIONS / EXAMPLE | +| --------- | --------------------- |---------------------- | --------- | ----------- | --------------- | +| -c | --synchronizationMode | CUSTOM_RUN | NO | Set a custom execution to run. | `splitsAndSegments` or `eventsAndImpressions` | +| -s | --wrapper | STORAGE_PATH | YES | Path to the JS file exposing the Storage API. | `path/to/storageAdapter.js` | +| -d | --debug | DEBUG | NO | Set Logger in DEBUG mode enable. | N/A | +| -k | --apikey | APIKEY | YES | Set the Split apikey. | N/A | +| -r | --sdkUrl | API_URL | NO | Set the Split API URL. | N/A | +| -e | --eventsUrl | EVENTS_API_URL | NO | Set a custom execution to run. | N/A | +| -m | --cliMode | | NO | Set where to obtain the Synchronizer configurations. If empty, it implies set via CLI arguments. | `json` or `env` | +| -p | --prefix | PREFIX | NO | Set the Storage's prefix | N/A | +| -n | --eventsPerPost | EVENTS_PER_POST | NO | Set the number of events to send in a POST request | N/A | +| -f | --impressionsPerPost | IMPRESSIONS_PER_POST | NO | Set a custom execution to run | N/A | +| -t | --maxRetries | MAX_RETRIES | NO | Set the number of retries attempt perform an Event or Impression POST request. | N/A | +| -i | --impressionsMode | IMPRESSIONS_MODE | NO | This configuration defines how impressions are queued. | `optimized` or `debug` | + +## CLI usage example +``` +splitio-node-synchronizer + --apikey + --storage /path/to/storageAdapter.js + --apiUrl https://sdk.split.io/api + --eventsApiUrl https://events.split.io/api + --prefix myStoragePrefix + --eventsPerPost 2000 + --impressionsPerPost 3000 + --impressionsMode debug + --maxRetries 5 + --debug +``` +## `env` mode usage example + +``` +splitio-node-synchronizer + --mode env + API_KEY= + STORAGE_PATH=/path/to/storageAdapter.js + API_URL=https://sdk.split.io/api + EVENTS_API_URL=https://events.split.io/api + PREFIX=myStoragePrefix + EVENTS_PER_POST=2000 + IMPRESSIONS_PER_POST=3000 + IMPRESSIONS_MODE=debug + MAX_RETRIES=5 + DEBUG=true +``` + +## `json` mode usage example + +``` +splitio-node-synchronizer --mode json --config /path/to/config.json +``` + +JSON file example: +``` +{ + "API_KEY": "", + "STORAGE_PATH": "/path/to/storageAdapter.js", + "API_URL": "https://sdk.split.io/api", + "EVENTS_API_URL": "https://events.split.io/api", + "PREFIX": "myStoragePrefix", + "EVENTS_PER_POST": 2000, + "IMPRESSIONS_PER_POST": 3000, + "IMPRESSIONS_MODE": "debug", + "MAX_RETRIES": 5, + "DEBUG": "true" +} +``` diff --git a/CONTRIBUTORS-GUIDE.md b/CONTRIBUTORS-GUIDE.md index 1b1dbc2..b86f4a7 100644 --- a/CONTRIBUTORS-GUIDE.md +++ b/CONTRIBUTORS-GUIDE.md @@ -28,6 +28,11 @@ The different builds can be generated all at once with the command `npm run buil _Note:_ In order to run build/tests commands, Node 10 or higher is required. +### Building the tools CLI + +To create the CLI that will be set as `bin` in the package, run the command `npm run build:cli`. Refer to [package.json](package.json) for more insight on the build scripts. +_Note:_ the CLI capabilities rely on [yargs](https://www.npmjs.com/package/yargs), which requires Node 12 or higher. + ### Running tests The project includes unit as well as integration tests. diff --git a/README.md b/README.md index 78da75f..79864f1 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,18 @@ This package includes a set of Javascript synchronization tools built based on t [![Twitter Follow](https://img.shields.io/twitter/follow/splitsoftware.svg?style=social&label=Follow&maxAge=1529000)](https://twitter.com/intent/follow?screen_name=splitsoftware) ## Compatibility -Split sync tools supports Node version 8 or higher. +Split sync tools supports: +- Node version 12 or higher to execute the CLI. +- Node version 8 or higher to import the package and use programmatically. ## Getting started Below is a simple example that describes the execution of the Javascript Synchronizer: +### Install package as global dependency and run CLI +1. Install npm package via `npm install -g @splitsoftware/splitio-sync-tools` +2. Then, execute the CLI `split-sync-tools [...args]` + +### Install package as a project dependency to run programmatically 1. Install npm package via `npm install @splitsoftware/splitio-sync-tools` 2. Inside your app, import the `Synchronizer` diff --git a/package.json b/package.json index aea6576..4c6e131 100644 --- a/package.json +++ b/package.json @@ -4,8 +4,12 @@ "description": "Split Javascript Sync Tools", "main": "lib/cjs/index.js", "module": "lib/esm/index.js", + "bin": { + "splitio-sync-tools": "bin/splitio-sync-tools.js" + }, "files": [ "lib", + "bin", "types", "src" ], @@ -17,9 +21,10 @@ "check": "npm run check:lint && npm run check:types", "check:lint": "eslint src --ext .js,.ts", "check:types": "tsc --noEmit", - "build": "npm run build:esm && npm run build:cjs", + "build": "npm run build:esm && npm run build:cjs && npm run build:cli", "build:esm": "rimraf lib/esm && tsc -m es2015 --outDir lib/esm --importHelpers && scripts/build_esm_replace_imports.sh && replace @VERSION@ $npm_package_version lib/esm/settings/defaults.js", "build:cjs": "rimraf lib/cjs && tsc -m CommonJS --outDir lib/cjs --importHelpers && scripts/build_cjs_replace_imports.sh && replace @VERSION@ $npm_package_version lib/cjs/settings/defaults.js", + "build:cli": "rimraf bin && rollup -c && scripts/make_cli.sh", "json-server": "node ./e2e/server/server.js", "test:unit": "jest src/", "test:e2e": "start-server-and-test 'json-server' 3000 './scripts/check_redis.sh && jest e2e/ --runInBand --forceExit'",