@api-client/core 0.5.7 → 0.5.10

package/src/models/store/Breadcrumb.ts

@@ -0,0 +1,17 @@
+/**
+ * A schema describing a breadcrumb for a file.
+ */
+export interface IBreadcrumb {
+  /**
+   * The key of the parent item
+   */
+  key: string;
+  /**
+   * The parent's kind
+   */
+  kind: string;
+  /**
+   * The parent's name
+   */
+  displayName: string;
+}

package/src/models/store/Capabilities.ts

@@ -0,0 +1,77 @@
+/**
+ * Capabilities the current user has on this file.
+ * This is populated by the store each time the user requests 
+ * a file.
+ */
+export interface ICapabilities {
+  /**
+   * Whether the user can edit the current file.
+   * The permission to edit can be inherited from a containing space so not visible
+   * in the file's permissions.
+   */
+  canEdit: boolean;
+  /**
+   * Whether the user can comment on the current file.
+   * The permission to edit can be inherited from a containing space so not visible
+   * in the file's permissions.
+   */
+  canComment: boolean;
+  /**
+   * Whether the user can share the current file.
+   * The permission to edit can be inherited from a containing space so not visible
+   * in the file's permissions.
+   */
+  canShare: boolean;
+  /**
+   * Whether the user can make a copy of the file.
+   * 
+   * Note, this is reserved for future use an currently not supported by the store.
+   * 
+   * The permission to edit can be inherited from a containing space so not visible
+   * in the file's permissions.
+   */
+  canCopy?: boolean;
+  /**
+   * Whether the user can read revisions of the file.
+   * 
+   * Note, this is reserved for future use an currently not supported by the store.
+   * 
+   * The permission to edit can be inherited from a containing space so not visible
+   * in the file's permissions.
+   */
+  canReadRevisions?: boolean;
+  /**
+   * Whether the user can add children to the file.
+   * This can be `true` only for user spaces.
+   */
+  canAddChildren: boolean;
+  /**
+   * Whether the user can permanently delete the file.
+   * 
+   * The permission to edit can be inherited from a containing space so not visible
+   * in the file's permissions.
+   */
+  canDelete: boolean;
+  /**
+   * Only set for user spaces. Otherwise it is always `false`.
+   * Whether the user can list children of the user space.
+   */
+  canListChildren: boolean;
+  /**
+   * Whether the user can rename the file.
+   */
+  canRename: boolean;
+  /**
+   * Whether the user can move the file to trash.
+   */
+  canTrash: boolean;
+  /**
+   * Whether the user can move the file back from trash.
+   */
+  canUntrash: boolean;
+  /**
+   * Whether the user can read media for the file.
+   * This is always `false` for a user space which has no media.
+   */
+  canReadMedia: boolean;
+}

package/src/models/store/File.ts

@@ -1,9 +1,10 @@
-import { IPermission } from './Permission.js';
+import { IPermission, Permission, PermissionRole } from './Permission.js';
 import { IModification } from './Modification.js';
 import { IDeletion } from './Deletion.js';
 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';
 
 export const DefaultOwner = 'default';
 
@@ -56,6 +57,18 @@ export interface IStoredFile {
    * An arbitrary list of labels applied to the file.
    */
   labels?: string[];
+  /**
+   * This is populated when reading a file from the store.
+   * A list of actions the user can perform on the file.
+   * 
+   * This is a readonly field and it is ignored when creating / updating the file.
+   */
+  capabilities?: ICapabilities;
+  /**
+   * The color of the icon to render for this file in the file explorer.
+   * This should be a hex format, e.g.: #c00 for red.
+   */
+  iconColor?: string;
 }
 
 /**
@@ -75,6 +88,15 @@ export interface IFile extends IStoredFile {
   permissions: IPermission[];
 }
 
+const parentsSymbol = Symbol('parents');
+const deletedSymbol = Symbol('deleted');
+const deletedInfoSymbol = Symbol('deletedInfo');
+const ownerSymbol = Symbol('owner');
+const lastModifiedSymbol = Symbol('lastModified');
+const capabilitiesSymbol = Symbol('capabilities');
+const permissionsSymbol = Symbol('permissions');
+const permissionIdsSymbol = Symbol('permissionIds');
+
 export class StoredFile {
   /**
    * The kind of the File
@@ -88,6 +110,9 @@ export class StoredFile {
    * The name of the environment.
    */
   info: Thing = Thing.fromName('');
+  
+  [parentsSymbol]: string[] = [];
+  
   /**
    * 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).
@@ -95,39 +120,84 @@ export class StoredFile {
    * This property cannot be manipulated directly by the client. Should be treated as 
    * opaque value.
    */
