@api-client/core 0.3.2 → 0.3.5

package/src/models/User.ts

@@ -0,0 +1,120 @@
+export type AccessControlLevel = 'read' | 'comment' | 'write' | 'admin' | 'owner';
+
+/**
+ * This is used in the communication with the backend to add/change user's access to the resource.
+ */
+export interface IUserAccessOperation {
+  /**
+   * The user id.
+   */
+  uid: string;
+}
+
+export interface IUserAccessAddOperation extends IUserAccessOperation {
+  op: "add";
+  /**
+   * The level that the user has access to.
+   */
+  value: AccessControlLevel;
+}
+
+export interface IUserAccessRemoveOperation extends IUserAccessOperation {
+  op: "remove";
+}
+
+export type UserAccessOperation = IUserAccessAddOperation | IUserAccessRemoveOperation;
+
+/**
+ * The definition of an access control.
+ * The user may have access to a workspace so this is the object describing the level of the workspace.
+ */
+export interface IAccessControl {
+  /**
+   * The data store key of the referenced object the user has access to.
+   */
+  key: string;
+  /**
+   * The level that the user has access to.
+   */
+  level: AccessControlLevel;
+}
+
+export interface IEmail {
+  /**
+   * When available the email of the user.
+   */
+  email?: string;
+  /**
+   * Whether the `email` was verified.
+   * Not verified emails should have limited use in the system.
+   */
+  verified?: boolean;
+}
+
+export interface IUserPicture {
+  /**
+   * When available, the URL to the user's picture image.
+   */
+  url?: string;
+  /**
+   * Alternative to the `imageUrl`. When set it is a data URL value of the image.
+   */
+  data?: string;
+}
+
+export const Kind = 'ARC#User';
+
+/**
+ * Represents a user in the system.
+ * This can be embedded in various situations like project's revision history,
+ * ACL, Authorization, etc.
+ * 
+ * Note, the store implementation may have additional fields that support external 
+ * identity providers. However, this is not exposed to the user through the API.
+ */
+export interface IUser {
+  /**
+   * Data store key of the user.
+   */
+  key: string;
+  /**
+   * The display name of the user.
+   */
+  name: string;
+  /**
+   * When available the email of the user.
+   */
+  email?: IEmail[];
+  /**
+   * The user picture to render.
+   */
+  picture?: IUserPicture;
+  /**
+   * General purpose tags field.
+   */
+  tags?: string[];
+  /**
+   * Optional user locale information.
+   */
+  locale?: string;
+  /**
+   * Optional metadata related to the auth provider.
+   */
+  provider?: unknown;
+}
+
+/**
+ * This object may be created for each user in the system.
+ * It describes to which spaces user has access to.
+ */
+export interface IUserSpaces {
+  /**
+   * The list of access to the spaces for the user.
+   */
+  spaces: IAccessControl[];
+  /**
+   * The data store key of the user that has access to the space.
+   * This is also the key of the entry.
+   */
+  user: string;
+}

package/src/models/WebApi.ts

