@api-client/core 0.3.2 → 0.3.5

package/src/events/BaseEvents.ts

@@ -0,0 +1,259 @@
+import CustomEvent from './CustomEvent.js';
+
+/**
+ * Base event detail definition for the events that returns a `result`
+ * property on the `detail` object
+ */
+export interface ContextEventDetailWithResult<T> {
+  /**
+   * This property is set by the context provider, a promise resolved when the operation finish
+   * with the corresponding result.
+   */
+  result?: Promise<T> | undefined;
+}
+
+/**
+ * A base class to use with context providers.
+ */
+export class ContextEvent<S extends object, R> extends CustomEvent<ContextEventDetailWithResult<R>> {
+  /**
+   * @param type The event type
+   * @param detail The optional detail object. It adds object's properties to the `detail` with the `result` property.
+   */
+  constructor(type: string, detail: S) {
+    super(type, {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+      detail: {
+        result: undefined,
+        ...detail,
+      }
+    });
+  }
+}
+
+export interface ContextReadEventDetail {
+  /**
+   * The id of the state object to read.
+   */
+  id: string;
+  /**
+   * Optional revision of the state, when supported by the context provider.
+   */
+  rev?: string;
+}
+
+/**
+ * An event to be used to read a state from a context provider.
+ */
+export class ContextReadEvent<T> extends ContextEvent<ContextReadEventDetail, T> {
+  /**
+   * @param type The type of the event
+   * @param id The domain id of the object to read
+   * @param rev Optional revision of the state, when supported by the context provider.
+   */
+  constructor(type: string, id: string, rev?: string) {
+    super(type, { id, rev });
+  }
+}
+
+export interface ContextReadBulkEventDetail {
+  /**
+   * The list of ids to read.
+   */
+  ids: string[];
+}
+
+/**
+ * An event to be used to read a list of object from the API store.
+ */
+export class ContextReadBulkEvent<T> extends ContextEvent<ContextReadBulkEventDetail, T> {
+  /**
+   * @param type The type of the event
+   * @param ids The list of domain ids to read. These must be of the same domain type.
+   */
+  constructor(type: string, ids: string[]) {
+    super(type, { ids });
+  }
+}
+
+/**
+ * A general purpose change record.
+ * Set on the `detail` object of the `CustomEvent` when a change occurs in the context store.
+ */
+export interface ContextChangeRecord<T> {
+  /**
+   * The data kind of the changed item.
+   * May not be present when this is used with the old architecture.
+   */
+  kind?: string;
+  /**
+   * The ID of the changed context state object.
+   */
+  key: string;
+  /**
+   * The revision of the updated context state object.
+   * It is not set when old revision is unavailable (new entity is created) or when the context provider does not support this value.
+   */
+  oldRev?: string;
+  /**
+   * New revision of updated state object. May not be set when the context provider does not support this value.
+   */
+  rev?: string;
+  /**
+   * The updated context state object.
+   */
+  item?: T;
+  /**
+   * Optionally, when relevant, the id of the parent of the changed object.
+   */
+  parent?: string;
+}
+
+export interface ContextDeleteEventDetail {
+  /**
+   * The id of the domain object to remove.
+   */
+  id: string;
+  /**
+   * The id of the parent object, if applicable.
+   */
+  parent?: string;
+  /**
+   * The revision to delete, when applicable.
+   */
+  rev?: string;
+}
+
+/**
+ * An event to be used to delete a state in the context provider.
+ */
+export class ContextDeleteEvent extends ContextEvent<ContextDeleteEventDetail, ContextDeleteRecord> {
+  /**
+   * @param type The type of the event to dispatch.
+   * @param id The id of the object to delete
+   * @param parent The id of the parent object, if applicable.
+   */
+  constructor(type: string, id: string, parent?: string, rev?: string) {
+    super(type, { id, parent, rev });
+  }
+}
+
+export interface ContextDeleteRecord {
+  /**
+   * The data kind of the deleted item.
+   * May not be present when this is used with the old architecture.
+   */
+  kind?: string;
+  /**
+   * The id of the removed object.
+   */
+  id: string;
+  /**
+   * The id of the parent object, if applicable.
+   */
+  parent?: string;
+}
+
+/**
+ * An event dispatched when a context store object has been deleted.
+ * In general a single context store uses the same event to dispatch the change record.
+ * For example the `data-store` dispatches the `x` event and the change record has the 
+ * `kind` property that is used to recognize the type of the data object.
+ */
+export class ContextStateDeleteEvent extends CustomEvent<ContextDeleteRecord> {
+  /**
+   * @param type The type of the event to dispatch.
+   * @param record The delete record.
+   */
+  constructor(type: string, record: ContextDeleteRecord) {
+    super(type, {
+      bubbles: true,
+      composed: true,
+      cancelable: false,
+      detail: record,
+    });
+  }
+}
+
+/**
+ * An event dispatched when a context store object has been updated.
+ */
+export class ContextStateUpdateEvent<T> extends CustomEvent<ContextChangeRecord<T>> {
+  /**
+   * @param type The type of the event to dispatch.
+   * @param record The delete record.
+   */
+  constructor(type: string, record: ContextChangeRecord<T>) {
+    super(type, {
+      bubbles: true,
+      composed: true,
+      cancelable: false,
+      detail: record,
+    });
+  }
+}
+
+export interface ContextUpdateEventDetail<T> {
+  /**
+   * The context store object to be updated by the context provider.
+   */
+  item: T;
+  /**
+   * The id of the parent object, if applicable.
+   */
+  parent?: string;
+}
+
+/**
+ * An event that is dispatched to update the entire object in the store.
+ * This is equivalent to PUT operation in REST HTTP.
+ * 
+ * @template T The object that is being updated.
+ */
+export class ContextUpdateEvent<T extends object> extends ContextEvent<ContextUpdateEventDetail<T>, ContextChangeRecord<T>> {
+  constructor(type: string, updateInfo: ContextUpdateEventDetail<T>) {
+    super(type, updateInfo);
+  }
+}
+
+/**
+ * Data store query result object.
+ */
+export interface ContextListResult<T> {
+  /**
+   * Next page token to be used with pagination.
+   * It is not set when the query has not returned any results.
+   */
+  nextPageToken?: string;
+  /**
+   * The list of items in the response.
+   * May be empty array when there was no more results.
+   */
+  items: T[];
+}
+
+/**
+ * Base query options for the data store.
+ */
+export interface ContextListOptions {
+  /**
+   * The number of results per the page.
+   */
+  limit?: number;
+  /**
+   * A string that should be used with the pagination.
+   */
+  nextPageToken?: string;
+}
+
+export class ContextListEvent<T> extends ContextEvent<ContextListOptions, ContextListResult<T>> {
+  /**
+   * @param type The type of the event
+   * @param opts Query options.
+   */
+  constructor(type: string, opts: ContextListOptions = {}) {
+    super(type, opts);
+  }
+}