-  parents: string[] = [];
+  get parents(): string[] {
+    return this[parentsSymbol];
+  }
+
+  [permissionIdsSymbol]: ReadonlyArray<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[] = [];
+  get permissionIds(): ReadonlyArray<string> {
+    return this[permissionIdsSymbol];
+  }
+
+  [deletedSymbol]?: boolean;
+
   /**
    * Whether the file object is deleted.
    */
-  deleted?: boolean;
+  get deleted(): boolean {
+    return this[deletedSymbol] || false;
+  }
+
+  [deletedInfoSymbol]?: Readonly<IDeletion>;
+
   /**
    * The information about the delete information.
    * Always set when the `delete` is true.
    */
-  deletedInfo?: IDeletion;
+  get deletedInfo(): Readonly<IDeletion> | undefined {
+    return this[deletedInfoSymbol];
+  }
+
+  [ownerSymbol]: string = DefaultOwner;
+
   /**
    * 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 = DefaultOwner;
+  get owner(): string {
+    return this[ownerSymbol];
+  }
+
+  [lastModifiedSymbol]: Readonly<IModification> = { user: '', time: 0, byMe: false };
+
   /**
    * The last modification made to this file.
    */
-  lastModified: IModification = { user: '', time: 0, byMe: false };
+  get lastModified(): Readonly<IModification> {
+    return this[lastModifiedSymbol];
+  }
+
   /**
    * An arbitrary list of labels applied to the file.
    */
   labels?: string[];
 
