refactor: provide common functions and abstraction

.gitignore

@@ -20,7 +20,7 @@ coverage
 # nyc test coverage
 .nyc_output
 
-# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
 .grunt
 
 # Bower dependency directory (https://bower.io/)
@@ -29,14 +29,14 @@ bower_components
 # node-waf configuration
 .lock-wscript
 
-# Compiled binary addons (http://nodejs.org/api/addons.html)
+# Compiled binary addons (https://nodejs.org/api/addons.html)
 build/Release
 
 # Dependency directories
 node_modules/
 jspm_packages/
 
-# Typescript v1 declaration files
+# TypeScript v1 declaration files
 typings/
 
 # Optional npm cache directory
@@ -57,7 +57,30 @@ typings/
 # dotenv environment variables file
 .env
 
-# ignore IDE files
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+#DynamoDB Local files
+.dynamodb/
+
+########## end of https://github.com/github/gitignore/blob/master/Node.gitignore
+
+# ignore ide files
 .idea
 .vscode
 

.gitlab-ci.yml

@@ -3,7 +3,7 @@ image: registry.gitlab.com/openstapps/projectmanagement/node
 cache:
   key: ${CI_COMMIT_REF_SLUG}
   paths:
-  - node_modules/
+    - node_modules
 
 before_script:
   - npm install
@@ -19,9 +19,19 @@ build:
     - npm run build
 
 audit:
-  stage: test
+  allow_failure: true
+  except:
+    - schedules
   script:
     - npm audit
+  stage: test
+
+scheduled-audit:
+  only:
+    - schedules
+  script:
+    - npm audit
+  stage: test
 
 mocha:
   stage: test

.npmignore

@@ -4,6 +4,7 @@
 # Except these files/folders
 !docs
 !lib
+lib/tsconfig.tsbuildinfo
 !LICENSE
 !package.json
 !package-lock.json

README.md

@@ -2,9 +2,9 @@
 
 ## Prerequisites:
 
-*  `node` (version 10+) and `npm` installed
+* `node` (version 10 LTS) and `npm` installed
 