@@ -0,0 +1,234 @@
+export const Kind = 'ARC#WebApi';
+
+/**
+ * @deprecated This was used in the old version of ARC.
+ */
+export interface ILegacyRestApi {
+  /**
+   * The ID of the index item that this entry refers to.
+   */
+  indexId: string;
+  /**
+   * Version name of the API
+   */
+  version: string;
+  /**
+   * API data model. It is the output of the AMF parser run on the API.
+   */
+  data: string;
+  /**
+   * The AMF parser version used to parse this document.
+   */
+  amfVersion?: string;
+}
+
+export interface IWebApi {
+  kind: typeof Kind;
+  /**
+   * The ID of the index item that this entry refers to.
+   */
+  indexId: string;
+  /**
+   * Version name of the API
+   */
+  version: string;
+  /**
+   * API data model. It is the output of the AMF parser run on the API.
+   * This is left for compatibility.
+   * @deprecated This was used in the old version of ARC. v18 uses the `path` with the location of the API project.
+   */
+  data?: string;
+  /**
+   * The AMF parser version used to parse this document.
+   * This is left for compatibility.
+   * @deprecated This was used in the old version of ARC. v18 does not use this information.
+   */
+  amfVersion?: string;
+  /**
+   * The location of the API project. This can be any URI to get the sources of the API project.
+   */
+  path: string;
+  /**
+   * Optional information to point to the API's main file.
+   */
+  main?: string;
+  /**
+   * The API format's media type.
+   */
+  mime?: string;
+  /**
+   * The API vendor. E.g. RAML 1.0, OAS 3.0, ASYNC 2.0, ...
+   */
+  vendor?: string;
+}
+
+export class WebApi {
+  kind = Kind;
+  /**
+   * The ID of the index item that this entry refers to.
+   */
+  indexId = '';
+  /**
+   * Version name of the API
+   */
+  version = '';
+  /**
+   * API data model. It is the output of the AMF parser run on the API.
+   * This is left for compatibility.
+   * @deprecated This was used in the old version of ARC. v18 uses the `path` with the location of the API project.
+   */
+  data?: string;
+  /**
+   * The AMF parser version used to parse this document.
+   * This is left for compatibility.
+   * @deprecated This was used in the old version of ARC. v18 does not use this information.
+   */
+  amfVersion?: string;
+  /**
+   * The location of the API project. This can be any URI to get the sources of the API project.
+   */
+  path = '';
+  /**
+   * Optional information to point to the API's main file.
+   */
+  main?: string;
+  /**
+   * The API format's media type.
+   */
+  mime?: string;
+  /**
+   * The API vendor. E.g. RAML 1.0, OAS 3.0, ASYNC 2.0, ...
+   */
+  vendor?: string;
+
+  /**
+   * Checks whether the object represents a legacy way of storing the web API data.
+   */
+  get isLegacy(): boolean {
+    return !!this.data;
+  }
+
+  /**
+   * Checks whether the object is the legacy schema for web API (formally known as RestAPI)
+   */
+  static isLegacy(api: unknown): boolean {
+    const legacy = api as ILegacyRestApi;
+    if (legacy.data) {
+      return true;
+    }
+    return false;
+  }
+
+  static fromLegacy(api: ILegacyRestApi): WebApi {
+    const { version, amfVersion, data, indexId } = api;
+    const init: IWebApi = {
+      kind: Kind,
+      version,
+      path: '',
+      indexId,
+    };
+    if (amfVersion) {
+      init.amfVersion = amfVersion;
+    }
+    if (data) {
+      init.data = data;
+    }
+    return new WebApi(init);
+  }
+
+  /**
+   * Creates an identifier of this web API object.
+   * @param indexId The id of the corresponding index item. This is usually the base URI of the API.
+   * @param version The version name of this web API.
+   * @returns The unique and reversible identifier of this web API.
+   */
+  static createId(indexId: string, version: string): string {
+    return `${indexId}|${version}`;
+  }
+
+  constructor(input?: string|IWebApi) {
+    let init: IWebApi;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        version: '',
+        path: '',
+        indexId: '',
+      };
+    }
+    this.new(init);
+  }
+
+  new(init: IWebApi): void {
+    const { version, data, amfVersion, path, main, mime, vendor, indexId } = init;
+    if (indexId) {
+      this.indexId = indexId;
+    } else {
+      this.indexId = '';
+    }
+    if (version) {
+      this.version = version;
+    } else {
+      this.version = '';
+    }
+    if (data) {
+      this.data = data;
+    } else {
+      this.data = undefined;
+    }
+    if (amfVersion) {
+      this.amfVersion = amfVersion;
+    } else {
+      this.amfVersion = undefined;
+    }
+    if (path) {
+      this.path = path;
+    } else {
+      this.path = '';
+    }
+    if (main) {
+      this.main = main;
+    } else {
+      this.main = undefined
+    }
+    if (mime) {
+      this.mime = mime;
+    } else {
+      this.mime = mime;
+    }
+    if (vendor) {
+      this.vendor = vendor;
+    } else {
+      this.vendor = undefined;
+    }
+  }
+
+  toJSON(): IWebApi {
+    const result: IWebApi = {
+      kind: Kind,
+      version: this.version,
+      path: this.path,
+      indexId: this.indexId,
+    };
+    if (this.data) {
+      result.data = this.data;
+    }
+    if (this.amfVersion) {
+      result.amfVersion = this.amfVersion;
+    }
+    if (this.main) {
+      result.main = this.main;
+    }
+    if (this.mime) {
+      result.mime = this.mime;
+    }
+    if (this.vendor) {
+      result.vendor = this.vendor;
+    }
+    return result;
+  }
+}

