@api-client/core 0.3.2 → 0.3.5

package/src/events/models/ClientCertificateEvents.ts

@@ -0,0 +1,87 @@
+import { IClientCertificate, ICertificateIndex, IRequestCertificate } from '../../models/ClientCertificate.js';
+import { ContextReadEvent, ContextListEvent, ContextListOptions, ContextListResult, ContextDeleteEvent, ContextDeleteRecord, ContextUpdateEvent, ContextChangeRecord, ContextStateUpdateEvent, ContextStateDeleteEvent } from '../BaseEvents.js';
+import { ModelEventTypes } from './ModelEventTypes.js';
+
+export class ClientCertificateEvents {
+  /**
+   * Dispatches an event handled by the data store to read the client certificate.
+   *
+   * @param target A node on which to dispatch the event.
+   * @param id The id of the client certificate
+   * @param rev The revision of the client certificate. If not set then the latest revision is used.
+   * @returns Promise resolved to a client certificate model.
+   */
+  static async read(target: EventTarget, id: string, rev?: string): Promise<IRequestCertificate | undefined> {
+    const e = new ContextReadEvent<IClientCertificate>(ModelEventTypes.ClientCertificate.read, id, rev);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * Dispatches an event to list the client certificates data.
+   *
+   * @param target A node on which to dispatch the event.
+   * @param opts Query options.
+   * @returns The list result.
+   */
+  static async list(target: EventTarget, opts?: ContextListOptions): Promise<ContextListResult<ICertificateIndex> | undefined> {
+    const e = new ContextListEvent<ICertificateIndex>(ModelEventTypes.ClientCertificate.list, opts);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * Dispatches an event handled by the data store to delete a client certificate
+   *
+   * @param target A node on which to dispatch the event.
+   * @param id The id of the project to delete.
+   * @param rev The revision of the project. If not set then the latest revision is used.
+   * @returns Promise resolved to a new revision after delete.
+   */
+  static async delete(target: EventTarget, id: string, rev?: string): Promise<ContextDeleteRecord | undefined> {
+    const e = new ContextDeleteEvent(ModelEventTypes.ClientCertificate.delete, id, undefined, rev);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * Dispatches an event handled by the data store to insert a new client certificate.
+   *
+   * @param target A node on which to dispatch the event.
+   * @param item The certificate object.
+   * @returns Promise resolved to the change record
+   */
+  static async insert(target: EventTarget, item: IClientCertificate): Promise<ContextChangeRecord<ICertificateIndex> | undefined> {
+    const e = new ContextUpdateEvent<IClientCertificate>(ModelEventTypes.ClientCertificate.insert, { item, });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  static get State(): typeof StateEvents {
+    return StateEvents;
+  }
+}
+
+class StateEvents {
+  /**
+   * Dispatches an event after a client certificate was updated
+   *
+   * @param target A node on which to dispatch the event.
+   * @param record Change record
+   */
+  static update(target: EventTarget, record: ContextChangeRecord<ICertificateIndex>): void {
+    const e = new ContextStateUpdateEvent<ICertificateIndex>(ModelEventTypes.ClientCertificate.State.update, record);
+    target.dispatchEvent(e);
+  }
+
+  /**
+   * Dispatches an event after a client certificate was deleted
+   *
+   * @param target A node on which to dispatch the event.
+   * @param record The context store delete record
+   */
+  static delete(target: EventTarget, record: ContextDeleteRecord): void {
+    const e = new ContextStateDeleteEvent(ModelEventTypes.ClientCertificate.State.delete, record);
+    target.dispatchEvent(e);
+  }
+}

package/src/events/models/ModelEventTypes.ts

@@ -0,0 +1,47 @@
+export const ModelEventTypes = {
+  ClientCertificate: Object.freeze({
+    read: 'storeclientcertificateread',
+    list: 'storeclientcertificatelist',
+    delete: 'storeclientcertificatedelete',
+    update: 'storeclientcertificateupdate',
+    insert: 'storeclientcertificateinsert',
+    State: Object.freeze({
+      update: 'storestateclientcertificateupdate',
+      delete: 'storestateclientcertificatedelete',
+    }),
+  }),
+  Project: Object.freeze({
+    create: 'storeprojectcreate',
+    read: 'storeprojectread',
+    update: 'storeprojectupdate',
+    delete: 'storeprojectdelete',
+    /** 
+     * Moves objects inside a project between position and/or folders.
+     */
+    move: 'storeprojectmove',
+    /** 
+     * Makes a copy of the project and stores it as new.
+     */
+    clone: 'storeprojectclone',
+    listAll: 'storeprojectlistall', // without pagination
+    Folder: Object.freeze({
+      create: 'storeprojectfoldercreate',
+      delete: 'storeprojectfolderdelete',
+      update: 'storeprojectfolderupdate',
+    }),
+    Request: Object.freeze({
+      create: 'storeprojectrequestcreate',
+      delete: 'storeprojectrequestdelete',
+      update: 'storeprojectrequestupdate',
+    }),
+    Environment: Object.freeze({
+      create: 'storeprojectenvironmentcreate',
+      delete: 'storeprojectenvironmentdelete',
+      update: 'storeprojectenvironmentupdate',
+    }),
+    State: Object.freeze({
+      update: 'storeprojectstateupdate',
+      delete: 'storeprojectstatedelete',
+    })
+  }),
+}

package/src/events/models/ModelEvents.ts

@@ -0,0 +1,7 @@
+import { ClientCertificateEvents } from './ClientCertificateEvents.js';
+import { ProjectEvents } from './ProjectEvents.js';
+
+export const ModelEvents = Object.freeze({
+  Project: ProjectEvents,
+  ClientCertificate: ClientCertificateEvents,
+});

package/src/events/models/ProjectEvents.ts

@@ -0,0 +1,331 @@
+import { IHttpProject, IProjectInitOptions, IProjectMoveOptions, IHttpProjectIndex, IFolderCreateOptions, IRequestAddOptions } from "../../models/HttpProject.js";
+import { IProjectFolder } from "../../models/ProjectFolder.js";
+import { IProjectRequest } from "../../models/ProjectRequest.js";
+import { IEnvironment } from "../../models/Environment.js";
+import { ContextChangeRecord, ContextEvent, ContextReadEvent, ContextUpdateEvent, ContextDeleteRecord, ContextDeleteEvent, ContextEventDetailWithResult } from "../BaseEvents.js";
+import { ModelEventTypes } from './ModelEventTypes.js';
+import CustomEvent from '../CustomEvent.js';
+
+export interface ProjectMoveEventDetail {
+  type: 'request' | 'folder';
+  key: string;
+  opts?: IProjectMoveOptions;
+}
+
+export interface ProjectCloneEventDetail {
+  /**
+   * The id of the project to clone in the data store.
+   */
+  id: string;
+}
+
+/**
+ * A list of options to initialize a folder in a project.
+ */
+export interface IFolderInitOptions extends IFolderCreateOptions {
+  /**
+   * The store id of the project.
+   */
+  id: string;
+  /**
+   * Optional name of the new folder.
+   */
+  name?: string;
+}
+
+/**
+ * A list of options to initialize a request in a project.
+ */
+export interface IRequestInitOptions extends IRequestAddOptions {
+  /**
+   * The store id of the project.
+   */
+  id: string;
+  /**
+   * The URL of the request.
+   */
+  url: string;
+}
+
+export interface IEnvironmentInitOptions {
+  /**
+   * The store id of the project.
+   */
+  id: string;
+  /**
+   * The name of the environment to create.
+   */
+  name: string;
+  /**
+   * The optional key of the parent folder.
+   */
+  key?: string;
+}
+
+class ProjectFolderEvents {
+  /**
+   * Creates a folder in a project.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The store id of the project
+   * @param name Optionally, name of the folder to create.
+   * @param opts Optional options to create a folder.
+   * @returns The change record of the created folder. Note, the client should either refresh the project from the store or append the change record to the instance of the project.
+   */
+  static async create(target: EventTarget, id: string, name?: string, opts: IFolderCreateOptions = {}): Promise<ContextChangeRecord<IProjectFolder> | undefined> {
+    const init: IFolderInitOptions = { ...opts, id, name, };
+    const e = new ContextEvent<IFolderInitOptions, ContextChangeRecord<IProjectFolder>>(ModelEventTypes.Project.Folder.create, init);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Deletes a folder from a project
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The data store id of the project
+   * @param key The key of the folder to delete.
+   */
+  static async delete(target: EventTarget, id: string, key: string): Promise<ContextDeleteRecord | undefined> {
+    const e = new ContextDeleteEvent(ModelEventTypes.Project.Folder.delete, key, id);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Updates the entire folder schema in a project.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The data store id of the project
+   * @param folder The folder to replace the schema for.
+   * @returns The change record of the updated folder.
+   */
+  static async update(target: EventTarget, id: string, folder: IProjectFolder): Promise<ContextChangeRecord<IProjectFolder> | undefined> {
+    const e = new ContextUpdateEvent(ModelEventTypes.Project.Folder.update, { item: folder, parent: id });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+}
+
+class ProjectRequestEvents {
+  /**
+   * Creates a request in a project.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The store id of the project
+   * @param url The URL of the request.
+   * @param opts Optional options to create a request.
+   * @returns The change record of the created request. Note, the client should either refresh the project from the store or append the change record to the instance of the project.
+   */
+  static async create(target: EventTarget, id: string, url: string, opts: IRequestAddOptions = {}): Promise<ContextChangeRecord<IProjectRequest> | undefined> {
+    const init: IRequestInitOptions = { ...opts, id, url, };
+    const e = new ContextEvent<IRequestInitOptions, ContextChangeRecord<IProjectRequest>>(ModelEventTypes.Project.Request.create, init);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Deletes a request from a project
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The data store id of the project
+   * @param key The key of the request to delete.
+   */
+  static async delete(target: EventTarget, id: string, key: string): Promise<ContextDeleteRecord | undefined> {
+    const e = new ContextDeleteEvent(ModelEventTypes.Project.Request.delete, key, id);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Updates the entire request schema in a project.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The data store id of the project
+   * @param request The request to replace the schema for.
+   * @returns The change record of the updated request.
+   */
+  static async update(target: EventTarget, id: string, request: IProjectRequest): Promise<ContextChangeRecord<IProjectRequest> | undefined> {
+    const e = new ContextUpdateEvent(ModelEventTypes.Project.Request.update, { item: request, parent: id });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+}
+
+class ProjectEnvironmentEvents {
+  /**
+   * Creates an environment in a project.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The store id of the project
+   * @param name The name of the environment.
+   * @param key The optional key of the parent folder.
+   * @returns The change record of the created environment. Note, the client should either refresh the project from the store or append the change record to the instance of the project.
+   */
+  static async create(target: EventTarget, id: string, name: string, key?: string): Promise<ContextChangeRecord<IEnvironment> | undefined> {
+    const init: IEnvironmentInitOptions = { id, name, key };
+    const e = new ContextEvent<IEnvironmentInitOptions, ContextChangeRecord<IEnvironment>>(ModelEventTypes.Project.Environment.create, init);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Deletes an environment from a project
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The data store id of the project
+   * @param key The key of the environment to delete.
+   */
+  static async delete(target: EventTarget, id: string, key: string): Promise<ContextDeleteRecord | undefined> {
+    const e = new ContextDeleteEvent(ModelEventTypes.Project.Environment.delete, key, id);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Updates the entire environment schema in a project.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The data store id of the project
+   * @param environment The environment to replace the schema for.
+   * @returns The change record of the updated environment.
+   */
+  static async update(target: EventTarget, id: string, environment: IEnvironment): Promise<ContextChangeRecord<IEnvironment> | undefined> {
+    const e = new ContextUpdateEvent(ModelEventTypes.Project.Environment.update, { item: environment, parent: id });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+}
+
+/**
+ * ARC's HTTP project events.
+ * 
+ * Note, `id`s refers to datastore ids but `key`s are internal identifiers inside the project.
+ * Whenever id is used it refers to the store's ids. When `key` is used it is the id of the project or any of its components.
+ */
+export class ProjectEvents {
+  /** 
+   * Creates a new project in the data store.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param name The name of the project to create
+   * @returns The change record of the created project.
+   */
+  static async create(target: EventTarget, name: string): Promise<ContextChangeRecord<IHttpProject> | undefined> {
+    const e = new ContextEvent<IProjectInitOptions, ContextChangeRecord<IHttpProject>>(ModelEventTypes.Project.create, { name });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Reads a project from the data store.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The data store id of the project to read.
+   * @param rev Optional revision version, when supported.
+   */
+  static async read(target: EventTarget, id: string, rev?: string): Promise<IHttpProject | undefined> {
+    const e = new ContextReadEvent<IHttpProject>(ModelEventTypes.Project.read, id, rev);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Updates the entire object in the store.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param project The project to replace the value for.
+   * @returns The change record of the updated project.
+   */
+  static async update(target: EventTarget, project: IHttpProject): Promise<ContextChangeRecord<IHttpProject> | undefined> {
+    const e = new ContextUpdateEvent(ModelEventTypes.Project.update, { item: project });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Deletes a project from the data store.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The data store id of the project to delete.
+   */
+  static async delete(target: EventTarget, id: string): Promise<ContextDeleteRecord | undefined> {
+    const e = new ContextDeleteEvent(ModelEventTypes.Project.delete, id);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Moves a request or a folder inside the project.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param type The type of the object to move within the project.
+   * @param key The `key` of the request of the folder
+   * @param opts The move options. When omitted then it moves the object to the project root at the last position.
+   * @returns The change record of the updated project.
+   */
+  static async move(target: EventTarget, type: 'request' | 'folder', key: string, opts?: IProjectMoveOptions): Promise<ContextChangeRecord<IHttpProject> | undefined> {
+    const e = new ContextEvent<ProjectMoveEventDetail, ContextChangeRecord<IHttpProject>>(ModelEventTypes.Project.move, {
+      key,
+      type,
+      opts,
+    });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Clones a project that is stored in the data store.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param id The data store id of the project to clone.
+   * @returns The cloned project (the copy).
+   */
+  static async clone(target: EventTarget, id: string): Promise<ContextChangeRecord<IHttpProject> | undefined> {
+    const e = new ContextEvent<ProjectCloneEventDetail, ContextChangeRecord<IHttpProject>>(ModelEventTypes.Project.clone, {
+      id,
+    });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * Lists all projects in the data store.
+   * This does not return the whole project record. Instead it only returns the index object of the project.
+   * 
+   * @param target The target on which to dispatch the event
+   * @returns The list of project index objects.
+   */
+  static async listAll(target: EventTarget): Promise<IHttpProjectIndex[] | undefined> {
+    const detail: ContextEventDetailWithResult<IHttpProjectIndex[]> = {};
+    const e = new CustomEvent(ModelEventTypes.Project.listAll, {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+      detail,
+    });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * Events related to a folder manipulation in a project.
+   */
+  static get Folder(): typeof ProjectFolderEvents {
+    return ProjectFolderEvents;
+  }
+
+  /**
+   * Events related to a request manipulation in a project.
+   */
+  static get Request(): typeof ProjectRequestEvents {
+    return ProjectRequestEvents;
+  }
+
+  /**
+   * Events related to an environment manipulation in a project.
+   */
+  static get Environment(): typeof ProjectEnvironmentEvents {
+    return ProjectEnvironmentEvents;
+  }
+};

package/src/events/process/ProcessEventTypes.ts

@@ -0,0 +1,5 @@
+export const ProcessEventTypes = Object.freeze({
+  loadingStart: 'processloadingstart',
+  loadingStop: 'processloadingstop',
+  loadingError: 'processloadingerror',
+});

package/src/events/process/ProcessEvents.ts

@@ -0,0 +1,76 @@
+import { ProcessEventTypes } from './ProcessEventTypes.js';
+
+export interface IProcessStartDetail {
+  pid: string;
+  message: string;
+}
+
+export interface IProcessStopDetail {
+  pid: string;
+}
+
+export interface IProcessErrorDetail {
+  pid: string;
+  message: string;
+  error?: Error
+}
+
+export class ProcessEvents {
+  /**
+   * An event to be dispatched when the application is stating a long running process
+   * in the background. The side effect of the event is the UI showing a process
+   * indicator.
+   * 
+   * @param target A node on which to dispatch the event.
+   * @param pid The id of the process. The same id has to be passed to the stop event.
+   * @param message Optional message rendered in the UI.
+   */
+  static loadingStart(target: EventTarget, pid: string, message: string): void {
+    const detail: IProcessStartDetail = { pid, message };
+    const e = new CustomEvent(ProcessEventTypes.loadingStart, {
+      cancelable: true,
+      composed: true,
+      bubbles: true,
+      detail,
+    });
+    target.dispatchEvent(e);
+  }
+
+  /**
+   * An event to be dispatched when the application has finished a long running process
+   * in the background.
+   * 
+   * @param target A node on which to dispatch the event.
+   * @param pid The id of the process. The same id has to be passed to the stop event.
+   */
+  static loadingStop(target: EventTarget, pid: string): void {
+    const detail: IProcessStopDetail = { pid };
+    const e = new CustomEvent(ProcessEventTypes.loadingStop, {
+      cancelable: true,
+      composed: true,
+      bubbles: true,
+      detail,
+    });
+    target.dispatchEvent(e);
+  }
+
+  /**
+   * An event to be dispatched when the application has finished a long running process
+   * in the background with an error.
+   * 
+   * @param target A node on which to dispatch the event.
+   * @param pid The id of the process used to start it.
+   * @param message The message to be rendered to the user.
+   * @param error The error object caused the event. Optional.
+   */
+  static loadingError(target: EventTarget, pid: string, message: string, error?: Error): void {
+    const detail: IProcessErrorDetail = { pid, message, error };
+    const e = new CustomEvent(ProcessEventTypes.loadingError, {
+      cancelable: true,
+      composed: true,
+      bubbles: true,
+      detail,
+    });
+    target.dispatchEvent(e);
+  }
+}

package/src/events/readme.md

@@ -0,0 +1,22 @@
+# Events
+
+This package contains a definition of events used by the ARC ecosystem to communicate with context providers.
+
+## Context provider
+
+A context provider is any service that is listening for relevant events and responds to them by taking some action.
+
+For example a Store Context Provider is a provider that listens to events related to the data models and performs CRUD operations on the data store. The result of the operation is passed to the `result` object of the event. The event is an instance of the CustomEvent class.
+
+## Communication architecture
+
+A module or an application wants to read the context value from a context provider. The module dispatches a CustomEvent on the application's EventTarget with the corresponding `type` handled by the context provider.
+
+The provider handles the event, cancels it (when applicable, prevents duplication), and calls the corresponding asynchronous logic. The result of the operation is always a Promise. The promise is resolved when the operation finish
+
+The promise is set on the `detail` object if the `CustomEvent` as the `result` property.
+
+This has the following implications:
+
+- all events are processed asynchronously
+- all events must extend `CustomEvent` class, unless they have no side effects (no result, no data to pass to the provider)

package/src/events/reporting/ReportingEventTypes.ts

@@ -0,0 +1,3 @@
+export const ReportingEventTypes = Object.freeze({
+  error: 'reporterror',
+});

package/src/events/reporting/ReportingEvents.ts

@@ -0,0 +1,28 @@
+import { ReportingEventTypes } from './ReportingEventTypes.js';
+
+export interface IReportingErrorDetail {
+  description: string;
+  error?: Error;
+  component?: string;
+}
+
+export class ReportingEvents {
+  /**
+   * Dispatches the general error event for UI logging purposes.
+   * 
+   * @param target A node on which to dispatch the event
+   * @param description The error description
+   * @param error Optional original error object that has caused this event
+   * @param component Optional component name.
+   */
+  static error(target: EventTarget, description: string, error?: Error, component?: string): void {
+    const detail: IReportingErrorDetail = { error, description, component };
+    const e = new CustomEvent(ReportingEventTypes.error, {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+      detail,
+    });
+    target.dispatchEvent(e);
+  }
+}

package/src/events/telemetry/TelemetryEventTypes.ts

@@ -0,0 +1,10 @@
+export const TelemetryEventTypes = Object.freeze({
+  view: 'telemetryscreenview',
+  event: 'telemetryevent',
+  exception: 'telemetryexception',
+  social: 'telemetrysocial',
+  timing: 'telemetrytiming',
+  State: Object.freeze({
+    set: 'telemetrystateset',
+  }),
+});