@api-client/core 0.3.3 → 0.3.4

package/src/models/AuthorizationData.ts

@@ -0,0 +1,60 @@
+export interface IAuthorizationData {
+  username?: string;
+  password?: string;
+  domain?: string;
+}
+
+
+/**
+ * Represents an auth data stored in ARC's data store to be retrieved
+ * when the response status is 401.
+ * 
+ * Each entry represent a Basic or NTLM authorization.
+ */
+export class AuthorizationData {
+  username?: string;
+  password?: string;
+  domain?: string;
+
+  /**
+   * @param input The provider definition used to restore the state.
+   */
+  constructor(input?: string|IAuthorizationData) {
+    let init: IAuthorizationData;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {};
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new provider clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the provider is not an ARC provider object.
+   */
+  new(init: IAuthorizationData): void {
+    const { username, password, domain } = init;
+    this.username = username;
+    this.password = password;
+    this.domain = domain;
+  }
+
+  toJSON(): IAuthorizationData {
+    const result:IAuthorizationData = {
+    };
+    if (this.username) {
+      result.username = this.username;
+    }
+    if (this.password) {
+      result.password = this.password;
+    }
+    if (this.domain) {
+      result.domain = this.domain;
+    }
+    return result;
+  }
+}

package/src/models/Backend.ts

@@ -0,0 +1,107 @@
+export type BackendMode = 'single-user' | 'multi-user';
+
+export interface IBackendInfo {
+  /**
+   * The model the store is on.
+   * 
+   * The `single-user` mode is the default mode where external user authentication is not required
+   * (but clients must use the auth token issued by the session endpoint).
+   * 
+   * In the `multi-user` model the authentication configuration is required and the user must 
+   * authenticate through an external identity provider (by default Open ID Connect is supported).
+   * After that the client has to create an authenticated session in the store service and use
+   * the token with the API calls.
+   * 
+   * @default single-user
+   */
+  mode: BackendMode;
+  /**
+   * Optional, the store base path when set on the configuration.
+   */
+  prefix?: string;
+  /**
+   * The path to the authentication endpoint.
+   */
+  authPath: string;
+}
+
+export interface IBackendCommand {
+  /**
+   * Optional path. When not set the path is the URL of the web socket channel.
+   */
+  path?: string;
+  /**
+   * The operation to perform
+   */
+  operation: 'delete' | 'patch' | 'create';
+  /**
+   * The command data.
+   */
+  value?: unknown;
+}
+
+export interface IBackendMessage {
+  /**
+   * The message type. Usually it is an `event`, meaning, a data change notification.
+   */
+  type: 'event';
+  /**
+   * In most cases an event has data associated with it like the created object or 
+   * the patch that has been applied to the object.
+   * Not set for events related to deleting an object.
+   */
+  data?: unknown;
+}
+
+export interface IBackendEvent extends IBackendMessage {
+  /**
+   * The operation that has been performed on the resource.
+   * 
+   * Note, `updated` is when the entire object must be revalidated in the opposite
+   * to `patch` where the patch should be applied to the object.
+   */
+  operation: 'created' | 'updated' | 'patch' | 'deleted' | 'access-granted' | 'access-removed';
+  /**
+   * The kind of data that has been changed.
+   */
+  kind: string;
+  /**
+   * For update events it is the key of the updated object.
+   */
+  id?: string;
+}
+
+export interface IListResponse {
+  /**
+   * The cursor to use with the next query.
+   * Not set when no more results.
+   */
+  cursor?: string;
+  /**
+   * The list of objects returned from the store.
+   */
+  data: unknown[];
+}
+
+export interface IListOptions {
+  /**
+   * Page cursor to use with the query.
+   */
+  cursor?: string;
+  /**
+   * Number of items in the result.
+   * Ignored when `cursor` is set.
+   * 
+   * Note, when changing the number of items in the result
+   * you need to start listing over again.
+   */
+  limit?: number;
+  /**
+   * Supported by some endpoints. When set it performs a query on the data store.
+   */
+  query?: string;
+  /**
+   * Only with the `query` property. Tells the system in which fields to search for the query term.
+   */
+  queryField?: string[];
+}

package/src/models/ClientCertificate.ts

@@ -0,0 +1,68 @@
+export type CertificateType = 'p12' | 'pem';
+
+/**
+ * Represents a single certificate object (cert/key)
+ */
+export interface ICertificate {
+  /**
+   * The certificate to use.
+   * The `p12` type certificate must be a Buffer.
+   */
+  data: string|ArrayBuffer|Buffer|Uint8Array;
+  /**
+   * A passphrase to use to unlock the certificate.
+   */
+  passphrase?: string;
+  /**
+   * The original data type of the certificate. This is used by the data store
+   * to move between buffers and string values stored in the store.
+   * By any means, outside the internal procedure of the data store this
+   * filed is always `undefined` and the `data` contains the original data format.
+   */
+  type?: string;
+}
+
+/**
+ * Represents a complete certificate configuration required to make
+ * a HTTP request.
+ */
+export interface IRequestCertificate {
+ /**
+   * Certificate type. Either `p12` or `pem`.
+   */
+  type: CertificateType;
+  /**
+   * Certificate or list of certificates to use.
+   */
+  cert: ICertificate|ICertificate[];
+  /**
+   * Key for the `pem` type certificate.
+   */
+  key?: ICertificate|ICertificate[];
+}
+
+/**
+ * Client certificate index definition for listings. 
+ */
+export interface ICertificateIndex {
+  /**
+   * Certificate type. Either `p12` or `pem`.
+   */
+  type: CertificateType;
+  /**
+   * Custom name of the certificate.
+   */
+  name: string;
+  /**
+   * Timestamp when the certificate was inserted into the data store.
+   * Required when returning a result. Auto-generated when inserting, if missing.
+   */
+  created?: number;
+}
+
+/**
+ * A base client certificate object used in ARC to create / list objects.
+ * This is not a data entity but rather something used to outside of a context of a data store.
+ */
+export interface IClientCertificate extends IRequestCertificate, ICertificateIndex {
+}

package/src/models/Environment.ts

@@ -0,0 +1,279 @@
+import { Property, IProperty } from './Property.js';
+import { Server, IServer } from './Server.js';
+import { IThing, Thing, Kind as ThingKind } from './Thing.js';
+import v4 from '../lib/uuid.js';
+import { ARCVariable } from './legacy/models/Variable.js';
+
+export interface IEnvironmentCloneOptions {
+  /**
+   * By default it revalidates (re-creates) keys in the environment.
+   * Set this to true to not make any changes to the keys.
+   */
+  withoutRevalidate?: boolean;
+}
+
+/**
+ * A project environment definition.
+ */
+export interface IEnvironment {
+  kind: 'ARC#Environment';
+  /**
+   * The identifier of the environment.
+   */
+  key: string;
+  /**
+   * The environment's meta info.
+   */
+  info: IThing;
+  /**
+   * The server's definition for the environment.
+   * When a server is defined for the environment then all request that have no 
+   * absolute URL will inherit this server configuration.
+   */
+  server?: IServer;
+  /**
+   * The variables added to this project.
+   * It overrides application defined variables.
+   */
+  variables: IProperty[];
+  /**
+   * When set this configuration does not allow to be extended by the parent object's environment configuration.
+   * By default an environment can be extended by the parent object's values.
+   */
+  encapsulated?: boolean;
+  /**
+   * The security to be applied to all requests that are going to this environment.
+   */
+  security?: unknown;
+}
+
+export const Kind = 'ARC#Environment';
+
+/**
+ * An environment is applied to a project or a folder.
+ * It consists of a list of variables and a server configuration.
+ * This allows to apply the runtime configuration just by changing the environment.
+ */
+export class Environment {
+  kind = Kind;
+  key = '';
+  /**
+   * The name of the environment.
+   */
+  info: Thing = new Thing({ kind: ThingKind });
+  /**
+   * The variables added to this project.
+   * It overrides application defined variables.
+   */
+  variables: Property[] = [];
+  /**
+   * The server's definition for the environment.
+   * When a server is defined for the environment then all request that have no 
+   * absolute URL will inherit this server configuration.
+   */
+  server?: Server;
+  /**
+   * When set this configuration does not allow to be extended by the parent object's environment configuration.
+   * By default an environment can be extended by the parent object's values.
+   * 
+   * When encapsulation is disabled you can, for example, skip server definition and only overwrite variables. 
+   */
+  encapsulated = false;
+  /**
+   * The security to be applied to all requests that are going to this server.
+   */
+  security?: unknown;
+  
+  /**
+   * Creates a new Environment object from a name.
+   * 
+   * @param name The name to set.
+   */
+  static fromName(name: string): Environment {
+    const key = v4();
+    const info = new Thing({ kind: ThingKind, name });
+    const definition = new Environment({
+      key,
+      kind: Kind,
+      info: info.toJSON(),
+      variables: [],
+    });
+    return definition;
+  }
+
+  static fromLegacyVariables(name: string, variables: ARCVariable[]): Environment {
+    const key = v4();
+    const info = new Thing({ kind: ThingKind, name });
+    const definition = new Environment({
+      key,
+      kind: Kind,
+      info: info.toJSON(),
+      variables: [],
+    });
+    variables.forEach((i) => {
+      const name = i.variable || i.name;
+      const property = Property.fromApiType(i);
+      property.name = name;
+      definition.variables.push(property);
+    });
+    return definition;
+  }
+
+  /**
+   * @param input The environment definition used to restore the state.
+   */
+  constructor(input?: string|IEnvironment) {
+    let init: IEnvironment;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        key: v4(),
+        info: {
+          kind: ThingKind,
+          name: '',
+        },
+        variables: [],
+      };
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new environment clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the environment is not an ARC environment. 
+   */
+  new(init: IEnvironment): void {
+    if (!Environment.isEnvironment(init)) {
+      throw new Error(`Not an ARC environment.`);
+    }
+    const { key=v4(), variables, info, server, encapsulated=false, security } = init;
+    this.kind = Kind;
+    this.key = key;
+    this.encapsulated = encapsulated;
+    this.security = security;
+    if (Array.isArray(variables)) {
+      this.variables = variables.map(i => new Property(i))
+    } else {
+      this.variables = [];
+    }
+    if (server) {
+      this.server = new Server(server);
+    } else {
+      this.server = undefined;
+    }
+    if (info) {
+      this.info = new Thing(info);
+    } else {
+      this.info = new Thing({ kind: ThingKind, name: '' });
+    }
+  }
+
+  /**
+   * Checks whether the input is a definition of a environment.
+   */
+  static isEnvironment(input: unknown): boolean {
+    const typed = input as IEnvironment;
+    if (!input || typed.kind !== Kind) {
+      return false;
+    }
+    return true;
+  }
+
+  toJSON(): IEnvironment {
+    const { variables=[], encapsulated=false, server } = this;
+    const result: IEnvironment = {
+      kind: Kind,
+      key: this.key,
+      info: this.info.toJSON(),
+      variables: variables.map((v) => v.toJSON()),
+      encapsulated,
+    };
+    if (server) {
+      result.server = server.toJSON();
+    }
+    if (this.security) {
+      result.security = this.security;
+    }
+    return result;
+  }
+
+  addVariable(name: string, value: unknown): Property;
+  addVariable(variable: IProperty): Property;
+
+  /**
+   * Adds a new variable to the list of variables.
+   * It makes sure the variables property is initialized.
+   */
+  addVariable(variableOrName: IProperty|string, value?: unknown): Property {
+    if (!Array.isArray(this.variables)) {
+      this.variables = [];
+    }
+    let prop: Property;
+    if (typeof variableOrName === 'string') {
+      prop = Property.fromType(variableOrName, value);
+    } else {
+      prop = new Property(variableOrName);
+    }
+    this.variables.push(prop);
+    return prop;
+  }
+
+  /**
+   * Reads the server configuration.
+   * @param force When set then it creates a server instance when missing.
+   */
+  getServer(force?: boolean): Server|undefined {
+    if (!this.server && !force) {
+      return undefined;
+    }
+    
+    if (!this.server) {
+      this.server = new Server();
+    }
+    return this.server;
+  }
+
+  /**
+   * Adds a new server definition.
+   * @param uri The base URI to create the server from
+   */
+  addServer(uri: string): Server;
+
+  /**
+   * Adds a new server definition.
+   * @param info The server definition.
+   */
+  addServer(info: IServer): Server;
+
+  /**
+   * Adds a new server definition.
+   * @param uriOrInfo Either URI to create the server from or the definition of the server.
+   */
+  addServer(uriOrInfo: string | IServer): Server {
+    let srv: Server;
+    if (typeof uriOrInfo === 'string') {
+      srv = Server.fromUri(uriOrInfo);
+    } else {
+      srv = new Server(uriOrInfo);
+    }
+    this.server = srv;
+    return srv;
+  }
+
+  /**
+   * Makes a copy of this environment
+   * @param opts Cloning options.
+   */
+  clone(opts: IEnvironmentCloneOptions = {}): Environment {
+    const copy = new Environment(this.toJSON());
+    if (!opts.withoutRevalidate) {
+      copy.key = v4();
+    }
+    return copy;
+  }
+}

package/src/models/ErrorResponse.ts

@@ -0,0 +1,101 @@
+import { IHttpResponse, HttpResponse, Kind } from './HttpResponse.js';
+import { ErrorResponse as LegacyErrorResponse } from './legacy/request/ArcResponse.js';
+import { PayloadSerializer } from '../lib/transformers/PayloadSerializer.js';
+import { Normalizer } from './legacy/Normalizer.js';
+
+export interface IErrorResponse extends IHttpResponse {
+  /**
+   * An error associated with the response
+   */
+  error: string | Error;
+}
+
+export class ErrorResponse extends HttpResponse {
+  /**
+   * An error associated with the response
+   */
+  error = new Error('Unknown error');
+
+  /**
+   * @returns The same Error or new Error instance when passed string.
+   */
+  static ensureError(error: string | Error): Error {
+    return typeof error === 'string' ? new Error(error) : error;
+  }
+
+  /**
+   * @param error The error message or Error object to use.
+   */
+  static fromError(error: Error | string): ErrorResponse {
+    const err = ErrorResponse.ensureError(error);
+    return new ErrorResponse({
+      kind: Kind,
+      status: 0,
+      error: err,
+    });
+  }
+
+  static async fromLegacy(input: LegacyErrorResponse): Promise<ErrorResponse> {
+    const init: IErrorResponse = {
+      kind: Kind,
+      status: input.status || 0,
+      error: input.error ? ErrorResponse.ensureError(input.error) : new Error('Unknown error'),
+    };
+    if (input.headers) {
+      init.headers = input.headers;
+    }
+    if (input.statusText) {
+      init.statusText = input.statusText;
+    }
+    if (input.payload) {
+      const orig = Normalizer.restoreTransformedPayload(input.payload);
+      if (orig) {
+        init.payload = await PayloadSerializer.serialize(orig);
+      }
+    }
+    return new ErrorResponse(init);
+  }
+
+  /**
+   * @param input The request definition used to restore the state.
+   */
+  constructor(input?: string|IErrorResponse) {
+    super(input);
+    let init: IErrorResponse;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        status: 0,
+        error: new Error('Unknown error'),
+      };
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new request clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the object is not an ARC request.
+   */
+  new(init: IErrorResponse): void {
+    super.new(init);
+    if (init.error) {
+      this.error = ErrorResponse.ensureError(init.error);
+    }
+  }
+
+  toJSON(): IErrorResponse {
+    const response = super.toJSON() as IErrorResponse;
+    response.error = this.error;
+    return response;
+  }
+
+  static isErrorResponse(input: unknown): boolean {
+    const typed = input as IErrorResponse;
+    return !!typed.error;
+  }
+}

package/src/models/HistoryIndex.ts

@@ -0,0 +1,76 @@
+/**
+ * An object that is stored in ARCs internal store to build history navigation.
+ * It does not contain all the history data. Just the ones that are presented in the UI.
+ */
+export interface IHistoryIndex {
+  /**
+   * Timestamp when the request was last updated.
+   */
+  updated: number;
+  /**
+   * A timestamp of the midnight when the request object was updated
+   */
+  midnight: number;
+  /**
+   * The request URL
+   */
+  url: string;
+  /**
+   * HTTP method name
+   */
+  method: string;
+}
+
+export class HistoryIndex {
+  /**
+   * Timestamp when the request was last updated.
+   */
+  updated = 0;
+  /**
+   * A timestamp of the midnight when the request object was updated
+   */
+  midnight = 0;
+  /**
+   * The request URL
+   */
+  url = '';
+  /**
+   * HTTP method name
+   */
+  method = 'GET';
+
+  constructor(input?: string|IHistoryIndex) {
+    let init: IHistoryIndex;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        updated: 0,
+        midnight: 0,
+        url: '',
+        method: 'GET',
+      };
+    }
+    this.new(init);
+  }
+
+  new(init: IHistoryIndex): void {
+    const { updated=0, midnight=0, url='', method='GET' } = init;
+    this.updated = updated;
+    this.midnight = midnight;
+    this.url = url;
+    this.method = method;
+  }
+
+  toJSON(): IHistoryIndex {
+    const result: IHistoryIndex = {
+      updated: this.updated,
+      midnight: this.midnight,
+      url: this.url,
+      method: this.method,
+    };
+    return result;
+  }
+}