package/src/events/CustomEvent.ts

@@ -0,0 +1,27 @@
+var ctor: typeof CustomEvent;
+
+if (typeof CustomEvent === 'function') {
+  ctor = CustomEvent;
+} else {
+  const detailSymbol = Symbol('detail');
+  ctor = class CustomEvent<T> extends Event {
+    [detailSymbol]: T;
+
+    get detail(): T {
+      return this[detailSymbol];
+    }
+
+    constructor(type: string, eventInitDict?: CustomEventInit | undefined) {
+      super(type, eventInitDict);
+      if (eventInitDict && eventInitDict.detail) {
+        this[detailSymbol] = eventInitDict.detail;
+      }
+    }
+
+    initCustomEvent(type: string, bubbles?: boolean, cancelable?: boolean, detail?: T): void {
+      throw new Error(`This is deprecated. Do not use this function.`);
+    }
+  }
+}
+
+export default ctor;

package/src/events/EventTypes.ts

@@ -0,0 +1,19 @@
+import { ModelEventTypes } from './models/ModelEventTypes.js';
+import { CookieEventTypes } from './cookies/CookieEventTypes.js';
+import { AuthorizationEventTypes } from './authorization/AuthorizationEventTypes.js';
+import { EncryptionEventTypes } from './encryption/EncryptionEventTypes.js';
+import { ProcessEventTypes } from './process/ProcessEventTypes.js';
+import { ReportingEventTypes } from './reporting/ReportingEventTypes.js';
+import { TelemetryEventTypes } from './telemetry/TelemetryEventTypes.js';
+import { EnvironmentEventTypes } from './environment/EnvironmentEventTypes.js';
+
+export const EventTypes = Object.freeze({
+  Authorization: AuthorizationEventTypes,
+  Cookie: CookieEventTypes,
+  Encryption: EncryptionEventTypes,
+  Model: ModelEventTypes,
+  Process: ProcessEventTypes,
+  Reporting: ReportingEventTypes,
+  Telemetry: TelemetryEventTypes,
+  Environment: EnvironmentEventTypes,
+});

