@adobe/exc-app 0.2.45 → 1.0.0

package/metrics/Application.ts

@@ -1,24 +0,0 @@
-/*************************************************************************
- * Copyright 2021 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * @ignore
- */
-export interface Application {
-  id: string;         // an identifier for the applicaton executable
-  name?: string;      // human-readable application title
-  solution?: {
-    id: string;       // an identifier for the solution/subapplication
-    name?: string;    // a human-reacable solution title
-    version?: string; // solution build version
-  };
-  version?: string;   // build version string
-}

package/metrics/Configuration.ts

@@ -1,33 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * @ignore
- */
-export default interface Configuration {
-    apiKey?: string;
-    analytics?: {
-        script: string;
-        solution: string;
-        version?: string;
-    };
-    application?: {
-        id: string;
-        version?: string;
-    },
-    batch?: boolean;
-    deviceId?: string;
-    environment?: string;
-    instanceId?: string;
-    maxPayloadSize?: number;
-    mode?: string;
-    user?: any;
-}

package/metrics/Events.ts

@@ -1,28 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * @packageDocumentation
- * @module metrics
- */
-
-/**
- * Named events in loading lifecycle
- */
-/**
- * @ignore
- */
-export enum Events {
-  PAGE_LOAD_DONE= 'exc.metrics.pageState.load.done',
-  PAGE_LOAD_START= 'exc.metrics.pageState.load.start',
-  SPINNER_DONE = 'exc.metrics.pageState.spinner.done',
-  SPINNER_START= 'exc.metrics.pageState.spinner.start'
-}

package/metrics/History.ts

@@ -1,36 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * @packageDocumentation
- * @module metrics
- */
-
-/**
- * Defines APIs used to log history events.
- */
-export default interface History {
-  /**
-   * Records a history replace event.
-   * @param path The current URL.
-   * @param state Optional. The state associated to the event.
-   * @param data Additional data associated to the event.
-   */
-  replace(path: string, state?: any, ...args: any): void;
-
-  /**
-   * Records a history push event.
-   * @param path The current URL.
-   * @param state Optional. The state associated to the event.
-   * @param data Additional data associated to the event.
-   */
-  push(path: string, state?: any, ...args: any): void;
-}

package/metrics/Metric.ts

@@ -1,52 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * @packageDocumentation
- * @module metrics
- */
-
-import {Level} from './Level';
-
-/**
- * Defines the attribute of a metric to be logged.
- */
-export default interface Metric {
-  /**
-   * A long integer storage column, e.g. the value when recordType = Counter.
-   */
-  counter?: number;
-
-  /**
-   * An opaque (to Metrics) object for application storage.
-   */
-  data?: any;
-
-  /**
-   * An application-defined event.
-   */
-  event?: string | string[];
-
-  /**
-   * The importance of this metric, e.g. log level.
-   */
-  level?: Level;
-
-  /**
-   * A human-readable message, e.g. console messages.
-   */
-  message?: string;
-
-  /**
-   * The type of this metric record, may be application-specific.
-   */
-  recordType?: string;
-}

package/metrics/Metrics.ts