+  [capabilitiesSymbol]?: Readonly<ICapabilities>;
+
+  /**
+   * This is populated when reading a file from the store.
+   * A list of actions the user can perform on the file.
+   * 
+   * This is a readonly field and it is ignored when creating / updating the file.
+   */
+  get capabilities(): Readonly<ICapabilities> | undefined {
+    return this[capabilitiesSymbol];
+  }
+
+  /**
+   * The color of the icon to render for this file in the file explorer.
+   */
+  iconColor?: string;
+
   new(init: IStoredFile): void {
-    const { key = v4(), info, kind, parents=[], permissionIds=[], deleted, deletedInfo, owner = DefaultOwner, lastModified, labels } = init;
+    const { key = v4(), info, kind, parents=[], permissionIds=[], deleted, deletedInfo, owner = DefaultOwner, lastModified, labels, iconColor } = init;
     this.key = key;
     this.kind = kind;
     if (info) {
@@ -135,22 +205,27 @@ export class StoredFile {
     } else {
       this.info = Thing.fromName('');
     }
-    this.parents = parents;
-    this.permissionIds = permissionIds;
-    this.owner = owner;
-    this.lastModified = lastModified ? { ...lastModified } : { user: '', time: 0, byMe: false };
+    this[parentsSymbol] = [...parents];
+    this[permissionIdsSymbol] = [...permissionIds];
+    this[ownerSymbol] = owner;
+    this[lastModifiedSymbol] = lastModified ? Object.freeze({ ...lastModified }) : Object.freeze({ user: '', time: 0, byMe: false });
     if (typeof deleted === 'boolean') {
-      this.deleted = deleted;
-      this.deletedInfo = deletedInfo ? { ...deletedInfo } : undefined;
+      this[deletedSymbol] = deleted;
+      this[deletedInfoSymbol] = deletedInfo ? Object.freeze({ ...deletedInfo }) : undefined;
     } else {
-      this.deleted = undefined;
-      this.deletedInfo = undefined;
+      this[deletedSymbol] = undefined;
+      this[deletedInfoSymbol] = undefined;
     }
     if (Array.isArray(labels)) {
-      this.labels = labels;
+      this.labels = [...labels];
     } else {
       this.labels = undefined; 
     }
+    if (iconColor) {
+      this.iconColor = iconColor;
+    } else {
+      this.iconColor = undefined;
+    }
   }
 
   toJSON(): IStoredFile {
@@ -159,17 +234,20 @@ export class StoredFile {
       key: this.key,
       kind: this.kind,
       info: this.info.toJSON(),
-      parents: this.parents,
-      permissionIds: this.permissionIds,
-      lastModified: this.lastModified,
+      parents: [...this.parents],
+      permissionIds: [...this.permissionIds],
+      lastModified: { ...this.lastModified },
       owner,
     };
     if (this.deleted) {
       result.deleted = this.deleted;
-      result.deletedInfo = this.deletedInfo;
+      result.deletedInfo = { ...this.deletedInfo } as IDeletion;
     }
     if (Array.isArray(this.labels)) {
-      result.labels = this.labels;
+      result.labels = [...this.labels];
+    }
+    if (this.iconColor) {
+      result.iconColor = this.iconColor;
     }
     return result;
   }
@@ -187,7 +265,7 @@ export class StoredFile {
     if (user.kind !== UserKind) {
       throw new Error(`Invalid value for the user when setting "lastModified".`);
     }
-    this.lastModified = {
+    this[lastModifiedSymbol] = {
       byMe: false,
       time: Date.now(),
       user: user.key,
@@ -234,35 +312,106 @@ export class StoredFile {
     if (user.kind !== UserKind) {
       throw new Error(`Invalid value for the user when setting "lastModified".`);
     }
-    this.deleted = true;
-    this.deletedInfo = {
+    this[deletedSymbol] = true;
+    this[deletedInfoSymbol] = {
       byMe: false,
       time: Date.now(),
       user: user.key,
       name: user.name,
     };
   }
+
+  /**
+   * Creates the Capabilities object for a file giving user level.
+   * 
+   * @param file The file object to create the capabilities to. The object is not mutated.
+   * @param role The user role to the file.
+   */
+  static createFileCapabilities(file: IStoredFile | StoredFile, role?: PermissionRole): ICapabilities {
+    const isCommenter = Permission.hasRole('commenter', role);
+    const isOwner = Permission.hasRole('owner', role);
+    const isReader = Permission.hasRole('reader', role);
+    const isWriter = Permission.hasRole('writer', role);
+    const result: ICapabilities = {
+      canEdit: isWriter,
+      canComment: isCommenter,
+      // This is open to discussion. Technically sharing is writing to a file resource.
+      // However, should we allow to share the file by a user that has read access?
+      canShare: isWriter,
+      // not yet supported in the store
+      canCopy: false,
+      // not yet supported in the store. Currently the user can read revisions when they have read access to the file.
+      canReadRevisions: isReader,
+      canAddChildren: false,
+      // debatable, can writer permanently delete a file?
+      canDelete: isOwner,
+      canListChildren: false,
+      canRename: isWriter,
+      // debatable, can writer trash a file?
+      canTrash: isOwner,
+      canUntrash: isOwner,
+      canReadMedia: false,
+    };
+    // Do not use the `WorkspaceKind` reference here as it's circular and creates
+    // an error.
+    if (file.kind === 'Core#Space' && isWriter) {
+      result.canAddChildren = true;
+    }
+    if (file.kind === 'Core#Space') {
+      result.canListChildren = isReader;
+    }
+    if (file.kind !== 'Core#Space') {
+      result.canReadMedia = isReader;
+    }
+    return result;
+  }
+
+  createFileCapabilities(role: PermissionRole): ICapabilities {
+    return File.createFileCapabilities(this, role);
+  }
+
+  /**
+   * Mutates the file object by setting the `byMe` properties (on deleted and modified info)
+   * 
+   * Note, this can be done only on file schema (IFile). The `File` object has
+   * this properties frozen.
+   * 
+   * @param file The file to mutate
+   * @param user The user key to compare.
+   */
+  static updateByMeMeta(file: IFile, user: string): void {
+    if (file.deletedInfo) {
+      file.deletedInfo.byMe = file.deletedInfo.user === user;
+    }
+    if (file.lastModified) {
+      file.lastModified.byMe = file.lastModified.user === user;
+    }
+  }
 }
 
 export class File extends StoredFile {
+  [permissionsSymbol]: ReadonlyArray<IPermission> = [];
+
   /**
    * 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[] = [];
+  get permissions(): ReadonlyArray<IPermission> {
+    return this[permissionsSymbol];
+  }
   
   new(init: IFile): void {
     super.new(init);
     const { permissions=[] } = init;
-    this.permissions = permissions;
+    this[permissionsSymbol] = permissions.map(i => ({ ...i }));
   }
 
   toJSON(): IFile {
     const result: IFile = {
       ...super.toJSON(),
-      permissions: this.permissions,
+      permissions: [...this.permissions],
     };
     return result;
   }

package/src/models/store/Permission.ts

@@ -4,6 +4,7 @@ export const Kind = 'Core#Permission';
 
 export type PermissionType = 'user' | 'group' | 'anyone';
 export type PermissionRole = 'owner' | 'reader' | 'commenter' | 'writer';
+const orderedRoles: PermissionRole[] = ["reader", "commenter", "writer", "owner"];
 
 interface IBasePermission {
   /**
@@ -47,7 +48,6 @@ interface IBasePermission {
    * The store id of the user that added this permission.
    */
   addingUser: string;
-
   /**
    * Whether the permission object is deleted.
    */
@@ -65,7 +65,7 @@ interface IBasePermission {
 /**
  * A schema describing a permission to a store object.
  */
-export interface IPermission extends IBasePermission{
+export interface IPermission extends IBasePermission {
   kind: typeof Kind;
   /**
    * The data store key of the permission.
@@ -142,6 +142,7 @@ export class Permission {
    * 
    * @param role The user role to set.
    * @param user The user id that has the role.
+   * @param addingUser The key of the user that created this permission
    */
   static fromUserRole(role: PermissionRole, user: string, addingUser: string): Permission {
     const init: IPermission = {
@@ -160,6 +161,7 @@ export class Permission {
    * 
    * @param role The group role to set.
    * @param group The group id that has the role.
+   * @param addingUser The key of the user that created this permission
    */
   static fromGroupRole(role: PermissionRole, group: string, addingUser: string): Permission {
     const init: IPermission = {
@@ -177,7 +179,7 @@ export class Permission {
    * Creates a Permission object for a group.
    * 
    * @param role The group role to set.
-   * @param group The group id that has the role.
+   * @param addingUser The key of the user that created this permission
    */
   static fromAnyoneRole(role: PermissionRole, addingUser: string): Permission {
     const init: IPermission = {
@@ -268,6 +270,31 @@ export class Permission {
     return true;
   }
 
+  /**
+   * Checks whether the current user role meets the minimum required role.
+   * 
+   * @param minimumLevel The minimum requested role
+   * @param currentRole The user role. When not set it always returns false.
+   * @returns True if the `currentRole` is at least the `minimumRole`
+   */
+  static hasRole(minimumLevel: PermissionRole, currentRole?: PermissionRole): boolean {
+    if (!currentRole) {
+      return false;
+    }
+    const currentAccessIndex = orderedRoles.indexOf(currentRole);
+    const requestedAccessIndex = orderedRoles.indexOf(minimumLevel);
+    // the current must be at least at the index of requested.
+    return currentAccessIndex >= requestedAccessIndex;
+  }
+
+  /**
+   * Link to the `Permission.hasRole(minimumLevel, currentRole)`.
+   * @see {@link Permission.hasRole}
+   */
+  hasRole(minimumLevel: PermissionRole, currentRole: PermissionRole): boolean {
+    return Permission.hasRole(minimumLevel, currentRole);
+  }
+
   toJSON(): IPermission {
     const result: IPermission = {
       kind: Kind,

package/src/models/{RevisionInfo.ts → store/Revision.ts}

@@ -1,4 +1,4 @@
-import { IModification } from './store/Modification.js';
+import { IModification } from './Modification.js';
 
 export const Kind = 'Core#Revision';
 
@@ -6,7 +6,7 @@ export const Kind = 'Core#Revision';
  * The definition of a patch revision.
  * The revision is created with the `@api-client/json` library.
  */
-export interface IRevisionInfo {
+export interface IRevision {
   /**
    * The datastore key for this patch object.
    */

package/src/runtime/store/FilesSdk.ts

@@ -148,6 +148,44 @@ export class FilesSdk extends SdkBase {
     return data;
   }
 
+  /**
+   * Reads a number of files in a bulk operation.
+   * 
+   * @param keys The list of keys to read. When the user has no access to the file it returns undefined 
+   * in that place. It also inserts `undefined` in place of a file that doesn't exist.
+   * @param request Optional request options.
+   */
+  async readBulk(keys: string[], request: ISdkRequestOptions = {}): Promise<IListResponse<IFile|undefined>> {
+    const token = request.token || this.sdk.token;
+    const url = this.sdk.getUrl(RouteBuilder.filesBulk());
+    const body = JSON.stringify(keys);
+    const result = await this.sdk.http.post(url.toString(), { token, body });
+    this.inspectCommonStatusCodes(result.status, result.body);
+    const E_PREFIX = 'Unable to read files in bulk. ';
+    if (result.status !== 200) {
+      this.logInvalidResponse(result);
+      let e = this.createGenericSdkError(result.body)
+      if (!e) {
+        e = new SdkError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.status);
+        e.response = result.body;
+      }
+      throw e;
+    }
+    if (!result.body) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`);
+    }
+    let data: IListResponse<IFile | undefined>;
+    try {
+      data = JSON.parse(result.body);
+    } catch (e) {
+      throw new Error(`${E_PREFIX}${E_INVALID_JSON}.`);
+    }
+    if (!Array.isArray(data.data)) {
+      throw new Error(`${E_PREFIX}${E_RESPONSE_UNKNOWN}.`);
+    }
+    return data;
+  }
+
   /**
    * Patches file's meta in the store.
    * 

package/src/runtime/store/RouteBuilder.ts

@@ -9,6 +9,13 @@ export class RouteBuilder {
     return '/files';
   }
 
+  /**
+   * @returns The path to the /files/bulk route.
+   */
+  static filesBulk(): string {
+    return '/files/bulk';
+  }
+
   /**
    * @returns The path to the /files/[id] route.
    */

package/build/src/models/RevisionInfo.js

@@ -1,2 +0,0 @@
-export const Kind = 'Core#Revision';
-//# sourceMappingURL=RevisionInfo.js.map

package/build/src/models/RevisionInfo.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"RevisionInfo.js","sourceRoot":"","sources":["../../../src/models/RevisionInfo.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,IAAI,GAAG,eAAe,CAAC"}