-* a backend, which is running locally (on http://localhost:3000) --- for testing purposes, it is advisable to use `minimal-deployment` project
+* a backend, which is running locally (on http://localhost:3000) – for testing purposes, it is advisable to use `minimal-deployment` project
 
 ## How to get started
 
@@ -20,7 +20,9 @@ npm run build
 
 To execute the code in "CLI" script (basically to execute the connector):
 ```sh
-node lib/cli.js
+node lib/cli.js run <backendURL> <origin> <licensePlate>
+e.g.:
+node lib/cli.js run http://localhost:3000 minimal-connector f-u
 ```
 
 To run some sample tests, use:
@@ -30,14 +32,38 @@ npm test
 
 The `npm` scripts are defined in `package.json` file.
 
+## Creating your own connector
+
+1. Update the `executeConnector`-function in `cli.ts` according to the comments and needs of your connector
+2. Implement the `fetchItems()` function in `MinimalConnector.ts`
+3. Test your connector in your test environment by passing the according arguments to the CLI (See execution-example above)
+
+## Next steps
+
+You may want to:
+* modify the convenience methods in the `minimal-connector/api` to your needs.
+* add additional options to your cli.
+
+Explore open source connectors from other schools to get some ideas.
+
+## Go into production
+
+1. Deploy your connector.
+2. Adjust the CLI-args to fit your production mode
+
 ## Code structure
 
-File [src/main.ts](src/index.ts) contains:
+Folder [src](src/) contains:
-* `MinimalConnector` as class with sample `getItems()` method, which simulates fetching of items from a resource and validator property which is useful for validating items against **StAppsCore**
+* Reference implementations for CLI and a connector, using the api-classes.
-* sample indexing methods: `parse`, `bulk`, `index` and `finish`
+* [/cli.ts](src/cli.ts) 
-
+  * minimal CLI to start your connector, that uses CLI-args, so that there are no hard coded values for configuration.
-File [src/cli.ts](src/cli.ts) contains:
+  * will execute the specified connectors and push the data to the backend
-* instantiation of a client
+* [/common.ts](src/api/Connector.ts)
-* calls to asynchronous indexing methods using `auto` method of `async` library
+  * `createUUID`, that will generate a unique id for a given identifying object
+  * `executeConnector`, that will execute the connector, which will fetch the items and push them to the backend 
+* [/Connector.ts](src/api/Connector.ts) abstracts the process of executing your specific connector and creating unique ids for the imported items
+* [/MinimalConnector.ts](src/MinimalConnector.ts) example connector with mock-up data
+  * shows how to instantiate things
+  * shows how to use the convenience functions
 
 File [test/MinimalConnector.spec.ts](test/MinimalConnector.spec.ts) contains sample test suite using `mocha` and `chai`.

package.json

@@ -11,41 +11,47 @@
   "contributors": [
     "Jovan Krunić <jovan.krunic@gmail.com>",
     "Karl-Philipp Wulfert <krlwlfrt@gmail.com>",
-    "Rainer Killinger <git@killinger.co>"
+    "Rainer Killinger <git@killinger.co>",
+    "Michel Jonathan Schmitz <michel.schmitz1992@gmail.com>"
   ],
   "main": "lib/cli.js",
   "types": "lib/index.d.ts",
   "scripts": {
-    "build": "npm run tslint && npm run compile && npm run documentation",
+    "build": "npm run tslint && npm run compile",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md && git commit -m 'docs: update changelog'",
     "check-configuration": "openstapps-configuration",
-    "compile": "tsc",
+    "compile": "rimraf lib && tsc && prepend lib/cli.js '#!/usr/bin/env node\n'",
-    "documentation": "typedoc --includeDeclarations --excludeExternals --mode modules --out docs src",
+    "documentation": "typedoc --includeDeclarations --mode modules --out docs --readme README.md --listInvalidSymbolLinks src",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm ci && npm run build",
     "test": "nyc mocha --require ts-node/register --require source-map-support/register --ui mocha-typescript --recursive 'test/*.spec.ts'",
     "tslint": "tslint 'src/**/*.ts'"
   },
   "dependencies": {
-    "@openstapps/api": "0.1.0",
+    "@openstapps/api": "0.7.0",
-    "@openstapps/core": "0.3.0",
+    "@openstapps/core": "0.17.0",
-    "@openstapps/logger": "0.0.5",
+    "@openstapps/logger": "0.1.0"
-    "promise-limit": "2.7.0",
-    "typescript": "3.2.2"
   },
   "devDependencies": {
-    "@openstapps/configuration": "0.5.1",
+    "@openstapps/configuration": "0.14.0",
-    "@openstapps/core-tools": "0.3.0",
+    "@openstapps/core-tools": "0.6.0",
     "@types/chai": "4.1.7",
-    "@types/mocha": "5.2.5",
+    "@types/chai-as-promised": "7.1.0",
-    "@types/node": "10.12.18",
+    "@types/mocha": "5.2.6",
+    "@types/nock": "10.0.2",
+    "@types/node": "12.0.0",
     "chai": "4.2.0",
-    "conventional-changelog-cli": "2.0.11",
+    "chai-as-promised": "7.1.1",
-    "mocha": "5.2.0",
+    "conventional-changelog-cli": "2.0.21",
+    "mocha": "6.1.4",
     "mocha-typescript": "1.1.17",
-    "nyc": "13.1.0",
+    "nock": "10.0.6",
-    "ts-node": "8.0.2",
+    "nyc": "14.1.1",
-    "tslint": "5.12.1",
+    "prepend-file-cli": "1.0.6",
-    "typedoc": "0.14.2"
+    "rimraf": "2.6.3",
+    "ts-node": "8.1.0",
+    "tslint": "5.16.0",
+    "typedoc": "0.14.2",
+    "typescript": "3.4.5"
   },
   "nyc": {
     "all": true,
@@ -69,5 +75,6 @@
       "text-summary"
     ],
     "statements": 95
-  }
+  },
+  "openstappsConfiguration": {}
 }