@@ -1,129 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * @packageDocumentation
- * @module metrics
- */
-
-import Analytics from './Analytics';
-import History from './History';
-import Metric from './Metric';
-
-/**
- * Defines APIs on a timer.
- */
-export interface Timer {
-  /**
-   * Records the elapsed time from when the timer was created by calling Metrics.start API.
-   * @param event The name of the event being logged. The `{event: string}` form of this argument
-   * can be used to specify the precise event name that should be recorded (the prefix supplied
-   * at construction time is ignored).
-   * @returns The elapsed time since the timer started, in milliseconds.
-   */
-  time(event: string | {event: string}, ...args: any): number;
-}
-
-/**
- * Defines metrics APIs.
- */
-export default interface Metrics {
-  /**
-   * The Analytics APIs are designed to mirror the Omega APIs, enabling an Analtyics record to be
-   * remotely stored which simulatenously captures additional context provided by the Metrics system
-   * at the same time that window.digitalData is sent to analytics. Two use cases are supported,
-   * described as follows.
-   *
-   * For applications that provide Omega launch script configuration to the
-   * `MetricsBrowserRuntime.init()` method, the corresponding portions of the digitalData object can
-   * be supplied to the following APIs, and the Metrics SDK will store the provided object in
-   * `window.digitalData`, and simultaneously record the Analytics record in remote storage and call
-   * the Omega `window._satellite.track()` method. This approach assures consistency in the data
-   * between Omega and Metrics.
-   */
-  analytics: Readonly<Analytics>;
-
-  /**
-   * The History APIs are designed to mirror browser history management. Calling a Metrics history
-   * API is recommended either immediately before or after a call to window history, and will record
-   * a History record type and begin a new page load by generating a new HistoryID guid.
-   */
-  history: Readonly<History>;
-
-  /**
-   * Log a debug message similar to console.debug().
-   * @param message The message being logged.
-   * @param args Additional data associated to the log entry.
-   */
-  debug(message: string, ...args: any): void;
-
-  /**
-   * Log an error message similar to console.error().
-   * @param message The message being logged.
-   * @param args Additional data associated to the error.
-   */
-  error(message: string, ...args: any): void;
-
-  /**
-   * Records the specified event.
-   * @param event The name of the event being logged.
-   * @param data Additional data associated to the event.
-   */
-  event(event: string | string[], ...args: any): void;
-
-  /**
-   * Log an informational message similar to console.info().
-   * @param message The message being logged.
-   * @param args Additional data associated to the log entry.
-   */
-  info(message: string, ...args: any): void;
-
-  /**
-   * Log an informational message similar to console.log().
-   * @param message The message being logged.
-   * @param args Additional data associated to the log entry.
-   */
-  log(message: string, args: any): void;
-
-  /**
-   * Construct a named "Recent" event and emit it to storage. The payload is expected
-   * to contain PII so downstream handling must a) keep the data bag intact, and
-   * b) send the Recent record (with PII) only to Unified Recents. PII must be
-   * removed before sending to ADX.
-   * @function
-   * @param {string} revent The event.
-   * @param {any} args Optional arguments to be applied to the recorded metrics.
-   * @returns {Promise} A promise that resolves to the number of metrics that
-   * were queued for eventual flushing.
-   */
-  recent(revent: string | string[], ...args: any): void;
-
-  /**
-   * Starts a named timer that can be used to record time taken for an operation.
-   * @param name The name for the timer, which is used as a prefix for the
-   * emitted timer events.
-   * @param args Additional data associated to the timer.
-   */
-  start(name: string, ...args: any): Timer;
-
-  /**
-   * Stores the specified metric entry.
-   * @param metric The metric to be logged.
-   */
-  store(metric: Metric): void;
-
-  /**
-   * Log a warning message similar to console.warn().
-   * @param message The message being logged.
-   * @param args Additional data associated to the log entry.
-   */
-  warn(message: string, ...args: any): void;
-}

package/metrics/RecordType.ts

@@ -1,139 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * RecordType is an enumeration of known telemetry records. These
- * record types have specified symantics and use specific columns
- * for each type. That said, any record type may specify any of the
- * known fields for the custom purpose of the application.
- *
- * All RecordTypes except User are implementations of the Metric
- * interface. The User RecordType is for User context changes and should
- * not be created direclty by clients.
- *
- * Clients may specify custom record types, however there will be no
- * attempt to validate any fields. Storage of custom record types may
- * silently fail.
- */
-export enum RecordType {
-  /**
-   * Analytics record type reports an Omega analtycis record. The dynamicData
-   * object is copied from global.dynamicData.
-   */
-  ANALYTICS = 'Analytics',
-
-  /**
-   * Event reports an event to the system. Events are typically application-
-   * specific enumerations. Event strings should be very stable since they
-   * will be used for dashboards and alert queries. The recommended pattern is
-   * to use featureArea.subject.verb, for example: shell.solutionPicker.click.
-   *
-   * All events starting with 'exc.metrics' are reserved for metrics system use.
-   *
-   * Event record types are very similar to Log record types with the main
-   * difference being that the Event is expected to have a value for the event
-   * property, and the message property is considered optional, whereas Log
-   * records are expected to have a human-readable string in the message
-   * property, and the event property is considered optional.
-   */
-  EVENT = 'Event',
-
-  /**
-   * Recent is an Event destined for collection by the Unified Recents team.
-   * The data bag is expected to be prescribed yet customized for this record
-   * type and may contain PII. As such, the payload is ingested as a Log metric
-   * with User data. The Gateway sends the RECENT event to Unified Recents then
-   * sends the sanitized record to ADX.
-   */
-  RECENT = 'Recent',
-
-  /**
-   * History reports a history change in the current window. The
-   * window.location object will be stored in metricsState.
-   */
-  HISTORY = 'History',
-
-  /**
-   * Location reports a location change in the current window. Location
-   * records should be emitted just prior to calling window location
-   * methods to allow for flushing in case of reload. A
-   * new historyId will be generated, and the page will be considered
-   * 'loading'.
-   */
-  LOCATION = 'Location',
-
-  /**
-   * Log RecordType reports a string message at a specified log level.
-   * A logger name is optional but highly recommended for searching
-   * and filtering since the log message can be any string.
-   */
-  LOG = 'Log',
-
-  /**
-   * NetworkRequest reports the start of a network invocation, including
-   * the url and request parameters. The metric's data property will
-   * contain the network Request object supplied by the javascript VM.
-   */
-  NETWORK_REQUEST = 'NetworkRequest',
-
-  /**
-   * NetworkResponse reports the conclusion of a network invocation, which
-   * may be an HTTP status or an outright error. The metric's data
-   * property will contain either the Response object from the
-   * javascritp VM, or the Error returned by the network call.
-   */
-  NETWORK_RESPONSE = 'NetworkResponse',
-
-  /**
-   * ResourceTiming reports the timing results of network resource requests
-   * as reported by the Performance interface. The metric's data property
-   * will contain the ResourceTiming object suppolied by the javascript VM.
-   */
-  RESOURCE_TIMING = 'ResourceTiming',
-
-  /**
-   * PaintTiming reports the paint timing results as supplied by
-   * the Performance interface from the javascript VM. The PaintTiming
-   * object is stored in the metric's data property.
-   */
-  PAINT_TIMING = 'PaintTiming',
-
-  /**
-   * NavigationTiming reports the timing results of navigation events
-   * emitted from the javascript VM. The NavigationTiming object is stored
-   * in the metric's data property.
-   */
-  NAVIGATION_TIMING = 'NavigationTiming',
-
-  /**
-   * Timer reports the elapsed time between events. The duration property
-   * records the elapsed time since construction - the timer "starts" at
-   * construction. Timers are typically constructed using the start()
-   * method on an instance of Metrics. It is also possible to construct
-   * a new Timer object direclty, in which case a logger-style name for
-   * the timer is highly recommended to aid searching and filtering.
-   */
-  TIMER = 'Timer',
-
-  /**
-   * Tracer is a reserved RecordType for monitoring system health. It should
-   * not be used by clients.
-   */
-  TRACER = 'Tracer',
-
-  /**
-   * The User RecordType reports changes in the current user's login
-   * status and current effective group. This record type should not
-   * be used direclty. Instead, use the setUser() and clearUser()
-   * methods.
-   */
-  USER = 'User'
-}

