fiftyone.pipeline.engines.fiftyone 4.4.99 → 4.4.101

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiftyone.pipeline.engines.fiftyone",
-  "version": "4.4.99",
+  "version": "4.4.101",
   "description": "Shared base functions for implementing 51Degrees engines for the 51Degrees Pipeline API",
   "keywords": [
     "51degrees",
@@ -9,6 +9,7 @@
     "service"
   ],
   "main": "index.js",
+  "types": "types/index.d.ts",
   "directories": {
     "test": "tests"
   },
@@ -21,7 +22,10 @@
     "fiftyone.pipeline.engines": "4.4.x"
   },
   "devDependencies": {
-    "jest": "^27.5.1"
+    "@types/jest": "^27.5.2",
+    "@types/node": "^20.14.10",
+    "jest": "^27.5.1",
+    "typescript": "^5.5.3"
   },
   "license": "EUPL-1.2",
   "bugs": {

package/shareUsage.js

@@ -1,23 +1,23 @@
-/* *********************************************************************
- * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
- * Copyright 2023 51 Degrees Mobile Experts Limited, Davidson House,
- * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
- *
- * This Original Work is licensed under the European Union Public Licence
- * (EUPL) v.1.2 and is subject to its terms as set out below.
- *
- * If a copy of the EUPL was not distributed with this file, You can obtain
- * one at https://opensource.org/licenses/EUPL-1.2.
- *
- * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
- * amended by the European Commission) shall be deemed incompatible for
- * the purposes of the Work and the provisions of the compatibility
- * clause in Article 5 of the EUPL shall not apply.
- *
- * If using the Work as, or as part of, a network application, by
- * including the attribution notice(s) required under Article 5 of the EUPL
- * in the end user terms of the application under an appropriate heading,
- * such notice(s) shall fulfill the requirements of that article.
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2023 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
  * ********************************************************************* */
 
 const engines = require('fiftyone.pipeline.engines');
@@ -40,6 +40,7 @@ const SHARE_USAGE_VERSION = '1.1';
 
 /**
  * @typedef {import('fiftyone.pipeline.core').FlowData} FlowData
+ * @typedef {import('fiftyone.pipeline.core').FlowElement} FlowElement
  */
 
 /**
@@ -317,6 +318,10 @@ class ShareUsage extends Engine {
    */
   getFlowElements () {
     if (!this.flowElements) {
+      /**
+       * @type {Array<FlowElement>}
+       */
+      this.flowElements = [];
       if (this.pipelines.length === 1) {
         const list = [];
         for (const [, value] of Object.entries(this.pipelines[0].flowElements)) {
@@ -330,9 +335,8 @@ class ShareUsage extends Engine {
         // make up the pipeline so a warning is logged
         // but otherwise, the system can continue as normal.
         this._log('warn', 'Share usage element registered ' +
-                    `to ${this.pipelines.length > 0 ? 'too many' : 'no'}` +
-                    ' pipelines. Unable to send share usage information.');
-        this.flowElements = [];
+          `to ${this.pipelines.length > 0 ? 'too many' : 'no'}` +
+          ' pipelines. Unable to send share usage information.');
       }
     }
     return this.flowElements;
@@ -402,6 +406,12 @@ class ShareUsageData {
     this.sequence = '';
   }
 
+  /**
+   * Try to add data to shared usage
+   *
+   * @param {string} key key to add by
+   * @param {*} value value to add
+   */
   tryAddToData (key, value) {
     // Get the category and field names from the evidence key.
     let category = '';

package/shareUsageTracker.js

@@ -1,23 +1,23 @@
-/* *********************************************************************
- * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
- * Copyright 2023 51 Degrees Mobile Experts Limited, Davidson House,
- * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
- *
- * This Original Work is licensed under the European Union Public Licence
- * (EUPL) v.1.2 and is subject to its terms as set out below.
- *
- * If a copy of the EUPL was not distributed with this file, You can obtain
- * one at https://opensource.org/licenses/EUPL-1.2.
- *
- * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
- * amended by the European Commission) shall be deemed incompatible for
- * the purposes of the Work and the provisions of the compatibility
- * clause in Article 5 of the EUPL shall not apply.
- *
- * If using the Work as, or as part of, a network application, by
- * including the attribution notice(s) required under Article 5 of the EUPL
- * in the end user terms of the application under an appropriate heading,
- * such notice(s) shall fulfill the requirements of that article.
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2023 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
  * ********************************************************************* */
 
 const engines = require('fiftyone.pipeline.engines');
@@ -50,7 +50,7 @@ class ShareUsageTracker extends Tracker {
    * Function to check if we should put the evidence in the cache
    *
    * @param {string} key key of piece of evidence
-   * @param {mixed} value value of piece of evidence
+   * @param {*} value value of piece of evidence
    * @returns {boolean} whether put in cache
    **/
   match (key, value) {
@@ -69,7 +69,7 @@ class ShareUsageTracker extends Tracker {
    * Retreive entry from cache
    *
    * @param {object} cacheKey key value store of evidence to lookup
-   * @returns {mixed} value stored in cache
+   * @returns {*} value stored in cache
    **/
   get (cacheKey) {
     return this.cache.read(cacheKey);

package/tsconfig.json

@@ -1,21 +1,22 @@
 {
-    // Change this to match your project
-    "include": ["*"],
-    "compilerOptions": {
-      // Tells TypeScript to read JS files, as
-      // normally they are ignored as source files
-      "allowJs": true,
-      // Generate d.ts files
-      "declaration": true,
-      // This compiler run should
-      // only output d.ts files
-      "emitDeclarationOnly": true,
-      // Types should go into this directory.
-      // Removing this would place the .d.ts files
-      // next to the .js files
-      "outDir": "types",
-      "lib": ["ES2015"],
-      "moduleResolution": "Node",
-      "noImplicitAny": true
-    }
-  }
+  // Change this to match your project
+  "include": ["*"],
+  "exclude": ["node_modules"],
+  "compilerOptions": {
+    // Tells TypeScript to read JS files, as
+    // normally they are ignored as source files
+    "allowJs": true,
+    // Generate d.ts files
+    "declaration": true,
+    // This compiler run should
+    // only output d.ts files
+    "emitDeclarationOnly": true,
+    // Types should go into this directory.
+    // Removing this would place the .d.ts files
+    // next to the .js files
+    "outDir": "types",
+    "lib": ["ES2015"],
+    "moduleResolution": "Node",
+    "noImplicitAny": true
+  }
+}

package/types/index.d.ts

@@ -1 +1 @@
-export const ShareUsage: typeof import("./shareUsage");
+export let ShareUsage: typeof import("./shareUsage");

package/types/shareUsage.d.ts

@@ -2,6 +2,7 @@ export = ShareUsage;
 declare const ShareUsage_base: typeof import("fiftyone.pipeline.engines/types/engine");
 /**
  * @typedef {import('fiftyone.pipeline.core').FlowData} FlowData
+ * @typedef {import('fiftyone.pipeline.core').FlowElement} FlowElement
  */
 /**
  * The ShareUsage element sends usage data to 51Degrees in zipped batches
@@ -10,44 +11,114 @@ declare class ShareUsage extends ShareUsage_base {
     /**
      * Constructor for ShareUsage engine
      *
-     * @param {object} options settings object for shareusage
-     * @param {number} options.interval how often to send
-     * @param {number} options.requestedPackageSize how many items
-     * in one zipped packaged
-     * @param {string} options.cookie which cookie is used to track evidence
-     * @param {Array} options.queryWhitelist list of query string
-     * whitelist evidence to keep
-     * @param {Array} options.headerBlacklist list of header evidence to exclude
-     * @param {number} options.sharePercentage percentage of requests to share
-     */
-    constructor({ interval, requestedPackageSize, cookie, queryWhitelist, headerBlacklist, sharePercentage }?: {
+     * @param {object} options settings object for share usage.
+     * @param {number} options.interval If exactly the same evidence values
+     * are seen multiple times within this time limit (in milliseconds) then
+     * they will only be shared once.
+     * @param {number} options.requestedPackageSize The usage element
+     * will group data into single requests before sending it.
+     * This setting controls the minimum number of entries before
+     * data is sent.
+     * If you are sharing large amounts of data, increasing this value
+     * is recommended in order to reduce the overhead of sending HTTP
+     * messages.
+     * For example, the 51Degrees cloud service uses a value of 2500.
+     * @param {string} options.cookie if a cookie is being used to identify
+     * user sessions, it can be specified here in order to reduce the
+     * sharing of duplicated data.
+     * @param {Array} options.queryWhitelist By default query string
+     * and HTTP form parameters are not shared unless prefixed with '51D_'.
+     * If you need to share query string parameters, a list can be
+     * specified here.
+     * @param {Array} options.headerBlacklist By default, all HTTP headers
+     * (except a few, such as Cookies) are shared. Individual headers can
+     * be excluded from sharing by adding them to this list.
+     * @param {number} options.sharePercentage approximate proportion of
+     * requests to be shared. 1 = 100%, 0.5 = 50%, etc..
+     * @param {string} options.endpoint The target destination for usage
+     * sharing data. The default is https://devices-v4.51degrees.com/new.ashx.
+     */
+    constructor({ interval, requestedPackageSize, cookie, queryWhitelist, headerBlacklist, sharePercentage, endpoint }?: {
         interval: number;
         requestedPackageSize: number;
         cookie: string;
         queryWhitelist: any[];
         headerBlacklist: any[];
         sharePercentage: number;
+        endpoint: string;
     }, ...args: any[]);
     trackingCookie: string;
+    evidenceKeyFilter: ShareUsageEvidenceKeyFilter;
     tracker: ShareUsageTracker;
     requestedPackageSize: number;
     sharePercentage: number;
-    sharePercentageCounter: number;
     shareData: any[];
+    endpoint: url.URL;
+    http: typeof import("http") | typeof import("https");
+    /**
+     * Internal process method which uses the ShareUsageTracker
+     * to determine whether to add usage data to a batch and adds it if necessary.
+     *
+     * @param {FlowData} flowData flowData to process
+     */
+    processInternal(flowData: FlowData): void;
+    /**
+     * Creates a ShareUsageData instance populated from the evidence
+     * within the flow data provided.
+     *
+     * @param {FlowData} flowData the flow data containing the evidence to use
+     * @returns {ShareUsageData} New ShareUsageData instance, populated from the evidence
+     * provided
+     */
+    getDataFromEvidence(flowData: FlowData): ShareUsageData;
+    getConstantXml(): string;
+    constantXml: string;
     /**
      * Internal method which adds to the share usage bundle (generating XML)
      *
-     * @param {object} key key value store of current
+     * @param {object} data key value store of current
      * evidence in FlowData (filtered by the ShareUsageEvidenceKeyFilter)
      */
-    addToShareUsage(key: object): void;
+    addToShareUsage(data: object): void;
     /**
      * Internal method to send the share usage bundle to the 51Degrees servers
      */
     sendShareUsage(): void;
+    /**
+     * Return a list of FlowElements in the pipeline.
+     * If the list is null then populate from the pipeline.
+     * If there are multiple or no pipelines then log an error.
+     *
+     * @returns {Array<FlowElement>} list of flow elements
+     */
+    getFlowElements(): Array<FlowElement>;
+    /**
+     * @type {Array<FlowElement>}
+     */
+    flowElements: Array<FlowElement>;
 }
 declare namespace ShareUsage {
-    export { FlowData };
+    export { FlowData, FlowElement };
 }
+import ShareUsageEvidenceKeyFilter = require("./shareUsageEvidenceKeyFilter");
 import ShareUsageTracker = require("./shareUsageTracker");
+import url = require("url");
+/**
+ * Internal class that is used to store details of data in memory
+ * prior to it being sent to 51Degrees.
+ */
+declare class ShareUsageData {
+    evidenceData: {};
+    sessionId: string;
+    clientIp: string;
+    sequence: string;
+    /**
+     * Try to add data to shared usage
+     *
+     * @param {string} key key to add by
+     * @param {*} value value to add
+     */
+    tryAddToData(key: string, value: any): void;
+}
 type FlowData = import("fiftyone.pipeline.core/types/flowData");
+type FlowElement = import("fiftyone.pipeline.core/types/flowElement");

package/types/shareUsageEvidenceKeyFilter.d.ts

@@ -20,7 +20,8 @@ declare class ShareUsageEvidenceKeyFilter extends ShareUsageEvidenceKeyFilter_ba
         queryWhitelist: any[];
         headerBlacklist: any[];
     }, ...args: any[]);
-    queryWhitelist: any[];
-    headerBlacklist: any[];
+    includedQueryStringParams: any[];
+    blockedHttpHeaders: any[];
     cookie: string;
+    shareAll: boolean;
 }

package/types/shareUsageTracker.d.ts

@@ -11,7 +11,7 @@ declare class ShareUsageTracker extends ShareUsageTracker_base {
      *
      * @param {object} options options for share usage tracker
      * @param {number} options.size size of the share usage lru cache
-     * @param {number} options.interval how often to put evidence into the cache
+     * @param {number} options.interval if identical evidence values are seen by the tracker within this interval (in milliseconds) it will be ignored by the tracker.
      **/
     constructor({ size, interval }?: {
         size: number;
@@ -19,4 +19,18 @@ declare class ShareUsageTracker extends ShareUsageTracker_base {
     }, ...args: any[]);
     cache: import("fiftyone.pipeline.engines/types/lru");
     interval: number;
+    /**
+     * Retreive entry from cache
+     *
+     * @param {object} cacheKey key value store of evidence to lookup
+     * @returns {*} value stored in cache
+     **/
+    get(cacheKey: object): any;
+    /**
+     * Put entry in cache
+     *
+     * @param {object} cacheKey key value store of evidence
+     * to place in cache
+     **/
+    put(cacheKey: object): void;
 }