src/Connector.ts

@@ -0,0 +1,79 @@
+/*
+ * Copyright (C) 2019 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import {SCLicensePlate, SCThingOriginType, SCThingRemoteOrigin, SCThings} from '@openstapps/core';
+import {createUUID} from './common';
+
+/**
+ * Provides abstracted methods for the connector execution process 
+ * 
+ * By extending this class connector-developers only need to implement load and transform of the data
+ * Pushing the data to the backend will be handled automatically
+ *
+ * @typeparam T Any serializable type
+ */
+export abstract class Connector<T extends SCThings> {
+  /**
+   * License plate of the school
+   */
+  protected licensePlate: SCLicensePlate;
+  /**
+   * Name of the connector
+   */
+  public origin: string;
+
+  /**
+   * Abstract constructor for a connector 
+   * 
+   * @param licensePlate License plate of the school
+   * @param origin Name of the connector
+   */
+  constructor(licensePlate: SCLicensePlate, origin: string) {
+    this.licensePlate = licensePlate;
+    this.origin = origin;
+  }
+
+  /**
+   * Will fetch items from systems
+   *
+   * Implementation according to your schools requirements
+   */
+  protected abstract async fetchItems(): Promise<T[]>;
+
+  /**
+   * Creates a remote origin with the current date-time
+   */
+  createRemoteOrigin(): SCThingRemoteOrigin {
+    return {
+      indexed: new Date().toISOString(),
+      name: this.origin,
+      type: SCThingOriginType.Remote,
+    };
+  }
+
+  /**
+   * Fetches items and generates missing uids
+   */
+  async getItems(): Promise<T[]> {
+    const importedItems = await this.fetchItems();
+
+    for (const item of importedItems) {
+      if (item.uid.length === 0) {
+        item.uid = createUUID(item, this.licensePlate);
+      }
+    }
+
+    return importedItems;
+  }
+}

src/MinimalConnector.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright (C) 2018, 2019 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import {SCLicensePlate, SCMessage, SCThingRemoteOrigin, SCThingType} from '@openstapps/core';
+import {createUUID} from './common';
+import {Connector} from './Connector';
+
+/**
+ * Example connector
+ */
+export class MinimalConnector extends Connector<SCMessage> {
+  // for quick access to the type
+  private type: SCThingType.Message = SCThingType.Message;
+
+  /**
+   * Constructor for the MinimalConnector
+   * 
+   * @param licensePlate License plate of the school
+   * @param origin Name of the connector
+   */
+  constructor(licensePlate: SCLicensePlate, origin: string) {
+    super(licensePlate, origin);
+  }
+
+  /**
+   * Use or override the `createRemoteOrigin` method to customize the remote origin
+   */
+  private createCustomRemoteOrigin(): SCThingRemoteOrigin {
+    const customRemoteOrigin = this.createRemoteOrigin();
+    // may add a maintainer or other attributes here
+    customRemoteOrigin.url = 'http://your.backend.url';
+    return customRemoteOrigin;
+  }
+
+  /**
+   * Mock-up data
+   */
+  protected async fetchItems(): Promise<SCMessage[]> {
+    const importedItems: SCMessage[] = [
+      {
+        audiences: ['students', 'employees'],
+        description: 'Some description 1',
+        message: 'Some message 1',
+        name: 'Some name 1',
+        origin: this.createCustomRemoteOrigin(),
+        type: this.type,
+        uid: createUUID({id: 'message_1'}, this.licensePlate),
+      },
+      {
+        audiences: ['students', 'employees'],
+        description: 'Some description 2',
+        message: 'Some message 2',
+        name: 'Some name 2',
+        origin: this.createCustomRemoteOrigin(),
+        type: this.type,
+        uid: '', // see Connetor.getItems()
+      },
+      {
+        audiences: ['students', 'employees'],
+        description: 'Some description 3',
+        message: 'Some message 3',
+        name: 'Some name 3',
+        origin: this.createCustomRemoteOrigin(),
+        type: this.type,
+        uid: createUUID({id: 'message_3'}, this.licensePlate),
+      },
+    ];
+    return importedItems;
+  }
+}