package/metrics/User.ts

@@ -1,30 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-import Metric from './Metric';
-
-/**
- * @ignore
- */
-export default interface User extends Metric {
-  accountType?: string; // Analytics Data Layer: The account level of the user for your given product.
-  attributes?:  any; // Analytics Data Layer: additional values stored in key:value pairs with the value ALWAYS being strings.
-  authOrigin?:  string; // Analytics Data Layer: The origin of where the user logged in or "anonymous" if the user is not logged in.
-  authSystem?:  string; // Analytics Data Layer: The system used to provide the user.id and user.corpId.
-  displayName?: string; // firstname lastname - for convenience in viewing/searching
-  groupId?:     string; // user's group identifier, e.g. currently selected IMS org, or a solution user group
-  groupName?:   string; // current effective group for the user, e.g. current IMS org, for viewing/searching
-  ipAddress?:   string; // as viewed by the metrics gateway - an indicator of the user's location
-  language?:    string; // Analytics Data Layer: The language/locale setting the user has currently selected within the UI.
-  privileges?:  string[]; // Analytics Data Layer: Privileges that the user currently has access to as relating to the product as a whole.
-  sessionId?:   string; // user's session identifier, e.g. IMS session or browser session header/cookie
-  userAgent?:   string; // a client identifier, e.g. the User-Agent request header
-  userId?:      string; // user's login string, e.g. AdobeId or username, as submitted to the auth system
-}

package/metrics.ts

@@ -1,94 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * API used to log messages, errors, events, metrics and analytics that get pushed to our telemetry
- * system.
- *
- * The main goal of this project is to provide solutions that are integrating with Unified-Shell and
- * running on Adobe Experience Cloud as much telemetry information as possible "for free" and a
- * convenient integration option to collect custom, application specific metrics.
- *
- * ***Import:***
- *
- * ```typescript
- * import metrics from '@adobe/exc-app/metrics';
- * ```
- *
- * ***Type:***
- *
- * [MetricsApi](../interfaces/metrics.metricsapi.md#interface-metricsapi)
- *
- * ***Usage:***
- *
- * ```typescript
- * import metrics from '@adobe/exc-app/metrics';
- *
- * class MyClass {
- *   constructor() {
- *     this.metrics = metrics.create('exc.landing-page.recents');
- *   }
- *
- *   async someOperation() {
- *     const timer = this.metrics.start('MyClass.someOperation');
- *     try {
- *       await performOperation();
- *       timer.time('done');
- *     } catch(err) {
- *       this.metrics.error(error);
- *       throw err;
- *     }
- *   }
- * }
- * ```
- * @packageDocumentation
- * @module metrics
- * @preferred
- */
-
-import {connect} from './src/Global';
-import {Events} from './metrics/Events';
-import {Level} from './metrics/Level';
-import Metric from './metrics/Metric';
-import Metrics from './metrics/Metrics';
-
-/**
- * Defines the metrics API.
- */
-export interface MetricsApi {
-  /**
-   * Creates a metrics instance for the specified component to log entries and events.
-   * @param name The name of the component.
-   */
-  create(name: string): Readonly<Metrics>;
-}
-
-const api = connect('metrics', [
-  ['create', true]
-]) as MetricsApi;
-
-export default api;
-
-/**
- * @ignore
- */
-export {
-  Events,
-  Level
-};
-
-/**
- * @ignore
- */
-export type {
-  Metric,
-  Metrics
-};