package/src/models/WebApiIndex.ts

@@ -0,0 +1,122 @@
+export const Kind = 'ARC#WebApiIndex';
+
+/**
+ * @deprecated This was used in the old version of ARC.
+ */
+export interface ILegacyWebApiIndex {
+  /**
+   * API title
+   */
+  title: string;
+  /**
+   * API media type
+   * @deprecated This has been renamed to `vendor`.
+   */
+  type: string;
+  /**
+   * API order on the list
+   */
+  order: number;
+  /**
+   * List of version names stored with this API.
+   */
+  versions: string[];
+  /**
+   * The latest added version name.
+   */
+  latest: string;
+}
+
+export interface IWebApiIndex {
+  kind: typeof Kind;
+  /**
+   * API title
+   */
+  title: string;
+  /**
+   * List of version names stored with this API.
+   */
+  versions: string[];
+  /**
+   * The latest added version name.
+   */
+  latest: string;
+  /**
+   * The API vendor. E.g. RAML 1.0, OAS 3.0, ASYNC 2.0, ...
+   */
+  vendor: string;
+}
+
+export class WebApiIndex {
+  kind = Kind;
+  /**
+   * API title
+   */
+  title = '';
+  /**
+   * List of version names stored with this API.
+   */
+  versions: string[] = [];
+  /**
+   * The latest added version name.
+   */
+  latest = '';
+  /**
+   * The API vendor. E.g. RAML 1.0, OAS 3.0, ASYNC 2.0, ...
+   */
+  vendor = '';
+
+  static isLegacy(api: unknown): boolean {
+    const legacy = api as ILegacyWebApiIndex;
+    return !!legacy.type;
+  }
+
+  static fromLegacy(api: ILegacyWebApiIndex): WebApiIndex {
+    const { title, type, versions=[], latest } = api;
+    const init: IWebApiIndex = {
+      kind: Kind,
+      title,
+      versions,
+      latest,
+      vendor: type,
+    };
+    return new WebApiIndex(init);
+  }
+
+  constructor(input?: string|IWebApiIndex) {
+    let init: IWebApiIndex;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        latest: '',
+        title: '',
+        vendor: '',
+        versions: [],
+      };
+    }
+    this.new(init);
+  }
+
+  new(init: IWebApiIndex): void {
+    const { latest='', title='', vendor='', versions=[] } = init;
+    this.latest = latest;
+    this.versions = versions;
+    this.title = title;
+    this.vendor = vendor;
+  }
+
+  toJSON(): IWebApiIndex {
+    const result: IWebApiIndex = {
+      kind: Kind,
+      latest: this.latest,
+      versions: this.versions,
+      title: this.title,
+      vendor: this.vendor,
+    };
+    return result;
+  }
+}

package/src/models/Workspace.ts