src/cli.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2018-2019 StApps
+ * Copyright (C) 2018, 2019 StApps
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License as published by the Free
  * Software Foundation, version 3.
@@ -12,58 +12,49 @@
  * You should have received a copy of the GNU General Public License along with
  * this program. If not, see <https://www.gnu.org/licenses/>.
  */
-import {Bulk} from '@openstapps/api/lib/bulk';
-import {ConnectorClient as Client} from '@openstapps/api/lib/connectorClient';
-import {HttpClient} from '@openstapps/api/lib/httpClient';
-import {SCBulkAddResponse, SCMessage, SCThingType} from '@openstapps/core';
 import {Logger} from '@openstapps/logger';
-import * as promiseLimit from 'promise-limit';
+import * as commander from 'commander';
-import {MinimalConnector} from '.';
+import {readFileSync} from 'fs';
+import {join} from 'path';
+import {executeConnector, isValidSCNamespace} from './common';
+import {MinimalConnector} from './MinimalConnector';
 
-const api = new Client(new HttpClient(), 'http://localhost:3000');
+const connectorVersion = JSON.parse(
-const logger = new Logger();
+  readFileSync(join(__dirname, '..', 'package.json')).toString(),
+).version;
 
-async function runConnector() {
+process.on('unhandledRejection', (error) => {
-
+  throw error;
-  const connector = new MinimalConnector();
-  const items = await connector.getItems();
-
-  if (items.length === 0) {
-    throw new Error('No items fetched.');
-  }
-
-  let bulk: Bulk<SCMessage>;
-
-  try {
-    bulk = await api.bulk<SCMessage>(SCThingType.Message, 'minimal-connector');
-  } catch (err) {
-    logger.error('Couldn\'t open bulk.');
-    throw err;
-  }
-
-  // create a concurrency limit
-  const limit = promiseLimit<SCBulkAddResponse>(5);
-
-  try {
-    // index all items with our concurrency limit
-    await Promise.all(items.map((item) => {
-      return limit(() => bulk.add(item));
-    }));
-  } catch (err) {
-    logger.error('Error while indexing items.');
-    throw err;
-  }
-
-  try {
-    await bulk.done();
-  } catch (err) {
-    logger.error('Error while closing bulk');
-    throw err;
-  }
-}
-
-runConnector().then(() => {
-  logger.log('Done.');
-}, (err) => {
-  throw err;
 });
+
+/**
+ * Uses arguments to paramtrize the connector execution
+ */
+commander
+  .version(connectorVersion)
+  .command('run')
+  .option('-b <backend>', 'URL of the StApps backend deployment', 'http://localhost:3000')
+  .option('-o <origin>', 'Origin, where the data comes from. Typically the name of the connector', 'minimal-connector')
+  .option('-l <licensePlate>', 'The license plate of your school. Must be matched to a SCNamespace', 'f-u')
+  .action(async (backend: string, origin: string, licensePlate: string) => {
+      if (backend.length === 0) {
+        throw new Error('Param "backend" needs to have a length greater zero.');
+      }
+      const originRegex = /^[a-z\-\_0-9]*$/;
+      if (!originRegex.test(origin)) {
+        throw new Error('Origin name can only consist of lowercase letters from a-z, "-", "_" and integer numbers.');
+      }
+
+      if (!isValidSCNamespace(licensePlate)) {
+        throw new Error('Not a valid license plate. Please register a namespace with a unique-id in "core"');
+      }
+
+      // TODO for connector-developers: set your connector here
+      const connector = new MinimalConnector(licensePlate, origin);
+
+      executeConnector(backend, connector);
+      Logger.ok('Done');
+    },
+  );
+
+commander.parse(process.argv);

src/common.ts

@@ -0,0 +1,66 @@
+/*
+ * Copyright (C) 2019 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import {ConnectorClient} from '@openstapps/api/lib/connectorClient';
+import {HttpClient} from '@openstapps/api/lib/httpClient';
+import {
+  SCLicensePlate,
+  SCNamespaces,
+  SCThings,
+} from '@openstapps/core';
+import {Connector} from './Connector';
+
+/**
+ * Checks if the input is a valid SCNamespace
+ *
+ * @param input Name of the potential SCNamespace
+ */
+export function isValidSCNamespace(input: string): input is SCLicensePlate {
+  return Object.keys(SCNamespaces).indexOf(input) > 0;
+}
+
+/**
+ * Creates a uuid from a JSON stringified item identifier
+ * 
+ * You may create custom itemIdentifier-Interfaces to generate UIDs consistently
+ *
+ * @param itemIdentifier Identifying representation of the item 
+ * @param licensePlate License plate of the school
+ */
+export function createUUID(itemIdentifier: any, licensePlate: SCLicensePlate): string {
+  return ConnectorClient.makeUUID(JSON.stringify(itemIdentifier), licensePlate);
+}
+
+/**
+ * Fetches items specified by the connector and pushs them to the backend,
+ * by overwriting the bulk indexed with the `origin`.
+ *
+ * @param backend URL of the StApps backend eployment
+ * @param connector Connector to be executed
+ */
+export async function executeConnector<T extends SCThings>(
+  backend: string,
+  connector: Connector<T>,
+) {
+  const items: T[] = await connector.getItems();
+  const client: ConnectorClient = new ConnectorClient(
+    new HttpClient(),
+    backend,
+  );
+  try {
+    await client.index<T>(items, connector.origin);
+  } catch (err) {
+    throw err;
+  }
+}

src/index.ts

@@ -1,84 +0,0 @@
-/*
- * Copyright (C) 2018-2019 StApps
- * This program is free software: you can redistribute it and/or modify it
- * under the terms of the GNU General Public License as published by the Free
- * Software Foundation, version 3.
- *
- * This program is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program. If not, see <https://www.gnu.org/licenses/>.
- */
-import {ConnectorClient as Client} from '@openstapps/api/lib/connectorClient';
-import {SCMessage, SCThingOriginType, SCThingType} from '@openstapps/core';
-
-export class MinimalConnector {
-  // Data is mocked inside of getItems()
-  private items: SCMessage[] = [];
-
-  /**
-   * Provides "fetched" items (e.g. messages)
-   * 
-   * @returns {Promise<SCMessage[]>}
-   * @memberof MinimalConnector
-   */
-  async getItems(): Promise<SCMessage[]> {
-    // reset items
-    this.items.length = 0;
-
-    // sample items (messages) "fetched" from some source
-    const importedItems: SCMessage[] = [
-      {
-        audiences: ['students', 'employees'],
-        description: 'Some description 1' ,
-        message: 'Some message 1',
-        name: 'Some name 1',
-        origin: {
-          indexed: (new Date()).toISOString(),
-          name: 'minimal connector',
-          type: SCThingOriginType.Remote,
-        },
-        type: SCThingType.Message,
-        uid: '',
-      },
-      {
-        audiences: ['students', 'employees'],
-        description: 'Some description 2',
-        message: 'Some message 2',
-        name: 'Some name 2',
-        origin: {
-          indexed: (new Date()).toISOString(),
-          name: 'minimal connector',
-          type: SCThingOriginType.Remote,
-        },
-        type: SCThingType.Message,
-        uid: '',
-      },
-      {
-        audiences: ['students', 'employees'],
-        description: 'Some description 3',
-        message: 'Some message 3',
-        name: 'Some name 3',
-        origin: {
-          indexed: (new Date()).toISOString(),
-          name: 'minimal connector',
-          type: SCThingOriginType.Remote,
-        },
-        type: SCThingType.Message,
-        uid: '',
-      },
-    ];
-
-    // create a universally unique identifier for each item
-    for (const item of importedItems) {
-      // each uid is generated by a string and the namespace id of your university
-      item.uid = Client.makeUUID(JSON.stringify(item), 'f-u');
-      this.items.push(item);
-    }
-
-    return this.items;
-  }
-}

test/Connector.spec.ts

@@ -0,0 +1,45 @@
+/*
+ * Copyright (C) 2018, 2019 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import {SCThingOriginType} from '@openstapps/core';
+import {expect} from 'chai';
+import {suite, test} from 'mocha-typescript';
+import {MinimalConnector} from '../src/MinimalConnector';
+
+@suite
+export class ConnectorSpec {
+  private static connector: MinimalConnector;
+
+  static async before() {
+    this.connector = new MinimalConnector('f-u', 'minimal-connector');
+  }
+
+  @test
+  testCreateRemoteOrigin() {
+    const remoteOrigin = ConnectorSpec.connector.createRemoteOrigin();
+    expect(remoteOrigin.name).to.equal(ConnectorSpec.connector.origin);
+    expect(remoteOrigin.type).to.equal(SCThingOriginType.Remote);
+    expect(new Date().valueOf()).to.be.at.least(Date.parse(remoteOrigin.indexed).valueOf());
+  }
+
+  @test
+  async testAutomaticMissingUIDGeneration() {
+    const uuidRegExp = new RegExp('^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+    const messages = await ConnectorSpec.connector.getItems();
+    for(const message of messages){
+      expect(message.uid).to.match(uuidRegExp);
+    }
+  }
+
+}

test/MinimalConnector.spec.ts

@@ -0,0 +1,77 @@
+/*
+ * Copyright (C) 2018, 2019 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import {SCThings, SCThingType} from '@openstapps/core';
+import {Validator} from '@openstapps/core-tools/lib/validate';
+import {expect} from 'chai';
+import {suite, test} from 'mocha-typescript';
+import {join} from 'path';
+import {MinimalConnector} from '../src/MinimalConnector';
+
+@suite
+export class MinimalConnectorSpec {
+  private static connector: MinimalConnector;
+  private static validator: Validator;
+
+  static async before() {
+    this.validator = new Validator();
+    await this.validator.addSchemas(
+      join(__dirname, '..', 'node_modules', '@openstapps', 'core', 'lib', 'schema'),
+    );
+    this.connector = new MinimalConnector('f-u', 'minimal-connector');
+  }
+
+  /**
+   * Gets the `SCThingType`-key as string
+   *
+   * @param instance Contains `type` with the value of a SCThingType-key
+   */
+  static getSchemaNameFromType<T extends SCThings>(instance: T): string {
+    const type = instance.type;
+    const index = Object.values(SCThingType).indexOf(type);
+    const key = Object.keys(SCThingType)[index];
+    return `SC${key}`;
+  }
+
+  /**
+   * Checks, if the items are valid
+   *
+   * @param things Items fetched by the connector
+   */
+  static validateThings<T extends SCThings>(things: T[]) {
+    things.forEach((thing: T) => {
+      const schemaName = this.getSchemaNameFromType<T>(thing);
+      // validate thing
+      const validatorResult = MinimalConnectorSpec.validator.validate(thing, schemaName);
+      expect(validatorResult.errors).to.have.lengthOf(
+        0,
+        JSON.stringify({
+          errors: validatorResult.errors,
+          thing: thing,
+        }),
+      );
+    });
+  }
+
+  @test
+  getSampleThings() {
+    return MinimalConnectorSpec.connector
+      .getItems()
+      .then(<T extends SCThings>(items: T[]) => {
+        if (items.length > 0) {
+          MinimalConnectorSpec.validateThings(items);
+        }
+      });
+  }
+}

test/common.spec.ts

@@ -0,0 +1,94 @@
+/*
+ * Copyright (C) 2018, 2019 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import {SCThingType, SCBulkResponse, SCLicensePlate} from '@openstapps/core';
+import {expect} from 'chai';
+import {suite, test} from 'mocha-typescript';
+import {MinimalConnector} from '../src/MinimalConnector';
+import {createUUID, executeConnector, isValidSCNamespace} from '../src/common';
+import nock = require('nock');
+
+@suite
+export class CommonSpec {
+  private static connector: MinimalConnector;
+
+  static async before() {
+    this.connector = new MinimalConnector('f-u', 'minimal-connector');
+  }
+
+  @test
+  public isValidSCNamespace() {
+    const existingAddedSCLIcensePlate: SCLicensePlate = 'f-u';
+    const notASCLicensePlate: string = 'NOT-A-LICENSE';
+    const existingButUnaddedLicensePlate: SCLicensePlate = 'a-fh';
+    expect(isValidSCNamespace(existingAddedSCLIcensePlate)).to.be.equal(true);
+    expect(isValidSCNamespace(notASCLicensePlate)).to.be.equal(false);
+    expect(isValidSCNamespace(existingButUnaddedLicensePlate)).to.be.equal(false);
+  }
+
+  @test
+  testCreateUUID() {
+    const item = {
+      type: 'Not even a thing'
+    };
+    expect(createUUID(item,'f-u')).to.equal('3ac2b548-75d3-5326-920a-241e514fe445');
+    // ID was generated once before!
+  }
+
+  @test
+  async testExecuteConnector() {
+    const source = CommonSpec.connector.origin;
+
+    const bulkOpen: SCBulkResponse = {
+      source: source,
+      state: 'in progress',
+      type: SCThingType.Message,
+      uid: '744321ca-cc95-4967-b8df-42c98b792db6',
+    };
+
+    nock('http://localhost:3000')
+    .post('/bulk')
+    .reply(200, bulkOpen);
+
+    const nockBulkAdd = nock('http://localhost:3000')
+    .post('/bulk/744321ca-cc95-4967-b8df-42c98b792db6')
+    .reply(201, {})
+    .persist(); // otherwise consumed!
+
+    nock('http://localhost:3000')
+    .post('/bulk/744321ca-cc95-4967-b8df-42c98b792db6/done')
+    .reply(204, {});
+
+    // should succeed
+    expect(await CommonSpec.runExecuteConnector()).to.equal(true);
+
+    nockBulkAdd.persist(false);
+
+    // should fail due to nockBulkAdd being consumed
+    expect(await CommonSpec.runExecuteConnector()).to.equal(false);
+
+  }
+
+  /**
+   * Executes the connector
+   */
+  static async runExecuteConnector(): Promise<boolean> {
+    try{
+      await executeConnector('http://localhost:3000', CommonSpec.connector)
+      return true;
+    }catch(err){
+      return false;
+    }
+  }
+}

