@api-client/core 0.6.31 → 0.7.2

package/src/models/http-actions/HttpActions.ts

@@ -0,0 +1,270 @@
+import { SameSiteValue } from '../../cookies/CookieParser.js';
+
+export const ReadDataStepKind = 'HttpAction#ReadData';
+export const SetDataStepKind = 'HttpAction#SetData';
+export const SetVariableStepKind = 'HttpAction#SetVariable';
+export const SetCookieStepKind = 'HttpAction#SetCookie';
+export const DeleteCookieStepKind = 'HttpAction#DeleteCookie';
+
+export enum ActionSourceEnum {
+  /**
+   * The request object.
+   */
+  request = 'request',
+  /**
+   * The response object.
+   */
+  response = 'response',
+  /**
+   * A variable from the current environment.
+   */
+  variable = 'variable',
+}
+
+export enum ActionOperatorEnum {
+  equal = "equal",
+  notEqual = "not-equal",
+  greaterThan = "greater-than",
+  greaterThanEqual = "greater-than-equal",
+  lessThan = "less-than",
+  lessThanEqual = "less-than-equal",
+  contains = "contains",
+  regex = "regex",
+}
+
+export enum ActionRequestDataEnum {
+  url = "url",
+  method = "method",
+  headers = "headers",
+  body = "body"
+}
+
+export enum ActionResponseDataEnum {
+  url = "url",
+  status = "status",
+  headers = "headers",
+  body = "body"
+}
+
+/**
+ * A flow represents a series of actions to be performed one-by-one after the HTTP request is sent or when the response 
+ * is ready.
+ */
+export interface IHttpActionFlow {
+  /**
+   * The description of the flow
+   */
+  description?: string;
+  /**
+   * Describes when the flow is executed.
+   * The `request` means the flow is executed before the request is sent to the HTTP engine.
+   * The `response` means the flow is executed after the response has been received in full, but before reporting 
+   * the response to the UI.
+   */
+  trigger: 'request' | 'response';
+  /**
+   * The ordered list of actions to execute.
+   */
+  actions: IHttpAction[];
+}
+
+/**
+ * Describes a single action in a flow.
+ * An action can have a condition that is checked against the current context.
+ * Action is not executed when the condition is not meet.
+ * 
+ * Each action has one or more steps (when 0 items then the action is ignored). Each step performs a task.
+ * The result of a task is passed to the next step as an input. The result of a task may be `void`, `null`, or `undefined` which is treated as `void`.
+ */
+export interface IHttpAction {
+  /**
+   * The description of the action
+   */
+  description?: string;
+  /**
+   * A condition to check before performing the action.
+   */
+  condition?: IHttpCondition;
+  /**
+   * The list of steps to perform. This is an ordered list of action tasks.
+   * Each step is described by the `kind` property which tells the runner what action to perform.
+   */
+  steps: IActionStep[];
+}
+
+/**
+ * A condition to execute for an action.
+ */
+export interface IHttpCondition {
+  /**
+   * The main data source.
+   * In the legacy actions this was `type`.
+   */
+  source?: ActionSourceEnum;
+  /**
+   * Source of the data.
+   * In the legacy actions this was `source`.
+   * This is not required when the source is not `request` or `response`.
+   */
+  data?: ActionRequestDataEnum | ActionResponseDataEnum;
+  /**
+   * The path to the data.
+   * For JSON value use https://jmespath.org/ syntax.
+   * For XML use xpath.
+   * For any other use a simple path to the data separated by dot (e.g. headers.content-type)
+   */
+  path?: string;
+  /**
+   * The comparison operator.
+   */
+  operator?: ActionOperatorEnum;
+  /**
+   * The value to compare the read result.
+   * In runtime, the type is casted to the same type as read value.
+   * 
+   * When this is not set it compares to an empty string value or `0`.
+   * 
+   * In ARC actions this was the `predictedValue`.
+   */
+  value?: string;
+}
+
+export interface IActionStep {
+  /**
+   * The kind of the action to perform.
+   */
+  kind: string;
+  /**
+   * Whether the step is disabled in the flow.
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Reads the data from various sources.
+ */
+export interface IReadDataStep extends IActionStep {
+  kind: typeof ReadDataStepKind;
+  /**
+   * The main data source.
+   * In the legacy actions this was `type`.
+   */
+  source?: ActionSourceEnum;
+  /**
+   * Source of the data.
+   * In the legacy actions this was `source`.
+   * This is not required when the source is not `request` or `response`.
+   */
+  data?: ActionRequestDataEnum | ActionResponseDataEnum;
+  /**
+   * The path to the data.
+   * For JSON value use https://jmespath.org/ syntax.
+   * For XML use xpath.
+   * For any other use a simple path to the data separated by dot (e.g. headers.content-type)
+   */
+  path?: string;
+}
+
+/**
+ * Sets a manually defined value that can be passed to the next step.
+ */
+export interface ISetDataStep extends IActionStep {
+  kind: typeof SetDataStepKind;
+  /**
+   * The value to return to the next step.
+   * This is always a string. Use the `dataType` to determine the correct data type.
+   */
+  value: string;
+  /**
+   * The data type of the value. This is a value prefixed with 
+   * `http://www.w3.org/2001/XMLSchema#` or `http://a.ml/vocabularies/shapes#`.
+   * 
+   * Examples:
+   * 
+   * - `http://www.w3.org/2001/XMLSchema#boolean`
+   * - `http://www.w3.org/2001/XMLSchema#string`
+   * - `http://www.w3.org/2001/XMLSchema#number`
+   * - `http://www.w3.org/2001/XMLSchema#integer`
+   * - `http://www.w3.org/2001/XMLSchema#long`
+   * - `http://a.ml/vocabularies/shapes#number`
+   * - `http://a.ml/vocabularies/shapes#integer`
+   * - `http://a.ml/vocabularies/shapes#double`
+   * - ...
+   * 
+   * @default `http://www.w3.org/2001/XMLSchema#string`
+   */
+  dataType?: string;
+}
+
+/**
+ * A step that accepts an input from the previous step and sets a variable in the current environment
+ * with this value. If the value is `void`, `null`, or `undefined` then the variable is removed from the 
+ * environment.
+ * 
+ * All variables are strings.
+ */
+export interface ISetVariableStep extends IActionStep {
+  kind: typeof SetVariableStepKind;
+  /**
+   * The name of the variable to set
+   */
+  name: string;
+}
+
+/**
+ * A step that allows to set a cookie with the value returned by a previous step.
+ */
+export interface ISetCookieStep extends IActionStep {
+  kind: typeof SetCookieStepKind;
+  /**
+   * Name of the cookie
+   */
+  name: string;
+  /**
+   * The URL associated with the cookie. When not set it uses the request URL or the request URL of the last redirect.
+   */
+  url?: string;
+  /**
+   * The cookie expiration time. It can be a valid cookie date or a string representing a relative time to "now"
+   * like `4d`, `600s`, etc.
+   */
+  expires?: string;
+  /**
+   * Whether the cookie is host only
+   */
+  hostOnly?: boolean;
+  /**
+   * Whether the cookie is HTTP only
+   */
+  httpOnly?: boolean;
+  /**
+   * Whether the cookie is HTTPS only
+   */
+  secure?: boolean;
+  /**
+   * Whether the cookie is a session cookie
+   */
+  session?: boolean;
+  /**
+   * The SameSite parameter of the cookie.
+   * https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#creating_cookies
+   */
+  sameSite?: SameSiteValue;
+}
+
+/**
+ * A step allowing to delete a cookie for the given configuration.
+ * This step does not require an input.
+ */
+export interface IDeleteCookieStep extends IActionStep {
+  kind: typeof DeleteCookieStepKind;
+  /**
+   * The URL associated with the cookie. When not set it uses the request URL or the request URL of the last redirect.
+   */
+  url?: string;
+  /**
+   * Name of the cookie to remove.
+   * When not set it removes all cookies for the URL.
+   */
+  name?: string;
+}

package/src/models/http-actions/LegacyTranslator.ts

@@ -0,0 +1,223 @@
+import { RequestActions as LegacyRequestActions } from '../../models/legacy/request/ArcRequest.js';
+import { RunnableAction as LegacyRunnable, Condition as LegacyCondition, Action as LegacyAction, SetCookieConfig, SetVariableConfig, DeleteCookieConfig, DataSourceConfiguration } from '../../models/legacy/actions/Actions.js';
+import { IHttpActionFlow, IHttpAction, IHttpCondition, ActionSourceEnum, ActionRequestDataEnum, ActionResponseDataEnum, ActionOperatorEnum, IActionStep, ISetDataStep, SetDataStepKind, IReadDataStep, ReadDataStepKind, ISetCookieStep, SetCookieStepKind, IDeleteCookieStep, DeleteCookieStepKind } from './HttpActions.js';
+import { AmfNamespace } from '../../amf/definitions/Namespace.js';
+
+/**
+ * Allows to translate the old ARC actions into Action flows.
+ */
+export class LegacyTranslator {
+  static translate(action: LegacyRequestActions): IHttpActionFlow[] {
+    const { request, response } = action;
+    const result: IHttpActionFlow[] = [];
+
+    if (Array.isArray(request) && request.length) {
+      const flow: IHttpActionFlow = {
+        trigger: 'request',
+        actions: this._translateRunnables(request),
+      };
+      result.push(flow);
+    }
+
+    if (Array.isArray(response) && response.length) {
+      const flow: IHttpActionFlow = {
+        trigger: 'response',
+        actions: this._translateRunnables(response),
+      };
+      result.push(flow);
+    }
+    return result;
+  }
+
+  protected static _translateRunnables(runnables: LegacyRunnable[]): IHttpAction[] {
+    const result: IHttpAction[] = [];
+    runnables.forEach((runnable) => {
+      const actions = this._translateRunnable(runnable);
+      actions.forEach(item => result.push(item));
+    });
+    return result;
+  }
+
+  protected static _translateRunnable(runnable: LegacyRunnable): IHttpAction[] {
+    const result: IHttpAction[] = [];
+    const { actions, condition } = runnable;
+    actions.forEach((action) => {
+      const current: IHttpAction = {
+        steps: this._translateAction(action),
+      };
+      if (condition) {
+        current.condition = this._translateCondition(condition);
+      }
+      result.push(current);
+    });
+    return result;
+  }
+
+  protected static _translateCondition(runnable: LegacyCondition): IHttpCondition | undefined {
+    const { source, alwaysPass, operator, path, predictedValue, type } = runnable;
+    if (alwaysPass) {
+      // in the flow, if there's no condition the steps are always executed.
+      return undefined
+    }
+
+    const result: IHttpCondition = {};
+    if (typeof path === 'string') {
+      result.path = path;
+    }
+    if (type) {
+      switch (type) {
+        case 'request': result.source = ActionSourceEnum.request; break;
+        case 'response': result.source = ActionSourceEnum.response; break;
+      }
+    }
+    if (type && source) {
+      if (type === 'request') {
+        result.data = source as ActionRequestDataEnum;
+      }
+      if (type === 'response') {
+        result.data = source as ActionResponseDataEnum;
+      }
+    }
+    if (predictedValue) {
+      result.value = String(predictedValue);
+    }
+    if (operator) {
+      switch (operator) {
+        case 'contains': result.operator = ActionOperatorEnum.contains; break;
+        case 'equal': result.operator = ActionOperatorEnum.equal; break;
+        case 'greater-than': result.operator = ActionOperatorEnum.greaterThan; break;
+        case 'greater-than-equal': result.operator = ActionOperatorEnum.greaterThanEqual; break;
+        case 'less-than': result.operator = ActionOperatorEnum.lessThan; break;
+        case 'less-than-equal': result.operator = ActionOperatorEnum.lessThanEqual; break;
+        case 'not-equal': result.operator = ActionOperatorEnum.notEqual; break;
+        case 'regex': result.operator = ActionOperatorEnum.regex; break;
+      }
+    }
+    return result;
+  }
+
+  protected static _translateAction(item: LegacyAction): IActionStep[] {
+    switch (item.name) {
+      case 'set-cookie': return this._translateSetCookieAction(item);
+      case 'set-variable': return this._translateSetVariableAction(item);
+      case 'delete-cookie': return this._translateDeleteCookieAction(item);
+      default: return [];
+    }
+  }
+
+  protected static _translateSetCookieAction(item: LegacyAction): IActionStep[] {
+    const legacy = item.config as SetCookieConfig;
+
+    const steps: IActionStep[] = [];
+    const ds = this._translateDataSource(legacy.source);
+    steps.push(ds);
+
+    const action: ISetCookieStep = {
+      kind: SetCookieStepKind,
+      name: legacy.name,
+    };
+    if (item.enabled === false) {
+      action.enabled = item.enabled;
+    }
+    if (legacy.url) {
+      action.url = legacy.url;
+    }
+    if (legacy.expires) {
+      action.expires = legacy.expires;
+    }
+    if (typeof legacy.hostOnly === 'boolean') {
+      action.hostOnly = legacy.hostOnly;
+    }
+    if (typeof legacy.httpOnly === 'boolean') {
+      action.httpOnly = legacy.httpOnly;
+    }
+    if (typeof legacy.secure === 'boolean') {
+      action.secure = legacy.secure;
+    }
+    if (typeof legacy.session === 'boolean') {
+      action.session = legacy.session;
+    }
+    steps.push(action);
+    
+    return steps;
+  }
+
+  protected static _translateSetVariableAction(item: LegacyAction): IActionStep[] {
+    const legacy = item.config as SetVariableConfig;
+
+    const steps: IActionStep[] = [];
+    const ds = this._translateDataSource(legacy.source);
+    steps.push(ds);
+
+    const action: ISetCookieStep = {
+      kind: SetCookieStepKind,
+      name: legacy.name,
+    };
+    if (item.enabled === false) {
+      action.enabled = item.enabled;
+    }
+    steps.push(action);
+
+    return steps;
+  }
+
+  protected static _translateDeleteCookieAction(item: LegacyAction): IActionStep[] {
+    const legacy = item.config as DeleteCookieConfig;
+
+    const steps: IActionStep[] = [];
+    
+    const action: IDeleteCookieStep = {
+      kind: DeleteCookieStepKind,
+    };
+    if (item.enabled === false) {
+      action.enabled = item.enabled;
+    }
+    if (legacy.name && !legacy.removeAll) {
+      action.name = legacy.name;
+    }
+    if (legacy.url && !legacy.useRequestUrl) {
+      action.url = legacy.url;
+    }
+    steps.push(action);
+
+    return steps;
+  }
+
+  protected static _translateDataSource(source: DataSourceConfiguration): IActionStep {
+    if (source.value) {
+      const dataSet: ISetDataStep = {
+        kind: SetDataStepKind,
+        value: source.value,
+        dataType: AmfNamespace.w3.xmlSchema.string,
+      };
+      return dataSet;
+    }
+
+    // Note, there's no way for us to translate the old "iterator" configuration
+    // to the current syntax. We just drop it.
+
+    const { path, type, source: legacySource } = source;
+    const result: IReadDataStep = {
+      kind: ReadDataStepKind,
+    };
+
+    if (typeof path === 'string') {
+      result.path = path;
+    }
+    if (type) {
+      switch (type) {
+        case 'request': result.source = ActionSourceEnum.request; break;
+        case 'response': result.source = ActionSourceEnum.response; break;
+      }
+    }
+    if (type && legacySource) {
+      if (type === 'request') {
+        result.data = legacySource as ActionRequestDataEnum;
+      }
+      if (type === 'response') {
+        result.data = legacySource as ActionResponseDataEnum;
+      }
+    }
+    return result;
+  }
+}

package/src/models/store/Backend.ts

@@ -20,7 +20,25 @@ export interface IBackendInfo {
    * @default single-user
    */
   mode: BackendMode;
-  
+
+  /**
+   * The list of capabilities this store has.
+   * This is defined by the store and clients should use values defined there to detect supported capabilities.
+   * 
+   * Example capabilities include:
+   * - authorization
+   * - authentication
+   * - files
+   * - history
+   * - certificates
+   * - etc.
+   * 
+   * This could be potentially replaced by the version number of the store library but this
+   * is more future-proof in case we go into a distributed architecture with the store.
+   * Clients should look for a capability rather the version of the store.
+   */
+  capabilities: string[];
+
   /**
    * Client authentication configuration
    */
@@ -124,7 +142,7 @@ export interface IListResponse<T = unknown> {
   /**
    * The list of objects returned from the store.
    */
-  data: T[];
+  items: T[];
 }
 
 export interface IListOptions {
@@ -300,3 +318,131 @@ export interface IPatchRevision extends IPatchInfo {
    */
   revert: JsonPatch;
 }
+
+/**
+ * Describes a batch read operation body.
+ */
+export interface IBatchRead {
+  /**
+   * The keys of the items to read. The response has the ordered list of results.
+   */
+  items: string[];
+}
+
+/**
+ * Describes a result of the batch read operation body.
+ */
+export interface IBatchReadResult<T = unknown> {
+  /**
+   * The ordered list of read entities.
+   * Each element can be null/undefined when the item cannot be read.
+   * 
+   * The batch operation does not return specific errors. Use the direct read operation
+   * for the detailed error.
+   */
+  items: (T | null | undefined)[];
+}
+
+/**
+ * Describes a batch update/create operation body.
+ */
+export interface IBatchUpdate<T = unknown> {
+  /**
+   * The items to add or update in a batch operation.
+   */
+  items: T[];
+  /**
+   * The optional key of the parent object of the created/updated items.
+   */
+  parent?: string;
+}
+
+/**
+ * Describes a result of the batch update/create operation body.
+ */
+export interface IBatchUpdateResult<T = unknown> {
+  /**
+   * The ordered list of create/update result for each item.
+   */
+  items: T[];
+  /**
+   * The optional key of the parent object of the created/updated items.
+   */
+  parent?: string;
+}
+
+/**
+ * Describes a batch delete operation body.
+ */
+export interface IBatchDelete {
+  /**
+   * The list of keys of items to delete.
+   */
+  items: string[];
+  /**
+   * The optional key of the parent object of the deleted items.
+   * Not used by the store but reported back through the events.
+   */
+  parent?: string;
+}
+
+/**
+ * Describes a result of the batch delete operation.
+ */
+export interface IBatchDeleteResult {
+  /**
+   * The ordered list of delete result for each item.
+   * 
+   * The batch operation does not return specific errors. Use the direct delete operation
+   * for the detailed error.
+   */
+  items: (IDeleteRecord | undefined | null)[];
+}
+
+export interface IDeleteRecord {
+  /**
+   * The key of the removed object.
+   */
+  key: string;
+  /**
+   * The key of the parent object, if applicable.
+   */
+  parent?: string;
+}
+
+/**
+ * Describes a batch undelete operation body.
+ */
+export interface IBatchUndelete {
+  /**
+   * The list of keys of the items to undelete.
+   */
+  items: string[];
+  /**
+   * The optional key of the parent object of the deleted items.
+   */
+  parent?: string;
+}
+
+export interface IRevertResult<T = unknown> {
+  /**
+   * The data kind of the changed item.
+   */
+  kind?: string;
+  /**
+   * The key of the changed object.
+   */
+  key: string;
+  /**
+   * The updated object.
+   */
+  item?: T;
+  /**
+   * Optionally, when relevant, the key of the parent of the changed object.
+   */
+  parent?: string;
+}
+
+export interface IRevertResponse<T = unknown> {
+  items: (IRevertResult<T> | undefined)[];
+}

package/src/models/store/File.ts

@@ -5,6 +5,8 @@ import { IUser, Kind as UserKind } from './User.js';
 import { IThing, Thing } from '../Thing.js';
 import v4 from '../../lib/uuid.js';
 import { ICapabilities } from './Capabilities.js';
+// this causes error
+// import { Kind as WorkspaceKind } from '../Workspace.js';
 
 export const DefaultOwner = 'default';
 
@@ -18,7 +20,7 @@ export interface IStoredFile {
    */
   key: string;
   /**
-   * The projects's meta info.
+   * The file's meta info.
    */
   info: IThing;
   /**

package/src/models/store/User.ts

@@ -16,7 +16,7 @@ export interface IUserPicture {
    */
   url?: string;
   /**
-   * Alternative to the `imageUrl`. When set it is a data URL value of the image.
+   * Alternative to the `url`. When set it is a data URL value of the image.
    */
   data?: string;
 }
@@ -26,7 +26,7 @@ export const Kind = 'Core#User';
 interface BaseUser {
   kind: typeof Kind;
   /**
-   * Data store key of the user.
+   * The data store key of the user.
    */
   key: string;
   /**
@@ -42,7 +42,7 @@ interface BaseUser {
    */
   picture?: IUserPicture;
   /**
-   * General purpose tags field.
+   * A general purpose tags field.
    */
   tags?: string[];
   /**