@@ -0,0 +1,182 @@
+import { AccessControlLevel } from "./User.js";
+import { IThing, Thing, Kind as ThingKind } from './Thing.js';
+import v4 from '../lib/uuid.js';
+
+export const Kind = 'ARC#Space';
+/**
+ * A definition of the working space for users.
+ * 
+ * A working space is a logical container in the data store
+ * created by the system users, where they can store their projects and other data.
+ */
+export interface IWorkspace {
+  kind: 'ARC#Space';
+  /**
+   * The space identifier.
+   */
+  key: string;
+  /**
+   * The environment's meta info.
+   */
+  info: IThing;
+  /**
+   * The list of users added to this space. May not be set when owner did not add anyone to the space.
+   */
+  users?: string[];
+  /**
+   * The owner of this space. The id of the User object.
+   * Set to `default` when there are no users in the system (no authentication).
+   */
+  owner: string;
+  /**
+   * The list of project keys added to the workspace.
+   * @deprecated This is not actually used.
+   */
+  projects: string[];
+}
+
+/**
+ * The workspace information set to a specific client what contains user specific data.
+ */
+export interface IUserWorkspace extends IWorkspace {
+  access: AccessControlLevel;
+}
+
+export const DefaultOwner = 'default';
+
+/**
+ * A definition of the working space for users.
+ * 
+ * A working space is a logical container in the data store
+ * created by the system users, where they can store their projects and other data.
+ */
+export class Workspace {
+  kind = Kind;
+  /**
+   * The space identifier.
+   */
+  key = '';
+  /**
+   * The name of the environment.
+   */
+  info: Thing = new Thing({ kind: ThingKind });
+  /**
+   * The list of users added to this space. May not be set when owner did not add anyone to the space.
+   */
+  users?: string[];
+  /**
+   * The owner of this space. The id of the User object.
+   * Set to `default` when there are no users in the system (no authentication).
+   */
+  owner = '';
+  /**
+   * The list of keys of projects added to the workspace.
+   * @deprecated This is not actually used.
+   */
+  projects: string[] = [];
+  /**
+   * Only set when the object was created from the data received by the ARC backend.
+   * Level access of the current user to the space.
+   * Note, this information is never serialized with the object.
+   */
+  access?: AccessControlLevel;
+
+  /**
+   * Creates a new Space object from a name.
+   * 
+   * @param name The name to set.
+   * @param owner The user id that is the owner of the space.
+   */
+  static fromName(name: string, owner = DefaultOwner): Workspace {
+    const key = v4();
+    const info = new Thing({ kind: ThingKind, name });
+    const definition = new Workspace({
+      key,
+      kind: Kind,
+      info: info.toJSON(),
+      owner,
+      projects: [],
+    });
+    return definition;
+  }
+
+  /**
+   * @param input The environment definition used to restore the state.
+   */
+  constructor(input?: string | IWorkspace | IUserWorkspace) {
+    let init: IWorkspace;
+    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: '',
+        },
+        owner: DefaultOwner,
+        projects: [],
+      };
+    }
+    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: IWorkspace | IUserWorkspace): void {
+    if (!Workspace.isWorkspace(init)) {
+      throw new Error(`Not an ARC space.`);
+    }
+    const { key = v4(), projects = [], info, owner = DefaultOwner, users } = init;
+    this.kind = Kind;
+    this.key = key;
+    this.projects = projects;
+    this.owner = owner;
+    if (info) {
+      this.info = new Thing(info);
+    } else {
+      this.info = new Thing({ kind: ThingKind, name: '' });
+    }
+    if (Array.isArray(users)) {
+      this.users = users;
+    } else {
+      this.users = [];
+    }
+    const typed = init as IUserWorkspace;
+    if (typed.access) {
+      this.access = typed.access;
+    }
+  }
+
+  /**
+   * Checks whether the input is a definition of an user space.
+   */
+  static isWorkspace(input: unknown): boolean {
+    const typed = input as IWorkspace;
+    if (!input || typed.kind !== Kind) {
+      return false;
+    }
+    return true;
+  }
+
+  toJSON(): IWorkspace {
+    const { projects = [], owner = DefaultOwner, users } = this;
+    const result: IWorkspace = {
+      kind: Kind,
+      key: this.key,
+      info: this.info.toJSON(),
+      projects,
+      owner,
+    };
+    if (Array.isArray(users) && users.length) {
+      result.users = users;
+    }
+    return result;
+  }
+}