test/index.spec.ts

@@ -1,51 +0,0 @@
-/*
- * Copyright (C) 2018-2019 StApps
- * This program is free software: you can redistribute it and/or modify it
- * under the terms of the GNU General Public License as published by the Free
- * Software Foundation, version 3.
- *
- * This program is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program. If not, see <https://www.gnu.org/licenses/>.
- */
-import {SCThings} from '@openstapps/core';
-import {Validator} from '@openstapps/core-tools/lib/validate';
-import {expect} from 'chai';
-import {suite, test} from 'mocha-typescript';
-import {MinimalConnector} from '../src';
-
-@suite
-export class MinimalConnectorSpec {
-
-  private static connector: MinimalConnector;
-  private static validator: Validator;
-
-  static async before() {
-    this.validator = new Validator();
-    await this.validator.addSchemas('./node_modules/@openstapps/core/lib/schema');
-    this.connector = new MinimalConnector();
-  }
-
-   static validateThings(things: SCThings[]) {
-    things.forEach((thing: SCThings) => {
-      // validate thing
-      expect(MinimalConnectorSpec.validator.validateThing(thing).errors).to.have.lengthOf(0, JSON.stringify({
-        errors: MinimalConnectorSpec.validator.validateThing(thing).errors,
-        thing: thing,
-      }));
-    });
-  }
-
-  @test
-  getSampleThings() {
-    return MinimalConnectorSpec.connector.getItems().then(<T extends SCThings>(items: T[]) => {
-      if (items.length > 0) {
-        MinimalConnectorSpec.validateThings(items);
-      }
-    });
-  }
-}