package/src/events/Events.ts

@@ -0,0 +1,19 @@
+import { ModelEvents } from './models/ModelEvents.js';
+import { CookieEvents } from './cookies/CookieEvents.js';
+import { AuthorizationEvents } from './authorization/AuthorizationEvents.js';
+import { EncryptionEvents } from './encryption/EncryptionEvents.js';
+import { ProcessEvents } from './process/ProcessEvents.js';
+import { ReportingEvents } from './reporting/ReportingEvents.js';
+import { TelemetryEvents } from './telemetry/TelemetryEvents.js';
+import { EnvironmentEvents } from './environment/EnvironmentEvents.js';
+
+export const Events = Object.freeze({
+  Authorization: AuthorizationEvents,
+  Cookie: CookieEvents,
+  Encryption: EncryptionEvents,
+  Model: ModelEvents,
+  Process: ProcessEvents,
+  Reporting: ReportingEvents, 
+  Telemetry: TelemetryEvents,
+  Environment: EnvironmentEvents,
+});

package/src/events/authorization/AuthorizationEventTypes.ts

@@ -0,0 +1,22 @@
+export const AuthorizationEventTypes = Object.freeze({
+  OAuth2: Object.freeze({
+    /** 
+     * Authorization with auth configuration on detail
+     */
+    authorize: 'oauth2authorize',
+    /** 
+     * Removes cached token for the provider
+     */
+    removeToken: 'oauth2removetoken',
+  }),
+  Oidc: Object.freeze({
+    /** 
+     * Authorization the user with the provided configuration.
+     */
+    authorize: 'oidcauthorize',
+    /** 
+     * Removes cached tokens for the provider
+     */
+    removeTokens: 'oidcremovetokens',
+  }),
+});

package/src/events/authorization/AuthorizationEvents.ts

