@api-client/core 0.4.4 → 0.5.0

package/src/models/Workspace.ts

@@ -1,4 +1,4 @@
-import { AccessControlLevel } from "./User.js";
+import { IFile, File } from "./store/File.js";
 import { IThing, Thing, Kind as ThingKind } from './Thing.js';
 import v4 from '../lib/uuid.js';
 
@@ -9,7 +9,7 @@ export const Kind = 'Core#Space';
  * 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 {
+export interface IWorkspace extends IFile {
   kind: typeof Kind;
   /**
    * The space identifier.
@@ -19,27 +19,11 @@ export interface IWorkspace {
    * 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';
@@ -50,7 +34,7 @@ export const DefaultOwner = 'default';
  * 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 {
+export class Workspace extends File {
   kind = Kind;
   /**
    * The space identifier.
@@ -60,26 +44,11 @@ export class Workspace {
    * 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 API Client 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.
@@ -95,7 +64,9 @@ export class Workspace {
       kind: Kind,
       info: info.toJSON(),
       owner,
-      projects: [],
+      parents: [],
+      permissionIds: [],
+      permissions: [],
     });
     return definition;
   }
@@ -103,7 +74,8 @@ export class Workspace {
   /**
    * @param input The environment definition used to restore the state.
    */
-  constructor(input?: string | IWorkspace | IUserWorkspace) {
+  constructor(input?: string | IWorkspace) {
+    super();
     let init: IWorkspace;
     if (typeof input === 'string') {
       init = JSON.parse(input);
@@ -118,7 +90,9 @@ export class Workspace {
           name: '',
         },
         owner: DefaultOwner,
-        projects: [],
+        parents: [],
+        permissionIds: [],
+        permissions: [],
       };
     }
     this.new(init);
@@ -129,29 +103,20 @@ export class Workspace {
    * 
    * Note, this throws an error when the environment is not a space. 
    */
-  new(init: IWorkspace | IUserWorkspace): void {
+  new(init: IWorkspace): void {
     if (!Workspace.isWorkspace(init)) {
       throw new Error(`Not a space.`);
     }
-    const { key = v4(), projects = [], info, owner = DefaultOwner, users } = init;
+    super.new(init);
+    const { key = v4(), info, owner = DefaultOwner } = 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;
-    }
   }
 
   /**
@@ -166,17 +131,14 @@ export class Workspace {
   }
 
   toJSON(): IWorkspace {
-    const { projects = [], owner = DefaultOwner, users } = this;
+    const { owner = DefaultOwner } = this;
     const result: IWorkspace = {
       kind: Kind,
       key: this.key,
       info: this.info.toJSON(),
-      projects,
       owner,
+      ...super.toJSON(),
     };
-    if (Array.isArray(users) && users.length) {
-      result.users = [...users];
-    }
     return result;
   }
 }

package/src/models/store/File.ts

@@ -0,0 +1,135 @@
+import { IPermission } from './Permission.js';
+
+export interface IStoredFile {
+  /**
+   * The list of parents of the object. It is an ordered list of parents
+   * from the top (first element) to the lowest parent in the tree (last element).
+   * 
+   * After creating the object, this property cannot be manipulated directly by the client. 
+   * Should be treated as opaque value.
+   */
+  parents: string[];
+  /**
+   * The list of permissions to this file object.
+   * 
+   * This property cannot be manipulated directly by the client. Should be treated as 
+   * opaque value.
+   */
+  permissionIds: string[];
+  /**
+   * Whether the file object is deleted.
+   */
+  deleted?: boolean;
+  /**
+   * The timestamp of when the file was deleted.
+   */
+  deletedTime?: number;
+  /**
+   * The id of the user that has deleted the file.
+   */
+  deletingUser?: string;
+}
+
+/**
+ * An interface describing an object in the data store that
+ * describes a file or an object that can be treated as a file or a folder.
+ */
+export interface IFile extends IStoredFile {
+  /**
+   * Populated by the server when reading the file. The list of permissions to the object.
+   * 
+   * This property cannot be manipulated directly by the client. Should be treated as 
+   * opaque value.
+   * 
+   * Data store implementation note, this is not stored in the store but it is populated
+   * when reading the object.
+   */
+  permissions: IPermission[];
+}
+
+export class StoredFile {
+  /**
+   * The list of parents of the object. It is an ordered list of parents
+   * from the top (first element) to the lowest parent in the tree (last element).
+   * 
+   * This property cannot be manipulated directly by the client. Should be treated as 
+   * opaque value.
+   */
+  parents: string[] = [];
+  /**
+   * The list of permissions to this file object.
+   * 
+   * This property cannot be manipulated directly by the client. Should be treated as 
+   * opaque value.
+   */
+  permissionIds: string[] = [];
+  /**
+   * Whether the file object is deleted.
+   */
+  deleted?: boolean;
+  /**
+   * The timestamp of when the file was deleted.
+   */
+  deletedTime?: number;
+  /**
+   * The id of the user that has deleted the file.
+   */
+  deletingUser?: string;
+
+  new(init: IStoredFile): void {
+    const { parents=[], permissionIds=[], deleted, deletedTime, deletingUser } = init;
+    this.parents = parents;
+    this.permissionIds = permissionIds;
+    if (typeof deleted === 'boolean') {
+      this.deleted = deleted;
+      this.deletedTime = deletedTime;
+      this.deletingUser = deletingUser;
+    } else {
+      this.deleted = undefined;
+      this.deletedTime = undefined;
+      this.deletingUser = undefined;
+    }
+  }
+
+  toJSON(): IStoredFile {
+    const result: IStoredFile = {
+      parents: this.parents,
+      permissionIds: this.permissionIds,
+    };
+    if (typeof this.deleted === 'boolean') {
+      result.deleted = this.deleted;
+
+      if (this.deletedTime) {
+        result.deletedTime = this.deletedTime;
+      }
+      if (this.deletingUser) {
+        result.deletingUser = this.deletingUser;
+      }
+    }
+    return result;
+  }
+}
+
+export class File extends StoredFile {
+  /**
+   * Populated by the server when reading the file. The list of permissions to the object.
+   * 
+   * This property cannot be manipulated directly by the client. Should be treated as 
+   * opaque value.
+   */
+  permissions: IPermission[] = [];
+  
+  new(init: IFile): void {
+    super.new(init);
+    const { permissions=[] } = init;
+    this.permissions = permissions;
+  }
+
+  toJSON(): IFile {
+    const result: IFile = {
+      ...super.toJSON(),
+      permissions: this.permissions,
+    };
+    return result;
+  }
+}

package/src/models/store/Group.ts

@@ -0,0 +1,21 @@
+/**
+ * An object representing a user group.
+ */
+export interface IGroup {
+  /**
+   * The key of the group.
+   */
+  key: string;
+  /**
+   * The name of the group
+   */
+  name: string;
+  /**
+   * The id of the user that created this group.
+   */
+  owner: string;
+  /**
+   * The list of users in this group.
+   */
+  users: string[];
+}

package/src/models/store/Permission.ts

@@ -0,0 +1,318 @@
+import v4 from '../../lib/uuid.js';
+
+export const Kind = 'Core#Permission';
+
+export type PermissionType = 'user' | 'group' | 'anyone';
+export type PermissionRole = 'owner' | 'reader' | 'commenter' | 'writer';
+
+/**
+ * A schema describing a permission to a store object.
+ */
+export interface IPermission {
+  kind: typeof Kind;
+  /**
+   * The data store key of the permission.
+   * This property is generated by the store and is not writable.
+   */
+  key: string;
+  /**
+   * The type of the permission. 
+   * 
+   * - `user` can access the file by a specific user
+   * - `group` can access the file by a group of users
+   * - `anyone` the object can be searched by anyone who has access to the store.
+   * 
+   * Note, the `anyone` object does not mean that the end-user sees the file when 
+   * listing objects in the store. It means the file can be searched for.
+   */
+  type: PermissionType;
+  /**
+   * The id of the owner of the permission.
+   * The value depends on the `type`. For the `user` type it is the user id.
+   * The `group` means the group id. It is not set when the role is `anyone`.
+   */
+  owner?: string;
+  /**
+   * The role granted by this permission.
+   */
+  role: PermissionRole;
+  /**
+   * The "pretty" name to render with the permission.
+   * 
+   * - `user` type - user's full name
+   * - `group` type - the name of the group
+   * - `anyone` type - no render name
+   */
+  displayName?: string;
+  /**
+   * Optional expiration date of the permission. This is the timestamp when the permission expires.
+   * When creating / updating the permission the expiration date must:
+   * 
+   * - be used on a user or a group
+   * - the time must be in the future
+   */
+  expirationTime?: number;
+  /**
+   * The store id of the user that added this permission.
+   */
+  addingUser: string;
+
+  /**
+   * Whether the permission object is deleted.
+   */
+  deleted?: boolean;
+  /**
+   * The timestamp of when the permission was deleted.
+   */
+  deletedTime?: number;
+  /**
+   * The id of the user that has deleted the permission.
+   */
+  deletingUser?: string;
+}
+
+export class Permission {
+  kind = Kind;
+  /**
+   * The data store key of the permission.
+   * This property is generated by the store and is not writable.
+   */
+  key = '';
+  /**
+   * The type of the permission. 
+   * 
+   * - `user` can access the file by a specific user
+   * - `group` can access the file by a group of users
+   * - `anyone` the object can be searched by anyone who has access to the store.
+   * 
+   * Note, the `anyone` object does not mean that the end-user sees the file when 
+   * listing objects in the store. It means the file can be searched for.
+   */
+  type: PermissionType = 'user';
+  /**
+   * The id of the owner of the permission.
+   * The value depends on the `type`. For the `user` type it is the user id.
+   * The `group` means the group id. It is not set when the role is `anyone`.
+   */
+  owner?: string;
+  /**
+   * The role granted by this permission.
+   */
+  role: PermissionRole = 'reader';
+  /**
+   * The "pretty" name to render with the permission.
+   * 
+   * - `user` type - user's full name
+   * - `group` type - the name of the group
+   * - `anyone` type - no render name
+   */
+  displayName?: string;
+  /**
+   * Optional expiration date of the permission. This is the timestamp when the permission expires.
+   * When creating / updating the permission the expiration date must:
+   * 
+   * - be used on a user or a group
+   * - the time must be in the future
+   */
+  expirationTime?: number;
+
+  /**
+   * The store id of the user that added this permission.
+   */
+  addingUser: string = '';
+
+  /**
+   * Whether the file object is deleted.
+   */
+  deleted?: boolean;
+  /**
+   * The timestamp of when the file was deleted.
+   */
+  deletedTime?: number;
+  /**
+   * The id of the user that has deleted the file.
+   */
+  deletingUser?: string;
+
+  /**
+   * Creates a Permission object for a user.
+   * 
+   * @param role The user role to set.
+   * @param user The user id that has the role.
+   */
+  static fromUserRole(role: PermissionRole, user: string, addingUser: string): Permission {
+    const init: IPermission = {
+      key: v4(),
+      kind: Kind,
+      owner: user,
+      role,
+      type: 'user',
+      addingUser,
+    };
+    return new Permission(init);
+  }
+
+  /**
+   * Creates a Permission object for a group.
+   * 
+   * @param role The group role to set.
+   * @param group The group id that has the role.
+   */
+  static fromGroupRole(role: PermissionRole, group: string, addingUser: string): Permission {
+    const init: IPermission = {
+      key: v4(),
+      kind: Kind,
+      owner: group,
+      role,
+      type: 'group',
+      addingUser,
+    };
+    return new Permission(init);
+  }
+
+  /**
+   * Creates a Permission object for a group.
+   * 
+   * @param role The group role to set.
+   * @param group The group id that has the role.
+   */
+  static fromAnyoneRole(role: PermissionRole, addingUser: string): Permission {
+    const init: IPermission = {
+      key: v4(),
+      kind: Kind,
+      role,
+      type: 'anyone',
+      addingUser,
+    };
+    return new Permission(init);
+  }
+
+  constructor(input?: string | IPermission) {
+    let init: IPermission;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        key: v4(),
+        owner: '',
+        role: 'reader',
+        type: 'user',
+        addingUser: '',
+      };
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new environment clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the environment is not a space. 
+   */
+  new(init: IPermission): void {
+    if (!Permission.isPermission(init)) {
+      throw new Error(`Not a permission.`);
+    }
+    const { key = v4(), owner, role, type, displayName, expirationTime, addingUser, deleted, deletedTime, deletingUser } = init;
+    this.kind = Kind;
+    this.key = key;
+    this.owner = owner;
+    this.role = role;
+    this.type = type;
+    this.addingUser = addingUser;
+    if (displayName) {
+      this.displayName = displayName;
+    } else {
+      this.displayName = undefined;
+    }
+    if (typeof expirationTime === 'number') {
+      this.expirationTime = expirationTime;
+    } else {
+      this.expirationTime = undefined;
+    }
+    if (typeof deleted === 'boolean') {
+      this.deleted = deleted;
+      this.deletedTime = deletedTime;
+      this.deletingUser = deletingUser;
+    } else {
+      this.deleted = undefined;
+      this.deletedTime = undefined;
+      this.deletingUser = undefined;
+    }
+  }
+
+  /**
+   * Checks whether the input is a definition of an user space.
+   */
+  static isPermission(input: unknown): boolean {
+    const typed = input as IPermission;
+    if (!input || typed.kind !== Kind) {
+      return false;
+    }
+    return true;
+  }
+
+  toJSON(): IPermission {
+    const result: IPermission = {
+      kind: Kind,
+      key: this.key,
+      role: this.role,
+      type: this.type,
+      addingUser: this.addingUser,
+    };
+    if (this.owner) {
+      result.owner = this.owner;
+    }
+    if (this.displayName) {
+      result.displayName = this.displayName;
+    }
+    if (this.expirationTime) {
+      result.expirationTime = this.expirationTime;
+    }
+    if (typeof this.deleted === 'boolean') {
+      result.deleted = this.deleted;
+
+      if (this.deletedTime) {
+        result.deletedTime = this.deletedTime;
+      }
+      if (this.deletingUser) {
+        result.deletingUser = this.deletingUser;
+      }
+    }
+    return result;
+  }
+}
+
+/**
+ * This is used in the communication with the backend to add/change user's access to the resource.
+ */
+export interface IAccessOperation {
+  /**
+   * The user or group id. Not populated for `anyone` type.
+   */
+  id?: string;
+  /**
+   * The permission type
+   */
+  type: PermissionType;
+}
+
+export interface IAccessAddOperation extends IAccessOperation {
+  op: "add";
+  /**
+   * The level that the user or the group has access to.
+   */
+  value: PermissionRole;
+  /**
+   * The timestamp when the permission expires.
+   */
+  expirationTime?: number;
+}
+
+export interface IAccessRemoveOperation extends IAccessOperation {
+  op: "remove";
+}
+
+export type AccessOperation = IAccessAddOperation | IAccessRemoveOperation;

package/src/models/store/User.ts

@@ -0,0 +1,83 @@
+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 = 'Core#User';
+
+interface BaseUser {
+  kind: typeof Kind;
+  /**
+   * 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;
+  /**
+   * Whether the user is deleted from the system.
+   */
+  deleted?: boolean;
+  /**
+   * The timestamp of when the user was deleted.
+   */
+  deletedTime?: number;
+  /**
+   * The id of the user that deleted the user.
+   */
+  deletingUser?: string;
+}
+
+/**
+ * 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 extends BaseUser {
+  /**
+   * Optional metadata related to the auth provider.
+   */
+  provider?: unknown;
+}