@commercelayer/cli-plugin-metrics 1.0.0 → 1.0.2

package/README.md

@@ -1 +1,210 @@
-# commercelayer-cli-plugin-links
+# @commercelayer/cli-plugin-metrics
+
+Commerce Layer CLI Metrics plugin
+
+[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
+[![Version](https://img.shields.io/npm/v/@commercelayer/cli-plugin-metrics.svg)](https://npmjs.org/package/@commercelayer/cli-plugin-metrics)
+[![Downloads/week](https://img.shields.io/npm/dw/@commercelayer/cli-plugin-metrics.svg)](https://npmjs.org/package/@commercelayer/cli-plugin-metrics)
+[![License](https://img.shields.io/npm/l/@commercelayer/cli-plugin-metrics.svg)](https://github.com/@commercelayer/cli-plugin-metrics/blob/master/package.json)
+
+<!-- toc -->
+
+* [Usage](#usage)
+* [Commands](#commands)
+<!-- tocstop -->
+## Usage
+<!-- usage -->
+
+```sh-session
+commercelayer COMMAND
+
+commercelayer [COMMAND] (--help | -h) for detailed information about plugin commands.
+```
+<!-- usagestop -->
+## Commands
+<!-- commands -->
+
+* [`commercelayer metrics:breakdown RESOURCE`](#commercelayer-metricsbreakdown-resource)
+* [`commercelayer metrics:date_breakdown RESOURCE`](#commercelayer-metricsdate_breakdown-resource)
+* [`commercelayer metrics:fbt`](#commercelayer-metricsfbt)
+* [`commercelayer metrics:search RESOURCE`](#commercelayer-metricssearch-resource)
+* [`commercelayer metrics:stats RESOURCE`](#commercelayer-metricsstats-resource)
+
+### `commercelayer metrics:breakdown RESOURCE`
+
+Perform a breakdown query on the Metrics API endpoint.
+
+```sh-session
+USAGE
+  $ commercelayer metrics:breakdown RESOURCE -b <value> -f <value> -O
+    avg|cardinality|max|min|percentiles|stats|sum|value_count [-F <value>] [-B <value>] [-c <value>] [-s asc|desc] [-l
+    <value>]
+
+FLAGS
+  -B, --breakdown=<value>  the optional nested breakdown
+  -F, --filter=<value>     the filter to apply to the query in JSON format (enclosed in single quotes)
+  -O, --operator=<option>  (required) the computing operator
+                           <options: avg|cardinality|max|min|percentiles|stats|sum|value_count>
+  -b, --by=<value>         (required) the field you want the results of the query aggragated by
+  -c, --condition=<value>  an additional constraint to fine-tune the set of records
+  -f, --field=<value>      (required) the field you want the metrics or statistics computed on
+  -l, --limit=<value>      the maximum number of records shown in the response
+  -s, --sort=<option>      the way you want the results of the query to be sorted
+                           <options: asc|desc>
+
+DESCRIPTION
+  perform a breakdown query on the Metrics API endpoint
+
+ALIASES
+  $ commercelayer metrics:break
+  $ commercelayer breakdown
+
+EXAMPLES
+  $ commercelayer metrics:breakdown orders -b order.country_code -f order.id -O value_count -s desc -l 20
+
+  cl breakdown orders -b order.country_code -f order.id -O value_count -s desc -l 20 -B '{"by": "line_items.name","field": "line_items.id","operator": "value_count","sort": "desc","limit": 20}'
+
+FLAG DESCRIPTIONS
+  -B, --breakdown=<value>  the optional nested breakdown
+
+    a JSON object (enclosed in single quotes) containing the nested breakdown
+
+  -O, --operator=avg|cardinality|max|min|percentiles|stats|sum|value_count  the computing operator
+
+    the list of valid operators depends on the value of the field key
+
+  -c, --condition=<value>  an additional constraint to fine-tune the set of records
+
+    the condition is applied to the computed results of the query and it is available for operators that return single
+    numeric (float or integer) values.
+```
+
+_See code: [src/commands/metrics/breakdown.ts](https://github.com/commercelayer/commercelayer-cli-plugin-metrics/blob/main/src/commands/metrics/breakdown.ts)_
+
+### `commercelayer metrics:date_breakdown RESOURCE`
+
+Perform a date breakdown query on the Metrics API endpoint.
+
+```sh-session
+USAGE
+  $ commercelayer metrics:date_breakdown RESOURCE -b <value> -f <value> -O
+    avg|cardinality|max|min|percentiles|stats|sum|value_count [-F <value>] [-B <value>] [-i hour|day|week|month|year]
+
+FLAGS
+  -B, --breakdown=<value>  the optional nested breakdown
+  -F, --filter=<value>     the filter to apply to the query in JSON format (enclosed in single quotes)
+  -O, --operator=<option>  (required) the computing operator
+                           <options: avg|cardinality|max|min|percentiles|stats|sum|value_count>
+  -b, --by=<value>         (required) the field you want the results of the query aggragated by
+  -f, --field=<value>      (required) the field you want the metrics or statistics computed on
+  -i, --interval=<option>  the time interval over which the metrics are computed
+                           <options: hour|day|week|month|year>
+
+DESCRIPTION
+  perform a date breakdown query on the Metrics API endpoint
+
+ALIASES
+  $ commercelayer metrics:breakdate
+  $ commercelayer metrics:date
+  $ commercelayer breakdate
+  $ commercelayer date_breakdown
+
+EXAMPLES
+  $ commercelayer metrics:date_breakdown orders -b order.placed_at -f order.total_amount_with_taxes -O stats -i month
+
+FLAG DESCRIPTIONS
+  -B, --breakdown=<value>  the optional nested breakdown
+
+    a JSON object (enclosed in single quotes) containing the nested breakdown
+
+  -O, --operator=avg|cardinality|max|min|percentiles|stats|sum|value_count  the computing operator
+
+    the list of valid operators depends on the value of the field key
+```
+
+_See code: [src/commands/metrics/date_breakdown.ts](https://github.com/commercelayer/commercelayer-cli-plugin-metrics/blob/main/src/commands/metrics/date_breakdown.ts)_
+
+### `commercelayer metrics:fbt`
+
+Perform a Frequently Bought Together query on the Metrics API analysis endpoint.
+
+```sh-session
+USAGE
+  $ commercelayer metrics:fbt [-F <value>] [-i <value>...]
+
+FLAGS
+  -F, --filter=<value>  the filter to apply to the query in JSON format (enclosed in single quotes)
+  -i, --in=<value>...   a list of SKU or bundle IDs associated as line items to one or more orders
+
+DESCRIPTION
+  perform a Frequently Bought Together query on the Metrics API analysis endpoint
+
+ALIASES
+  $ commercelayer fbt
+
+EXAMPLES
+  $ commercelayer metrics:fbt --in xYZkjABcde,yzXKjYzaCx
+```
+
+_See code: [src/commands/metrics/fbt.ts](https://github.com/commercelayer/commercelayer-cli-plugin-metrics/blob/main/src/commands/metrics/fbt.ts)_
+
+### `commercelayer metrics:search RESOURCE`
+
+Perform a search query on the Metrics API endpoint.
+
+```sh-session
+USAGE
+  $ commercelayer metrics:search RESOURCE -f <value>... [-F <value>] [-l <value>] [-s asc|desc -b <value>] [-c
+    <value>]
+
+FLAGS
+  -F, --filter=<value>     the filter to apply to the query in JSON format (enclosed in single quotes)
+  -b, --sort_by=<value>    the date field you want the results of the query sorted by
+  -c, --cursor=<value>     the cursor pointing to a specific page in the paginated search results
+  -f, --fields=<value>...  (required) comma-separated list of fields you want to be returned for each record in the
+                           response
+  -l, --limit=<value>      the maximum number of records shown in the response
+  -s, --sort=<option>      the way you want the results of the query to be sorted
+                           <options: asc|desc>
+
+DESCRIPTION
+  perform a search query on the Metrics API endpoint
+
+ALIASES
+  $ commercelayer search
+
+EXAMPLES
+  commercelayewr metrics:search orders -l 5 -s asc -b order.placed_at -f order.id,order.number,order.placed_at,customer.email
+```
+
+_See code: [src/commands/metrics/search.ts](https://github.com/commercelayer/commercelayer-cli-plugin-metrics/blob/main/src/commands/metrics/search.ts)_
+
+### `commercelayer metrics:stats RESOURCE`
+
+Perform a stats query on the Metrics API endpoint.
+
+```sh-session
+USAGE
+  $ commercelayer metrics:stats RESOURCE -f <value> -O avg|cardinality|max|min|percentiles|stats|sum|value_count
+    [-F <value>]
+
+FLAGS
+  -F, --filter=<value>     the filter to apply to the query in JSON format (enclosed in single quotes)
+  -O, --operator=<option>  (required) the computing operator
+                           <options: avg|cardinality|max|min|percentiles|stats|sum|value_count>
+  -f, --field=<value>      (required) the field you want the metrics or statistics computed on
+
+DESCRIPTION
+  perform a stats query on the Metrics API endpoint
+
+ALIASES
+  $ commercelayer stats
+
+EXAMPLES
+  $ commercelayer metrics:stats orders -f order.total_amount_with_taxes --op avg
+
+  cl stats orders -f order.total_amount_with_taxes -O stats
+```
+
+_See code: [src/commands/metrics/stats.ts](https://github.com/commercelayer/commercelayer-cli-plugin-metrics/blob/main/src/commands/metrics/stats.ts)_
+<!-- commandsstop -->

package/lib/base.d.ts

@@ -15,7 +15,16 @@ export declare abstract class BaseCommand extends Command {
     protected multivalFlag(flag?: string[]): string[];
     protected printResponse(response: Response): Promise<void>;
 }
-export declare abstract class BaseResourceCommand extends BaseCommand {
+export declare abstract class BaseFilterCommand extends BaseCommand {
+    static baseFlags: {
+        filter: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        organization: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        domain: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        accessToken: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    protected filterFlag(flag?: string): MetricsFilter | undefined;
+}
+export declare abstract class BaseResourceCommand extends BaseFilterCommand {
     static baseFlags: {
         filter: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         organization: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
@@ -25,7 +34,6 @@ export declare abstract class BaseResourceCommand extends BaseCommand {
     static args: {
         resource: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
     };
-    protected filterFlag(flag?: string): MetricsFilter | undefined;
 }
 export declare abstract class BaseBreakdownCommand extends BaseResourceCommand {
     static baseFlags: {

package/lib/base.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Flags = exports.Args = exports.BaseBreakdownCommand = exports.BaseResourceCommand = exports.BaseCommand = void 0;
+exports.Flags = exports.Args = exports.BaseBreakdownCommand = exports.BaseResourceCommand = exports.BaseFilterCommand = exports.BaseCommand = void 0;
 const tslib_1 = require("tslib");
 const sdk_1 = tslib_1.__importStar(require("@commercelayer/sdk"));
 const core_1 = require("@oclif/core");
@@ -99,7 +99,7 @@ class BaseCommand extends core_1.Command {
     }
 }
 exports.BaseCommand = BaseCommand;
-class BaseResourceCommand extends BaseCommand {
+class BaseFilterCommand extends BaseCommand {
     static baseFlags = {
         ...BaseCommand.baseFlags,
         filter: core_1.Flags.string({
@@ -107,9 +107,6 @@ class BaseResourceCommand extends BaseCommand {
             description: 'the filter to apply to the query in JSON format (enclosed in single quotes)'
         })
     };
-    static args = {
-        resource: core_1.Args.string({ resource: 'the resource name', options: common_1.resources, required: true })
-    };
     filterFlag(flag) {
         let filter;
         if (flag) {
@@ -123,6 +120,15 @@ class BaseResourceCommand extends BaseCommand {
         return filter;
     }
 }
+exports.BaseFilterCommand = BaseFilterCommand;
+class BaseResourceCommand extends BaseFilterCommand {
+    static baseFlags = {
+        ...BaseFilterCommand.baseFlags
+    };
+    static args = {
+        resource: core_1.Args.string({ resource: 'the resource name', options: common_1.resources, required: true })
+    };
+}
 exports.BaseResourceCommand = BaseResourceCommand;
 class BaseBreakdownCommand extends BaseResourceCommand {
     static baseFlags = {

package/lib/commands/metrics/fbt.d.ts

@@ -1,11 +1,11 @@
-import { BaseCommand } from '../../base';
-export default class MetricsFbt extends BaseCommand {
+import { BaseFilterCommand } from '../../base';
+export default class MetricsFbt extends BaseFilterCommand {
     static operation: string;
     static aliases: string[];
     static description: string;
     static examples: string[];
     static flags: {
-        in: import("@oclif/core/lib/interfaces").OptionFlag<string[], import("@oclif/core/lib/interfaces").CustomOptions>;
+        in: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/lib/commands/metrics/fbt.js

@@ -6,7 +6,7 @@ const base_1 = require("../../base");
 const request_1 = require("../../request");
 const cli_core_1 = require("@commercelayer/cli-core");
 const cliux = tslib_1.__importStar(require("@commercelayer/cli-ux"));
-class MetricsFbt extends base_1.BaseCommand {
+class MetricsFbt extends base_1.BaseFilterCommand {
     static operation = 'fbt';
     static aliases = [MetricsFbt.operation];
     static description = 'perform a Frequently Bought Together query on the Metrics API analysis endpoint';
@@ -17,23 +17,28 @@ class MetricsFbt extends base_1.BaseCommand {
         in: core_1.Flags.string({
             char: 'i',
             description: 'a list of SKU or bundle IDs associated as line items to one or more orders',
-            required: true,
-            multiple: true
+            required: false,
+            multiple: true,
+            relationships: [
+                { type: 'some', flags: ['in', 'filter'] }
+            ],
         })
     };
     async run() {
         const { flags } = await this.parse(MetricsFbt);
         this.checkAcessTokenData(flags.accessToken, flags);
         const ids = this.multivalFlag(flags.in);
-        const query = {
+        const filterObject = this.filterFlag(flags.filter);
+        const query = (ids.length > 0) ? {
             filter: {
+                ...filterObject,
                 line_items: {
                     item_ids: {
                         in: ids
                     }
                 }
             }
-        };
+        } : {};
         const response = await (0, request_1.metricsRequest)(MetricsFbt.operation, query, undefined, flags);
         if (response.ok) {
             cliux.action.stop(cli_core_1.clColor.msg.success('Done'));

package/lib/common.d.ts

@@ -101,7 +101,7 @@ export type MetricsFilterFbt = {
     };
 };
 export type MetricsQueryFbt = {
-    filter: MetricsFilterFbt;
+    filter?: MetricsFilterFbt;
 };
 export type MetricsQuery = (({
     search: MetricsQuerySearch;

package/oclif.manifest.json

@@ -365,11 +365,28 @@
           "multiple": false,
           "type": "option"
         },
+        "filter": {
+          "char": "F",
+          "description": "the filter to apply to the query in JSON format (enclosed in single quotes)",
+          "name": "filter",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "in": {
           "char": "i",
           "description": "a list of SKU or bundle IDs associated as line items to one or more orders",
           "name": "in",
-          "required": true,
+          "relationships": [
+            {
+              "type": "some",
+              "flags": [
+                "in",
+                "filter"
+              ]
+            }
+          ],
+          "required": false,
           "hasDynamicHelp": false,
           "multiple": true,
           "type": "option"
@@ -670,5 +687,5 @@
       ]
     }
   },
-  "version": "1.0.0"
+  "version": "1.0.2"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@commercelayer/cli-plugin-metrics",
   "description": "Commerce Layer CLI metrics plugin",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "author": "Pierluigi Viti <pierluigi@commercelayer.io>",
   "bugs": "https://github.com/commercelayer/commercelayer-cli-plugin-metrics/issues",
   "engines": {
@@ -62,22 +62,21 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/chai": "^4.3.20",
-    "@types/lodash.isempty": "^4.4.9",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^22.15.18",
+    "@types/node": "^22.15.24",
     "chai": "^4.5.0",
     "eslint": "^8.57.1",
     "mocha": "^10.8.2",
     "nyc": "^15.1.0",
     "oclif": "^4.17.46",
-    "semantic-release": "^24.2.3",
+    "semantic-release": "^24.2.5",
     "tsx": "^4.19.4",
     "typescript": "5.5.2"
   },
   "dependencies": {
     "@commercelayer/cli-core": "^5.9.0",
     "@commercelayer/cli-ux": "^1.0.7",
-    "@commercelayer/sdk": "^6.41.0",
+    "@commercelayer/sdk": "^6.42.0",
     "@oclif/core": "^3.27.0",
     "tslib": "^2.8.1"
   },