@@ -0,0 +1,61 @@
+import { IOAuth2Authorization, ITokenRemoveOptions, IOidcTokenInfo, IOidcTokenError, ITokenInfo } from '../../models/Authorization.js';
+import { AuthorizationEventTypes } from './AuthorizationEventTypes.js';
+import { ContextEvent } from "../BaseEvents.js";
+
+export class AuthorizationEvents {
+  static get OAuth2(): typeof OAuth2Events {
+    return OAuth2Events;
+  }
+
+  static get Oidc(): typeof OidcEvents {
+    return OidcEvents;
+  }
+}
+
+class OAuth2Events {
+  /**
+   * @param target A node on which to dispatch the event.
+   * @param config Authorization options.
+   * @returns Promise resolved with authorization result
+   */
+  static async authorize(target: EventTarget, config: IOAuth2Authorization): Promise<ITokenInfo | undefined> {
+    const e = new ContextEvent<IOAuth2Authorization, ITokenInfo>(AuthorizationEventTypes.OAuth2.authorize, config);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * @param target A node on which to dispatch the event.
+   * @param config Authorization options.
+   * @returns Promise resolved when the token is removed
+   */
+  static async removeToken(target: EventTarget, config: ITokenRemoveOptions): Promise<void> {
+    const e = new ContextEvent<ITokenRemoveOptions, void>(AuthorizationEventTypes.OAuth2.removeToken, config);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+}
+
+class OidcEvents {
+  /**
+   * @param target A node on which to dispatch the event.
+   * @param config Authorization options.
+   * @returns Promise resolved with authorization result
+   */
+  static async authorize(target: EventTarget, config: IOAuth2Authorization): Promise<(IOidcTokenInfo|IOidcTokenError)[] | undefined> {
+    const e = new ContextEvent<IOAuth2Authorization, (IOidcTokenInfo|IOidcTokenError)[]>(AuthorizationEventTypes.Oidc.authorize, config);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * @param target A node on which to dispatch the event.
+   * @param config Authorization options.
+   * @returns Promise resolved when the token is removed
+   */
+  static async removeToken(target: EventTarget, config: ITokenRemoveOptions): Promise<void> {
+    const e = new ContextEvent<ITokenRemoveOptions, void>(AuthorizationEventTypes.Oidc.removeTokens, config);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+}

package/src/events/cookies/CookieEventTypes.ts

@@ -0,0 +1,13 @@
+export const CookieEventTypes = Object.freeze({
+  listAll: 'sessioncookielistall',
+  listDomain: 'sessioncookielistdomain',
+  listUrl: 'sessioncookielisturl',
+  delete: 'sessioncookiedelete',
+  deleteUrl: 'sessioncookiedeleteurl',
+  update: 'sessioncookieupdate',
+  updateBulk: 'sessioncookieupdatebulk',
+  State: Object.freeze({
+    delete: 'sessioncookiestatedelete',
+    update: 'sessioncookiestateupdate',
+  }),
+});

package/src/events/cookies/CookieEvents.ts

@@ -0,0 +1,157 @@
+import { CookieEventTypes } from './CookieEventTypes.js';
+import { IHttpCookie } from "../../models/HttpCookie.js";
+import { ContextEventDetailWithResult, ContextEvent, ContextChangeRecord, ContextUpdateEvent, ContextStateUpdateEvent } from "../BaseEvents.js";
+
+export interface ICookieDomainListDetail {
+  domain: string;
+}
+
+export interface ICookieUrlListDetail {
+  url: string;
+}
+
+export interface ICookieItemsDetail {
+  cookies: IHttpCookie[];
+}
+
+export interface ICookieDetail {
+  cookie: IHttpCookie;
+}
+
+export interface ICookieDeleteUrlDetail {
+  url: string;
+  name?: string
+}
+
+export class CookieEvents {
+  /**
+   * 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<IHttpCookie[] | undefined> {
+    const detail: ContextEventDetailWithResult<IHttpCookie[]> = {};
+    const e = new CustomEvent(CookieEventTypes.listAll, {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+      detail,
+    });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * @param target The target on which to dispatch the event
+   * @param domain The cookie domain
+   * @returns The list of project index objects.
+   */
+  static async listDomain(target: EventTarget, domain: string): Promise<IHttpCookie[] | undefined> {
+    const detail: ICookieDomainListDetail = { domain };
+    const e = new ContextEvent<ICookieDomainListDetail, IHttpCookie[]>(CookieEventTypes.listDomain, detail);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * @param target The target on which to dispatch the event
+   * @param url The cookie URL
+   * @returns The list of project index objects.
+   */
+  static async listUrl(target: EventTarget, url: string): Promise<IHttpCookie[] | undefined> {
+    const detail: ICookieUrlListDetail = { url };
+    const e = new ContextEvent<ICookieUrlListDetail, IHttpCookie[]>(CookieEventTypes.listUrl, detail);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Deletes cookies from the store.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param cookies The list of cookies to remove
+   */
+  static async delete(target: EventTarget, cookies: IHttpCookie[]): Promise<void> {
+    const detail: ICookieItemsDetail = { cookies };
+    const e = new ContextEvent<ICookieItemsDetail, void>(CookieEventTypes.delete, detail);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Deletes cookies from the store.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param url The url associated with the cookie. Depending on the session mechanism the URL or the domain and the path is used.
+   * @param name The name of the cookie to remove. When not set all cookies are removed for the given URL.
+   */
+  static async deleteUrl(target: EventTarget, url: string, name?: string): Promise<void> {
+    const detail: ICookieDeleteUrlDetail = { url, name };
+    const e = new ContextEvent<ICookieDeleteUrlDetail, void>(CookieEventTypes.deleteUrl, detail);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Updates a cookie in the store.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param cookie A cookie to update
+   * @returns The change record of the updated cookie.
+   */
+  static async update(target: EventTarget, cookie: IHttpCookie): Promise<ContextChangeRecord<IHttpCookie> | undefined> {
+    const e = new ContextUpdateEvent(CookieEventTypes.update, { item: cookie });
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /** 
+   * Updates a cookie in the store in a bulk operation.
+   * 
+   * @param target The target on which to dispatch the event
+   * @param cookies A list of cookies to update
+   * @returns The change record of the updated cookie.
+   */
+  static async updateBulk(target: EventTarget, cookies: IHttpCookie[]): Promise<void> {
+    const detail: ICookieItemsDetail = { cookies };
+    const e = new ContextEvent<ICookieItemsDetail, void>(CookieEventTypes.updateBulk, detail);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * Events related to a state of a cookie store.
+   */
+  static get State(): typeof StateEvents {
+    return StateEvents;
+  }
+}
+
+class StateEvents {
+  /**
+   * Event dispatched when a cookie was deleted from the context store
+   * @param target The target on which to dispatch the event
+   * @param cookie The schema of the removed cookie
+   */
+  static delete(target: EventTarget, cookie: IHttpCookie): void {
+    const e = new CustomEvent<ICookieDetail>(CookieEventTypes.State.delete, {
+      bubbles: true,
+      composed: true,
+      cancelable: false,
+      detail: { cookie },
+    });
+    target.dispatchEvent(e);
+  }
+
+  /**
+   * Event dispatched when a cookie was deleted from the context store
+   * @param target The target on which to dispatch the event
+   * @param record The change record.
+   */
+  static update(target: EventTarget, record: ContextChangeRecord<IHttpCookie>): void {
+    const e = new ContextStateUpdateEvent<IHttpCookie>(CookieEventTypes.State.update, record);
+    target.dispatchEvent(e);
+  }
+}

package/src/events/encryption/EncryptionEventTypes.ts

@@ -0,0 +1,4 @@
+export const EncryptionEventTypes = Object.freeze({
+  encrypt: 'encryptionencrypt',
+  decrypt: 'encryptiondecrypt',
+});

package/src/events/encryption/EncryptionEvents.ts

@@ -0,0 +1,51 @@
+import { EncryptionEventTypes } from './EncryptionEventTypes.js';
+import { ContextEvent } from "../BaseEvents.js";
+
+export interface IEncryptionEventDetail {
+  /**
+   * The data to export
+   */
+  data: any;
+  /**
+   * The passphrase to use in 2-way data encryption
+   */
+  passphrase: string;
+  /**
+   * Encryption method to use
+   */
+  method: string;
+}
+
+export class EncryptionEvents {
+  /**
+   * Dispatches an event handled by the encryption module to encrypt the data
+   *
+   * @param target A node on which to dispatch the event.
+   * @param data The data to encrypt
+   * @param passphrase The passphrase to use in 2-way data encryption
+   * @param method Encryption method to use
+   * @returns Promise resolved to the encryption result
+   */
+  static async encrypt(target: EventTarget, data: any, passphrase: string, method: string): Promise<string | undefined> {
+    const config: IEncryptionEventDetail = { data, passphrase, method };
+    const e = new ContextEvent<IEncryptionEventDetail, string>(EncryptionEventTypes.encrypt, config);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+
+  /**
+   * Dispatches an event handled by the encryption module to decrypt the data
+   *
+   * @param target A node on which to dispatch the event.
+   * @param data The data to decrypt
+   * @param passphrase The passphrase to use to decrypt the data
+   * @param method Method used to encrypt the data
+   * @returns Promise resolved to the decrypted result
+   */
+  static async decrypt(target: EventTarget, data: any, passphrase: string, method: string): Promise<string | undefined> {
+    const config: IEncryptionEventDetail = { data, passphrase, method };
+    const e = new ContextEvent<IEncryptionEventDetail, string>(EncryptionEventTypes.decrypt, config);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+}

package/src/events/environment/EnvironmentEventTypes.ts

@@ -0,0 +1,3 @@
+export const EnvironmentEventTypes = Object.freeze({
+  set: 'environmentsetvariable',
+});

package/src/events/environment/EnvironmentEvents.ts

@@ -0,0 +1,24 @@
+import { EnvironmentEventTypes } from './EnvironmentEventTypes.js';
+import { ContextEvent } from "../BaseEvents.js";
+
+export interface ISetVariableDetail {
+  name: string;
+  value: string;
+}
+
+export class EnvironmentEvents {
+  /**
+   * An event dispatched to set a variable in the current environment.
+   * 
+   * @param target A node on which to dispatch the event.
+   * @param name Variable name
+   * @param value Variable value
+   * @returns Nothing. The promise resolves when the variable is set.
+   */
+  static async set(target: EventTarget, name: string, value: string): Promise<void> {
+    const detail: ISetVariableDetail = { name, value };
+    const e = new ContextEvent<ISetVariableDetail, void>(EnvironmentEventTypes.set, detail);
+    target.dispatchEvent(e);
+    return e.detail.result;
+  }
+}